idea to tweak wording of CRLF warning

idea to tweak wording of CRLF warning

[mark.yagnatinsky]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset="us-ascii", Size: 3053 bytes --]

If I'm on Windows and I "git add" a file with LF line endings, I get the following misleading warning:

warning: LF will be replaced by CRLF in t.txt

This makes me think something is about to happen "now" but actually the warning is about what will happen "later".
In particular, the file will be committed with LF, but git may convert to CRLF when it comes time to check out the file.
Thus, I propose to add the words "on checkout" somewhere in the warning message, to emphasize that the conversion will occur later instead of now.
E.g., "warning, LF will be replaced by CRLF on next checkout of t.txt" or something along those lines.

This suggestion was inspired by the amazingly detailed answer to my question on Stack overflow, without which I would have been badly confused:
https://stackoverflow.com/questions/67199433/git-line-endings-behavior-does-not-match-documentation


_________________________________________________________________________________________________________________________________________________________________________________________________________________________________
“This message is for information purposes only, it is not a recommendation, advice, offer or solicitation to buy or sell a product or service nor an official confirmation of any transaction. It is directed at persons who are professionals and is not intended for retail customer use. Intended for recipient only. This message is subject to the terms at: www.barclays.com/emaildisclaimer.

For important disclosures, please see: www.barclays.com/salesandtradingdisclaimer regarding market commentary from Barclays Sales and/or Trading, who are active market participants; https://www.investmentbank.barclays.com/disclosures/barclays-global-markets-disclosures.html regarding our standard terms for the Investment Bank of Barclays where we trade with you in principal-to-principal wholesale markets transactions; and in respect of Barclays Research, including disclosures relating to specific issuers, please see http://publicresearch.barclays.com.”  
_________________________________________________________________________________________________________________________________________________________________________________________________________________________________
If you are incorporated or operating in Australia, please see https://www.home.barclays/disclosures/importantapacdisclosures.html for important disclosure.
_________________________________________________________________________________________________________________________________________________________________________________________________________________________________
How we use personal information  see our privacy notice https://www.investmentbank.barclays.com/disclosures/personalinformationuse.html 
_________________________________________________________________________________________________________________________________________________________________________________________________________________________________

Re: idea to tweak wording of CRLF warning

[Torsten Bögershausen]

On Mon, Apr 26, 2021 at 05:31:53PM +0000, mark.yagnatinsky@barclays.com wrote:
> If I'm on Windows and I "git add" a file with LF line endings, I get the following misleading warning:
>
> warning: LF will be replaced by CRLF in t.txt
>
> This makes me think something is about to happen "now" but actually the warning is about what will happen "later".
> In particular, the file will be committed with LF, but git may convert to CRLF when it comes time to check out the file.
> Thus, I propose to add the words "on checkout" somewhere in the warning message, to emphasize that the conversion will occur later instead of now.
> E.g., "warning, LF will be replaced by CRLF on next checkout of t.txt" or something along those lines.
>
> This suggestion was inspired by the amazingly detailed answer to my question on Stack overflow, without which I would have been badly confused:
> https://stackoverflow.com/questions/67199433/git-line-endings-behavior-does-not-match-documentation
>

Thanks for posting here.

I think/hope that a couple of answers given on stackoverflow could have digged out from here
(or may be they where ?)

About the gitattributes:
https://git-scm.com/docs/gitattributes

Out of curiosity, please allow a question:
Is that material too hard to understand, or too hard do find ?
Or does it take too much time to read ?

Back to the confusing message.
It is confusing even to me.

... I like that message suggestion. You might consider offering it to the Git mailing list as a patch to Git ...

It may be, that someone sends a patch.
However, as a very first step: "or something along those lines." needs to be defined.

Which short text would have explained the whole story better ?

The attributes with "* text=auto" means different things:
Files with CRLF in the working tree will get LF in the index,
when they are commited/added.

git checkout t.txt (which has LF) in your scenario
will not checkout the file with CRLF rigth now.
It is is not changed in the index.

A checkout will only change the working tree if you checkout t.txt with
different content - checkout a different branch, switch to a tag,
or checkout a commit id.

Or if you delete it in the working tree, and check it out again.

In that sense: Suggestions (the complete new text) of the warning message
are welcome.

RE: idea to tweak wording of CRLF warning

[mark.yagnatinsky]

> Is that material too hard to understand, or too hard to find?
> Or does it take too much time to read?

Easy enough to find; first place I looked.
Too hard to connect the stuff I was reading to the error message I was getting.
I saw things like "git will normalize CRLF to LF", while git itself seems to be warning me that it will normalize in the exact opposite direction, when I'm already committing LF.

> However, as a very first step: "or something along those lines." needs to be defined.
> Which short text would have explained the whole story better?

If the goal here is merely to explain the whole story "better", that is easy.
Add the words "on checkout" somewhere near the end of the existing error message.

> git checkout t.txt (which has LF) in your scenario will not checkout the file with CRLF rigth now.
This shows that "better" is not the same as "perfect".
My suggestion is indeed a bit misleading in that department.
But I think it is less misleading than the current wording.
It doesn't take the user all the way to the final destination, but does point them in the right direction.
The current wording pointed me in the wrong direction.
I think, but obviously can't prove, that if the words "later" or "at checkout" had been in the
error message, it would have been clear enough that I would have eventually figured out what's going
on without having to ask on stack overflow.

> In that sense: Suggestions (the complete new text) of the warning message are welcome.
Okay this is actually kind of hard, since there's a tension between being concise and being precise, or at least not lying too much.

Something like this might be a bit too verbose, but tells only one white lie ("will be converted" should really be "will be converted unless your git settings (git config plus git attributes) change by then"):

warning: t.txt will be committed with LF line endings, but will be converted to CRLF in your working directory the next time this file needs to be checked out.
Until then, it will have keep its LF line endings in your working directory.

Alternatively, here's a less drastic change that's more concise but perhaps still "hand-holdy" enough:

warning: LF will be replaced by CRLF in t.txt the next time this file is checked out.
Until then, it will have keep its LF line endings in your working directory.

I could come up with more variations on this theme but I think you see what I'm trying to gesture at.

Thoughts?
_________________________________________________________________________________________________________________________________________________________________________________________________________________________________
“This message is for information purposes only, it is not a recommendation, advice, offer or solicitation to buy or sell a product or service nor an official confirmation of any transaction. It is directed at persons who are professionals and is not intended for retail customer use. Intended for recipient only. This message is subject to the terms at: www.barclays.com/emaildisclaimer.

For important disclosures, please see: www.barclays.com/salesandtradingdisclaimer regarding market commentary from Barclays Sales and/or Trading, who are active market participants; https://www.investmentbank.barclays.com/disclosures/barclays-global-markets-disclosures.html regarding our standard terms for the Investment Bank of Barclays where we trade with you in principal-to-principal wholesale markets transactions; and in respect of Barclays Research, including disclosures relating to specific issuers, please see http://publicresearch.barclays.com.”  
_________________________________________________________________________________________________________________________________________________________________________________________________________________________________
If you are incorporated or operating in Australia, please see https://www.home.barclays/disclosures/importantapacdisclosures.html for important disclosure.
_________________________________________________________________________________________________________________________________________________________________________________________________________________________________
How we use personal information  see our privacy notice https://www.investmentbank.barclays.com/disclosures/personalinformationuse.html 
_________________________________________________________________________________________________________________________________________________________________________________________________________________________________