[PATCH 0/2] Improvements to tests and docs for .gitattributes eol

[PATCH 0/2] Improvements to tests and docs for .gitattributes eol

[brian m. carlson]

I was answering a question on StackOverflow recently about the
interaction between text=auto and eol, and someone pointed out to me
that what I had written, which was based on the documentation, was not
correct as of Git 2.10 (and more specifically 6523728499 ("convert:
unify the "auto" handling of CRLF", 2016-06-28)).

When I set out to document the behavior correctly, I ran into the fact
that the tests, where I looked for examples of how this behaves, didn't
have any tests for some of these cases, and so I had some trouble
documenting this clearly and accurately.  So this series basically just
adds some tests for existing behavior so we don't change it (and so I
could figure out how it works) and then updates the documentation
accordingly.

I tried to make the docs as specific as possible, since I needed them to
be specific and accurate here, and I felt like speaking affirmatively
about the behavior would be clearer than speaking negatively about the
behavior (I tried both).  I would of course be delighted to hear
suggestions on how this could be clearer or easier to understand.

I realize that 2.35.0-rc0 has just come out and so this won't be picked
up right away, which is fine, but I thought I'd send it out
nevertheless (mostly so I don't forget).

brian m. carlson (2):
  t0027: add tests for eol without text in .gitattributes
  docs: correct documentation about eol attribute

 Documentation/gitattributes.txt | 11 ++++++-----
 t/t0027-auto-crlf.sh            |  6 ++++++
 2 files changed, 12 insertions(+), 5 deletions(-)

[PATCH 1/2] t0027: add tests for eol without text in .gitattributes

[brian m. carlson]

Right now, it isn't clear what the behavior is when the eol attribute is
set in .gitattributes but the text attribute is not.  Let's add some
tests to document this behavior in our code, which happens to be that
the behavior is as if we set the text attribute implicitly.  This will
make sure we don't accidentally change the behavior, which somebody is
probably relying on, and serve as documentation to developers.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
 t/t0027-auto-crlf.sh | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/t/t0027-auto-crlf.sh b/t/t0027-auto-crlf.sh
index 4a5c5c602c..c5f7ac63b0 100755
--- a/t/t0027-auto-crlf.sh
+++ b/t/t0027-auto-crlf.sh
@@ -597,6 +597,12 @@ do
 	# auto: core.autocrlf=false and core.eol unset(or native) uses native eol
 	checkout_files     auto  "$id" ""     false   ""       $NL   CRLF  CRLF_mix_LF  LF_mix_CR    LF_nul
 	checkout_files     auto  "$id" ""     false   native   $NL   CRLF  CRLF_mix_LF  LF_mix_CR    LF_nul
+	# core.autocrlf false, .gitattributes sets eol
+	checkout_files     ""    "$id" "lf"   false   ""       LF    CRLF  CRLF_mix_LF  LF_mix_CR    LF_nul
+	checkout_files     ""    "$id" "crlf" false   ""       CRLF  CRLF  CRLF         CRLF_mix_CR  CRLF_nul
+	# core.autocrlf true, .gitattributes sets eol
+	checkout_files     ""    "$id" "lf"   true    ""       LF    CRLF  CRLF_mix_LF  LF_mix_CR    LF_nul
+	checkout_files     ""    "$id" "crlf" true    ""       CRLF  CRLF  CRLF         CRLF_mix_CR  CRLF_nul
 done
 
 # The rest of the tests are unique; do the usual linting.

[PATCH 2/2] docs: correct documentation about eol attribute

[brian m. carlson]

The documentation for the eol attribute states that it is "effectively
setting the text attribute".  However, this implies that it forces the
text attribute to always be set, which has not been the case since
6523728499 ("convert: unify the "auto" handling of CRLF", 2016-06-28).
Let's avoid confusing users (and the present author when trying to
describe Git's behavior to others) by clearly documenting in which
cases the "eol" attribute has effect.

Specifically, the attribute always has an effect unless the file is
explicitly set as -text, or the file is set as text=auto and the file is
detected as binary.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
 Documentation/gitattributes.txt | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index 83fd4e19a4..60984a4682 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -160,11 +160,12 @@ unspecified.
 ^^^^^
 
 This attribute sets a specific line-ending style to be used in the
-working directory.  It enables end-of-line conversion without any
-content checks, effectively setting the `text` attribute.  Note that
-setting this attribute on paths which are in the index with CRLF line
-endings may make the paths to be considered dirty.  Adding the path to
-the index again will normalize the line endings in the index.
+working directory.  This attribute has effect only if the `text`
+attribute is set or unspecified, or if it is set to `auto` and the file
+is detected as text.  Note that setting this attribute on paths which
+are in the index with CRLF line endings may make the paths to be
+considered dirty. Adding the path to the index again will normalize the
+line endings in the index.
 
 Set to string value "crlf"::
 

Re: [PATCH 2/2] docs: correct documentation about eol attribute

[Torsten =?unknown-8bit?Q?B=C3=B6gershausen?=]

Hej Brian,
thanks for digging into this.

Could you be so kind to send the stackoverflow issue ?
(You can send it to me only)

I have some comments/questions, out of my head.

On Tue, Jan 11, 2022 at 02:15:07AM +0000, brian m. carlson wrote:
> The documentation for the eol attribute states that it is "effectively
> setting the text attribute".
> Let's avoid confusing users (and the present author when trying to
> describe Git's behavior to others) by clearly documenting in which
> cases the "eol" attribute has effect.
>
> Specifically, the attribute always has an effect unless the file is
> explicitly set as -text, or the file is set as text=auto and the file is
> detected as binary.
>
> Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
> ---
>  Documentation/gitattributes.txt | 11 ++++++-----
>  1 file changed, 6 insertions(+), 5 deletions(-)
>
> diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
> index 83fd4e19a4..60984a4682 100644
> --- a/Documentation/gitattributes.txt
> +++ b/Documentation/gitattributes.txt
> @@ -160,11 +160,12 @@ unspecified.
>  ^^^^^
>
>  This attribute sets a specific line-ending style to be used in the
> -working directory.  It enables end-of-line conversion without any
> -content checks, effectively setting the `text` attribute.  Note that
> -setting this attribute on paths which are in the index with CRLF line
> -endings may make the paths to be considered dirty.  Adding the path to
> -the index again will normalize the line endings in the index.
> +working directory.  This attribute has effect only if the `text`
> +attribute is set or unspecified, or if it is set to `auto` and the file
> +is detected as text.



>  Note that setting this attribute on paths which
> +are in the index with CRLF line endings may make the paths to be
> +considered dirty. Adding the path to the index again will normalize the
> +line endings in the index.

I think that this can be loosened as well. And, beside this, the "dirty"
warning about setting attributes could be written as part of the "text"
attribute as well. I dunno. Here is a possible suggestion:


  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. `git ls-files --eol` can be used to check the "line ending status".
  Adding the path to the index again will normalize the line endings in the index.

>
>  Set to string value "crlf"::
>

Re: [PATCH 2/2] docs: correct documentation about eol attribute

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 1536 bytes --]

On 2022-01-11 at 18:30:03, Torsten Bögershausen wrote:
> Hej Brian,
> thanks for digging into this.
> 
> Could you be so kind to send the stackoverflow issue ?
> (You can send it to me only)

I'll just post it here publicly, since I think there's value to folks
seeing what questions users have:

https://stackoverflow.com/questions/70633469/what-is-the-difference-between-text-auto-and-text-auto-eol-lf/70636508?

> On Tue, Jan 11, 2022 at 02:15:07AM +0000, brian m. carlson wrote:
> >  Note that setting this attribute on paths which
> > +are in the index with CRLF line endings may make the paths to be
> > +considered dirty. Adding the path to the index again will normalize the
> > +line endings in the index.
> 
> I think that this can be loosened as well. And, beside this, the "dirty"
> warning about setting attributes could be written as part of the "text"
> attribute as well. I dunno. Here is a possible suggestion:
> 
> 
>   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. `git ls-files --eol` can be used to check the "line ending status".
>   Adding the path to the index again will normalize the line endings in the index.

I'm not sure that's correct, though.  The problem is if the file is
detected as text, which it might well be if text=auto is set.  Or am I
not understanding something correctly?
-- 
brian m. carlson (he/him or they/them)
Toronto, Ontario, CA

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 262 bytes --]

