Git LF CRLF Warning — Fix Line Endings

You add a file, and Git prints: warning: LF will be replaced by CRLF the next time Git touches it. Or the reverse on a Mac: CRLF will be replaced by LF. The commit succeeds. The file looks fine. Yet the warning returns on every other file, diffs show whole files changed when you touched one line, and a shell script fails with $'\r': command not found.

The reflex is to ignore it because it's only a warning. That works until mixed endings poison a build: a .sh checked out with CRLF won't run on Linux, a .bat with LF confuses old Windows tools, and phantom diffs bury real code review changes under thousands of line-ending-only lines.

The cause is three layers disagreeing: your core.autocrlf setting, the repo's .gitattributes rules, and your editor's save behavior. Windows, macOS, and Linux each want a different checkout style, and without committed rules every clone negotiates endings on its own.

This guide shows what the warning actually did, which autocrlf value fits your OS, how .gitattributes locks the contract, how to renormalize once, and how mixed endings break diffs and builds. You'll silence the warning permanently with settings that travel with the repo.

Reading the Warning: What Git Actually Did

Git's line-ending warnings describe a conversion, not corruption. LF will be replaced by CRLF means the file is stored with LF in the repo but will check out with CRLF on your Windows disk. CRLF will be replaced by LF means the reverse: your working file has CRLF but Git will store LF. In both cases your data is intact — Git translated the invisible characters at line ends so the file matches your platform's convention.

The warning fires at predictable moments: on git add when the working file's endings differ from what the index will store, and on git checkout when the stored endings differ from what your disk will get. A warning that appears once per file is Git announcing its translation policy. The same warning on every commit is Git telling you the policy was never locked down, so it renegotiates per file.

Diagnose with two commands that show both sides. git ls-files --eol lists each file's index ending versus working-tree ending, so you can see at a glance which files are mixed. git diff piped through cat -A reveals ^M carriage-return markers on changed lines, proving CRLF is present where you expected LF.

Don't suppress the messenger. The warning is the cheapest signal you'll get that three layers — your config, the repo attributes, and your editor — disagree. Read one warning fully, fix the policy behind it, and the rest of the warnings disappear with it.

# Which files are mixed? index (i/) vs worktree (w/) endings
git ls-files --eol | head -30

# Show invisible carriage returns in the diff
git diff | cat -A | head -40

# Inspect one suspect file directly
file scripts/deploy.sh
grep -c $'\r' scripts/deploy.sh || echo "no CR found"
cat -A scripts/deploy.sh | head -5

core.autocrlf True, Input, False: Pick Per OS

core.autocrlf controls the default translation when no .gitattributes rule covers a file. true checks out CRLF and commits LF: the Windows default, where Notepad-era tools expect carriage returns on disk but the repo stays LF-clean. input converts CRLF to LF on commit but checks out verbatim: the macOS and Linux default, where disks already want LF and only inbound Windows endings need cleaning. false disables all translation: what you save is what you commit, byte for byte.

Pick by OS unless the repo already pins everything. Windows developers should use true so local tools see CRLF while the shared history stays LF. macOS and Linux developers should use input so stray CRLF from cross-platform edits gets normalized on commit. false fits only repos where .gitattributes covers every path and you want zero magic — bare servers, containers, and Linux-only teams with strict attributes.

Set it at the right scope and verify. git config --global core.autocrlf true sets your user default on Windows; --global core.autocrlf input does the macOS and Linux side. Repo-local config overrides global, so check git config --list --show-origin | grep autocrlf when behavior surprises you — a cloned repo template may have set its own value.

Remember this setting is personal, not shared. It never travels with git push, which is why .gitattributes must carry the team contract. Autocrlf handles your disk; attributes handle the repo.

# Windows: checkout CRLF, commit LF
git config --global core.autocrlf true

# macOS / Linux: normalize to LF on commit
git config --global core.autocrlf input

# Strict no-magic (only with full .gitattributes coverage)
# git config --global core.autocrlf false

# Verify effective value and where it came from
git config --list --show-origin | grep -i autocrlf
git config --show-origin core.autocrlf

.gitattributes Text and EOL: Rules That Travel

Unlike autocrlf, .gitattributes commits with the repo and applies identically on every clone. The text attribute enables normalization for a path; eol pins the checkout style. * text=auto tells Git to normalize line endings on commit for files it detects as text while leaving detected binaries alone. That's the safe baseline every repo should start from, because it makes the shared history LF without touching images or archives.

Pin the exceptions explicitly. .sh text eol=lf forces shell scripts to LF on every OS, which is non-negotiable for Linux execution. .bat and .ps1 often want eol=crlf for legacy Windows tooling. .png, .jpg, and .zip want -text or binary so Git never translates a byte. Language-agnostic wildcards beat enumerating every extension: pin by execution need, not by editor preference.

