Re: [PATCH v2] docs: rewrite the documentation of the text and eol attributes

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



On Sun, Apr 30, 2023 at 7:19 AM Torsten Bögershausen <tboegi@xxxxxx> wrote:
>
> On Thu, Apr 27, 2023 at 10:22:21PM -0600, Alex Henrie wrote:

> > -This attribute enables and controls end-of-line normalization.  When a
>
> Hm, not only, I think. The terminologie is probably not very well specified.
> I would say that it "controls end-of-line conversion".
> There are 2 type of conversions, from CRLF into LF and LF into CRLF.
> The CRLF -> LF conversion happens only at `git commit`
> (strictly speaking already at `git add`) and is called normalization.
> Because in Git a "normalized" file has LF in the repo (and index).
> The term normalize has even been add to 2 commands:
>
> `git add --renormalize .`
> inspired by
> `git merge -Xrenormalize`

Yes, we should probably be consistent about using the word "normalize"
to refer to conversion to LF and the word "convert" to refer to
conversion to CRLF or conversion in general. That would also allow us
to use the word "normalize" for emphasis without wondering whether to
add "if necessary", because normalization certainly does not imply
conversion if the file is already normalized.

> > -Note that setting `core.autocrlf` to `true` or `input` overrides
> > -`core.eol` (see the definitions of those options in
> > -linkgit:git-config[1]).
>
> Looking with fresh eyes: I am not sure if like this historical construct.
> First we say the the "core.eol" sets the line endings (if not defined in
> the attribute) and the we say that core.autcrlf overrides core.eol
>
> This is mainly due to historically resons.
> I think that things goes like this:
> When text or text=auto (and Git identifies the file as text),
> and the eol attribute is not set, then:
> core.autocrlf=true gives CRLF
> core.autocrlf=input give LF
> core.autocrlf=false looks at core.eol:
> core.eol=clrf gives CRLF
> core.eol=lf give LF
> core.eol unset gives the platform default

Yes, core.autocrlf takes precedence over core.eol. That's explained in
the git-config documentation and doesn't need to be explained again in
the attribute documentation. However, in the documentation for
unspecified `eol`, I did make sure to name `eol`, core.autocrlf, and
core.eol in order of precedence.

> > +file is added to the index, even if it has CRLF line endings in the
> > +working directory, the file is stored in the index with LF line endings.
> > +Conversely, when the file is copied from the index to the working
> "copied" is not an ideal word here:
> We may specify a filter and/or an encoding as well.
> Would "transferred and possibly filtered/encoded" be better ?

Although "transferred and possibly filtered/encoded" might be
technically more accurate, it is a mouthful. For readability, it would
be better to keep the documentation concise. It's clear in this
sentence that "copy" does not mean a byte-for-byte copy (because the
line endings may be changed), which leaves open the possibility that
the file may be transformed in other ways during checkout.

> > +     When `text` is set to "auto", Git decides by itself whether the file
> > +     is text or binary.  If it is text and the file was not already in
> > +     Git with CRLF endings, line endings are converted on checkin and
> > +     checkout as described above.  Otherwise, no conversion is done on
> > +     checkin or checkout.
>
> Side note: We previously talked about files. path is better.

It depends: When talking about applying the attribute to a path, path
is better, but the actual transformation happens on the file contents.
The file is what's text or binary and the file is what's transformed;
the path is always text and never transformed.

Thanks for the feedback. I will send a v3 that takes into account your
feedback and Junio's.

-Alex




[Index of Archives]     [Linux Kernel Development]     [Gcc Help]     [IETF Annouce]     [DCCP]     [Netdev]     [Networking]     [Security]     [V4L]     [Bugtraq]     [Yosemite]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Linux SCSI]     [Fedora Users]

  Powered by Linux