diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/config.txt | 4 | ||||
| -rw-r--r-- | Documentation/gitattributes.txt | 138 |
2 files changed, 115 insertions, 27 deletions
diff --git a/Documentation/config.txt b/Documentation/config.txt index 4c36aa95b7..c6cc7abe3e 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -203,8 +203,8 @@ core.autocrlf:: based on the file's contents. See linkgit:gitattributes[5]. core.safecrlf:: - If true, makes git check if converting `CRLF` as controlled by - `core.autocrlf` is reversible. Git will verify if a command + If true, makes git check if converting `CRLF` is reversible when + end-of-line conversion is active. Git will verify if a command modifies a file in the work tree either directly or indirectly. For example, committing a file followed by checking out the same file should yield the original file in the work tree. If diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index b396a871b3..f621b23b84 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -95,50 +95,138 @@ repository upon 'git add' and 'git commit'. `crlf` ^^^^^^ -This attribute controls the line-ending convention. +This attribute enables and controls end-of-line normalization. When a +text file is normalized, its line endings are converted to LF in the +repository. To control what line ending style is used in the working +directory, use the `eol` attribute for a single file and the +`core.autocrlf` configuration variable for all text files. Set:: - Setting the `crlf` attribute on a path is meant to mark - the path as a "text" file. 'core.autocrlf' conversion - takes place without guessing the content type by - inspection. + Setting the `crlf` 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. Unset:: Unsetting the `crlf` attribute on a path tells git not to attempt any end-of-line conversion upon checkin or checkout. +Set to string value "auto":: + + When `crlf` is set to "auto", the path is marked for automatic + end-of-line normalization. If git decides that the content is + text, its line endings are normalized to LF on checkin. + Unspecified:: - Unspecified `crlf` attribute tells git to apply the - `core.autocrlf` conversion when the file content looks - like text. + If the `crlf` attribute is unspecified, git uses the `eol` + attribute and the `core.autocrlf` configuration variable to + determine if the file should be converted. -Set to string value "input":: +Any other value causes git to act as if `crlf` has been left +unspecified. - This is similar to setting the attribute to `true`, but - also forces git to act as if `core.autocrlf` is set to - `input` for the path. +`eol` +^^^^^ -Any other value set to `crlf` attribute is ignored and git acts -as if the attribute is left unspecified. +This attribute sets a specific line-ending style to be used in the +working directory. It enables end-of-line normalization without any +content checks, similar to setting the `crlf` attribute. +Set to string value "crlf":: -The `core.autocrlf` conversion -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + This setting forces git to normalize line endings on checkin + and convert them to CRLF when the file is checked out, + regardless of `crlf` and `core.autocrlf`. + +Set to string value "lf":: + + This setting forces git to normalize line endings to LF on + checkin and prevents conversion to CRLF when the file is + checked out, regardless of `crlf` and `core.autocrlf`. + `crlf=input` is a backwards compatibility alias for `eol=lf`. + +End-of-line conversion +^^^^^^^^^^^^^^^^^^^^^^ + +While git normally leaves file contents alone, it can be configured to +normalize line endings to LF in the repository and, optionally, to +convert them to CRLF when files are checked out. + +Here is an example that will make git normalize .txt, .vcproj and .sh +files, ensure that .vcproj files have CRLF and .sh files have LF in +the working directory, and prevent .jpg files from being normalized +regardless of their content. + +------------------------ +*.txt crlf +*.vcproj eol=crlf +*.sh eol=lf +*.jpg -crlf +------------------------ + +Other source code management systems normalize all text files in their +repositories, and there are two ways to enable similar automatic +normalization in git. + +If you simply want to have CRLF line endings in your working directory +regardless of the repository you are working with, you can set the +config variable "core.autocrlf" without changing any attributes. + +------------------------ +[core] + autocrlf = true +------------------------ + +This does not force normalization of all text files, but does ensure +that text files that you introduce to the repository have their line +endings normalized to LF when they are added, and that files that are +already normalized in the repository stay normalized. You can also +set `autocrlf` to "input" to have automatic normalization of new text +files without conversion to CRLF in the working directory. + +If you want to interoperate with a source code management system that +enforces end-of-line normalization, or you simply want all text files +in your repository to be normalized, you should instead set the `crlf` +attribute to "auto" for _all_ files. + +------------------------ +* crlf=auto +------------------------ + +This ensures that all files that git considers to be text will have +normalized (LF) line endings in the repository. -If the configuration variable `core.autocrlf` is false, no -conversion is done. +NOTE: When `crlf=auto` normalization is enabled in an existing +repository, any text files containing CRLFs should be normalized. If +they are not they will be normalized the next time someone tries to +change them, causing unfortunate misattribution. From a clean working +directory: -When `core.autocrlf` is true, it means that the platform wants -CRLF line endings for files in the working tree, and you want to -convert them back to the normal LF line endings when checking -in to the repository. +------------------------------------------------- +$ echo "* crlf=auto" >>.gitattributes +$ rm .git/index # Remove the index to force git to +$ git reset # re-scan the working directory +$ git status # Show files that will be normalized +$ git add -u +$ git add .gitattributes +$ git commit -m "Introduce end-of-line normalization" +------------------------------------------------- -When `core.autocrlf` is set to "input", line endings are -converted to LF upon checkin, but there is no conversion done -upon checkout. +If any files that should not be normalized show up in 'git status', +unset their `crlf` attribute before running 'git add -u'. + +------------------------ +manual.pdf -crlf +------------------------ + +Conversely, text files that git does not detect can have normalization +enabled manually. + +------------------------ +weirdchars.txt crlf +------------------------ If `core.safecrlf` is set to "true" or "warn", git verifies if the conversion is reversible for the current setting of |