gitattributes.txt: Remove a duplicated paragraph about 'ident' and 'crlf' interaction.
[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 Sometimes you would need to override an setting of an attribute
67 for a path to `unspecified` state. This can be done by listing
68 the name of the attribute prefixed with an exclamation point `!`.
69
70
71 EFFECTS
72 -------
73
74 Certain operations by git can be influenced by assigning
75 particular attributes to a path. Currently, the following
76 operations are attributes-aware.
77
78 Checking-out and checking-in
79 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
80
81 These attributes affect how the contents stored in the
82 repository are copied to the working tree files when commands
83 such as `git checkout` and `git merge` run. They also affect how
84 git stores the contents you prepare in the working tree in the
85 repository upon `git add` and `git commit`.
86
87 `crlf`
88 ^^^^^^
89
90 This attribute controls the line-ending convention.
91
92 Set::
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
99 Unset::
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
105 Unspecified::
106
107 Unspecified `crlf` attribute tells git to apply the
108 `core.autocrlf` conversion when the file content looks
109 like text.
110
111 Set 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
117 Any other value set to `crlf` attribute is ignored and git acts
118 as if the attribute is left unspecified.
119
120
121 The `core.autocrlf` conversion
122 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
123
124 If the configuration variable `core.autocrlf` is false, no
125 conversion is done.
126
127 When `core.autocrlf` is true, it means that the platform wants
128 CRLF line endings for files in the working tree, and you want to
129 convert them back to the normal LF line endings when checking
130 in to the repository.
131
132 When `core.autocrlf` is set to "input", line endings are
133 converted to LF upon checkin, but there is no conversion done
134 upon checkout.
135
136
137 `ident`
138 ^^^^^^^
139
140 When the attribute `ident` is set to a path, git replaces
141 `$Id$` in the blob object with `$Id:`, followed by
142 40-character hexadecimal blob object name, followed by a dollar
143 sign `$` upon checkout. Any byte sequence that begins with
144 `$Id:` and ends with `$` in the worktree file is replaced
145 with `$Id$` upon check-in.
146
147
148 `filter`
149 ^^^^^^^^
150
151 A `filter` attribute can be set to a string value. This names
152 filter driver specified in the configuration.
153
154 A filter driver consists of `clean` command and `smudge`
155 command, either of which can be left unspecified. Upon
156 checkout, when `smudge` command is specified, the command is fed
157 the blob object from its standard input, and its standard output
158 is used to update the worktree file. Similarly, `clean` command
159 is used to convert the contents of worktree file upon checkin.
160
161 Missing filter driver definition in the config is not an error
162 but makes the filter a no-op passthru.
163
164 The content filtering is done to massage the content into a
165 shape that is more convenient for the platform, filesystem, and
166 the 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
169 project uses filtering mechanism in such a way that it makes
170 your project unusable unless the checkout is done with a
171 specific filter in effect.
172
173
174 Interaction between checkin/checkout attributes
175 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
176
177 In the check-in codepath, the worktree file is first converted
178 with `filter` driver (if specified and corresponding driver
179 defined), then the result is processed with `ident` (if
180 specified), and then finally with `crlf` (again, if specified
181 and applicable).
182
183 In the check-out codepath, the blob content is first converted
184 with `crlf`, and then `ident` and fed to `filter`.
185
186
187 Generating diff text
188 ~~~~~~~~~~~~~~~~~~~~
189
190 The attribute `diff` affects if `git diff` generates textual
191 patch for the path or just says `Binary files differ`. It also
192 can affect what line is shown on the hunk header `@@ -k,l +n,m @@`
193 line.
194
195 Set::
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
201 Unset::
202
203 A path to which the `diff` attribute is unset will
204 generate `Binary files differ`.
205
206 Unspecified::
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
213 String::
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
218 program. This name is also used for custom hunk header
219 selection.
220
221
222 Defining a custom diff driver
223 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
224
225 The definition of a diff driver is done in `gitconfig`, not
226 `gitattributes` file, so strictly speaking this manual page is a
227 wrong place to talk about it. However...
228
229 To 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
237 When git needs to show you a diff for the path with `diff`
238 attribute set to `jcdiff`, it calls the command you specified
239 with the above configuration, i.e. `j-c-diff`, with 7
240 parameters, just like `GIT_EXTERNAL_DIFF` program is called.
241 See gitlink:git[7] for details.
242
243
244 Defining a custom hunk-header
245 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
246
247 Each group of changes (called "hunk") in the textual diff output
248 is prefixed with a line of the form:
249
250 @@ -k,l +n,m @@ TEXT
251
252 The text is called 'hunk header', and by default a line that
253 begins with an alphabet, an underscore or a dollar sign is used,
254 which matches what GNU `diff -p` output uses. This default
255 selection however is not suited for some contents, and you can
256 use customized pattern to make a selection.
257
258 First in .gitattributes, you would assign the `diff` attribute
259 for paths.
260
261 ------------------------
262 *.tex diff=tex
263 ------------------------
264
265 Then, you would define "diff.tex.funcname" configuration to
266 specify a regular expression that matches a line that you would
267 want to appear as the hunk header, like this:
268
269 ------------------------
270 [diff "tex"]
271 funcname = "^\\(\\\\\\(sub\\)*section{.*\\)$"
272 ------------------------
273
274 Note. A single level of backslashes are eaten by the
275 configuration file parser, so you would need to double the
276 backslashes; the pattern above picks a line that begins with a
277 backslash, and zero or more occurrences of `sub` followed by
278 `section` followed by open brace, to the end of line.
279
280 There are a few built-in patterns to make this easier, and `tex`
281 is one of them, so you do not have to write the above in your
282 configuration file (you still need to enable this with the
283 attribute mechanism, via `.gitattributes`). Another built-in
284 pattern is defined for `java` that defines a pattern suitable
285 for program text in Java language.
286
287
288 Performing a three-way merge
289 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
290
291 The attribute `merge` affects how three versions of a file is
292 merged when a file-level merge is necessary during `git merge`,
293 and other programs such as `git revert` and `git cherry-pick`.
294
295 Set::
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
301 Unset::
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
308 Unspecified::
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
316 String::
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
322 requested with "binary".
323
324
325 Defining a custom merge driver
326 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
327
328 The definition of a merge driver is done in `gitconfig` not
329 `gitattributes` file, so strictly speaking this manual page is a
330 wrong place to talk about it. However...
331
332 To 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
342 The `merge.*.name` variable gives the driver a human-readable
343 name.
344
345 The `merge.*.driver` variable's value is used to construct a
346 command to run to merge ancestor's version (`%O`), current
347 version (`%A`) and the other branches' version (`%B`). These
348 three tokens are replaced with the names of temporary files that
349 hold the contents of these versions when the command line is
350 built.
351
352 The merge driver is expected to leave the result of the merge in
353 the file named with `%A` by overwriting it, and exit with zero
354 status if it managed to merge them cleanly, or non-zero if there
355 were conflicts.
356
357 The `merge.*.recursive` variable specifies what other merge
358 driver to use when the merge driver is called for an internal
359 merge between common ancestors, when there are more than one.
360 When left unspecified, the driver itself is used for both
361 internal merge and the final merge.
362
363
364 EXAMPLE
365 -------
366
367 If you have these three `gitattributes` file:
368
369 ----------------------------------------------------------------
370 (in $GIT_DIR/info/attributes)
371
372 a* foo !bar -baz
373
374 (in .gitattributes)
375 abc foo bar baz
376
377 (in t/.gitattributes)
378 ab* merge=filfre
379 abc -foo -bar
380 *.c frotz
381 ----------------------------------------------------------------
382
383 the attributes given to path `t/abc` are computed as follows:
384
385 1. By examining `t/.gitattributes` (which is in the same
386 directory as the path in question), git finds that the first
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
391 2. 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
397 3. Finally it examines `$GIT_DIR/info/attributes`. This file
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
402 As the result, the attributes assignment to `t/abc` becomes:
403
404 ----------------------------------------------------------------
405 foo set to true
406 bar unspecified
407 baz set to false
408 merge set to string value "filfre"
409 frotz unspecified
410 ----------------------------------------------------------------
411
412
413 GIT
414 ---
415 Part of the gitlink:git[7] suite