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- `html` suitable for HTML/XHTML documents. 481 482- `java` suitable for source code in the Java language. 483 484- `objc` suitable for source code in the Objective-C language. 485 486- `pascal` suitable for source code in the Pascal/Delphi language. 487 488- `php` suitable for source code in the PHP language. 489 490- `python` suitable for source code in the Python language. 491 492- `ruby` suitable for source code in the Ruby language. 493 494- `tex` suitable for source code for LaTeX documents. 495 496 497Customizing word diff 498^^^^^^^^^^^^^^^^^^^^^ 499 500You can customize the rules that `git diff --word-diff` uses to 501split words in a line, by specifying an appropriate regular expression 502in the "diff.*.wordRegex" configuration variable. For example, in TeX 503a backslash followed by a sequence of letters forms a command, but 504several such commands can be run together without intervening 505whitespace. To separate them, use a regular expression in your 506`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 507 508------------------------ 509[diff "tex"] 510 wordRegex = "\\\\[a-zA-Z]+|[{}]|\\\\.|[^\\{}[:space:]]+" 511------------------------ 512 513A built-in pattern is provided for all languages listed in the 514previous section. 515 516 517Performing text diffs of binary files 518^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 519 520Sometimes it is desirable to see the diff of a text-converted 521version of some binary files. For example, a word processor 522document can be converted to an ASCII text representation, and 523the diff of the text shown. Even though this conversion loses 524some information, the resulting diff is useful for human 525viewing (but cannot be applied directly). 526 527The `textconv` config option is used to define a program for 528performing such a conversion. The program should take a single 529argument, the name of a file to convert, and produce the 530resulting text on stdout. 531 532For example, to show the diff of the exif information of a 533file instead of the binary information (assuming you have the 534exif tool installed), add the following section to your 535`$GIT_DIR/config` file (or `$HOME/.gitconfig` file): 536 537------------------------ 538[diff "jpg"] 539 textconv = exif 540------------------------ 541 542NOTE: The text conversion is generally a one-way conversion; 543in this example, we lose the actual image contents and focus 544just on the text data. This means that diffs generated by 545textconv are _not_ suitable for applying. For this reason, 546only `git diff` and the `git log` family of commands (i.e., 547log, whatchanged, show) will perform text conversion. `git 548format-patch` will never generate this output. If you want to 549send somebody a text-converted diff of a binary file (e.g., 550because it quickly conveys the changes you have made), you 551should generate it separately and send it as a comment _in 552addition to_ the usual binary diff that you might send. 553 554Because text conversion can be slow, especially when doing a 555large number of them with `git log -p`, git provides a mechanism 556to cache the output and use it in future diffs. To enable 557caching, set the "cachetextconv" variable in your diff driver's 558config. For example: 559 560------------------------ 561[diff "jpg"] 562 textconv = exif 563 cachetextconv = true 564------------------------ 565 566This will cache the result of running "exif" on each blob 567indefinitely. If you change the textconv config variable for a 568diff driver, git will automatically invalidate the cache entries 569and re-run the textconv filter. If you want to invalidate the 570cache manually (e.g., because your version of "exif" was updated 571and now produces better output), you can remove the cache 572manually with `git update-ref -d refs/notes/textconv/jpg` (where 573"jpg" is the name of the diff driver, as in the example above). 574 575Performing a three-way merge 576~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 577 578`merge` 579^^^^^^^ 580 581The attribute `merge` affects how three versions of a file is 582merged when a file-level merge is necessary during `git merge`, 583and other commands such as `git revert` and `git cherry-pick`. 584 585Set:: 586 587 Built-in 3-way merge driver is used to merge the 588 contents in a way similar to 'merge' command of `RCS` 589 suite. This is suitable for ordinary text files. 590 591Unset:: 592 593 Take the version from the current branch as the 594 tentative merge result, and declare that the merge has 595 conflicts. This is suitable for binary files that does 596 not have a well-defined merge semantics. 597 598Unspecified:: 599 600 By default, this uses the same built-in 3-way merge 601 driver as is the case the `merge` attribute is set. 602 However, `merge.default` configuration variable can name 603 different merge driver to be used for paths to which the 604 `merge` attribute is unspecified. 605 606String:: 607 608 3-way merge is performed using the specified custom 609 merge driver. The built-in 3-way merge driver can be 610 explicitly specified by asking for "text" driver; the 611 built-in "take the current branch" driver can be 612 requested with "binary". 613 614 615Built-in merge drivers 616^^^^^^^^^^^^^^^^^^^^^^ 617 618There are a few built-in low-level merge drivers defined that 619can be asked for via the `merge` attribute. 620 621text:: 622 623 Usual 3-way file level merge for text files. Conflicted 624 regions are marked with conflict markers `<<<<<<<`, 625 `=======` and `>>>>>>>`. The version from your branch 626 appears before the `=======` marker, and the version 627 from the merged branch appears after the `=======` 628 marker. 629 630binary:: 631 632 Keep the version from your branch in the work tree, but 633 leave the path in the conflicted state for the user to 634 sort out. 635 636union:: 637 638 Run 3-way file level merge for text files, but take 639 lines from both versions, instead of leaving conflict 640 markers. This tends to leave the added lines in the 641 resulting file in random order and the user should 642 verify the result. Do not use this if you do not 643 understand the implications. 644 645 646Defining a custom merge driver 647^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 648 649The definition of a merge driver is done in the `.git/config` 650file, not in the `gitattributes` file, so strictly speaking this 651manual page is a wrong place to talk about it. However... 652 653To define a custom merge driver `filfre`, add a section to your 654`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 655 656---------------------------------------------------------------- 657[merge "filfre"] 658 name = feel-free merge driver 659 driver = filfre %O %A %B 660 recursive = binary 661---------------------------------------------------------------- 662 663The `merge.*.name` variable gives the driver a human-readable 664name. 665 666The `merge.*.driver` variable's value is used to construct a 667command to run to merge ancestor's version (`%O`), current 668version (`%A`) and the other branches' version (`%B`). These 669three tokens are replaced with the names of temporary files that 670hold the contents of these versions when the command line is 671built. Additionally, %L will be replaced with the conflict marker 672size (see below). 673 674The merge driver is expected to leave the result of the merge in 675the file named with `%A` by overwriting it, and exit with zero 676status if it managed to merge them cleanly, or non-zero if there 677were conflicts. 678 679The `merge.*.recursive` variable specifies what other merge 680driver to use when the merge driver is called for an internal 681merge between common ancestors, when there are more than one. 682When left unspecified, the driver itself is used for both 683internal merge and the final merge. 684 685 686`conflict-marker-size` 687^^^^^^^^^^^^^^^^^^^^^^ 688 689This attribute controls the length of conflict markers left in 690the work tree file during a conflicted merge. Only setting to 691the value to a positive integer has any meaningful effect. 692 693For example, this line in `.gitattributes` can be used to tell the merge 694machinery to leave much longer (instead of the usual 7-character-long) 695conflict markers when merging the file `Documentation/git-merge.txt` 696results in a conflict. 697 698------------------------ 699Documentation/git-merge.txt conflict-marker-size=32 700------------------------ 701 702 703Checking whitespace errors 704~~~~~~~~~~~~~~~~~~~~~~~~~~ 705 706`whitespace` 707^^^^^^^^^^^^ 708 709The `core.whitespace` configuration variable allows you to define what 710'diff' and 'apply' should consider whitespace errors for all paths in 711the project (See linkgit:git-config[1]). This attribute gives you finer 712control per path. 713 714Set:: 715 716 Notice all types of potential whitespace errors known to git. 717 718Unset:: 719 720 Do not notice anything as error. 721 722Unspecified:: 723 724 Use the value of `core.whitespace` configuration variable to 725 decide what to notice as error. 726 727String:: 728 729 Specify a comma separate list of common whitespace problems to 730 notice in the same format as `core.whitespace` configuration 731 variable. 732 733 734Creating an archive 735~~~~~~~~~~~~~~~~~~~ 736 737`export-ignore` 738^^^^^^^^^^^^^^^ 739 740Files and directories with the attribute `export-ignore` won't be added to 741archive files. 742 743`export-subst` 744^^^^^^^^^^^^^^ 745 746If the attribute `export-subst` is set for a file then git will expand 747several placeholders when adding this file to an archive. The 748expansion depends on the availability of a commit ID, i.e., if 749linkgit:git-archive[1] has been given a tree instead of a commit or a 750tag then no replacement will be done. The placeholders are the same 751as those for the option `--pretty=format:` of linkgit:git-log[1], 752except that they need to be wrapped like this: `$Format:PLACEHOLDERS$` 753in the file. E.g. the string `$Format:%H$` will be replaced by the 754commit hash. 755 756 757Packing objects 758~~~~~~~~~~~~~~~ 759 760`delta` 761^^^^^^^ 762 763Delta compression will not be attempted for blobs for paths with the 764attribute `delta` set to false. 765 766 767Viewing files in GUI tools 768~~~~~~~~~~~~~~~~~~~~~~~~~~ 769 770`encoding` 771^^^^^^^^^^ 772 773The value of this attribute specifies the character encoding that should 774be used by GUI tools (e.g. linkgit:gitk[1] and linkgit:git-gui[1]) to 775display the contents of the relevant file. Note that due to performance 776considerations linkgit:gitk[1] does not use this attribute unless you 777manually enable per-file encodings in its options. 778 779If this attribute is not set or has an invalid value, the value of the 780`gui.encoding` configuration variable is used instead 781(See linkgit:git-config[1]). 782 783 784USING ATTRIBUTE MACROS 785---------------------- 786 787You do not want any end-of-line conversions applied to, nor textual diffs 788produced for, any binary file you track. You would need to specify e.g. 789 790------------ 791*.jpg -text -diff 792------------ 793 794but that may become cumbersome, when you have many attributes. Using 795attribute macros, you can specify groups of attributes set or unset at 796the same time. The system knows a built-in attribute macro, `binary`: 797 798------------ 799*.jpg binary 800------------ 801 802which is equivalent to the above. Note that the attribute macros can only 803be "Set" (see the above example that sets "binary" macro as if it were an 804ordinary attribute --- setting it in turn unsets "text" and "diff"). 805 806 807DEFINING ATTRIBUTE MACROS 808------------------------- 809 810Custom attribute macros can be defined only in the `.gitattributes` file 811at the toplevel (i.e. not in any subdirectory). The built-in attribute 812macro "binary" is equivalent to: 813 814------------ 815[attr]binary -diff -text 816------------ 817 818 819EXAMPLE 820------- 821 822If you have these three `gitattributes` file: 823 824---------------------------------------------------------------- 825(in $GIT_DIR/info/attributes) 826 827a* foo !bar -baz 828 829(in .gitattributes) 830abc foo bar baz 831 832(in t/.gitattributes) 833ab* merge=filfre 834abc -foo -bar 835*.c frotz 836---------------------------------------------------------------- 837 838the attributes given to path `t/abc` are computed as follows: 839 8401. By examining `t/.gitattributes` (which is in the same 841 directory as the path in question), git finds that the first 842 line matches. `merge` attribute is set. It also finds that 843 the second line matches, and attributes `foo` and `bar` 844 are unset. 845 8462. Then it examines `.gitattributes` (which is in the parent 847 directory), and finds that the first line matches, but 848 `t/.gitattributes` file already decided how `merge`, `foo` 849 and `bar` attributes should be given to this path, so it 850 leaves `foo` and `bar` unset. Attribute `baz` is set. 851 8523. Finally it examines `$GIT_DIR/info/attributes`. This file 853 is used to override the in-tree settings. The first line is 854 a match, and `foo` is set, `bar` is reverted to unspecified 855 state, and `baz` is unset. 856 857As the result, the attributes assignment to `t/abc` becomes: 858 859---------------------------------------------------------------- 860foo set to true 861bar unspecified 862baz set to false 863merge set to string value "filfre" 864frotz unspecified 865---------------------------------------------------------------- 866 867 868 869GIT 870--- 871Part of the linkgit:git[1] suite