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. Additionally, %L will be replaced with the conflict marker 515size (see below). 516 517The merge driver is expected to leave the result of the merge in 518the file named with `%A` by overwriting it, and exit with zero 519status if it managed to merge them cleanly, or non-zero if there 520were conflicts. 521 522The `merge.*.recursive` variable specifies what other merge 523driver to use when the merge driver is called for an internal 524merge between common ancestors, when there are more than one. 525When left unspecified, the driver itself is used for both 526internal merge and the final merge. 527 528 529`conflict-marker-size` 530^^^^^^^^^^^^^^^^^^^^^^ 531 532This attribute controls the length of conflict markers left in 533the work tree file during a conflicted merge. Only setting to 534the value to a positive integer has any meaningful effect. 535 536For example, this line in `.gitattributes` can be used to tell the merge 537machinery to leave much longer (instead of the usual 7-character-long) 538conflict markers when merging the file `Documentation/git-merge.txt` 539results in a conflict. 540 541------------------------ 542Documentation/git-merge.txt conflict-marker-size=32 543------------------------ 544 545 546Checking whitespace errors 547~~~~~~~~~~~~~~~~~~~~~~~~~~ 548 549`whitespace` 550^^^^^^^^^^^^ 551 552The `core.whitespace` configuration variable allows you to define what 553'diff' and 'apply' should consider whitespace errors for all paths in 554the project (See linkgit:git-config[1]). This attribute gives you finer 555control per path. 556 557Set:: 558 559 Notice all types of potential whitespace errors known to git. 560 561Unset:: 562 563 Do not notice anything as error. 564 565Unspecified:: 566 567 Use the value of `core.whitespace` configuration variable to 568 decide what to notice as error. 569 570String:: 571 572 Specify a comma separate list of common whitespace problems to 573 notice in the same format as `core.whitespace` configuration 574 variable. 575 576 577Creating an archive 578~~~~~~~~~~~~~~~~~~~ 579 580`export-ignore` 581^^^^^^^^^^^^^^^ 582 583Files and directories with the attribute `export-ignore` won't be added to 584archive files. 585 586`export-subst` 587^^^^^^^^^^^^^^ 588 589If the attribute `export-subst` is set for a file then git will expand 590several placeholders when adding this file to an archive. The 591expansion depends on the availability of a commit ID, i.e., if 592linkgit:git-archive[1] has been given a tree instead of a commit or a 593tag then no replacement will be done. The placeholders are the same 594as those for the option `--pretty=format:` of linkgit:git-log[1], 595except that they need to be wrapped like this: `$Format:PLACEHOLDERS$` 596in the file. E.g. the string `$Format:%H$` will be replaced by the 597commit hash. 598 599 600Packing objects 601~~~~~~~~~~~~~~~ 602 603`delta` 604^^^^^^^ 605 606Delta compression will not be attempted for blobs for paths with the 607attribute `delta` set to false. 608 609 610Viewing files in GUI tools 611~~~~~~~~~~~~~~~~~~~~~~~~~~ 612 613`encoding` 614^^^^^^^^^^ 615 616The value of this attribute specifies the character encoding that should 617be used by GUI tools (e.g. linkgit:gitk[1] and linkgit:git-gui[1]) to 618display the contents of the relevant file. Note that due to performance 619considerations linkgit:gitk[1] does not use this attribute unless you 620manually enable per-file encodings in its options. 621 622If this attribute is not set or has an invalid value, the value of the 623`gui.encoding` configuration variable is used instead 624(See linkgit:git-config[1]). 625 626 627USING ATTRIBUTE MACROS 628---------------------- 629 630You do not want any end-of-line conversions applied to, nor textual diffs 631produced for, any binary file you track. You would need to specify e.g. 632 633------------ 634*.jpg -crlf -diff 635------------ 636 637but that may become cumbersome, when you have many attributes. Using 638attribute macros, you can specify groups of attributes set or unset at 639the same time. The system knows a built-in attribute macro, `binary`: 640 641------------ 642*.jpg binary 643------------ 644 645which is equivalent to the above. Note that the attribute macros can only 646be "Set" (see the above example that sets "binary" macro as if it were an 647ordinary attribute --- setting it in turn unsets "crlf" and "diff"). 648 649 650DEFINING ATTRIBUTE MACROS 651------------------------- 652 653Custom attribute macros can be defined only in the `.gitattributes` file 654at the toplevel (i.e. not in any subdirectory). The built-in attribute 655macro "binary" is equivalent to: 656 657------------ 658[attr]binary -diff -crlf 659------------ 660 661 662EXAMPLE 663------- 664 665If you have these three `gitattributes` file: 666 667---------------------------------------------------------------- 668(in $GIT_DIR/info/attributes) 669 670a* foo !bar -baz 671 672(in .gitattributes) 673abc foo bar baz 674 675(in t/.gitattributes) 676ab* merge=filfre 677abc -foo -bar 678*.c frotz 679---------------------------------------------------------------- 680 681the attributes given to path `t/abc` are computed as follows: 682 6831. By examining `t/.gitattributes` (which is in the same 684 directory as the path in question), git finds that the first 685 line matches. `merge` attribute is set. It also finds that 686 the second line matches, and attributes `foo` and `bar` 687 are unset. 688 6892. Then it examines `.gitattributes` (which is in the parent 690 directory), and finds that the first line matches, but 691 `t/.gitattributes` file already decided how `merge`, `foo` 692 and `bar` attributes should be given to this path, so it 693 leaves `foo` and `bar` unset. Attribute `baz` is set. 694 6953. Finally it examines `$GIT_DIR/info/attributes`. This file 696 is used to override the in-tree settings. The first line is 697 a match, and `foo` is set, `bar` is reverted to unspecified 698 state, and `baz` is unset. 699 700As the result, the attributes assignment to `t/abc` becomes: 701 702---------------------------------------------------------------- 703foo set to true 704bar unspecified 705baz set to false 706merge set to string value "filfre" 707frotz unspecified 708---------------------------------------------------------------- 709 710 711 712GIT 713--- 714Part of the linkgit:git[1] suite