threads / discuss / 50335

unclear docs

Subject: unclear docs

## tl;dr

16 messages between Jan 27, 2019 and Jan 29, 2019.

replies: 15people: 4as markdown or json

Sergey Lukashev· Jan 27, 2019, 09:58 UTC · lore
Hello!

Could somebody please explain what 'core.autocrlf overrides core.eol' means given that we have the following statement in core.eol docs: "Sets the line ending type to use in the working directory for files that have the text property set when core.autocrlf is false".

I would like to know which line endings I'm supposed to get in the working tree if I have core.autocrlf=false and '* text=auto' in .gitattributes on windows. I get CRLFs  which is consistent with the last quote but I don't understand what 'core.autocrlf overrides core.eol' means in this case.

Links: https://git-scm.com/docs/git-config#git-config-coreeol https://git-scm.com/docs/gitattributes#_checking_out_and_checking_in

Sergey Lukashev· Jan 27, 2019, 11:55 UTC · re: Sergey Lukashev · lore

Re: unclear docs

A follow up on my previous mail.
Well, I have two problems:
1) The endings I get with core.autocrlf=false depend on whether I have * text=auto (a file was commited with LFs). At least in git 2.20.1
2) If the quote holds true then autocrlf=false is actually "true" (for output conversion) on Windows by default because default core.eol is 'native', which is CRLF. I believe autocrlf=false is supposed to mean "no any conversion, input or output, read or write the repo as is".
27.01.2019, 13:05, "Sergey Lukashev" <lukashev.s@ya.ru>:
Show 10 quoted lines
> Hello!
>
> Could somebody please explain what 'core.autocrlf overrides core.eol' means given that we have the following statement in core.eol docs:
> "Sets the line ending type to use in the working directory for files that have the text property set when core.autocrlf is false".
>
> I would like to know which line endings I'm supposed to get in the working tree if I have core.autocrlf=false and '* text=auto' in .gitattributes on windows. I get CRLFs which is consistent with the last quote but I don't understand what 'core.autocrlf overrides core.eol' means in this case.
>
> Links:
> https://git-scm.com/docs/git-config#git-config-coreeol
> https://git-scm.com/docs/gitattributes#_checking_out_and_checking_in
Jeff King· Jan 28, 2019, 16:09 UTC · re: Sergey Lukashev · lore

Re: unclear docs

On Sun, Jan 27, 2019 at 02:55:23PM +0300, Sergey Lukashev wrote:
> Well, I have two problems:
> 1) The endings I get with core.autocrlf=false depend on whether I have
>    * text=auto (a file was commited with LFs). At least in git 2.20.1

That sounds right. The default is that Git will never touch your line endings (going into or out of the working tree). Turning on the "text=auto" attribute for everything will tell it to start doing so (according to core.eol, which on Windows is CRLF).

Show 5 quoted lines
> 2) If the quote holds true then autocrlf=false is actually "true" (for
>    output conversion) on Windows by default because default core.eol
>    is 'native', which is CRLF. I believe autocrlf=false is supposed to
>    mean "no any conversion, input or output, read or write the repo as
>    is".

No, it only means "do not use the autocrlf feature". If you've separately configured text attributes, it does not disable them.

-Peff
Sergey Lukashev· Jan 28, 2019, 18:12 UTC · re: Jeff King · lore

Re: unclear docs

