Line endings

The invisible character at the end of every line of a text file: what it is, how to see it, and when it matters.

The short version

A text file is a long string of bytes. The line breaks you see are one or two of those bytes, placed where a line stops. There are two kinds in use today. LF is one byte, and macOS, Linux and the web use it. CRLF is two bytes, and Windows traditionally uses it. Your editor draws either as the end of a line, so you never see them.

LFCRLFCR
NameLine feedCarriage return + line feedCarriage return
Written as\n\r\n\r
Bytes0a0d 0a0d
Used bymacOS, Linux, the web, nearly all toolsWindows, traditionallyMac OS before OS X
TodayThe defaultStill seen from WindowsObsolete

The same two lines, three ways

Each file below holds the text "Hello" and "World" on two lines. Under each is the text with its line endings written out, and the bytes the file is really made of. Click through the files and compare the last bytes on each line.

textlf.txt
Two lines, each ended by one LF.
This is what macOS and Linux write, and what most tools expect.

text    H  e  l  l  o LF  W  o  r  l  d LF
bytes  48 65 6c 6c 6f 0a 57 6f 72 6c 64 0a

The bytes are in hexadecimal. 48 is H, 0a is LF and 0d is CR.

Why there are two

The names come from typewriters and teleprinters. Two separate things had to happen to start a new line: the carriage returned to the left (CR), and the paper rolled up one line (LF). Early systems sent both. Later systems chose differently:

  • Unix, and so Linux and macOS, kept only LF. One byte is enough to mean "new line".
  • DOS and Windows kept both, as CRLF. Their file formats and tools grew up around it.
  • The old Mac OS used a lone CR. It stopped when macOS became Unix underneath.

Today the split barely matters. Browsers, editors, compilers and formatters accept either. It only shows up where a tool is strict.

Looking at the real bytes

These commands show a file's line endings. The examples are two real files from this site: an SVG that came with Windows endings, and a stylesheet with the usual Mac ones.

textcat-ve.txt
$ cat -ve public/tool-logos/lua.svg | head -1
<?xml version="1.0" encoding="utf-8"?>^M$

$ cat -ve src/components/site/footer.module.css | head -3
@reference "../../app/globals.css";$
$
/* full-width band under the page shell */$

cat -ve prints $ where every line ends, and ^M for a CR.
A CRLF file shows ^M$ at the end of its lines. An LF file shows only $.

Changing it, and keeping it that way

You can switch a file's ending in the editor. To keep a whole project consistent, tell Git and your editor what you want, so a file pasted in from another machine can't bring a different ending along.

text.gitattributes
# Git writes every text file with LF, whatever the machine that checked it out
* text=auto eol=lf

When it goes wrong

Most of the time nothing happens. These are the cases where something does.

textscript-fails.txt
deploy.sh, saved with CRLF:

  #!/bin/bash^M
  echo "deploying"^M

$ ./deploy.sh
-bash: ./deploy.sh: /bin/bash^M: bad interpreter: No such file or directory

The shell reads the first line as the program "/bin/bash" followed by a CR,
and there is no program with that name.
  • Shell scripts are the one place CRLF fails loudly on a Mac or Linux machine.
  • Git diffs get noisy when two people's machines disagree. A .gitattributes file fixes it for everyone.
  • The final newline is a convention: every line, including the last, ends with a line ending. Tools like Git and wc count lines by their endings, so a file without one can read as one line short.

What's in this project

I checked every file Git tracks. Everything is LF, apart from two SVG logos that came from somewhere else.

What I foundCount
Files with LF endings352
Files with no line breaks at all (so no ending)33
Files that aren't text (images and so on)7
Files with CRLF endings2
Text files with no final newline3

There's no .gitattributes or .editorconfig. Everything works because everything is LF, not because anything makes it so.