docs: rewrite the documentation of the text and eol attributes
commit6696077aced3847b49af2db8b7477b6823fa681b
authorAlex Henrie <alexhenrie24@gmail.com>
Wed, 3 May 2023 04:46:56 +0000 (2 22:46 -0600)
committerJunio C Hamano <gitster@pobox.com>
Wed, 3 May 2023 16:02:11 +0000 (3 09:02 -0700)
tree9f97f531855daf9e85b00f565b55bc01d9a12ce0
parent0d1bd1dfb37ef25e1911777c94129fc769ffec38
docs: rewrite the documentation of the text and eol attributes

These two sentences are confusing because the description of the text
attribute sounds exactly the same as the description of the text=auto
attribute:

"Setting the text attribute on a path enables end-of-line normalization"

"When text is set to "auto", the path is marked for automatic
end-of-line conversion"

Unless the reader is already familiar with the two variants, there's a
high probability that they will think that "end-of-line normalization"
is the same thing as "automatic end-of-line conversion".

It's also not clear that the phrase "When the file has been committed
with CRLF, no conversion is done" in the paragraph for text=auto does
not apply equally to the bare text attribute which is described earlier.
Moreover, it falsely implies that normalization is only suppressed if
the file has been committed. In fact, running `git add` on a CRLF file,
adding the text=auto attribute to the file, and running `git add` again
does not do anything to the line endings either.

On top of that, in several places the documentation for the eol
attribute sounds like either it does not affect normalization on checkin
or it forces normalization on checkin. It also sounds like setting eol
(or setting a config variable) is required to turn on conversion on
checkout, but the text attribute can turn on conversion on checkout by
itself if eol is unspecified.

Rephrase the documentation of text, text=auto, eol, eol=crlf, and eol=lf
to be clear about how they are the same, how they are different, and in
what cases conversion is performed.

Helped-by: Torsten Bögershausen <tboegi@web.de>
Signed-off-by: Alex Henrie <alexhenrie24@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Documentation/gitattributes.txt