Re: [PATCH 2/2] docs: correct documentation about eol attribute

[Torsten =?unknown-8bit?Q?B=C3=B6gershausen?=]

On Tue, Jan 11, 2022 at 10:40:47PM +0000, brian m. carlson wrote:
> On 2022-01-11 at 18:30:03, Torsten B??gershausen wrote:
> > Hej Brian,
> > thanks for digging into this.
> >
> > Could you be so kind to send the stackoverflow issue ?
> > (You can send it to me only)
>
> I'll just post it here publicly, since I think there's value to folks
> seeing what questions users have:

Thanks - Please see the comments inline, as usual.

>
> https://stackoverflow.com/questions/70633469/what-is-the-difference-between-text-auto-and-text-auto-eol-lf/70636508?

To pick up the question here:

  I was reading about the .gitattributes file and the rule to force line endings
  in some tutorials it's written like
  * text=auto
  and in some others, it's like
  * text=auto eol=lf
  at the first line of the file.

  Are there any differences? what does the first one exactly do? Does it even force any line endings?
[]

Yes, there are differences.
The line
* text=auto
will make sure that all by-Git-as-text-files-detected files
will be commited with LF into the repo.
CRLF in the working tree will become LF in the repo.

When the files are checkout, the line endings depend on local
git config settings:
core.autocrlf=true will give CRLF
core.autocrlf=input will give LF
When core.autocrlf is false (or unset) git looks at core.eol:
core.eol=crlf gives CRLF
core.eol=lf gives LF
core.eol unset (or native) will use the the native line endings,
CRLF on Windows, LF everywhere else.
--------------
Let's look at
* text=auto eol=lf

Here Git does not look at any local config variables.
All files will be checkout out with LF, even on Windows.

>
> > On Tue, Jan 11, 2022 at 02:15:07AM +0000, brian m. carlson wrote:
> > >  Note that setting this attribute on paths which
> > > +are in the index with CRLF line endings may make the paths to be
> > > +considered dirty. Adding the path to the index again will normalize the
> > > +line endings in the index.
> >
> > I think that this can be loosened as well. And, beside this, the "dirty"
> > warning about setting attributes could be written as part of the "text"
> > attribute as well. I dunno. Here is a possible suggestion:
> >
> >
> >   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. `git ls-files --eol` can be used to check the "line ending status".
> >   Adding the path to the index again will normalize the line endings in the index.
>
> I'm not sure that's correct, though.  The problem is if the file is
> detected as text, which it might well be if text=auto is set.  Or am I
> not understanding something correctly?

Which problem are we talking about ?
Files that once had been commited with CRLF into the repo are
now considered dirty?
The "new safer autocrlf-handling" will not try to normalize them
when text=auto is specified.
They keep their existing line endings at checkout or checkin.

I hope this makes sense ?

[PATCH v2 0/2] Improvements to tests and docs for .gitattributes eol

[brian m. carlson]

