6 gitattributes - defining attributes per path
10 $GIT_DIR/info/attributes, .gitattributes
16 A `gitattributes` file is a simple text file that gives
17 `attributes` to pathnames.
19 Each line in `gitattributes` file is of form:
21 pattern attr1 attr2 ...
23 That is, a pattern followed by an attributes list,
24 separated by whitespaces. Leading and trailing whitespaces are
25 ignored. Lines that begin with '#' are ignored. Patterns
26 that begin with a double quote are quoted in C style.
27 When the pattern matches the path in question, the attributes
28 listed on the line are given to the path.
30 Each attribute can be in one of these states for a given path:
34 The path has the attribute with special value "true";
35 this is specified by listing only the name of the
36 attribute in the attribute list.
40 The path has the attribute with special value "false";
41 this is specified by listing the name of the attribute
42 prefixed with a dash `-` in the attribute list.
46 The path has the attribute with specified string value;
47 this is specified by listing the name of the attribute
48 followed by an equal sign `=` and its value in the
53 No pattern matches the path, and nothing says if
54 the path has or does not have the attribute, the
55 attribute for the path is said to be Unspecified.
57 When more than one pattern matches the path, a later line
58 overrides an earlier line. This overriding is done per
61 The rules by which the pattern matches paths are the same as in
62 `.gitignore` files (see linkgit:gitignore[5]), with a few exceptions:
64 - negative patterns are forbidden
66 - patterns that match a directory do not recursively match paths
67 inside that directory (so using the trailing-slash `path/` syntax is
68 pointless in an attributes file; use `path/**` instead)
70 When deciding what attributes are assigned to a path, Git
71 consults `$GIT_DIR/info/attributes` file (which has the highest
72 precedence), `.gitattributes` file in the same directory as the
73 path in question, and its parent directories up to the toplevel of the
74 work tree (the further the directory that contains `.gitattributes`
75 is from the path in question, the lower its precedence). Finally
76 global and system-wide files are considered (they have the lowest
79 When the `.gitattributes` file is missing from the work tree, the
80 path in the index is used as a fall-back. During checkout process,
81 `.gitattributes` in the index is used and then the file in the
82 working tree is used as a fall-back.
84 If you wish to affect only a single repository (i.e., to assign
85 attributes to files that are particular to
86 one user's workflow for that repository), then
87 attributes should be placed in the `$GIT_DIR/info/attributes` file.
88 Attributes which should be version-controlled and distributed to other
89 repositories (i.e., attributes of interest to all users) should go into
90 `.gitattributes` files. Attributes that should affect all repositories
91 for a single user should be placed in a file specified by the
92 `core.attributesFile` configuration option (see linkgit:git-config[1]).
93 Its default value is $XDG_CONFIG_HOME/git/attributes. If $XDG_CONFIG_HOME
94 is either not set or empty, $HOME/.config/git/attributes is used instead.
95 Attributes for all users on a system should be placed in the
96 `$(prefix)/etc/gitattributes` file.
98 Sometimes you would need to override a setting of an attribute
99 for a path to `Unspecified` state. This can be done by listing
100 the name of the attribute prefixed with an exclamation point `!`.
106 Certain operations by Git can be influenced by assigning
107 particular attributes to a path. Currently, the following
108 operations are attributes-aware.
110 Checking-out and checking-in
111 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
113 These attributes affect how the contents stored in the
114 repository are copied to the working tree files when commands
115 such as 'git checkout' and 'git merge' run. They also affect how
116 Git stores the contents you prepare in the working tree in the
117 repository upon 'git add' and 'git commit'.
122 This attribute enables and controls end-of-line normalization. When a
123 text file is normalized, its line endings are converted to LF in the
124 repository. To control what line ending style is used in the working
125 directory, use the `eol` attribute for a single file and the
126 `core.eol` configuration variable for all text files.
127 Note that `core.autocrlf` overrides `core.eol`
131 Setting the `text` attribute on a path enables end-of-line
132 normalization and marks the path as a text file. End-of-line
133 conversion takes place without guessing the content type.
137 Unsetting the `text` attribute on a path tells Git not to
138 attempt any end-of-line conversion upon checkin or checkout.
140 Set to string value "auto"::
142 When `text` is set to "auto", the path is marked for automatic
143 end-of-line conversion. If Git decides that the content is
144 text, its line endings are converted to LF on checkin.
145 When the file has been committed with CRLF, no conversion is done.
149 If the `text` attribute is unspecified, Git uses the
150 `core.autocrlf` configuration variable to determine if the
151 file should be converted.
153 Any other value causes Git to act as if `text` has been left
159 This attribute sets a specific line-ending style to be used in the
160 working directory. It enables end-of-line conversion without any
161 content checks, effectively setting the `text` attribute. Note that
162 setting this attribute on paths which are in the index with CRLF line
163 endings may make the paths to be considered dirty. Adding the path to
164 the index again will normalize the line endings in the index.
166 Set to string value "crlf"::
168 This setting forces Git to normalize line endings for this
169 file on checkin and convert them to CRLF when the file is
172 Set to string value "lf"::
174 This setting forces Git to normalize line endings to LF on
175 checkin and prevents conversion to CRLF when the file is
178 Backwards compatibility with `crlf` attribute
179 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
181 For backwards compatibility, the `crlf` attribute is interpreted as
184 ------------------------
188 ------------------------
190 End-of-line conversion
191 ^^^^^^^^^^^^^^^^^^^^^^
193 While Git normally leaves file contents alone, it can be configured to
194 normalize line endings to LF in the repository and, optionally, to
195 convert them to CRLF when files are checked out.
197 If you simply want to have CRLF line endings in your working directory
198 regardless of the repository you are working with, you can set the
199 config variable "core.autocrlf" without using any attributes.
201 ------------------------
204 ------------------------
206 This does not force normalization of text files, but does ensure
207 that text files that you introduce to the repository have their line
208 endings normalized to LF when they are added, and that files that are
209 already normalized in the repository stay normalized.
211 If you want to ensure that text files that any contributor introduces to
212 the repository have their line endings normalized, you can set the
213 `text` attribute to "auto" for _all_ files.
215 ------------------------
217 ------------------------
219 The attributes allow a fine-grained control, how the line endings
221 Here is an example that will make Git normalize .txt, .vcproj and .sh
222 files, ensure that .vcproj files have CRLF and .sh files have LF in
223 the working directory, and prevent .jpg files from being normalized
224 regardless of their content.
226 ------------------------
229 *.vcproj text eol=crlf
232 ------------------------
234 NOTE: When `text=auto` conversion is enabled in a cross-platform
235 project using push and pull to a central repository the text files
236 containing CRLFs should be normalized.
238 From a clean working directory:
240 -------------------------------------------------
241 $ echo "* text=auto" >.gitattributes
242 $ git add --renormalize .
243 $ git status # Show files that will be normalized
244 $ git commit -m "Introduce end-of-line normalization"
245 -------------------------------------------------
247 If any files that should not be normalized show up in 'git status',
248 unset their `text` attribute before running 'git add -u'.
250 ------------------------
252 ------------------------
254 Conversely, text files that Git does not detect can have normalization
257 ------------------------
259 ------------------------
261 If `core.safecrlf` is set to "true" or "warn", Git verifies if
262 the conversion is reversible for the current setting of
263 `core.autocrlf`. For "true", Git rejects irreversible
264 conversions; for "warn", Git only prints a warning but accepts
265 an irreversible conversion. The safety triggers to prevent such
266 a conversion done to the files in the work tree, but there are a
267 few exceptions. Even though...
269 - 'git add' itself does not touch the files in the work tree, the
270 next checkout would, so the safety triggers;
272 - 'git apply' to update a text file with a patch does touch the files
273 in the work tree, but the operation is about text files and CRLF
274 conversion is about fixing the line ending inconsistencies, so the
275 safety does not trigger;
277 - 'git diff' itself does not touch the files in the work tree, it is
278 often run to inspect the changes you intend to next 'git add'. To
279 catch potential problems early, safety triggers.
285 When the attribute `ident` is set for a path, Git replaces
286 `$Id$` in the blob object with `$Id:`, followed by the
287 40-character hexadecimal blob object name, followed by a dollar
288 sign `$` upon checkout. Any byte sequence that begins with
289 `$Id:` and ends with `$` in the worktree file is replaced
290 with `$Id$` upon check-in.
296 A `filter` attribute can be set to a string value that names a
297 filter driver specified in the configuration.
299 A filter driver consists of a `clean` command and a `smudge`
300 command, either of which can be left unspecified. Upon
301 checkout, when the `smudge` command is specified, the command is
302 fed the blob object from its standard input, and its standard
303 output is used to update the worktree file. Similarly, the
304 `clean` command is used to convert the contents of worktree file
305 upon checkin. By default these commands process only a single
306 blob and terminate. If a long running `process` filter is used
307 in place of `clean` and/or `smudge` filters, then Git can process
308 all blobs with a single filter command invocation for the entire
309 life of a single Git command, for example `git add --all`. If a
310 long running `process` filter is configured then it always takes
311 precedence over a configured single blob filter. See section
312 below for the description of the protocol used to communicate with
315 One use of the content filtering is to massage the content into a shape
316 that is more convenient for the platform, filesystem, and the user to use.
317 For this mode of operation, the key phrase here is "more convenient" and
318 not "turning something unusable into usable". In other words, the intent
319 is that if someone unsets the filter driver definition, or does not have
320 the appropriate filter program, the project should still be usable.
322 Another use of the content filtering is to store the content that cannot
323 be directly used in the repository (e.g. a UUID that refers to the true
324 content stored outside Git, or an encrypted content) and turn it into a
325 usable form upon checkout (e.g. download the external content, or decrypt
326 the encrypted content).
328 These two filters behave differently, and by default, a filter is taken as
329 the former, massaging the contents into more convenient shape. A missing
330 filter driver definition in the config, or a filter driver that exits with
331 a non-zero status, is not an error but makes the filter a no-op passthru.
333 You can declare that a filter turns a content that by itself is unusable
334 into a usable content by setting the filter.<driver>.required configuration
337 Note: Whenever the clean filter is changed, the repo should be renormalized:
338 $ git add --renormalize .
340 For example, in .gitattributes, you would assign the `filter`
343 ------------------------
345 ------------------------
347 Then you would define a "filter.indent.clean" and "filter.indent.smudge"
348 configuration in your .git/config to specify a pair of commands to
349 modify the contents of C programs when the source files are checked
350 in ("clean" is run) and checked out (no change is made because the
353 ------------------------
357 ------------------------
359 For best results, `clean` should not alter its output further if it is
360 run twice ("clean->clean" should be equivalent to "clean"), and
361 multiple `smudge` commands should not alter `clean`'s output
362 ("smudge->smudge->clean" should be equivalent to "clean"). See the
363 section on merging below.
365 The "indent" filter is well-behaved in this regard: it will not modify
366 input that is already correctly indented. In this case, the lack of a
367 smudge filter means that the clean filter _must_ accept its own output
368 without modifying it.
370 If a filter _must_ succeed in order to make the stored contents usable,
371 you can declare that the filter is `required`, in the configuration:
373 ------------------------
375 clean = openssl enc ...
376 smudge = openssl enc -d ...
378 ------------------------
380 Sequence "%f" on the filter command line is replaced with the name of
381 the file the filter is working on. A filter might use this in keyword
382 substitution. For example:
384 ------------------------
386 clean = git-p4-filter --clean %f
387 smudge = git-p4-filter --smudge %f
388 ------------------------
390 Note that "%f" is the name of the path that is being worked on. Depending
391 on the version that is being filtered, the corresponding file on disk may
392 not exist, or may have different contents. So, smudge and clean commands
393 should not try to access the file on disk, but only act as filters on the
394 content provided to them on standard input.
396 Long Running Filter Process
397 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
399 If the filter command (a string value) is defined via
400 `filter.<driver>.process` then Git can process all blobs with a
401 single filter invocation for the entire life of a single Git
402 command. This is achieved by using the long-running process protocol
403 (described in technical/long-running-process-protocol.txt).
405 When Git encounters the first file that needs to be cleaned or smudged,
406 it starts the filter and performs the handshake. In the handshake, the
407 welcome message sent by Git is "git-filter-client", only version 2 is
408 suppported, and the supported capabilities are "clean", "smudge", and
411 Afterwards Git sends a list of "key=value" pairs terminated with
412 a flush packet. The list will contain at least the filter command
413 (based on the supported capabilities) and the pathname of the file
414 to filter relative to the repository root. Right after the flush packet
415 Git sends the content split in zero or more pkt-line packets and a
416 flush packet to terminate content. Please note, that the filter
417 must not send any response before it received the content and the
418 final flush packet. Also note that the "value" of a "key=value" pair
419 can contain the "=" character whereas the key would never contain
421 ------------------------
422 packet: git> command=smudge
423 packet: git> pathname=path/testfile.dat
427 ------------------------
429 The filter is expected to respond with a list of "key=value" pairs
430 terminated with a flush packet. If the filter does not experience
431 problems then the list must contain a "success" status. Right after
432 these packets the filter is expected to send the content in zero
433 or more pkt-line packets and a flush packet at the end. Finally, a
434 second list of "key=value" pairs terminated with a flush packet
435 is expected. The filter can change the status in the second list
436 or keep the status as is with an empty list. Please note that the
437 empty list must be terminated with a flush packet regardless.
439 ------------------------
440 packet: git< status=success
442 packet: git< SMUDGED_CONTENT
444 packet: git< 0000 # empty list, keep "status=success" unchanged!
445 ------------------------
447 If the result content is empty then the filter is expected to respond
448 with a "success" status and a flush packet to signal the empty content.
449 ------------------------
450 packet: git< status=success
452 packet: git< 0000 # empty content!
453 packet: git< 0000 # empty list, keep "status=success" unchanged!
454 ------------------------
456 In case the filter cannot or does not want to process the content,
457 it is expected to respond with an "error" status.
458 ------------------------
459 packet: git< status=error
461 ------------------------
463 If the filter experiences an error during processing, then it can
464 send the status "error" after the content was (partially or
466 ------------------------
467 packet: git< status=success
469 packet: git< HALF_WRITTEN_ERRONEOUS_CONTENT
471 packet: git< status=error
473 ------------------------
475 In case the filter cannot or does not want to process the content
476 as well as any future content for the lifetime of the Git process,
477 then it is expected to respond with an "abort" status at any point
479 ------------------------
480 packet: git< status=abort
482 ------------------------
484 Git neither stops nor restarts the filter process in case the
485 "error"/"abort" status is set. However, Git sets its exit code
486 according to the `filter.<driver>.required` flag, mimicking the
487 behavior of the `filter.<driver>.clean` / `filter.<driver>.smudge`
490 If the filter dies during the communication or does not adhere to
491 the protocol then Git will stop the filter process and restart it
492 with the next file that needs to be processed. Depending on the
493 `filter.<driver>.required` flag Git will interpret that as error.
498 If the filter supports the "delay" capability, then Git can send the
499 flag "can-delay" after the filter command and pathname. This flag
500 denotes that the filter can delay filtering the current blob (e.g. to
501 compensate network latencies) by responding with no content but with
502 the status "delayed" and a flush packet.
503 ------------------------
504 packet: git> command=smudge
505 packet: git> pathname=path/testfile.dat
506 packet: git> can-delay=1
510 packet: git< status=delayed
512 ------------------------
514 If the filter supports the "delay" capability then it must support the
515 "list_available_blobs" command. If Git sends this command, then the
516 filter is expected to return a list of pathnames representing blobs
517 that have been delayed earlier and are now available.
518 The list must be terminated with a flush packet followed
519 by a "success" status that is also terminated with a flush packet. If
520 no blobs for the delayed paths are available, yet, then the filter is
521 expected to block the response until at least one blob becomes
522 available. The filter can tell Git that it has no more delayed blobs
523 by sending an empty list. As soon as the filter responds with an empty
524 list, Git stops asking. All blobs that Git has not received at this
525 point are considered missing and will result in an error.
527 ------------------------
528 packet: git> command=list_available_blobs
530 packet: git< pathname=path/testfile.dat
531 packet: git< pathname=path/otherfile.dat
533 packet: git< status=success
535 ------------------------
537 After Git received the pathnames, it will request the corresponding
538 blobs again. These requests contain a pathname and an empty content
539 section. The filter is expected to respond with the smudged content
540 in the usual way as explained above.
541 ------------------------
542 packet: git> command=smudge
543 packet: git> pathname=path/testfile.dat
545 packet: git> 0000 # empty content!
546 packet: git< status=success
548 packet: git< SMUDGED_CONTENT
550 packet: git< 0000 # empty list, keep "status=success" unchanged!
551 ------------------------
556 A long running filter demo implementation can be found in
557 `contrib/long-running-filter/example.pl` located in the Git
558 core repository. If you develop your own long running filter
559 process then the `GIT_TRACE_PACKET` environment variables can be
560 very helpful for debugging (see linkgit:git[1]).
562 Please note that you cannot use an existing `filter.<driver>.clean`
563 or `filter.<driver>.smudge` command with `filter.<driver>.process`
564 because the former two use a different inter process communication
565 protocol than the latter one.
568 Interaction between checkin/checkout attributes
569 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
571 In the check-in codepath, the worktree file is first converted
572 with `filter` driver (if specified and corresponding driver
573 defined), then the result is processed with `ident` (if
574 specified), and then finally with `text` (again, if specified
577 In the check-out codepath, the blob content is first converted
578 with `text`, and then `ident` and fed to `filter`.
581 Merging branches with differing checkin/checkout attributes
582 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
584 If you have added attributes to a file that cause the canonical
585 repository format for that file to change, such as adding a
586 clean/smudge filter or text/eol/ident attributes, merging anything
587 where the attribute is not in place would normally cause merge
590 To prevent these unnecessary merge conflicts, Git can be told to run a
591 virtual check-out and check-in of all three stages of a file when
592 resolving a three-way merge by setting the `merge.renormalize`
593 configuration variable. This prevents changes caused by check-in
594 conversion from causing spurious merge conflicts when a converted file
595 is merged with an unconverted file.
597 As long as a "smudge->clean" results in the same output as a "clean"
598 even on files that are already smudged, this strategy will
599 automatically resolve all filter-related conflicts. Filters that do
600 not act in this way may cause additional merge conflicts that must be
610 The attribute `diff` affects how Git generates diffs for particular
611 files. It can tell Git whether to generate a textual patch for the path
612 or to treat the path as a binary file. It can also affect what line is
613 shown on the hunk header `@@ -k,l +n,m @@` line, tell Git to use an
614 external command to generate the diff, or ask Git to convert binary
615 files to a text format before generating the diff.
619 A path to which the `diff` attribute is set is treated
620 as text, even when they contain byte values that
621 normally never appear in text files, such as NUL.
625 A path to which the `diff` attribute is unset will
626 generate `Binary files differ` (or a binary patch, if
627 binary patches are enabled).
631 A path to which the `diff` attribute is unspecified
632 first gets its contents inspected, and if it looks like
633 text and is smaller than core.bigFileThreshold, it is treated
634 as text. Otherwise it would generate `Binary files differ`.
638 Diff is shown using the specified diff driver. Each driver may
639 specify one or more options, as described in the following
640 section. The options for the diff driver "foo" are defined
641 by the configuration variables in the "diff.foo" section of the
645 Defining an external diff driver
646 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
648 The definition of a diff driver is done in `gitconfig`, not
649 `gitattributes` file, so strictly speaking this manual page is a
650 wrong place to talk about it. However...
652 To define an external diff driver `jcdiff`, add a section to your
653 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
655 ----------------------------------------------------------------
658 ----------------------------------------------------------------
660 When Git needs to show you a diff for the path with `diff`
661 attribute set to `jcdiff`, it calls the command you specified
662 with the above configuration, i.e. `j-c-diff`, with 7
663 parameters, just like `GIT_EXTERNAL_DIFF` program is called.
664 See linkgit:git[1] for details.
667 Defining a custom hunk-header
668 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
670 Each group of changes (called a "hunk") in the textual diff output
671 is prefixed with a line of the form:
675 This is called a 'hunk header'. The "TEXT" portion is by default a line
676 that begins with an alphabet, an underscore or a dollar sign; this
677 matches what GNU 'diff -p' output uses. This default selection however
678 is not suited for some contents, and you can use a customized pattern
681 First, in .gitattributes, you would assign the `diff` attribute
684 ------------------------
686 ------------------------
688 Then, you would define a "diff.tex.xfuncname" configuration to
689 specify a regular expression that matches a line that you would
690 want to appear as the hunk header "TEXT". Add a section to your
691 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
693 ------------------------
695 xfuncname = "^(\\\\(sub)*section\\{.*)$"
696 ------------------------
698 Note. A single level of backslashes are eaten by the
699 configuration file parser, so you would need to double the
700 backslashes; the pattern above picks a line that begins with a
701 backslash, and zero or more occurrences of `sub` followed by
702 `section` followed by open brace, to the end of line.
704 There are a few built-in patterns to make this easier, and `tex`
705 is one of them, so you do not have to write the above in your
706 configuration file (you still need to enable this with the
707 attribute mechanism, via `.gitattributes`). The following built in
708 patterns are available:
710 - `ada` suitable for source code in the Ada language.
712 - `bibtex` suitable for files with BibTeX coded references.
714 - `cpp` suitable for source code in the C and C++ languages.
716 - `csharp` suitable for source code in the C# language.
718 - `css` suitable for cascading style sheets.
720 - `fortran` suitable for source code in the Fortran language.
722 - `fountain` suitable for Fountain documents.
724 - `golang` suitable for source code in the Go language.
726 - `html` suitable for HTML/XHTML documents.
728 - `java` suitable for source code in the Java language.
730 - `matlab` suitable for source code in the MATLAB language.
732 - `objc` suitable for source code in the Objective-C language.
734 - `pascal` suitable for source code in the Pascal/Delphi language.
736 - `perl` suitable for source code in the Perl language.
738 - `php` suitable for source code in the PHP language.
740 - `python` suitable for source code in the Python language.
742 - `ruby` suitable for source code in the Ruby language.
744 - `tex` suitable for source code for LaTeX documents.
747 Customizing word diff
748 ^^^^^^^^^^^^^^^^^^^^^
750 You can customize the rules that `git diff --word-diff` uses to
751 split words in a line, by specifying an appropriate regular expression
752 in the "diff.*.wordRegex" configuration variable. For example, in TeX
753 a backslash followed by a sequence of letters forms a command, but
754 several such commands can be run together without intervening
755 whitespace. To separate them, use a regular expression in your
756 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
758 ------------------------
760 wordRegex = "\\\\[a-zA-Z]+|[{}]|\\\\.|[^\\{}[:space:]]+"
761 ------------------------
763 A built-in pattern is provided for all languages listed in the
767 Performing text diffs of binary files
768 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
770 Sometimes it is desirable to see the diff of a text-converted
771 version of some binary files. For example, a word processor
772 document can be converted to an ASCII text representation, and
773 the diff of the text shown. Even though this conversion loses
774 some information, the resulting diff is useful for human
775 viewing (but cannot be applied directly).
777 The `textconv` config option is used to define a program for
778 performing such a conversion. The program should take a single
779 argument, the name of a file to convert, and produce the
780 resulting text on stdout.
782 For example, to show the diff of the exif information of a
783 file instead of the binary information (assuming you have the
784 exif tool installed), add the following section to your
785 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file):
787 ------------------------
790 ------------------------
792 NOTE: The text conversion is generally a one-way conversion;
793 in this example, we lose the actual image contents and focus
794 just on the text data. This means that diffs generated by
795 textconv are _not_ suitable for applying. For this reason,
796 only `git diff` and the `git log` family of commands (i.e.,
797 log, whatchanged, show) will perform text conversion. `git
798 format-patch` will never generate this output. If you want to
799 send somebody a text-converted diff of a binary file (e.g.,
800 because it quickly conveys the changes you have made), you
801 should generate it separately and send it as a comment _in
802 addition to_ the usual binary diff that you might send.
804 Because text conversion can be slow, especially when doing a
805 large number of them with `git log -p`, Git provides a mechanism
806 to cache the output and use it in future diffs. To enable
807 caching, set the "cachetextconv" variable in your diff driver's
810 ------------------------
814 ------------------------
816 This will cache the result of running "exif" on each blob
817 indefinitely. If you change the textconv config variable for a
818 diff driver, Git will automatically invalidate the cache entries
819 and re-run the textconv filter. If you want to invalidate the
820 cache manually (e.g., because your version of "exif" was updated
821 and now produces better output), you can remove the cache
822 manually with `git update-ref -d refs/notes/textconv/jpg` (where
823 "jpg" is the name of the diff driver, as in the example above).
825 Choosing textconv versus external diff
826 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
828 If you want to show differences between binary or specially-formatted
829 blobs in your repository, you can choose to use either an external diff
830 command, or to use textconv to convert them to a diff-able text format.
831 Which method you choose depends on your exact situation.
833 The advantage of using an external diff command is flexibility. You are
834 not bound to find line-oriented changes, nor is it necessary for the
835 output to resemble unified diff. You are free to locate and report
836 changes in the most appropriate way for your data format.
838 A textconv, by comparison, is much more limiting. You provide a
839 transformation of the data into a line-oriented text format, and Git
840 uses its regular diff tools to generate the output. There are several
841 advantages to choosing this method:
843 1. Ease of use. It is often much simpler to write a binary to text
844 transformation than it is to perform your own diff. In many cases,
845 existing programs can be used as textconv filters (e.g., exif,
848 2. Git diff features. By performing only the transformation step
849 yourself, you can still utilize many of Git's diff features,
850 including colorization, word-diff, and combined diffs for merges.
852 3. Caching. Textconv caching can speed up repeated diffs, such as those
853 you might trigger by running `git log -p`.
856 Marking files as binary
857 ^^^^^^^^^^^^^^^^^^^^^^^
859 Git usually guesses correctly whether a blob contains text or binary
860 data by examining the beginning of the contents. However, sometimes you
861 may want to override its decision, either because a blob contains binary
862 data later in the file, or because the content, while technically
863 composed of text characters, is opaque to a human reader. For example,
864 many postscript files contain only ASCII characters, but produce noisy
865 and meaningless diffs.
867 The simplest way to mark a file as binary is to unset the diff
868 attribute in the `.gitattributes` file:
870 ------------------------
872 ------------------------
874 This will cause Git to generate `Binary files differ` (or a binary
875 patch, if binary patches are enabled) instead of a regular diff.
877 However, one may also want to specify other diff driver attributes. For
878 example, you might want to use `textconv` to convert postscript files to
879 an ASCII representation for human viewing, but otherwise treat them as
880 binary files. You cannot specify both `-diff` and `diff=ps` attributes.
881 The solution is to use the `diff.*.binary` config option:
883 ------------------------
887 ------------------------
889 Performing a three-way merge
890 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
895 The attribute `merge` affects how three versions of a file are
896 merged when a file-level merge is necessary during `git merge`,
897 and other commands such as `git revert` and `git cherry-pick`.
901 Built-in 3-way merge driver is used to merge the
902 contents in a way similar to 'merge' command of `RCS`
903 suite. This is suitable for ordinary text files.
907 Take the version from the current branch as the
908 tentative merge result, and declare that the merge has
909 conflicts. This is suitable for binary files that do
910 not have a well-defined merge semantics.
914 By default, this uses the same built-in 3-way merge
915 driver as is the case when the `merge` attribute is set.
916 However, the `merge.default` configuration variable can name
917 different merge driver to be used with paths for which the
918 `merge` attribute is unspecified.
922 3-way merge is performed using the specified custom
923 merge driver. The built-in 3-way merge driver can be
924 explicitly specified by asking for "text" driver; the
925 built-in "take the current branch" driver can be
926 requested with "binary".
929 Built-in merge drivers
930 ^^^^^^^^^^^^^^^^^^^^^^
932 There are a few built-in low-level merge drivers defined that
933 can be asked for via the `merge` attribute.
937 Usual 3-way file level merge for text files. Conflicted
938 regions are marked with conflict markers `<<<<<<<`,
939 `=======` and `>>>>>>>`. The version from your branch
940 appears before the `=======` marker, and the version
941 from the merged branch appears after the `=======`
946 Keep the version from your branch in the work tree, but
947 leave the path in the conflicted state for the user to
952 Run 3-way file level merge for text files, but take
953 lines from both versions, instead of leaving conflict
954 markers. This tends to leave the added lines in the
955 resulting file in random order and the user should
956 verify the result. Do not use this if you do not
957 understand the implications.
960 Defining a custom merge driver
961 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
963 The definition of a merge driver is done in the `.git/config`
964 file, not in the `gitattributes` file, so strictly speaking this
965 manual page is a wrong place to talk about it. However...
967 To define a custom merge driver `filfre`, add a section to your
968 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
970 ----------------------------------------------------------------
972 name = feel-free merge driver
973 driver = filfre %O %A %B %L %P
975 ----------------------------------------------------------------
977 The `merge.*.name` variable gives the driver a human-readable
980 The `merge.*.driver` variable's value is used to construct a
981 command to run to merge ancestor's version (`%O`), current
982 version (`%A`) and the other branches' version (`%B`). These
983 three tokens are replaced with the names of temporary files that
984 hold the contents of these versions when the command line is
985 built. Additionally, %L will be replaced with the conflict marker
988 The merge driver is expected to leave the result of the merge in
989 the file named with `%A` by overwriting it, and exit with zero
990 status if it managed to merge them cleanly, or non-zero if there
993 The `merge.*.recursive` variable specifies what other merge
994 driver to use when the merge driver is called for an internal
995 merge between common ancestors, when there are more than one.
996 When left unspecified, the driver itself is used for both
997 internal merge and the final merge.
999 The merge driver can learn the pathname in which the merged result
1000 will be stored via placeholder `%P`.
1003 `conflict-marker-size`
1004 ^^^^^^^^^^^^^^^^^^^^^^
1006 This attribute controls the length of conflict markers left in
1007 the work tree file during a conflicted merge. Only setting to
1008 the value to a positive integer has any meaningful effect.
1010 For example, this line in `.gitattributes` can be used to tell the merge
1011 machinery to leave much longer (instead of the usual 7-character-long)
1012 conflict markers when merging the file `Documentation/git-merge.txt`
1013 results in a conflict.
1015 ------------------------
1016 Documentation/git-merge.txt conflict-marker-size=32
1017 ------------------------
1020 Checking whitespace errors
1021 ~~~~~~~~~~~~~~~~~~~~~~~~~~
1026 The `core.whitespace` configuration variable allows you to define what
1027 'diff' and 'apply' should consider whitespace errors for all paths in
1028 the project (See linkgit:git-config[1]). This attribute gives you finer
1033 Notice all types of potential whitespace errors known to Git.
1034 The tab width is taken from the value of the `core.whitespace`
1035 configuration variable.
1039 Do not notice anything as error.
1043 Use the value of the `core.whitespace` configuration variable to
1044 decide what to notice as error.
1048 Specify a comma separate list of common whitespace problems to
1049 notice in the same format as the `core.whitespace` configuration
1059 Files and directories with the attribute `export-ignore` won't be added to
1065 If the attribute `export-subst` is set for a file then Git will expand
1066 several placeholders when adding this file to an archive. The
1067 expansion depends on the availability of a commit ID, i.e., if
1068 linkgit:git-archive[1] has been given a tree instead of a commit or a
1069 tag then no replacement will be done. The placeholders are the same
1070 as those for the option `--pretty=format:` of linkgit:git-log[1],
1071 except that they need to be wrapped like this: `$Format:PLACEHOLDERS$`
1072 in the file. E.g. the string `$Format:%H$` will be replaced by the
1082 Delta compression will not be attempted for blobs for paths with the
1083 attribute `delta` set to false.
1086 Viewing files in GUI tools
1087 ~~~~~~~~~~~~~~~~~~~~~~~~~~
1092 The value of this attribute specifies the character encoding that should
1093 be used by GUI tools (e.g. linkgit:gitk[1] and linkgit:git-gui[1]) to
1094 display the contents of the relevant file. Note that due to performance
1095 considerations linkgit:gitk[1] does not use this attribute unless you
1096 manually enable per-file encodings in its options.
1098 If this attribute is not set or has an invalid value, the value of the
1099 `gui.encoding` configuration variable is used instead
1100 (See linkgit:git-config[1]).
1103 USING MACRO ATTRIBUTES
1104 ----------------------
1106 You do not want any end-of-line conversions applied to, nor textual diffs
1107 produced for, any binary file you track. You would need to specify e.g.
1113 but that may become cumbersome, when you have many attributes. Using
1114 macro attributes, you can define an attribute that, when set, also
1115 sets or unsets a number of other attributes at the same time. The
1116 system knows a built-in macro attribute, `binary`:
1122 Setting the "binary" attribute also unsets the "text" and "diff"
1123 attributes as above. Note that macro attributes can only be "Set",
1124 though setting one might have the effect of setting or unsetting other
1125 attributes or even returning other attributes to the "Unspecified"
1129 DEFINING MACRO ATTRIBUTES
1130 -------------------------
1132 Custom macro attributes can be defined only in top-level gitattributes
1133 files (`$GIT_DIR/info/attributes`, the `.gitattributes` file at the
1134 top level of the working tree, or the global or system-wide
1135 gitattributes files), not in `.gitattributes` files in working tree
1136 subdirectories. The built-in macro attribute "binary" is equivalent
1140 [attr]binary -diff -merge -text
1147 If you have these three `gitattributes` file:
1149 ----------------------------------------------------------------
1150 (in $GIT_DIR/info/attributes)
1157 (in t/.gitattributes)
1161 ----------------------------------------------------------------
1163 the attributes given to path `t/abc` are computed as follows:
1165 1. By examining `t/.gitattributes` (which is in the same
1166 directory as the path in question), Git finds that the first
1167 line matches. `merge` attribute is set. It also finds that
1168 the second line matches, and attributes `foo` and `bar`
1171 2. Then it examines `.gitattributes` (which is in the parent
1172 directory), and finds that the first line matches, but
1173 `t/.gitattributes` file already decided how `merge`, `foo`
1174 and `bar` attributes should be given to this path, so it
1175 leaves `foo` and `bar` unset. Attribute `baz` is set.
1177 3. Finally it examines `$GIT_DIR/info/attributes`. This file
1178 is used to override the in-tree settings. The first line is
1179 a match, and `foo` is set, `bar` is reverted to unspecified
1180 state, and `baz` is unset.
1182 As the result, the attributes assignment to `t/abc` becomes:
1184 ----------------------------------------------------------------
1188 merge set to string value "filfre"
1190 ----------------------------------------------------------------
1195 linkgit:git-check-attr[1].
1199 Part of the linkgit:git[1] suite