From fd6cce9e89ab5ac1125a3b5f5611048ad22379e7 Mon Sep 17 00:00:00 2001 From: Eyvind Bernhardsen Date: Wed, 19 May 2010 22:43:10 +0200 Subject: Add per-repository eol normalization Change the semantics of the "crlf" attribute so that it enables end-of-line normalization when it is set, regardless of "core.autocrlf". Add a new setting for "crlf": "auto", which enables end-of-line conversion but does not override the automatic text file detection. Add a new attribute "eol" with possible values "crlf" and "lf". When set, this attribute enables normalization and forces git to use CRLF or LF line endings in the working directory, respectively. The line ending style to be used for normalized text files in the working directory is set using "core.autocrlf". When it is set to "true", CRLFs are used in the working directory; when set to "input" or "false", LFs are used. Signed-off-by: Eyvind Bernhardsen Signed-off-by: Junio C Hamano --- Documentation/gitattributes.txt | 138 ++++++++++++++++++++++++++++++++-------- 1 file changed, 113 insertions(+), 25 deletions(-) (limited to 'Documentation/gitattributes.txt') 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 -- cgit v1.2.3 From 5ec3e67052289217c84e53d2cda90d939ac5725b Mon Sep 17 00:00:00 2001 From: Eyvind Bernhardsen Date: Wed, 19 May 2010 22:43:11 +0200 Subject: Rename the "crlf" attribute "text" As discussed on the list, "crlf" is not an optimal name. Linus suggested "text", which is much better. Signed-off-by: Eyvind Bernhardsen Signed-off-by: Junio C Hamano --- Documentation/gitattributes.txt | 59 ++++++++++++++++++++++++----------------- 1 file changed, 35 insertions(+), 24 deletions(-) (limited to 'Documentation/gitattributes.txt') diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index f621b23b84..1120b90a58 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -92,7 +92,7 @@ such as 'git checkout' and 'git merge' run. They also affect how git stores the contents you prepare in the working tree in the repository upon 'git add' and 'git commit'. -`crlf` +`text` ^^^^^^ This attribute enables and controls end-of-line normalization. When a @@ -103,28 +103,28 @@ directory, use the `eol` attribute for a single file and the Set:: - Setting the `crlf` 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 takes place without guessing the content type. Unset:: - Unsetting the `crlf` attribute on a path tells git not to + Unsetting the `text` 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 + When `text` 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:: - If the `crlf` attribute is unspecified, git uses the `eol` + If the `text` attribute is unspecified, git uses the `eol` attribute and the `core.autocrlf` configuration variable to determine if the file should be converted. -Any other value causes git to act as if `crlf` has been left +Any other value causes git to act as if `text` has been left unspecified. `eol` @@ -132,20 +132,31 @@ 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. +content checks, similar to setting the `text` attribute. Set to string value "crlf":: 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`. + regardless of `text` 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`. + checked out, regardless of `text` and `core.autocrlf`. + +Backwards compatibility with `crlf` attribute +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For backwards compatibility, the `crlf` attribute is interpreted as +follows: + +------------------------ +crlf text +-crlf -text +crlf=input eol=lf +------------------------ End-of-line conversion ^^^^^^^^^^^^^^^^^^^^^^ @@ -160,10 +171,10 @@ the working directory, and prevent .jpg files from being normalized regardless of their content. ------------------------ -*.txt crlf +*.txt text *.vcproj eol=crlf *.sh eol=lf -*.jpg -crlf +*.jpg -text ------------------------ Other source code management systems normalize all text files in their @@ -188,24 +199,24 @@ 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` +in your repository to be normalized, you should instead set the `text` attribute to "auto" for _all_ files. ------------------------ -* crlf=auto +* text=auto ------------------------ This ensures that all files that git considers to be text will have normalized (LF) line endings in the repository. -NOTE: When `crlf=auto` normalization is enabled in an existing +NOTE: When `text=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: ------------------------------------------------- -$ echo "* crlf=auto" >>.gitattributes +$ echo "* text=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 @@ -215,17 +226,17 @@ $ git commit -m "Introduce end-of-line normalization" ------------------------------------------------- If any files that should not be normalized show up in 'git status', -unset their `crlf` attribute before running 'git add -u'. +unset their `text` attribute before running 'git add -u'. ------------------------ -manual.pdf -crlf +manual.pdf -text ------------------------ Conversely, text files that git does not detect can have normalization enabled manually. ------------------------ -weirdchars.txt crlf +weirdchars.txt text ------------------------ If `core.safecrlf` is set to "true" or "warn", git verifies if @@ -311,11 +322,11 @@ Interaction between checkin/checkout attributes In the check-in codepath, the worktree file is first converted with `filter` driver (if specified and corresponding driver defined), then the result is processed with `ident` (if -specified), and then finally with `crlf` (again, if specified +specified), and then finally with `text` (again, if specified and applicable). In the check-out codepath, the blob content is first converted -with `crlf`, and then `ident` and fed to `filter`. +with `text`, and then `ident` and fed to `filter`. Generating diff text @@ -718,7 +729,7 @@ You do not want any end-of-line conversions applied to, nor textual diffs produced for, any binary file you track. You would need to specify e.g. ------------ -*.jpg -crlf -diff +*.jpg -text -diff ------------ but that may become cumbersome, when you have many attributes. Using @@ -731,7 +742,7 @@ the same time. The system knows a built-in attribute macro, `binary`: which is equivalent to the above. Note that the attribute macros can only be "Set" (see the above example that sets "binary" macro as if it were an -ordinary attribute --- setting it in turn unsets "crlf" and "diff"). +ordinary attribute --- setting it in turn unsets "text" and "diff"). DEFINING ATTRIBUTE MACROS @@ -742,7 +753,7 @@ at the toplevel (i.e. not in any subdirectory). The built-in attribute macro "binary" is equivalent to: ------------ -[attr]binary -diff -crlf +[attr]binary -diff -text ------------ -- cgit v1.2.3 From 942e7747678ecf5f118ea5b2d0c763166de21f3a Mon Sep 17 00:00:00 2001 From: Eyvind Bernhardsen Date: Fri, 4 Jun 2010 21:29:08 +0200 Subject: Add "core.eol" config variable Introduce a new configuration variable, "core.eol", that allows the user to set which line endings to use for end-of-line-normalized files in the working directory. It defaults to "native", which means CRLF on Windows and LF everywhere else. Note that "core.autocrlf" overrides core.eol. This means that [core] autocrlf = true puts CRLFs in the working directory even if core.eol is set to "lf". Signed-off-by: Eyvind Bernhardsen Signed-off-by: Junio C Hamano --- Documentation/gitattributes.txt | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) (limited to 'Documentation/gitattributes.txt') diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 1120b90a58..c2efe4c079 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -99,7 +99,7 @@ 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. +`core.eol` configuration variable for all text files. Set:: @@ -120,9 +120,9 @@ Set to string value "auto":: Unspecified:: - If the `text` attribute is unspecified, git uses the `eol` - attribute and the `core.autocrlf` configuration variable to - determine if the file should be converted. + If the `text` attribute is unspecified, git uses the + `core.autocrlf` configuration variable to determine if the + file should be converted. Any other value causes git to act as if `text` has been left unspecified. @@ -132,19 +132,19 @@ 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 `text` attribute. +content checks, effectively setting the `text` attribute. Set to string value "crlf":: - This setting forces git to normalize line endings on checkin - and convert them to CRLF when the file is checked out, - regardless of `text` and `core.autocrlf`. + This setting forces git to normalize line endings for this + file on checkin and convert them to CRLF when the file is + checked out. 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 `text` and `core.autocrlf`. + checked out. Backwards compatibility with `crlf` attribute ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -193,9 +193,7 @@ config variable "core.autocrlf" without changing any attributes. 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. +already normalized in the repository stay normalized. If you want to interoperate with a source code management system that enforces end-of-line normalization, or you simply want all text files @@ -207,7 +205,11 @@ attribute to "auto" for _all_ files. ------------------------ This ensures that all files that git considers to be text will have -normalized (LF) line endings in the repository. +normalized (LF) line endings in the repository. The `core.eol` +configuration variable controls which line endings git will use for +normalized files in your working directory; the default is to use the +native line ending for your platform, or CRLF if `core.autocrlf` is +set. NOTE: When `text=auto` normalization is enabled in an existing repository, any text files containing CRLFs should be normalized. If -- cgit v1.2.3