I was answering a question on StackOverflow recently about the
interaction between text=auto and eol, and someone pointed out to me
that what I had written, which was based on the documentation, was not
correct as of Git 2.10 (and more specifically 6523728499 ("convert:
unify the "auto" handling of CRLF", 2016-06-28)).

When I set out to document the behavior correctly, I ran into the fact
that the tests, where I looked for examples of how this behaves, didn't
have any tests for some of these cases, and so I had some trouble
documenting this clearly and accurately.  So this series basically just
adds some tests for existing behavior so we don't change it (and so I
could figure out how it works) and then updates the documentation
accordingly.

Changes from v1:
* Correct documentation inaccuracy with respect to text=auto.

brian m. carlson (2):
  t0027: add tests for eol without text in .gitattributes
  docs: correct documentation about eol attribute

 Documentation/gitattributes.txt | 12 +++++++-----
 t/t0027-auto-crlf.sh            |  6 ++++++
 2 files changed, 13 insertions(+), 5 deletions(-)

[PATCH v2 1/2] t0027: add tests for eol without text in .gitattributes

[brian m. carlson]

Right now, it isn't clear what the behavior is when the eol attribute is
set in .gitattributes but the text attribute is not.  Let's add some
tests to document this behavior in our code, which happens to be that
the behavior is as if we set the text attribute implicitly.  This will
make sure we don't accidentally change the behavior, which somebody is
probably relying on, and serve as documentation to developers.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
 t/t0027-auto-crlf.sh | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/t/t0027-auto-crlf.sh b/t/t0027-auto-crlf.sh
index 4a5c5c602c..c5f7ac63b0 100755
--- a/t/t0027-auto-crlf.sh
+++ b/t/t0027-auto-crlf.sh
@@ -597,6 +597,12 @@ do
 	# auto: core.autocrlf=false and core.eol unset(or native) uses native eol
 	checkout_files     auto  "$id" ""     false   ""       $NL   CRLF  CRLF_mix_LF  LF_mix_CR    LF_nul
 	checkout_files     auto  "$id" ""     false   native   $NL   CRLF  CRLF_mix_LF  LF_mix_CR    LF_nul
+	# core.autocrlf false, .gitattributes sets eol
+	checkout_files     ""    "$id" "lf"   false   ""       LF    CRLF  CRLF_mix_LF  LF_mix_CR    LF_nul
+	checkout_files     ""    "$id" "crlf" false   ""       CRLF  CRLF  CRLF         CRLF_mix_CR  CRLF_nul
+	# core.autocrlf true, .gitattributes sets eol
+	checkout_files     ""    "$id" "lf"   true    ""       LF    CRLF  CRLF_mix_LF  LF_mix_CR    LF_nul
+	checkout_files     ""    "$id" "crlf" true    ""       CRLF  CRLF  CRLF         CRLF_mix_CR  CRLF_nul
 done
 
 # The rest of the tests are unique; do the usual linting.

[PATCH v2 2/2] docs: correct documentation about eol attribute

[brian m. carlson]

The documentation for the eol attribute states that it is "effectively
setting the text attribute".  However, this implies that it forces the
text attribute to always be set, which has not been the case since
6523728499 ("convert: unify the "auto" handling of CRLF", 2016-06-28).
Let's avoid confusing users (and the present author when trying to
describe Git's behavior to others) by clearly documenting in which
cases the "eol" attribute has effect.

Specifically, the attribute always has an effect unless the file is
explicitly set as -text, or the file is set as text=auto and the file is
detected as binary or has CRLF endings.  It used to be the case that
text=auto did cause automatic conversion of files with CRLF endings, but
that is no longer the case, so let's document that fact as well.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
 Documentation/gitattributes.txt | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index 83fd4e19a4..a71dad2674 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -160,11 +160,13 @@ unspecified.
 ^^^^^
 
 This attribute sets a specific line-ending style to be used in the
-working directory.  It enables end-of-line conversion without any
-content checks, effectively setting the `text` attribute.  Note that
-setting this attribute on paths which are in the index with CRLF line
-endings may make the paths to be considered dirty.  Adding the path to
-the index again will normalize the line endings in the index.
+working directory.  This attribute has effect only if the `text`
+attribute is set or unspecified, or if it is set to `auto`, the file is
+detected as text, and it is stored with LF endings in the index.  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.
 
 Set to string value "crlf"::
 

Re: [PATCH v2 0/2] Improvements to tests and docs for .gitattributes eol

[Derrick Stolee]

On 2/13/2022 9:08 PM, brian m. carlson wrote:
> I was answering a question on StackOverflow recently about the
> interaction between text=auto and eol, and someone pointed out to me
> that what I had written, which was based on the documentation, was not
> correct as of Git 2.10 (and more specifically 6523728499 ("convert:
> unify the "auto" handling of CRLF", 2016-06-28)).
> 
> When I set out to document the behavior correctly, I ran into the fact
> that the tests, where I looked for examples of how this behaves, didn't
> have any tests for some of these cases, and so I had some trouble
> documenting this clearly and accurately.  So this series basically just
> adds some tests for existing behavior so we don't change it (and so I
> could figure out how it works) and then updates the documentation
> accordingly.

Thanks for these updates. They look good as-is.

-Stolee

Re: [PATCH v2 0/2] Improvements to tests and docs for .gitattributes eol

[Junio C Hamano]

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

> I was answering a question on StackOverflow recently about the
> interaction between text=auto and eol, and someone pointed out to me
> that what I had written, which was based on the documentation, was not
> correct as of Git 2.10 (and more specifically 6523728499 ("convert:
> unify the "auto" handling of CRLF", 2016-06-28)).
>
> When I set out to document the behavior correctly, I ran into the fact
> that the tests, where I looked for examples of how this behaves, didn't
> have any tests for some of these cases, and so I had some trouble
> documenting this clearly and accurately.  So this series basically just
> adds some tests for existing behavior so we don't change it (and so I
> could figure out how it works) and then updates the documentation
> accordingly.

This seems to be a replacement of the two-patch series that was
merged to 'master' at 8db2f665 (Merge branch 'bc/clarify-eol-attr',
2022-02-11) and was merged to 'next' at dc1db4bd (Merge branch
'bc/clarify-eol-attr' into next, 2022-02-04).  The changes seem to
be in the second step to update Documentation/gitattributes.txt and
it needs to be made an incremental update.

Thanks.

---- >8 -----
From: brian m. carlson <sandals@crustytoothpaste.net>
Subject: doc: clarify interaction between 'eol' and text=auto

The `eol` takes effect on text files only when the index has the
contents in LF line endings.  Paths with contents in CRLF line
endings in the index may become dirty unless text=auto.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/gitattributes.txt | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git c/Documentation/gitattributes.txt w/Documentation/gitattributes.txt
index 60984a4682..a71dad2674 100644
--- c/Documentation/gitattributes.txt
+++ w/Documentation/gitattributes.txt
@@ -161,11 +161,12 @@ unspecified.
 
 This attribute sets a specific line-ending style to be used in the
 working directory.  This attribute has effect only if the `text`
-attribute is set or unspecified, or if it is set to `auto` and the file
-is detected as text.  Note that setting this attribute on paths which
-are in the index with CRLF line endings may make the paths to be
-considered dirty. Adding the path to the index again will normalize the
-line endings in the index.
+attribute is set or unspecified, or if it is set to `auto`, the file is
+detected as text, and it is stored with LF endings in the index.  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.
 
 Set to string value "crlf"::
 

Re: [PATCH v2 0/2] Improvements to tests and docs for .gitattributes eol

[Torsten =?unknown-8bit?Q?B=C3=B6gershausen?=]

[]
> This seems to be a replacement of the two-patch series that was
> merged to 'master' at 8db2f665 (Merge branch 'bc/clarify-eol-attr',
> 2022-02-11) and was merged to 'next' at dc1db4bd (Merge branch
> 'bc/clarify-eol-attr' into next, 2022-02-04).  The changes seem to
> be in the second step to update Documentation/gitattributes.txt and
> it needs to be made an incremental update.
>
> Thanks.
>
> ---- >8 -----
> From: brian m. carlson <sandals@crustytoothpaste.net>
> Subject: doc: clarify interaction between 'eol' and text=auto
>
> The `eol` takes effect on text files only when the index has the
> contents in LF line endings.  Paths with contents in CRLF line
> endings in the index may become dirty unless text=auto.

That is a nice, precise and short summary here in the commit message
as well as the patch further down.

>
> Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
>  Documentation/gitattributes.txt | 11 ++++++-----
>  1 file changed, 6 insertions(+), 5 deletions(-)
>
> diff --git c/Documentation/gitattributes.txt w/Documentation/gitattributes.txt
> index 60984a4682..a71dad2674 100644
> --- c/Documentation/gitattributes.txt
> +++ w/Documentation/gitattributes.txt
> @@ -161,11 +161,12 @@ unspecified.
>
>  This attribute sets a specific line-ending style to be used in the
>  working directory.  This attribute has effect only if the `text`
> -attribute is set or unspecified, or if it is set to `auto` and the file
> -is detected as text.  Note that setting this attribute on paths which
> -are in the index with CRLF line endings may make the paths to be
> -considered dirty. Adding the path to the index again will normalize the
> -line endings in the index.
> +attribute is set or unspecified, or if it is set to `auto`, the file is
> +detected as text, and it is stored with LF endings in the index.  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.
>
>  Set to string value "crlf"::
>

Re: [PATCH v2 0/2] Improvements to tests and docs for .gitattributes eol

[Junio C Hamano]

Torsten Bögershausen <tboegi@web.de> writes:

>> ---- >8 -----
>> From: brian m. carlson <sandals@crustytoothpaste.net>
>> Subject: doc: clarify interaction between 'eol' and text=auto
>>
>> The `eol` takes effect on text files only when the index has the
>> contents in LF line endings.  Paths with contents in CRLF line
>> endings in the index may become dirty unless text=auto.
>
> That is a nice, precise and short summary here in the commit message
> as well as the patch further down.

Thanks.  Then let's queue it for 'next' and merge it down.

>>
>> Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
>> Signed-off-by: Junio C Hamano <gitster@pobox.com>
>> ---
>>  Documentation/gitattributes.txt | 11 ++++++-----
>>  1 file changed, 6 insertions(+), 5 deletions(-)
>>
>> diff --git c/Documentation/gitattributes.txt w/Documentation/gitattributes.txt
>> index 60984a4682..a71dad2674 100644
>> --- c/Documentation/gitattributes.txt
>> +++ w/Documentation/gitattributes.txt
>> @@ -161,11 +161,12 @@ unspecified.
>>
>>  This attribute sets a specific line-ending style to be used in the
>>  working directory.  This attribute has effect only if the `text`
>> -attribute is set or unspecified, or if it is set to `auto` and the file
>> -is detected as text.  Note that setting this attribute on paths which
>> -are in the index with CRLF line endings may make the paths to be
>> -considered dirty. Adding the path to the index again will normalize the
>> -line endings in the index.
>> +attribute is set or unspecified, or if it is set to `auto`, the file is
>> +detected as text, and it is stored with LF endings in the index.  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.
>>
>>  Set to string value "crlf"::
>>

Re: [PATCH v2 0/2] Improvements to tests and docs for .gitattributes eol

[Johannes Sixt]

Am 15.02.22 um 01:15 schrieb Junio C Hamano:
> Torsten Bögershausen <tboegi@web.de> writes:
> 
>>> ---- >8 -----
>>> From: brian m. carlson <sandals@crustytoothpaste.net>
>>> Subject: doc: clarify interaction between 'eol' and text=auto
>>>
>>> The `eol` takes effect on text files only when the index has the
>>> contents in LF line endings.  Paths with contents in CRLF line
>>> endings in the index may become dirty unless text=auto.
>>
>> That is a nice, precise and short summary here in the commit message
>> as well as the patch further down.
> 
> Thanks.  Then let's queue it for 'next' and merge it down.
> 
>>>
>>> Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
>>> Signed-off-by: Junio C Hamano <gitster@pobox.com>
>>> ---
>>>  Documentation/gitattributes.txt | 11 ++++++-----
>>>  1 file changed, 6 insertions(+), 5 deletions(-)
>>>
>>> diff --git c/Documentation/gitattributes.txt w/Documentation/gitattributes.txt
>>> index 60984a4682..a71dad2674 100644
>>> --- c/Documentation/gitattributes.txt
>>> +++ w/Documentation/gitattributes.txt
>>> @@ -161,11 +161,12 @@ unspecified.
>>>
>>>  This attribute sets a specific line-ending style to be used in the
>>>  working directory.  This attribute has effect only if the `text`
>>> -attribute is set or unspecified, or if it is set to `auto` and the file
>>> -is detected as text.  Note that setting this attribute on paths which
>>> -are in the index with CRLF line endings may make the paths to be
>>> -considered dirty. Adding the path to the index again will normalize the
>>> -line endings in the index.
>>> +attribute is set or unspecified, or if it is set to `auto`, the file is
>>> +detected as text, and it is stored with LF endings in the index.  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.

Sorry, I don't find this description clear at all due to the many 'or's
and 'and's and no indication which parts belong together. The original
text was clear (but, of course, not helpful if it was wrong).

I suggest to rewrite the paragraph into format with bullet points:

   ... only if one of the following is true:

  - is set and foo or bar
  - is unspecified and either
      - this
      - or that
  - is set to auto but not...

or something along the lines. I can't propose actual text because I have
no clue what the truth is.

-- Hannes

Re: [PATCH v2 0/2] Improvements to tests and docs for .gitattributes eol

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 817 bytes --]

On 2022-02-15 at 07:05:44, Johannes Sixt wrote:
> Sorry, I don't find this description clear at all due to the many 'or's
> and 'and's and no indication which parts belong together. The original
> text was clear (but, of course, not helpful if it was wrong).
> 
> I suggest to rewrite the paragraph into format with bullet points:
> 
>    ... only if one of the following is true:
> 
>   - is set and foo or bar
>   - is unspecified and either
>       - this
>       - or that
>   - is set to auto but not...
> 
> or something along the lines. I can't propose actual text because I have
> no clue what the truth is.

Unfortunately, the fact is that this behaviour is complicated.  I can
try a reroll with a bulleted list, though.
-- 
brian m. carlson (he/him or they/them)
Toronto, Ontario, CA

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 262 bytes --]

Re: [PATCH v2 0/2] Improvements to tests and docs for .gitattributes eol

[Johannes Sixt]

Am 15.02.22 um 23:46 schrieb brian m. carlson:
> On 2022-02-15 at 07:05:44, Johannes Sixt wrote:
>> Sorry, I don't find this description clear at all due to the many 'or's
>> and 'and's and no indication which parts belong together. The original
>> text was clear (but, of course, not helpful if it was wrong).
>>
>> I suggest to rewrite the paragraph into format with bullet points:
>>
>>    ... only if one of the following is true:
>>
>>   - is set and foo or bar
>>   - is unspecified and either
>>       - this
>>       - or that
>>   - is set to auto but not...
>>
>> or something along the lines. I can't propose actual text because I have
>> no clue what the truth is.
> 
> Unfortunately, the fact is that this behaviour is complicated.  I can
> try a reroll with a bulleted list, though.

Just so you know where my confusion arises from: Your updated text has
the structure (as I read it)

   if ... set or unspecified or if auto then ... detected ... and LF

It is unclear whether the 'then' conditions apply only to 'if auto'.
Even if the additional 'if' in the middle makes me think that the
'then's apply only to the 'auto' case, it is sufficently vage because in
my mental model there is not much difference between an 'unset' and a
set-to-'auto' attribute, and I wonder why the 'then's should not apply
to the 'unset' case as well.

Moreover, after re-reading the text, I notice that text may be read as
"this attribute has an effect only if <conditions>" where <conditions>
basically means "always except for when the 'if auto' case is not met",
right? Would it perhaps be better to write "has no effect if <very
specific condition>"?

-- Hannes

Re: [PATCH v2 0/2] Improvements to tests and docs for .gitattributes eol

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 1588 bytes --]

