From: Alex Henrie <alexhenrie24@gmail.com>
To: "Torsten Bögershausen" <tboegi@web.de>
Cc: git@vger.kernel.org, eyvind.bernhardsen@gmail.com, gitster@pobox.com
Subject: Re: [PATCH v2] docs: rewrite the documentation of the text and eol attributes
Date: Sun, 30 Apr 2023 17:43:00 -0600 [thread overview]
Message-ID: <CAMMLpeS7Cf5JbgtLMY5XCPdhSLgtyZEMt2xLdRpfD=Yj+uvz2g@mail.gmail.com> (raw)
In-Reply-To: <20230430131943.4ag5gawuxkvuywlv@tb-raspi4>
On Sun, Apr 30, 2023 at 7:19 AM Torsten Bögershausen <tboegi@web.de> 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
prev parent reply other threads:[~2023-04-30 23:44 UTC|newest]
Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-04-21 5:56 [PATCH] docs: clarify how the text and text=auto attributes are different Alex Henrie
2023-04-21 16:35 ` 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 [this message]
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='CAMMLpeS7Cf5JbgtLMY5XCPdhSLgtyZEMt2xLdRpfD=Yj+uvz2g@mail.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).