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

Message

Alex Henrie May 1, 2023, 2:35 a.m. UTC

Changes from v2:
- Correct incorrect statement in commit message about dependence of
  `eol` on `text`
- Use "normalize" to refer to conversion to LF, and "convert" for
  conversion from LF
- Add Helped-by line
- Reduce wordiness/redundancy
- Add Junio's suggested phrasing to introduce `eol`

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

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

Range-diff against v2:
1:  446fb632a5 ! 1:  3d5985bc28 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 force normalization on checkin and checkout
    -    all by itself, but eol doesn't control normalization on checkin and
    -    doesn't control normalization on checkout either unless accompanied by
    -    the text attribute.
    +    attribute sounds like it can turn on normalization on checkin, but eol
    +    only controls conversion on checkout. 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.
     
         Rephrase the documentation of text, text=auto, eol, eol=crlf, and eol=lf
         to be clear about how they are the same, how they are different, and in
    -    what cases normalization is performed.
    +    what cases conversion is performed.
     
    +    Helped-by: Torsten Bögershausen <[e-mail]>
         Signed-off-by: Alex Henrie <[e-mail]>
     
      ## Documentation/gitattributes.txt ##
     @@ Documentation/gitattributes.txt: repository upon 'git add' and 'git commit'.
    @@ Documentation/gitattributes.txt: repository upon 'git add' and 'git commit'.
     -`core.eol` (see the definitions of those options in
     -linkgit:git-config[1]).
     +This attribute marks the path as a text file, which enables end-of-line
    -+normalization on checkin and possibly also checkout: When a matching
    -+file is added to the index, even if it has CRLF line endings in the
    -+working directory, the file is stored in the index with LF line endings.
    -+Conversely, when the file is copied from the index to the working
    -+directory, its line endings may be converted from LF to CRLF depending
    -+on the `eol` attribute, the Git config, and the platform (see
    -+explanation of `eol` below).
    ++conversion: When a matching file is added to the index, the file's line
    ++endings are normalized to LF in the index.  Conversely, when the file is
    ++copied from the index to the working directory, its line endings may be
    ++converted from LF to CRLF depending on the `eol` attribute, the Git
    ++config, and the platform (see explanation of `eol` below).
      
      Set::
      
      	Setting the `text` attribute on a path enables end-of-line
     -	normalization and marks the path as a text file.  End-of-line
     -	conversion takes place without guessing the content type.
    -+	normalization on checkin and checkout as described above.  Line
    -+	endings are normalized in the index the next time the file is
    -+	checked in, even if the file was previously added to Git with CRLF
    -+	line endings.
    ++	conversion on checkin and checkout as described above.  Line endings
    ++	are normalized to LF in the index every time the file is checked in,
    ++	even if the file was previously added to Git with CRLF line endings.
      
      Unset::
      
    @@ Documentation/gitattributes.txt: Unset::
      Unspecified::
      
     @@ Documentation/gitattributes.txt: unspecified.
    - This attribute sets a specific line-ending style to be used in the
    - working directory.  This attribute has effect only if the `text`
    - attribute is set or unspecified, or if it is set to `auto`, the file is
    + `eol`
    + ^^^^^
    + 
    +-This attribute sets a specific line-ending style to be used in the
    +-working directory.  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.  Note
     -that setting this attribute on paths which are in the index with CRLF
     -line endings may make the paths to be considered dirty unless
     -`text=auto` is set. Adding the path to the index again will normalize
     -the line endings in the index.
    -+detected as text, and it is stored with LF 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.
      
      Set to string value "crlf"::
      
    @@ Documentation/gitattributes.txt: unspecified.
     -	checkin and prevents conversion to CRLF when the file is
     -	checked out.
     +	This setting uses the same line endings in the working directory as
    -+	in the index, whether they are LF or CRLF.  However, unless
    -+	`text=auto`, adding the file to the index again will normalize its
    -+	line endings to LF in the index.
    ++	in the index when the file is checked out.
     +
     +Unspecified::
     +