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`text` 96^^^^^^ 97 98This attribute enables and controls end-of-line normalization. When a 99text file is normalized, its line endings are converted to LF in the 100repository. To control what line ending style is used in the working 101directory, use the `eol` attribute for a single file and the 102`core.eol` configuration variable for all text files. 103 104Set:: 105 106 Setting the `text` attribute on a path enables end-of-line 107 normalization and marks the path as a text file. End-of-line 108 conversion takes place without guessing the content type. 109 110Unset:: 111 112 Unsetting the `text` attribute on a path tells git not to 113 attempt any end-of-line conversion upon checkin or checkout. 114 115Set to string value "auto":: 116 117 When `text` is set to "auto", the path is marked for automatic 118 end-of-line normalization. If git decides that the content is 119 text, its line endings are normalized to LF on checkin. 120 121Unspecified:: 122 123 If the `text` attribute is unspecified, git uses the 124 `core.autocrlf` configuration variable to determine if the 125 file should be converted. 126 127Any other value causes git to act as if `text` has been left 128unspecified. 129 130`eol` 131^^^^^ 132 133This attribute sets a specific line-ending style to be used in the 134working directory. It enables end-of-line normalization without any 135content checks, effectively setting the `text` attribute. 136 137Set to string value "crlf":: 138 139 This setting forces git to normalize line endings for this 140 file on checkin and convert them to CRLF when the file is 141 checked out. 142 143Set to string value "lf":: 144 145 This setting forces git to normalize line endings to LF on 146 checkin and prevents conversion to CRLF when the file is 147 checked out. 148 149Backwards compatibility with `crlf` attribute 150^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 151 152For backwards compatibility, the `crlf` attribute is interpreted as 153follows: 154 155------------------------ 156crlf text 157-crlf -text 158crlf=input eol=lf 159------------------------ 160 161End-of-line conversion 162^^^^^^^^^^^^^^^^^^^^^^ 163 164While git normally leaves file contents alone, it can be configured to 165normalize line endings to LF in the repository and, optionally, to 166convert them to CRLF when files are checked out. 167 168Here is an example that will make git normalize .txt, .vcproj and .sh 169files, ensure that .vcproj files have CRLF and .sh files have LF in 170the working directory, and prevent .jpg files from being normalized 171regardless of their content. 172 173------------------------ 174*.txt text 175*.vcproj eol=crlf 176*.sh eol=lf 177*.jpg -text 178------------------------ 179 180Other source code management systems normalize all text files in their 181repositories, and there are two ways to enable similar automatic 182normalization in git. 183 184If you simply want to have CRLF line endings in your working directory 185regardless of the repository you are working with, you can set the 186config variable "core.autocrlf" without changing any attributes. 187 188------------------------ 189[core] 190 autocrlf = true 191------------------------ 192 193This does not force normalization of all text files, but does ensure 194that text files that you introduce to the repository have their line 195endings normalized to LF when they are added, and that files that are 196already normalized in the repository stay normalized. 197 198If you want to interoperate with a source code management system that 199enforces end-of-line normalization, or you simply want all text files 200in your repository to be normalized, you should instead set the `text` 201attribute to "auto" for _all_ files. 202 203------------------------ 204* text=auto 205------------------------ 206 207This ensures that all files that git considers to be text will have 208normalized (LF) line endings in the repository. The `core.eol` 209configuration variable controls which line endings git will use for 210normalized files in your working directory; the default is to use the 211native line ending for your platform, or CRLF if `core.autocrlf` is 212set. 213 214NOTE: When `text=auto` normalization is enabled in an existing 215repository, any text files containing CRLFs should be normalized. If 216they are not they will be normalized the next time someone tries to 217change them, causing unfortunate misattribution. From a clean working 218directory: 219 220------------------------------------------------- 221$ echo "* text=auto" >>.gitattributes 222$ rm .git/index # Remove the index to force git to 223$ git reset # re-scan the working directory 224$ git status # Show files that will be normalized 225$ git add -u 226$ git add .gitattributes 227$ git commit -m "Introduce end-of-line normalization" 228------------------------------------------------- 229 230If any files that should not be normalized show up in 'git status', 231unset their `text` attribute before running 'git add -u'. 232 233------------------------ 234manual.pdf -text 235------------------------ 236 237Conversely, text files that git does not detect can have normalization 238enabled manually. 239 240------------------------ 241weirdchars.txt text 242------------------------ 243 244If `core.safecrlf` is set to "true" or "warn", git verifies if 245the conversion is reversible for the current setting of 246`core.autocrlf`. For "true", git rejects irreversible 247conversions; for "warn", git only prints a warning but accepts 248an irreversible conversion. The safety triggers to prevent such 249a conversion done to the files in the work tree, but there are a 250few exceptions. Even though... 251 252- 'git add' itself does not touch the files in the work tree, the 253 next checkout would, so the safety triggers; 254 255- 'git apply' to update a text file with a patch does touch the files 256 in the work tree, but the operation is about text files and CRLF 257 conversion is about fixing the line ending inconsistencies, so the 258 safety does not trigger; 259 260- 'git diff' itself does not touch the files in the work tree, it is 261 often run to inspect the changes you intend to next 'git add'. To 262 catch potential problems early, safety triggers. 263 264 265`ident` 266^^^^^^^ 267 268When the attribute `ident` is set for a path, git replaces 269`$Id$` in the blob object with `$Id:`, followed by the 27040-character hexadecimal blob object name, followed by a dollar 271sign `$` upon checkout. Any byte sequence that begins with 272`$Id:` and ends with `$` in the worktree file is replaced 273with `$Id$` upon check-in. 274 275 276`filter` 277^^^^^^^^ 278 279A `filter` attribute can be set to a string value that names a 280filter driver specified in the configuration. 281 282A filter driver consists of a `clean` command and a `smudge` 283command, either of which can be left unspecified. Upon 284checkout, when the `smudge` command is specified, the command is 285fed the blob object from its standard input, and its standard 286output is used to update the worktree file. Similarly, the 287`clean` command is used to convert the contents of worktree file 288upon checkin. 289 290A missing filter driver definition in the config is not an error 291but makes the filter a no-op passthru. 292 293The content filtering is done to massage the content into a 294shape that is more convenient for the platform, filesystem, and 295the user to use. The key phrase here is "more convenient" and not 296"turning something unusable into usable". In other words, the 297intent is that if someone unsets the filter driver definition, 298or does not have the appropriate filter program, the project 299should still be usable. 300 301For example, in .gitattributes, you would assign the `filter` 302attribute for paths. 303 304------------------------ 305*.c filter=indent 306------------------------ 307 308Then you would define a "filter.indent.clean" and "filter.indent.smudge" 309configuration in your .git/config to specify a pair of commands to 310modify the contents of C programs when the source files are checked 311in ("clean" is run) and checked out (no change is made because the 312command is "cat"). 313 314------------------------ 315[filter "indent"] 316 clean = indent 317 smudge = cat 318------------------------ 319 320For best results, `clean` should not alter its output further if it is 321run twice ("clean->clean" should be equivalent to "clean"), and 322multiple `smudge` commands should not alter `clean`'s output 323("smudge->smudge->clean" should be equivalent to "clean"). See the 324section on merging below. 325 326The "indent" filter is well-behaved in this regard: it will not modify 327input that is already correctly indented. In this case, the lack of a 328smudge filter means that the clean filter _must_ accept its own output 329without modifying it. 330 331 332Interaction between checkin/checkout attributes 333^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 334 335In the check-in codepath, the worktree file is first converted 336with `filter` driver (if specified and corresponding driver 337defined), then the result is processed with `ident` (if 338specified), and then finally with `text` (again, if specified 339and applicable). 340 341In the check-out codepath, the blob content is first converted 342with `text`, and then `ident` and fed to `filter`. 343 344 345Merging branches with differing checkin/checkout attributes 346^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 347 348If you have added attributes to a file that cause the canonical 349repository format for that file to change, such as adding a 350clean/smudge filter or text/eol/ident attributes, merging anything 351where the attribute is not in place would normally cause merge 352conflicts. 353 354To prevent these unnecessary merge conflicts, git can be told to run a 355virtual check-out and check-in of all three stages of a file when 356resolving a three-way merge by setting the `merge.renormalize` 357configuration variable. This prevents changes caused by check-in 358conversion from causing spurious merge conflicts when a converted file 359is merged with an unconverted file. 360 361As long as a "smudge->clean" results in the same output as a "clean" 362even on files that are already smudged, this strategy will 363automatically resolve all filter-related conflicts. Filters that do 364not act in this way may cause additional merge conflicts that must be 365resolved manually. 366 367 368Generating diff text 369~~~~~~~~~~~~~~~~~~~~ 370 371`diff` 372^^^^^^ 373 374The attribute `diff` affects how 'git' generates diffs for particular 375files. It can tell git whether to generate a textual patch for the path 376or to treat the path as a binary file. It can also affect what line is 377shown on the hunk header `@@ -k,l +n,m @@` line, tell git to use an 378external command to generate the diff, or ask git to convert binary 379files to a text format before generating the diff. 380 381Set:: 382 383 A path to which the `diff` attribute is set is treated 384 as text, even when they contain byte values that 385 normally never appear in text files, such as NUL. 386 387Unset:: 388 389 A path to which the `diff` attribute is unset will 390 generate `Binary files differ` (or a binary patch, if 391 binary patches are enabled). 392 393Unspecified:: 394 395 A path to which the `diff` attribute is unspecified 396 first gets its contents inspected, and if it looks like 397 text, it is treated as text. Otherwise it would 398 generate `Binary files differ`. 399 400String:: 401 402 Diff is shown using the specified diff driver. Each driver may 403 specify one or more options, as described in the following 404 section. The options for the diff driver "foo" are defined 405 by the configuration variables in the "diff.foo" section of the 406 git config file. 407 408 409Defining an external diff driver 410^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 411 412The definition of a diff driver is done in `gitconfig`, not 413`gitattributes` file, so strictly speaking this manual page is a 414wrong place to talk about it. However... 415 416To define an external diff driver `jcdiff`, add a section to your 417`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 418 419---------------------------------------------------------------- 420[diff "jcdiff"] 421 command = j-c-diff 422---------------------------------------------------------------- 423 424When git needs to show you a diff for the path with `diff` 425attribute set to `jcdiff`, it calls the command you specified 426with the above configuration, i.e. `j-c-diff`, with 7 427parameters, just like `GIT_EXTERNAL_DIFF` program is called. 428See linkgit:git[1] for details. 429 430 431Defining a custom hunk-header 432^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 433 434Each group of changes (called a "hunk") in the textual diff output 435is prefixed with a line of the form: 436 437 @@ -k,l +n,m @@ TEXT 438 439This is called a 'hunk header'. The "TEXT" portion is by default a line 440that begins with an alphabet, an underscore or a dollar sign; this 441matches what GNU 'diff -p' output uses. This default selection however 442is not suited for some contents, and you can use a customized pattern 443to make a selection. 444 445First, in .gitattributes, you would assign the `diff` attribute 446for paths. 447 448------------------------ 449*.tex diff=tex 450------------------------ 451 452Then, you would define a "diff.tex.xfuncname" configuration to 453specify a regular expression that matches a line that you would 454want to appear as the hunk header "TEXT". Add a section to your 455`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 456 457------------------------ 458[diff "tex"] 459 xfuncname = "^(\\\\(sub)*section\\{.*)$" 460------------------------ 461 462Note. A single level of backslashes are eaten by the 463configuration file parser, so you would need to double the 464backslashes; the pattern above picks a line that begins with a 465backslash, and zero or more occurrences of `sub` followed by 466`section` followed by open brace, to the end of line. 467 468There are a few built-in patterns to make this easier, and `tex` 469is one of them, so you do not have to write the above in your 470configuration file (you still need to enable this with the 471attribute mechanism, via `.gitattributes`). The following built in 472patterns are available: 473 474- `bibtex` suitable for files with BibTeX coded references. 475 476- `cpp` suitable for source code in the C and C++ languages. 477 478- `csharp` suitable for source code in the C# language. 479 480- `fortran` suitable for source code in the Fortran language. 481 482- `html` suitable for HTML/XHTML documents. 483 484- `java` suitable for source code in the Java language. 485 486- `objc` suitable for source code in the Objective-C language. 487 488- `pascal` suitable for source code in the Pascal/Delphi language. 489 490- `php` suitable for source code in the PHP language. 491 492- `python` suitable for source code in the Python language. 493 494- `ruby` suitable for source code in the Ruby language. 495 496- `tex` suitable for source code for LaTeX documents. 497 498 499Customizing word diff 500^^^^^^^^^^^^^^^^^^^^^ 501 502You can customize the rules that `git diff --word-diff` uses to 503split words in a line, by specifying an appropriate regular expression 504in the "diff.*.wordRegex" configuration variable. For example, in TeX 505a backslash followed by a sequence of letters forms a command, but 506several such commands can be run together without intervening 507whitespace. To separate them, use a regular expression in your 508`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 509 510------------------------ 511[diff "tex"] 512 wordRegex = "\\\\[a-zA-Z]+|[{}]|\\\\.|[^\\{}[:space:]]+" 513------------------------ 514 515A built-in pattern is provided for all languages listed in the 516previous section. 517 518 519Performing text diffs of binary files 520^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 521 522Sometimes it is desirable to see the diff of a text-converted 523version of some binary files. For example, a word processor 524document can be converted to an ASCII text representation, and 525the diff of the text shown. Even though this conversion loses 526some information, the resulting diff is useful for human 527viewing (but cannot be applied directly). 528 529The `textconv` config option is used to define a program for 530performing such a conversion. The program should take a single 531argument, the name of a file to convert, and produce the 532resulting text on stdout. 533 534For example, to show the diff of the exif information of a 535file instead of the binary information (assuming you have the 536exif tool installed), add the following section to your 537`$GIT_DIR/config` file (or `$HOME/.gitconfig` file): 538 539------------------------ 540[diff "jpg"] 541 textconv = exif 542------------------------ 543 544NOTE: The text conversion is generally a one-way conversion; 545in this example, we lose the actual image contents and focus 546just on the text data. This means that diffs generated by 547textconv are _not_ suitable for applying. For this reason, 548only `git diff` and the `git log` family of commands (i.e., 549log, whatchanged, show) will perform text conversion. `git 550format-patch` will never generate this output. If you want to 551send somebody a text-converted diff of a binary file (e.g., 552because it quickly conveys the changes you have made), you 553should generate it separately and send it as a comment _in 554addition to_ the usual binary diff that you might send. 555 556Because text conversion can be slow, especially when doing a 557large number of them with `git log -p`, git provides a mechanism 558to cache the output and use it in future diffs. To enable 559caching, set the "cachetextconv" variable in your diff driver's 560config. For example: 561 562------------------------ 563[diff "jpg"] 564 textconv = exif 565 cachetextconv = true 566------------------------ 567 568This will cache the result of running "exif" on each blob 569indefinitely. If you change the textconv config variable for a 570diff driver, git will automatically invalidate the cache entries 571and re-run the textconv filter. If you want to invalidate the 572cache manually (e.g., because your version of "exif" was updated 573and now produces better output), you can remove the cache 574manually with `git update-ref -d refs/notes/textconv/jpg` (where 575"jpg" is the name of the diff driver, as in the example above). 576 577Marking files as binary 578^^^^^^^^^^^^^^^^^^^^^^^ 579 580Git usually guesses correctly whether a blob contains text or binary 581data by examining the beginning of the contents. However, sometimes you 582may want to override its decision, either because a blob contains binary 583data later in the file, or because the content, while technically 584composed of text characters, is opaque to a human reader. For example, 585many postscript files contain only ascii characters, but produce noisy 586and meaningless diffs. 587 588The simplest way to mark a file as binary is to unset the diff 589attribute in the `.gitattributes` file: 590 591------------------------ 592*.ps -diff 593------------------------ 594 595This will cause git to generate `Binary files differ` (or a binary 596patch, if binary patches are enabled) instead of a regular diff. 597 598However, one may also want to specify other diff driver attributes. For 599example, you might want to use `textconv` to convert postscript files to 600an ascii representation for human viewing, but otherwise treat them as 601binary files. You cannot specify both `-diff` and `diff=ps` attributes. 602The solution is to use the `diff.*.binary` config option: 603 604------------------------ 605[diff "ps"] 606 textconv = ps2ascii 607 binary = true 608------------------------ 609 610Performing a three-way merge 611~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 612 613`merge` 614^^^^^^^ 615 616The attribute `merge` affects how three versions of a file is 617merged when a file-level merge is necessary during `git merge`, 618and other commands such as `git revert` and `git cherry-pick`. 619 620Set:: 621 622 Built-in 3-way merge driver is used to merge the 623 contents in a way similar to 'merge' command of `RCS` 624 suite. This is suitable for ordinary text files. 625 626Unset:: 627 628 Take the version from the current branch as the 629 tentative merge result, and declare that the merge has 630 conflicts. This is suitable for binary files that does 631 not have a well-defined merge semantics. 632 633Unspecified:: 634 635 By default, this uses the same built-in 3-way merge 636 driver as is the case the `merge` attribute is set. 637 However, `merge.default` configuration variable can name 638 different merge driver to be used for paths to which the 639 `merge` attribute is unspecified. 640 641String:: 642 643 3-way merge is performed using the specified custom 644 merge driver. The built-in 3-way merge driver can be 645 explicitly specified by asking for "text" driver; the 646 built-in "take the current branch" driver can be 647 requested with "binary". 648 649 650Built-in merge drivers 651^^^^^^^^^^^^^^^^^^^^^^ 652 653There are a few built-in low-level merge drivers defined that 654can be asked for via the `merge` attribute. 655 656text:: 657 658 Usual 3-way file level merge for text files. Conflicted 659 regions are marked with conflict markers `<<<<<<<`, 660 `=======` and `>>>>>>>`. The version from your branch 661 appears before the `=======` marker, and the version 662 from the merged branch appears after the `=======` 663 marker. 664 665binary:: 666 667 Keep the version from your branch in the work tree, but 668 leave the path in the conflicted state for the user to 669 sort out. 670 671union:: 672 673 Run 3-way file level merge for text files, but take 674 lines from both versions, instead of leaving conflict 675 markers. This tends to leave the added lines in the 676 resulting file in random order and the user should 677 verify the result. Do not use this if you do not 678 understand the implications. 679 680 681Defining a custom merge driver 682^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 683 684The definition of a merge driver is done in the `.git/config` 685file, not in the `gitattributes` file, so strictly speaking this 686manual page is a wrong place to talk about it. However... 687 688To define a custom merge driver `filfre`, add a section to your 689`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 690 691---------------------------------------------------------------- 692[merge "filfre"] 693 name = feel-free merge driver 694 driver = filfre %O %A %B 695 recursive = binary 696---------------------------------------------------------------- 697 698The `merge.*.name` variable gives the driver a human-readable 699name. 700 701The `merge.*.driver` variable's value is used to construct a 702command to run to merge ancestor's version (`%O`), current 703version (`%A`) and the other branches' version (`%B`). These 704three tokens are replaced with the names of temporary files that 705hold the contents of these versions when the command line is 706built. Additionally, %L will be replaced with the conflict marker 707size (see below). 708 709The merge driver is expected to leave the result of the merge in 710the file named with `%A` by overwriting it, and exit with zero 711status if it managed to merge them cleanly, or non-zero if there 712were conflicts. 713 714The `merge.*.recursive` variable specifies what other merge 715driver to use when the merge driver is called for an internal 716merge between common ancestors, when there are more than one. 717When left unspecified, the driver itself is used for both 718internal merge and the final merge. 719 720 721`conflict-marker-size` 722^^^^^^^^^^^^^^^^^^^^^^ 723 724This attribute controls the length of conflict markers left in 725the work tree file during a conflicted merge. Only setting to 726the value to a positive integer has any meaningful effect. 727 728For example, this line in `.gitattributes` can be used to tell the merge 729machinery to leave much longer (instead of the usual 7-character-long) 730conflict markers when merging the file `Documentation/git-merge.txt` 731results in a conflict. 732 733------------------------ 734Documentation/git-merge.txt conflict-marker-size=32 735------------------------ 736 737 738Checking whitespace errors 739~~~~~~~~~~~~~~~~~~~~~~~~~~ 740 741`whitespace` 742^^^^^^^^^^^^ 743 744The `core.whitespace` configuration variable allows you to define what 745'diff' and 'apply' should consider whitespace errors for all paths in 746the project (See linkgit:git-config[1]). This attribute gives you finer 747control per path. 748 749Set:: 750 751 Notice all types of potential whitespace errors known to git. 752 753Unset:: 754 755 Do not notice anything as error. 756 757Unspecified:: 758 759 Use the value of `core.whitespace` configuration variable to 760 decide what to notice as error. 761 762String:: 763 764 Specify a comma separate list of common whitespace problems to 765 notice in the same format as `core.whitespace` configuration 766 variable. 767 768 769Creating an archive 770~~~~~~~~~~~~~~~~~~~ 771 772`export-ignore` 773^^^^^^^^^^^^^^^ 774 775Files and directories with the attribute `export-ignore` won't be added to 776archive files. 777 778`export-subst` 779^^^^^^^^^^^^^^ 780 781If the attribute `export-subst` is set for a file then git will expand 782several placeholders when adding this file to an archive. The 783expansion depends on the availability of a commit ID, i.e., if 784linkgit:git-archive[1] has been given a tree instead of a commit or a 785tag then no replacement will be done. The placeholders are the same 786as those for the option `--pretty=format:` of linkgit:git-log[1], 787except that they need to be wrapped like this: `$Format:PLACEHOLDERS$` 788in the file. E.g. the string `$Format:%H$` will be replaced by the 789commit hash. 790 791 792Packing objects 793~~~~~~~~~~~~~~~ 794 795`delta` 796^^^^^^^ 797 798Delta compression will not be attempted for blobs for paths with the 799attribute `delta` set to false. 800 801 802Viewing files in GUI tools 803~~~~~~~~~~~~~~~~~~~~~~~~~~ 804 805`encoding` 806^^^^^^^^^^ 807 808The value of this attribute specifies the character encoding that should 809be used by GUI tools (e.g. linkgit:gitk[1] and linkgit:git-gui[1]) to 810display the contents of the relevant file. Note that due to performance 811considerations linkgit:gitk[1] does not use this attribute unless you 812manually enable per-file encodings in its options. 813 814If this attribute is not set or has an invalid value, the value of the 815`gui.encoding` configuration variable is used instead 816(See linkgit:git-config[1]). 817 818 819USING ATTRIBUTE MACROS 820---------------------- 821 822You do not want any end-of-line conversions applied to, nor textual diffs 823produced for, any binary file you track. You would need to specify e.g. 824 825------------ 826*.jpg -text -diff 827------------ 828 829but that may become cumbersome, when you have many attributes. Using 830attribute macros, you can specify groups of attributes set or unset at 831the same time. The system knows a built-in attribute macro, `binary`: 832 833------------ 834*.jpg binary 835------------ 836 837which is equivalent to the above. Note that the attribute macros can only 838be "Set" (see the above example that sets "binary" macro as if it were an 839ordinary attribute --- setting it in turn unsets "text" and "diff"). 840 841 842DEFINING ATTRIBUTE MACROS 843------------------------- 844 845Custom attribute macros can be defined only in the `.gitattributes` file 846at the toplevel (i.e. not in any subdirectory). The built-in attribute 847macro "binary" is equivalent to: 848 849------------ 850[attr]binary -diff -text 851------------ 852 853 854EXAMPLE 855------- 856 857If you have these three `gitattributes` file: 858 859---------------------------------------------------------------- 860(in $GIT_DIR/info/attributes) 861 862a* foo !bar -baz 863 864(in .gitattributes) 865abc foo bar baz 866 867(in t/.gitattributes) 868ab* merge=filfre 869abc -foo -bar 870*.c frotz 871---------------------------------------------------------------- 872 873the attributes given to path `t/abc` are computed as follows: 874 8751. By examining `t/.gitattributes` (which is in the same 876 directory as the path in question), git finds that the first 877 line matches. `merge` attribute is set. It also finds that 878 the second line matches, and attributes `foo` and `bar` 879 are unset. 880 8812. Then it examines `.gitattributes` (which is in the parent 882 directory), and finds that the first line matches, but 883 `t/.gitattributes` file already decided how `merge`, `foo` 884 and `bar` attributes should be given to this path, so it 885 leaves `foo` and `bar` unset. Attribute `baz` is set. 886 8873. Finally it examines `$GIT_DIR/info/attributes`. This file 888 is used to override the in-tree settings. The first line is 889 a match, and `foo` is set, `bar` is reverted to unspecified 890 state, and `baz` is unset. 891 892As the result, the attributes assignment to `t/abc` becomes: 893 894---------------------------------------------------------------- 895foo set to true 896bar unspecified 897baz set to false 898merge set to string value "filfre" 899frotz unspecified 900---------------------------------------------------------------- 901 902 903 904GIT 905--- 906Part of the linkgit:git[1] suite