What is the difference between eol=lf and text in a .gitattributes file?

Question

According to the documentation on .gitattributes, text enables end-of-line normalization:

text

Setting the text attribute on a path enables end-of-line normalization and marks the path as a text file. End-of-line conversion takes place without guessing the content type.

According to the same documentation, eol=lf will also normalize linebreaks:

eol

This attribute sets a specific line-ending style to be used in the working directory. It enables end-of-line normalization without any content checks, effectively setting the text attribute.

The fact that the examples given mix them in the same file seems to imply that there is some (perhaps subtle) difference between them:

*.txt       text
*.vcproj    eol=crlf
*.sh        eol=lf
*.jpg       -text

Also, there seems to nowhere be an unambiguous statement that they are the same, or that text is shorthand for eol=lf—though that appears to be the case. The closest thing I could find to such a statement is what I quoted above, where it says "effectively setting the text attribute". But the word effectively seems to back-pedal just slightly, as though it's not actually setting the text attribute, but just more-or-less setting it, or having almost the same effect.

What, precisely, is the difference between these two? (Or is text just shorthand for the common use case?) Is there any reason you would mix the two in one .gitattributes file?

OR: does text require that Git guess which kind of linebreak you need, while eol (obviously) specifies?

Answer 1

eol tells Git which line endings to use in your working directory and also enables LF normalization for those files in the repository. This setting applies to a particular path, so I'll use *.txt in my examples:

• *.txt eol=crlf tells Git to (1) normalize line endings to LF on checkin and (2) convert them to CRLF when the file is checked out.
• *.txt eol=lf tells Git to (1) normalize line endings to LF on checkin and (2) prevent conversion to CRLF when the file is checked out.

Notice that both settings normalize line endings to LF on checkin! This effectively sets the text attribute because text does the same thing.

---

Since these settings only apply to changes going forward, additional steps would be needed to update files that are already checked in.

And one more thing... Be careful to set eol only on paths matching text files. It enables normalization without any content checks, but binary files should not be normalized. Depending on your paths, you might need to explicitly exclude certain file types:

# Disable eol normalization for these types:
*.png -text
*.jpg -text
*.ttf -text