This Git error occurs when Git's core.autocrlf or core.safecrlf settings prevent automatic line ending conversion. The safecrlf setting blocks changes that would irreversibly convert CRLF (Windows) line endings to LF (Unix), protecting your files from unintended modifications.
This error occurs when Git detects that adding or committing a file would cause line ending changes that cannot be undone. Specifically, the file contains CRLF (Carriage Return + Line Feed, used by Windows) line endings, but Git is configured to convert them to LF (Line Feed only, used by Unix/Linux/macOS). The "fatal" designation indicates that Git's `core.safecrlf` setting is enabled and set to `true`, which causes Git to abort operations that would result in irreversible line ending conversions. This is a safety mechanism designed to prevent accidental corruption of binary files or files that genuinely need Windows-style line endings. Line endings differ between operating systems: - **Windows**: Uses CRLF (\r\n) - two characters - **Unix/Linux/macOS**: Uses LF (\n) - one character - **Legacy macOS (pre-OS X)**: Used CR (\r) - one character When Git is set to normalize line endings (via `core.autocrlf`), it can convert between these formats. However, if a file has mixed line endings or is a binary file incorrectly detected as text, this conversion can cause problems. The safecrlf option exists to catch these cases before they cause issues.
First, check your current Git settings for line ending handling:
# Check core.autocrlf setting
git config --get core.autocrlf
# Check core.safecrlf setting
git config --get core.safecrlf
# Check all line-ending related settings
git config --list | grep -E "(crlf|eol)"Common values for core.autocrlf:
- true: Convert LF to CRLF on checkout, CRLF to LF on commit (Windows default)
- input: Convert CRLF to LF on commit only, no conversion on checkout (recommended for Unix)
- false: No automatic conversion
Values for core.safecrlf:
- true: Abort if irreversible conversion would occur (causes this error)
- warn: Warn but allow the conversion
- false: No warnings or errors (default)
If you're confident the conversion is safe (the file is a text file that should have consistent line endings), disable the safecrlf check:
# Disable safecrlf for current repository
git config core.safecrlf false
# Or set to warn instead of abort
git config core.safecrlf warn
# Now try adding the file again
git add file.txtTo set globally (affects all repositories):
git config --global core.safecrlf falseTemporary override for a single command:
git -c core.safecrlf=false add file.txtAfter completing your commit, you may want to re-enable safecrlf for future protection:
git config core.safecrlf trueInstead of changing Git settings, you can convert the file's line endings to match what Git expects:
On Linux/macOS:
# Convert CRLF to LF using sed
sed -i 's/\r$//' file.txt
# Or using dos2unix (install if needed)
dos2unix file.txt
# Convert multiple files
find . -name "*.txt" -exec dos2unix {} \;On Windows (using Git Bash):
# dos2unix is available in Git Bash
dos2unix file.txt
# Or use Perl
perl -pi -e 's/\r\n/\n/g' file.txtOn Windows (using PowerShell):
# Read content and write with Unix line endings
(Get-Content file.txt -Raw) -replace "\r\n", "\n" | Set-Content file.txt -NoNewlineUsing VS Code:
1. Open the file
2. Click on "CRLF" in the bottom right status bar
3. Select "LF"
4. Save the file
The recommended solution for cross-platform projects is to use a .gitattributes file to explicitly control line ending handling:
# Create or edit .gitattributes in your repository rootBasic .gitattributes for most projects:
# Set default behavior to automatically normalize line endings
* text=auto
# Explicitly declare text files to normalize
*.txt text
*.md text
*.js text
*.ts text
*.json text
*.css text
*.html text
*.xml text
*.yml text
*.yaml text
# Declare files that should always have LF endings, even on Windows
*.sh text eol=lf
*.bash text eol=lf
Makefile text eol=lf
# Declare files that should always have CRLF endings, even on Unix
*.bat text eol=crlf
*.cmd text eol=crlf
*.ps1 text eol=crlf
# Denote binary files that should not be modified
*.png binary
*.jpg binary
*.gif binary
*.ico binary
*.pdf binary
*.zip binary
*.exe binary
*.dll binaryAfter creating .gitattributes:
git add .gitattributes
git commit -m "Add .gitattributes for line ending normalization"If you've added .gitattributes but existing files still have wrong line endings, re-normalize them:
# First, commit or stash any uncommitted changes
git stash
# Remove everything from the index
git rm --cached -r .
# Re-add all files (they will be normalized according to .gitattributes)
git reset --hard
# Alternatively, refresh the index
git add --renormalize .
# Check what changed
git status
git diff
# Commit the normalized files
git commit -m "Normalize line endings"Note: The --renormalize flag (Git 2.16+) is the cleanest way to renormalize:
git add --renormalize .
git status
git commit -m "Normalize all line endings"This process modifies the files in your working tree, so all team members should commit their work before you push this change.
If a binary file is incorrectly being treated as text, mark it explicitly in .gitattributes:
# Mark specific files as binary
path/to/file.dat binary
*.dat binary
*.bin binary
# Or mark them as not having text conversion
path/to/file.dat -textCheck if a file is being treated as binary or text:
# Check how Git sees the file
git check-attr -a filename
# Example output for text file:
# filename: text: auto
# filename: diff: set
# Example output for binary file:
# filename: binary: set
# filename: diff: unsetCommon binary file types to exclude from normalization:
- Image files: *.png, *.jpg, *.gif, *.svg, *.ico
- Compiled files: *.exe, *.dll, *.so, *.dylib
- Archives: *.zip, *.tar, *.gz, *.7z
- Fonts: *.ttf, *.woff, *.woff2, *.eot
- Documents: *.pdf, *.doc, *.docx
Set up core.autocrlf based on your operating system and project requirements:
For Windows users (recommended):
# Convert LF to CRLF on checkout, CRLF to LF on commit
git config --global core.autocrlf trueFor Linux/macOS users (recommended):
# Only convert CRLF to LF on commit (in case of Windows files)
git config --global core.autocrlf inputFor projects with strict requirements:
# No automatic conversion - rely entirely on .gitattributes
git config --global core.autocrlf falseCross-platform team recommendation:
1. Set core.autocrlf=false for all team members
2. Use .gitattributes to explicitly define line endings
3. This ensures consistent behavior regardless of individual Git configurations
# Apply to all team members
git config --global core.autocrlf false### Understanding Line Ending Conversion Flow
When Git processes files, conversion happens at two points:
1. Checkout (working directory <-- repository): smudge filter / CRLF conversion
2. Commit (working directory --> repository): clean filter / LF normalization
The safecrlf error specifically occurs during the commit phase when:
- The file has CRLF endings
- Git would convert them to LF
- But converting back (on checkout) wouldn't restore the original CRLF
### Why "Irreversible" Matters
The conversion is considered irreversible when:
1. Mixed line endings exist in the file
2. The file is binary but detected as text
3. round-trip conversion would change the file
Example of irreversible conversion:
Original: line1\r\n line2\n line3\r\n (mixed endings)
Commit: line1\n line2\n line3\n (normalized to LF)
Checkout: line1\r\n line2\r\n line3\r\n (all become CRLF)The original mixed state is lost.
### .gitattributes Takes Precedence
The priority order for line ending configuration:
1. .gitattributes in the repository (highest priority)
2. .git/info/attributes (local, not shared)
3. core.autocrlf and core.eol config (lowest priority)
Always prefer .gitattributes for project-wide settings.
### Special Cases
Preserving mixed line endings:
# In .gitattributes - disable normalization for specific files
file-with-mixed-endings.txt -textForcing specific line endings regardless of platform:
# Always use LF (Unix style)
*.sh text eol=lf
# Always use CRLF (Windows style)
*.bat text eol=crlf### Debugging Line Ending Issues
# See actual line endings in a file
cat -A file.txt | head
# LF shows as $, CRLF shows as ^M$
# Or with hexdump
hexdump -C file.txt | head
# 0a = LF, 0d 0a = CRLF
# Check what Git would store
git ls-files -s file.txt
git hash-object file.txt
# Compare with what's in the index
git diff --cached file.txt### CI/CD Considerations
In CI/CD pipelines, line ending issues often appear because:
1. Repository was committed from Windows
2. CI runs on Linux
3. Scripts fail due to CRLF in shell scripts
Prevention in CI:
# In GitHub Actions or similar
- name: Configure Git
run: git config --global core.autocrlf false
- name: Fix line endings for scripts
run: |
git ls-files -z '*.sh' | xargs -0 dos2unix### Git LFS and Line Endings
Git LFS-tracked files bypass the normal text/CRLF conversion:
# In .gitattributes
*.psd filter=lfs diff=lfs merge=lfs -textThe -text attribute prevents any line ending conversion for LFS files.
### Editor Configuration
Prevent line ending issues at the source with editor settings:
VS Code (.vscode/settings.json):
{
"files.eol": "\n"
}EditorConfig (.editorconfig):
[*]
end_of_line = lf
[*.{bat,cmd}]
end_of_line = crlfwarning: BOM detected in file, this may cause issues
UTF-8 Byte Order Mark (BOM) detected in file
fatal: Server does not support --shallow-exclude
Server does not support --shallow-exclude
warning: filtering out blobs larger than limit
Git partial clone filtering large blobs warning
fatal: Server does not support --shallow-since
Server does not support --shallow-since in Git
kex_exchange_identification: Connection closed by remote host
Connection closed by remote host when connecting to Git server