Git

Git Line Ending Warning "LF Will Be Replaced by CRLF," Fixing .gitattributes

The "LF will be replaced by CRLF" warning means Git's automatic line-ending conversion (core.autocrlf) is active and converting a file's line endings during checkout — it's usually harmless, but becomes a real source of friction across a team when different developers have different local settings, causing files to appear to change on every commit for no real reason.

The Problem

Committing files, especially on Windows, produces a warning:

warning: LF will be replaced by CRLF in src/utils.js.
The file will have its original line endings in your working directory

Individually this warning is often harmless, but when different team members have different core.autocrlf settings, the same files can appear to have unexpected line-ending-only changes in diffs, or actual functional issues in files (like shell scripts) that are sensitive to which line ending style they use.

Why It Happens

Git's core.autocrlf setting controls automatic conversion between LF (Unix-style, used internally in Git's own storage) and CRLF (Windows-style) line endings during checkout and commit. This setting is configured per-user, per-machine — meaning different developers on the same project, especially across different operating systems, can have different settings, leading to inconsistent behavior:

  • A Windows developer with core.autocrlf=true gets CRLF endings in their working directory, converted back to LF when committing
  • A macOS/Linux developer typically has core.autocrlf=input or unset entirely, keeping LF endings throughout
  • Without a project-level, explicit configuration, this per-user setting is left to individual preference or default, producing inconsistent results across a team and sometimes genuine bugs in line-ending-sensitive files (like shell scripts that fail with CRLF endings, as covered in a related common issue)

The Fix

The reliable, team-wide fix is a .gitattributes file committed to the repository itself, which defines line-ending behavior explicitly per file type, overriding any individual developer's personal core.autocrlf setting for files in this repository specifically:

# .gitattributes
* text=auto

*.js text eol=lf
*.ts text eol=lf
*.json text eol=lf
*.md text eol=lf
*.sh text eol=lf

*.png binary
*.jpg binary
*.ico binary

The first line, * text=auto, tells Git to automatically detect text files and normalize their line endings to LF in the repository itself, while still allowing appropriate conversion in each developer's working directory based on their own OS conventions if desired. The specific overrides below it (eol=lf for particular file types) force those specific files to always use LF, both in the repository and in every developer's working directory, regardless of their personal core.autocrlf setting — this is particularly important for files like shell scripts, where CRLF endings cause genuine functional breakage on Linux, not just a cosmetic diff annoyance.

The binary declarations for image and other non-text file types explicitly tell Git never to attempt any line-ending conversion on them at all, since applying text-based line-ending logic to binary files would corrupt them.

After adding or updating .gitattributes, existing files already checked out may still have the old, inconsistent line endings until they're explicitly renormalized:

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

This effectively re-applies the new .gitattributes rules to every already-tracked file, producing a one-time commit that fixes any files with inconsistent existing line endings, after which future commits should remain consistent without needing this step repeated.

For your own personal, general-purpose Git configuration across all repositories (as a sensible default for repos without their own .gitattributes), configure core.autocrlf appropriately for your OS, though understand this is a personal fallback, not a substitute for an explicit .gitattributes file in shared team repositories:

# Windows
git config --global core.autocrlf true

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

Still Not Working?

If you've added .gitattributes and renormalized, but the warning still appears for specific files, check whether those files were already committed with genuinely mixed line endings within the same file (some lines LF, others CRLF) before the .gitattributes fix — this can happen after merges between contributors with different original settings, and might require a more targeted, manual cleanup of the specific affected file's line endings (using a tool like dos2unix to normalize it explicitly) beyond what an automatic renormalize alone fully resolves in every edge case.

You might also like