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 committed 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 185If you simply want to have CRLF line endings in your working directory 186regardless of the repository you are working with, you can set the 187config variable "core.autocrlf" without using any attributes. 188 189------------------------ 190[core] 191 autocrlf = true 192------------------------ 193 194This does not force normalization of text files, but does ensure 195that text files that you introduce to the repository have their line 196endings normalized to LF when they are added, and that files that are 197already normalized in the repository stay normalized. 198 199If you want to ensure that text files that any contributor introduces to 200the repository have their line endings normalized, you can set the 201`text` attribute to "auto" for _all_ files. 202 203------------------------ 204* text=auto 205------------------------ 206 207The attributes allow a fine-grained control, how the line endings 208are converted. 209Here is an example that will make Git normalize .txt, .vcproj and .sh 210files, ensure that .vcproj files have CRLF and .sh files have LF in 211the working directory, and prevent .jpg files from being normalized 212regardless of their content. 213 214------------------------ 215* text=auto 216*.txt text 217*.vcproj text eol=crlf 218*.sh text eol=lf 219*.jpg -text 220------------------------ 221 222NOTE: When `text=auto` conversion is enabled in a cross-platform 223project using push and pull to a central repository the text files 224containing CRLFs should be normalized. 225 226From a clean working directory: 227 228------------------------------------------------- 229$ echo "* text=auto" >.gitattributes 230$ rm .git/index # Remove the index to force Git to 231$ git reset # re-scan the working directory 232$ git status # Show files that will be normalized 233$ git add -u 234$ git add .gitattributes 235$ git commit -m "Introduce end-of-line normalization" 236------------------------------------------------- 237 238If any files that should not be normalized show up in 'git status', 239unset their `text` attribute before running 'git add -u'. 240 241------------------------ 242manual.pdf -text 243------------------------ 244 245Conversely, text files that Git does not detect can have normalization 246enabled manually. 247 248------------------------ 249weirdchars.txt text 250------------------------ 251 252If `core.safecrlf` is set to "true" or "warn", Git verifies if 253the conversion is reversible for the current setting of 254`core.autocrlf`. For "true", Git rejects irreversible 255conversions; for "warn", Git only prints a warning but accepts 256an irreversible conversion. The safety triggers to prevent such 257a conversion done to the files in the work tree, but there are a 258few exceptions. Even though... 259 260- 'git add' itself does not touch the files in the work tree, the 261 next checkout would, so the safety triggers; 262 263- 'git apply' to update a text file with a patch does touch the files 264 in the work tree, but the operation is about text files and CRLF 265 conversion is about fixing the line ending inconsistencies, so the 266 safety does not trigger; 267 268- 'git diff' itself does not touch the files in the work tree, it is 269 often run to inspect the changes you intend to next 'git add'. To 270 catch potential problems early, safety triggers. 271 272 273`ident` 274^^^^^^^ 275 276When the attribute `ident` is set for a path, Git replaces 277`$Id$` in the blob object with `$Id:`, followed by the 27840-character hexadecimal blob object name, followed by a dollar 279sign `$` upon checkout. Any byte sequence that begins with 280`$Id:` and ends with `$` in the worktree file is replaced 281with `$Id$` upon check-in. 282 283 284`filter` 285^^^^^^^^ 286 287A `filter` attribute can be set to a string value that names a 288filter driver specified in the configuration. 289 290A filter driver consists of a `clean` command and a `smudge` 291command, either of which can be left unspecified. Upon 292checkout, when the `smudge` command is specified, the command is 293fed the blob object from its standard input, and its standard 294output is used to update the worktree file. Similarly, the 295`clean` command is used to convert the contents of worktree file 296upon checkin. By default these commands process only a single 297blob and terminate. If a long running `process` filter is used 298in place of `clean` and/or `smudge` filters, then Git can process 299all blobs with a single filter command invocation for the entire 300life of a single Git command, for example `git add --all`. If a 301long running `process` filter is configured then it always takes 302precedence over a configured single blob filter. See section 303below for the description of the protocol used to communicate with 304a `process` filter. 305 306One use of the content filtering is to massage the content into a shape 307that is more convenient for the platform, filesystem, and the user to use. 308For this mode of operation, the key phrase here is "more convenient" and 309not "turning something unusable into usable". In other words, the intent 310is that if someone unsets the filter driver definition, or does not have 311the appropriate filter program, the project should still be usable. 312 313Another use of the content filtering is to store the content that cannot 314be directly used in the repository (e.g. a UUID that refers to the true 315content stored outside Git, or an encrypted content) and turn it into a 316usable form upon checkout (e.g. download the external content, or decrypt 317the encrypted content). 318 319These two filters behave differently, and by default, a filter is taken as 320the former, massaging the contents into more convenient shape. A missing 321filter driver definition in the config, or a filter driver that exits with 322a non-zero status, is not an error but makes the filter a no-op passthru. 323 324You can declare that a filter turns a content that by itself is unusable 325into a usable content by setting the filter.<driver>.required configuration 326variable to `true`. 327 328For example, in .gitattributes, you would assign the `filter` 329attribute for paths. 330 331------------------------ 332*.c filter=indent 333------------------------ 334 335Then you would define a "filter.indent.clean" and "filter.indent.smudge" 336configuration in your .git/config to specify a pair of commands to 337modify the contents of C programs when the source files are checked 338in ("clean" is run) and checked out (no change is made because the 339command is "cat"). 340 341------------------------ 342[filter "indent"] 343 clean = indent 344 smudge = cat 345------------------------ 346 347For best results, `clean` should not alter its output further if it is 348run twice ("clean->clean" should be equivalent to "clean"), and 349multiple `smudge` commands should not alter `clean`'s output 350("smudge->smudge->clean" should be equivalent to "clean"). See the 351section on merging below. 352 353The "indent" filter is well-behaved in this regard: it will not modify 354input that is already correctly indented. In this case, the lack of a 355smudge filter means that the clean filter _must_ accept its own output 356without modifying it. 357 358If a filter _must_ succeed in order to make the stored contents usable, 359you can declare that the filter is `required`, in the configuration: 360 361------------------------ 362[filter "crypt"] 363 clean = openssl enc ... 364 smudge = openssl enc -d ... 365 required 366------------------------ 367 368Sequence "%f" on the filter command line is replaced with the name of 369the file the filter is working on. A filter might use this in keyword 370substitution. For example: 371 372------------------------ 373[filter "p4"] 374 clean = git-p4-filter --clean %f 375 smudge = git-p4-filter --smudge %f 376------------------------ 377 378Note that "%f" is the name of the path that is being worked on. Depending 379on the version that is being filtered, the corresponding file on disk may 380not exist, or may have different contents. So, smudge and clean commands 381should not try to access the file on disk, but only act as filters on the 382content provided to them on standard input. 383 384Long Running Filter Process 385^^^^^^^^^^^^^^^^^^^^^^^^^^^ 386 387If the filter command (a string value) is defined via 388`filter.<driver>.process` then Git can process all blobs with a 389single filter invocation for the entire life of a single Git 390command. This is achieved by using a packet format (pkt-line, 391see technical/protocol-common.txt) based protocol over standard 392input and standard output as follows. All packets, except for the 393"*CONTENT" packets and the "0000" flush packet, are considered 394text and therefore are terminated by a LF. 395 396Git starts the filter when it encounters the first file 397that needs to be cleaned or smudged. After the filter started 398Git sends a welcome message ("git-filter-client"), a list of supported 399protocol version numbers, and a flush packet. Git expects to read a welcome 400response message ("git-filter-server"), exactly one protocol version number 401from the previously sent list, and a flush packet. All further 402communication will be based on the selected version. The remaining 403protocol description below documents "version=2". Please note that 404"version=42" in the example below does not exist and is only there 405to illustrate how the protocol would look like with more than one 406version. 407 408After the version negotiation Git sends a list of all capabilities that 409it supports and a flush packet. Git expects to read a list of desired 410capabilities, which must be a subset of the supported capabilities list, 411and a flush packet as response: 412------------------------ 413packet: git> git-filter-client 414packet: git> version=2 415packet: git> version=42 416packet: git> 0000 417packet: git< git-filter-server 418packet: git< version=2 419packet: git< 0000 420packet: git> capability=clean 421packet: git> capability=smudge 422packet: git> capability=not-yet-invented 423packet: git> 0000 424packet: git< capability=clean 425packet: git< capability=smudge 426packet: git< 0000 427------------------------ 428Supported filter capabilities in version 2 are "clean" and 429"smudge". 430 431Afterwards Git sends a list of "key=value" pairs terminated with 432a flush packet. The list will contain at least the filter command 433(based on the supported capabilities) and the pathname of the file 434to filter relative to the repository root. Right after the flush packet 435Git sends the content split in zero or more pkt-line packets and a 436flush packet to terminate content. Please note, that the filter 437must not send any response before it received the content and the 438final flush packet. 439------------------------ 440packet: git> command=smudge 441packet: git> pathname=path/testfile.dat 442packet: git> 0000 443packet: git> CONTENT 444packet: git> 0000 445------------------------ 446 447The filter is expected to respond with a list of "key=value" pairs 448terminated with a flush packet. If the filter does not experience 449problems then the list must contain a "success" status. Right after 450these packets the filter is expected to send the content in zero 451or more pkt-line packets and a flush packet at the end. Finally, a 452second list of "key=value" pairs terminated with a flush packet 453is expected. The filter can change the status in the second list 454or keep the status as is with an empty list. Please note that the 455empty list must be terminated with a flush packet regardless. 456 457------------------------ 458packet: git< status=success 459packet: git< 0000 460packet: git< SMUDGED_CONTENT 461packet: git< 0000 462packet: git< 0000 # empty list, keep "status=success" unchanged! 463------------------------ 464 465If the result content is empty then the filter is expected to respond 466with a "success" status and a flush packet to signal the empty content. 467------------------------ 468packet: git< status=success 469packet: git< 0000 470packet: git< 0000 # empty content! 471packet: git< 0000 # empty list, keep "status=success" unchanged! 472------------------------ 473 474In case the filter cannot or does not want to process the content, 475it is expected to respond with an "error" status. 476------------------------ 477packet: git< status=error 478packet: git< 0000 479------------------------ 480 481If the filter experiences an error during processing, then it can 482send the status "error" after the content was (partially or 483completely) sent. 484------------------------ 485packet: git< status=success 486packet: git< 0000 487packet: git< HALF_WRITTEN_ERRONEOUS_CONTENT 488packet: git< 0000 489packet: git< status=error 490packet: git< 0000 491------------------------ 492 493In case the filter cannot or does not want to process the content 494as well as any future content for the lifetime of the Git process, 495then it is expected to respond with an "abort" status at any point 496in the protocol. 497------------------------ 498packet: git< status=abort 499packet: git< 0000 500------------------------ 501 502Git neither stops nor restarts the filter process in case the 503"error"/"abort" status is set. However, Git sets its exit code 504according to the `filter.<driver>.required` flag, mimicking the 505behavior of the `filter.<driver>.clean` / `filter.<driver>.smudge` 506mechanism. 507 508If the filter dies during the communication or does not adhere to 509the protocol then Git will stop the filter process and restart it 510with the next file that needs to be processed. Depending on the 511`filter.<driver>.required` flag Git will interpret that as error. 512 513After the filter has processed a blob it is expected to wait for 514the next "key=value" list containing a command. Git will close 515the command pipe on exit. The filter is expected to detect EOF 516and exit gracefully on its own. Git will wait until the filter 517process has stopped. 518 519A long running filter demo implementation can be found in 520`contrib/long-running-filter/example.pl` located in the Git 521core repository. If you develop your own long running filter 522process then the `GIT_TRACE_PACKET` environment variables can be 523very helpful for debugging (see linkgit:git[1]). 524 525Please note that you cannot use an existing `filter.<driver>.clean` 526or `filter.<driver>.smudge` command with `filter.<driver>.process` 527because the former two use a different inter process communication 528protocol than the latter one. 529 530 531Interaction between checkin/checkout attributes 532^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 533 534In the check-in codepath, the worktree file is first converted 535with `filter` driver (if specified and corresponding driver 536defined), then the result is processed with `ident` (if 537specified), and then finally with `text` (again, if specified 538and applicable). 539 540In the check-out codepath, the blob content is first converted 541with `text`, and then `ident` and fed to `filter`. 542 543 544Merging branches with differing checkin/checkout attributes 545^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 546 547If you have added attributes to a file that cause the canonical 548repository format for that file to change, such as adding a 549clean/smudge filter or text/eol/ident attributes, merging anything 550where the attribute is not in place would normally cause merge 551conflicts. 552 553To prevent these unnecessary merge conflicts, Git can be told to run a 554virtual check-out and check-in of all three stages of a file when 555resolving a three-way merge by setting the `merge.renormalize` 556configuration variable. This prevents changes caused by check-in 557conversion from causing spurious merge conflicts when a converted file 558is merged with an unconverted file. 559 560As long as a "smudge->clean" results in the same output as a "clean" 561even on files that are already smudged, this strategy will 562automatically resolve all filter-related conflicts. Filters that do 563not act in this way may cause additional merge conflicts that must be 564resolved manually. 565 566 567Generating diff text 568~~~~~~~~~~~~~~~~~~~~ 569 570`diff` 571^^^^^^ 572 573The attribute `diff` affects how Git generates diffs for particular 574files. It can tell Git whether to generate a textual patch for the path 575or to treat the path as a binary file. It can also affect what line is 576shown on the hunk header `@@ -k,l +n,m @@` line, tell Git to use an 577external command to generate the diff, or ask Git to convert binary 578files to a text format before generating the diff. 579 580Set:: 581 582 A path to which the `diff` attribute is set is treated 583 as text, even when they contain byte values that 584 normally never appear in text files, such as NUL. 585 586Unset:: 587 588 A path to which the `diff` attribute is unset will 589 generate `Binary files differ` (or a binary patch, if 590 binary patches are enabled). 591 592Unspecified:: 593 594 A path to which the `diff` attribute is unspecified 595 first gets its contents inspected, and if it looks like 596 text and is smaller than core.bigFileThreshold, it is treated 597 as text. Otherwise it would generate `Binary files differ`. 598 599String:: 600 601 Diff is shown using the specified diff driver. Each driver may 602 specify one or more options, as described in the following 603 section. The options for the diff driver "foo" are defined 604 by the configuration variables in the "diff.foo" section of the 605 Git config file. 606 607 608Defining an external diff driver 609^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 610 611The definition of a diff driver is done in `gitconfig`, not 612`gitattributes` file, so strictly speaking this manual page is a 613wrong place to talk about it. However... 614 615To define an external diff driver `jcdiff`, add a section to your 616`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 617 618---------------------------------------------------------------- 619[diff "jcdiff"] 620 command = j-c-diff 621---------------------------------------------------------------- 622 623When Git needs to show you a diff for the path with `diff` 624attribute set to `jcdiff`, it calls the command you specified 625with the above configuration, i.e. `j-c-diff`, with 7 626parameters, just like `GIT_EXTERNAL_DIFF` program is called. 627See linkgit:git[1] for details. 628 629 630Defining a custom hunk-header 631^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 632 633Each group of changes (called a "hunk") in the textual diff output 634is prefixed with a line of the form: 635 636 @@ -k,l +n,m @@ TEXT 637 638This is called a 'hunk header'. The "TEXT" portion is by default a line 639that begins with an alphabet, an underscore or a dollar sign; this 640matches what GNU 'diff -p' output uses. This default selection however 641is not suited for some contents, and you can use a customized pattern 642to make a selection. 643 644First, in .gitattributes, you would assign the `diff` attribute 645for paths. 646 647------------------------ 648*.tex diff=tex 649------------------------ 650 651Then, you would define a "diff.tex.xfuncname" configuration to 652specify a regular expression that matches a line that you would 653want to appear as the hunk header "TEXT". Add a section to your 654`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 655 656------------------------ 657[diff "tex"] 658 xfuncname = "^(\\\\(sub)*section\\{.*)$" 659------------------------ 660 661Note. A single level of backslashes are eaten by the 662configuration file parser, so you would need to double the 663backslashes; the pattern above picks a line that begins with a 664backslash, and zero or more occurrences of `sub` followed by 665`section` followed by open brace, to the end of line. 666 667There are a few built-in patterns to make this easier, and `tex` 668is one of them, so you do not have to write the above in your 669configuration file (you still need to enable this with the 670attribute mechanism, via `.gitattributes`). The following built in 671patterns are available: 672 673- `ada` suitable for source code in the Ada language. 674 675- `bibtex` suitable for files with BibTeX coded references. 676 677- `cpp` suitable for source code in the C and C++ languages. 678 679- `csharp` suitable for source code in the C# language. 680 681- `css` suitable for cascading style sheets. 682 683- `fortran` suitable for source code in the Fortran language. 684 685- `fountain` suitable for Fountain documents. 686 687- `html` suitable for HTML/XHTML documents. 688 689- `java` suitable for source code in the Java language. 690 691- `matlab` suitable for source code in the MATLAB language. 692 693- `objc` suitable for source code in the Objective-C language. 694 695- `pascal` suitable for source code in the Pascal/Delphi language. 696 697- `perl` suitable for source code in the Perl language. 698 699- `php` suitable for source code in the PHP language. 700 701- `python` suitable for source code in the Python language. 702 703- `ruby` suitable for source code in the Ruby language. 704 705- `tex` suitable for source code for LaTeX documents. 706 707 708Customizing word diff 709^^^^^^^^^^^^^^^^^^^^^ 710 711You can customize the rules that `git diff --word-diff` uses to 712split words in a line, by specifying an appropriate regular expression 713in the "diff.*.wordRegex" configuration variable. For example, in TeX 714a backslash followed by a sequence of letters forms a command, but 715several such commands can be run together without intervening 716whitespace. To separate them, use a regular expression in your 717`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 718 719------------------------ 720[diff "tex"] 721 wordRegex = "\\\\[a-zA-Z]+|[{}]|\\\\.|[^\\{}[:space:]]+" 722------------------------ 723 724A built-in pattern is provided for all languages listed in the 725previous section. 726 727 728Performing text diffs of binary files 729^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 730 731Sometimes it is desirable to see the diff of a text-converted 732version of some binary files. For example, a word processor 733document can be converted to an ASCII text representation, and 734the diff of the text shown. Even though this conversion loses 735some information, the resulting diff is useful for human 736viewing (but cannot be applied directly). 737 738The `textconv` config option is used to define a program for 739performing such a conversion. The program should take a single 740argument, the name of a file to convert, and produce the 741resulting text on stdout. 742 743For example, to show the diff of the exif information of a 744file instead of the binary information (assuming you have the 745exif tool installed), add the following section to your 746`$GIT_DIR/config` file (or `$HOME/.gitconfig` file): 747 748------------------------ 749[diff "jpg"] 750 textconv = exif 751------------------------ 752 753NOTE: The text conversion is generally a one-way conversion; 754in this example, we lose the actual image contents and focus 755just on the text data. This means that diffs generated by 756textconv are _not_ suitable for applying. For this reason, 757only `git diff` and the `git log` family of commands (i.e., 758log, whatchanged, show) will perform text conversion. `git 759format-patch` will never generate this output. If you want to 760send somebody a text-converted diff of a binary file (e.g., 761because it quickly conveys the changes you have made), you 762should generate it separately and send it as a comment _in 763addition to_ the usual binary diff that you might send. 764 765Because text conversion can be slow, especially when doing a 766large number of them with `git log -p`, Git provides a mechanism 767to cache the output and use it in future diffs. To enable 768caching, set the "cachetextconv" variable in your diff driver's 769config. For example: 770 771------------------------ 772[diff "jpg"] 773 textconv = exif 774 cachetextconv = true 775------------------------ 776 777This will cache the result of running "exif" on each blob 778indefinitely. If you change the textconv config variable for a 779diff driver, Git will automatically invalidate the cache entries 780and re-run the textconv filter. If you want to invalidate the 781cache manually (e.g., because your version of "exif" was updated 782and now produces better output), you can remove the cache 783manually with `git update-ref -d refs/notes/textconv/jpg` (where 784"jpg" is the name of the diff driver, as in the example above). 785 786Choosing textconv versus external diff 787^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 788 789If you want to show differences between binary or specially-formatted 790blobs in your repository, you can choose to use either an external diff 791command, or to use textconv to convert them to a diff-able text format. 792Which method you choose depends on your exact situation. 793 794The advantage of using an external diff command is flexibility. You are 795not bound to find line-oriented changes, nor is it necessary for the 796output to resemble unified diff. You are free to locate and report 797changes in the most appropriate way for your data format. 798 799A textconv, by comparison, is much more limiting. You provide a 800transformation of the data into a line-oriented text format, and Git 801uses its regular diff tools to generate the output. There are several 802advantages to choosing this method: 803 8041. Ease of use. It is often much simpler to write a binary to text 805 transformation than it is to perform your own diff. In many cases, 806 existing programs can be used as textconv filters (e.g., exif, 807 odt2txt). 808 8092. Git diff features. By performing only the transformation step 810 yourself, you can still utilize many of Git's diff features, 811 including colorization, word-diff, and combined diffs for merges. 812 8133. Caching. Textconv caching can speed up repeated diffs, such as those 814 you might trigger by running `git log -p`. 815 816 817Marking files as binary 818^^^^^^^^^^^^^^^^^^^^^^^ 819 820Git usually guesses correctly whether a blob contains text or binary 821data by examining the beginning of the contents. However, sometimes you 822may want to override its decision, either because a blob contains binary 823data later in the file, or because the content, while technically 824composed of text characters, is opaque to a human reader. For example, 825many postscript files contain only ASCII characters, but produce noisy 826and meaningless diffs. 827 828The simplest way to mark a file as binary is to unset the diff 829attribute in the `.gitattributes` file: 830 831------------------------ 832*.ps -diff 833------------------------ 834 835This will cause Git to generate `Binary files differ` (or a binary 836patch, if binary patches are enabled) instead of a regular diff. 837 838However, one may also want to specify other diff driver attributes. For 839example, you might want to use `textconv` to convert postscript files to 840an ASCII representation for human viewing, but otherwise treat them as 841binary files. You cannot specify both `-diff` and `diff=ps` attributes. 842The solution is to use the `diff.*.binary` config option: 843 844------------------------ 845[diff "ps"] 846 textconv = ps2ascii 847 binary = true 848------------------------ 849 850Performing a three-way merge 851~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 852 853`merge` 854^^^^^^^ 855 856The attribute `merge` affects how three versions of a file are 857merged when a file-level merge is necessary during `git merge`, 858and other commands such as `git revert` and `git cherry-pick`. 859 860Set:: 861 862 Built-in 3-way merge driver is used to merge the 863 contents in a way similar to 'merge' command of `RCS` 864 suite. This is suitable for ordinary text files. 865 866Unset:: 867 868 Take the version from the current branch as the 869 tentative merge result, and declare that the merge has 870 conflicts. This is suitable for binary files that do 871 not have a well-defined merge semantics. 872 873Unspecified:: 874 875 By default, this uses the same built-in 3-way merge 876 driver as is the case when the `merge` attribute is set. 877 However, the `merge.default` configuration variable can name 878 different merge driver to be used with paths for which the 879 `merge` attribute is unspecified. 880 881String:: 882 883 3-way merge is performed using the specified custom 884 merge driver. The built-in 3-way merge driver can be 885 explicitly specified by asking for "text" driver; the 886 built-in "take the current branch" driver can be 887 requested with "binary". 888 889 890Built-in merge drivers 891^^^^^^^^^^^^^^^^^^^^^^ 892 893There are a few built-in low-level merge drivers defined that 894can be asked for via the `merge` attribute. 895 896text:: 897 898 Usual 3-way file level merge for text files. Conflicted 899 regions are marked with conflict markers `<<<<<<<`, 900 `=======` and `>>>>>>>`. The version from your branch 901 appears before the `=======` marker, and the version 902 from the merged branch appears after the `=======` 903 marker. 904 905binary:: 906 907 Keep the version from your branch in the work tree, but 908 leave the path in the conflicted state for the user to 909 sort out. 910 911union:: 912 913 Run 3-way file level merge for text files, but take 914 lines from both versions, instead of leaving conflict 915 markers. This tends to leave the added lines in the 916 resulting file in random order and the user should 917 verify the result. Do not use this if you do not 918 understand the implications. 919 920 921Defining a custom merge driver 922^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 923 924The definition of a merge driver is done in the `.git/config` 925file, not in the `gitattributes` file, so strictly speaking this 926manual page is a wrong place to talk about it. However... 927 928To define a custom merge driver `filfre`, add a section to your 929`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: 930 931---------------------------------------------------------------- 932[merge "filfre"] 933 name = feel-free merge driver 934 driver = filfre %O %A %B %L %P 935 recursive = binary 936---------------------------------------------------------------- 937 938The `merge.*.name` variable gives the driver a human-readable 939name. 940 941The `merge.*.driver` variable's value is used to construct a 942command to run to merge ancestor's version (`%O`), current 943version (`%A`) and the other branches' version (`%B`). These 944three tokens are replaced with the names of temporary files that 945hold the contents of these versions when the command line is 946built. Additionally, %L will be replaced with the conflict marker 947size (see below). 948 949The merge driver is expected to leave the result of the merge in 950the file named with `%A` by overwriting it, and exit with zero 951status if it managed to merge them cleanly, or non-zero if there 952were conflicts. 953 954The `merge.*.recursive` variable specifies what other merge 955driver to use when the merge driver is called for an internal 956merge between common ancestors, when there are more than one. 957When left unspecified, the driver itself is used for both 958internal merge and the final merge. 959 960The merge driver can learn the pathname in which the merged result 961will be stored via placeholder `%P`. 962 963 964`conflict-marker-size` 965^^^^^^^^^^^^^^^^^^^^^^ 966 967This attribute controls the length of conflict markers left in 968the work tree file during a conflicted merge. Only setting to 969the value to a positive integer has any meaningful effect. 970 971For example, this line in `.gitattributes` can be used to tell the merge 972machinery to leave much longer (instead of the usual 7-character-long) 973conflict markers when merging the file `Documentation/git-merge.txt` 974results in a conflict. 975 976------------------------ 977Documentation/git-merge.txt conflict-marker-size=32 978------------------------ 979 980 981Checking whitespace errors 982~~~~~~~~~~~~~~~~~~~~~~~~~~ 983 984`whitespace` 985^^^^^^^^^^^^ 986 987The `core.whitespace` configuration variable allows you to define what 988'diff' and 'apply' should consider whitespace errors for all paths in 989the project (See linkgit:git-config[1]). This attribute gives you finer 990control per path. 991 992Set:: 993 994 Notice all types of potential whitespace errors known to Git. 995 The tab width is taken from the value of the `core.whitespace` 996 configuration variable. 997 998Unset:: 9991000 Do not notice anything as error.10011002Unspecified::10031004 Use the value of the `core.whitespace` configuration variable to1005 decide what to notice as error.10061007String::10081009 Specify a comma separate list of common whitespace problems to1010 notice in the same format as the `core.whitespace` configuration1011 variable.101210131014Creating an archive1015~~~~~~~~~~~~~~~~~~~10161017`export-ignore`1018^^^^^^^^^^^^^^^10191020Files and directories with the attribute `export-ignore` won't be added to1021archive files.10221023`export-subst`1024^^^^^^^^^^^^^^10251026If the attribute `export-subst` is set for a file then Git will expand1027several placeholders when adding this file to an archive. The1028expansion depends on the availability of a commit ID, i.e., if1029linkgit:git-archive[1] has been given a tree instead of a commit or a1030tag then no replacement will be done. The placeholders are the same1031as those for the option `--pretty=format:` of linkgit:git-log[1],1032except that they need to be wrapped like this: `$Format:PLACEHOLDERS$`1033in the file. E.g. the string `$Format:%H$` will be replaced by the1034commit hash.103510361037Packing objects1038~~~~~~~~~~~~~~~10391040`delta`1041^^^^^^^10421043Delta compression will not be attempted for blobs for paths with the1044attribute `delta` set to false.104510461047Viewing files in GUI tools1048~~~~~~~~~~~~~~~~~~~~~~~~~~10491050`encoding`1051^^^^^^^^^^10521053The value of this attribute specifies the character encoding that should1054be used by GUI tools (e.g. linkgit:gitk[1] and linkgit:git-gui[1]) to1055display the contents of the relevant file. Note that due to performance1056considerations linkgit:gitk[1] does not use this attribute unless you1057manually enable per-file encodings in its options.10581059If this attribute is not set or has an invalid value, the value of the1060`gui.encoding` configuration variable is used instead1061(See linkgit:git-config[1]).106210631064USING MACRO ATTRIBUTES1065----------------------10661067You do not want any end-of-line conversions applied to, nor textual diffs1068produced for, any binary file you track. You would need to specify e.g.10691070------------1071*.jpg -text -diff1072------------10731074but that may become cumbersome, when you have many attributes. Using1075macro attributes, you can define an attribute that, when set, also1076sets or unsets a number of other attributes at the same time. The1077system knows a built-in macro attribute, `binary`:10781079------------1080*.jpg binary1081------------10821083Setting the "binary" attribute also unsets the "text" and "diff"1084attributes as above. Note that macro attributes can only be "Set",1085though setting one might have the effect of setting or unsetting other1086attributes or even returning other attributes to the "Unspecified"1087state.108810891090DEFINING MACRO ATTRIBUTES1091-------------------------10921093Custom macro attributes can be defined only in top-level gitattributes1094files (`$GIT_DIR/info/attributes`, the `.gitattributes` file at the1095top level of the working tree, or the global or system-wide1096gitattributes files), not in `.gitattributes` files in working tree1097subdirectories. The built-in macro attribute "binary" is equivalent1098to:10991100------------1101[attr]binary -diff -merge -text1102------------110311041105EXAMPLE1106-------11071108If you have these three `gitattributes` file:11091110----------------------------------------------------------------1111(in $GIT_DIR/info/attributes)11121113a* foo !bar -baz11141115(in .gitattributes)1116abc foo bar baz11171118(in t/.gitattributes)1119ab* merge=filfre1120abc -foo -bar1121*.c frotz1122----------------------------------------------------------------11231124the attributes given to path `t/abc` are computed as follows:112511261. By examining `t/.gitattributes` (which is in the same1127 directory as the path in question), Git finds that the first1128 line matches. `merge` attribute is set. It also finds that1129 the second line matches, and attributes `foo` and `bar`1130 are unset.113111322. Then it examines `.gitattributes` (which is in the parent1133 directory), and finds that the first line matches, but1134 `t/.gitattributes` file already decided how `merge`, `foo`1135 and `bar` attributes should be given to this path, so it1136 leaves `foo` and `bar` unset. Attribute `baz` is set.113711383. Finally it examines `$GIT_DIR/info/attributes`. This file1139 is used to override the in-tree settings. The first line is1140 a match, and `foo` is set, `bar` is reverted to unspecified1141 state, and `baz` is unset.11421143As the result, the attributes assignment to `t/abc` becomes:11441145----------------------------------------------------------------1146foo set to true1147bar unspecified1148baz set to false1149merge set to string value "filfre"1150frotz unspecified1151----------------------------------------------------------------115211531154SEE ALSO1155--------1156linkgit:git-check-attr[1].11571158GIT1159---1160Part of the linkgit:git[1] suite