[v4,0/1] docs: rewrite the documentation of the text and eol attributes

Message

Alex Henrie May 3, 2023, 4:46 a.m. UTC

Changes from v3:
- Rewrite sentence about how `eol` can imply `text`
- Use the phrase "all other platforms" instead of the word "Unix"

Alex Henrie (1):
  docs: rewrite the documentation of the text and eol attributes

 Documentation/gitattributes.txt | 59 +++++++++++++++++----------------
 1 file changed, 31 insertions(+), 28 deletions(-)

Range-diff against v3:
1:  3d5985bc28 ! 1:  eccf627db1 docs: rewrite the documentation of the text and eol attributes
    @@ Commit message
         does not do anything to the line endings either.
     
         On top of that, in several places the documentation for the eol
    -    attribute sounds like it can turn on normalization on checkin, but eol
    -    only controls conversion on checkout. It also sounds like setting eol
    +    attribute sounds like either it does not affect normalization on checkin
    +    or it forces normalization on checkin. It also sounds like setting eol
         (or setting a config variable) is required to turn on conversion on
         checkout, but the text attribute can turn on conversion on checkout by
         itself if eol is unspecified.
    @@ Documentation/gitattributes.txt: unspecified.
     -`text=auto` is set. Adding the path to the index again will normalize
     -the line endings in the index.
     +This attribute marks a path to use a specific line-ending style in the
    -+working tree when it is checked out.  This attribute has effect only if
    -+the `text` attribute is set or unspecified, or if it is set to `auto`,
    -+the file is detected as text, and it is stored with LF endings in the
    -+index.
    ++working tree when it is checked out.  It has effect only if `text` or
    ++`text=auto` is set (see above), but specifying `eol` automatically sets
    ++`text` if `text` was left unspecified.
      
      Set to string value "crlf"::
      
    @@ Documentation/gitattributes.txt: unspecified.
     +	If the `eol` attribute is unspecified for a file, its line endings
     +	in the working directory are determined by the `core.autocrlf` or
     +	`core.eol` configuration variable (see the definitions of those
    -+	options in linkgit:git-config[1]).  The default if `text` is set but
    -+	neither of those variables is is `eol=lf` on Unix and `eol=crlf` on
    -+	Windows.
    ++	options in linkgit:git-config[1]).  If `text` is set but neither of
    ++	those variables is, the default is `eol=crlf` on Windows and
    ++	`eol=lf` on all other platforms.
      
      Backwards compatibility with `crlf` attribute
      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^