Teach new attribute 'export-ignore' to git-archive
[git/git.git] / Documentation / gitattributes.txt
CommitLineData
88e7fdf2
JH
1gitattributes(5)
2================
3
4NAME
5----
6gitattributes - defining attributes per path
7
8SYNOPSIS
9--------
2d76548b 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
21 glob attr1 attr2 ...
22
23That is, a glob pattern followed by an attributes list,
24separated by whitespaces. When the glob pattern matches the
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
51 No glob 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
JH
54
55When more than one glob pattern matches the path, a later line
b9d14ffb
JH
56overrides an earlier line. This overriding is done per
57attribute.
88e7fdf2
JH
58
59When deciding what attributes are assigned to a path, git
60consults `$GIT_DIR/info/attributes` file (which has the highest
61precedence), `.gitattributes` file in the same directory as the
62path in question, and its parent directories (the further the
63directory that contains `.gitattributes` is from the path in
64question, the lower its precedence).
65
90b22907
JK
66If you wish to affect only a single repository (i.e., to assign
67attributes to files that are particular to one user's workflow), then
68attributes should be placed in the `$GIT_DIR/info/attributes` file.
69Attributes which should be version-controlled and distributed to other
70repositories (i.e., attributes of interest to all users) should go into
71`.gitattributes` files.
72
88e7fdf2
JH
73Sometimes you would need to override an setting of an attribute
74for a path to `unspecified` state. This can be done by listing
75the name of the attribute prefixed with an exclamation point `!`.
76
77
78EFFECTS
79-------
80
81Certain operations by git can be influenced by assigning
ae7aa499
JH
82particular attributes to a path. Currently, the following
83operations are attributes-aware.
88e7fdf2
JH
84
85Checking-out and checking-in
86~~~~~~~~~~~~~~~~~~~~~~~~~~~~
87
3fed15f5 88These attributes affect how the contents stored in the
88e7fdf2 89repository are copied to the working tree files when commands
3fed15f5 90such as `git checkout` and `git merge` run. They also affect how
88e7fdf2
JH
91git stores the contents you prepare in the working tree in the
92repository upon `git add` and `git commit`.
93
3fed15f5
JH
94`crlf`
95^^^^^^
96
97This attribute controls the line-ending convention.
98
88e7fdf2
JH
99Set::
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
106Unset::
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
112Unspecified::
113
114 Unspecified `crlf` attribute tells git to apply the
115 `core.autocrlf` conversion when the file content looks
116 like text.
117
118Set 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
124Any other value set to `crlf` attribute is ignored and git acts
125as if the attribute is left unspecified.
126
127
128The `core.autocrlf` conversion
129^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
130
131If the configuration variable `core.autocrlf` is false, no
132conversion is done.
133
134When `core.autocrlf` is true, it means that the platform wants
135CRLF line endings for files in the working tree, and you want to
136convert them back to the normal LF line endings when checking
137in to the repository.
138
139When `core.autocrlf` is set to "input", line endings are
140converted to LF upon checkin, but there is no conversion done
141upon checkout.
142
21e5ad50
SP
143If `core.safecrlf` is set to "true" or "warn", git verifies if
144the conversion is reversible for the current setting of
145`core.autocrlf`. For "true", git rejects irreversible
146conversions; for "warn", git only prints a warning but accepts
147an irreversible conversion. The safety triggers to prevent such
148a conversion done to the files in the work tree, but there are a
149few 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
88e7fdf2 163
3fed15f5
JH
164`ident`
165^^^^^^^
166
167When the attribute `ident` is set to a path, git replaces
af9b54bb 168`$Id$` in the blob object with `$Id:`, followed by
3fed15f5
JH
16940-character hexadecimal blob object name, followed by a dollar
170sign `$` upon checkout. Any byte sequence that begins with
af9b54bb
AP
171`$Id:` and ends with `$` in the worktree file is replaced
172with `$Id$` upon check-in.
3fed15f5
JH
173
174
aa4ed402
JH
175`filter`
176^^^^^^^^
177
c05ef938 178A `filter` attribute can be set to a string value that names a
aa4ed402
JH
179filter driver specified in the configuration.
180
c05ef938 181A filter driver consists of a `clean` command and a `smudge`
aa4ed402 182command, either of which can be left unspecified. Upon
c05ef938
WC
183checkout, when the `smudge` command is specified, the command is
184fed the blob object from its standard input, and its standard
185output is used to update the worktree file. Similarly, the
186`clean` command is used to convert the contents of worktree file
187upon checkin.
aa4ed402 188
c05ef938 189A missing filter driver definition in the config is not an error
aa4ed402
JH
190but makes the filter a no-op passthru.
191
192The content filtering is done to massage the content into a
193shape that is more convenient for the platform, filesystem, and
c05ef938 194the user to use. The key phrase here is "more convenient" and not
4d84aff3
JS
195"turning something unusable into usable". In other words, the
196intent is that if someone unsets the filter driver definition,
197or does not have the appropriate filter program, the project
198should still be usable.
aa4ed402
JH
199
200
201Interaction between checkin/checkout attributes
202^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
203
204In the check-in codepath, the worktree file is first converted
205with `filter` driver (if specified and corresponding driver
206defined), then the result is processed with `ident` (if
207specified), and then finally with `crlf` (again, if specified
208and applicable).
209
210In the check-out codepath, the blob content is first converted
211with `crlf`, and then `ident` and fed to `filter`.
212
213
88e7fdf2
JH
214Generating diff text
215~~~~~~~~~~~~~~~~~~~~
216
217The attribute `diff` affects if `git diff` generates textual
ae7aa499
JH
218patch for the path or just says `Binary files differ`. It also
219can affect what line is shown on the hunk header `@@ -k,l +n,m @@`
220line.
88e7fdf2
JH
221
222Set::
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
228Unset::
229
230 A path to which the `diff` attribute is unset will
231 generate `Binary files differ`.
232
233Unspecified::
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
2cc3167c
JH
240String::
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
ae7aa499
JH
245 program. This name is also used for custom hunk header
246 selection.
2cc3167c
JH
247
248
249Defining a custom diff driver
250^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
251
252The definition of a diff driver is done in `gitconfig`, not
253`gitattributes` file, so strictly speaking this manual page is a
254wrong place to talk about it. However...
255
256To 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
264When git needs to show you a diff for the path with `diff`
265attribute set to `jcdiff`, it calls the command you specified
266with the above configuration, i.e. `j-c-diff`, with 7
267parameters, just like `GIT_EXTERNAL_DIFF` program is called.
9e1f0a85 268See linkgit:git[1] for details.
88e7fdf2
JH
269
270
ae7aa499
JH
271Defining a custom hunk-header
272^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
273
274Each group of changes (called "hunk") in the textual diff output
275is prefixed with a line of the form:
276
277 @@ -k,l +n,m @@ TEXT
278
279The text is called 'hunk header', and by default a line that
280begins with an alphabet, an underscore or a dollar sign is used,
281which matches what GNU `diff -p` output uses. This default
282selection however is not suited for some contents, and you can
283use customized pattern to make a selection.
284
285First in .gitattributes, you would assign the `diff` attribute
286for paths.
287
288------------------------
289*.tex diff=tex
290------------------------
291
292Then, you would define "diff.tex.funcname" configuration to
293specify a regular expression that matches a line that you would
294want to appear as the hunk header, like this:
295
296------------------------
297[diff "tex"]
298 funcname = "^\\(\\\\\\(sub\\)*section{.*\\)$"
299------------------------
300
301Note. A single level of backslashes are eaten by the
302configuration file parser, so you would need to double the
303backslashes; the pattern above picks a line that begins with a
02783075 304backslash, and zero or more occurrences of `sub` followed by
ae7aa499
JH
305`section` followed by open brace, to the end of line.
306
307There are a few built-in patterns to make this easier, and `tex`
308is one of them, so you do not have to write the above in your
309configuration file (you still need to enable this with the
310attribute mechanism, via `.gitattributes`). Another built-in
311pattern is defined for `java` that defines a pattern suitable
312for program text in Java language.
313
314
88e7fdf2
JH
315Performing a three-way merge
316~~~~~~~~~~~~~~~~~~~~~~~~~~~~
317
318The attribute `merge` affects how three versions of a file is
319merged when a file-level merge is necessary during `git merge`,
320and other programs such as `git revert` and `git cherry-pick`.
321
322Set::
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
328Unset::
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
335Unspecified::
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
2cc3167c 343String::
88e7fdf2
JH
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
b9d14ffb 349 requested with "binary".
88e7fdf2
JH
350
351
0e545f75
JH
352Built-in merge drivers
353^^^^^^^^^^^^^^^^^^^^^^
354
355There are a few built-in low-level merge drivers defined that
356can be asked for via the `merge` attribute.
357
358text::
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
367binary::
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
373union::
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
88e7fdf2
JH
383Defining a custom merge driver
384^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
385
0e545f75
JH
386The definition of a merge driver is done in the `.git/config`
387file, not in the `gitattributes` file, so strictly speaking this
388manual page is a wrong place to talk about it. However...
88e7fdf2
JH
389
390To 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
400The `merge.*.name` variable gives the driver a human-readable
401name.
402
403The `merge.*.driver` variable's value is used to construct a
404command to run to merge ancestor's version (`%O`), current
405version (`%A`) and the other branches' version (`%B`). These
406three tokens are replaced with the names of temporary files that
407hold the contents of these versions when the command line is
408built.
409
410The merge driver is expected to leave the result of the merge in
411the file named with `%A` by overwriting it, and exit with zero
412status if it managed to merge them cleanly, or non-zero if there
413were conflicts.
414
415The `merge.*.recursive` variable specifies what other merge
416driver to use when the merge driver is called for an internal
417merge between common ancestors, when there are more than one.
418When left unspecified, the driver itself is used for both
419internal merge and the final merge.
420
421
cf1b7869
JH
422Checking whitespace errors
423~~~~~~~~~~~~~~~~~~~~~~~~~~
424
425`whitespace`
426^^^^^^^^^^^^
427
428The `core.whitespace` configuration variable allows you to define what
429`diff` and `apply` should consider whitespace errors for all paths in
5162e697 430the project (See linkgit:git-config[1]). This attribute gives you finer
cf1b7869
JH
431control per path.
432
433Set::
434
435 Notice all types of potential whitespace errors known to git.
436
437Unset::
438
439 Do not notice anything as error.
440
441Unspecified::
442
443 Use the value of `core.whitespace` configuration variable to
444 decide what to notice as error.
445
446String::
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
88e7fdf2
JH
453EXAMPLE
454-------
455
456If you have these three `gitattributes` file:
457
458----------------------------------------------------------------
459(in $GIT_DIR/info/attributes)
460
461a* foo !bar -baz
462
463(in .gitattributes)
464abc foo bar baz
465
466(in t/.gitattributes)
467ab* merge=filfre
468abc -foo -bar
469*.c frotz
470----------------------------------------------------------------
471
472the attributes given to path `t/abc` are computed as follows:
473
4741. By examining `t/.gitattributes` (which is in the same
02783075 475 directory as the path in question), git finds that the first
88e7fdf2
JH
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
4802. 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
5c759f96 4863. Finally it examines `$GIT_DIR/info/attributes`. This file
88e7fdf2
JH
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
02783075 491As the result, the attributes assignment to `t/abc` becomes:
88e7fdf2
JH
492
493----------------------------------------------------------------
494foo set to true
495bar unspecified
496baz set to false
497merge set to string value "filfre"
498frotz unspecified
499----------------------------------------------------------------
500
501
8460b2fc
RS
502Creating an archive
503~~~~~~~~~~~~~~~~~~~
504
008d896d
RS
505`export-ignore`
506^^^^^^^^^^^^^^^
507
508Files and directories with the attribute `export-ignore` won't be added to
509archive files.
510
38c9c9b7
RS
511`export-subst`
512^^^^^^^^^^^^^^
8460b2fc 513
38c9c9b7 514If the attribute `export-subst` is set for a file then git will expand
8460b2fc
RS
515several placeholders when adding this file to an archive. The
516expansion depends on the availability of a commit ID, i.e. if
5162e697 517linkgit:git-archive[1] has been given a tree instead of a commit or a
8460b2fc 518tag then no replacement will be done. The placeholders are the same
5162e697 519as those for the option `--pretty=format:` of linkgit:git-log[1],
df4a394f
RS
520except that they need to be wrapped like this: `$Format:PLACEHOLDERS$`
521in the file. E.g. the string `$Format:%H$` will be replaced by the
522commit hash.
8460b2fc
RS
523
524
88e7fdf2
JH
525GIT
526---
9e1f0a85 527Part of the linkgit:git[1] suite