Line Ending Troubleshooting: CRLF, LF, and Cross-Platform Issues
Diagnose and fix line ending problems that cause scripts to fail, diffs to show every line changed, and files to display incorrectly. Covers Git configuration, editor settings, and conversion tools.
Key Takeaways
- Windows uses CRLF (carriage return + line feed, `\r\n`), Unix/macOS uses LF (`\n`), and classic Mac OS used CR (`\r`).
- Git's `core.autocrlf` setting controls automatic conversion:
- Convert line endings with `dos2unix` / `unix2dos` on the command line, or use your editor's line ending selector.
The Line Ending Problem
Windows uses CRLF (carriage return + line feed, \r\n), Unix/macOS uses LF (\n), and classic Mac OS used CR (\r). When files are shared across platforms without normalization, scripts fail with mysterious errors, Git shows every line as changed, and editors display ^M characters.
Symptoms and Diagnosis
| Symptom | Likely Cause | Diagnosis Command |
|---|---|---|
^M visible in terminal |
CRLF file on Unix | cat -v file |
Script fails with \r error |
CRLF in shell script | file script.sh |
| Git diff shows all lines changed | Mixed line endings | git diff --check |
| Double-spaced display | LF file in Notepad (old) | Open in modern editor |
Git Configuration
Git's core.autocrlf setting controls automatic conversion:
true(Windows): Convert LF→CRLF on checkout, CRLF→LF on commitinput(macOS/Linux): Convert CRLF→LF on commit onlyfalse: No conversion (manual management)
A .gitattributes file provides per-file-type control and overrides individual user settings — always prefer this over relying on core.autocrlf.
.gitattributes Configuration
* text=auto
*.sh text eol=lf
*.bat text eol=crlf
*.png binary
Conversion
Convert line endings with dos2unix / unix2dos on the command line, or use your editor's line ending selector. For batch conversion, the Peasy line ending converter handles files entirely in your browser with preview before applying changes.