On 2022-02-16 at 07:00:24, Johannes Sixt wrote:
> Just so you know where my confusion arises from: Your updated text has
> the structure (as I read it)
> 
>    if ... set or unspecified or if auto then ... detected ... and LF
> 
> It is unclear whether the 'then' conditions apply only to 'if auto'.
> Even if the additional 'if' in the middle makes me think that the
> 'then's apply only to the 'auto' case, it is sufficently vage because in
> my mental model there is not much difference between an 'unset' and a
> set-to-'auto' attribute, and I wonder why the 'then's should not apply
> to the 'unset' case as well.
> 
> Moreover, after re-reading the text, I notice that text may be read as
> "this attribute has an effect only if <conditions>" where <conditions>
> basically means "always except for when the 'if auto' case is not met",
> right? Would it perhaps be better to write "has no effect if <very
> specific condition>"?

The situation is that eol is in effect if and only if:

* text is set;
* text is unspecified; or
* text is auto, the file is detected as text, and the file has LF line
  endings in the index.

Alternately, it has no effect if and only if:

* text is unset;
* text is auto and the file is detected as binary; or
* text is auto and the file is detected as text and has CRLF line
  endings.

I'm not sure one reads significantly easier than the other.  I slightly
prefer the former because it has fewer conditions with multiple nested
entries, though.
-- 
brian m. carlson (he/him or they/them)
Toronto, Ontario, CA

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 262 bytes --]

