Fix CRLF line ending problems with .gitattributes
Short answer: If a deploy script fails with "bad interpreter" or $'\r': command not found, or every line of a file shows as changed in a pull request, mixed line endings are the cause. Windows editors often save lines ending in CRLF; Linux servers and most tools expect LF. Add a .gitattributes file with * text=auto and explicit rules such as *.sh text eol=lf, then run git add --renormalize . once and commit. The repository itself then decides line endings, instead of each developer's settings.
What's going on
Text files mark the end of each line with invisible characters. Windows traditionally uses two (carriage return plus line feed, CRLF); macOS and Linux use one (line feed, LF). Most editors can handle both, so nobody notices until something strict reads the file:
- Shell scripts with CRLF fail on Linux, because the shell sees the carriage return as part of the command or interpreter path.
- Config files for servers, containers and CI may be misread or rejected.
- Diffs in pull requests show entire files as changed when someone's editor converts line endings on save.
- Merge conflicts appear on lines nobody actually edited.
- Checksums and tests comparing file contents fail between machines.
Mixed teams, a Windows-using contractor alongside developers on Macs, with deploys to Linux, hit this regularly.
Why per-developer settings aren't enough
Git has a setting, core.autocrlf, that converts line endings on checkout and commit. GitHub's documentation explains the usual choices: input on macOS and Linux, true on Windows. The trouble is that it depends on every person configuring their machine correctly, including new hires, contractors and CI runners. One misconfigured machine is enough to commit CRLF files.
A .gitattributes file in the repository is better because it travels with the code. GitHub's same guide recommends it for that reason: settings in the repository override individual configurations and apply to everyone.
Writing a .gitattributes file
Create .gitattributes in the repository root. A sensible starting point:
* text=autolets Git detect text files and normalise their line endings in the repository.*.sh text eol=lfforces LF for shell scripts on every checkout, including on Windows.*.bat text eol=crlfand*.cmd text eol=crlfkeep Windows batch files in CRLF, which they expect.*.png binary,*.jpg binary,*.pdf binaryand similar mark files that must never be converted.
Git's documentation explains how text=auto behaves: Git decides by itself whether each file is text or binary, and for text files not already stored with CRLF, converts line endings on check-in and checkout. Setting eol for a pattern implies text. Where neither attribute nor configuration says otherwise, the default checkout ending is CRLF on Windows and LF elsewhere, which is exactly why scripts need an explicit eol=lf.
Add other files that must stay LF, such as Dockerfiles, YAML pipeline definitions and environment templates, if they're edited on Windows.
Normalising files already in the repository
Adding the file doesn't rewrite existing content. Git's documentation and GitHub's guide both give the same steps:
- Commit the new
.gitattributes. - Run
git add --renormalize . - Run
git statusto see which files changed. - Commit with a clear message such as "Normalise line endings".
That commit touches many files, so do it when few branches are open, and add its hash to a .git-blame-ignore-revs file so blame history stays useful. Developers should then refresh their working copies; deleting and re-checking out files, or re-cloning, removes stale CRLF copies.
Editor settings help too
An .editorconfig file with end_of_line = lf tells most editors which ending to use for new files, so problems are rarer in the first place. It complements .gitattributes rather than replacing it.
Quick fixes for a broken server deploy
If a script is failing on a server right now:
- Check with
file deploy.sh; it reports "with CRLF line terminators" if that's the issue. - Convert it with a tool such as
dos2unix, or with your editor's line-ending setting, and redeploy. - Then fix the repository with
.gitattributes, or it will happen again on the next commit from a Windows machine.
Stop it coming back
Add a cheap check to CI so a CRLF file never reaches the main branch unnoticed. A short script can list tracked files that Git sees with CRLF in the repository using git ls-files --eol, which prints the line-ending state of each file in the index and working tree, and fail the build if any text file shows CRLF where you expect LF. Run the same command locally when you first add .gitattributes, to see how many files are affected before you normalise them. Mention the rule in your contributing notes, so contractors know why the check might fail.
Which files to watch most closely
Some files cause trouble with CRLF far more often than others. Shell scripts and anything with a #! first line are the classic case. Container build files, cron definitions, server configuration snippets and CI pipeline files are close behind, because the tools reading them run on Linux. Files consumed only by Windows tools, such as PowerShell scripts, are usually fine either way. List the risky types explicitly in .gitattributes with eol=lf, even if text=auto would probably handle them.
A worked example
Picture a hypothetical Saskatoon equipment-hire company whose website deploy started failing after a new contractor joined. The deploy log showed the shell interpreter not found, with a stray \r at the end of the path. The contractor's Windows editor had saved the deploy script with CRLF. The lead developer added a .gitattributes with * text=auto and eol=lf for scripts and pipeline files, ran git add --renormalize ., committed, and asked everyone to refresh their checkouts. Deploys worked again, and pull requests stopped showing whole-file changes.
FAQ
Should I set core.autocrlf as well?
It doesn't hurt, but .gitattributes in the repository takes precedence and works for everyone.
Will renormalising change my files' content?
Only their line endings. The visible text stays the same.
What about files that need CRLF?
Mark them with eol=crlf in .gitattributes.
Can binary files be damaged?
They can if Git wrongly treats them as text. Mark binary types explicitly to be safe.
If line-ending problems keep breaking your deploys or reviews, tell us about your team's setup and we'll help sort it out.