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 200 201Interaction between checkin/checkout attributes 202^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 203 204In the check-in codepath, the worktree file is first converted 205with `filter` driver (if specified and corresponding driver 206defined), then the result is processed with `ident` (if 207specified), and then finally with `crlf` (again, if specified 208and applicable). 209 210In the check-out codepath, the blob content is first converted 211with `crlf`, and then `ident` and fed to `filter`. 212 213 214Generating diff text 215~~~~~~~~~~~~~~~~~~~~ 216 217`diff` 218^^^^^^ 219 220The attribute `diff` affects how 'git' generates diffs for particular 221files. It can tell git whether to generate a textual patch for the path 222or to treat the path as a binary file. It can also affect what line is 223shown on the hunk header `@@ -k,l +n,m @@` line, tell git to use an 224external command to generate the diff, or ask git to convert binary 225files to a text format before generating the diff. 226 227Set:: 228 229 A path to which the `diff` attribute is set is treated 230 as text, even when they contain byte values that 231 normally never appear in text files, such as NUL. 232 233Unset:: 234 235 A path to which the `diff` attribute is unset will 236 generate `Binary files differ` (or a binary patch, if 237 binary patches are enabled). 238 239Unspecified:: 240 241 A path to which the `diff` attribute is unspecified 242 first gets its contents inspected, and if it looks like 243 text, it is treated as text. Otherwise it would 244 generate `Binary files differ`. 245 246String:: 247 248 Diff is shown using the specified diff driver. Each driver may 249 specify one or more options, as described in the following 250 section. The options for the diff driver "foo" are defined 251 by the configuration variables in the "diff.foo" section of the 252 git config file. 253 254 255Defining an external diff driver 256^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 257 258The definition of a diff driver is done in `gitconfig`, not 259`gitattributes` file, so strictly speaking this manual page is a 260wrong place to talk about it. However... 261 262To define an external diff driver `jcdiff`, add a section to your 263`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 264 265---------------------------------------------------------------- 266[diff "jcdiff"] 267 command = j-c-diff 268---------------------------------------------------------------- 269 270When git needs to show you a diff for the path with `diff` 271attribute set to `jcdiff`, it calls the command you specified 272with the above configuration, i.e. `j-c-diff`, with 7 273parameters, just like `GIT_EXTERNAL_DIFF` program is called. 274See linkgit:git[1] for details. 275 276 277Defining a custom hunk-header 278^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 279 280Each group of changes (called a "hunk") in the textual diff output 281is prefixed with a line of the form: 282 283 @@ -k,l +n,m @@ TEXT 284 285This is called a 'hunk header'. The "TEXT" portion is by default a line 286that begins with an alphabet, an underscore or a dollar sign; this 287matches what GNU 'diff -p' output uses. This default selection however 288is not suited for some contents, and you can use a customized pattern 289to make a selection. 290 291First, in .gitattributes, you would assign the `diff` attribute 292for paths. 293 294------------------------ 295*.tex diff=tex 296------------------------ 297 298Then, you would define a "diff.tex.xfuncname" configuration to 299specify a regular expression that matches a line that you would 300want to appear as the hunk header "TEXT". Add a section to your 301`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 302 303------------------------ 304[diff "tex"] 305 xfuncname = "^(\\\\(sub)*section\\{.*)$" 306------------------------ 307 308Note. A single level of backslashes are eaten by the 309configuration file parser, so you would need to double the 310backslashes; the pattern above picks a line that begins with a 311backslash, and zero or more occurrences of `sub` followed by 312`section` followed by open brace, to the end of line. 313 314There are a few built-in patterns to make this easier, and `tex` 315is one of them, so you do not have to write the above in your 316configuration file (you still need to enable this with the 317attribute mechanism, via `.gitattributes`). The following built in 318patterns are available: 319 320- `bibtex` suitable for files with BibTeX coded references. 321 322- `cpp` suitable for source code in the C and C++ languages. 323 324- `html` suitable for HTML/XHTML documents. 325 326- `java` suitable for source code in the Java language. 327 328- `objc` suitable for source code in the Objective-C language. 329 330- `pascal` suitable for source code in the Pascal/Delphi language. 331 332- `php` suitable for source code in the PHP language. 333 334- `python` suitable for source code in the Python language. 335 336- `ruby` suitable for source code in the Ruby language. 337 338- `tex` suitable for source code for LaTeX documents. 339 340 341Customizing word diff 342^^^^^^^^^^^^^^^^^^^^^ 343 344You can customize the rules that `git diff --color-words` uses to 345split words in a line, by specifying an appropriate regular expression 346in the "diff.*.wordRegex" configuration variable. For example, in TeX 347a backslash followed by a sequence of letters forms a command, but 348several such commands can be run together without intervening 349whitespace. To separate them, use a regular expression in your 350`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 351 352------------------------ 353[diff "tex"] 354 wordRegex = "\\\\[a-zA-Z]+|[{}]|\\\\.|[^\\{}[:space:]]+" 355------------------------ 356 357A built-in pattern is provided for all languages listed in the 358previous section. 359 360 361Performing text diffs of binary files 362^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 363 364Sometimes it is desirable to see the diff of a text-converted 365version of some binary files. For example, a word processor 366document can be converted to an ASCII text representation, and 367the diff of the text shown. Even though this conversion loses 368some information, the resulting diff is useful for human 369viewing (but cannot be applied directly). 370 371The `textconv` config option is used to define a program for 372performing such a conversion. The program should take a single 373argument, the name of a file to convert, and produce the 374resulting text on stdout. 375 376For example, to show the diff of the exif information of a 377file instead of the binary information (assuming you have the 378exif tool installed), add the following section to your 379`$GIT_DIR/config` file (or `$HOME/.gitconfig` file): 380 381------------------------ 382[diff "jpg"] 383 textconv = exif 384------------------------ 385 386NOTE: The text conversion is generally a one-way conversion; 387in this example, we lose the actual image contents and focus 388just on the text data. This means that diffs generated by 389textconv are _not_ suitable for applying. For this reason, 390only `git diff` and the `git log` family of commands (i.e., 391log, whatchanged, show) will perform text conversion. `git 392format-patch` will never generate this output. If you want to 393send somebody a text-converted diff of a binary file (e.g., 394because it quickly conveys the changes you have made), you 395should generate it separately and send it as a comment _in 396addition to_ the usual binary diff that you might send. 397 398 399Performing a three-way merge 400~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 401 402`merge` 403^^^^^^^ 404 405The attribute `merge` affects how three versions of a file is 406merged when a file-level merge is necessary during `git merge`, 407and other commands such as `git revert` and `git cherry-pick`. 408 409Set:: 410 411 Built-in 3-way merge driver is used to merge the 412 contents in a way similar to 'merge' command of `RCS` 413 suite. This is suitable for ordinary text files. 414 415Unset:: 416 417 Take the version from the current branch as the 418 tentative merge result, and declare that the merge has 419 conflicts. This is suitable for binary files that does 420 not have a well-defined merge semantics. 421 422Unspecified:: 423 424 By default, this uses the same built-in 3-way merge 425 driver as is the case the `merge` attribute is set. 426 However, `merge.default` configuration variable can name 427 different merge driver to be used for paths to which the 428 `merge` attribute is unspecified. 429 430String:: 431 432 3-way merge is performed using the specified custom 433 merge driver. The built-in 3-way merge driver can be 434 explicitly specified by asking for "text" driver; the 435 built-in "take the current branch" driver can be 436 requested with "binary". 437 438 439Built-in merge drivers 440^^^^^^^^^^^^^^^^^^^^^^ 441 442There are a few built-in low-level merge drivers defined that 443can be asked for via the `merge` attribute. 444 445text:: 446 447 Usual 3-way file level merge for text files. Conflicted 448 regions are marked with conflict markers `<<<<<<<`, 449 `=======` and `>>>>>>>`. The version from your branch 450 appears before the `=======` marker, and the version 451 from the merged branch appears after the `=======` 452 marker. 453 454binary:: 455 456 Keep the version from your branch in the work tree, but 457 leave the path in the conflicted state for the user to 458 sort out. 459 460union:: 461 462 Run 3-way file level merge for text files, but take 463 lines from both versions, instead of leaving conflict 464 markers. This tends to leave the added lines in the 465 resulting file in random order and the user should 466 verify the result. Do not use this if you do not 467 understand the implications. 468 469 470Defining a custom merge driver 471^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 472 473The definition of a merge driver is done in the `.git/config` 474file, not in the `gitattributes` file, so strictly speaking this 475manual page is a wrong place to talk about it. However... 476 477To define a custom merge driver `filfre`, add a section to your 478`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 479 480---------------------------------------------------------------- 481[merge "filfre"] 482 name = feel-free merge driver 483 driver = filfre %O %A %B 484 recursive = binary 485---------------------------------------------------------------- 486 487The `merge.*.name` variable gives the driver a human-readable 488name. 489 490The `merge.*.driver` variable's value is used to construct a 491command to run to merge ancestor's version (`%O`), current 492version (`%A`) and the other branches' version (`%B`). These 493three tokens are replaced with the names of temporary files that 494hold the contents of these versions when the command line is 495built. 496 497The merge driver is expected to leave the result of the merge in 498the file named with `%A` by overwriting it, and exit with zero 499status if it managed to merge them cleanly, or non-zero if there 500were conflicts. 501 502The `merge.*.recursive` variable specifies what other merge 503driver to use when the merge driver is called for an internal 504merge between common ancestors, when there are more than one. 505When left unspecified, the driver itself is used for both 506internal merge and the final merge. 507 508 509Checking whitespace errors 510~~~~~~~~~~~~~~~~~~~~~~~~~~ 511 512`whitespace` 513^^^^^^^^^^^^ 514 515The `core.whitespace` configuration variable allows you to define what 516'diff' and 'apply' should consider whitespace errors for all paths in 517the project (See linkgit:git-config[1]). This attribute gives you finer 518control per path. 519 520Set:: 521 522 Notice all types of potential whitespace errors known to git. 523 524Unset:: 525 526 Do not notice anything as error. 527 528Unspecified:: 529 530 Use the value of `core.whitespace` configuration variable to 531 decide what to notice as error. 532 533String:: 534 535 Specify a comma separate list of common whitespace problems to 536 notice in the same format as `core.whitespace` configuration 537 variable. 538 539 540Creating an archive 541~~~~~~~~~~~~~~~~~~~ 542 543`export-ignore` 544^^^^^^^^^^^^^^^ 545 546Files and directories with the attribute `export-ignore` won't be added to 547archive files. 548 549`export-subst` 550^^^^^^^^^^^^^^ 551 552If the attribute `export-subst` is set for a file then git will expand 553several placeholders when adding this file to an archive. The 554expansion depends on the availability of a commit ID, i.e., if 555linkgit:git-archive[1] has been given a tree instead of a commit or a 556tag then no replacement will be done. The placeholders are the same 557as those for the option `--pretty=format:` of linkgit:git-log[1], 558except that they need to be wrapped like this: `$Format:PLACEHOLDERS$` 559in the file. E.g. the string `$Format:%H$` will be replaced by the 560commit hash. 561 562 563Viewing files in GUI tools 564~~~~~~~~~~~~~~~~~~~~~~~~~~ 565 566`encoding` 567^^^^^^^^^^ 568 569The value of this attribute specifies the character encoding that should 570be used by GUI tools (e.g. linkgit:gitk[1] and linkgit:git-gui[1]) to 571display the contents of the relevant file. Note that due to performance 572considerations linkgit:gitk[1] does not use this attribute unless you 573manually enable per-file encodings in its options. 574 575If this attribute is not set or has an invalid value, the value of the 576`gui.encoding` configuration variable is used instead 577(See linkgit:git-config[1]). 578 579 580USING ATTRIBUTE MACROS 581---------------------- 582 583You do not want any end-of-line conversions applied to, nor textual diffs 584produced for, any binary file you track. You would need to specify e.g. 585 586------------ 587*.jpg -crlf -diff 588------------ 589 590but that may become cumbersome, when you have many attributes. Using 591attribute macros, you can specify groups of attributes set or unset at 592the same time. The system knows a built-in attribute macro, `binary`: 593 594------------ 595*.jpg binary 596------------ 597 598which is equivalent to the above. Note that the attribute macros can only 599be "Set" (see the above example that sets "binary" macro as if it were an 600ordinary attribute --- setting it in turn unsets "crlf" and "diff"). 601 602 603DEFINING ATTRIBUTE MACROS 604------------------------- 605 606Custom attribute macros can be defined only in the `.gitattributes` file 607at the toplevel (i.e. not in any subdirectory). The built-in attribute 608macro "binary" is equivalent to: 609 610------------ 611[attr]binary -diff -crlf 612------------ 613 614 615EXAMPLE 616------- 617 618If you have these three `gitattributes` file: 619 620---------------------------------------------------------------- 621(in $GIT_DIR/info/attributes) 622 623a* foo !bar -baz 624 625(in .gitattributes) 626abc foo bar baz 627 628(in t/.gitattributes) 629ab* merge=filfre 630abc -foo -bar 631*.c frotz 632---------------------------------------------------------------- 633 634the attributes given to path `t/abc` are computed as follows: 635 6361. By examining `t/.gitattributes` (which is in the same 637 directory as the path in question), git finds that the first 638 line matches. `merge` attribute is set. It also finds that 639 the second line matches, and attributes `foo` and `bar` 640 are unset. 641 6422. Then it examines `.gitattributes` (which is in the parent 643 directory), and finds that the first line matches, but 644 `t/.gitattributes` file already decided how `merge`, `foo` 645 and `bar` attributes should be given to this path, so it 646 leaves `foo` and `bar` unset. Attribute `baz` is set. 647 6483. Finally it examines `$GIT_DIR/info/attributes`. This file 649 is used to override the in-tree settings. The first line is 650 a match, and `foo` is set, `bar` is reverted to unspecified 651 state, and `baz` is unset. 652 653As the result, the attributes assignment to `t/abc` becomes: 654 655---------------------------------------------------------------- 656foo set to true 657bar unspecified 658baz set to false 659merge set to string value "filfre" 660frotz unspecified 661---------------------------------------------------------------- 662 663 664 665GIT 666--- 667Part of the linkgit:git[1] suite