| 1 | gitattributes(5) |
| 2 | ================ |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | gitattributes - Defining attributes per path |
| 7 | |
| 8 | SYNOPSIS |
| 9 | -------- |
| 10 | $GIT_DIR/info/attributes, .gitattributes |
| 11 | |
| 12 | |
| 13 | DESCRIPTION |
| 14 | ----------- |
| 15 | |
| 16 | A `gitattributes` file is a simple text file that gives |
| 17 | `attributes` to pathnames. |
| 18 | |
| 19 | Each line in `gitattributes` file is of form: |
| 20 | |
| 21 | pattern attr1 attr2 ... |
| 22 | |
| 23 | That is, a pattern followed by an attributes list, |
| 24 | separated by whitespaces. Leading and trailing whitespaces are |
| 25 | ignored. Lines that begin with '#' are ignored. Patterns |
| 26 | that begin with a double quote are quoted in C style. |
| 27 | When the pattern matches the path in question, the attributes |
| 28 | listed on the line are given to the path. |
| 29 | |
| 30 | Each attribute can be in one of these states for a given path: |
| 31 | |
| 32 | Set:: |
| 33 | |
| 34 | The path has the attribute with special value "true"; |
| 35 | this is specified by listing only the name of the |
| 36 | attribute in the attribute list. |
| 37 | |
| 38 | Unset:: |
| 39 | |
| 40 | The path has the attribute with special value "false"; |
| 41 | this is specified by listing the name of the attribute |
| 42 | prefixed with a dash `-` in the attribute list. |
| 43 | |
| 44 | Set to a value:: |
| 45 | |
| 46 | The path has the attribute with specified string value; |
| 47 | this is specified by listing the name of the attribute |
| 48 | followed by an equal sign `=` and its value in the |
| 49 | attribute list. |
| 50 | |
| 51 | Unspecified:: |
| 52 | |
| 53 | No pattern matches the path, and nothing says if |
| 54 | the path has or does not have the attribute, the |
| 55 | attribute for the path is said to be Unspecified. |
| 56 | |
| 57 | When more than one pattern matches the path, a later line |
| 58 | overrides an earlier line. This overriding is done per |
| 59 | attribute. |
| 60 | |
| 61 | The rules by which the pattern matches paths are the same as in |
| 62 | `.gitignore` files (see linkgit:gitignore[5]), with a few exceptions: |
| 63 | |
| 64 | - negative patterns are forbidden |
| 65 | |
| 66 | - patterns that match a directory do not recursively match paths |
| 67 | inside that directory (so using the trailing-slash `path/` syntax is |
| 68 | pointless in an attributes file; use `path/**` instead) |
| 69 | |
| 70 | When deciding what attributes are assigned to a path, Git |
| 71 | consults `$GIT_DIR/info/attributes` file (which has the highest |
| 72 | precedence), `.gitattributes` file in the same directory as the |
| 73 | path in question, and its parent directories up to the toplevel of the |
| 74 | work tree (the further the directory that contains `.gitattributes` |
| 75 | is from the path in question, the lower its precedence). Finally |
| 76 | global and system-wide files are considered (they have the lowest |
| 77 | precedence). |
| 78 | |
| 79 | When the `.gitattributes` file is missing from the work tree, the |
| 80 | path in the index is used as a fall-back. During checkout process, |
| 81 | `.gitattributes` in the index is used and then the file in the |
| 82 | working tree is used as a fall-back. |
| 83 | |
| 84 | If you wish to affect only a single repository (i.e., to assign |
| 85 | attributes to files that are particular to |
| 86 | one user's workflow for that repository), then |
| 87 | attributes should be placed in the `$GIT_DIR/info/attributes` file. |
| 88 | Attributes which should be version-controlled and distributed to other |
| 89 | repositories (i.e., attributes of interest to all users) should go into |
| 90 | `.gitattributes` files. Attributes that should affect all repositories |
| 91 | for a single user should be placed in a file specified by the |
| 92 | `core.attributesFile` configuration option (see linkgit:git-config[1]). |
| 93 | Its default value is $XDG_CONFIG_HOME/git/attributes. If $XDG_CONFIG_HOME |
| 94 | is either not set or empty, $HOME/.config/git/attributes is used instead. |
| 95 | Attributes for all users on a system should be placed in the |
| 96 | `$(prefix)/etc/gitattributes` file. |
| 97 | |
| 98 | Sometimes you would need to override a setting of an attribute |
| 99 | for a path to `Unspecified` state. This can be done by listing |
| 100 | the name of the attribute prefixed with an exclamation point `!`. |
| 101 | |
| 102 | |
| 103 | RESERVED BUILTIN_* ATTRIBUTES |
| 104 | ----------------------------- |
| 105 | |
| 106 | builtin_* is a reserved namespace for builtin attribute values. Any |
| 107 | user defined attributes under this namespace will be ignored and |
| 108 | trigger a warning. |
| 109 | |
| 110 | `builtin_objectmode` |
| 111 | ~~~~~~~~~~~~~~~~~~~~ |
| 112 | This attribute is for filtering files by their file bit modes (40000, |
| 113 | 120000, 160000, 100755, 100644). e.g. ':(attr:builtin_objectmode=160000)'. |
| 114 | You may also check these values with `git check-attr builtin_objectmode -- <file>`. |
| 115 | If the object is not in the index `git check-attr --cached` will return unspecified. |
| 116 | |
| 117 | |
| 118 | EFFECTS |
| 119 | ------- |
| 120 | |
| 121 | Certain operations by Git can be influenced by assigning |
| 122 | particular attributes to a path. Currently, the following |
| 123 | operations are attributes-aware. |
| 124 | |
| 125 | Checking-out and checking-in |
| 126 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 127 | |
| 128 | These attributes affect how the contents stored in the |
| 129 | repository are copied to the working tree files when commands |
| 130 | such as 'git switch', 'git checkout' and 'git merge' run. |
| 131 | They also affect how |
| 132 | Git stores the contents you prepare in the working tree in the |
| 133 | repository upon 'git add' and 'git commit'. |
| 134 | |
| 135 | `text` |
| 136 | ^^^^^^ |
| 137 | |
| 138 | This attribute marks the path as a text file, which enables end-of-line |
| 139 | conversion: When a matching file is added to the index, the file's line |
| 140 | endings are normalized to LF in the index. Conversely, when the file is |
| 141 | copied from the index to the working directory, its line endings may be |
| 142 | converted from LF to CRLF depending on the `eol` attribute, the Git |
| 143 | config, and the platform (see explanation of `eol` below). |
| 144 | |
| 145 | Set:: |
| 146 | |
| 147 | Setting the `text` attribute on a path enables end-of-line |
| 148 | conversion on checkin and checkout as described above. Line endings |
| 149 | are normalized to LF in the index every time the file is checked in, |
| 150 | even if the file was previously added to Git with CRLF line endings. |
| 151 | |
| 152 | Unset:: |
| 153 | |
| 154 | Unsetting the `text` attribute on a path tells Git not to |
| 155 | attempt any end-of-line conversion upon checkin or checkout. |
| 156 | |
| 157 | Set to string value "auto":: |
| 158 | |
| 159 | When `text` is set to "auto", Git decides by itself whether the file |
| 160 | is text or binary. If it is text and the file was not already in |
| 161 | Git with CRLF endings, line endings are converted on checkin and |
| 162 | checkout as described above. Otherwise, no conversion is done on |
| 163 | checkin or checkout. |
| 164 | |
| 165 | Unspecified:: |
| 166 | |
| 167 | If the `text` attribute is unspecified, Git uses the |
| 168 | `core.autocrlf` configuration variable to determine if the |
| 169 | file should be converted. |
| 170 | |
| 171 | Any other value causes Git to act as if `text` has been left |
| 172 | unspecified. |
| 173 | |
| 174 | `eol` |
| 175 | ^^^^^ |
| 176 | |
| 177 | This attribute marks a path to use a specific line-ending style in the |
| 178 | working tree when it is checked out. It has effect only if `text` or |
| 179 | `text=auto` is set (see above), but specifying `eol` automatically sets |
| 180 | `text` if `text` was left unspecified. |
| 181 | |
| 182 | Set to string value "crlf":: |
| 183 | |
| 184 | This setting converts the file's line endings in the working |
| 185 | directory to CRLF when the file is checked out. |
| 186 | |
| 187 | Set to string value "lf":: |
| 188 | |
| 189 | This setting uses the same line endings in the working directory as |
| 190 | in the index when the file is checked out. |
| 191 | |
| 192 | Unspecified:: |
| 193 | |
| 194 | If the `eol` attribute is unspecified for a file, its line endings |
| 195 | in the working directory are determined by the `core.autocrlf` or |
| 196 | `core.eol` configuration variable (see the definitions of those |
| 197 | options in linkgit:git-config[1]). If `text` is set but neither of |
| 198 | those variables is, the default is `eol=crlf` on Windows and |
| 199 | `eol=lf` on all other platforms. |
| 200 | |
| 201 | Backwards compatibility with `crlf` attribute |
| 202 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 203 | |
| 204 | For backwards compatibility, the `crlf` attribute is interpreted as |
| 205 | follows: |
| 206 | |
| 207 | ------------------------ |
| 208 | crlf text |
| 209 | -crlf -text |
| 210 | crlf=input eol=lf |
| 211 | ------------------------ |
| 212 | |
| 213 | End-of-line conversion |
| 214 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 215 | |
| 216 | While Git normally leaves file contents alone, it can be configured to |
| 217 | normalize line endings to LF in the repository and, optionally, to |
| 218 | convert them to CRLF when files are checked out. |
| 219 | |
| 220 | If you simply want to have CRLF line endings in your working directory |
| 221 | regardless of the repository you are working with, you can set the |
| 222 | config variable "core.autocrlf" without using any attributes. |
| 223 | |
| 224 | ------------------------ |
| 225 | [core] |
| 226 | autocrlf = true |
| 227 | ------------------------ |
| 228 | |
| 229 | This does not force normalization of text files, but does ensure |
| 230 | that text files that you introduce to the repository have their line |
| 231 | endings normalized to LF when they are added, and that files that are |
| 232 | already normalized in the repository stay normalized. |
| 233 | |
| 234 | If you want to ensure that text files that any contributor introduces to |
| 235 | the repository have their line endings normalized, you can set the |
| 236 | `text` attribute to "auto" for _all_ files. |
| 237 | |
| 238 | ------------------------ |
| 239 | * text=auto |
| 240 | ------------------------ |
| 241 | |
| 242 | The attributes allow a fine-grained control, how the line endings |
| 243 | are converted. |
| 244 | Here is an example that will make Git normalize .txt, .vcproj and .sh |
| 245 | files, ensure that .vcproj files have CRLF and .sh files have LF in |
| 246 | the working directory, and prevent .jpg files from being normalized |
| 247 | regardless of their content. |
| 248 | |
| 249 | ------------------------ |
| 250 | * text=auto |
| 251 | *.txt text |
| 252 | *.vcproj text eol=crlf |
| 253 | *.sh text eol=lf |
| 254 | *.jpg -text |
| 255 | ------------------------ |
| 256 | |
| 257 | NOTE: When `text=auto` conversion is enabled in a cross-platform |
| 258 | project using push and pull to a central repository the text files |
| 259 | containing CRLFs should be normalized. |
| 260 | |
| 261 | From a clean working directory: |
| 262 | |
| 263 | ------------------------------------------------- |
| 264 | $ echo "* text=auto" >.gitattributes |
| 265 | $ git add --renormalize . |
| 266 | $ git status # Show files that will be normalized |
| 267 | $ git commit -m "Introduce end-of-line normalization" |
| 268 | ------------------------------------------------- |
| 269 | |
| 270 | If any files that should not be normalized show up in 'git status', |
| 271 | unset their `text` attribute before running 'git add -u'. |
| 272 | |
| 273 | ------------------------ |
| 274 | manual.pdf -text |
| 275 | ------------------------ |
| 276 | |
| 277 | Conversely, text files that Git does not detect can have normalization |
| 278 | enabled manually. |
| 279 | |
| 280 | ------------------------ |
| 281 | weirdchars.txt text |
| 282 | ------------------------ |
| 283 | |
| 284 | If `core.safecrlf` is set to "true" or "warn", Git verifies if |
| 285 | the conversion is reversible for the current setting of |
| 286 | `core.autocrlf`. For "true", Git rejects irreversible |
| 287 | conversions; for "warn", Git only prints a warning but accepts |
| 288 | an irreversible conversion. The safety triggers to prevent such |
| 289 | a conversion done to the files in the work tree, but there are a |
| 290 | few exceptions. Even though... |
| 291 | |
| 292 | - 'git add' itself does not touch the files in the work tree, the |
| 293 | next checkout would, so the safety triggers; |
| 294 | |
| 295 | - 'git apply' to update a text file with a patch does touch the files |
| 296 | in the work tree, but the operation is about text files and CRLF |
| 297 | conversion is about fixing the line ending inconsistencies, so the |
| 298 | safety does not trigger; |
| 299 | |
| 300 | - 'git diff' itself does not touch the files in the work tree, it is |
| 301 | often run to inspect the changes you intend to next 'git add'. To |
| 302 | catch potential problems early, safety triggers. |
| 303 | |
| 304 | |
| 305 | `working-tree-encoding` |
| 306 | ^^^^^^^^^^^^^^^^^^^^^^^ |
| 307 | |
| 308 | Git recognizes files encoded in ASCII or one of its supersets (e.g. |
| 309 | UTF-8, ISO-8859-1, ...) as text files. Files encoded in certain other |
| 310 | encodings (e.g. UTF-16) are interpreted as binary and consequently |
| 311 | built-in Git text processing tools (e.g. 'git diff') as well as most Git |
| 312 | web front ends do not visualize the contents of these files by default. |
| 313 | |
| 314 | In these cases you can tell Git the encoding of a file in the working |
| 315 | directory with the `working-tree-encoding` attribute. If a file with this |
| 316 | attribute is added to Git, then Git re-encodes the content from the |
| 317 | specified encoding to UTF-8. Finally, Git stores the UTF-8 encoded |
| 318 | content in its internal data structure (called "the index"). On checkout |
| 319 | the content is re-encoded back to the specified encoding. |
| 320 | |
| 321 | Please note that using the `working-tree-encoding` attribute may have a |
| 322 | number of pitfalls: |
| 323 | |
| 324 | - Alternative Git implementations (e.g. JGit or libgit2) and older Git |
| 325 | versions (as of March 2018) do not support the `working-tree-encoding` |
| 326 | attribute. If you decide to use the `working-tree-encoding` attribute |
| 327 | in your repository, then it is strongly recommended to ensure that all |
| 328 | clients working with the repository support it. |
| 329 | + |
| 330 | For example, Microsoft Visual Studio resources files (`*.rc`) or |
| 331 | PowerShell script files (`*.ps1`) are sometimes encoded in UTF-16. |
| 332 | If you declare `*.ps1` as files as UTF-16 and you add `foo.ps1` with |
| 333 | a `working-tree-encoding` enabled Git client, then `foo.ps1` will be |
| 334 | stored as UTF-8 internally. A client without `working-tree-encoding` |
| 335 | support will checkout `foo.ps1` as UTF-8 encoded file. This will |
| 336 | typically cause trouble for the users of this file. |
| 337 | + |
| 338 | If a Git client that does not support the `working-tree-encoding` |
| 339 | attribute adds a new file `bar.ps1`, then `bar.ps1` will be |
| 340 | stored "as-is" internally (in this example probably as UTF-16). |
| 341 | A client with `working-tree-encoding` support will interpret the |
| 342 | internal contents as UTF-8 and try to convert it to UTF-16 on checkout. |
| 343 | That operation will fail and cause an error. |
| 344 | |
| 345 | - Reencoding content to non-UTF encodings can cause errors as the |
| 346 | conversion might not be UTF-8 round trip safe. If you suspect your |
| 347 | encoding to not be round trip safe, then add it to |
| 348 | `core.checkRoundtripEncoding` to make Git check the round trip |
| 349 | encoding (see linkgit:git-config[1]). SHIFT-JIS (Japanese character |
| 350 | set) is known to have round trip issues with UTF-8 and is checked by |
| 351 | default. |
| 352 | |
| 353 | - Reencoding content requires resources that might slow down certain |
| 354 | Git operations (e.g 'git checkout' or 'git add'). |
| 355 | |
| 356 | Use the `working-tree-encoding` attribute only if you cannot store a file |
| 357 | in UTF-8 encoding and if you want Git to be able to process the content |
| 358 | as text. |
| 359 | |
| 360 | As an example, use the following attributes if your '*.ps1' files are |
| 361 | UTF-16 encoded with byte order mark (BOM) and you want Git to perform |
| 362 | automatic line ending conversion based on your platform. |
| 363 | |
| 364 | ------------------------ |
| 365 | *.ps1 text working-tree-encoding=UTF-16 |
| 366 | ------------------------ |
| 367 | |
| 368 | Use the following attributes if your '*.ps1' files are UTF-16 little |
| 369 | endian encoded without BOM and you want Git to use Windows line endings |
| 370 | in the working directory (use `UTF-16LE-BOM` instead of `UTF-16LE` if |
| 371 | you want UTF-16 little endian with BOM). |
| 372 | Please note, it is highly recommended to |
| 373 | explicitly define the line endings with `eol` if the `working-tree-encoding` |
| 374 | attribute is used to avoid ambiguity. |
| 375 | |
| 376 | ------------------------ |
| 377 | *.ps1 text working-tree-encoding=UTF-16LE eol=crlf |
| 378 | ------------------------ |
| 379 | |
| 380 | You can get a list of all available encodings on your platform with the |
| 381 | following command: |
| 382 | |
| 383 | ------------------------ |
| 384 | iconv --list |
| 385 | ------------------------ |
| 386 | |
| 387 | If you do not know the encoding of a file, then you can use the `file` |
| 388 | command to guess the encoding: |
| 389 | |
| 390 | ------------------------ |
| 391 | file foo.ps1 |
| 392 | ------------------------ |
| 393 | |
| 394 | |
| 395 | `ident` |
| 396 | ^^^^^^^ |
| 397 | |
| 398 | When the attribute `ident` is set for a path, Git replaces |
| 399 | `$Id$` in the blob object with `$Id:`, followed by the |
| 400 | 40-character hexadecimal blob object name, followed by a dollar |
| 401 | sign `$` upon checkout. Any byte sequence that begins with |
| 402 | `$Id:` and ends with `$` in the worktree file is replaced |
| 403 | with `$Id$` upon check-in. |
| 404 | |
| 405 | |
| 406 | `filter` |
| 407 | ^^^^^^^^ |
| 408 | |
| 409 | A `filter` attribute can be set to a string value that names a |
| 410 | filter driver specified in the configuration. |
| 411 | |
| 412 | A filter driver consists of a `clean` command and a `smudge` |
| 413 | command, either of which can be left unspecified. Upon |
| 414 | checkout, when the `smudge` command is specified, the command is |
| 415 | fed the blob object from its standard input, and its standard |
| 416 | output is used to update the worktree file. Similarly, the |
| 417 | `clean` command is used to convert the contents of worktree file |
| 418 | upon checkin. By default these commands process only a single |
| 419 | blob and terminate. If a long running `process` filter is used |
| 420 | in place of `clean` and/or `smudge` filters, then Git can process |
| 421 | all blobs with a single filter command invocation for the entire |
| 422 | life of a single Git command, for example `git add --all`. If a |
| 423 | long running `process` filter is configured then it always takes |
| 424 | precedence over a configured single blob filter. See section |
| 425 | below for the description of the protocol used to communicate with |
| 426 | a `process` filter. |
| 427 | |
| 428 | One use of the content filtering is to massage the content into a shape |
| 429 | that is more convenient for the platform, filesystem, and the user to use. |
| 430 | For this mode of operation, the key phrase here is "more convenient" and |
| 431 | not "turning something unusable into usable". In other words, the intent |
| 432 | is that if someone unsets the filter driver definition, or does not have |
| 433 | the appropriate filter program, the project should still be usable. |
| 434 | |
| 435 | Another use of the content filtering is to store the content that cannot |
| 436 | be directly used in the repository (e.g. a UUID that refers to the true |
| 437 | content stored outside Git, or an encrypted content) and turn it into a |
| 438 | usable form upon checkout (e.g. download the external content, or decrypt |
| 439 | the encrypted content). |
| 440 | |
| 441 | These two filters behave differently, and by default, a filter is taken as |
| 442 | the former, massaging the contents into more convenient shape. A missing |
| 443 | filter driver definition in the config, or a filter driver that exits with |
| 444 | a non-zero status, is not an error but makes the filter a no-op passthru. |
| 445 | |
| 446 | You can declare that a filter turns a content that by itself is unusable |
| 447 | into a usable content by setting the filter.<driver>.required configuration |
| 448 | variable to `true`. |
| 449 | |
| 450 | Note: Whenever the clean filter is changed, the repo should be renormalized: |
| 451 | $ git add --renormalize . |
| 452 | |
| 453 | For example, in .gitattributes, you would assign the `filter` |
| 454 | attribute for paths. |
| 455 | |
| 456 | ------------------------ |
| 457 | *.c filter=indent |
| 458 | ------------------------ |
| 459 | |
| 460 | Then you would define a "filter.indent.clean" and "filter.indent.smudge" |
| 461 | configuration in your .git/config to specify a pair of commands to |
| 462 | modify the contents of C programs when the source files are checked |
| 463 | in ("clean" is run) and checked out (no change is made because the |
| 464 | command is "cat"). |
| 465 | |
| 466 | ------------------------ |
| 467 | [filter "indent"] |
| 468 | clean = indent |
| 469 | smudge = cat |
| 470 | ------------------------ |
| 471 | |
| 472 | For best results, `clean` should not alter its output further if it is |
| 473 | run twice ("clean->clean" should be equivalent to "clean"), and |
| 474 | multiple `smudge` commands should not alter `clean`'s output |
| 475 | ("smudge->smudge->clean" should be equivalent to "clean"). See the |
| 476 | section on merging below. |
| 477 | |
| 478 | The "indent" filter is well-behaved in this regard: it will not modify |
| 479 | input that is already correctly indented. In this case, the lack of a |
| 480 | smudge filter means that the clean filter _must_ accept its own output |
| 481 | without modifying it. |
| 482 | |
| 483 | If a filter _must_ succeed in order to make the stored contents usable, |
| 484 | you can declare that the filter is `required`, in the configuration: |
| 485 | |
| 486 | ------------------------ |
| 487 | [filter "crypt"] |
| 488 | clean = openssl enc ... |
| 489 | smudge = openssl enc -d ... |
| 490 | required |
| 491 | ------------------------ |
| 492 | |
| 493 | Sequence "%f" on the filter command line is replaced with the name of |
| 494 | the file the filter is working on. A filter might use this in keyword |
| 495 | substitution. For example: |
| 496 | |
| 497 | ------------------------ |
| 498 | [filter "p4"] |
| 499 | clean = git-p4-filter --clean %f |
| 500 | smudge = git-p4-filter --smudge %f |
| 501 | ------------------------ |
| 502 | |
| 503 | Note that "%f" is the name of the path that is being worked on. Depending |
| 504 | on the version that is being filtered, the corresponding file on disk may |
| 505 | not exist, or may have different contents. So, smudge and clean commands |
| 506 | should not try to access the file on disk, but only act as filters on the |
| 507 | content provided to them on standard input. |
| 508 | |
| 509 | Long Running Filter Process |
| 510 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 511 | |
| 512 | If the filter command (a string value) is defined via |
| 513 | `filter.<driver>.process` then Git can process all blobs with a |
| 514 | single filter invocation for the entire life of a single Git |
| 515 | command. This is achieved by using the long-running process protocol |
| 516 | (described in Documentation/technical/long-running-process-protocol.adoc). |
| 517 | |
| 518 | When Git encounters the first file that needs to be cleaned or smudged, |
| 519 | it starts the filter and performs the handshake. In the handshake, the |
| 520 | welcome message sent by Git is "git-filter-client", only version 2 is |
| 521 | supported, and the supported capabilities are "clean", "smudge", and |
| 522 | "delay". |
| 523 | |
| 524 | Afterwards Git sends a list of "key=value" pairs terminated with |
| 525 | a flush packet. The list will contain at least the filter command |
| 526 | (based on the supported capabilities) and the pathname of the file |
| 527 | to filter relative to the repository root. Right after the flush packet |
| 528 | Git sends the content split in zero or more pkt-line packets and a |
| 529 | flush packet to terminate content. Please note, that the filter |
| 530 | must not send any response before it received the content and the |
| 531 | final flush packet. Also note that the "value" of a "key=value" pair |
| 532 | can contain the "=" character whereas the key would never contain |
| 533 | that character. |
| 534 | |
| 535 | ----------------------- |
| 536 | packet: git> command=smudge |
| 537 | packet: git> pathname=path/testfile.dat |
| 538 | packet: git> 0000 |
| 539 | packet: git> CONTENT |
| 540 | packet: git> 0000 |
| 541 | ----------------------- |
| 542 | |
| 543 | The filter is expected to respond with a list of "key=value" pairs |
| 544 | terminated with a flush packet. If the filter does not experience |
| 545 | problems then the list must contain a "success" status. Right after |
| 546 | these packets the filter is expected to send the content in zero |
| 547 | or more pkt-line packets and a flush packet at the end. Finally, a |
| 548 | second list of "key=value" pairs terminated with a flush packet |
| 549 | is expected. The filter can change the status in the second list |
| 550 | or keep the status as is with an empty list. Please note that the |
| 551 | empty list must be terminated with a flush packet regardless. |
| 552 | |
| 553 | ------------------------ |
| 554 | packet: git< status=success |
| 555 | packet: git< 0000 |
| 556 | packet: git< SMUDGED_CONTENT |
| 557 | packet: git< 0000 |
| 558 | packet: git< 0000 # empty list, keep "status=success" unchanged! |
| 559 | ------------------------ |
| 560 | |
| 561 | If the result content is empty then the filter is expected to respond |
| 562 | with a "success" status and a flush packet to signal the empty content. |
| 563 | |
| 564 | ------------------------ |
| 565 | packet: git< status=success |
| 566 | packet: git< 0000 |
| 567 | packet: git< 0000 # empty content! |
| 568 | packet: git< 0000 # empty list, keep "status=success" unchanged! |
| 569 | ------------------------ |
| 570 | |
| 571 | In case the filter cannot or does not want to process the content, |
| 572 | it is expected to respond with an "error" status. |
| 573 | |
| 574 | ----------------------- |
| 575 | packet: git< status=error |
| 576 | packet: git< 0000 |
| 577 | ----------------------- |
| 578 | |
| 579 | If the filter experiences an error during processing, then it can |
| 580 | send the status "error" after the content was (partially or |
| 581 | completely) sent. |
| 582 | |
| 583 | ------------------------ |
| 584 | packet: git< status=success |
| 585 | packet: git< 0000 |
| 586 | packet: git< HALF_WRITTEN_ERRONEOUS_CONTENT |
| 587 | packet: git< 0000 |
| 588 | packet: git< status=error |
| 589 | packet: git< 0000 |
| 590 | ------------------------ |
| 591 | |
| 592 | In case the filter cannot or does not want to process the content |
| 593 | as well as any future content for the lifetime of the Git process, |
| 594 | then it is expected to respond with an "abort" status at any point |
| 595 | in the protocol. |
| 596 | |
| 597 | ----------------------- |
| 598 | packet: git< status=abort |
| 599 | packet: git< 0000 |
| 600 | ----------------------- |
| 601 | |
| 602 | Git neither stops nor restarts the filter process in case the |
| 603 | "error"/"abort" status is set. However, Git sets its exit code |
| 604 | according to the `filter.<driver>.required` flag, mimicking the |
| 605 | behavior of the `filter.<driver>.clean` / `filter.<driver>.smudge` |
| 606 | mechanism. |
| 607 | |
| 608 | If the filter dies during the communication or does not adhere to |
| 609 | the protocol then Git will stop the filter process and restart it |
| 610 | with the next file that needs to be processed. Depending on the |
| 611 | `filter.<driver>.required` flag Git will interpret that as error. |
| 612 | |
| 613 | Delay |
| 614 | ^^^^^ |
| 615 | |
| 616 | If the filter supports the "delay" capability, then Git can send the |
| 617 | flag "can-delay" after the filter command and pathname. This flag |
| 618 | denotes that the filter can delay filtering the current blob (e.g. to |
| 619 | compensate network latencies) by responding with no content but with |
| 620 | the status "delayed" and a flush packet. |
| 621 | |
| 622 | ----------------------- |
| 623 | packet: git> command=smudge |
| 624 | packet: git> pathname=path/testfile.dat |
| 625 | packet: git> can-delay=1 |
| 626 | packet: git> 0000 |
| 627 | packet: git> CONTENT |
| 628 | packet: git> 0000 |
| 629 | packet: git< status=delayed |
| 630 | packet: git< 0000 |
| 631 | ----------------------- |
| 632 | |
| 633 | If the filter supports the "delay" capability then it must support the |
| 634 | "list_available_blobs" command. If Git sends this command, then the |
| 635 | filter is expected to return a list of pathnames representing blobs |
| 636 | that have been delayed earlier and are now available. |
| 637 | The list must be terminated with a flush packet followed |
| 638 | by a "success" status that is also terminated with a flush packet. If |
| 639 | no blobs for the delayed paths are available, yet, then the filter is |
| 640 | expected to block the response until at least one blob becomes |
| 641 | available. The filter can tell Git that it has no more delayed blobs |
| 642 | by sending an empty list. As soon as the filter responds with an empty |
| 643 | list, Git stops asking. All blobs that Git has not received at this |
| 644 | point are considered missing and will result in an error. |
| 645 | |
| 646 | ------------------------ |
| 647 | packet: git> command=list_available_blobs |
| 648 | packet: git> 0000 |
| 649 | packet: git< pathname=path/testfile.dat |
| 650 | packet: git< pathname=path/otherfile.dat |
| 651 | packet: git< 0000 |
| 652 | packet: git< status=success |
| 653 | packet: git< 0000 |
| 654 | ------------------------ |
| 655 | |
| 656 | |
| 657 | After Git received the pathnames, it will request the corresponding |
| 658 | blobs again. These requests contain a pathname and an empty content |
| 659 | section. The filter is expected to respond with the smudged content |
| 660 | in the usual way as explained above. |
| 661 | |
| 662 | ------------------------ |
| 663 | packet: git> command=smudge |
| 664 | packet: git> pathname=path/testfile.dat |
| 665 | packet: git> 0000 |
| 666 | packet: git> 0000 # empty content! |
| 667 | packet: git< status=success |
| 668 | packet: git< 0000 |
| 669 | packet: git< SMUDGED_CONTENT |
| 670 | packet: git< 0000 |
| 671 | packet: git< 0000 # empty list, keep "status=success" unchanged! |
| 672 | ------------------------ |
| 673 | |
| 674 | Example |
| 675 | ^^^^^^^ |
| 676 | |
| 677 | A long running filter demo implementation can be found in |
| 678 | `contrib/long-running-filter/example.pl` located in the Git |
| 679 | core repository. If you develop your own long running filter |
| 680 | process then the `GIT_TRACE_PACKET` environment variables can be |
| 681 | very helpful for debugging (see linkgit:git[1]). |
| 682 | |
| 683 | Please note that you cannot use an existing `filter.<driver>.clean` |
| 684 | or `filter.<driver>.smudge` command with `filter.<driver>.process` |
| 685 | because the former two use a different inter process communication |
| 686 | protocol than the latter one. |
| 687 | |
| 688 | |
| 689 | Interaction between checkin/checkout attributes |
| 690 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 691 | |
| 692 | In the check-in codepath, the worktree file is first converted |
| 693 | with `filter` driver (if specified and corresponding driver |
| 694 | defined), then the result is processed with `ident` (if |
| 695 | specified), and then finally with `text` (again, if specified |
| 696 | and applicable). |
| 697 | |
| 698 | In the check-out codepath, the blob content is first converted |
| 699 | with `text`, and then `ident` and fed to `filter`. |
| 700 | |
| 701 | |
| 702 | Merging branches with differing checkin/checkout attributes |
| 703 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 704 | |
| 705 | If you have added attributes to a file that cause the canonical |
| 706 | repository format for that file to change, such as adding a |
| 707 | clean/smudge filter or text/eol/ident attributes, merging anything |
| 708 | where the attribute is not in place would normally cause merge |
| 709 | conflicts. |
| 710 | |
| 711 | To prevent these unnecessary merge conflicts, Git can be told to run a |
| 712 | virtual check-out and check-in of all three stages of each file that |
| 713 | needs a three-way content merge, by setting the `merge.renormalize` |
| 714 | configuration variable. This prevents changes caused by check-in |
| 715 | conversion from causing spurious merge conflicts when a converted file |
| 716 | is merged with an unconverted file. |
| 717 | |
| 718 | As long as a "smudge->clean" results in the same output as a "clean" |
| 719 | even on files that are already smudged, this strategy will |
| 720 | automatically resolve all filter-related conflicts. Filters that do |
| 721 | not act in this way may cause additional merge conflicts that must be |
| 722 | resolved manually. |
| 723 | |
| 724 | |
| 725 | Generating diff text |
| 726 | ~~~~~~~~~~~~~~~~~~~~ |
| 727 | |
| 728 | `diff` |
| 729 | ^^^^^^ |
| 730 | |
| 731 | The attribute `diff` affects how Git generates diffs for particular |
| 732 | files. It can tell Git whether to generate a textual patch for the path |
| 733 | or to treat the path as a binary file. It can also affect what line is |
| 734 | shown on the hunk header `@@ -k,l +n,m @@` line, tell Git to use an |
| 735 | external command to generate the diff, or ask Git to convert binary |
| 736 | files to a text format before generating the diff. |
| 737 | |
| 738 | Set:: |
| 739 | |
| 740 | A path to which the `diff` attribute is set is treated |
| 741 | as text, even when they contain byte values that |
| 742 | normally never appear in text files, such as NUL. |
| 743 | |
| 744 | Unset:: |
| 745 | |
| 746 | A path to which the `diff` attribute is unset will |
| 747 | generate `Binary files differ` (or a binary patch, if |
| 748 | binary patches are enabled). |
| 749 | |
| 750 | Unspecified:: |
| 751 | |
| 752 | A path to which the `diff` attribute is unspecified |
| 753 | first gets its contents inspected, and if it looks like |
| 754 | text and is smaller than core.bigFileThreshold, it is treated |
| 755 | as text. Otherwise it would generate `Binary files differ`. |
| 756 | |
| 757 | String:: |
| 758 | |
| 759 | Diff is shown using the specified diff driver. Each driver may |
| 760 | specify one or more options, as described in the following |
| 761 | section. The options for the diff driver "foo" are defined |
| 762 | by the configuration variables in the "diff.foo" section of the |
| 763 | Git config file. |
| 764 | |
| 765 | |
| 766 | Defining an external diff driver |
| 767 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 768 | |
| 769 | The definition of a diff driver is done in `gitconfig`, not |
| 770 | `gitattributes` file, so strictly speaking this manual page is a |
| 771 | wrong place to talk about it. However... |
| 772 | |
| 773 | To define an external diff driver `jcdiff`, add a section to your |
| 774 | `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: |
| 775 | |
| 776 | ---------------------------------------------------------------- |
| 777 | [diff "jcdiff"] |
| 778 | command = j-c-diff |
| 779 | ---------------------------------------------------------------- |
| 780 | |
| 781 | When Git needs to show you a diff for the path with `diff` |
| 782 | attribute set to `jcdiff`, it calls the command you specified |
| 783 | with the above configuration, i.e. `j-c-diff`, with 7 |
| 784 | parameters, just like `GIT_EXTERNAL_DIFF` program is called. |
| 785 | See linkgit:git[1] for details. |
| 786 | |
| 787 | An external diff driver replaces the patch Git would otherwise |
| 788 | produce for the path: Git runs the command and shows its output in |
| 789 | place of its own. Output features that post-process Git's diff do |
| 790 | not apply to the driver's output; word diff, function context (`-W`), |
| 791 | `--color-moved`, and coloring all act on Git's builtin diff, not the |
| 792 | driver's output. |
| 793 | The driver is consulted only when Git generates a textual patch. The |
| 794 | summary formats (`--stat`, `--numstat`, `--shortstat`, and |
| 795 | `--dirstat`), `git blame`, and `git log -L` do not run it and |
| 796 | continue to use Git's builtin diff. |
| 797 | |
| 798 | If the program is able to ignore certain changes (similar to |
| 799 | `git diff --ignore-space-change`), then also set the option |
| 800 | `trustExitCode` to true. It is then expected to return exit code 1 if |
| 801 | it finds significant changes and 0 if it doesn't. |
| 802 | |
| 803 | Setting the internal diff algorithm |
| 804 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 805 | |
| 806 | The diff algorithm can be set through the `diff.algorithm` config key, but |
| 807 | sometimes it may be helpful to set the diff algorithm per path. For example, |
| 808 | one may want to use the `minimal` diff algorithm for .json files, and the |
| 809 | `histogram` for .c files, and so on without having to pass in the algorithm |
| 810 | through the command line each time. |
| 811 | |
| 812 | First, in `.gitattributes`, assign the `diff` attribute for paths. |
| 813 | |
| 814 | ------------------------ |
| 815 | *.json diff=<name> |
| 816 | ------------------------ |
| 817 | |
| 818 | Then, define a "diff.<name>.algorithm" configuration to specify the diff |
| 819 | algorithm, choosing from `myers`, `patience`, `minimal`, or `histogram`. |
| 820 | |
| 821 | ---------------------------------------------------------------- |
| 822 | [diff "<name>"] |
| 823 | algorithm = histogram |
| 824 | ---------------------------------------------------------------- |
| 825 | |
| 826 | This diff algorithm applies to user facing diff output like git-diff(1), |
| 827 | git-show(1) and is used for the `--stat` output as well. The merge machinery |
| 828 | will not use the diff algorithm set through this method. |
| 829 | |
| 830 | NOTE: If `diff.<name>.command` is defined for path with the |
| 831 | `diff=<name>` attribute, it is executed as an external diff driver |
| 832 | (see above), and adding `diff.<name>.algorithm` has no effect, as the |
| 833 | algorithm is not passed to the external diff driver. |
| 834 | |
| 835 | Answering diffs from a long-running process |
| 836 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 837 | |
| 838 | Unlike `diff.<name>.command`, which replaces the textual patch, the |
| 839 | process configured in `diff.<name>.process` feeds hunks back into |
| 840 | Git's own machinery: |
| 841 | it answers "which line ranges changed between these two blobs", and |
| 842 | Git's output is produced from that answer. A process is started |
| 843 | lazily, once per configured command string and per repository, and |
| 844 | consulted over a pkt-line protocol (following the long-running filter |
| 845 | process protocol; see the "Long Running Filter Process" section above |
| 846 | for the filter analogue). |
| 847 | |
| 848 | The process is asked by object names alone: a request carries the |
| 849 | pathname and the `old-oid`/`new-oid` of the blob pair, and no content. |
| 850 | The pathname is the repository-relative old-side (preimage) path, not |
| 851 | the shortened display path a `--relative` diff shows, so a driver |
| 852 | scoped to a directory matches whatever directory the command runs from. |
| 853 | This suits a process that keeps a persistent cache keyed on the pair, and |
| 854 | a process that fetches the blobs itself (for example via |
| 855 | `git cat-file --batch`) to compute its own notion of the changed |
| 856 | lines. Pairs with a side that is not a stored blob (a working-tree |
| 857 | file, textconv output) are not sent; Git computes those itself. |
| 858 | |
| 859 | The exchange opens with a handshake: Git announces its role and |
| 860 | version, the process replies in kind, and then Git lists the |
| 861 | capabilities it supports and the process replies with the ones it |
| 862 | implements. A process that announces a capability Git did not list |
| 863 | aborts the command. |
| 864 | |
| 865 | ----------------------- |
| 866 | packet: git> git-diff-client |
| 867 | packet: git> version=1 |
| 868 | packet: git> 0000 |
| 869 | packet: git< git-diff-server |
| 870 | packet: git< version=1 |
| 871 | packet: git< 0000 |
| 872 | packet: git> capability=hunks-by-oid |
| 873 | packet: git> 0000 |
| 874 | packet: git< capability=hunks-by-oid |
| 875 | packet: git< 0000 |
| 876 | ----------------------- |
| 877 | |
| 878 | After the handshake, each request and response looks like: |
| 879 | |
| 880 | ----------------------- |
| 881 | packet: git> command=hunks-by-oid |
| 882 | packet: git> pathname=path/file.c |
| 883 | packet: git> old-oid=<hex> |
| 884 | packet: git> new-oid=<hex> |
| 885 | packet: git> 0000 |
| 886 | packet: git< hunk <old_start> <old_count> <new_start> <new_count> |
| 887 | packet: git< 0000 |
| 888 | packet: git< status=success |
| 889 | packet: git< 0000 |
| 890 | ----------------------- |
| 891 | |
| 892 | Start values are 1-based and counts are non-negative; a count of 0 |
| 893 | describes a pure insertion or deletion at the 1-based line the change |
| 894 | sits before (a start of 0 is accepted for an empty file side). Hunks |
| 895 | must be listed in order, must not overlap, and must keep the unchanged |
| 896 | runs between them the same length on both sides; Git validates this |
| 897 | and, with a warning, falls back to its builtin diff on a response |
| 898 | that violates these rules. |
| 899 | |
| 900 | A `status=success` response with zero hunks asserts that the blobs are |
| 901 | equivalent, including their trailing newlines. A process that cannot |
| 902 | answer a pair from its object names (or cannot rule out a |
| 903 | trailing-newline-only difference) responds `status=need-content`, and |
| 904 | Git produces that pair's diff itself. An asserted equivalence makes |
| 905 | the pair vanish from the summary formats, but the pair still counts |
| 906 | as changed for `--exit-code`, the same way a whitespace-only pair |
| 907 | does under `-w`. |
| 908 | |
| 909 | The status names the disposition of the whole request. Git |
| 910 | understands three: `success` (the hunk lines are the answer), |
| 911 | `need-content` (Git produces this pair's diff itself), and `abort`, which |
| 912 | withdraws the capability the request used: Git stops sending |
| 913 | `hunks-by-oid` requests to that process for the rest of the command, |
| 914 | while the process stays alive for request forms negotiated under |
| 915 | other capabilities. Any other status is a protocol error: Git warns, |
| 916 | stops the process, and uses the builtin diff for the remainder of the |
| 917 | command. |
| 918 | |
| 919 | Every response has the same shape whatever its status: zero or more |
| 920 | hunk lines, a flush packet, and a status packet terminated with a |
| 921 | flush packet. A response that carries no hunks, `need-content` |
| 922 | included, still begins with the empty hunk section's flush packet; a |
| 923 | bare status packet is a protocol error: |
| 924 | |
| 925 | ----------------------- |
| 926 | packet: git< 0000 |
| 927 | packet: git< status=need-content |
| 928 | packet: git< 0000 |
| 929 | ----------------------- |
| 930 | |
| 931 | The process must read the entire request before it responds; Git |
| 932 | writes the whole request before it reads the response. |
| 933 | |
| 934 | The protocol extends without breaking deployed processes: a process |
| 935 | must ignore request keys it does not recognize, and Git ignores |
| 936 | trailing space-separated tokens after the last field of a hunk line, |
| 937 | so a later protocol version can append request keys and hunk fields. |
| 938 | New request forms arrive as capabilities, which a process may decline |
| 939 | to announce; announcing a capability Git did not request aborts the |
| 940 | command, as it does under the long-running filter process protocol. |
| 941 | |
| 942 | There is no shutdown handshake: Git's side of the pipes closes when |
| 943 | the command exits, and the process should exit when it reads EOF. No |
| 944 | flush point is guaranteed, so a process that maintains persistent |
| 945 | state (such as a cache) should persist as it answers rather than at |
| 946 | exit. Git applies no timeout to a response; a process that hangs |
| 947 | hangs the command, as with the long-running filter processes. |
| 948 | |
| 949 | `git blame` and the `--stat`, `--numstat`, and `--shortstat` formats |
| 950 | consult the process; the textual patch and `git log -L` range |
| 951 | tracking are produced by the builtin machinery, so a process whose |
| 952 | answers deliberately differ from the builtin diff shows that |
| 953 | difference only in blame and those formats. `--dirstat=lines` routes |
| 954 | through the diffstat path and consults; the other `--dirstat` modes do |
| 955 | not. A merge's `--stat` (including under `--cc`) is computed against |
| 956 | the first parent, so it consults like any other stat; the combined |
| 957 | patch itself compares one merge result against all of its parents at |
| 958 | once, which the pairwise request above does not express, so that patch |
| 959 | uses the builtin diff, and extending the protocol to combined diffs is |
| 960 | left for future work. A content-carrying extension of this |
| 961 | protocol would bring patch output and `git log -L` range tracking to |
| 962 | the same answer. |
| 963 | |
| 964 | Consulting is allowed per command, as with textconv: `git diff`, |
| 965 | `git log` (`git whatchanged` included) and `git show`, and |
| 966 | `git blame` consult a configured process; the plumbing diff commands |
| 967 | do not unless `--ext-diff` or `--diff-process` is given explicitly, |
| 968 | and the interactive-patch commands (`git add -p` and friends), which |
| 969 | build the hunks they present from plumbing output, always stage from |
| 970 | the builtin diff. `git range-diff` generates the patches it |
| 971 | compares with `--no-ext-diff`. `--diff-process` and |
| 972 | `--no-diff-process` allow or forbid only the consulting; |
| 973 | `--no-ext-diff` disables all external diff mechanisms, this one |
| 974 | included. Options the process is never told about never select it: |
| 975 | with the whitespace-ignoring options, `--ignore-matching-lines`, and |
| 976 | `--anchored`, the pair is answered as when no process is configured. |
| 977 | `--diff-algorithm` (or a configured `diff.algorithm`) forces a builtin |
| 978 | algorithm and bypasses the process the same way. A per-path |
| 979 | ++diff.++__<driver>__++.algorithm++ does so for `git diff` and the stat |
| 980 | formats, which build their diff parameters from it; `git blame` builds |
| 981 | its parameters from its own diff options, so a per-driver algorithm |
| 982 | does not by itself keep blame from consulting the process. |
| 983 | `git format-patch` never |
| 984 | consults the process, so generated patches are always based on the |
| 985 | builtin diff and apply for recipients without the process. On a |
| 986 | path whose driver has a process, the process is consulted before the |
| 987 | diff-hunks store (see linkgit:git-diff-hunks[1]): a pair the process |
| 988 | answers is never served from the store and never recorded into it. |
| 989 | A pair the process does not answer, for example with |
| 990 | `status=need-content`, gets the builtin diff, so the store may serve |
| 991 | it and a warming run may record it: the store holds builtin results, |
| 992 | and for such a pair the builtin result is what would be computed |
| 993 | anyway. |
| 994 | |
| 995 | Defining a custom hunk-header |
| 996 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 997 | |
| 998 | Each group of changes (called a "hunk") in the textual diff output |
| 999 | is prefixed with a line of the form: |
| 1000 | |
| 1001 | @@ -k,l +n,m @@ TEXT |
| 1002 | |
| 1003 | This is called a 'hunk header'. The "TEXT" portion is by default a line |
| 1004 | that begins with an alphabet, an underscore or a dollar sign; this |
| 1005 | matches what GNU 'diff -p' output uses. This default selection however |
| 1006 | is not suited for some contents, and you can use a customized pattern |
| 1007 | to make a selection. |
| 1008 | |
| 1009 | First, in .gitattributes, you would assign the `diff` attribute |
| 1010 | for paths. |
| 1011 | |
| 1012 | ------------------------ |
| 1013 | *.tex diff=tex |
| 1014 | ------------------------ |
| 1015 | |
| 1016 | Then, you would define a "diff.tex.xfuncname" configuration to |
| 1017 | specify a regular expression that matches a line that you would |
| 1018 | want to appear as the hunk header "TEXT". Add a section to your |
| 1019 | `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: |
| 1020 | |
| 1021 | ------------------------ |
| 1022 | [diff "tex"] |
| 1023 | xfuncname = "^(\\\\(sub)*section\\{.*)$" |
| 1024 | ------------------------ |
| 1025 | |
| 1026 | Note. A single level of backslashes are eaten by the |
| 1027 | configuration file parser, so you would need to double the |
| 1028 | backslashes; the pattern above picks a line that begins with a |
| 1029 | backslash, and zero or more occurrences of `sub` followed by |
| 1030 | `section` followed by open brace, to the end of line. |
| 1031 | |
| 1032 | There are a few built-in patterns to make this easier, and `tex` |
| 1033 | is one of them, so you do not have to write the above in your |
| 1034 | configuration file (you still need to enable this with the |
| 1035 | attribute mechanism, via `.gitattributes`). The following built in |
| 1036 | patterns are available: |
| 1037 | |
| 1038 | - `ada` suitable for source code in the Ada language. |
| 1039 | |
| 1040 | - `bash` suitable for source code in the Bourne-Again SHell language. |
| 1041 | Covers a superset of POSIX shell function definitions. |
| 1042 | |
| 1043 | - `bibtex` suitable for files with BibTeX coded references. |
| 1044 | |
| 1045 | - `cpp` suitable for source code in the C and C++ languages. |
| 1046 | |
| 1047 | - `csharp` suitable for source code in the C# language. |
| 1048 | |
| 1049 | - `css` suitable for cascading style sheets. |
| 1050 | |
| 1051 | - `dts` suitable for devicetree (DTS) files. |
| 1052 | |
| 1053 | - `elixir` suitable for source code in the Elixir language. |
| 1054 | |
| 1055 | - `fortran` suitable for source code in the Fortran language. |
| 1056 | |
| 1057 | - `fountain` suitable for Fountain documents. |
| 1058 | |
| 1059 | - `golang` suitable for source code in the Go language. |
| 1060 | |
| 1061 | - `html` suitable for HTML/XHTML documents. |
| 1062 | |
| 1063 | - `java` suitable for source code in the Java language. |
| 1064 | |
| 1065 | - `kotlin` suitable for source code in the Kotlin language. |
| 1066 | |
| 1067 | - `markdown` suitable for Markdown documents. |
| 1068 | |
| 1069 | - `matlab` suitable for source code in the MATLAB and Octave languages. |
| 1070 | |
| 1071 | - `objc` suitable for source code in the Objective-C language. |
| 1072 | |
| 1073 | - `pascal` suitable for source code in the Pascal/Delphi language. |
| 1074 | |
| 1075 | - `perl` suitable for source code in the Perl language. |
| 1076 | |
| 1077 | - `php` suitable for source code in the PHP language. |
| 1078 | |
| 1079 | - `python` suitable for source code in the Python language. |
| 1080 | |
| 1081 | - `ruby` suitable for source code in the Ruby language. |
| 1082 | |
| 1083 | - `rust` suitable for source code in the Rust language. |
| 1084 | |
| 1085 | - `scheme` suitable for source code in most Lisp dialects, |
| 1086 | including Scheme, Emacs Lisp, Common Lisp, and Clojure. |
| 1087 | |
| 1088 | - `swift` suitable for source code in the Swift language. |
| 1089 | |
| 1090 | - `tex` suitable for source code for LaTeX documents. |
| 1091 | |
| 1092 | |
| 1093 | Customizing word diff |
| 1094 | ^^^^^^^^^^^^^^^^^^^^^ |
| 1095 | |
| 1096 | You can customize the rules that `git diff --word-diff` uses to |
| 1097 | split words in a line, by specifying an appropriate regular expression |
| 1098 | in the "diff.*.wordRegex" configuration variable. For example, in TeX |
| 1099 | a backslash followed by a sequence of letters forms a command, but |
| 1100 | several such commands can be run together without intervening |
| 1101 | whitespace. To separate them, use a regular expression in your |
| 1102 | `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: |
| 1103 | |
| 1104 | ------------------------ |
| 1105 | [diff "tex"] |
| 1106 | wordRegex = "\\\\[a-zA-Z]+|[{}]|\\\\.|[^\\{}[:space:]]+" |
| 1107 | ------------------------ |
| 1108 | |
| 1109 | A built-in pattern is provided for all languages listed in the |
| 1110 | previous section. |
| 1111 | |
| 1112 | |
| 1113 | Performing text diffs of binary files |
| 1114 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 1115 | |
| 1116 | Sometimes it is desirable to see the diff of a text-converted |
| 1117 | version of some binary files. For example, a word processor |
| 1118 | document can be converted to an ASCII text representation, and |
| 1119 | the diff of the text shown. Even though this conversion loses |
| 1120 | some information, the resulting diff is useful for human |
| 1121 | viewing (but cannot be applied directly). |
| 1122 | |
| 1123 | The `textconv` config option is used to define a program for |
| 1124 | performing such a conversion. The program should take a single |
| 1125 | argument, the name of a file to convert, and produce the |
| 1126 | resulting text on stdout. |
| 1127 | |
| 1128 | For example, to show the diff of the exif information of a |
| 1129 | file instead of the binary information (assuming you have the |
| 1130 | exif tool installed), add the following section to your |
| 1131 | `$GIT_DIR/config` file (or `$HOME/.gitconfig` file): |
| 1132 | |
| 1133 | ------------------------ |
| 1134 | [diff "jpg"] |
| 1135 | textconv = exif |
| 1136 | ------------------------ |
| 1137 | |
| 1138 | NOTE: The text conversion is generally a one-way conversion; |
| 1139 | in this example, we lose the actual image contents and focus |
| 1140 | just on the text data. This means that diffs generated by |
| 1141 | textconv are _not_ suitable for applying. For this reason, |
| 1142 | only `git diff` and the `git log` family of commands (i.e., |
| 1143 | log, whatchanged, show) will perform text conversion. `git |
| 1144 | format-patch` will never generate this output. If you want to |
| 1145 | send somebody a text-converted diff of a binary file (e.g., |
| 1146 | because it quickly conveys the changes you have made), you |
| 1147 | should generate it separately and send it as a comment _in |
| 1148 | addition to_ the usual binary diff that you might send. |
| 1149 | |
| 1150 | Because text conversion can be slow, especially when doing a |
| 1151 | large number of them with `git log -p`, Git provides a mechanism |
| 1152 | to cache the output and use it in future diffs. To enable |
| 1153 | caching, set the "cachetextconv" variable in your diff driver's |
| 1154 | config. For example: |
| 1155 | |
| 1156 | ------------------------ |
| 1157 | [diff "jpg"] |
| 1158 | textconv = exif |
| 1159 | cachetextconv = true |
| 1160 | ------------------------ |
| 1161 | |
| 1162 | This will cache the result of running "exif" on each blob |
| 1163 | indefinitely. If you change the textconv config variable for a |
| 1164 | diff driver, Git will automatically invalidate the cache entries |
| 1165 | and re-run the textconv filter. If you want to invalidate the |
| 1166 | cache manually (e.g., because your version of "exif" was updated |
| 1167 | and now produces better output), you can remove the cache |
| 1168 | manually with `git update-ref -d refs/notes/textconv/jpg` (where |
| 1169 | "jpg" is the name of the diff driver, as in the example above). |
| 1170 | |
| 1171 | Choosing textconv versus external diff |
| 1172 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 1173 | |
| 1174 | If you want to show differences between binary or specially-formatted |
| 1175 | blobs in your repository, you can choose to use either an external diff |
| 1176 | command, or to use textconv to convert them to a diff-able text format. |
| 1177 | Which method you choose depends on your exact situation. |
| 1178 | |
| 1179 | The advantage of using an external diff command is flexibility. You are |
| 1180 | not bound to find line-oriented changes, nor is it necessary for the |
| 1181 | output to resemble unified diff. You are free to locate and report |
| 1182 | changes in the most appropriate way for your data format. |
| 1183 | |
| 1184 | A textconv, by comparison, is much more limiting. You provide a |
| 1185 | transformation of the data into a line-oriented text format, and Git |
| 1186 | uses its regular diff tools to generate the output. There are several |
| 1187 | advantages to choosing this method: |
| 1188 | |
| 1189 | 1. Ease of use. It is often much simpler to write a binary to text |
| 1190 | transformation than it is to perform your own diff. In many cases, |
| 1191 | existing programs can be used as textconv filters (e.g., exif, |
| 1192 | odt2txt). |
| 1193 | |
| 1194 | 2. Git diff features. By performing only the transformation step |
| 1195 | yourself, you can still utilize many of Git's diff features, |
| 1196 | including colorization, word-diff, and combined diffs for merges. |
| 1197 | |
| 1198 | 3. Caching. Textconv caching can speed up repeated diffs, such as those |
| 1199 | you might trigger by running `git log -p`. |
| 1200 | |
| 1201 | |
| 1202 | Marking files as binary |
| 1203 | ^^^^^^^^^^^^^^^^^^^^^^^ |
| 1204 | |
| 1205 | Git usually guesses correctly whether a blob contains text or binary |
| 1206 | data by examining the beginning of the contents. However, sometimes you |
| 1207 | may want to override its decision, either because a blob contains binary |
| 1208 | data later in the file, or because the content, while technically |
| 1209 | composed of text characters, is opaque to a human reader. For example, |
| 1210 | many postscript files contain only ASCII characters, but produce noisy |
| 1211 | and meaningless diffs. |
| 1212 | |
| 1213 | The simplest way to mark a file as binary is to unset the diff |
| 1214 | attribute in the `.gitattributes` file: |
| 1215 | |
| 1216 | ------------------------ |
| 1217 | *.ps -diff |
| 1218 | ------------------------ |
| 1219 | |
| 1220 | This will cause Git to generate `Binary files differ` (or a binary |
| 1221 | patch, if binary patches are enabled) instead of a regular diff. |
| 1222 | |
| 1223 | However, one may also want to specify other diff driver attributes. For |
| 1224 | example, you might want to use `textconv` to convert postscript files to |
| 1225 | an ASCII representation for human viewing, but otherwise treat them as |
| 1226 | binary files. You cannot specify both `-diff` and `diff=ps` attributes. |
| 1227 | The solution is to use the `diff.*.binary` config option: |
| 1228 | |
| 1229 | ------------------------ |
| 1230 | [diff "ps"] |
| 1231 | textconv = ps2ascii |
| 1232 | binary = true |
| 1233 | ------------------------ |
| 1234 | |
| 1235 | Performing a three-way merge |
| 1236 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1237 | |
| 1238 | `merge` |
| 1239 | ^^^^^^^ |
| 1240 | |
| 1241 | The attribute `merge` affects how three versions of a file are |
| 1242 | merged when a file-level merge is necessary during `git merge`, |
| 1243 | and other commands such as `git revert` and `git cherry-pick`. |
| 1244 | |
| 1245 | Set:: |
| 1246 | |
| 1247 | Built-in 3-way merge driver is used to merge the |
| 1248 | contents in a way similar to 'merge' command of `RCS` |
| 1249 | suite. This is suitable for ordinary text files. |
| 1250 | |
| 1251 | Unset:: |
| 1252 | |
| 1253 | Take the version from the current branch as the |
| 1254 | tentative merge result, and declare that the merge has |
| 1255 | conflicts. This is suitable for binary files that do |
| 1256 | not have a well-defined merge semantics. |
| 1257 | |
| 1258 | Unspecified:: |
| 1259 | |
| 1260 | By default, this uses the same built-in 3-way merge |
| 1261 | driver as is the case when the `merge` attribute is set. |
| 1262 | However, the `merge.default` configuration variable can name |
| 1263 | different merge driver to be used with paths for which the |
| 1264 | `merge` attribute is unspecified. |
| 1265 | |
| 1266 | String:: |
| 1267 | |
| 1268 | 3-way merge is performed using the specified custom |
| 1269 | merge driver. The built-in 3-way merge driver can be |
| 1270 | explicitly specified by asking for "text" driver; the |
| 1271 | built-in "take the current branch" driver can be |
| 1272 | requested with "binary". |
| 1273 | |
| 1274 | |
| 1275 | Built-in merge drivers |
| 1276 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 1277 | |
| 1278 | There are a few built-in low-level merge drivers defined that |
| 1279 | can be asked for via the `merge` attribute. |
| 1280 | |
| 1281 | text:: |
| 1282 | |
| 1283 | Usual 3-way file level merge for text files. Conflicted |
| 1284 | regions are marked with conflict markers `<<<<<<<`, |
| 1285 | `=======` and `>>>>>>>`. The version from your branch |
| 1286 | appears before the `=======` marker, and the version |
| 1287 | from the merged branch appears after the `=======` |
| 1288 | marker. |
| 1289 | |
| 1290 | binary:: |
| 1291 | |
| 1292 | Keep the version from your branch in the work tree, but |
| 1293 | leave the path in the conflicted state for the user to |
| 1294 | sort out. |
| 1295 | |
| 1296 | union:: |
| 1297 | |
| 1298 | Run 3-way file level merge for text files, but take |
| 1299 | lines from both versions, instead of leaving conflict |
| 1300 | markers. This tends to leave the added lines in the |
| 1301 | resulting file in random order and the user should |
| 1302 | verify the result. Do not use this if you do not |
| 1303 | understand the implications. |
| 1304 | |
| 1305 | |
| 1306 | Defining a custom merge driver |
| 1307 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 1308 | |
| 1309 | The definition of a merge driver is done in the `.git/config` |
| 1310 | file, not in the `gitattributes` file, so strictly speaking this |
| 1311 | manual page is a wrong place to talk about it. However... |
| 1312 | |
| 1313 | To define a custom merge driver `filfre`, add a section to your |
| 1314 | `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: |
| 1315 | |
| 1316 | ---------------------------------------------------------------- |
| 1317 | [merge "filfre"] |
| 1318 | name = feel-free merge driver |
| 1319 | driver = filfre %O %A %B %L %P |
| 1320 | recursive = binary |
| 1321 | ---------------------------------------------------------------- |
| 1322 | |
| 1323 | The `merge.*.name` variable gives the driver a human-readable |
| 1324 | name. |
| 1325 | |
| 1326 | The `merge.*.driver` variable's value is used to construct a |
| 1327 | command to run to common ancestor's version (`%O`), current |
| 1328 | version (`%A`) and the other branches' version (`%B`). These |
| 1329 | three tokens are replaced with the names of temporary files that |
| 1330 | hold the contents of these versions when the command line is |
| 1331 | built. Additionally, `%L` will be replaced with the conflict marker |
| 1332 | size (see below). |
| 1333 | |
| 1334 | The merge driver is expected to leave the result of the merge in |
| 1335 | the file named with `%A` by overwriting it, and exit with zero |
| 1336 | status if it managed to merge them cleanly, or non-zero if there |
| 1337 | were conflicts. When the driver crashes (e.g. killed by SEGV), |
| 1338 | it is expected to exit with non-zero status that are higher than |
| 1339 | 128, and in such a case, the merge results in a failure (which is |
| 1340 | different from producing a conflict). |
| 1341 | |
| 1342 | The `merge.*.recursive` variable specifies what other merge |
| 1343 | driver to use when the merge driver is called for an internal |
| 1344 | merge between common ancestors, when there are more than one. |
| 1345 | When left unspecified, the driver itself is used for both |
| 1346 | internal merge and the final merge. |
| 1347 | |
| 1348 | The merge driver can learn the pathname in which the merged result |
| 1349 | will be stored via placeholder `%P`. The conflict labels to be used |
| 1350 | for the common ancestor, local head and other head can be passed by |
| 1351 | using `%S`, `%X` and `%Y` respectively. |
| 1352 | |
| 1353 | `conflict-marker-size` |
| 1354 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 1355 | |
| 1356 | This attribute controls the length of conflict markers left in |
| 1357 | the work tree file during a conflicted merge. Only a positive |
| 1358 | integer has a meaningful effect. |
| 1359 | |
| 1360 | For example, this line in `.gitattributes` can be used to tell the merge |
| 1361 | machinery to leave much longer (instead of the usual 7-character-long) |
| 1362 | conflict markers when merging the file `Documentation/git-merge.adoc` |
| 1363 | results in a conflict. |
| 1364 | |
| 1365 | ------------------------ |
| 1366 | Documentation/git-merge.adoc conflict-marker-size=32 |
| 1367 | ------------------------ |
| 1368 | |
| 1369 | |
| 1370 | Checking whitespace errors |
| 1371 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1372 | |
| 1373 | `whitespace` |
| 1374 | ^^^^^^^^^^^^ |
| 1375 | |
| 1376 | The `core.whitespace` configuration variable allows you to define what |
| 1377 | 'diff' and 'apply' should consider whitespace errors for all paths in |
| 1378 | the project (See linkgit:git-config[1]). This attribute gives you finer |
| 1379 | control per path. |
| 1380 | |
| 1381 | Set:: |
| 1382 | |
| 1383 | Notice all types of potential whitespace errors known to Git. |
| 1384 | The tab width is taken from the value of the `core.whitespace` |
| 1385 | configuration variable. |
| 1386 | |
| 1387 | Unset:: |
| 1388 | |
| 1389 | Do not notice anything as error. |
| 1390 | |
| 1391 | Unspecified:: |
| 1392 | |
| 1393 | Use the value of the `core.whitespace` configuration variable to |
| 1394 | decide what to notice as error. |
| 1395 | |
| 1396 | String:: |
| 1397 | |
| 1398 | Specify a comma separated list of common whitespace problems to |
| 1399 | notice in the same format as the `core.whitespace` configuration |
| 1400 | variable. |
| 1401 | |
| 1402 | |
| 1403 | Creating an archive |
| 1404 | ~~~~~~~~~~~~~~~~~~~ |
| 1405 | |
| 1406 | `export-ignore` |
| 1407 | ^^^^^^^^^^^^^^^ |
| 1408 | |
| 1409 | Files and directories with the attribute `export-ignore` won't be added to |
| 1410 | archive files. |
| 1411 | |
| 1412 | `export-subst` |
| 1413 | ^^^^^^^^^^^^^^ |
| 1414 | |
| 1415 | If the attribute `export-subst` is set for a file then Git will expand |
| 1416 | several placeholders when adding this file to an archive. The |
| 1417 | expansion depends on the availability of a commit ID, i.e., if |
| 1418 | linkgit:git-archive[1] has been given a tree instead of a commit or a |
| 1419 | tag then no replacement will be done. The placeholders are the same |
| 1420 | as those for the option `--pretty=format:` of linkgit:git-log[1], |
| 1421 | except that they need to be wrapped like this: `$Format:PLACEHOLDERS$` |
| 1422 | in the file. E.g. the string `$Format:%H$` will be replaced by the |
| 1423 | commit hash. However, only one `%(describe)` placeholder is expanded |
| 1424 | per archive to avoid denial-of-service attacks. |
| 1425 | |
| 1426 | |
| 1427 | Packing objects |
| 1428 | ~~~~~~~~~~~~~~~ |
| 1429 | |
| 1430 | `delta` |
| 1431 | ^^^^^^^ |
| 1432 | |
| 1433 | Delta compression will not be attempted for blobs for paths with the |
| 1434 | attribute `delta` set to false. |
| 1435 | |
| 1436 | |
| 1437 | Viewing files in GUI tools |
| 1438 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1439 | |
| 1440 | `encoding` |
| 1441 | ^^^^^^^^^^ |
| 1442 | |
| 1443 | The value of this attribute specifies the character encoding that should |
| 1444 | be used by GUI tools (e.g. linkgit:gitk[1] and linkgit:git-gui[1]) to |
| 1445 | display the contents of the relevant file. Note that due to performance |
| 1446 | considerations linkgit:gitk[1] does not use this attribute unless you |
| 1447 | manually enable per-file encodings in its options. |
| 1448 | |
| 1449 | If this attribute is not set or has an invalid value, the value of the |
| 1450 | `gui.encoding` configuration variable is used instead |
| 1451 | (See linkgit:git-config[1]). |
| 1452 | |
| 1453 | |
| 1454 | USING MACRO ATTRIBUTES |
| 1455 | ---------------------- |
| 1456 | |
| 1457 | You do not want any end-of-line conversions applied to, nor textual diffs |
| 1458 | produced for, any binary file you track. You would need to specify e.g. |
| 1459 | |
| 1460 | ------------ |
| 1461 | *.jpg -text -diff |
| 1462 | ------------ |
| 1463 | |
| 1464 | but that may become cumbersome, when you have many attributes. Using |
| 1465 | macro attributes, you can define an attribute that, when set, also |
| 1466 | sets or unsets a number of other attributes at the same time. The |
| 1467 | system knows a built-in macro attribute, `binary`: |
| 1468 | |
| 1469 | ------------ |
| 1470 | *.jpg binary |
| 1471 | ------------ |
| 1472 | |
| 1473 | Setting the "binary" attribute also unsets the "text" and "diff" |
| 1474 | attributes as above. Note that macro attributes can only be "Set", |
| 1475 | though setting one might have the effect of setting or unsetting other |
| 1476 | attributes or even returning other attributes to the "Unspecified" |
| 1477 | state. |
| 1478 | |
| 1479 | |
| 1480 | DEFINING MACRO ATTRIBUTES |
| 1481 | ------------------------- |
| 1482 | |
| 1483 | Custom macro attributes can be defined only in top-level gitattributes |
| 1484 | files (`$GIT_DIR/info/attributes`, the `.gitattributes` file at the |
| 1485 | top level of the working tree, or the global or system-wide |
| 1486 | gitattributes files), not in `.gitattributes` files in working tree |
| 1487 | subdirectories. The built-in macro attribute "binary" is equivalent |
| 1488 | to: |
| 1489 | |
| 1490 | ------------ |
| 1491 | [attr]binary -diff -merge -text |
| 1492 | ------------ |
| 1493 | |
| 1494 | NOTES |
| 1495 | ----- |
| 1496 | |
| 1497 | Git does not follow symbolic links when accessing a `.gitattributes` |
| 1498 | file in the working tree. This keeps behavior consistent when the file |
| 1499 | is accessed from the index or a tree versus from the filesystem. |
| 1500 | |
| 1501 | EXAMPLES |
| 1502 | -------- |
| 1503 | |
| 1504 | If you have these three `gitattributes` file: |
| 1505 | |
| 1506 | ---------------------------------------------------------------- |
| 1507 | (in $GIT_DIR/info/attributes) |
| 1508 | |
| 1509 | a* foo !bar -baz |
| 1510 | |
| 1511 | (in .gitattributes) |
| 1512 | abc foo bar baz |
| 1513 | |
| 1514 | (in t/.gitattributes) |
| 1515 | ab* merge=filfre |
| 1516 | abc -foo -bar |
| 1517 | *.c frotz |
| 1518 | ---------------------------------------------------------------- |
| 1519 | |
| 1520 | the attributes given to path `t/abc` are computed as follows: |
| 1521 | |
| 1522 | 1. By examining `t/.gitattributes` (which is in the same |
| 1523 | directory as the path in question), Git finds that the first |
| 1524 | line matches. `merge` attribute is set. It also finds that |
| 1525 | the second line matches, and attributes `foo` and `bar` |
| 1526 | are unset. |
| 1527 | |
| 1528 | 2. Then it examines `.gitattributes` (which is in the parent |
| 1529 | directory), and finds that the first line matches, but |
| 1530 | `t/.gitattributes` file already decided how `merge`, `foo` |
| 1531 | and `bar` attributes should be given to this path, so it |
| 1532 | leaves `foo` and `bar` unset. Attribute `baz` is set. |
| 1533 | |
| 1534 | 3. Finally it examines `$GIT_DIR/info/attributes`. This file |
| 1535 | is used to override the in-tree settings. The first line is |
| 1536 | a match, and `foo` is set, `bar` is reverted to unspecified |
| 1537 | state, and `baz` is unset. |
| 1538 | |
| 1539 | As the result, the attributes assignment to `t/abc` becomes: |
| 1540 | |
| 1541 | ---------------------------------------------------------------- |
| 1542 | foo set to true |
| 1543 | bar unspecified |
| 1544 | baz set to false |
| 1545 | merge set to string value "filfre" |
| 1546 | frotz unspecified |
| 1547 | ---------------------------------------------------------------- |
| 1548 | |
| 1549 | |
| 1550 | SEE ALSO |
| 1551 | -------- |
| 1552 | linkgit:git-check-attr[1]. |
| 1553 | |
| 1554 | GIT |
| 1555 | --- |
| 1556 | Part of the linkgit:git[1] suite |