# Git Settings for Devs

This guide defines the minimum Git configuration every developer must use on this project to avoid line‑ending issues, noisy diffs, and broken scripts.

### Core rules

- The repository stores only LF (\n) line endings for all text files.
- Windows developers may work with CRLF (\r\n) locally, but must not commit CRLF back to the repo.
- The .gitattributes file in the repo is the single source of truth for line‑ending behavior.

***

### Global Git configuration

All developers must set a sane global Git configuration before contributing.

#### macOS / Linux

Run these commands once:

git config --global core.autocrlf input
git config --global core.safecrlf warn
git config --global pull.rebase true
git config --global rebase.autoStash true

Explanation:

- core.autocrlf=input
- On commit: converts CRLF → LF so the repo stays clean.
- On checkout: does not convert LF → CRLF, matching Unix tooling.

- core.safecrlf=warn
- Warns if you try to commit mixed or invalid line endings.

- pull.rebase=true and rebase.autoStash=true
- Encourages linear history and automatically stashes local changes before a rebase.

#### Windows

Windows developers must run:

git config --global core.autocrlf true
git config --global core.safecrlf warn

Explanation:

- On checkout: LF in the repo becomes CRLF in your working tree so editors and tools behave normally on Windows.
- On commit: CRLF is converted back to LF so the repository stays consistent for everyone.

***

### Required .gitattributes

Every repository in this organization must include a .gitattributes file at the root. This file overrides local Git settings for tracked paths and guarantees consistent line endings.

Recommended baseline:

# Default — treat files as text and normalize to LF in the repo
* text=auto eol=lf

# Shell scripts
*.sh text eol=lf

# Python
*.py text eol=lf

# JavaScript / TypeScript
*.js  text eol=lf
*.ts  text eol=lf
*.jsx text eol=lf
*.tsx text eol=lf

# JSON, YAML, Markdown
*.json text eol=lf
*.yml  text eol=lf
*.yaml text eol=lf
*.md   text eol=lf

# Windows batch files (explicitly CRLF)
*.bat text eol=crlf

# Binary files (never modified)
*.png  binary
*.jpg  binary
*.jpeg binary
*.gif  binary
*.ico  binary
*.pdf  binary
*.zip  binary

Teams can extend this with stack‑specific patterns (e.g., Dockerfiles, .env, .cs, .go, etc.) as long as they preserve “LF in repo” as the default.

***

### Adding .gitattributes to an existing repo

When introducing .gitattributes to a repository that already has files, you must normalize once so Git rewrites tracked files according to the new rules.

1) Add or update .gitattributes in the repo root.
2) Normalize line endings:

git add --renormalize .
git commit -m "Normalize line endings"

This commit should only change line endings, not file content.

***

## Developer checklist (copy/paste for onboarding)

Every new developer checklist:

- [ ] Run the required global Git configuration for their platform (see “Global Git configuration”).
- [ ] Confirm the repo contains a .gitattributes file and do not remove or override it.
- [ ] If .gitattributes was just added, pull the normalization commit before starting new work.
- [ ] Avoid committing files with mixed or incorrect line endings; treat safecrlf warnings as errors.