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