Understand and fix Git LF-to-CRLF warnings

An “LF will be replaced by CRLF” warning means Git's line-ending rules expect to convert that text when updating the working tree. The warning does not by itself mean the commit failed. Decide which endings the project requires, then put that policy in .gitattributes so every contributor uses the same file-specific rules.

Define a repository policy

For LF by default, with CRLF for Windows batch files:

# Normalize detected text and use LF in the working tree.
* text=auto eol=lf

# Keep batch files compatible with Windows tools.
*.bat text eol=crlf

# Shell scripts need LF for common Unix tooling.
*.sh text eol=lf

# Do not apply text conversion to PNG files.
*.png binary

Comments belong on separate lines. .gitattributes does not treat a trailing # explanation like a shell comment; it can be parsed as additional attributes.

For normalized text, Git stores LF in the index. The eol attribute controls working-tree endings: eol=lf selects LF and eol=crlf selects CRLF. Binary files must not undergo text normalization.

Understand local autocrlf settings

When a path has no overriding attributes, common personal defaults are:

# Windows: normalize on add, use CRLF on checkout.
git config --global core.autocrlf true

# macOS/Linux: normalize CRLF on add without CRLF checkout conversion.
git config --global core.autocrlf input

Choose the setting for your own environment; these commands are alternatives. Explicit file attributes take precedence for the paths they govern. You do not need to change everyone's global configuration to enforce a repository's eol policy.

Normalize existing tracked files

Start with a clean working tree or save unrelated work first. Then add the policy and renormalize:

git add .gitattributes
git add --renormalize .
git diff --cached --stat
git diff --cached
git commit -m "Normalize text line endings"

Review the staged changes before committing. Renormalization can touch many files and runs configured clean filters, so do it as a deliberate change. Existing working-tree bytes are not necessarily rewritten immediately.

Inspect a file's index and working-tree endings with:

git ls-files --eol -- scripts/build.sh

FAQ

Can I ignore the warning?

If the policy is intentional and the application accepts those working-tree endings, the conversion can be harmless. Check scripts and tools that require a particular format rather than assuming every working-tree representation is interchangeable.

Why does a shell script fail with a carriage-return error?

It may contain CRLF. Set *.sh text eol=lf, normalize the tracked content, and convert the working copy to LF in your editor. To rewrite a clean, saved file through Git's checkout conversion, remove only that file and restore it from the normalized index; never delete unsaved work just to silence the warning.

Can the editor help?

Yes. VS Code exposes the current line-ending style in the status bar. A committed .editorconfig with end_of_line = lf can align editor saves with your Git policy; add exceptions for files that require CRLF.

See gitattributes, git-config, and git-add.