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 <tboegi@xxxxxx>
Signed-off-by: Alex Henrie <alexhenrie24@xxxxxxxxx>
## 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::
+
--
2.40.1
