Re: [PATCH] docs: clarify how the text and text=auto attributes are different

From: Alex Henrie <alexhenrie24@gmail.com>
Date: Apr 26, 2023, 13:18 UTC
Message-ID: <CAMMLpeRWXCFxk1wCjLPizdgJLG8n0Hy0o+Gm849Ln85cZkkH8w@mail.gmail.com>
In-Reply-To: <20230421182556.xxd4vrcksr6634ao@tb-raspi4>

On Fri, Apr 21, 2023 at 12:26 PM Torsten Bögershausen <tboegi@web.de> wrote:

Show 11 quoted lines

> Using
> *.txt text
> in .gitattributes
> will convert CRLF into LF in the repo at the next git commit/git add
>
> When you create a file with CRLF (no atttibutes), commit it into the repo,
> and later add the attribute "text", the file may be reported as modified.
> Not always. A `touch file.txt` typically asks Git to re-investigate things,
> and it may show up as modified.
> After a `git clone` it may be shown as modified or not.
> End of side-note.

Thank you very much for pointing that out. I had assumed that "text" and "text=auto" behaved the same for text files, but they do not: "text" normalizes line endings even if the file is already in Git. That means that my proposed text is not correct, and I will have to change it similarly to how you suggested below.

Show 17 quoted lines

> >  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.
>
> Here we need to have the lines from above:
>
> 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.
> However, if the file was already in Git with CRLF endings, no
> conversion is done.

Yes, the note about what happens if the file is already in Git with CRLF endings applies specifically to text=auto, so it needs to be in the text=auto section. The documentation of the eol attribute actually explains it more clearly:

"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."

I think that explanation needs to be moved from the eol attribute documentation to the text attribute documentation and edited for clarity. I will send a v2 that revises the documentation of both attributes, taking into account your and Junio's feedback.

Thanks again,

-Alex