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 --color-words` 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 417 418Performing a three-way merge 419~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 420 421`merge` 422^^^^^^^ 423 424The attribute `merge` affects how three versions of a file is 425merged when a file-level merge is necessary during `git merge`, 426and other commands such as `git revert` and `git cherry-pick`. 427 428Set:: 429 430 Built-in 3-way merge driver is used to merge the 431 contents in a way similar to 'merge' command of `RCS` 432 suite. This is suitable for ordinary text files. 433 434Unset:: 435 436 Take the version from the current branch as the 437 tentative merge result, and declare that the merge has 438 conflicts. This is suitable for binary files that does 439 not have a well-defined merge semantics. 440 441Unspecified:: 442 443 By default, this uses the same built-in 3-way merge 444 driver as is the case the `merge` attribute is set. 445 However, `merge.default` configuration variable can name 446 different merge driver to be used for paths to which the 447 `merge` attribute is unspecified. 448 449String:: 450 451 3-way merge is performed using the specified custom 452 merge driver. The built-in 3-way merge driver can be 453 explicitly specified by asking for "text" driver; the 454 built-in "take the current branch" driver can be 455 requested with "binary". 456 457 458Built-in merge drivers 459^^^^^^^^^^^^^^^^^^^^^^ 460 461There are a few built-in low-level merge drivers defined that 462can be asked for via the `merge` attribute. 463 464text:: 465 466 Usual 3-way file level merge for text files. Conflicted 467 regions are marked with conflict markers `<<<<<<<`, 468 `=======` and `>>>>>>>`. The version from your branch 469 appears before the `=======` marker, and the version 470 from the merged branch appears after the `=======` 471 marker. 472 473binary:: 474 475 Keep the version from your branch in the work tree, but 476 leave the path in the conflicted state for the user to 477 sort out. 478 479union:: 480 481 Run 3-way file level merge for text files, but take 482 lines from both versions, instead of leaving conflict 483 markers. This tends to leave the added lines in the 484 resulting file in random order and the user should 485 verify the result. Do not use this if you do not 486 understand the implications. 487 488 489Defining a custom merge driver 490^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 491 492The definition of a merge driver is done in the `.git/config` 493file, not in the `gitattributes` file, so strictly speaking this 494manual page is a wrong place to talk about it. However... 495 496To define a custom merge driver `filfre`, add a section to your 497`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 498 499---------------------------------------------------------------- 500[merge "filfre"] 501 name = feel-free merge driver 502 driver = filfre %O %A %B 503 recursive = binary 504---------------------------------------------------------------- 505 506The `merge.*.name` variable gives the driver a human-readable 507name. 508 509The `merge.*.driver` variable's value is used to construct a 510command to run to merge ancestor's version (`%O`), current 511version (`%A`) and the other branches' version (`%B`). These 512three tokens are replaced with the names of temporary files that 513hold the contents of these versions when the command line is 514built. 515 516The merge driver is expected to leave the result of the merge in 517the file named with `%A` by overwriting it, and exit with zero 518status if it managed to merge them cleanly, or non-zero if there 519were conflicts. 520 521The `merge.*.recursive` variable specifies what other merge 522driver to use when the merge driver is called for an internal 523merge between common ancestors, when there are more than one. 524When left unspecified, the driver itself is used for both 525internal merge and the final merge. 526 527 528Checking whitespace errors 529~~~~~~~~~~~~~~~~~~~~~~~~~~ 530 531`whitespace` 532^^^^^^^^^^^^ 533 534The `core.whitespace` configuration variable allows you to define what 535'diff' and 'apply' should consider whitespace errors for all paths in 536the project (See linkgit:git-config[1]). This attribute gives you finer 537control per path. 538 539Set:: 540 541 Notice all types of potential whitespace errors known to git. 542 543Unset:: 544 545 Do not notice anything as error. 546 547Unspecified:: 548 549 Use the value of `core.whitespace` configuration variable to 550 decide what to notice as error. 551 552String:: 553 554 Specify a comma separate list of common whitespace problems to 555 notice in the same format as `core.whitespace` configuration 556 variable. 557 558 559Creating an archive 560~~~~~~~~~~~~~~~~~~~ 561 562`export-ignore` 563^^^^^^^^^^^^^^^ 564 565Files and directories with the attribute `export-ignore` won't be added to 566archive files. 567 568`export-subst` 569^^^^^^^^^^^^^^ 570 571If the attribute `export-subst` is set for a file then git will expand 572several placeholders when adding this file to an archive. The 573expansion depends on the availability of a commit ID, i.e., if 574linkgit:git-archive[1] has been given a tree instead of a commit or a 575tag then no replacement will be done. The placeholders are the same 576as those for the option `--pretty=format:` of linkgit:git-log[1], 577except that they need to be wrapped like this: `$Format:PLACEHOLDERS$` 578in the file. E.g. the string `$Format:%H$` will be replaced by the 579commit hash. 580 581 582Packing objects 583~~~~~~~~~~~~~~~ 584 585`delta` 586^^^^^^^ 587 588Delta compression will not be attempted for blobs for paths with the 589attribute `delta` set to false. 590 591 592Viewing files in GUI tools 593~~~~~~~~~~~~~~~~~~~~~~~~~~ 594 595`encoding` 596^^^^^^^^^^ 597 598The value of this attribute specifies the character encoding that should 599be used by GUI tools (e.g. linkgit:gitk[1] and linkgit:git-gui[1]) to 600display the contents of the relevant file. Note that due to performance 601considerations linkgit:gitk[1] does not use this attribute unless you 602manually enable per-file encodings in its options. 603 604If this attribute is not set or has an invalid value, the value of the 605`gui.encoding` configuration variable is used instead 606(See linkgit:git-config[1]). 607 608 609USING ATTRIBUTE MACROS 610---------------------- 611 612You do not want any end-of-line conversions applied to, nor textual diffs 613produced for, any binary file you track. You would need to specify e.g. 614 615------------ 616*.jpg -crlf -diff 617------------ 618 619but that may become cumbersome, when you have many attributes. Using 620attribute macros, you can specify groups of attributes set or unset at 621the same time. The system knows a built-in attribute macro, `binary`: 622 623------------ 624*.jpg binary 625------------ 626 627which is equivalent to the above. Note that the attribute macros can only 628be "Set" (see the above example that sets "binary" macro as if it were an 629ordinary attribute --- setting it in turn unsets "crlf" and "diff"). 630 631 632DEFINING ATTRIBUTE MACROS 633------------------------- 634 635Custom attribute macros can be defined only in the `.gitattributes` file 636at the toplevel (i.e. not in any subdirectory). The built-in attribute 637macro "binary" is equivalent to: 638 639------------ 640[attr]binary -diff -crlf 641------------ 642 643 644EXAMPLE 645------- 646 647If you have these three `gitattributes` file: 648 649---------------------------------------------------------------- 650(in $GIT_DIR/info/attributes) 651 652a* foo !bar -baz 653 654(in .gitattributes) 655abc foo bar baz 656 657(in t/.gitattributes) 658ab* merge=filfre 659abc -foo -bar 660*.c frotz 661---------------------------------------------------------------- 662 663the attributes given to path `t/abc` are computed as follows: 664 6651. By examining `t/.gitattributes` (which is in the same 666 directory as the path in question), git finds that the first 667 line matches. `merge` attribute is set. It also finds that 668 the second line matches, and attributes `foo` and `bar` 669 are unset. 670 6712. Then it examines `.gitattributes` (which is in the parent 672 directory), and finds that the first line matches, but 673 `t/.gitattributes` file already decided how `merge`, `foo` 674 and `bar` attributes should be given to this path, so it 675 leaves `foo` and `bar` unset. Attribute `baz` is set. 676 6773. Finally it examines `$GIT_DIR/info/attributes`. This file 678 is used to override the in-tree settings. The first line is 679 a match, and `foo` is set, `bar` is reverted to unspecified 680 state, and `baz` is unset. 681 682As the result, the attributes assignment to `t/abc` becomes: 683 684---------------------------------------------------------------- 685foo set to true 686bar unspecified 687baz set to false 688merge set to string value "filfre" 689frotz unspecified 690---------------------------------------------------------------- 691 692 693 694GIT 695--- 696Part of the linkgit:git[1] suite