Re: [PATCH v2 0/2] Improvements to tests and docs for .gitattributes eol

[Torsten =?unknown-8bit?Q?B=C3=B6gershausen?=]

On Wed, Feb 16, 2022 at 10:28:24AM +0000, brian m. carlson wrote:
> On 2022-02-16 at 07:00:24, Johannes Sixt wrote:
> > Just so you know where my confusion arises from: Your updated text has
> > the structure (as I read it)
> >
> >    if ... set or unspecified or if auto then ... detected ... and LF
> >
> > It is unclear whether the 'then' conditions apply only to 'if auto'.
> > Even if the additional 'if' in the middle makes me think that the
> > 'then's apply only to the 'auto' case, it is sufficently vage because in
> > my mental model there is not much difference between an 'unset' and a
> > set-to-'auto' attribute, and I wonder why the 'then's should not apply
> > to the 'unset' case as well.
> >
> > Moreover, after re-reading the text, I notice that text may be read as
> > "this attribute has an effect only if <conditions>" where <conditions>
> > basically means "always except for when the 'if auto' case is not met",
> > right? Would it perhaps be better to write "has no effect if <very
> > specific condition>"?
>
> The situation is that eol is in effect if and only if:

Well written

>
> * text is set;
> * text is unspecified; or
> * text is auto, the file is detected as text, and the file has LF line
>   endings in the index.
>
> Alternately, it has no effect if and only if:
>
> * text is unset;
> * text is auto and the file is detected as binary; or
> * text is auto and the file is detected as text and has CRLF line
>   endings.
... CRLF line endings in the index.
                      ^^^^^^^^^^^^