Thank you. Does the paragraph about core.eol refers to the text attribute? It's written 'property' there. I was thinking it means whether git thinks file is text, using .gitattributes OR otherwise. Maybe changing this word will make it clearer?
28.01.2019, 19:09, "Jeff King" <peff@peff.net>:
Show 21 quoted lines
> On Sun, Jan 27, 2019 at 02:55:23PM +0300, Sergey Lukashev wrote:
>
>>  Well, I have two problems:
>>  1) The endings I get with core.autocrlf=false depend on whether I have
>>     * text=auto (a file was commited with LFs). At least in git 2.20.1
>
> That sounds right. The default is that Git will never touch your line
> endings (going into or out of the working tree). Turning on the
> "text=auto" attribute for everything will tell it to start doing so
> (according to core.eol, which on Windows is CRLF).
>
>>  2) If the quote holds true then autocrlf=false is actually "true" (for
>>     output conversion) on Windows by default because default core.eol
>>     is 'native', which is CRLF. I believe autocrlf=false is supposed to
>>     mean "no any conversion, input or output, read or write the repo as
>>     is".
>
> No, it only means "do not use the autocrlf feature". If you've
> separately configured text attributes, it does not disable them.
>
> -Peff
Jeff King· Jan 28, 2019, 18:31 UTC · re: Sergey Lukashev · lore

Re: unclear docs

On Mon, Jan 28, 2019 at 09:12:00PM +0300, Sergey Lukashev wrote:
> Thank you. Does the paragraph about core.eol refers to the text
> attribute? It's written 'property' there. I was thinking it means
> whether git thinks file is text, using .gitattributes OR otherwise.
> Maybe changing this word will make it clearer?

Yeah, I think the word "property" is unnecessarily confusing. Here's another patch (meant to go on top of the other).

-- >8 --
Subject: [PATCH] docs/config: clarify "text property" in core.eol

The word "property" is less clear than "attribute", which is used elsewhere in the (surprise!) gitattributes documentation. So let's use that.

While we're here, let's make the paragraph a little easier to read by de-emphasizing the "when core.autocrlf is false" bit. Putting it in the first sentence obscures the main content, and many readers won't care about autocrlf (i.e., anyone who is just following the gitattributes(7) advice, which mainly discusses "text" and "core.eol").

Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/config/core.txt | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt
index d0e6635fe0..69c73ffe30 100644
--- a/Documentation/config/core.txt
+++ b/Documentation/config/core.txt
@@ -121,11 +121,12 @@ core.quotePath::
 
 core.eol::
 	Sets the line ending type to use in the working directory for
-	files that have the `text` property set when core.autocrlf is false.
+	files that have the `text` attribute.
 	Alternatives are 'lf', 'crlf' and 'native', which uses the platform's
 	native line ending.  The default value is `native`.  See
 	linkgit:gitattributes[5] for more information on end-of-line
-	conversion.
+	conversion. Note that this value is ignored if `core.autocrlf`
+	is set to `true`.
 
 core.safecrlf::
 	If true, makes Git check if converting `CRLF` is reversible when

-- 
2.20.1.845.g57b86ca485
Torsten Bögershausen· Jan 29, 2019, 07:38 UTC · re: Jeff King · lore

Re: unclear docs

On Mon, Jan 28, 2019 at 01:31:17PM -0500, Jeff King wrote:
Show 9 quoted lines
> On Mon, Jan 28, 2019 at 09:12:00PM +0300, Sergey Lukashev wrote:
>
> > Thank you. Does the paragraph about core.eol refers to the text
> > attribute? It's written 'property' there. I was thinking it means
> > whether git thinks file is text, using .gitattributes OR otherwise.
> > Maybe changing this word will make it clearer?
>
> Yeah, I think the word "property" is unnecessarily confusing. Here's
> another patch (meant to go on top of the other).
The property was originally meant to say:
- Either the "text" attribute is set in .gitattributes
  or
- The "text=auto" attribute is set in .gitattributes and
  Git auto-detects the file as text (and not as binary).
