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 577Performing a three-way merge 578~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 579 580`merge` 581^^^^^^^ 582 583The attribute `merge` affects how three versions of a file is 584merged when a file-level merge is necessary during `git merge`, 585and other commands such as `git revert` and `git cherry-pick`. 586 587Set:: 588 589 Built-in 3-way merge driver is used to merge the 590 contents in a way similar to 'merge' command of `RCS` 591 suite. This is suitable for ordinary text files. 592 593Unset:: 594 595 Take the version from the current branch as the 596 tentative merge result, and declare that the merge has 597 conflicts. This is suitable for binary files that does 598 not have a well-defined merge semantics. 599 600Unspecified:: 601 602 By default, this uses the same built-in 3-way merge 603 driver as is the case the `merge` attribute is set. 604 However, `merge.default` configuration variable can name 605 different merge driver to be used for paths to which the 606 `merge` attribute is unspecified. 607 608String:: 609 610 3-way merge is performed using the specified custom 611 merge driver. The built-in 3-way merge driver can be 612 explicitly specified by asking for "text" driver; the 613 built-in "take the current branch" driver can be 614 requested with "binary". 615 616 617Built-in merge drivers 618^^^^^^^^^^^^^^^^^^^^^^ 619 620There are a few built-in low-level merge drivers defined that 621can be asked for via the `merge` attribute. 622 623text:: 624 625 Usual 3-way file level merge for text files. Conflicted 626 regions are marked with conflict markers `<<<<<<<`, 627 `=======` and `>>>>>>>`. The version from your branch 628 appears before the `=======` marker, and the version 629 from the merged branch appears after the `=======` 630 marker. 631 632binary:: 633 634 Keep the version from your branch in the work tree, but 635 leave the path in the conflicted state for the user to 636 sort out. 637 638union:: 639 640 Run 3-way file level merge for text files, but take 641 lines from both versions, instead of leaving conflict 642 markers. This tends to leave the added lines in the 643 resulting file in random order and the user should 644 verify the result. Do not use this if you do not 645 understand the implications. 646 647 648Defining a custom merge driver 649^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 650 651The definition of a merge driver is done in the `.git/config` 652file, not in the `gitattributes` file, so strictly speaking this 653manual page is a wrong place to talk about it. However... 654 655To define a custom merge driver `filfre`, add a section to your 656`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 657 658---------------------------------------------------------------- 659[merge "filfre"] 660 name = feel-free merge driver 661 driver = filfre %O %A %B 662 recursive = binary 663---------------------------------------------------------------- 664 665The `merge.*.name` variable gives the driver a human-readable 666name. 667 668The `merge.*.driver` variable's value is used to construct a 669command to run to merge ancestor's version (`%O`), current 670version (`%A`) and the other branches' version (`%B`). These 671three tokens are replaced with the names of temporary files that 672hold the contents of these versions when the command line is 673built. Additionally, %L will be replaced with the conflict marker 674size (see below). 675 676The merge driver is expected to leave the result of the merge in 677the file named with `%A` by overwriting it, and exit with zero 678status if it managed to merge them cleanly, or non-zero if there 679were conflicts. 680 681The `merge.*.recursive` variable specifies what other merge 682driver to use when the merge driver is called for an internal 683merge between common ancestors, when there are more than one. 684When left unspecified, the driver itself is used for both 685internal merge and the final merge. 686 687 688`conflict-marker-size` 689^^^^^^^^^^^^^^^^^^^^^^ 690 691This attribute controls the length of conflict markers left in 692the work tree file during a conflicted merge. Only setting to 693the value to a positive integer has any meaningful effect. 694 695For example, this line in `.gitattributes` can be used to tell the merge 696machinery to leave much longer (instead of the usual 7-character-long) 697conflict markers when merging the file `Documentation/git-merge.txt` 698results in a conflict. 699 700------------------------ 701Documentation/git-merge.txt conflict-marker-size=32 702------------------------ 703 704 705Checking whitespace errors 706~~~~~~~~~~~~~~~~~~~~~~~~~~ 707 708`whitespace` 709^^^^^^^^^^^^ 710 711The `core.whitespace` configuration variable allows you to define what 712'diff' and 'apply' should consider whitespace errors for all paths in 713the project (See linkgit:git-config[1]). This attribute gives you finer 714control per path. 715 716Set:: 717 718 Notice all types of potential whitespace errors known to git. 719 720Unset:: 721 722 Do not notice anything as error. 723 724Unspecified:: 725 726 Use the value of `core.whitespace` configuration variable to 727 decide what to notice as error. 728 729String:: 730 731 Specify a comma separate list of common whitespace problems to 732 notice in the same format as `core.whitespace` configuration 733 variable. 734 735 736Creating an archive 737~~~~~~~~~~~~~~~~~~~ 738 739`export-ignore` 740^^^^^^^^^^^^^^^ 741 742Files and directories with the attribute `export-ignore` won't be added to 743archive files. 744 745`export-subst` 746^^^^^^^^^^^^^^ 747 748If the attribute `export-subst` is set for a file then git will expand 749several placeholders when adding this file to an archive. The 750expansion depends on the availability of a commit ID, i.e., if 751linkgit:git-archive[1] has been given a tree instead of a commit or a 752tag then no replacement will be done. The placeholders are the same 753as those for the option `--pretty=format:` of linkgit:git-log[1], 754except that they need to be wrapped like this: `$Format:PLACEHOLDERS$` 755in the file. E.g. the string `$Format:%H$` will be replaced by the 756commit hash. 757 758 759Packing objects 760~~~~~~~~~~~~~~~ 761 762`delta` 763^^^^^^^ 764 765Delta compression will not be attempted for blobs for paths with the 766attribute `delta` set to false. 767 768 769Viewing files in GUI tools 770~~~~~~~~~~~~~~~~~~~~~~~~~~ 771 772`encoding` 773^^^^^^^^^^ 774 775The value of this attribute specifies the character encoding that should 776be used by GUI tools (e.g. linkgit:gitk[1] and linkgit:git-gui[1]) to 777display the contents of the relevant file. Note that due to performance 778considerations linkgit:gitk[1] does not use this attribute unless you 779manually enable per-file encodings in its options. 780 781If this attribute is not set or has an invalid value, the value of the 782`gui.encoding` configuration variable is used instead 783(See linkgit:git-config[1]). 784 785 786USING ATTRIBUTE MACROS 787---------------------- 788 789You do not want any end-of-line conversions applied to, nor textual diffs 790produced for, any binary file you track. You would need to specify e.g. 791 792------------ 793*.jpg -text -diff 794------------ 795 796but that may become cumbersome, when you have many attributes. Using 797attribute macros, you can specify groups of attributes set or unset at 798the same time. The system knows a built-in attribute macro, `binary`: 799 800------------ 801*.jpg binary 802------------ 803 804which is equivalent to the above. Note that the attribute macros can only 805be "Set" (see the above example that sets "binary" macro as if it were an 806ordinary attribute --- setting it in turn unsets "text" and "diff"). 807 808 809DEFINING ATTRIBUTE MACROS 810------------------------- 811 812Custom attribute macros can be defined only in the `.gitattributes` file 813at the toplevel (i.e. not in any subdirectory). The built-in attribute 814macro "binary" is equivalent to: 815 816------------ 817[attr]binary -diff -text 818------------ 819 820 821EXAMPLE 822------- 823 824If you have these three `gitattributes` file: 825 826---------------------------------------------------------------- 827(in $GIT_DIR/info/attributes) 828 829a* foo !bar -baz 830 831(in .gitattributes) 832abc foo bar baz 833 834(in t/.gitattributes) 835ab* merge=filfre 836abc -foo -bar 837*.c frotz 838---------------------------------------------------------------- 839 840the attributes given to path `t/abc` are computed as follows: 841 8421. By examining `t/.gitattributes` (which is in the same 843 directory as the path in question), git finds that the first 844 line matches. `merge` attribute is set. It also finds that 845 the second line matches, and attributes `foo` and `bar` 846 are unset. 847 8482. Then it examines `.gitattributes` (which is in the parent 849 directory), and finds that the first line matches, but 850 `t/.gitattributes` file already decided how `merge`, `foo` 851 and `bar` attributes should be given to this path, so it 852 leaves `foo` and `bar` unset. Attribute `baz` is set. 853 8543. Finally it examines `$GIT_DIR/info/attributes`. This file 855 is used to override the in-tree settings. The first line is 856 a match, and `foo` is set, `bar` is reverted to unspecified 857 state, and `baz` is unset. 858 859As the result, the attributes assignment to `t/abc` becomes: 860 861---------------------------------------------------------------- 862foo set to true 863bar unspecified 864baz set to false 865merge set to string value "filfre" 866frotz unspecified 867---------------------------------------------------------------- 868 869 870 871GIT 872--- 873Part of the linkgit:git[1] suite