mirrors/git
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge branch 'ah/doc-attributes-text'

Browse Source 
Doc update to clarify how text and eol attributes interact to
specify the end-of-line conversion.

* ah/doc-attributes-text:
  docs: rewrite the documentation of the text and eol attributes
This commit is contained in:
Junio C Hamano
2023-05-10 10:23:28 -07:00
parent 7f3cc51b28 6696077ace
commit c05615e1c5
1 changed files with 31 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
Documentation/gitattributes.txt
View File

@ -120,20 +120,19 @@ repository upon 'git add' and 'git commit'.
`text` `text`
^^^^^^ ^^^^^^
This attribute enables and controls end-of-line normalization. When a This attribute marks the path as a text file, which enables end-of-line
text file is normalized, its line endings are converted to LF in the conversion: When a matching file is added to the index, the file's line
repository. To control what line ending style is used in the working endings are normalized to LF in the index. Conversely, when the file is
directory, use the `eol` attribute for a single file and the copied from the index to the working directory, its line endings may be
`core.eol` configuration variable for all text files. converted from LF to CRLF depending on the `eol` attribute, the Git
Note that setting `core.autocrlf` to `true` or `input` overrides config, and the platform (see explanation of `eol` below).
`core.eol` (see the definitions of those options in
linkgit:git-config[1]).
Set:: Set::
Setting the `text` attribute on a path enables end-of-line Setting the `text` attribute on a path enables end-of-line
normalization and marks the path as a text file. End-of-line conversion on checkin and checkout as described above. Line endings
conversion takes place without guessing the content type. 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:: Unset::
@ -142,10 +141,11 @@ Unset::
Set to string value "auto":: Set to string value "auto"::
When `text` is set to "auto", the path is marked for automatic When `text` is set to "auto", Git decides by itself whether the file
end-of-line conversion. If Git decides that the content is is text or binary. If it is text and the file was not already in
text, its line endings are converted to LF on checkin. Git with CRLF endings, line endings are converted on checkin and
When the file has been committed with CRLF, no conversion is done. checkout as described above. Otherwise, no conversion is done on
checkin or checkout.
Unspecified:: Unspecified::
@ -159,26 +159,29 @@ unspecified.
`eol` `eol`
^^^^^ ^^^^^
This attribute sets a specific line-ending style to be used in the This attribute marks a path to use a specific line-ending style in the
working directory. This attribute has effect only if the `text` working tree when it is checked out. It has effect only if `text` or
attribute is set or unspecified, or if it is set to `auto`, the file is `text=auto` is set (see above), but specifying `eol` automatically sets
detected as text, and it is stored with LF endings in the index. Note `text` if `text` was left unspecified.
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.
Set to string value "crlf":: Set to string value "crlf"::
This setting forces Git to normalize line endings for this This setting converts the file's line endings in the working
file on checkin and convert them to CRLF when the file is directory to CRLF when the file is checked out.
checked out.
Set to string value "lf":: Set to string value "lf"::
This setting forces Git to normalize line endings to LF on This setting uses the same line endings in the working directory as
checkin and prevents conversion to CRLF when the file is in the index when the file is checked out.
checked out.
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]). 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 Backwards compatibility with `crlf` attribute
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^