One of the reasons that the eol attribute is not 100% well-specified
is that people should use the eol attribute together with text.

Either
text=auto eol=crlf
or
text=auto eol=lf
or
text eol=crlf
or
text eol=lf

Older git versions did treat
* text=auto
* eol=crlf

The same as
* text eol=crlf
Which did corrupt binary files.

Never git versions treat
* text=auto
* eol=crlf
as
* text=auto eol=crlf
in the sense that only auto-detected text files are converted,
if they had not been commited with crlf before.

In that sense I feel that the short form
eol=crlf
should be avoided

>
> I'm not sure one reads significantly easier than the other.  I slightly
> prefer the former because it has fewer conditions with multiple nested
> entries, though.
> --
> brian m. carlson (he/him or they/them)
> Toronto, Ontario, CA

Re: [PATCH v2 0/2] Improvements to tests and docs for .gitattributes eol

[Johannes Sixt]

Am 16.02.22 um 11:28 schrieb brian m. carlson:
> The situation is that eol is in effect if and only if:
> 
> * text is set;
> * text is unspecified; or
> * text is auto, the file is detected as text, and the file has LF line
>   endings in the index.
> 
> Alternately, it has no effect if and only if:
> 
> * text is unset;
> * text is auto and the file is detected as binary; or
> * text is auto and the file is detected as text and has CRLF line
>   endings.
> 
> I'm not sure one reads significantly easier than the other.  I slightly
> prefer the former because it has fewer conditions with multiple nested
> entries, though.

I agree that the first version is easier to understand.

-- Hannes

[PATCH] .gitattributes: include `text` attribute for eol attributes

[Philip Oakley]

The standard advice for text file eol endings in the .gitattributes file
was updated in e28eae3184 (gitattributes: Document the unified "auto"
handling, 2016-08-26) with a recent clarification in 8c591dbfce (docs:
correct documentation about eol attribute, 2022-01-11), with a follow
up comment by the original author in [1] confirming the use of the eol
attribute in conjunction with the text attribute.

Update Git's .gitattributes file to reflect our own advice.

[1] https://lore.kernel.org/git/?q=%3C20220216115239.uo2ie3flaqo3nf2d%40tb-raspi4%3E.

Signed-off-by: Philip Oakley <philipoakley@iee.email>
---

I was catching up on last year's back emails, and had saved those on
eol and text conversion, and was prompted by Torsten's [1] to check
my .gitattribute files, only to discover, we aren't providing a good
example to others. Let's fix that. 


 .gitattributes | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/.gitattributes b/.gitattributes
index b0044cf272..158c3d45c4 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -1,17 +1,17 @@
 * whitespace=!indent,trail,space
 *.[ch] whitespace=indent,trail,space diff=cpp
-*.sh whitespace=indent,trail,space eol=lf
-*.perl eol=lf diff=perl
-*.pl eof=lf diff=perl
-*.pm eol=lf diff=perl
-*.py eol=lf diff=python
-*.bat eol=crlf
+*.sh whitespace=indent,trail,space text eol=lf
+*.perl text eol=lf diff=perl
+*.pl text eof=lf diff=perl
+*.pm text eol=lf diff=perl
+*.py text eol=lf diff=python
+*.bat text eol=crlf
 CODE_OF_CONDUCT.md -whitespace
