Re: unclear docs

[Jeff King <peff@peff.net>]

On Sun, Jan 27, 2019 at 12:58:58PM +0300, Sergey Lukashev wrote:

> 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