Explanation of `eol` attribute doesn't seem correct for Windows machines

Explanation of `eol` attribute doesn't seem correct for Windows machines

[Hans Meiser]

https://git-scm.com/docs/gitattributes#_eol

claims that:

---
Set to string value "crlf"

    This setting converts the file’s line endings in the working directory to CRLF when the file is checked out.
Set to string value "lf"

    This setting uses the same line endings in the working directory as in the index when the file is checked out.
---

I don't think this explanation is sufficient for files stored on Windows machines. A file might be stored with CRLF in the index. What happens then? And what happens when a file is added to the index with `core.autocrlf=input` on Windows machines?

Re: Explanation of `eol` attribute doesn't seem correct for Windows machines

[Torsten Bögershausen]

On Mon, Nov 06, 2023 at 03:11:54PM +0000, Hans Meiser wrote:
> https://git-scm.com/docs/gitattributes#_eol
>
> claims that:
>
> ---
> Set to string value "crlf"
>
>     This setting converts the file’s line endings in the working directory to CRLF when the file is checked out.
> Set to string value "lf"
>
>     This setting uses the same line endings in the working directory as in the index when the file is checked out.
> ---
>
> I don't think this explanation is sufficient for files stored on Windows machines.
> A file might be stored with CRLF in the index.
> What happens then?

  >This setting uses the same line endings in the working directory
  >as in the index when the file is checked out.
  If you have a file commited with CRLF into the index, it will have CRLF in the working tree.
  If the file had been commited with LF into the index, it will have LF in the working tree.
  That is what the documentation tries to say, I think.

However, the above discussion is only valid, when the "text" attribute is defined.
Otherwise the eol attribute has no effect.
So you need something like
* text=auto
and/or
*.txt text
in your .gitattributes file


> And what happens when a file is added to the index with `core.autocrlf=input` on Windows machines?
Do you have a .gitattributes file ? Or not ?
Is the file a new one, or does it exist ?

In any way,
git ls-files --eol
may help to find out, what is in the index and what is in the workingtree.

Re: Explanation of `eol` attribute doesn't seem correct for Windows machines

[Hans Meiser]

> > And what happens when a file is added to the index with `core.autocrlf=input` on Windows machines?
> Do you have a .gitattributes file ? Or not ?
> Is the file a new one, or does it exist ?

Exactly all these questions/cases should be explained by the documentation, I suppose.

-------
From: Torsten Bögershausen <tboegi@web.de>
Sent: Monday, November 6, 2023 17:21
To: Hans Meiser <brille1@hotmail.com>
Cc: git@vger.kernel.org <git@vger.kernel.org>
Subject: Re: Explanation of `eol` attribute doesn't seem correct for Windows machines 
 
On Mon, Nov 06, 2023 at 03:11:54PM +0000, Hans Meiser wrote:
> https://git-scm.com/docs/gitattributes#_eol
>
> claims that:
>
> ---
> Set to string value "crlf"
>
>     This setting converts the file’s line endings in the working directory to CRLF when the file is checked out.
> Set to string value "lf"
>
>     This setting uses the same line endings in the working directory as in the index when the file is checked out.
> ---
>
> I don't think this explanation is sufficient for files stored on Windows machines.
> A file might be stored with CRLF in the index.
> What happens then?

  >This setting uses the same line endings in the working directory
  >as in the index when the file is checked out.
  If you have a file commited with CRLF into the index, it will have CRLF in the working tree.
  If the file had been commited with LF into the index, it will have LF in the working tree.
  That is what the documentation tries to say, I think.

However, the above discussion is only valid, when the "text" attribute is defined.
Otherwise the eol attribute has no effect.
So you need something like
* text=auto
and/or
*.txt text
in your .gitattributes file


> And what happens when a file is added to the index with `core.autocrlf=input` on Windows machines?
Do you have a .gitattributes file ? Or not ?
Is the file a new one, or does it exist ?

In any way,
git ls-files --eol
may help to find out, what is in the index and what is in the workingtree.

Re: Explanation of `eol` attribute doesn't seem correct for Windows machines

[Torsten Bögershausen]

On Tue, Nov 07, 2023 at 12:23:29AM +0000, Hans Meiser wrote:
> > > And what happens when a file is added to the index with `core.autocrlf=input` on Windows machines?
> > Do you have a .gitattributes file ? Or not ?
> > Is the file a new one, or does it exist ?
>
> Exactly all these questions/cases should be explained by the documentation, I suppose.

In general, the CRLF - LF ("line endings") conversion is defined by
different settings.

The .gitattributes file (which is typically added to the repo and commited,
so that it travels trough into all repos by using `git clone`, `git pull`
or `git fetch` followed by a `git checkout`

This link
https://git-scm.com/docs/gitattributes#_text
should describe everything you may want to know about
.gitattributes
to handle line endings.
If I say "should" then this is from a perspective of someone who has read and used this
too often to see with fresh eyes what may be missing.