-/Documentation/**/*.txt eol=lf
-/command-list.txt eol=lf
-/GIT-VERSION-GEN eol=lf
-/mergetools/* eol=lf
-/t/oid-info/* eol=lf
+/Documentation/**/*.txt text eol=lf
+/command-list.txt text eol=lf
+/GIT-VERSION-GEN text eol=lf
+/mergetools/* text eol=lf
+/t/oid-info/* text eol=lf
 /Documentation/git-merge.txt conflict-marker-size=32
 /Documentation/gitk.txt conflict-marker-size=32
 /Documentation/user-manual.txt conflict-marker-size=32
-- 
2.39.1.windows.1

Re: [PATCH] .gitattributes: include `text` attribute for eol attributes

[Ævar Arnfjörð Bjarmason]

On Fri, Feb 03 2023, Philip Oakley wrote:

> The standard advice for text file eol endings in the .gitattributes file
> was updated in e28eae3184 (gitattributes: Document the unified "auto"
> handling, 2016-08-26) with a recent clarification in 8c591dbfce (docs:
> correct documentation about eol attribute, 2022-01-11), with a follow
> up comment by the original author in [1] confirming the use of the eol
> attribute in conjunction with the text attribute.
>
> Update Git's .gitattributes file to reflect our own advice.
>
> [1] https://lore.kernel.org/git/?q=%3C20220216115239.uo2ie3flaqo3nf2d%40tb-raspi4%3E.
>
> Signed-off-by: Philip Oakley <philipoakley@iee.email>
> ---
>
> I was catching up on last year's back emails, and had saved those on
> eol and text conversion, and was prompted by Torsten's [1] to check
> my .gitattribute files, only to discover, we aren't providing a good
> example to others. Let's fix that. 

This seems sensible, but if we're taking the churn of changing these
lines maybe it's worth moving or adjusting some of this while-at-it.

In particular:

>  .gitattributes | 22 +++++++++++-----------
>  1 file changed, 11 insertions(+), 11 deletions(-)
>
> diff --git a/.gitattributes b/.gitattributes
> index b0044cf272..158c3d45c4 100644
> --- a/.gitattributes
> +++ b/.gitattributes
> @@ -1,17 +1,17 @@
>  * whitespace=!indent,trail,space
>  *.[ch] whitespace=indent,trail,space diff=cpp
> -*.sh whitespace=indent,trail,space eol=lf
> -*.perl eol=lf diff=perl
> -*.pl eof=lf diff=perl
> -*.pm eol=lf diff=perl
> -*.py eol=lf diff=python
> -*.bat eol=crlf

We don't have any *.bat in-tree except in compat/vcbuild/. Shouldn't we
just create a compat/vcbuild/.gitattributes? This was added in
https://lore.kernel.org/git/pull.149.v2.git.gitgitgadget@gmail.com/; so
it's for those specific files.

>  CODE_OF_CONDUCT.md -whitespace
> -/Documentation/**/*.txt eol=lf
> -/command-list.txt eol=lf
> -/GIT-VERSION-GEN eol=lf
> -/mergetools/* eol=lf
> -/t/oid-info/* eol=lf
> +/Documentation/**/*.txt text eol=lf

We have a Documentation/.gitattributes, shouldn't we move this
Documentation/ rule there instead?

> +/command-list.txt text eol=lf
> +/GIT-VERSION-GEN text eol=lf
> +/mergetools/* text eol=lf

..maybe we should create a mergetools/.gitattributes & move this there?

> +/t/oid-info/* text eol=lf

Ditto t/.gitattributes and thist/oid-info/ rule.

>  /Documentation/git-merge.txt conflict-marker-size=32
>  /Documentation/gitk.txt conflict-marker-size=32
>  /Documentation/user-manual.txt conflict-marker-size=32

Re: [PATCH] .gitattributes: include `text` attribute for eol attributes

[Philip Oakley]

On 03/02/2023 13:40, Ævar Arnfjörð Bjarmason wrote:
> On Fri, Feb 03 2023, Philip Oakley wrote:
>
>> The standard advice for text file eol endings in the .gitattributes file
>> was updated in e28eae3184 (gitattributes: Document the unified "auto"
>> handling, 2016-08-26) with a recent clarification in 8c591dbfce (docs:
>> correct documentation about eol attribute, 2022-01-11), with a follow
>> up comment by the original author in [1] confirming the use of the eol
>> attribute in conjunction with the text attribute.
>>
>> Update Git's .gitattributes file to reflect our own advice.
>>
>> [1] https://lore.kernel.org/git/?q=%3C20220216115239.uo2ie3flaqo3nf2d%40tb-raspi4%3E.
>>
>> Signed-off-by: Philip Oakley <philipoakley@iee.email>
>> ---
>>
>> I was catching up on last year's back emails, and had saved those on
>> eol and text conversion, and was prompted by Torsten's [1] to check
>> my .gitattribute files, only to discover, we aren't providing a good
>> example to others. Let's fix that. 
> This seems sensible, but if we're taking the churn of changing these
> lines maybe it's worth moving or adjusting some of this while-at-it.

Seems reasonable.
I've added in dscho (cc) for consideration of the Git for Windows
viewpoint..
>
> In particular:
>
>>  .gitattributes | 22 +++++++++++-----------
>>  1 file changed, 11 insertions(+), 11 deletions(-)
>>
>> diff --git a/.gitattributes b/.gitattributes
>> index b0044cf272..158c3d45c4 100644
>> --- a/.gitattributes
>> +++ b/.gitattributes
>> @@ -1,17 +1,17 @@
>>  * whitespace=!indent,trail,space
>>  *.[ch] whitespace=indent,trail,space diff=cpp
>> -*.sh whitespace=indent,trail,space eol=lf
>> -*.perl eol=lf diff=perl
>> -*.pl eof=lf diff=perl
>> -*.pm eol=lf diff=perl
>> -*.py eol=lf diff=python
>> -*.bat eol=crlf
> We don't have any *.bat in-tree except in compat/vcbuild/. Shouldn't we
> just create a compat/vcbuild/.gitattributes? This was added in
> https://lore.kernel.org/git/pull.149.v2.git.gitgitgadget@gmail.com/; so
> it's for those specific files.

sensible
>>  CODE_OF_CONDUCT.md -whitespace

Maybe the CODE_OF_CONDUCT.md should also be marked as text?

>> -/Documentation/**/*.txt eol=lf
>> -/command-list.txt eol=lf
>> -/GIT-VERSION-GEN eol=lf
>> -/mergetools/* eol=lf
>> -/t/oid-info/* eol=lf
>> +/Documentation/**/*.txt text eol=lf
> We have a Documentation/.gitattributes, shouldn't we move this
> Documentation/ rule there instead?

