Why is git warning of CRLF on a file flagged as binary?

Question

I've got a file which has been flagged as binary:

$ cat .gitattributes
dist/* binary
$ git check-attr -a ./dist/app.js
./dist/app.js: binary: set
./dist/app.js: diff: unset
./dist/app.js: merge: unset
./dist/app.js: text: auto

And git diff correctly treats the file as binary:

$ git diff
diff --git a/dist/app.js b/dist/app.js
index 9c05798..fbcedd4 100644
Binary files a/dist/app.js and b/dist/app.js differ

But when I run git status, I get a warning about CRLF conversions:

$ git status
warning: CRLF will be replaced by LF in dist/app.js.
The file will have its original line endings in your working directory.
On branch master
Your branch is up-to-date with 'origin/master'.
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

        modified:   dist/app.js

What's going on? Why is git warning me about CRLFs in this file?

Answer 1

Git 2.10 (Q3 2016) should be more careful about crlf in binary.

See commit 6523728 (28 Jun 2016) by Torsten Bögershausen (tboegi).
^{(Merged by Junio C Hamano -- gitster -- in commit 21bed62, 25 Jul 2016)}

convert: unify the "auto" handling of CRLF

Before this change,

$ echo "* text=auto" >.gitattributes
$ echo "* eol=crlf" >>.gitattributes

would have the same effect as

$ echo "* text" >.gitattributes
$ git config core.eol crlf

Since the 'eol' attribute had higher priority than 'text=auto', this may corrupt binary files and is not what most users expect to happen.

Make the 'eol' attribute to obey 'text=auto' and now

$ echo "* text=auto" >.gitattributes
$ echo "* eol=crlf" >>.gitattributes

behaves the same as

$ echo "* text=auto" >.gitattributes
$ git config core.eol crlf

---

Git 2.13 (Q2 2017) makes sure the normalization uses the right commands
See commit 8599974 (12 Apr 2017) by Torsten Bögershausen (tboegi).
^{(Merged by Junio C Hamano -- gitster -- in commit 848d9a9, 24 Apr 2017)}

To trigger a re-normalization:

From a clean working directory:

$ echo "* text=auto" >.gitattributes
$ rm .git/index     # Remove the index to re-scan the working directory
$ git add .
$ git status        # Show files that will be normalized
$ git commit -m "Introduce end-of-line normalization"

---

With Git 2.36 (Q2 2022), the eol attribute documentation is completed.

See commit 8c591db, commit ab96151 (11 Jan 2022) by brian m. carlson (bk2204).
^{(Merged by Junio C Hamano -- gitster -- in commit 8db2f66, 11 Feb 2022)}

docs: correct documentation about eol attribute

^{Signed-off-by: brian m. carlson}

The documentation for the eol attribute states that it is "effectively setting the text attribute".

However, this implies that it forces the text attribute to always be set, which has not been the case since 6523728 (convert: unify the , 2016-06-28, Git v2.10.0-rc0 -- merge listed in batch #7) ("convert: unify the "auto" handling of CRLF", 2016-06-28).

Let's avoid confusing users (and the present author when trying to describe Git's behavior to others) by clearly documenting in which cases the "eol" attribute has effect.

Specifically, the attribute always has an effect unless the file is explicitly set as -text, or the file is set as text=auto and the file is detected as binary.

gitattributes now includes in its man page:

This attribute has effect only if the text attribute is set or unspecified, or if it is set to auto and the file is detected as text.

Note that setting this attribute on paths which are in the index with CRLF line endings may make the paths to be considered dirty.

Adding the path to the index again will normalize the line endings in the index.

---

To further clarify, with Git 2.36 (Q2 2022), the documentation is updated:

See commit 6a5678f (14 Feb 2022) by brian m. carlson (bk2204).
^{(Merged by Junio C Hamano -- gitster -- in commit 66633f2, 23 Feb 2022)}

doc: clarify interaction between 'eol' and text=auto

^{Signed-off-by: brian m. carlson}

The eol takes effect on text files only when the index has the contents in LF line endings.
Paths with contents in CRLF line endings in the index may become dirty unless text=auto.

gitattributes now includes in its man page:

This attribute sets a specific line-ending style to be used in the working directory.

This attribute has effect only if the text attribute is set or unspecified, or if it is set to auto, the file is detected as text, and it is stored with LF endings in the index.

Note that setting this attribute on paths which are in the index with CRLF line endings may make the paths to be considered dirty unless text=auto is set.
Adding the path to the index again will normalize the line endings in the index.

---

With Git 2.40 (Q1 2023), in-tree .gitattributes update to match the way we recommend our users to mark a file as text.

See commit 1f34e0c (03 Feb 2023) by Philip Oakley (PhilipOakley).
^{(Merged by Junio C Hamano -- gitster -- in commit f7c208c, 15 Feb 2023)}

.gitattributes: include text attribute for eol attributes

^{Signed-off-by: Philip Oakley}

The standard advice for text file eol endings in the .gitattributes file was updated in e28eae3 (gitattributes: Document the unified , 2016-08-26, Git v2.10.0-rc2 -- merge) (gitattributes: Document the unified "auto" handling, 2016-08-26) with a recent clarification in 8c591db ("docs: correct documentation about eol attribute", 2022-01-11, Git v2.36.0-rc0 -- merge listed in batch #3), with a follow up comment by the original author in this thread, confirming the use of the eol attribute in conjunction with the text attribute.

Update Git's .gitattributes file to reflect our own advice.

So instead of:

/Documentation/**/*.txt eol=lf

You now have:

/Documentation/**/*.txt text eol=lf