X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=Documentation%2Fgitattributes.txt;h=87723105d1aeeab3cc9918ffc80503f4291e749c;hb=667152528df417627e54de6cb281a63a727369af;hp=ece58abee2a46c54dfe52670eb43d8c3211a575c;hpb=520635fa3a7781cce412f6b02e165b5d897a99d1;p=git.git diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index ece58abee..87723105d 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -7,7 +7,7 @@ gitattributes - defining attributes per path SYNOPSIS -------- -.gitattributes +$GIT_DIR/info/attributes, gitattributes DESCRIPTION @@ -49,10 +49,12 @@ Set to a value:: Unspecified:: No glob pattern matches the path, and nothing says if - the path has or does not have the attribute. + the path has or does not have the attribute, the + attribute for the path is said to be Unspecified. When more than one glob pattern matches the path, a later line -overrides an earlier line. +overrides an earlier line. This overriding is done per +attribute. When deciding what attributes are assigned to a path, git consults `$GIT_DIR/info/attributes` file (which has the highest @@ -76,12 +78,17 @@ are attributes-aware. Checking-out and checking-in ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The attribute `crlf` affects how the contents stored in the +These attributes affect how the contents stored in the repository are copied to the working tree files when commands -such as `git checkout` and `git merge` run. It also affects how +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` +^^^^^^ + +This attribute controls the line-ending convention. + Set:: Setting the `crlf` attribute on a path is meant to mark @@ -127,6 +134,67 @@ converted to LF upon checkin, but there is no conversion done upon checkout. +`ident` +^^^^^^^ + +When the attribute `ident` is set to a path, git replaces +`$ident$` in the blob object with `$ident:`, followed by +40-character hexadecimal blob object name, followed by a dollar +sign `$` upon checkout. Any byte sequence that begins with +`$ident:` and ends with `$` in the worktree file is replaced +with `$ident$` upon check-in. + + +Interaction between checkin/checkout attributes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In the check-in codepath, the worktree file is first converted +with `ident` (if specified), and then with `crlf` (again, if +specified and applicable). + +In the check-out codepath, the blob content is first converted +with `crlf`, and then `ident`. + + +`filter` +^^^^^^^^ + +A `filter` attribute can be set to a string value. This names +filter driver specified in the configuration. + +A filter driver consists of `clean` command and `smudge` +command, either of which can be left unspecified. Upon +checkout, when `smudge` command is specified, the command is fed +the blob object from its standard input, and its standard output +is used to update the worktree file. Similarly, `clean` command +is used to convert the contents of worktree file upon checkin. + +Missing filter driver definition in the config is not an error +but makes the filter a no-op passthru. + +The content filtering is done to massage the content into a +shape that is more convenient for the platform, filesystem, and +the user to use. The keyword here is "more convenient" and not +"turning something unusable into usable". In other words, it is +"hanging yourself because we gave you a long rope" if your +project uses filtering mechanism in such a way that it makes +your project unusable unless the checkout is done with a +specific filter in effect. + + +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 +and applicable). + +In the check-out codepath, the blob content is first converted +with `crlf`, and then `ident` and fed to `filter`. + + Generating diff text ~~~~~~~~~~~~~~~~~~~~ @@ -151,8 +219,34 @@ Unspecified:: text, it is treated as text. Otherwise it would generate `Binary files differ`. -Any other value set to `diff` attribute is ignored and git acts -as if the attribute is left unspecified. +String:: + + Diff is shown using the specified custom diff driver. + The driver program is given its input using the same + calling convention as used for GIT_EXTERNAL_DIFF + program. + + +Defining a custom diff driver +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The definition of a diff driver is done in `gitconfig`, not +`gitattributes` file, so strictly speaking this manual page is a +wrong place to talk about it. However... + +To define a custom diff driver `jcdiff`, add a section to your +`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: + +---------------------------------------------------------------- +[diff "jcdiff"] + command = j-c-diff +---------------------------------------------------------------- + +When git needs to show you a diff for the path with `diff` +attribute set to `jcdiff`, it calls the command you specified +with the above configuration, i.e. `j-c-diff`, with 7 +parameters, just like `GIT_EXTERNAL_DIFF` program is called. +See gitlink:git[7] for details. Performing a three-way merge @@ -183,13 +277,13 @@ Unspecified:: different merge driver to be used for paths to which the `merge` attribute is unspecified. -Any other string value:: +String:: 3-way merge is performed using the specified custom merge driver. The built-in 3-way merge driver can be explicitly specified by asking for "text" driver; the built-in "take the current branch" driver can be - requested by "binary". + requested with "binary". Defining a custom merge driver