1gitattributes(5) 2================ 3 4NAME 5---- 6gitattributes - defining attributes per path 7 8SYNOPSIS 9-------- 10$GIT_DIR/info/attributes, .gitattributes 11 12 13DESCRIPTION 14----------- 15 16A `gitattributes` file is a simple text file that gives 17`attributes` to pathnames. 18 19Each line in `gitattributes` file is of form: 20 21 pattern attr1 attr2 ... 22 23That is, a pattern followed by an attributes list, 24separated by whitespaces. When the pattern matches the 25path in question, the attributes listed on the line are given to 26the path. 27 28Each attribute can be in one of these states for a given path: 29 30Set:: 31 32 The path has the attribute with special value "true"; 33 this is specified by listing only the name of the 34 attribute in the attribute list. 35 36Unset:: 37 38 The path has the attribute with special value "false"; 39 this is specified by listing the name of the attribute 40 prefixed with a dash `-` in the attribute list. 41 42Set to a value:: 43 44 The path has the attribute with specified string value; 45 this is specified by listing the name of the attribute 46 followed by an equal sign `=` and its value in the 47 attribute list. 48 49Unspecified:: 50 51 No pattern matches the path, and nothing says if 52 the path has or does not have the attribute, the 53 attribute for the path is said to be Unspecified. 54 55When more than one pattern matches the path, a later line 56overrides an earlier line. This overriding is done per 57attribute. The rules how the pattern matches paths are the 58same as in `.gitignore` files; see linkgit:gitignore[5]. 59 60When deciding what attributes are assigned to a path, git 61consults `$GIT_DIR/info/attributes` file (which has the highest 62precedence), `.gitattributes` file in the same directory as the 63path in question, and its parent directories up to the toplevel of the 64work tree (the further the directory that contains `.gitattributes` 65is from the path in question, the lower its precedence). 66 67If you wish to affect only a single repository (i.e., to assign 68attributes to files that are particular to one user's workflow), then 69attributes should be placed in the `$GIT_DIR/info/attributes` file. 70Attributes which should be version-controlled and distributed to other 71repositories (i.e., attributes of interest to all users) should go into 72`.gitattributes` files. 73 74Sometimes you would need to override an setting of an attribute 75for a path to `unspecified` state. This can be done by listing 76the name of the attribute prefixed with an exclamation point `!`. 77 78 79EFFECTS 80------- 81 82Certain operations by git can be influenced by assigning 83particular attributes to a path. Currently, the following 84operations are attributes-aware. 85 86Checking-out and checking-in 87~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 88 89These attributes affect how the contents stored in the 90repository are copied to the working tree files when commands 91such as 'git checkout' and 'git merge' run. They also affect how 92git stores the contents you prepare in the working tree in the 93repository upon 'git add' and 'git commit'. 94 95`crlf` 96^^^^^^ 97 98This attribute controls the line-ending convention. 99 100Set:: 101 102 Setting the `crlf` attribute on a path is meant to mark 103 the path as a "text" file. 'core.autocrlf' conversion 104 takes place without guessing the content type by 105 inspection. 106 107Unset:: 108 109 Unsetting the `crlf` attribute on a path tells git not to 110 attempt any end-of-line conversion upon checkin or checkout. 111 112Unspecified:: 113 114 Unspecified `crlf` attribute tells git to apply the 115 `core.autocrlf` conversion when the file content looks 116 like text. 117 118Set to string value "input":: 119 120 This is similar to setting the attribute to `true`, but 121 also forces git to act as if `core.autocrlf` is set to 122 `input` for the path. 123 124Any other value set to `crlf` attribute is ignored and git acts 125as if the attribute is left unspecified. 126 127 128The `core.autocrlf` conversion 129^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 130 131If the configuration variable `core.autocrlf` is false, no 132conversion is done. 133 134When `core.autocrlf` is true, it means that the platform wants 135CRLF line endings for files in the working tree, and you want to 136convert them back to the normal LF line endings when checking 137in to the repository. 138 139When `core.autocrlf` is set to "input", line endings are 140converted to LF upon checkin, but there is no conversion done 141upon checkout. 142 143If `core.safecrlf` is set to "true" or "warn", git verifies if 144the conversion is reversible for the current setting of 145`core.autocrlf`. For "true", git rejects irreversible 146conversions; for "warn", git only prints a warning but accepts 147an irreversible conversion. The safety triggers to prevent such 148a conversion done to the files in the work tree, but there are a 149few exceptions. Even though... 150 151- 'git add' itself does not touch the files in the work tree, the 152 next checkout would, so the safety triggers; 153 154- 'git apply' to update a text file with a patch does touch the files 155 in the work tree, but the operation is about text files and CRLF 156 conversion is about fixing the line ending inconsistencies, so the 157 safety does not trigger; 158 159- 'git diff' itself does not touch the files in the work tree, it is 160 often run to inspect the changes you intend to next 'git add'. To 161 catch potential problems early, safety triggers. 162 163 164`ident` 165^^^^^^^ 166 167When the attribute `ident` is set for a path, git replaces 168`$Id$` in the blob object with `$Id:`, followed by the 16940-character hexadecimal blob object name, followed by a dollar 170sign `$` upon checkout. Any byte sequence that begins with 171`$Id:` and ends with `$` in the worktree file is replaced 172with `$Id$` upon check-in. 173 174 175`filter` 176^^^^^^^^ 177 178A `filter` attribute can be set to a string value that names a 179filter driver specified in the configuration. 180 181A filter driver consists of a `clean` command and a `smudge` 182command, either of which can be left unspecified. Upon 183checkout, when the `smudge` command is specified, the command is 184fed the blob object from its standard input, and its standard 185output is used to update the worktree file. Similarly, the 186`clean` command is used to convert the contents of worktree file 187upon checkin. 188 189A missing filter driver definition in the config is not an error 190but makes the filter a no-op passthru. 191 192The content filtering is done to massage the content into a 193shape that is more convenient for the platform, filesystem, and 194the user to use. The key phrase here is "more convenient" and not 195"turning something unusable into usable". In other words, the 196intent is that if someone unsets the filter driver definition, 197or does not have the appropriate filter program, the project 198should still be usable. 199 200For example, in .gitattributes, you would assign the `filter` 201attribute for paths. 202 203------------------------ 204*.c filter=indent 205------------------------ 206 207Then you would define a "filter.indent.clean" and "filter.indent.smudge" 208configuration in your .git/config to specify a pair of commands to 209modify the contents of C programs when the source files are checked 210in ("clean" is run) and checked out (no change is made because the 211command is "cat"). 212 213------------------------ 214[filter "indent"] 215 clean = indent 216 smudge = cat 217------------------------ 218 219 220Interaction between checkin/checkout attributes 221^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 222 223In the check-in codepath, the worktree file is first converted 224with `filter` driver (if specified and corresponding driver 225defined), then the result is processed with `ident` (if 226specified), and then finally with `crlf` (again, if specified 227and applicable). 228 229In the check-out codepath, the blob content is first converted 230with `crlf`, and then `ident` and fed to `filter`. 231 232 233Generating diff text 234~~~~~~~~~~~~~~~~~~~~ 235 236`diff` 237^^^^^^ 238 239The attribute `diff` affects how 'git' generates diffs for particular 240files. It can tell git whether to generate a textual patch for the path 241or to treat the path as a binary file. It can also affect what line is 242shown on the hunk header `@@ -k,l +n,m @@` line, tell git to use an 243external command to generate the diff, or ask git to convert binary 244files to a text format before generating the diff. 245 246Set:: 247 248 A path to which the `diff` attribute is set is treated 249 as text, even when they contain byte values that 250 normally never appear in text files, such as NUL. 251 252Unset:: 253 254 A path to which the `diff` attribute is unset will 255 generate `Binary files differ` (or a binary patch, if 256 binary patches are enabled). 257 258Unspecified:: 259 260 A path to which the `diff` attribute is unspecified 261 first gets its contents inspected, and if it looks like 262 text, it is treated as text. Otherwise it would 263 generate `Binary files differ`. 264 265String:: 266 267 Diff is shown using the specified diff driver. Each driver may 268 specify one or more options, as described in the following 269 section. The options for the diff driver "foo" are defined 270 by the configuration variables in the "diff.foo" section of the 271 git config file. 272 273 274Defining an external diff driver 275^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 276 277The definition of a diff driver is done in `gitconfig`, not 278`gitattributes` file, so strictly speaking this manual page is a 279wrong place to talk about it. However... 280 281To define an external diff driver `jcdiff`, add a section to your 282`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 283 284---------------------------------------------------------------- 285[diff "jcdiff"] 286 command = j-c-diff 287---------------------------------------------------------------- 288 289When git needs to show you a diff for the path with `diff` 290attribute set to `jcdiff`, it calls the command you specified 291with the above configuration, i.e. `j-c-diff`, with 7 292parameters, just like `GIT_EXTERNAL_DIFF` program is called. 293See linkgit:git[1] for details. 294 295 296Defining a custom hunk-header 297^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 298 299Each group of changes (called a "hunk") in the textual diff output 300is prefixed with a line of the form: 301 302 @@ -k,l +n,m @@ TEXT 303 304This is called a 'hunk header'. The "TEXT" portion is by default a line 305that begins with an alphabet, an underscore or a dollar sign; this 306matches what GNU 'diff -p' output uses. This default selection however 307is not suited for some contents, and you can use a customized pattern 308to make a selection. 309 310First, in .gitattributes, you would assign the `diff` attribute 311for paths. 312 313------------------------ 314*.tex diff=tex 315------------------------ 316 317Then, you would define a "diff.tex.xfuncname" configuration to 318specify a regular expression that matches a line that you would 319want to appear as the hunk header "TEXT". Add a section to your 320`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 321 322------------------------ 323[diff "tex"] 324 xfuncname = "^(\\\\(sub)*section\\{.*)$" 325------------------------ 326 327Note. A single level of backslashes are eaten by the 328configuration file parser, so you would need to double the 329backslashes; the pattern above picks a line that begins with a 330backslash, and zero or more occurrences of `sub` followed by 331`section` followed by open brace, to the end of line. 332 333There are a few built-in patterns to make this easier, and `tex` 334is one of them, so you do not have to write the above in your 335configuration file (you still need to enable this with the 336attribute mechanism, via `.gitattributes`). The following built in 337patterns are available: 338 339- `bibtex` suitable for files with BibTeX coded references. 340 341- `cpp` suitable for source code in the C and C++ languages. 342 343- `html` suitable for HTML/XHTML documents. 344 345- `java` suitable for source code in the Java language. 346 347- `objc` suitable for source code in the Objective-C language. 348 349- `pascal` suitable for source code in the Pascal/Delphi language. 350 351- `php` suitable for source code in the PHP language. 352 353- `python` suitable for source code in the Python language. 354 355- `ruby` suitable for source code in the Ruby language. 356 357- `tex` suitable for source code for LaTeX documents. 358 359 360Customizing word diff 361^^^^^^^^^^^^^^^^^^^^^ 362 363You can customize the rules that `git diff --word-diff` uses to 364split words in a line, by specifying an appropriate regular expression 365in the "diff.*.wordRegex" configuration variable. For example, in TeX 366a backslash followed by a sequence of letters forms a command, but 367several such commands can be run together without intervening 368whitespace. To separate them, use a regular expression in your 369`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 370 371------------------------ 372[diff "tex"] 373 wordRegex = "\\\\[a-zA-Z]+|[{}]|\\\\.|[^\\{}[:space:]]+" 374------------------------ 375 376A built-in pattern is provided for all languages listed in the 377previous section. 378 379 380Performing text diffs of binary files 381^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 382 383Sometimes it is desirable to see the diff of a text-converted 384version of some binary files. For example, a word processor 385document can be converted to an ASCII text representation, and 386the diff of the text shown. Even though this conversion loses 387some information, the resulting diff is useful for human 388viewing (but cannot be applied directly). 389 390The `textconv` config option is used to define a program for 391performing such a conversion. The program should take a single 392argument, the name of a file to convert, and produce the 393resulting text on stdout. 394 395For example, to show the diff of the exif information of a 396file instead of the binary information (assuming you have the 397exif tool installed), add the following section to your 398`$GIT_DIR/config` file (or `$HOME/.gitconfig` file): 399 400------------------------ 401[diff "jpg"] 402 textconv = exif 403------------------------ 404 405NOTE: The text conversion is generally a one-way conversion; 406in this example, we lose the actual image contents and focus 407just on the text data. This means that diffs generated by 408textconv are _not_ suitable for applying. For this reason, 409only `git diff` and the `git log` family of commands (i.e., 410log, whatchanged, show) will perform text conversion. `git 411format-patch` will never generate this output. If you want to 412send somebody a text-converted diff of a binary file (e.g., 413because it quickly conveys the changes you have made), you 414should generate it separately and send it as a comment _in 415addition to_ the usual binary diff that you might send. 416 417Because text conversion can be slow, especially when doing a 418large number of them with `git log -p`, git provides a mechanism 419to cache the output and use it in future diffs. To enable 420caching, set the "cachetextconv" variable in your diff driver's 421config. For example: 422 423------------------------ 424[diff "jpg"] 425 textconv = exif 426 cachetextconv = true 427------------------------ 428 429This will cache the result of running "exif" on each blob 430indefinitely. If you change the textconv config variable for a 431diff driver, git will automatically invalidate the cache entries 432and re-run the textconv filter. If you want to invalidate the 433cache manually (e.g., because your version of "exif" was updated 434and now produces better output), you can remove the cache 435manually with `git update-ref -d refs/notes/textconv/jpg` (where 436"jpg" is the name of the diff driver, as in the example above). 437 438Performing a three-way merge 439~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 440 441`merge` 442^^^^^^^ 443 444The attribute `merge` affects how three versions of a file is 445merged when a file-level merge is necessary during `git merge`, 446and other commands such as `git revert` and `git cherry-pick`. 447 448Set:: 449 450 Built-in 3-way merge driver is used to merge the 451 contents in a way similar to 'merge' command of `RCS` 452 suite. This is suitable for ordinary text files. 453 454Unset:: 455 456 Take the version from the current branch as the 457 tentative merge result, and declare that the merge has 458 conflicts. This is suitable for binary files that does 459 not have a well-defined merge semantics. 460 461Unspecified:: 462 463 By default, this uses the same built-in 3-way merge 464 driver as is the case the `merge` attribute is set. 465 However, `merge.default` configuration variable can name 466 different merge driver to be used for paths to which the 467 `merge` attribute is unspecified. 468 469String:: 470 471 3-way merge is performed using the specified custom 472 merge driver. The built-in 3-way merge driver can be 473 explicitly specified by asking for "text" driver; the 474 built-in "take the current branch" driver can be 475 requested with "binary". 476 477 478Built-in merge drivers 479^^^^^^^^^^^^^^^^^^^^^^ 480 481There are a few built-in low-level merge drivers defined that 482can be asked for via the `merge` attribute. 483 484text:: 485 486 Usual 3-way file level merge for text files. Conflicted 487 regions are marked with conflict markers `<<<<<<<`, 488 `=======` and `>>>>>>>`. The version from your branch 489 appears before the `=======` marker, and the version 490 from the merged branch appears after the `=======` 491 marker. 492 493binary:: 494 495 Keep the version from your branch in the work tree, but 496 leave the path in the conflicted state for the user to 497 sort out. 498 499union:: 500 501 Run 3-way file level merge for text files, but take 502 lines from both versions, instead of leaving conflict 503 markers. This tends to leave the added lines in the 504 resulting file in random order and the user should 505 verify the result. Do not use this if you do not 506 understand the implications. 507 508 509Defining a custom merge driver 510^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 511 512The definition of a merge driver is done in the `.git/config` 513file, not in the `gitattributes` file, so strictly speaking this 514manual page is a wrong place to talk about it. However... 515 516To define a custom merge driver `filfre`, add a section to your 517`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 518 519---------------------------------------------------------------- 520[merge "filfre"] 521 name = feel-free merge driver 522 driver = filfre %O %A %B 523 recursive = binary 524---------------------------------------------------------------- 525 526The `merge.*.name` variable gives the driver a human-readable 527name. 528 529The `merge.*.driver` variable's value is used to construct a 530command to run to merge ancestor's version (`%O`), current 531version (`%A`) and the other branches' version (`%B`). These 532three tokens are replaced with the names of temporary files that 533hold the contents of these versions when the command line is 534built. Additionally, %L will be replaced with the conflict marker 535size (see below). 536 537The merge driver is expected to leave the result of the merge in 538the file named with `%A` by overwriting it, and exit with zero 539status if it managed to merge them cleanly, or non-zero if there 540were conflicts. 541 542The `merge.*.recursive` variable specifies what other merge 543driver to use when the merge driver is called for an internal 544merge between common ancestors, when there are more than one. 545When left unspecified, the driver itself is used for both 546internal merge and the final merge. 547 548 549`conflict-marker-size` 550^^^^^^^^^^^^^^^^^^^^^^ 551 552This attribute controls the length of conflict markers left in 553the work tree file during a conflicted merge. Only setting to 554the value to a positive integer has any meaningful effect. 555 556For example, this line in `.gitattributes` can be used to tell the merge 557machinery to leave much longer (instead of the usual 7-character-long) 558conflict markers when merging the file `Documentation/git-merge.txt` 559results in a conflict. 560 561------------------------ 562Documentation/git-merge.txt conflict-marker-size=32 563------------------------ 564 565 566Checking whitespace errors 567~~~~~~~~~~~~~~~~~~~~~~~~~~ 568 569`whitespace` 570^^^^^^^^^^^^ 571 572The `core.whitespace` configuration variable allows you to define what 573'diff' and 'apply' should consider whitespace errors for all paths in 574the project (See linkgit:git-config[1]). This attribute gives you finer 575control per path. 576 577Set:: 578 579 Notice all types of potential whitespace errors known to git. 580 581Unset:: 582 583 Do not notice anything as error. 584 585Unspecified:: 586 587 Use the value of `core.whitespace` configuration variable to 588 decide what to notice as error. 589 590String:: 591 592 Specify a comma separate list of common whitespace problems to 593 notice in the same format as `core.whitespace` configuration 594 variable. 595 596 597Creating an archive 598~~~~~~~~~~~~~~~~~~~ 599 600`export-ignore` 601^^^^^^^^^^^^^^^ 602 603Files and directories with the attribute `export-ignore` won't be added to 604archive files. 605 606`export-subst` 607^^^^^^^^^^^^^^ 608 609If the attribute `export-subst` is set for a file then git will expand 610several placeholders when adding this file to an archive. The 611expansion depends on the availability of a commit ID, i.e., if 612linkgit:git-archive[1] has been given a tree instead of a commit or a 613tag then no replacement will be done. The placeholders are the same 614as those for the option `--pretty=format:` of linkgit:git-log[1], 615except that they need to be wrapped like this: `$Format:PLACEHOLDERS$` 616in the file. E.g. the string `$Format:%H$` will be replaced by the 617commit hash. 618 619 620Packing objects 621~~~~~~~~~~~~~~~ 622 623`delta` 624^^^^^^^ 625 626Delta compression will not be attempted for blobs for paths with the 627attribute `delta` set to false. 628 629 630Viewing files in GUI tools 631~~~~~~~~~~~~~~~~~~~~~~~~~~ 632 633`encoding` 634^^^^^^^^^^ 635 636The value of this attribute specifies the character encoding that should 637be used by GUI tools (e.g. linkgit:gitk[1] and linkgit:git-gui[1]) to 638display the contents of the relevant file. Note that due to performance 639considerations linkgit:gitk[1] does not use this attribute unless you 640manually enable per-file encodings in its options. 641 642If this attribute is not set or has an invalid value, the value of the 643`gui.encoding` configuration variable is used instead 644(See linkgit:git-config[1]). 645 646 647USING ATTRIBUTE MACROS 648---------------------- 649 650You do not want any end-of-line conversions applied to, nor textual diffs 651produced for, any binary file you track. You would need to specify e.g. 652 653------------ 654*.jpg -crlf -diff 655------------ 656 657but that may become cumbersome, when you have many attributes. Using 658attribute macros, you can specify groups of attributes set or unset at 659the same time. The system knows a built-in attribute macro, `binary`: 660 661------------ 662*.jpg binary 663------------ 664 665which is equivalent to the above. Note that the attribute macros can only 666be "Set" (see the above example that sets "binary" macro as if it were an 667ordinary attribute --- setting it in turn unsets "crlf" and "diff"). 668 669 670DEFINING ATTRIBUTE MACROS 671------------------------- 672 673Custom attribute macros can be defined only in the `.gitattributes` file 674at the toplevel (i.e. not in any subdirectory). The built-in attribute 675macro "binary" is equivalent to: 676 677------------ 678[attr]binary -diff -crlf 679------------ 680 681 682EXAMPLE 683------- 684 685If you have these three `gitattributes` file: 686 687---------------------------------------------------------------- 688(in $GIT_DIR/info/attributes) 689 690a* foo !bar -baz 691 692(in .gitattributes) 693abc foo bar baz 694 695(in t/.gitattributes) 696ab* merge=filfre 697abc -foo -bar 698*.c frotz 699---------------------------------------------------------------- 700 701the attributes given to path `t/abc` are computed as follows: 702 7031. By examining `t/.gitattributes` (which is in the same 704 directory as the path in question), git finds that the first 705 line matches. `merge` attribute is set. It also finds that 706 the second line matches, and attributes `foo` and `bar` 707 are unset. 708 7092. Then it examines `.gitattributes` (which is in the parent 710 directory), and finds that the first line matches, but 711 `t/.gitattributes` file already decided how `merge`, `foo` 712 and `bar` attributes should be given to this path, so it 713 leaves `foo` and `bar` unset. Attribute `baz` is set. 714 7153. Finally it examines `$GIT_DIR/info/attributes`. This file 716 is used to override the in-tree settings. The first line is 717 a match, and `foo` is set, `bar` is reverted to unspecified 718 state, and `baz` is unset. 719 720As the result, the attributes assignment to `t/abc` becomes: 721 722---------------------------------------------------------------- 723foo set to true 724bar unspecified 725baz set to false 726merge set to string value "filfre" 727frotz unspecified 728---------------------------------------------------------------- 729 730 731 732GIT 733--- 734Part of the linkgit:git[1] suite