'eol' documentation confusion

'eol' documentation confusion

[Robert Dailey]

Upon inspection of the gitattributes documentation page here:
https://git-scm.com/docs/gitattributes

When comparing the documentation for 'text' with 'eol', I see the
following missing explanations for 'eol':

* eol
* -eol

Maybe the fact that these are missing means they are not valid to use.
There is also the issue that `text` usually controls EOL anyway. Is
there ever any reason to set eol in a way differently than explained
in the documentation (that is, `eol=lf` or `eol=crlf`)?

For example, what if you want a file to be treated as text BUT you do
not want it to perform EOL normalization at all. Could you do this?

    foo.txt text -eol

Just at first glance, this to me would mean line endings on checkin
and checkout are not touched (CRLF could be checked in). Is this
possible?

What about setting `eol` but not `text`?

Honestly it seems like `eol` is just a supplementary setting for
`text` and was never intended to be used in ways that are
undocumented. Some explanation to help uncloud this would help, or
maybe I missed something in the documentation that explains this.

Re: 'eol' documentation confusion

[Robert Dailey]

On Sun, Jun 21, 2015 at 9:04 AM, Robert Dailey <rcdailey.lists@gmail.com> wrote:
> Upon inspection of the gitattributes documentation page here:
> https://git-scm.com/docs/gitattributes
>
> When comparing the documentation for 'text' with 'eol', I see the
> following missing explanations for 'eol':
>
> * eol
> * -eol
>
> Maybe the fact that these are missing means they are not valid to use.
> There is also the issue that `text` usually controls EOL anyway. Is
> there ever any reason to set eol in a way differently than explained
> in the documentation (that is, `eol=lf` or `eol=crlf`)?
>
> For example, what if you want a file to be treated as text BUT you do
> not want it to perform EOL normalization at all. Could you do this?
>
>     foo.txt text -eol
>
> Just at first glance, this to me would mean line endings on checkin
> and checkout are not touched (CRLF could be checked in). Is this
> possible?
>
> What about setting `eol` but not `text`?
>
> Honestly it seems like `eol` is just a supplementary setting for
> `text` and was never intended to be used in ways that are
> undocumented. Some explanation to help uncloud this would help, or
> maybe I missed something in the documentation that explains this.

I did a few tests out of curiosity:

    * eol

This allowed CRLF to be committed in a file named `foo.txt` (I saw ^M
in the diff, which I think means CR character, and treats this
character as an error)

    * text=auto eol

This did not differ in behavior from `* text=auto` from what I could
see. It removed CR characters in the repository on check in.

    * text=auto -eol

Same as before, the addition of `-eol` did not change the behavior at all.

So yeah, I'm still horribly confused. None of these scenarios make any
sense. The only time I ever set `eol` explicitly is to either do
`eol=lf` or `eol=crlf`.

Re: 'eol' documentation confusion

[Torsten Bögershausen]

On 06/21/2015 04:16 PM, Robert Dailey wrote:
> On Sun, Jun 21, 2015 at 9:04 AM, Robert Dailey <rcdailey.lists@gmail.com> wrote:
>> Upon inspection of the gitattributes documentation page here:
>> https://git-scm.com/docs/gitattributes
>>
>> When comparing the documentation for 'text' with 'eol', I see the
>> following missing explanations for 'eol':
>>
>> * eol
>> * -eol
>>
>> Maybe the fact that these are missing means they are not valid to use.
>> There is also the issue that `text` usually controls EOL anyway. Is
>> there ever any reason to set eol in a way differently than explained
>> in the documentation (that is, `eol=lf` or `eol=crlf`)?
No.
eol=lf or eol=crlf are the only useful settings.
Everything else is ignored because it does not make sense.

See convert.c:
static enum eol git_path_check_eol()

Re: 'eol' documentation confusion

[Junio C Hamano]

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

> eol=lf or eol=crlf are the only useful settings.
> Everything else is ignored because it does not make sense.
>
> See convert.c:
> static enum eol git_path_check_eol()

That makes me wonder...

The original reasoning behind the current behaviour that we ignore
unknown values given to configuration variables and attributes is so
that people can use the same file that has values that are
understood by newer versions of Git with older versions of Git.

You may be trying the eol=cleverLF setting introduced in Git version
47-prerelease by adding it to .git/info/attributes, and may have
found it useful.  But you may also have to use the same repository
on another machine that you didn't install that future version of
Git over the network filesystem.  Barfing and not proceeding when we
see unknown eol=cleverLF does not sound like a nice thing to do,
which is why we just ignore and behave as if the setting was not
there.

Ideally, however, I think we should ignore an unknown setting as
long as it does not matter (i.e. we do not come to the codepath that
wants to know eol settings for the path, e.g. running "git log" to
show only the commit log messages and the topology of the history),
but we should error out when the unknown setting possibly matters
(i.e. we do need the eol setting for the path in order to correctly
convert the contents to end-user's liking).

Thoughts (and patches ;-)?

Re: 'eol' documentation confusion

[Torsten Bögershausen]

On 2015-06-22 18.11, Junio C Hamano wrote:
> Torsten Bögershausen <tboegi@web.de> writes:
> 
>> eol=lf or eol=crlf are the only useful settings.
>> Everything else is ignored because it does not make sense.
>>
>> See convert.c:
>> static enum eol git_path_check_eol()
> 
> That makes me wonder...
> 
> The original reasoning behind the current behaviour that we ignore
> unknown values given to configuration variables and attributes is so
> that people can use the same file that has values that are
> understood by newer versions of Git with older versions of Git.
> 
> You may be trying the eol=cleverLF setting introduced in Git version
> 47-prerelease by adding it to .git/info/attributes, and may have
> found it useful.  But you may also have to use the same repository
> on another machine that you didn't install that future version of
> Git over the network filesystem.  Barfing and not proceeding when we
> see unknown eol=cleverLF does not sound like a nice thing to do,
> which is why we just ignore and behave as if the setting was not
> there.
> 
> Ideally, however, I think we should ignore an unknown setting as
> long as it does not matter (i.e. we do not come to the codepath that
> wants to know eol settings for the path, e.g. running "git log" to
> show only the commit log messages and the topology of the history),
> but we should error out when the unknown setting possibly matters
> (i.e. we do need the eol setting for the path in order to correctly
> convert the contents to end-user's liking).
> 
> Thoughts (and patches ;-)?
In short:
Good idea, patches follow within the next weeks/months