X-Git-Url: https://asedeno.scripts.mit.edu/gitweb/?a=blobdiff_plain;f=Documentation%2Fgitattributes.txt;h=564586b943f439cb5ae04c4e76bc19d093c625da;hb=452c6d506b1a6dcf24d4ceaa592afc39c1c1a60e;hp=f621b23b841e52360d89670fa2274ae69b874d53;hpb=fd6cce9e89ab5ac1125a3b5f5611048ad22379e7;p=git.git diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index f621b23b8..564586b94 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -92,39 +92,39 @@ 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 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:: - 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` - 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 `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, 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 `crlf` 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 `crlf` and `core.autocrlf`. - `crlf=input` is a backwards compatibility alias for `eol=lf`. + checked out. + +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 @@ -182,30 +193,32 @@ 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 -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. +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 `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 +228,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 +324,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 @@ -448,7 +461,7 @@ patterns are available: Customizing word diff ^^^^^^^^^^^^^^^^^^^^^ -You can customize the rules that `git diff --color-words` uses to +You can customize the rules that `git diff --word-diff` uses to split words in a line, by specifying an appropriate regular expression in the "diff.*.wordRegex" configuration variable. For example, in TeX a backslash followed by a sequence of letters forms a command, but @@ -502,6 +515,26 @@ because it quickly conveys the changes you have made), you should generate it separately and send it as a comment _in addition to_ the usual binary diff that you might send. +Because text conversion can be slow, especially when doing a +large number of them with `git log -p`, git provides a mechanism +to cache the output and use it in future diffs. To enable +caching, set the "cachetextconv" variable in your diff driver's +config. For example: + +------------------------ +[diff "jpg"] + textconv = exif + cachetextconv = true +------------------------ + +This will cache the result of running "exif" on each blob +indefinitely. If you change the textconv config variable for a +diff driver, git will automatically invalidate the cache entries +and re-run the textconv filter. If you want to invalidate the +cache manually (e.g., because your version of "exif" was updated +and now produces better output), you can remove the cache +manually with `git update-ref -d refs/notes/textconv/jpg` (where +"jpg" is the name of the diff driver, as in the example above). Performing a three-way merge ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -599,7 +632,8 @@ command to run to merge ancestor's version (`%O`), current version (`%A`) and the other branches' version (`%B`). These three tokens are replaced with the names of temporary files that hold the contents of these versions when the command line is -built. +built. Additionally, %L will be replaced with the conflict marker +size (see below). The merge driver is expected to leave the result of the merge in the file named with `%A` by overwriting it, and exit with zero @@ -718,7 +752,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 +765,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 +776,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 ------------