Teach new attribute 'export-ignore' to git-archive
[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 (the further the
63 directory that contains `.gitattributes` is from the path in
64 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 is meant to
109 mark the path as a "binary" file. The path never goes
110 through line endings conversion upon checkin/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 to a path, git replaces
168 `$Id$` in the blob object with `$Id:`, followed by
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 The attribute `diff` affects if `git diff` generates textual
218 patch for the path or just says `Binary files differ`. It also
219 can affect what line is shown on the hunk header `@@ -k,l +n,m @@`
220 line.
221
222 Set::
223
224 A path to which the `diff` attribute is set is treated
225 as text, even when they contain byte values that
226 normally never appear in text files, such as NUL.
227
228 Unset::
229
230 A path to which the `diff` attribute is unset will
231 generate `Binary files differ`.
232
233 Unspecified::
234
235 A path to which the `diff` attribute is unspecified
236 first gets its contents inspected, and if it looks like
237 text, it is treated as text. Otherwise it would
238 generate `Binary files differ`.
239
240 String::
241
242 Diff is shown using the specified custom diff driver.
243 The driver program is given its input using the same
244 calling convention as used for GIT_EXTERNAL_DIFF
245 program. This name is also used for custom hunk header
246 selection.
247
248
249 Defining a custom diff driver
250 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
251
252 The definition of a diff driver is done in `gitconfig`, not
253 `gitattributes` file, so strictly speaking this manual page is a
254 wrong place to talk about it. However...
255
256 To define a custom diff driver `jcdiff`, add a section to your
257 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
258
259 ----------------------------------------------------------------
260 [diff "jcdiff"]
261 command = j-c-diff
262 ----------------------------------------------------------------
263
264 When git needs to show you a diff for the path with `diff`
265 attribute set to `jcdiff`, it calls the command you specified
266 with the above configuration, i.e. `j-c-diff`, with 7
267 parameters, just like `GIT_EXTERNAL_DIFF` program is called.
268 See linkgit:git[1] for details.
269
270
271 Defining a custom hunk-header
272 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
273
274 Each group of changes (called "hunk") in the textual diff output
275 is prefixed with a line of the form:
276
277 @@ -k,l +n,m @@ TEXT
278
279 The text is called 'hunk header', and by default a line that
280 begins with an alphabet, an underscore or a dollar sign is used,
281 which matches what GNU `diff -p` output uses. This default
282 selection however is not suited for some contents, and you can
283 use customized pattern to make a selection.
284
285 First in .gitattributes, you would assign the `diff` attribute
286 for paths.
287
288 ------------------------
289 *.tex diff=tex
290 ------------------------
291
292 Then, you would define "diff.tex.funcname" configuration to
293 specify a regular expression that matches a line that you would
294 want to appear as the hunk header, like this:
295
296 ------------------------
297 [diff "tex"]
298 funcname = "^\\(\\\\\\(sub\\)*section{.*\\)$"
299 ------------------------
300
301 Note. A single level of backslashes are eaten by the
302 configuration file parser, so you would need to double the
303 backslashes; the pattern above picks a line that begins with a
304 backslash, and zero or more occurrences of `sub` followed by
305 `section` followed by open brace, to the end of line.
306
307 There are a few built-in patterns to make this easier, and `tex`
308 is one of them, so you do not have to write the above in your
309 configuration file (you still need to enable this with the
310 attribute mechanism, via `.gitattributes`). Another built-in
311 pattern is defined for `java` that defines a pattern suitable
312 for program text in Java language.
313
314
315 Performing a three-way merge
316 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
317
318 The attribute `merge` affects how three versions of a file is
319 merged when a file-level merge is necessary during `git merge`,
320 and other programs such as `git revert` and `git cherry-pick`.
321
322 Set::
323
324 Built-in 3-way merge driver is used to merge the
325 contents in a way similar to `merge` command of `RCS`
326 suite. This is suitable for ordinary text files.
327
328 Unset::
329
330 Take the version from the current branch as the
331 tentative merge result, and declare that the merge has
332 conflicts. This is suitable for binary files that does
333 not have a well-defined merge semantics.
334
335 Unspecified::
336
337 By default, this uses the same built-in 3-way merge
338 driver as is the case the `merge` attribute is set.
339 However, `merge.default` configuration variable can name
340 different merge driver to be used for paths to which the
341 `merge` attribute is unspecified.
342
343 String::
344
345 3-way merge is performed using the specified custom
346 merge driver. The built-in 3-way merge driver can be
347 explicitly specified by asking for "text" driver; the
348 built-in "take the current branch" driver can be
349 requested with "binary".
350
351
352 Built-in merge drivers
353 ^^^^^^^^^^^^^^^^^^^^^^
354
355 There are a few built-in low-level merge drivers defined that
356 can be asked for via the `merge` attribute.
357
358 text::
359
360 Usual 3-way file level merge for text files. Conflicted
361 regions are marked with conflict markers `<<<<<<<`,
362 `=======` and `>>>>>>>`. The version from your branch
363 appears before the `=======` marker, and the version
364 from the merged branch appears after the `=======`
365 marker.
366
367 binary::
368
369 Keep the version from your branch in the work tree, but
370 leave the path in the conflicted state for the user to
371 sort out.
372
373 union::
374
375 Run 3-way file level merge for text files, but take
376 lines from both versions, instead of leaving conflict
377 markers. This tends to leave the added lines in the
378 resulting file in random order and the user should
379 verify the result. Do not use this if you do not
380 understand the implications.
381
382
383 Defining a custom merge driver
384 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
385
386 The definition of a merge driver is done in the `.git/config`
387 file, not in the `gitattributes` file, so strictly speaking this
388 manual page is a wrong place to talk about it. However...
389
390 To define a custom merge driver `filfre`, add a section to your
391 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
392
393 ----------------------------------------------------------------
394 [merge "filfre"]
395 name = feel-free merge driver
396 driver = filfre %O %A %B
397 recursive = binary
398 ----------------------------------------------------------------
399
400 The `merge.*.name` variable gives the driver a human-readable
401 name.
402
403 The `merge.*.driver` variable's value is used to construct a
404 command to run to merge ancestor's version (`%O`), current
405 version (`%A`) and the other branches' version (`%B`). These
406 three tokens are replaced with the names of temporary files that
407 hold the contents of these versions when the command line is
408 built.
409
410 The merge driver is expected to leave the result of the merge in
411 the file named with `%A` by overwriting it, and exit with zero
412 status if it managed to merge them cleanly, or non-zero if there
413 were conflicts.
414
415 The `merge.*.recursive` variable specifies what other merge
416 driver to use when the merge driver is called for an internal
417 merge between common ancestors, when there are more than one.
418 When left unspecified, the driver itself is used for both
419 internal merge and the final merge.
420
421
422 Checking whitespace errors
423 ~~~~~~~~~~~~~~~~~~~~~~~~~~
424
425 `whitespace`
426 ^^^^^^^^^^^^
427
428 The `core.whitespace` configuration variable allows you to define what
429 `diff` and `apply` should consider whitespace errors for all paths in
430 the project (See linkgit:git-config[1]). This attribute gives you finer
431 control per path.
432
433 Set::
434
435 Notice all types of potential whitespace errors known to git.
436
437 Unset::
438
439 Do not notice anything as error.
440
441 Unspecified::
442
443 Use the value of `core.whitespace` configuration variable to
444 decide what to notice as error.
445
446 String::
447
448 Specify a comma separate list of common whitespace problems to
449 notice in the same format as `core.whitespace` configuration
450 variable.
451
452
453 EXAMPLE
454 -------
455
456 If you have these three `gitattributes` file:
457
458 ----------------------------------------------------------------
459 (in $GIT_DIR/info/attributes)
460
461 a* foo !bar -baz
462
463 (in .gitattributes)
464 abc foo bar baz
465
466 (in t/.gitattributes)
467 ab* merge=filfre
468 abc -foo -bar
469 *.c frotz
470 ----------------------------------------------------------------
471
472 the attributes given to path `t/abc` are computed as follows:
473
474 1. By examining `t/.gitattributes` (which is in the same
475 directory as the path in question), git finds that the first
476 line matches. `merge` attribute is set. It also finds that
477 the second line matches, and attributes `foo` and `bar`
478 are unset.
479
480 2. Then it examines `.gitattributes` (which is in the parent
481 directory), and finds that the first line matches, but
482 `t/.gitattributes` file already decided how `merge`, `foo`
483 and `bar` attributes should be given to this path, so it
484 leaves `foo` and `bar` unset. Attribute `baz` is set.
485
486 3. Finally it examines `$GIT_DIR/info/attributes`. This file
487 is used to override the in-tree settings. The first line is
488 a match, and `foo` is set, `bar` is reverted to unspecified
489 state, and `baz` is unset.
490
491 As the result, the attributes assignment to `t/abc` becomes:
492
493 ----------------------------------------------------------------
494 foo set to true
495 bar unspecified
496 baz set to false
497 merge set to string value "filfre"
498 frotz unspecified
499 ----------------------------------------------------------------
500
501
502 Creating an archive
503 ~~~~~~~~~~~~~~~~~~~
504
505 `export-ignore`
506 ^^^^^^^^^^^^^^^
507
508 Files and directories with the attribute `export-ignore` won't be added to
509 archive files.
510
511 `export-subst`
512 ^^^^^^^^^^^^^^
513
514 If the attribute `export-subst` is set for a file then git will expand
515 several placeholders when adding this file to an archive. The
516 expansion depends on the availability of a commit ID, i.e. if
517 linkgit:git-archive[1] has been given a tree instead of a commit or a
518 tag then no replacement will be done. The placeholders are the same
519 as those for the option `--pretty=format:` of linkgit:git-log[1],
520 except that they need to be wrapped like this: `$Format:PLACEHOLDERS$`
521 in the file. E.g. the string `$Format:%H$` will be replaced by the
522 commit hash.
523
524
525 GIT
526 ---
527 Part of the linkgit:git[1] suite