Show 35 quoted lines
>
> -- >8 --
> Subject: [PATCH] docs/config: clarify "text property" in core.eol
>
> The word "property" is less clear than "attribute", which is used
> elsewhere in the (surprise!) gitattributes documentation. So let's use
> that.
>
> While we're here, let's make the paragraph a little easier to read by
> de-emphasizing the "when core.autocrlf is false" bit. Putting it in the
> first sentence obscures the main content, and many readers won't care
> about autocrlf (i.e., anyone who is just following the gitattributes(7)
> advice, which mainly discusses "text" and "core.eol").
>
> Signed-off-by: Jeff King <peff@peff.net>
> ---
>  Documentation/config/core.txt | 5 +++--
>  1 file changed, 3 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt
> index d0e6635fe0..69c73ffe30 100644
> --- a/Documentation/config/core.txt
> +++ b/Documentation/config/core.txt
> @@ -121,11 +121,12 @@ core.quotePath::
>
>  core.eol::
>  	Sets the line ending type to use in the working directory for
> -	files that have the `text` property set when core.autocrlf is false.
> +	files that have the `text` attribute.
>  	Alternatives are 'lf', 'crlf' and 'native', which uses the platform's
>  	native line ending.  The default value is `native`.  See
>  	linkgit:gitattributes[5] for more information on end-of-line
> -	conversion.
> +	conversion. Note that this value is ignored if `core.autocrlf`
> +	is set to `true`.
Should that be
 > +	conversion. Note that this value is ignored if `core.autocrlf`
 > +	is set to `true` or `input`.
As we look at convert.c:
static int text_eol_is_crlf(void)
{
  if (auto_crlf == AUTO_CRLF_TRUE)
    return 1;
  else if (auto_crlf == AUTO_CRLF_INPUT)
    return 0;
  if (core_eol == EOL_CRLF)
    return 1;
  if (core_eol == EOL_UNSET && EOL_NATIVE == EOL_CRLF)
    return 1;
  return 0;
}
Sergey Lukashev· Jan 29, 2019, 10:28 UTC · re: Torsten Bögershausen · lore

Re: unclear docs

This is in fact how I got it but it seems to have changed since then.
29.01.2019, 10:38, "Torsten Bögershausen" <tboegi@web.de>:
Show 7 quoted lines
>
> The property was originally meant to say:
> - Either the "text" attribute is set in .gitattributes
>   or
> - The "text=auto" attribute is set in .gitattributes and
>   Git auto-detects the file as text (and not as binary).
>
Jeff King· Jan 29, 2019, 12:40 UTC · re: Torsten Bögershausen · lore

[PATCH v2 0/2] eol/autocrlf doc clarifications

On Tue, Jan 29, 2019 at 07:38:10AM +0000, Torsten Bögershausen wrote:
Show 8 quoted lines
> > Yeah, I think the word "property" is unnecessarily confusing. Here's
> > another patch (meant to go on top of the other).
> 
> The property was originally meant to say:
> - Either the "text" attribute is set in .gitattributes
>   or
> - The "text=auto" attribute is set in .gitattributes and
>   Git auto-detects the file as text (and not as binary).

Thanks, that makes it much more clear what the original was trying to say.

Show 6 quoted lines
> > +	conversion. Note that this value is ignored if `core.autocrlf`
> > +	is set to `true`.
> 
> Should that be
>  > +	conversion. Note that this value is ignored if `core.autocrlf`
>  > +	is set to `true` or `input`.
Yes (and ditto in the other patch).
Here's a re-roll of both patches addressing these issues.
  [1/2]: doc/gitattributes: clarify "autocrlf overrides eol"
  [2/2]: docs/config: clarify "text property" in core.eol
 Documentation/config/core.txt   | 7 +++++--
 Documentation/gitattributes.txt | 4 +++-
 2 files changed, 8 insertions(+), 3 deletions(-)
-Peff
Jeff King· Jan 29, 2019, 12:41 UTC · re: Jeff King · lore

[PATCH v2 1/2] doc/gitattributes: clarify "autocrlf overrides eol"

We only override core.eol with core.autocrlf when the latter is set to something besides "false". Let's make this more clear, and point the reader to the git-config definitions, which discuss this in more detail.

