From: Alex Henrie <alexhenrie24@gmail.com>
To: git@vger.kernel.org, eyvind.bernhardsen@gmail.com, tboegi@web.de,
gitster@pobox.com
Cc: Alex Henrie <alexhenrie24@gmail.com>
Subject: [PATCH] docs: clarify how the text and text=auto attributes are different
Date: Thu, 20 Apr 2023 23:56:41 -0600 [thread overview]
Message-ID: <20230421055641.550199-1-alexhenrie24@gmail.com> (raw)
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 confusing that the explanation of how end-of-line conversion
works is in the paragraph for text=auto even though it applies equally
to the text attribute which is described earlier.
On top of that, "When the file has been committed with CRLF, no
conversion is done" implies that normalization is only suppressed if the
file has been committed. In fact, running `git add` on a CRLF file,
adding the text attribute to the file, and running `git add` again does
not do anything to the line endings either.
Rephrase the documentation of text and text=auto to be clear about how
they are the same, how they are different, and in what cases
normalization is performed.
Signed-off-by: Alex Henrie <alexhenrie24@gmail.com>
---
Documentation/gitattributes.txt | 16 +++++++++-------
1 file changed, 9 insertions(+), 7 deletions(-)
diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index 39bfbca1ff..6db4ecd794 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -131,9 +131,12 @@ linkgit:git-config[1]).
Set::
- 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.
+ Setting the `text` attribute on a path marks the path as a text
+ file, which enables end-of-line normalization: When a matching file
+ is added to the index, even if it has CRLF line endings in the
+ working directory, the file is stored in Git with LF line endings.
+ However, if the file was already in Git with CRLF endings, no
+ conversion is done.
Unset::
@@ -142,10 +145,9 @@ Unset::
Set to string value "auto"::
- When `text` is set to "auto", the path is marked for automatic
- end-of-line conversion. If Git decides that the content is
- text, its line endings are converted to LF on checkin.
- When the file has been committed with CRLF, no conversion is done.
+ When text is set to "auto", Git decides by itself whether the file
+ is text or binary. If it is text, line endings are converted as
+ described above. If it is binary, they are not.
Unspecified::
--
2.40.0
next reply other threads:[~2023-04-21 5:56 UTC|newest]
Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-04-21 5:56 Alex Henrie [this message]
2023-04-21 16:35 ` [PATCH] docs: clarify how the text and text=auto attributes are different Junio C Hamano
2023-04-21 18:25 ` Torsten Bögershausen
2023-04-26 13:18 ` Alex Henrie
2023-04-28 4:22 ` [PATCH v2] docs: rewrite the documentation of the text and eol attributes Alex Henrie
2023-04-28 18:05 ` Junio C Hamano
2023-04-29 19:19 ` Alex Henrie
2023-04-30 5:16 ` Junio C Hamano
2023-05-01 0:40 ` Alex Henrie
2023-04-30 13:19 ` Torsten Bögershausen
2023-04-30 23:43 ` Alex Henrie
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20230421055641.550199-1-alexhenrie24@gmail.com \
--to=alexhenrie24@gmail.com \
--cc=eyvind.bernhardsen@gmail.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=tboegi@web.de \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).