Blog
3 min read

"LF Will Be Replaced by CRLF": What the Git Warning Means and How to Fix It

Windows ends lines with CRLF, macOS and Linux with LF, and Git warns when it converts between them. What the warning means, whether it's a problem, the right core.autocrlf setting for your OS, and the .gitattributes file that fixes line endings for the whole team.

On Windows, git add sometimes prints:

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

It's a warning, not an error. Nothing is broken. But it's worth understanding, because line endings cause genuinely confusing problems in mixed Windows/Mac/Linux teams.

What LF and CRLF are

Text files mark the end of each line with invisible characters:

  • LF (line feed, \n) — used by macOS and Linux.
  • CRLF (carriage return + line feed, \r\n) — used by Windows.

Both look identical in an editor. Git notices the difference.

What the warning means

Git has a setting, core.autocrlf, that converts line endings automatically. On Windows it's often set to true, which means:

  • files are stored in the repository with LF,
  • files are checked out on your machine with CRLF.

The warning tells you a file currently has LF in your working folder, and Git will turn it into CRLF next time it writes the file. That's the setting doing its job.

When line endings actually cause problems

  • Every line shows as changed in a diff, though you only edited one. Someone's editor converted the whole file. (How to read a diff)
  • Shell scripts break on Linux: /bin/bash^M: bad interpreter or $'\r': command not found. A script with CRLF endings was copied to a Linux server or Docker container. (Bash scripting for beginners)
  • Docker builds fail with odd errors from an entrypoint script. (exec format error)
  • Linters complain about CRLF vs LF (Prettier and ESLint default to LF).

The best fix: a .gitattributes file

Instead of relying on everyone's personal Git settings, put the rule in the repository. Create .gitattributes at the root:

# Normalise all text files to LF in the repository
* text=auto eol=lf

# Windows-only scripts keep CRLF
*.bat text eol=crlf
*.cmd text eol=crlf
*.ps1 text eol=crlf

# Binary files: never touch
*.png binary
*.jpg binary
*.pdf binary

This forces LF everywhere except Windows batch files, regardless of anyone's core.autocrlf. Modern editors on Windows (including VS Code) handle LF files fine.

Then re-normalise the existing files once:

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

The personal setting

If you can't add a .gitattributes, set core.autocrlf to match your OS:

# Windows
git config --global core.autocrlf true

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

input converts CRLF to LF when committing but never adds CRLF on checkout.

Many developers on Windows now prefer false combined with a .gitattributes and an editor set to LF — fewer surprises.

Editor settings

In VS Code, the bottom-right of the status bar shows LF or CRLF for the current file; click to switch. Set the default in settings:

"files.eol": "\n"

An .editorconfig file with end_of_line = lf does the same across editors. (VS Code for beginners)

Avoiding it entirely

Working inside WSL on Windows means a Linux environment with LF line endings throughout, and Linux tooling behaves exactly as it will in production. (What is WSL?)

The summary

  • The warning is harmless — Git is converting line endings as configured.
  • Problems appear with shell scripts, Docker and noisy diffs.
  • Commit a .gitattributes with * text=auto eol=lf and run git add --renormalize ..
  • Or develop in WSL or a Linux environment.

EasySpawn gives you a Linux development environment in the cloud — LF line endings, the same OS as production, no Windows conversion surprises. See how it works or join the waitlist.

Related: What Is WSL? · Claude Code on Windows · What Is .gitignore? · Git and GitHub for Beginners

Keep reading