Prerequisites and safe setup

A file can contain CRLF bytes on disk while Git has already staged an LF-normalized version. Inspect both representations before assuming a line-ending policy failed. This tutorial uses Git, Bash and Python 3 in a fresh scratch directory. The script creates demo-repo and stops if that directory already exists. It does not touch an existing repository, configure a global setting or create a commit.

The example creates a .gitattributes rule for text files and writes known CRLF bytes to notes.txt. It stages the files with command-scoped core.autocrlf and core.safecrlf values so those two preferences do not depend on the normal per-user configuration. Use an ordinary scratch environment without custom system-wide attribute rules for a reproducible demonstration.

Read the diagnostic fields

git ls-files --eol reports the staged representation with an i/ prefix and the working representation with a w/ prefix. The fixture expects i/lf and w/crlf, followed by the applicable text and eol attributes. Column spacing may vary by Git version, so the important values are the named fields rather than an exact count of spaces.

The Python check reads the working file as bytes and obtains the staged blob through git show :notes.txt. It asserts CRLF in the former and LF in the latter. This independent byte check prevents a successful command exit or plausible-looking listing from being mistaken for verification. There is no HEAD commit in the repository; the colon syntax reads the index.

Understand what staging changed

The attribute requests normalization for staged text content and LF when Git writes an appropriate checkout. Adding the current CRLF file does not itself rewrite that working file. Therefore the mixed diagnostic is expected at this point. The demonstration makes that distinction visible without forcibly checking out a file or overwriting local edits.

For an existing project, inspect git status and review the proposed attributes first. If you later choose to renormalize tracked content, review the resulting staged diff as a separate maintenance change. Avoid mixing unrelated code edits with a repository-wide line-ending conversion, since that makes both review and blame harder to interpret.

Troubleshooting and limits

If the output reports mixed line endings, inspect the actual bytes and applicable attributes instead of repeatedly toggling global autocrlf settings. Binary content should have a deliberate binary or -text policy rather than being forced through a text rule. Files without newline bytes can have a different diagnostic even when the attribute is present.

The script verifies one text fixture on Git 2.43.0. A normalization warning may be printed by another Git version and is not, by itself, a failed assertion. The tested behavior concerns staging, not every editor, checkout platform or repository configuration. Remove the disposable demo-repo only after you finish inspecting it; no cleanup of unrelated paths is part of this example.

Complete example

Save as eol.sh.

#!/usr/bin/env bash
set -euo pipefail
# Run in a fresh scratch directory; demo-repo must not already exist.
mkdir demo-repo
cd demo-repo
git init -q
printf '*.txt text eol=lf\n' > .gitattributes
printf 'alpha\r\nbeta\r\n' > notes.txt
git -c core.autocrlf=false -c core.safecrlf=false add .gitattributes notes.txt
git ls-files --eol -- notes.txt
python3 - <<'CHECK'
import pathlib, subprocess
work = pathlib.Path("notes.txt").read_bytes()
index = subprocess.check_output(["git", "show", ":notes.txt"], timeout=5)
assert work == b"alpha\r\nbeta\r\n"
assert index == b"alpha\nbeta\n"
print("checked: working tree CRLF; staged blob LF")
CHECK

Run and expected output

bash eol.sh
i/lf    w/crlf  attr/text eol=lf      	notes.txt
checked: working tree CRLF; staged blob LF

Primary references

Continue with Git tutorials.