Line Ending Normalization with text=auto

What text=auto Does

The * text=auto directive is the single most important line in any .gitattributes file. It tells Git to auto-detect whether each file is text or binary. For text files, Git normalizes line endings to LF (\n) when storing them in the repository's object database.

How It Works

* text=auto

When Git adds a text file to the index (staging area), it converts all line endings to LF. When checking out files, Git converts LF to the platform's native line ending:

• Windows: LF → CRLF (\r\n)
• macOS / Linux: LF stays as LF (\n)

This two-way conversion ensures that:

1. The repository always stores files with consistent LF endings
2. Each developer sees native line endings in their working directory
3. Diffs are clean and don't show spurious line ending changes

Why It Matters

Without text=auto, a Windows developer committing a file with CRLF endings and a macOS developer editing the same file with LF endings will generate diffs that show every line as changed. This makes code review nearly impossible and pollutes the commit history.

The Full Normalization Flow

Stage	Windows	macOS/Linux
Working directory	CRLF	LF
git add (to index)	Converts to LF	Already LF
Repository (objects)	LF	LF
git checkout	Converts to CRLF	Stays LF

Applying to Existing Repositories

If you add * text=auto to an existing repository, you should re-normalize all files once:

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

This re-stages all tracked files using the new attributes, ensuring consistent endings going forward.