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