Noticed-by: Sergey Lukashev <lukashev.s@ya.ru>
Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/gitattributes.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index b8392fc330..ce383e97dc 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -124,7 +124,9 @@ text file is normalized, its line endings are converted to LF in the
 repository.  To control what line ending style is used in the working
 directory, use the `eol` attribute for a single file and the
 `core.eol` configuration variable for all text files.
-Note that `core.autocrlf` overrides `core.eol`
+Note that setting `core.autocrlf` to `true` or `input` overrides
+`core.eol` (see the definitions of those options in
+linkgit:git-config[1]).
 
 Set::
 

-- 
2.20.1.845.g57b86ca485
Jeff King· Jan 29, 2019, 12:41 UTC · re: Jeff King · lore

[PATCH v2 2/2] docs/config: clarify "text property" in core.eol

The word "property" is vague here. Let's spell out that we mean the path must be marked with the text attribute.

While we're here, let's make the paragraph a little easier to read by de-emphasizing the "when core.autocrlf is false" bit. Putting it in the first sentence obscures the main content, and many readers won't care about autocrlf (i.e., anyone who is just following the gitattributes(7) advice, which mainly discusses "text" and "core.eol").

Helped-by: Torsten Bögershausen <tboegi@web.de>
Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/config/core.txt | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)
diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt
index d0e6635fe0..7e9b6c8f4c 100644
--- a/Documentation/config/core.txt
+++ b/Documentation/config/core.txt
@@ -121,11 +121,14 @@ core.quotePath::
 
 core.eol::
 	Sets the line ending type to use in the working directory for
-	files that have the `text` property set when core.autocrlf is false.
+	files that are marked as text (either by having the `text`
+	attribute set, or by having `text=auto` and Git auto-detecting
+	the contents as text).
 	Alternatives are 'lf', 'crlf' and 'native', which uses the platform's
 	native line ending.  The default value is `native`.  See
 	linkgit:gitattributes[5] for more information on end-of-line
-	conversion.
+	conversion. Note that this value is ignored if `core.autocrlf`
+	is set to `true` or `input`.
 
 core.safecrlf::
 	If true, makes Git check if converting `CRLF` is reversible when

-- 
2.20.1.845.g57b86ca485
Torsten Bögershausen· Jan 28, 2019, 17:31 UTC · re: Sergey Lukashev · lore

Re: unclear docs

On Sun, Jan 27, 2019 at 02:55:23PM +0300, Sergey Lukashev wrote:
Show 17 quoted lines
> A follow up on my previous mail.
>
> Well, I have two problems:
> 1) The endings I get with core.autocrlf=false depend on whether I have * text=auto (a file was commited with LFs). At least in git 2.20.1
> 2) If the quote holds true then autocrlf=false is actually "true" (for output conversion) on Windows by default because default core.eol is 'native', which is CRLF. I believe autocrlf=false is supposed to mean "no any conversion, input or output, read or write the repo as is".
>
> 27.01.2019, 13:05, "Sergey Lukashev" <lukashev.s@ya.ru>:
> > Hello!
> >
> > Could somebody please explain what 'core.autocrlf overrides core.eol' means given that we have the following statement in core.eol docs:
> > "Sets the line ending type to use in the working directory for files that have the text property set when core.autocrlf is false".
> >
> > I would like to know which line endings I'm supposed to get in the working tree if I have core.autocrlf=false and '* text=auto' in .gitattributes on windows. I get CRLFs which is consistent with the last quote but I don't understand what 'core.autocrlf overrides core.eol' means in this case.
> >
> > Links:
> > https://git-scm.com/docs/git-config#git-config-coreeol
> > https://git-scm.com/docs/gitattributes#_checking_out_and_checking_in
Given your .gitattributes file, you will get:

core.autocrlf=false core.eol=CRLF gives CRLF core.autocrlf=false core.eol=LF gives LF core.autocrlf=false core.eol=native gives CRLF under Windows, LF everywhere else core.autocrlf=true gives CRLF (regardless of core.eol)

