Merge branch 'maint-1.6.1' into maint
[git/git.git] / Documentation / gitattributes.txt
1 gitattributes(5)
2 ================
3
4 NAME
5 ----
6 gitattributes - defining attributes per path
7
8 SYNOPSIS
9 --------
10 $GIT_DIR/info/attributes, .gitattributes
11
12
13 DESCRIPTION
14 -----------
15
16 A `gitattributes` file is a simple text file that gives
17 `attributes` to pathnames.
18
19 Each line in `gitattributes` file is of form:
20
21 pattern attr1 attr2 ...
22
23 That is, a pattern followed by an attributes list,
24 separated by whitespaces. When the pattern matches the
25 path in question, the attributes listed on the line are given to
26 the path.
27
28 Each attribute can be in one of these states for a given path:
29
30 Set::
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
36 Unset::
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
42 Set 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
49 Unspecified::
50
51 No pattern matches the path, and nothing says if
52 the path has or does not have the attribute, the
53 attribute for the path is said to be Unspecified.
54
55 When more than one pattern matches the path, a later line
56 overrides an earlier line. This overriding is done per
57 attribute. The rules how the pattern matches paths are the
58 same as in `.gitignore` files; see linkgit:gitignore[5].
59
60 When deciding what attributes are assigned to a path, git
61 consults `$GIT_DIR/info/attributes` file (which has the highest
62 precedence), `.gitattributes` file in the same directory as the
63 path in question, and its parent directories up to the toplevel of the
64 work tree (the further the directory that contains `.gitattributes`
65 is from the path in question, the lower its precedence).
66
67 If you wish to affect only a single repository (i.e., to assign
68 attributes to files that are particular to one user's workflow), then
69 attributes should be placed in the `$GIT_DIR/info/attributes` file.
70 Attributes which should be version-controlled and distributed to other
71 repositories (i.e., attributes of interest to all users) should go into
72 `.gitattributes` files.
73
74 Sometimes you would need to override an setting of an attribute
75 for a path to `unspecified` state. This can be done by listing
76 the name of the attribute prefixed with an exclamation point `!`.
77
78
79 EFFECTS
80 -------
81
82 Certain operations by git can be influenced by assigning
83 particular attributes to a path. Currently, the following
84 operations are attributes-aware.
85
86 Checking-out and checking-in
87 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
88
89 These attributes affect how the contents stored in the
90 repository are copied to the working tree files when commands
91 such as 'git-checkout' and 'git-merge' run. They also affect how
92 git stores the contents you prepare in the working tree in the
93 repository upon 'git-add' and 'git-commit'.
94
95 `crlf`
96 ^^^^^^
97
98 This attribute controls the line-ending convention.
99
100 Set::
101
102 Setting the `crlf` attribute on a path is meant to mark
103 the path as a "text" file. 'core.autocrlf' conversion
104 takes place without guessing the content type by
105 inspection.
106
107 Unset::
108
109 Unsetting the `crlf` attribute on a path tells git not to
110 attempt any end-of-line conversion upon checkin or checkout.
111
112 Unspecified::
113
114 Unspecified `crlf` attribute tells git to apply the
115 `core.autocrlf` conversion when the file content looks
116 like text.
117
118 Set to string value "input"::
119
120 This is similar to setting the attribute to `true`, but
121 also forces git to act as if `core.autocrlf` is set to
122 `input` for the path.
123
124 Any other value set to `crlf` attribute is ignored and git acts
125 as if the attribute is left unspecified.
126
127
128 The `core.autocrlf` conversion
129 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
130
131 If the configuration variable `core.autocrlf` is false, no
132 conversion is done.
133
134 When `core.autocrlf` is true, it means that the platform wants
135 CRLF line endings for files in the working tree, and you want to
136 convert them back to the normal LF line endings when checking
137 in to the repository.
138
139 When `core.autocrlf` is set to "input", line endings are
140 converted to LF upon checkin, but there is no conversion done
141 upon checkout.
142
143 If `core.safecrlf` is set to "true" or "warn", git verifies if
144 the conversion is reversible for the current setting of
145 `core.autocrlf`. For "true", git rejects irreversible
146 conversions; for "warn", git only prints a warning but accepts
147 an irreversible conversion. The safety triggers to prevent such
148 a conversion done to the files in the work tree, but there are a
149 few exceptions. Even though...
150
151 - 'git-add' itself does not touch the files in the work tree, the
152 next checkout would, so the safety triggers;
153
154 - 'git-apply' to update a text file with a patch does touch the files
155 in the work tree, but the operation is about text files and CRLF
156 conversion is about fixing the line ending inconsistencies, so the
157 safety does not trigger;
158
159 - 'git-diff' itself does not touch the files in the work tree, it is
160 often run to inspect the changes you intend to next 'git-add'. To
161 catch potential problems early, safety triggers.
162
163
164 `ident`
165 ^^^^^^^
166
167 When the attribute `ident` is set for a path, git replaces
168 `$Id$` in the blob object with `$Id:`, followed by the
169 40-character hexadecimal blob object name, followed by a dollar
170 sign `$` upon checkout. Any byte sequence that begins with
171 `$Id:` and ends with `$` in the worktree file is replaced
172 with `$Id$` upon check-in.
173
174
175 `filter`
176 ^^^^^^^^
177
178 A `filter` attribute can be set to a string value that names a
179 filter driver specified in the configuration.
180
181 A filter driver consists of a `clean` command and a `smudge`
182 command, either of which can be left unspecified. Upon
183 checkout, when the `smudge` command is specified, the command is
184 fed the blob object from its standard input, and its standard
185 output is used to update the worktree file. Similarly, the
186 `clean` command is used to convert the contents of worktree file
187 upon checkin.
188
189 A missing filter driver definition in the config is not an error
190 but makes the filter a no-op passthru.
191
192 The content filtering is done to massage the content into a
193 shape that is more convenient for the platform, filesystem, and
194 the user to use. The key phrase here is "more convenient" and not
195 "turning something unusable into usable". In other words, the
196 intent is that if someone unsets the filter driver definition,
197 or does not have the appropriate filter program, the project
198 should still be usable.
199
200
201 Interaction between checkin/checkout attributes
202 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
203
204 In the check-in codepath, the worktree file is first converted
205 with `filter` driver (if specified and corresponding driver
206 defined), then the result is processed with `ident` (if
207 specified), and then finally with `crlf` (again, if specified
208 and applicable).
209
210 In the check-out codepath, the blob content is first converted
211 with `crlf`, and then `ident` and fed to `filter`.
212
213
214 Generating diff text
215 ~~~~~~~~~~~~~~~~~~~~
216
217 `diff`
218 ^^^^^^
219
220 The attribute `diff` affects how 'git' generates diffs for particular
221 files. It can tell git whether to generate a textual patch for the path
222 or to treat the path as a binary file. It can also affect what line is
223 shown on the hunk header `@@ -k,l +n,m @@` line, tell git to use an
224 external command to generate the diff, or ask git to convert binary
225 files to a text format before generating the diff.
226
227 Set::
228
229 A path to which the `diff` attribute is set is treated
230 as text, even when they contain byte values that
231 normally never appear in text files, such as NUL.
232
233 Unset::
234
235 A path to which the `diff` attribute is unset will
236 generate `Binary files differ` (or a binary patch, if
237 binary patches are enabled).
238
239 Unspecified::
240
241 A path to which the `diff` attribute is unspecified
242 first gets its contents inspected, and if it looks like
243 text, it is treated as text. Otherwise it would
244 generate `Binary files differ`.
245
246 String::
247
248 Diff is shown using the specified diff driver. Each driver may
249 specify one or more options, as described in the following
250 section. The options for the diff driver "foo" are defined
251 by the configuration variables in the "diff.foo" section of the
252 git config file.
253
254
255 Defining an external diff driver
256 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
257
258 The definition of a diff driver is done in `gitconfig`, not
259 `gitattributes` file, so strictly speaking this manual page is a
260 wrong place to talk about it. However...
261
262 To define an external diff driver `jcdiff`, add a section to your
263 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
264
265 ----------------------------------------------------------------
266 [diff "jcdiff"]
267 command = j-c-diff
268 ----------------------------------------------------------------
269
270 When git needs to show you a diff for the path with `diff`
271 attribute set to `jcdiff`, it calls the command you specified
272 with the above configuration, i.e. `j-c-diff`, with 7
273 parameters, just like `GIT_EXTERNAL_DIFF` program is called.
274 See linkgit:git[1] for details.
275
276
277 Defining a custom hunk-header
278 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
279
280 Each group of changes (called a "hunk") in the textual diff output
281 is prefixed with a line of the form:
282
283 @@ -k,l +n,m @@ TEXT
284
285 This is called a 'hunk header'. The "TEXT" portion is by default a line
286 that begins with an alphabet, an underscore or a dollar sign; this
287 matches what GNU 'diff -p' output uses. This default selection however
288 is not suited for some contents, and you can use a customized pattern
289 to make a selection.
290
291 First, in .gitattributes, you would assign the `diff` attribute
292 for paths.
293
294 ------------------------
295 *.tex diff=tex
296 ------------------------
297
298 Then, you would define a "diff.tex.xfuncname" configuration to
299 specify a regular expression that matches a line that you would
300 want to appear as the hunk header "TEXT". Add a section to your
301 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
302
303 ------------------------
304 [diff "tex"]
305 xfuncname = "^(\\\\(sub)*section\\{.*)$"
306 ------------------------
307
308 Note. A single level of backslashes are eaten by the
309 configuration file parser, so you would need to double the
310 backslashes; the pattern above picks a line that begins with a
311 backslash, and zero or more occurrences of `sub` followed by
312 `section` followed by open brace, to the end of line.
313
314 There are a few built-in patterns to make this easier, and `tex`
315 is one of them, so you do not have to write the above in your
316 configuration file (you still need to enable this with the
317 attribute mechanism, via `.gitattributes`). The following built in
318 patterns are available:
319
320 - `bibtex` suitable for files with BibTeX coded references.
321
322 - `cpp` suitable for source code in the C and C++ languages.
323
324 - `html` suitable for HTML/XHTML documents.
325
326 - `java` suitable for source code in the Java language.
327
328 - `objc` suitable for source code in the Objective-C language.
329
330 - `pascal` suitable for source code in the Pascal/Delphi language.
331
332 - `php` suitable for source code in the PHP language.
333
334 - `python` suitable for source code in the Python language.
335
336 - `ruby` suitable for source code in the Ruby language.
337
338 - `tex` suitable for source code for LaTeX documents.
339
340
341 Customizing word diff
342 ^^^^^^^^^^^^^^^^^^^^^
343
344 You can customize the rules that `git diff --color-words` uses to
345 split words in a line, by specifying an appropriate regular expression
346 in the "diff.*.wordRegex" configuration variable. For example, in TeX
347 a backslash followed by a sequence of letters forms a command, but
348 several such commands can be run together without intervening
349 whitespace. To separate them, use a regular expression in your
350 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
351
352 ------------------------
353 [diff "tex"]
354 wordRegex = "\\\\[a-zA-Z]+|[{}]|\\\\.|[^\\{}[:space:]]+"
355 ------------------------
356
357 A built-in pattern is provided for all languages listed in the
358 previous section.
359
360
361 Performing text diffs of binary files
362 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
363
364 Sometimes it is desirable to see the diff of a text-converted
365 version of some binary files. For example, a word processor
366 document can be converted to an ASCII text representation, and
367 the diff of the text shown. Even though this conversion loses
368 some information, the resulting diff is useful for human
369 viewing (but cannot be applied directly).
370
371 The `textconv` config option is used to define a program for
372 performing such a conversion. The program should take a single
373 argument, the name of a file to convert, and produce the
374 resulting text on stdout.
375
376 For example, to show the diff of the exif information of a
377 file instead of the binary information (assuming you have the
378 exif tool installed), add the following section to your
379 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file):
380
381 ------------------------
382 [diff "jpg"]
383 textconv = exif
384 ------------------------
385
386 NOTE: The text conversion is generally a one-way conversion;
387 in this example, we lose the actual image contents and focus
388 just on the text data. This means that diffs generated by
389 textconv are _not_ suitable for applying. For this reason,
390 only `git diff` and the `git log` family of commands (i.e.,
391 log, whatchanged, show) will perform text conversion. `git
392 format-patch` will never generate this output. If you want to
393 send somebody a text-converted diff of a binary file (e.g.,
394 because it quickly conveys the changes you have made), you
395 should generate it separately and send it as a comment _in
396 addition to_ the usual binary diff that you might send.
397
398
399 Performing a three-way merge
400 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
401
402 `merge`
403 ^^^^^^^
404
405 The attribute `merge` affects how three versions of a file is
406 merged when a file-level merge is necessary during `git merge`,
407 and other programs such as `git revert` and `git cherry-pick`.
408
409 Set::
410
411 Built-in 3-way merge driver is used to merge the
412 contents in a way similar to 'merge' command of `RCS`
413 suite. This is suitable for ordinary text files.
414
415 Unset::
416
417 Take the version from the current branch as the
418 tentative merge result, and declare that the merge has
419 conflicts. This is suitable for binary files that does
420 not have a well-defined merge semantics.
421
422 Unspecified::
423
424 By default, this uses the same built-in 3-way merge
425 driver as is the case the `merge` attribute is set.
426 However, `merge.default` configuration variable can name
427 different merge driver to be used for paths to which the
428 `merge` attribute is unspecified.
429
430 String::
431
432 3-way merge is performed using the specified custom
433 merge driver. The built-in 3-way merge driver can be
434 explicitly specified by asking for "text" driver; the
435 built-in "take the current branch" driver can be
436 requested with "binary".
437
438
439 Built-in merge drivers
440 ^^^^^^^^^^^^^^^^^^^^^^
441
442 There are a few built-in low-level merge drivers defined that
443 can be asked for via the `merge` attribute.
444
445 text::
446
447 Usual 3-way file level merge for text files. Conflicted
448 regions are marked with conflict markers `<<<<<<<`,
449 `=======` and `>>>>>>>`. The version from your branch
450 appears before the `=======` marker, and the version
451 from the merged branch appears after the `=======`
452 marker.
453
454 binary::
455
456 Keep the version from your branch in the work tree, but
457 leave the path in the conflicted state for the user to
458 sort out.
459
460 union::
461
462 Run 3-way file level merge for text files, but take
463 lines from both versions, instead of leaving conflict
464 markers. This tends to leave the added lines in the
465 resulting file in random order and the user should
466 verify the result. Do not use this if you do not
467 understand the implications.
468
469
470 Defining a custom merge driver
471 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
472
473 The definition of a merge driver is done in the `.git/config`
474 file, not in the `gitattributes` file, so strictly speaking this
475 manual page is a wrong place to talk about it. However...
476
477 To define a custom merge driver `filfre`, add a section to your
478 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
479
480 ----------------------------------------------------------------
481 [merge "filfre"]
482 name = feel-free merge driver
483 driver = filfre %O %A %B
484 recursive = binary
485 ----------------------------------------------------------------
486
487 The `merge.*.name` variable gives the driver a human-readable
488 name.
489
490 The `merge.*.driver` variable's value is used to construct a
491 command to run to merge ancestor's version (`%O`), current
492 version (`%A`) and the other branches' version (`%B`). These
493 three tokens are replaced with the names of temporary files that
494 hold the contents of these versions when the command line is
495 built.
496
497 The merge driver is expected to leave the result of the merge in
498 the file named with `%A` by overwriting it, and exit with zero
499 status if it managed to merge them cleanly, or non-zero if there
500 were conflicts.
501
502 The `merge.*.recursive` variable specifies what other merge
503 driver to use when the merge driver is called for an internal
504 merge between common ancestors, when there are more than one.
505 When left unspecified, the driver itself is used for both
506 internal merge and the final merge.
507
508
509 Checking whitespace errors
510 ~~~~~~~~~~~~~~~~~~~~~~~~~~
511
512 `whitespace`
513 ^^^^^^^^^^^^
514
515 The `core.whitespace` configuration variable allows you to define what
516 'diff' and 'apply' should consider whitespace errors for all paths in
517 the project (See linkgit:git-config[1]). This attribute gives you finer
518 control per path.
519
520 Set::
521
522 Notice all types of potential whitespace errors known to git.
523
524 Unset::
525
526 Do not notice anything as error.
527
528 Unspecified::
529
530 Use the value of `core.whitespace` configuration variable to
531 decide what to notice as error.
532
533 String::
534
535 Specify a comma separate list of common whitespace problems to
536 notice in the same format as `core.whitespace` configuration
537 variable.
538
539
540 Creating an archive
541 ~~~~~~~~~~~~~~~~~~~
542
543 `export-ignore`
544 ^^^^^^^^^^^^^^^
545
546 Files and directories with the attribute `export-ignore` won't be added to
547 archive files.
548
549 `export-subst`
550 ^^^^^^^^^^^^^^
551
552 If the attribute `export-subst` is set for a file then git will expand
553 several placeholders when adding this file to an archive. The
554 expansion depends on the availability of a commit ID, i.e., if
555 linkgit:git-archive[1] has been given a tree instead of a commit or a
556 tag then no replacement will be done. The placeholders are the same
557 as those for the option `--pretty=format:` of linkgit:git-log[1],
558 except that they need to be wrapped like this: `$Format:PLACEHOLDERS$`
559 in the file. E.g. the string `$Format:%H$` will be replaced by the
560 commit hash.
561
562
563 Viewing files in GUI tools
564 ~~~~~~~~~~~~~~~~~~~~~~~~~~
565
566 `encoding`
567 ^^^^^^^^^^
568
569 The value of this attribute specifies the character encoding that should
570 be used by GUI tools (e.g. linkgit:gitk[1] and linkgit:git-gui[1]) to
571 display the contents of the relevant file. Note that due to performance
572 considerations linkgit:gitk[1] does not use this attribute unless you
573 manually enable per-file encodings in its options.
574
575 If this attribute is not set or has an invalid value, the value of the
576 `gui.encoding` configuration variable is used instead
577 (See linkgit:git-config[1]).
578
579
580 USING ATTRIBUTE MACROS
581 ----------------------
582
583 You do not want any end-of-line conversions applied to, nor textual diffs
584 produced for, any binary file you track. You would need to specify e.g.
585
586 ------------
587 *.jpg -crlf -diff
588 ------------
589
590 but that may become cumbersome, when you have many attributes. Using
591 attribute macros, you can specify groups of attributes set or unset at
592 the same time. The system knows a built-in attribute macro, `binary`:
593
594 ------------
595 *.jpg binary
596 ------------
597
598 which is equivalent to the above. Note that the attribute macros can only
599 be "Set" (see the above example that sets "binary" macro as if it were an
600 ordinary attribute --- setting it in turn unsets "crlf" and "diff").
601
602
603 DEFINING ATTRIBUTE MACROS
604 -------------------------
605
606 Custom attribute macros can be defined only in the `.gitattributes` file
607 at the toplevel (i.e. not in any subdirectory). The built-in attribute
608 macro "binary" is equivalent to:
609
610 ------------
611 [attr]binary -diff -crlf
612 ------------
613
614
615 EXAMPLE
616 -------
617
618 If you have these three `gitattributes` file:
619
620 ----------------------------------------------------------------
621 (in $GIT_DIR/info/attributes)
622
623 a* foo !bar -baz
624
625 (in .gitattributes)
626 abc foo bar baz
627
628 (in t/.gitattributes)
629 ab* merge=filfre
630 abc -foo -bar
631 *.c frotz
632 ----------------------------------------------------------------
633
634 the attributes given to path `t/abc` are computed as follows:
635
636 1. By examining `t/.gitattributes` (which is in the same
637 directory as the path in question), git finds that the first
638 line matches. `merge` attribute is set. It also finds that
639 the second line matches, and attributes `foo` and `bar`
640 are unset.
641
642 2. Then it examines `.gitattributes` (which is in the parent
643 directory), and finds that the first line matches, but
644 `t/.gitattributes` file already decided how `merge`, `foo`
645 and `bar` attributes should be given to this path, so it
646 leaves `foo` and `bar` unset. Attribute `baz` is set.
647
648 3. Finally it examines `$GIT_DIR/info/attributes`. This file
649 is used to override the in-tree settings. The first line is
650 a match, and `foo` is set, `bar` is reverted to unspecified
651 state, and `baz` is unset.
652
653 As the result, the attributes assignment to `t/abc` becomes:
654
655 ----------------------------------------------------------------
656 foo set to true
657 bar unspecified
658 baz set to false
659 merge set to string value "filfre"
660 frotz unspecified
661 ----------------------------------------------------------------
662
663
664
665 GIT
666 ---
667 Part of the linkgit:git[1] suite