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