46f9d591aa7a3af2235d29308d101b2bfa0bff56
[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 Interaction between checkin/checkout attributes
149 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
150
151 In the check-in codepath, the worktree file is first converted
152 with `ident` (if specified), and then with `crlf` (again, if
153 specified and applicable).
154
155 In the check-out codepath, the blob content is first converted
156 with `crlf`, and then `ident`.
157
158
159 `filter`
160 ^^^^^^^^
161
162 A `filter` attribute can be set to a string value. This names
163 filter driver specified in the configuration.
164
165 A filter driver consists of `clean` command and `smudge`
166 command, either of which can be left unspecified. Upon
167 checkout, when `smudge` command is specified, the command is fed
168 the blob object from its standard input, and its standard output
169 is used to update the worktree file. Similarly, `clean` command
170 is used to convert the contents of worktree file upon checkin.
171
172 Missing filter driver definition in the config is not an error
173 but makes the filter a no-op passthru.
174
175 The content filtering is done to massage the content into a
176 shape that is more convenient for the platform, filesystem, and
177 the user to use. The keyword here is "more convenient" and not
178 "turning something unusable into usable". In other words, it is
179 "hanging yourself because we gave you a long rope" if your
180 project uses filtering mechanism in such a way that it makes
181 your project unusable unless the checkout is done with a
182 specific filter in effect.
183
184
185 Interaction between checkin/checkout attributes
186 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
187
188 In the check-in codepath, the worktree file is first converted
189 with `filter` driver (if specified and corresponding driver
190 defined), then the result is processed with `ident` (if
191 specified), and then finally with `crlf` (again, if specified
192 and applicable).
193
194 In the check-out codepath, the blob content is first converted
195 with `crlf`, and then `ident` and fed to `filter`.
196
197
198 Generating diff text
199 ~~~~~~~~~~~~~~~~~~~~
200
201 The attribute `diff` affects if `git diff` generates textual
202 patch for the path or just says `Binary files differ`. It also
203 can affect what line is shown on the hunk header `@@ -k,l +n,m @@`
204 line.
205
206 Set::
207
208 A path to which the `diff` attribute is set is treated
209 as text, even when they contain byte values that
210 normally never appear in text files, such as NUL.
211
212 Unset::
213
214 A path to which the `diff` attribute is unset will
215 generate `Binary files differ`.
216
217 Unspecified::
218
219 A path to which the `diff` attribute is unspecified
220 first gets its contents inspected, and if it looks like
221 text, it is treated as text. Otherwise it would
222 generate `Binary files differ`.
223
224 String::
225
226 Diff is shown using the specified custom diff driver.
227 The driver program is given its input using the same
228 calling convention as used for GIT_EXTERNAL_DIFF
229 program. This name is also used for custom hunk header
230 selection.
231
232
233 Defining a custom diff driver
234 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
235
236 The definition of a diff driver is done in `gitconfig`, not
237 `gitattributes` file, so strictly speaking this manual page is a
238 wrong place to talk about it. However...
239
240 To define a custom diff driver `jcdiff`, add a section to your
241 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
242
243 ----------------------------------------------------------------
244 [diff "jcdiff"]
245 command = j-c-diff
246 ----------------------------------------------------------------
247
248 When git needs to show you a diff for the path with `diff`
249 attribute set to `jcdiff`, it calls the command you specified
250 with the above configuration, i.e. `j-c-diff`, with 7
251 parameters, just like `GIT_EXTERNAL_DIFF` program is called.
252 See gitlink:git[7] for details.
253
254
255 Defining a custom hunk-header
256 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
257
258 Each group of changes (called "hunk") in the textual diff output
259 is prefixed with a line of the form:
260
261 @@ -k,l +n,m @@ TEXT
262
263 The text is called 'hunk header', and by default a line that
264 begins with an alphabet, an underscore or a dollar sign is used,
265 which matches what GNU `diff -p` output uses. This default
266 selection however is not suited for some contents, and you can
267 use customized pattern to make a selection.
268
269 First in .gitattributes, you would assign the `diff` attribute
270 for paths.
271
272 ------------------------
273 *.tex diff=tex
274 ------------------------
275
276 Then, you would define "diff.tex.funcname" configuration to
277 specify a regular expression that matches a line that you would
278 want to appear as the hunk header, like this:
279
280 ------------------------
281 [diff "tex"]
282 funcname = "^\\(\\\\\\(sub\\)*section{.*\\)$"
283 ------------------------
284
285 Note. A single level of backslashes are eaten by the
286 configuration file parser, so you would need to double the
287 backslashes; the pattern above picks a line that begins with a
288 backslash, and zero or more occurrences of `sub` followed by
289 `section` followed by open brace, to the end of line.
290
291 There are a few built-in patterns to make this easier, and `tex`
292 is one of them, so you do not have to write the above in your
293 configuration file (you still need to enable this with the
294 attribute mechanism, via `.gitattributes`). Another built-in
295 pattern is defined for `java` that defines a pattern suitable
296 for program text in Java language.
297
298
299 Performing a three-way merge
300 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
301
302 The attribute `merge` affects how three versions of a file is
303 merged when a file-level merge is necessary during `git merge`,
304 and other programs such as `git revert` and `git cherry-pick`.
305
306 Set::
307
308 Built-in 3-way merge driver is used to merge the
309 contents in a way similar to `merge` command of `RCS`
310 suite. This is suitable for ordinary text files.
311
312 Unset::
313
314 Take the version from the current branch as the
315 tentative merge result, and declare that the merge has
316 conflicts. This is suitable for binary files that does
317 not have a well-defined merge semantics.
318
319 Unspecified::
320
321 By default, this uses the same built-in 3-way merge
322 driver as is the case the `merge` attribute is set.
323 However, `merge.default` configuration variable can name
324 different merge driver to be used for paths to which the
325 `merge` attribute is unspecified.
326
327 String::
328
329 3-way merge is performed using the specified custom
330 merge driver. The built-in 3-way merge driver can be
331 explicitly specified by asking for "text" driver; the
332 built-in "take the current branch" driver can be
333 requested with "binary".
334
335
336 Defining a custom merge driver
337 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
338
339 The definition of a merge driver is done in `gitconfig` not
340 `gitattributes` file, so strictly speaking this manual page is a
341 wrong place to talk about it. However...
342
343 To define a custom merge driver `filfre`, add a section to your
344 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
345
346 ----------------------------------------------------------------
347 [merge "filfre"]
348 name = feel-free merge driver
349 driver = filfre %O %A %B
350 recursive = binary
351 ----------------------------------------------------------------
352
353 The `merge.*.name` variable gives the driver a human-readable
354 name.
355
356 The `merge.*.driver` variable's value is used to construct a
357 command to run to merge ancestor's version (`%O`), current
358 version (`%A`) and the other branches' version (`%B`). These
359 three tokens are replaced with the names of temporary files that
360 hold the contents of these versions when the command line is
361 built.
362
363 The merge driver is expected to leave the result of the merge in
364 the file named with `%A` by overwriting it, and exit with zero
365 status if it managed to merge them cleanly, or non-zero if there
366 were conflicts.
367
368 The `merge.*.recursive` variable specifies what other merge
369 driver to use when the merge driver is called for an internal
370 merge between common ancestors, when there are more than one.
371 When left unspecified, the driver itself is used for both
372 internal merge and the final merge.
373
374
375 EXAMPLE
376 -------
377
378 If you have these three `gitattributes` file:
379
380 ----------------------------------------------------------------
381 (in $GIT_DIR/info/attributes)
382
383 a* foo !bar -baz
384
385 (in .gitattributes)
386 abc foo bar baz
387
388 (in t/.gitattributes)
389 ab* merge=filfre
390 abc -foo -bar
391 *.c frotz
392 ----------------------------------------------------------------
393
394 the attributes given to path `t/abc` are computed as follows:
395
396 1. By examining `t/.gitattributes` (which is in the same
397 directory as the path in question), git finds that the first
398 line matches. `merge` attribute is set. It also finds that
399 the second line matches, and attributes `foo` and `bar`
400 are unset.
401
402 2. Then it examines `.gitattributes` (which is in the parent
403 directory), and finds that the first line matches, but
404 `t/.gitattributes` file already decided how `merge`, `foo`
405 and `bar` attributes should be given to this path, so it
406 leaves `foo` and `bar` unset. Attribute `baz` is set.
407
408 3. Finally it examines `$GIT_DIR/info/attributes`. This file
409 is used to override the in-tree settings. The first line is
410 a match, and `foo` is set, `bar` is reverted to unspecified
411 state, and `baz` is unset.
412
413 As the result, the attributes assignment to `t/abc` becomes:
414
415 ----------------------------------------------------------------
416 foo set to true
417 bar unspecified
418 baz set to false
419 merge set to string value "filfre"
420 frotz unspecified
421 ----------------------------------------------------------------
422
423
424 GIT
425 ---
426 Part of the gitlink:git[7] suite