Order and specificity matter. Later lines override earlier ones, so put the * text=auto baseline first and specific pins after. Use git check-attr -a <path> to see the effective attributes for any file — it resolves the pattern stack and shows exactly which line won. When a file misbehaves, check-attr names the rule to fix instead of guessing.

Commit the file early and renormalize once. A three-line .gitattributes merged this week prevents three years of warning-by-warning negotiation across every contributor's machine.

# Minimal team baseline (.gitattributes)
# * text=auto
# *.sh text eol=lf
# *.bat text eol=crlf
# *.png binary
# *.zip binary

cat .gitattributes
git check-attr -a scripts/deploy.sh
git check-attr -a assets/logo.png
git ls-files --eol | head -20

Renormalize the Repo: Fix History Without Chaos

Adding .gitattributes doesn't rewrite files already in the index — it only governs future adds and checkouts. Renormalization applies the new rules to everything in one controlled pass. git add --renormalize . re-scans every tracked file, converts index endings per the fresh attributes, and stages exactly the files whose stored bytes must change. You review that set, commit once, and every future clone inherits clean endings.

Run it in sequence, not as a guess. Commit or stash all work first so the renormalize diff contains only ending changes. Commit the .gitattributes file itself. Then run git add --renormalize ., inspect with git status --short and git diff --stat, and commit with a message like Normalize line endings per .gitattributes. Push and have each teammate pull and re-checkout affected paths so stale working-tree endings don't get recommitted.

Expect a noisy-but-safe diff. Files that were stored CRLF flip to LF in the index; working-tree files may show as modified until re-checked out. That's the one-time cost. Announce the commit to the team, merge it during a quiet window, and ask open PRs to rebase after it lands so they don't resurrect old endings.

Never rewrite history for this. A single normalization commit at HEAD fixes the future without invalidating every SHA behind you. Filter-branch rewrites are slower, riskier, and unnecessary when the index converges going forward.

# Safe renormalize sequence
 git status --short  # commit or stash first
 git add .gitattributes
git commit -m "Add line-ending rules"

git add --renormalize .
git status --short
git diff --stat

git commit -m "Normalize line endings per .gitattributes"
git ls-files --eol | head -20

Mixed Endings Breaking Diffs and Builds

Mixed endings hurt in two places: human review and machine execution. A file that flips from LF to CRLF shows every line as changed in git diff, burying the one logic line under thousands of ending-only lines. Reviewers either wave it through blind or demand a cleanup that delays the feature. Execution breaks harder: bash reads the trailing \r as part of the shebang and command names, Python may tolerate it but shebang lines don't, and old Windows batch tools choke on bare LF.

Detect both failure modes with the same toolkit. git diff --stat flags whole-file rewrites from single-line edits — that shape screams endings. git diff | cat -A shows ^M on lines you never touched. For builds, file names the type (with CRLF line terminators is the smoking gun) and grep -c $'\r' counts the carriage returns. ls-files --eol maps the blast radius across the repo.

Fix the instance, then the class. Convert the broken file with the attribute plus renormalize flow, not with a manual editor save that may flip it back next week. Then pin its pattern in .gitattributes and add a CI gate: git grep -I --files-with-matches $'\r' -- '*.sh' fails the build when CRLF sneaks into scripts. Diffs get readable again because only real changes differ.

Treat phantom diffs as bugs, not noise. Every whole-file diff you excuse trains the team to skim, and skimmed reviews miss the logic error hiding under the endings.

# Spot ending-only whole-file diffs
git diff --stat
git diff -- scripts/deploy.sh | cat -A | head -20

# Prove CRLF in a failing script
file scripts/deploy.sh
grep -c $'\r' scripts/deploy.sh

# CI gate: fail on CRLF in shell scripts
git grep -I --files-with-matches $'\r' -- '*.sh' && echo "CRLF FOUND" || echo "scripts clean"

Editors and EditorConfig: Stop the Next Mix

Attributes normalize on commit, but editors decide what hits the disk between commits. An IDE set to CRLF on Windows will keep producing CRLF working files that look dirty against an LF index, re-raising warnings developer by developer. EditorConfig closes the loop: a committed .editorconfig with end_of_line = lf tells every compliant editor to save LF, and it travels with the repo just like .gitattributes.

Set both layers to agree. Keep .gitattributes as the enforcer ( text=auto, .sh eol=lf) and .editorconfig as the producer (end_of_line = lf, insert_final_newline = true, charset = utf-8). Configure the big three editors once: VS Code with files.eol set to , IntelliJ with Line separator set to Unix, and Vim with fileformat=unix. Document the trio in onboarding so new hires converge on day one.

Verify the loop holds. After saving, git diff should show only your logic lines, git ls-files --eol should show w/lf for your files, and git status should stay quiet on untouched files. If warnings return for one developer, check their editor setting before touching shared config — the repo is likely right and their save style is wrong.

Prevention beats renormalization. One EditorConfig commit plus a pre-commit hook that rejects CRLF in scripts costs minutes and ends the class of incident this guide opened with.