Subject: RE: suggestion for improved docs on autocrlf

From: "Yagnatinsky, Mark" <[email-masked]>
Date: Thu, 15 Aug 2019 04:56:05 +0000

Okay, first attempt at better phrasing.  This may need more paragraph breaks, or something.
Right now it's very wall-of-texty.  And probably in a style way too different from the rest of the git docs.
Also, the syntax is probably closer to markdown than AsciiDoc; sorry.
Anyway, enough disclaimers, here's the first draft:

This variable has three valid settings: true, input, and false.
(Leaving it unset is equivalent to setting it to "false".)
1. Set it to "true" if you want to have CRLF line endings in your 
working directory and the repository has LF line endings. 
Setting it to true is the same as setting the `text` attribute to
"auto" on all files and core.eol to "crlf".  In other words: any file
that has LF line endings in the repository will have CRLF line
endings in your working directory.  If you  commit a new file to
the repository, then git will commit it with LF line endings, even
if it has CRLF endings in your working  directory.  However, if you
edit an existing file that has CRLF line endings in the repository,
then git will not convert it to LF line endings when you commit it.

2. If you set it to "input" then git will not do any line ending conversions
when checking files out of the repository into your working directory.
That is, immediately after a checkout, the line endings in your working
directory will match those in the repository.  When committing a new
file to the repository, git will commit it with LF line endings, even if it has
CRLF line endings in your working directory.  If you edit an existing file in
the repository, then:
        * If the file had LF line endings in the repository, it will still have them,
            no matter what line endings are in the working directory.
        * If the file has LF line endings in the working directory, then it will be
            committed with LF line endings , no matter what line endings it used
            to have in the repository.
If neither of the above two cases apply, (in other words, if the file has CRLF
endings in the repository and in also in the working directory), then it will be
committed with CRLF line endings.

3. The simplest setting to explain is "false".  In this setting, git will not
perform any line ending conversion; all files will be checked out into
the working directory exactly as they are in the repo, and will be
committed to the repo exactly as they are in the working directory.
This setting is recommended; if you are tempted to use "input" or "true"
instead of "false", then consider looking into committing a .gitattributes file
into your repository instead.  Settings in that file override this configuration
variable, and since the same attributes file is being used by everyone who
works on the repo, the results end up being more predictable.

Or something like that.

----------------------------------------------------------------------
This message, and any attachments, is for the intended recipient(s) only, may contain information that is privileged, confidential and/or proprietary and subject to important terms and conditions available at http://www.bankofamerica.com/emaildisclaimer.   If you are not the intended recipient, please delete this message.