Does this help ?
Jeff King· Jan 28, 2019, 16:06 UTC · re: Sergey Lukashev · lore

Re: unclear docs

On Sun, Jan 27, 2019 at 12:58:58PM +0300, Sergey Lukashev wrote:
Show 10 quoted lines
> Could somebody please explain what 'core.autocrlf overrides core.eol'
> means given that we have the following statement in core.eol docs:
> "Sets the line ending type to use in the working directory for files
> that have the text property set when core.autocrlf is false".
> 
> I would like to know which line endings I'm supposed to get in the
> working tree if I have core.autocrlf=false and '* text=auto' in
> .gitattributes on windows. I get CRLFs  which is consistent with the
> last quote but I don't understand what 'core.autocrlf overrides
> core.eol' means in this case.
I think it means:
  - if core.autocrlf is false (the default), then the text attribute and
    core.eol are used
  - if core.autocrlf is true, then that overrides the whole
    attribute/eol system

This unfortunate complexity is due to historical reasons (the much-simpler autocrlf came first, and we had to maintain compatibility with it). I agree the wording in the documentation is pretty vague.

Perhaps the patch below makes it more clear (I similarly looked at the definitions of core.autocrlf and core.eol, but they make the distinction that autocrlf only matters when "true").

-- >8 --
Subject: [PATCH] doc/gitattributes: clarify "autocrlf overrides eol"

We only override core.eol with core.autocrlf when the latter is set to "true" (otherwise, core.eol would never do anything!). Let's make this more clear, and point the reader to the git-config definitions, which discuss this in more detail.

Noticed-by: Sergey Lukashev <lukashev.s@ya.ru>
Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/gitattributes.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index b8392fc330..0ce8740e44 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -124,7 +124,8 @@ text file is normalized, its line endings are converted to LF in the
 repository.  To control what line ending style is used in the working
 directory, use the `eol` attribute for a single file and the
 `core.eol` configuration variable for all text files.
-Note that `core.autocrlf` overrides `core.eol`
+Note that setting `core.autocrlf` to `true` overrides `core.eol` (see
+the definitions of those options in linkgit:git-config[1]).
 
 Set::
 

-- 
2.20.1.845.g57b86ca485
Junio C Hamano· Jan 28, 2019, 18:30 UTC · re: Jeff King · lore

Re: unclear docs

Jeff King <peff@peff.net> writes:
Show 7 quoted lines
> I think it means:
>
>   - if core.autocrlf is false (the default), then the text attribute and
>     core.eol are used
>
>   - if core.autocrlf is true, then that overrides the whole
>     attribute/eol system
I think that matches my understanding.
> Subject: [PATCH] doc/gitattributes: clarify "autocrlf overrides eol"
>
> We only override core.eol with core.autocrlf when the latter is set to
> "true" (otherwise, core.eol would never do anything!). Let's make this

I fail to understand what "otherwise..." wants to say. When core.autocrlf is not "true", core.eol would not do anything?

But I can understand what the patch text says and it matches my understanding of the overriding behaviour, so let's queue it.

Thanks.
Show 22 quoted lines
> more clear, and point the reader to the git-config definitions, which
> discuss this in more detail.
>
> Noticed-by: Sergey Lukashev <lukashev.s@ya.ru>
> Signed-off-by: Jeff King <peff@peff.net>
> ---
>  Documentation/gitattributes.txt | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
> index b8392fc330..0ce8740e44 100644
> --- a/Documentation/gitattributes.txt
> +++ b/Documentation/gitattributes.txt
> @@ -124,7 +124,8 @@ text file is normalized, its line endings are converted to LF in the
>  repository.  To control what line ending style is used in the working
>  directory, use the `eol` attribute for a single file and the
>  `core.eol` configuration variable for all text files.
> -Note that `core.autocrlf` overrides `core.eol`
> +Note that setting `core.autocrlf` to `true` overrides `core.eol` (see
> +the definitions of those options in linkgit:git-config[1]).
>  
>  Set::
Jeff King· Jan 28, 2019, 18:32 UTC · re: Junio C Hamano · lore