ok
>
>> +/command-list.txt text eol=lf
>> +/GIT-VERSION-GEN text eol=lf
>> +/mergetools/* text eol=lf
> ..maybe we should create a mergetools/.gitattributes & move this there?

perhaps. There are probably sufficient listed there to make it work it.
>
>> +/t/oid-info/* text eol=lf
> Ditto t/.gitattributes and this t/oid-info/ rule.
>
>>  /Documentation/git-merge.txt conflict-marker-size=32
>>  /Documentation/gitk.txt conflict-marker-size=32
>>  /Documentation/user-manual.txt conflict-marker-size=32
I'll hold a day or so for any extra contributions.

Philip

Re: [PATCH] .gitattributes: include `text` attribute for eol attributes

[Torsten Bögershausen]

On Fri, Feb 03, 2023 at 12:59:20PM +0000, Philip Oakley wrote:
> The standard advice for text file eol endings in the .gitattributes file
> was updated in e28eae3184 (gitattributes: Document the unified "auto"
> handling, 2016-08-26) with a recent clarification in 8c591dbfce (docs:
> correct documentation about eol attribute, 2022-01-11), with a follow
> up comment by the original author in [1] confirming the use of the eol
> attribute in conjunction with the text attribute.
>
> Update Git's .gitattributes file to reflect our own advice.
>
> [1] https://lore.kernel.org/git/?q=%3C20220216115239.uo2ie3flaqo3nf2d%40tb-raspi4%3E.
>
> Signed-off-by: Philip Oakley <philipoakley@iee.email>
> ---
>
> I was catching up on last year's back emails, and had saved those on
> eol and text conversion, and was prompted by Torsten's [1] to check
> my .gitattribute files, only to discover, we aren't providing a good
> example to others. Let's fix that.
>
>
>  .gitattributes | 22 +++++++++++-----------
>  1 file changed, 11 insertions(+), 11 deletions(-)
>
> diff --git a/.gitattributes b/.gitattributes
> index b0044cf272..158c3d45c4 100644
> --- a/.gitattributes
> +++ b/.gitattributes
> @@ -1,17 +1,17 @@
>  * whitespace=!indent,trail,space
>  *.[ch] whitespace=indent,trail,space diff=cpp
> -*.sh whitespace=indent,trail,space eol=lf
> -*.perl eol=lf diff=perl
> -*.pl eof=lf diff=perl
> -*.pm eol=lf diff=perl
> -*.py eol=lf diff=python
> -*.bat eol=crlf
> +*.sh whitespace=indent,trail,space text eol=lf
> +*.perl text eol=lf diff=perl
> +*.pl text eof=lf diff=perl
> +*.pm text eol=lf diff=perl

> +*.py text eol=lf diff=python
In my eperience python doesn't care about CRLF or LF, both work.

And it is stated here:
https://docs.python.org/3/reference/lexical_analysis.html?highlight=line%20endings

In that sense we can loosen the eol=lf, and use CRLF under
Windows and LF elsewhere. This will make e.g. notepad users happy:

> +*.py text  diff=python

Re: [PATCH] .gitattributes: include `text` attribute for eol attributes

[Junio C Hamano]

Philip Oakley <philipoakley@iee.email> writes:

> The standard advice for text file eol endings in the .gitattributes file
> was updated in e28eae3184 (gitattributes: Document the unified "auto"
> handling, 2016-08-26) with a recent clarification in 8c591dbfce (docs:
> correct documentation about eol attribute, 2022-01-11), with a follow
> up comment by the original author in [1] confirming the use of the eol
> attribute in conjunction with the text attribute.
>
> Update Git's .gitattributes file to reflect our own advice.
>
> [1] https://lore.kernel.org/git/?q=%3C20220216115239.uo2ie3flaqo3nf2d%40tb-raspi4%3E.
>
> Signed-off-by: Philip Oakley <philipoakley@iee.email>
> ---
>
> I was catching up on last year's back emails, and had saved those on
> eol and text conversion, and was prompted by Torsten's [1] to check
> my .gitattribute files, only to discover, we aren't providing a good
> example to others. Let's fix that. 

Thanks.  Let's keep this single step as a pure "no, eol=lf alone is
not how we recommend you to mark a text file, and here is the fix"
change.

There may be other things people might want to do on top of
this change, but they can be done on top.

Will queue.  Thanks.


>
>
>  .gitattributes | 22 +++++++++++-----------
>  1 file changed, 11 insertions(+), 11 deletions(-)
>
> diff --git a/.gitattributes b/.gitattributes
> index b0044cf272..158c3d45c4 100644
> --- a/.gitattributes
> +++ b/.gitattributes
> @@ -1,17 +1,17 @@
>  * whitespace=!indent,trail,space
>  *.[ch] whitespace=indent,trail,space diff=cpp
> -*.sh whitespace=indent,trail,space eol=lf
> -*.perl eol=lf diff=perl
> -*.pl eof=lf diff=perl
> -*.pm eol=lf diff=perl
> -*.py eol=lf diff=python
> -*.bat eol=crlf
> +*.sh whitespace=indent,trail,space text eol=lf
> +*.perl text eol=lf diff=perl
> +*.pl text eof=lf diff=perl
> +*.pm text eol=lf diff=perl
> +*.py text eol=lf diff=python
> +*.bat text eol=crlf
>  CODE_OF_CONDUCT.md -whitespace
> -/Documentation/**/*.txt eol=lf
> -/command-list.txt eol=lf
> -/GIT-VERSION-GEN eol=lf
> -/mergetools/* eol=lf
> -/t/oid-info/* eol=lf
> +/Documentation/**/*.txt text eol=lf
> +/command-list.txt text eol=lf
> +/GIT-VERSION-GEN text eol=lf
> +/mergetools/* text eol=lf
> +/t/oid-info/* text eol=lf
>  /Documentation/git-merge.txt conflict-marker-size=32
>  /Documentation/gitk.txt conflict-marker-size=32
>  /Documentation/user-manual.txt conflict-marker-size=32