Comprehensive guide to Git line ending configuration for cross-platform development teams. Use when configuring line endings, setting up .gitattributes, troubleshooting line ending issues, understanding core.autocrlf/core.eol/core.safecrlf, working with Git LFS, normalizing line endings in repositories, or resolving cross-platform line ending conflicts. Covers Windows, macOS, Linux, and WSL. Includes decision trees, workflows, best practices, and real-world scenarios.
Limited to specific tools
Additional assets for this skill
This skill is limited to using the following tools:
references/best-practices.mdreferences/commands-reference.mdreferences/configuration-approaches.mdreferences/configuration-mechanics.mdreferences/decision-tree.mdreferences/evaluations.mdreferences/git-lfs.mdreferences/gitattributes-guide.mdreferences/platform-specific.mdreferences/real-world-examples.mdreferences/troubleshooting.mdreferences/workflows-scenarios.mdComprehensive guide to Git line ending configuration for cross-platform development teams.
Last Verified: 2025-11-25 Last Audited: 2025-11-25 (Comprehensive Type A audit - 79/80 score, content validated via MCP servers against official Git documentation)
Line endings are invisible characters that mark the end of a line in text files:
\n - Used by Unix, Linux, macOS (1 byte)\r\n - Used by Windows (2 bytes)\r - Legacy Mac OS 9 and earlier (rarely seen today)The Problem:
# Windows developer creates file with CRLF
echo "#!/bin/bash" > script.sh
# Linux developer pulls and tries to run it
./script.sh
# Error: /bin/bash^M: bad interpreter: No such file or directory
Common Issues:
Git provides three mechanisms:
core.autocrlf, core.eol, core.safecrlf) - Automatic conversions.gitattributes file - Explicit per-file or per-pattern rules (highest priority)git add --renormalize) - One-time fixesGit's Design Philosophy:
Platform-specific configs with automatic normalization:
# Windows
git config --global core.autocrlf true
git config --global core.safecrlf warn
# Mac/Linux
git config --global core.autocrlf input
git config --global core.safecrlf warn
Pros:
When to use: You work in repos you don't control (open source, client, vendor repos)
Same config everywhere, relies on .gitattributes:
# All platforms
git config --global core.autocrlf false
git config --global core.eol native
git config --global core.safecrlf warn
Pros:
Cons:
When to use: You control ALL repositories and can ensure comprehensive .gitattributes
Use Option 1 if you work in mixed environments (internal + external repos). See Configuration Approaches for detailed comparison.
For comprehensive decision tree covering all scenarios (repository control, platform selection, file types, troubleshooting), see Decision Tree.
Quick decision:
autocrlf=true, macOS/Linux: autocrlf=input.gitattributes is a repository-level file that explicitly declares how Git should handle specific files.
Minimal .gitattributes:
# Auto-detect text files and normalize to LF in repository
* text=auto
Comprehensive .gitattributes:
# Default: auto-detect and normalize
* text=auto
# Documentation - LF everywhere
*.md text eol=lf
*.txt text eol=lf
# Shell scripts - MUST be LF (Unix requirement)
*.sh text eol=lf
*.bash text eol=lf
# PowerShell scripts - CRLF (Windows standard)
*.ps1 text eol=crlf
*.cmd text eol=crlf
*.bat text eol=crlf
# Configuration files - LF (cross-platform)
*.json text eol=lf
*.yml text eol=lf
.gitignore text eol=lf
.gitattributes text eol=lf
# Binary files - never convert
*.png binary
*.jpg binary
*.pdf binary
*.zip binary
*.exe binary
Why Use .gitattributes:
See .gitattributes Guide for comprehensive patterns and attribute reference.
# Check current config (should be default from Git for Windows)
git config --global --get core.autocrlf
# Expected: true
# If not set, configure explicitly
git config --global core.autocrlf true
git config --global core.safecrlf warn
Behavior:
See Platform-Specific Configuration for detailed setup guides for Windows, macOS, Linux, and WSL.
^M: bad interpreter)Error:
$ ./script.sh
bash: ./script.sh: /bin/bash^M: bad interpreter: No such file or directory
Root Cause: Shell script has CRLF line endings. Unix shells require LF.
Immediate Fix:
# Convert CRLF to LF
dos2unix script.sh
# Or with sed
sed -i 's/\r$//' script.sh
# Make executable
chmod +x script.sh
Permanent Fix (Add to .gitattributes):
# Shell scripts MUST have LF
*.sh text eol=lf
*.bash text eol=lf
# Normalize the script
git add --renormalize script.sh
git commit -m "Fix line endings in shell scripts"
Root Cause: Line endings changed (CRLF ↔ LF).
Fix:
# Check current line endings
git ls-files --eol file.txt
# Normalize to repository standard
git add --renormalize file.txt
git commit -m "Normalize line endings for file.txt"
See Troubleshooting for comprehensive issue resolution.
Quick reference for essential commands:
# View configuration
git config --list --show-origin | grep -E "autocrlf|eol|safecrlf"
# Check file attributes
git check-attr -a README.md
# Check line ending status
git ls-files --eol README.md
# Normalize files
git add --renormalize .
# Test line ending behavior
git ls-files --eol | grep "w/crlf" | grep "eol=lf" # Find mismatches
See Commands Reference for complete command listing.
Always use .gitattributes in repos you control
Document platform-specific configs in onboarding
autocrlf=trueautocrlf=inputSet core.safecrlf=warn for safety
Test with git ls-files --eol
Normalize when adding .gitattributes
git add --renormalize .See Best Practices for detailed guidance.
Git LFS stores large binary files separately from the main repository to prevent bloat. This is separate from line ending configuration but works alongside it.
See Git LFS Guide for comprehensive installation, configuration, when to use, GitHub limits, and migration strategies.
Configuration and Setup:
Implementation:
Troubleshooting and Support:
Testing:
For comprehensive test scenarios, multi-model testing notes, and formal evaluations, see Evaluations.
Evaluation Summary: 4/4 evaluations passed (100%) - Tested with Claude Sonnet 4 and Claude Opus 4.5
Date: 2025-11-28 Model: claude-opus-4-5-20251101