Re: unclear docs

On Mon, Jan 28, 2019 at 10:30:31AM -0800, Junio C Hamano wrote:
Show 19 quoted lines
> Jeff King <peff@peff.net> writes:
> 
> > I think it means:
> >
> >   - if core.autocrlf is false (the default), then the text attribute and
> >     core.eol are used
> >
> >   - if core.autocrlf is true, then that overrides the whole
> >     attribute/eol system
> 
> I think that matches my understanding.
> 
> > Subject: [PATCH] doc/gitattributes: clarify "autocrlf overrides eol"
> >
> > We only override core.eol with core.autocrlf when the latter is set to
> > "true" (otherwise, core.eol would never do anything!). Let's make this
> 
> I fail to understand what "otherwise..." wants to say.  When
> core.autocrlf is not "true", core.eol would not do anything?

I meant that if core.autocrlf overrides core.eol also when it is not set to true, then there would be no way to use core.eol, because the former must be either true or false.

I suppose one could argue that it can be "unset", though.
> But I can understand what the patch text says and it matches my
> understanding of the overriding behaviour, so let's queue it.

Thanks. I just posted a follow-up patch elsewhere in the thread. I think it makes sense to do both.

-Peff
Sergey Lukashev· Jan 28, 2019, 20:16 UTC · re: Jeff King · lore

Re: unclear docs

autocrlf can be "input" as well.
28.01.2019, 21:32, "Jeff King" <peff@peff.net>:
Show 26 quoted lines
> On Mon, Jan 28, 2019 at 10:30:31AM -0800, Junio C Hamano wrote:
>
>>  Jeff King <peff@peff.net> writes:
>>
>>  > I think it means:
>>  >
>>  > - if core.autocrlf is false (the default), then the text attribute and
>>  > core.eol are used
>>  >
>>  > - if core.autocrlf is true, then that overrides the whole
>>  > attribute/eol system
>>
>>  I think that matches my understanding.
>>
>>  > Subject: [PATCH] doc/gitattributes: clarify "autocrlf overrides eol"
>>  >
>>  > We only override core.eol with core.autocrlf when the latter is set to
>>  > "true" (otherwise, core.eol would never do anything!). Let's make this
>>
>>  I fail to understand what "otherwise..." wants to say. When
>>  core.autocrlf is not "true", core.eol would not do anything?
>
> I meant that if core.autocrlf overrides core.eol also when it is not set
> to true, then there would be no way to use core.eol, because the former
> must be either true or false.
>
Jeff King· Jan 28, 2019, 20:46 UTC · re: Sergey Lukashev · lore

Re: unclear docs

On Mon, Jan 28, 2019 at 11:16:54PM +0300, Sergey Lukashev wrote:
Show 13 quoted lines
> >>  > Subject: [PATCH] doc/gitattributes: clarify "autocrlf overrides eol"
> >>  >
> >>  > We only override core.eol with core.autocrlf when the latter is set to
> >>  > "true" (otherwise, core.eol would never do anything!). Let's make this
> >>
> >>  I fail to understand what "otherwise..." wants to say. When
> >>  core.autocrlf is not "true", core.eol would not do anything?
> >
> > I meant that if core.autocrlf overrides core.eol also when it is not set
> > to true, then there would be no way to use core.eol, because the former
> > must be either true or false.
>
> autocrlf can be "input" as well.

Ah, true. Should the documentation actually say "if core.autocrlf is not 'false'" then? I _think_ so from my reading of the code, but it would be nice to have confirmation from somebody better versed in the line-ending code than I am (+cc Torsten).

-Peff

← back to recent threads