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