gitattributes.txt: Remove a duplicated paragraph about 'ident' and 'crlf' interaction.
[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
66Sometimes you would need to override an setting of an attribute
67for a path to `unspecified` state. This can be done by listing
68the name of the attribute prefixed with an exclamation point `!`.
69
70
71EFFECTS
72-------
73
74Certain operations by git can be influenced by assigning
ae7aa499
JH
75particular attributes to a path. Currently, the following
76operations are attributes-aware.
88e7fdf2
JH
77
78Checking-out and checking-in
79~~~~~~~~~~~~~~~~~~~~~~~~~~~~
80
3fed15f5 81These attributes affect how the contents stored in the
88e7fdf2 82repository are copied to the working tree files when commands
3fed15f5 83such as `git checkout` and `git merge` run. They also affect how
88e7fdf2
JH
84git stores the contents you prepare in the working tree in the
85repository upon `git add` and `git commit`.
86
3fed15f5
JH
87`crlf`
88^^^^^^
89
90This attribute controls the line-ending convention.
91
88e7fdf2
JH
92Set::
93
94 Setting the `crlf` attribute on a path is meant to mark
95 the path as a "text" file. 'core.autocrlf' conversion
96 takes place without guessing the content type by
97 inspection.
98
99Unset::
100
101 Unsetting the `crlf` attribute on a path is meant to
102 mark the path as a "binary" file. The path never goes
103 through line endings conversion upon checkin/checkout.
104
105Unspecified::
106
107 Unspecified `crlf` attribute tells git to apply the
108 `core.autocrlf` conversion when the file content looks
109 like text.
110
111Set to string value "input"::
112
113 This is similar to setting the attribute to `true`, but
114 also forces git to act as if `core.autocrlf` is set to
115 `input` for the path.
116
117Any other value set to `crlf` attribute is ignored and git acts
118as if the attribute is left unspecified.
119
120
121The `core.autocrlf` conversion
122^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
123
124If the configuration variable `core.autocrlf` is false, no
125conversion is done.
126
127When `core.autocrlf` is true, it means that the platform wants
128CRLF line endings for files in the working tree, and you want to
129convert them back to the normal LF line endings when checking
130in to the repository.
131
132When `core.autocrlf` is set to "input", line endings are
133converted to LF upon checkin, but there is no conversion done
134upon checkout.
135
136
3fed15f5
JH
137`ident`
138^^^^^^^
139
140When the attribute `ident` is set to a path, git replaces
af9b54bb 141`$Id$` in the blob object with `$Id:`, followed by
3fed15f5
JH
14240-character hexadecimal blob object name, followed by a dollar
143sign `$` upon checkout. Any byte sequence that begins with
af9b54bb
AP
144`$Id:` and ends with `$` in the worktree file is replaced
145with `$Id$` upon check-in.
3fed15f5
JH
146
147
aa4ed402
JH
148`filter`
149^^^^^^^^
150
151A `filter` attribute can be set to a string value. This names
152filter driver specified in the configuration.
153
154A filter driver consists of `clean` command and `smudge`
155command, either of which can be left unspecified. Upon
156checkout, when `smudge` command is specified, the command is fed
157the blob object from its standard input, and its standard output
158is used to update the worktree file. Similarly, `clean` command
159is used to convert the contents of worktree file upon checkin.
160
161Missing filter driver definition in the config is not an error
162but makes the filter a no-op passthru.
163
164The content filtering is done to massage the content into a
165shape that is more convenient for the platform, filesystem, and
166the user to use. The keyword here is "more convenient" and not
167"turning something unusable into usable". In other words, it is
168"hanging yourself because we gave you a long rope" if your
169project uses filtering mechanism in such a way that it makes
170your project unusable unless the checkout is done with a
171specific filter in effect.
172
173
174Interaction between checkin/checkout attributes
175^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
176
177In the check-in codepath, the worktree file is first converted
178with `filter` driver (if specified and corresponding driver
179defined), then the result is processed with `ident` (if
180specified), and then finally with `crlf` (again, if specified
181and applicable).
182
183In the check-out codepath, the blob content is first converted
184with `crlf`, and then `ident` and fed to `filter`.
185
186
88e7fdf2
JH
187Generating diff text
188~~~~~~~~~~~~~~~~~~~~
189
190The attribute `diff` affects if `git diff` generates textual
ae7aa499
JH
191patch for the path or just says `Binary files differ`. It also
192can affect what line is shown on the hunk header `@@ -k,l +n,m @@`
193line.
88e7fdf2
JH
194
195Set::
196
197 A path to which the `diff` attribute is set is treated
198 as text, even when they contain byte values that
199 normally never appear in text files, such as NUL.
200
201Unset::
202
203 A path to which the `diff` attribute is unset will
204 generate `Binary files differ`.
205
206Unspecified::
207
208 A path to which the `diff` attribute is unspecified
209 first gets its contents inspected, and if it looks like
210 text, it is treated as text. Otherwise it would
211 generate `Binary files differ`.
212
2cc3167c
JH
213String::
214
215 Diff is shown using the specified custom diff driver.
216 The driver program is given its input using the same
217 calling convention as used for GIT_EXTERNAL_DIFF
ae7aa499
JH
218 program. This name is also used for custom hunk header
219 selection.
2cc3167c
JH
220
221
222Defining a custom diff driver
223^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
224
225The definition of a diff driver is done in `gitconfig`, not
226`gitattributes` file, so strictly speaking this manual page is a
227wrong place to talk about it. However...
228
229To define a custom diff driver `jcdiff`, add a section to your
230`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
231
232----------------------------------------------------------------
233[diff "jcdiff"]
234 command = j-c-diff
235----------------------------------------------------------------
236
237When git needs to show you a diff for the path with `diff`
238attribute set to `jcdiff`, it calls the command you specified
239with the above configuration, i.e. `j-c-diff`, with 7
240parameters, just like `GIT_EXTERNAL_DIFF` program is called.
241See gitlink:git[7] for details.
88e7fdf2
JH
242
243
ae7aa499
JH
244Defining a custom hunk-header
245^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
246
247Each group of changes (called "hunk") in the textual diff output
248is prefixed with a line of the form:
249
250 @@ -k,l +n,m @@ TEXT
251
252The text is called 'hunk header', and by default a line that
253begins with an alphabet, an underscore or a dollar sign is used,
254which matches what GNU `diff -p` output uses. This default
255selection however is not suited for some contents, and you can
256use customized pattern to make a selection.
257
258First in .gitattributes, you would assign the `diff` attribute
259for paths.
260
261------------------------
262*.tex diff=tex
263------------------------
264
265Then, you would define "diff.tex.funcname" configuration to
266specify a regular expression that matches a line that you would
267want to appear as the hunk header, like this:
268
269------------------------
270[diff "tex"]
271 funcname = "^\\(\\\\\\(sub\\)*section{.*\\)$"
272------------------------
273
274Note. A single level of backslashes are eaten by the
275configuration file parser, so you would need to double the
276backslashes; the pattern above picks a line that begins with a
02783075 277backslash, and zero or more occurrences of `sub` followed by
ae7aa499
JH
278`section` followed by open brace, to the end of line.
279
280There are a few built-in patterns to make this easier, and `tex`
281is one of them, so you do not have to write the above in your
282configuration file (you still need to enable this with the
283attribute mechanism, via `.gitattributes`). Another built-in
284pattern is defined for `java` that defines a pattern suitable
285for program text in Java language.
286
287
88e7fdf2
JH
288Performing a three-way merge
289~~~~~~~~~~~~~~~~~~~~~~~~~~~~
290
291The attribute `merge` affects how three versions of a file is
292merged when a file-level merge is necessary during `git merge`,
293and other programs such as `git revert` and `git cherry-pick`.
294
295Set::
296
297 Built-in 3-way merge driver is used to merge the
298 contents in a way similar to `merge` command of `RCS`
299 suite. This is suitable for ordinary text files.
300
301Unset::
302
303 Take the version from the current branch as the
304 tentative merge result, and declare that the merge has
305 conflicts. This is suitable for binary files that does
306 not have a well-defined merge semantics.
307
308Unspecified::
309
310 By default, this uses the same built-in 3-way merge
311 driver as is the case the `merge` attribute is set.
312 However, `merge.default` configuration variable can name
313 different merge driver to be used for paths to which the
314 `merge` attribute is unspecified.
315
2cc3167c 316String::
88e7fdf2
JH
317
318 3-way merge is performed using the specified custom
319 merge driver. The built-in 3-way merge driver can be
320 explicitly specified by asking for "text" driver; the
321 built-in "take the current branch" driver can be
b9d14ffb 322 requested with "binary".
88e7fdf2
JH
323
324
325Defining a custom merge driver
326^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
327
328The definition of a merge driver is done in `gitconfig` not
329`gitattributes` file, so strictly speaking this manual page is a
330wrong place to talk about it. However...
331
332To define a custom merge driver `filfre`, add a section to your
333`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
334
335----------------------------------------------------------------
336[merge "filfre"]
337 name = feel-free merge driver
338 driver = filfre %O %A %B
339 recursive = binary
340----------------------------------------------------------------
341
342The `merge.*.name` variable gives the driver a human-readable
343name.
344
345The `merge.*.driver` variable's value is used to construct a
346command to run to merge ancestor's version (`%O`), current
347version (`%A`) and the other branches' version (`%B`). These
348three tokens are replaced with the names of temporary files that
349hold the contents of these versions when the command line is
350built.
351
352The merge driver is expected to leave the result of the merge in
353the file named with `%A` by overwriting it, and exit with zero
354status if it managed to merge them cleanly, or non-zero if there
355were conflicts.
356
357The `merge.*.recursive` variable specifies what other merge
358driver to use when the merge driver is called for an internal
359merge between common ancestors, when there are more than one.
360When left unspecified, the driver itself is used for both
361internal merge and the final merge.
362
363
364EXAMPLE
365-------
366
367If you have these three `gitattributes` file:
368
369----------------------------------------------------------------
370(in $GIT_DIR/info/attributes)
371
372a* foo !bar -baz
373
374(in .gitattributes)
375abc foo bar baz
376
377(in t/.gitattributes)
378ab* merge=filfre
379abc -foo -bar
380*.c frotz
381----------------------------------------------------------------
382
383the attributes given to path `t/abc` are computed as follows:
384
3851. By examining `t/.gitattributes` (which is in the same
02783075 386 directory as the path in question), git finds that the first
88e7fdf2
JH
387 line matches. `merge` attribute is set. It also finds that
388 the second line matches, and attributes `foo` and `bar`
389 are unset.
390
3912. Then it examines `.gitattributes` (which is in the parent
392 directory), and finds that the first line matches, but
393 `t/.gitattributes` file already decided how `merge`, `foo`
394 and `bar` attributes should be given to this path, so it
395 leaves `foo` and `bar` unset. Attribute `baz` is set.
396
5c759f96 3973. Finally it examines `$GIT_DIR/info/attributes`. This file
88e7fdf2
JH
398 is used to override the in-tree settings. The first line is
399 a match, and `foo` is set, `bar` is reverted to unspecified
400 state, and `baz` is unset.
401
02783075 402As the result, the attributes assignment to `t/abc` becomes:
88e7fdf2
JH
403
404----------------------------------------------------------------
405foo set to true
406bar unspecified
407baz set to false
408merge set to string value "filfre"
409frotz unspecified
410----------------------------------------------------------------
411
412
413GIT
414---
415Part of the gitlink:git[7] suite