Git: 'LF will be replaced by CRLF' Warning Explained

LF will be replaced by CRLF is a warning, not an error. This warning alone does not mean the operation failed; check the exit status and any other errors. Git is telling you that a file uses Unix line endings (LF) in the repository but your core.autocrlf setting will write Windows line endings (CRLF) into your working copy when it next checks the file out. The clean fix is to set the same line-ending policy for everyone with a .gitattributes file.

Here is the full message you are likely staring at, with the filename being whatever Git is about to write:

warning: in the working copy of '.gitignore', LF will be replaced by CRLF the next time Git touches it

The general form is warning: in the working copy of '<file>', LF will be replaced by CRLF the next time Git touches it, so the same line shows up for any file (README.md, a .sh script, a source file). It almost always appears on Windows, during git add or git commit, and it can repeat once per affected file.

Diagnose LF-to-CRLF and CRLF-to-LF warnings

The reverse message, CRLF will be replaced by LF, describes conversion in the other direction. Check the exact file and the setting that applies before changing a global configuration:

git config --show-origin --get core.autocrlf
git config --show-origin --get core.safecrlf
git check-attr text eol -- README.md
git ls-files --eol -- README.md

Replace README.md with the affected tracked file. git ls-files --eol reports the index (i/), working tree (w/), and attributes. An unset config query can return no value; that does not itself indicate a broken repository. The Git attributes reference explains how text and eol determine conversion.

What LF and CRLF actually mean

A line ending is the invisible character (or characters) that mark the end of a line in a text file. There are two common conventions:

• LF (line feed, \n, hex 0A): one character. The Unix, Linux, and macOS standard. Git's own internal storage prefers this.
• CRLF (carriage return + line feed, \r\n, hex 0D0A): two characters. The Windows standard, inherited from old teleprinters.

The same text file can be byte-for-byte different depending on which convention it uses, even though it looks identical in your editor. That byte difference is the entire source of this warning. When you write code on Windows and your editor saves CRLF, but the repository stores LF, Git has to translate between the two, and it tells you so.

Why this is a warning and not an error

Git is not refusing to do anything. It is doing the conversion you asked it to do (through core.autocrlf) and announcing it. The file gets committed, the repository stays LF, and your working copy stays CRLF. Everything works.

The reason the warning exists at all is that line-ending churn is a real pain on teams: if half the team commits LF and half commits CRLF, you get diffs where every single line looks changed, merge conflicts on whitespace, and broken git blame. The warning is Git nudging you to set a deliberate policy before that mess starts. Line endings are a team concern, not a personal preference, in the same way a clean team Git workflow settles the rest of the shared conventions.

What core.autocrlf is doing

core.autocrlf is the per-machine setting that controls automatic line-ending conversion. It has three values:

On Windows the common advice is true: you edit with CRLF locally, Git stores LF in the repo. That is exactly the configuration producing your warning, but it is not the only valid policy. A repository may deliberately use LF working files on Windows too. Check what you have:

git config --get core.autocrlf

Set it (the --global flag applies it to your user account, not just this repo):

# Windows
git config --global core.autocrlf true

# macOS / Linux
git config --global core.autocrlf input

core.autocrlf is a personal machine setting, though. It does not travel with the repository, so it cannot guarantee that a teammate has the same value. That is the gap .gitattributes closes.

Make the warning go away with .gitattributes

A .gitattributes file lives in the repo, gets committed, and applies to everyone who clones it, regardless of their core.autocrlf. This is the actual fix for a team. Edit or create .gitattributes at the repository root. Preserve existing rules; do not overwrite the file with a one-line shell redirect.

* text=auto asks Git to detect text and normalize it to LF in the index. It does not force LF in every working copy or guarantee that this warning disappears. If you want to be explicit about a few cases:

# Normalize all text files to LF in the repo
* text=auto

# Force LF in the working copy for files that must stay LF
*.sh text eol=lf
*.bash text eol=lf

# Force CRLF in the working copy for Windows-only scripts
*.bat text eol=crlf
*.cmd text eol=crlf

# Treat these as binary, never touch line endings
*.png binary
*.jpg binary
*.pdf binary

eol=lf and eol=crlf override what lands in the working copy for matching files, which matters for shell scripts (a .sh file with CRLF often fails to run) and Windows batch files.

Start from a clean working tree or preserve unrelated work first. Stage the attributes file, renormalize tracked files, and inspect the staged changes before committing:

git status --short
git add .gitattributes
git add --renormalize .
git diff --cached --stat
git diff --cached
git commit -m "Add .gitattributes to normalize line endings"

That commit touches the whole repo, so spell out the why in the message: it is the kind of housekeeping change where a clear note pays off later, the same habit that helps you write commits your teammates can read. The renormalize pass may stage files that look unchanged in your editor. That is expected, it is rewriting the stored line endings to match the policy. After committing, verify that the index and working-copy endings match the intended policy. A text=auto rule alone can still permit checkout conversion. If you want to keep mixed line endings from creeping back in, you can automate the policy with a pre-commit hook that flags offending files before they land. This is a sensible thing to set up early, much like the .gitignore file every project should have.

Should I just silence the warning?

You can turn the message off, but I would not lead with that. The warning is harmless, and on a solo repo where you genuinely do not care, suppressing it is fine:

git config --global core.safecrlf false

core.safecrlf controls whether Git warns (or errors) about irreversible line-ending conversions. Setting it to false quiets the warning everywhere. The catch: you have hidden the symptom, not set a policy. The moment a second person clones the repo on a different OS, the line-ending churn is back and now nobody is being warned about it. Prefer the .gitattributes route. Silence the warning only when you have already decided the line endings are correct and you are tired of seeing the note.

reset vs renormalize: a quick clarification

A common reflex when files look "changed" after fixing line endings is to throw the changes away. Do not reach for that here. The renormalize is the work; discarding it leaves you exactly where you started. If you do find yourself wanting to back out a bad attempt, the right tools are covered in discarding local changes in Git, not a blanket reset of the renormalized files.

FAQ

Related reading

If you are still finding your feet with Git, start at my Git for beginners guide and work outward. Line endings sit right alongside other early setup decisions: what to keep out of the repo with a .gitignore file, how the staging area works when you run git add, and how to set Git up cleanly on a new project. When line-ending churn does cause a tangle, knowing how to resolve merge conflicts is the next skill to have.