How to fix fatal: LF would be replaced by CRLF in file.txt. Set core.safecrlf to false in Git

Before making changes, check your current Git configuration for line endings:

# Check global settings
git config --global core.autocrlf
git config --global core.safecrlf

# Check local (repository) settings
git config core.autocrlf
git config core.safecrlf

# See all relevant config at once
git config --list | grep -E "(autocrlf|safecrlf|eol)"

Typical Windows default values:
- core.autocrlf = true - Auto-convert line endings
- core.safecrlf = true or warn - Safety check enabled

Understanding the values:
| Setting | autocrlf value | Behavior |
|---------|---------------|----------|
| Windows default | true | Convert LF to CRLF on checkout, CRLF to LF on commit |
| Linux/macOS default | input | Convert CRLF to LF on commit, no conversion on checkout |
| No conversion | false | Never convert line endings |

| Setting | safecrlf value | Behavior |
|---------|---------------|----------|
| Strict | true | Error if conversion would change file |
| Warning | warn | Warn but allow the operation |
| Disabled | false | No safety check |

If you need to proceed immediately and understand the implications, you can disable the safety check:

Temporary (for one command):

git -c core.safecrlf=false add file.txt
git -c core.safecrlf=false add .

Disable globally:

git config --global core.safecrlf false

Disable for this repository only:

git config core.safecrlf false

When is this safe?
- When you're working with text files only
- When you understand that line endings will be normalized
- When your team has agreed on line ending handling

When to be cautious:
- If you have binary files that might contain CRLF sequences
- If you're unsure whether files should be treated as text or binary

The root cause is often the interaction between autocrlf and safecrlf. Configure autocrlf based on your platform and needs:

For Windows users (recommended):

# Convert to CRLF on checkout, to LF on commit
git config --global core.autocrlf true
git config --global core.safecrlf warn

For Linux/macOS users:

# Convert CRLF to LF on commit, no conversion on checkout
git config --global core.autocrlf input
git config --global core.safecrlf warn

For cross-platform projects (recommended approach):

# Disable autocrlf globally and use .gitattributes instead
git config --global core.autocrlf false
git config --global core.safecrlf false

Then use a .gitattributes file (see next step) for explicit control.

To completely disable line ending conversion:

git config --global core.autocrlf false

This keeps files exactly as they are, but requires your team to be consistent about line endings.

The best practice for cross-platform projects is to use a .gitattributes file at the repository root. This ensures consistent behavior regardless of individual developer's global settings.

Create a .gitattributes file:

# Recommended .gitattributes for most projects
* text=auto

# Explicitly declare text files
*.txt text
*.md text
*.json text
*.xml text
*.yaml text
*.yml text
*.html text
*.css text
*.js text
*.ts text
*.py text
*.rb text
*.java text
*.c text
*.cpp text
*.h text
*.sh text eol=lf
*.bash text eol=lf

# Windows-specific files
*.bat text eol=crlf
*.cmd text eol=crlf
*.ps1 text eol=crlf

# Binary files (never convert)
*.png binary
*.jpg binary
*.jpeg binary
*.gif binary
*.ico binary
*.pdf binary
*.zip binary
*.tar binary
*.gz binary
*.exe binary
*.dll binary
*.so binary
*.dylib binary

Key directives:
- text=auto: Let Git detect text files and normalize line endings
- text: Force file to be treated as text
- binary: Force file to be treated as binary (no conversion)
- eol=lf: Force LF line endings (for shell scripts)
- eol=crlf: Force CRLF line endings (for Windows batch files)

After adding .gitattributes, normalize existing files:

# Add the .gitattributes file first
git add .gitattributes
git commit -m "Add .gitattributes for line ending normalization"

# Renormalize all files
git add --renormalize .
git status
git commit -m "Normalize line endings"

Sometimes the error occurs because a file has inconsistent line endings. Here's how to fix it:

Check a file's current line endings:

# Using file command (Unix/macOS/Git Bash)
file filename.txt

# Using cat with visible line endings
cat -A filename.txt | head -5
# ^M at end = CRLF, $ at end = LF

# Using xxd to see hex values
xxd filename.txt | head -10
# 0d 0a = CRLF, 0a = LF

Convert a file's line endings:

Using dos2unix/unix2dos (if installed):

# Convert to Unix (LF)
dos2unix filename.txt

# Convert to Windows (CRLF)
unix2dos filename.txt

Using sed (Unix/macOS/Git Bash):

# Convert CRLF to LF
sed -i 's/\r$//' filename.txt

# On macOS, use:
sed -i '' 's/\r$//' filename.txt

Using PowerShell (Windows):

# Convert to LF
(Get-Content filename.txt -Raw) -replace "\r\n", "\n" | Set-Content -NoNewline filename-lf.txt

# Convert to CRLF
(Get-Content filename.txt -Raw) -replace "(?<!\r)\n", "\r\n" | Set-Content -NoNewline filename-crlf.txt

Using VS Code:
1. Open the file
2. Click on "CRLF" or "LF" in the bottom status bar
3. Select the desired line ending format
4. Save the file

After changing Git's line ending configuration, you may need to reset and re-add files for the changes to take effect:

For a single file:

# Remove from index (keeps working copy)
git rm --cached filename.txt

# Re-add with new settings
git add filename.txt

For all files in the repository:

# Save any uncommitted changes
git stash

# Remove all files from the index
git rm -r --cached .

# Re-add all files with new line ending settings
git add .

# Check what changed
git status
git diff --cached

# Commit if there are changes
git commit -m "Normalize line endings"

# Restore stashed changes
git stash pop

Using renormalize (Git 2.16+):

# More elegant approach - renormalize without removing from index
git add --renormalize .
git status
git commit -m "Normalize line endings"

Warning: These commands may show many files as modified if line endings are being normalized. This is expected behavior.

Sometimes Git misidentifies binary files as text and tries to convert their line endings, which can corrupt them. Here's how to fix it:

Symptoms:
- Binary files appear modified after checkout
- Image or executable files don't work after clone
- The safecrlf error appears for files you know are binary

Solution 1: Mark files as binary in .gitattributes:

# Add to .gitattributes
*.dat binary
*.bin binary
myfile.special binary

Solution 2: Reset a corrupted binary file:

# Discard local changes and get fresh copy
git checkout HEAD -- filename.bin

# Or from a specific commit
git checkout abc123 -- filename.bin

Solution 3: Check if Git thinks a file is text or binary:

# This shows how Git classifies the file
git check-attr -a filename

# Or specifically for diff/merge attributes
git check-attr diff filename
git check-attr merge filename

Prevention: Always declare binary file types in .gitattributes at the start of a project.