]>
Commit | Line | Data |
---|---|---|
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 tells git not to | |
109 | attempt any end-of-line conversion upon checkin or checkout. | |
110 | ||
111 | Unspecified:: | |
112 | ||
113 | Unspecified `crlf` attribute tells git to apply the | |
114 | `core.autocrlf` conversion when the file content looks | |
115 | like text. | |
116 | ||
117 | Set to string value "input":: | |
118 | ||
119 | This is similar to setting the attribute to `true`, but | |
120 | also forces git to act as if `core.autocrlf` is set to | |
121 | `input` for the path. | |
122 | ||
123 | Any other value set to `crlf` attribute is ignored and git acts | |
124 | as if the attribute is left unspecified. | |
125 | ||
126 | ||
127 | The `core.autocrlf` conversion | |
128 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
129 | ||
130 | If the configuration variable `core.autocrlf` is false, no | |
131 | conversion is done. | |
132 | ||
133 | When `core.autocrlf` is true, it means that the platform wants | |
134 | CRLF line endings for files in the working tree, and you want to | |
135 | convert them back to the normal LF line endings when checking | |
136 | in to the repository. | |
137 | ||
138 | When `core.autocrlf` is set to "input", line endings are | |
139 | converted to LF upon checkin, but there is no conversion done | |
140 | upon checkout. | |
141 | ||
142 | If `core.safecrlf` is set to "true" or "warn", git verifies if | |
143 | the conversion is reversible for the current setting of | |
144 | `core.autocrlf`. For "true", git rejects irreversible | |
145 | conversions; for "warn", git only prints a warning but accepts | |
146 | an irreversible conversion. The safety triggers to prevent such | |
147 | a conversion done to the files in the work tree, but there are a | |
148 | few exceptions. Even though... | |
149 | ||
150 | - 'git-add' itself does not touch the files in the work tree, the | |
151 | next checkout would, so the safety triggers; | |
152 | ||
153 | - 'git-apply' to update a text file with a patch does touch the files | |
154 | in the work tree, but the operation is about text files and CRLF | |
155 | conversion is about fixing the line ending inconsistencies, so the | |
156 | safety does not trigger; | |
157 | ||
158 | - 'git-diff' itself does not touch the files in the work tree, it is | |
159 | often run to inspect the changes you intend to next 'git-add'. To | |
160 | catch potential problems early, safety triggers. | |
161 | ||
162 | ||
163 | `ident` | |
164 | ^^^^^^^ | |
165 | ||
166 | When the attribute `ident` is set for a path, git replaces | |
167 | `$Id$` in the blob object with `$Id:`, followed by the | |
168 | 40-character hexadecimal blob object name, followed by a dollar | |
169 | sign `$` upon checkout. Any byte sequence that begins with | |
170 | `$Id:` and ends with `$` in the worktree file is replaced | |
171 | with `$Id$` upon check-in. | |
172 | ||
173 | ||
174 | `filter` | |
175 | ^^^^^^^^ | |
176 | ||
177 | A `filter` attribute can be set to a string value that names a | |
178 | filter driver specified in the configuration. | |
179 | ||
180 | A filter driver consists of a `clean` command and a `smudge` | |
181 | command, either of which can be left unspecified. Upon | |
182 | checkout, when the `smudge` command is specified, the command is | |
183 | fed the blob object from its standard input, and its standard | |
184 | output is used to update the worktree file. Similarly, the | |
185 | `clean` command is used to convert the contents of worktree file | |
186 | upon checkin. | |
187 | ||
188 | A missing filter driver definition in the config is not an error | |
189 | but makes the filter a no-op passthru. | |
190 | ||
191 | The content filtering is done to massage the content into a | |
192 | shape that is more convenient for the platform, filesystem, and | |
193 | the user to use. The key phrase here is "more convenient" and not | |
194 | "turning something unusable into usable". In other words, the | |
195 | intent is that if someone unsets the filter driver definition, | |
196 | or does not have the appropriate filter program, the project | |
197 | should still be usable. | |
198 | ||
199 | ||
200 | Interaction between checkin/checkout attributes | |
201 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
202 | ||
203 | In the check-in codepath, the worktree file is first converted | |
204 | with `filter` driver (if specified and corresponding driver | |
205 | defined), then the result is processed with `ident` (if | |
206 | specified), and then finally with `crlf` (again, if specified | |
207 | and applicable). | |
208 | ||
209 | In the check-out codepath, the blob content is first converted | |
210 | with `crlf`, and then `ident` and fed to `filter`. | |
211 | ||
212 | ||
213 | Generating diff text | |
214 | ~~~~~~~~~~~~~~~~~~~~ | |
215 | ||
216 | `diff` | |
217 | ^^^^^^ | |
218 | ||
219 | The attribute `diff` affects if 'git-diff' generates textual | |
220 | patch for the path or just says `Binary files differ`. It also | |
221 | can affect what line is shown on the hunk header `@@ -k,l +n,m @@` | |
222 | line. | |
223 | ||
224 | Set:: | |
225 | ||
226 | A path to which the `diff` attribute is set is treated | |
227 | as text, even when they contain byte values that | |
228 | normally never appear in text files, such as NUL. | |
229 | ||
230 | Unset:: | |
231 | ||
232 | A path to which the `diff` attribute is unset will | |
233 | generate `Binary files differ`. | |
234 | ||
235 | Unspecified:: | |
236 | ||
237 | A path to which the `diff` attribute is unspecified | |
238 | first gets its contents inspected, and if it looks like | |
239 | text, it is treated as text. Otherwise it would | |
240 | generate `Binary files differ`. | |
241 | ||
242 | String:: | |
243 | ||
244 | Diff is shown using the specified custom diff driver. | |
245 | The driver program is given its input using the same | |
246 | calling convention as used for GIT_EXTERNAL_DIFF | |
247 | program. This name is also used for custom hunk header | |
248 | selection. | |
249 | ||
250 | ||
251 | Defining a custom diff driver | |
252 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
253 | ||
254 | The definition of a diff driver is done in `gitconfig`, not | |
255 | `gitattributes` file, so strictly speaking this manual page is a | |
256 | wrong place to talk about it. However... | |
257 | ||
258 | To define a custom diff driver `jcdiff`, add a section to your | |
259 | `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: | |
260 | ||
261 | ---------------------------------------------------------------- | |
262 | [diff "jcdiff"] | |
263 | command = j-c-diff | |
264 | ---------------------------------------------------------------- | |
265 | ||
266 | When git needs to show you a diff for the path with `diff` | |
267 | attribute set to `jcdiff`, it calls the command you specified | |
268 | with the above configuration, i.e. `j-c-diff`, with 7 | |
269 | parameters, just like `GIT_EXTERNAL_DIFF` program is called. | |
270 | See linkgit:git[1] for details. | |
271 | ||
272 | ||
273 | Defining a custom hunk-header | |
274 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
275 | ||
276 | Each group of changes (called a "hunk") in the textual diff output | |
277 | is prefixed with a line of the form: | |
278 | ||
279 | @@ -k,l +n,m @@ TEXT | |
280 | ||
281 | This is called a 'hunk header'. The "TEXT" portion is by default a line | |
282 | that begins with an alphabet, an underscore or a dollar sign; this | |
283 | matches what GNU 'diff -p' output uses. This default selection however | |
284 | is not suited for some contents, and you can use a customized pattern | |
285 | to make a selection. | |
286 | ||
287 | First, in .gitattributes, you would assign the `diff` attribute | |
288 | for paths. | |
289 | ||
290 | ------------------------ | |
291 | *.tex diff=tex | |
292 | ------------------------ | |
293 | ||
294 | Then, you would define a "diff.tex.xfuncname" configuration to | |
295 | specify a regular expression that matches a line that you would | |
296 | want to appear as the hunk header "TEXT", like this: | |
297 | ||
298 | ------------------------ | |
299 | [diff "tex"] | |
300 | xfuncname = "^(\\\\(sub)*section\\{.*)$" | |
301 | ------------------------ | |
302 | ||
303 | Note. A single level of backslashes are eaten by the | |
304 | configuration file parser, so you would need to double the | |
305 | backslashes; the pattern above picks a line that begins with a | |
306 | backslash, and zero or more occurrences of `sub` followed by | |
307 | `section` followed by open brace, to the end of line. | |
308 | ||
309 | There are a few built-in patterns to make this easier, and `tex` | |
310 | is one of them, so you do not have to write the above in your | |
311 | configuration file (you still need to enable this with the | |
312 | attribute mechanism, via `.gitattributes`). The following built in | |
313 | patterns are available: | |
314 | ||
315 | - `bibtex` suitable for files with BibTeX coded references. | |
316 | ||
317 | - `java` suitable for source code in the Java language. | |
318 | ||
319 | - `pascal` suitable for source code in the Pascal/Delphi language. | |
320 | ||
321 | - `ruby` suitable for source code in the Ruby language. | |
322 | ||
323 | - `tex` suitable for source code for LaTeX documents. | |
324 | ||
325 | ||
326 | Performing a three-way merge | |
327 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
328 | ||
329 | `merge` | |
330 | ^^^^^^^ | |
331 | ||
332 | The attribute `merge` affects how three versions of a file is | |
333 | merged when a file-level merge is necessary during `git merge`, | |
334 | and other programs such as `git revert` and `git cherry-pick`. | |
335 | ||
336 | Set:: | |
337 | ||
338 | Built-in 3-way merge driver is used to merge the | |
339 | contents in a way similar to 'merge' command of `RCS` | |
340 | suite. This is suitable for ordinary text files. | |
341 | ||
342 | Unset:: | |
343 | ||
344 | Take the version from the current branch as the | |
345 | tentative merge result, and declare that the merge has | |
346 | conflicts. This is suitable for binary files that does | |
347 | not have a well-defined merge semantics. | |
348 | ||
349 | Unspecified:: | |
350 | ||
351 | By default, this uses the same built-in 3-way merge | |
352 | driver as is the case the `merge` attribute is set. | |
353 | However, `merge.default` configuration variable can name | |
354 | different merge driver to be used for paths to which the | |
355 | `merge` attribute is unspecified. | |
356 | ||
357 | String:: | |
358 | ||
359 | 3-way merge is performed using the specified custom | |
360 | merge driver. The built-in 3-way merge driver can be | |
361 | explicitly specified by asking for "text" driver; the | |
362 | built-in "take the current branch" driver can be | |
363 | requested with "binary". | |
364 | ||
365 | ||
366 | Built-in merge drivers | |
367 | ^^^^^^^^^^^^^^^^^^^^^^ | |
368 | ||
369 | There are a few built-in low-level merge drivers defined that | |
370 | can be asked for via the `merge` attribute. | |
371 | ||
372 | text:: | |
373 | ||
374 | Usual 3-way file level merge for text files. Conflicted | |
375 | regions are marked with conflict markers `<<<<<<<`, | |
376 | `=======` and `>>>>>>>`. The version from your branch | |
377 | appears before the `=======` marker, and the version | |
378 | from the merged branch appears after the `=======` | |
379 | marker. | |
380 | ||
381 | binary:: | |
382 | ||
383 | Keep the version from your branch in the work tree, but | |
384 | leave the path in the conflicted state for the user to | |
385 | sort out. | |
386 | ||
387 | union:: | |
388 | ||
389 | Run 3-way file level merge for text files, but take | |
390 | lines from both versions, instead of leaving conflict | |
391 | markers. This tends to leave the added lines in the | |
392 | resulting file in random order and the user should | |
393 | verify the result. Do not use this if you do not | |
394 | understand the implications. | |
395 | ||
396 | ||
397 | Defining a custom merge driver | |
398 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
399 | ||
400 | The definition of a merge driver is done in the `.git/config` | |
401 | file, not in the `gitattributes` file, so strictly speaking this | |
402 | manual page is a wrong place to talk about it. However... | |
403 | ||
404 | To define a custom merge driver `filfre`, add a section to your | |
405 | `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: | |
406 | ||
407 | ---------------------------------------------------------------- | |
408 | [merge "filfre"] | |
409 | name = feel-free merge driver | |
410 | driver = filfre %O %A %B | |
411 | recursive = binary | |
412 | ---------------------------------------------------------------- | |
413 | ||
414 | The `merge.*.name` variable gives the driver a human-readable | |
415 | name. | |
416 | ||
417 | The `merge.*.driver` variable's value is used to construct a | |
418 | command to run to merge ancestor's version (`%O`), current | |
419 | version (`%A`) and the other branches' version (`%B`). These | |
420 | three tokens are replaced with the names of temporary files that | |
421 | hold the contents of these versions when the command line is | |
422 | built. | |
423 | ||
424 | The merge driver is expected to leave the result of the merge in | |
425 | the file named with `%A` by overwriting it, and exit with zero | |
426 | status if it managed to merge them cleanly, or non-zero if there | |
427 | were conflicts. | |
428 | ||
429 | The `merge.*.recursive` variable specifies what other merge | |
430 | driver to use when the merge driver is called for an internal | |
431 | merge between common ancestors, when there are more than one. | |
432 | When left unspecified, the driver itself is used for both | |
433 | internal merge and the final merge. | |
434 | ||
435 | ||
436 | Checking whitespace errors | |
437 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
438 | ||
439 | `whitespace` | |
440 | ^^^^^^^^^^^^ | |
441 | ||
442 | The `core.whitespace` configuration variable allows you to define what | |
443 | 'diff' and 'apply' should consider whitespace errors for all paths in | |
444 | the project (See linkgit:git-config[1]). This attribute gives you finer | |
445 | control per path. | |
446 | ||
447 | Set:: | |
448 | ||
449 | Notice all types of potential whitespace errors known to git. | |
450 | ||
451 | Unset:: | |
452 | ||
453 | Do not notice anything as error. | |
454 | ||
455 | Unspecified:: | |
456 | ||
457 | Use the value of `core.whitespace` configuration variable to | |
458 | decide what to notice as error. | |
459 | ||
460 | String:: | |
461 | ||
462 | Specify a comma separate list of common whitespace problems to | |
463 | notice in the same format as `core.whitespace` configuration | |
464 | variable. | |
465 | ||
466 | ||
467 | Creating an archive | |
468 | ~~~~~~~~~~~~~~~~~~~ | |
469 | ||
470 | `export-ignore` | |
471 | ^^^^^^^^^^^^^^^ | |
472 | ||
473 | Files and directories with the attribute `export-ignore` won't be added to | |
474 | archive files. | |
475 | ||
476 | `export-subst` | |
477 | ^^^^^^^^^^^^^^ | |
478 | ||
479 | If the attribute `export-subst` is set for a file then git will expand | |
480 | several placeholders when adding this file to an archive. The | |
481 | expansion depends on the availability of a commit ID, i.e., if | |
482 | linkgit:git-archive[1] has been given a tree instead of a commit or a | |
483 | tag then no replacement will be done. The placeholders are the same | |
484 | as those for the option `--pretty=format:` of linkgit:git-log[1], | |
485 | except that they need to be wrapped like this: `$Format:PLACEHOLDERS$` | |
486 | in the file. E.g. the string `$Format:%H$` will be replaced by the | |
487 | commit hash. | |
488 | ||
489 | ||
490 | USING ATTRIBUTE MACROS | |
491 | ---------------------- | |
492 | ||
493 | You do not want any end-of-line conversions applied to, nor textual diffs | |
494 | produced for, any binary file you track. You would need to specify e.g. | |
495 | ||
496 | ------------ | |
497 | *.jpg -crlf -diff | |
498 | ------------ | |
499 | ||
500 | but that may become cumbersome, when you have many attributes. Using | |
501 | attribute macros, you can specify groups of attributes set or unset at | |
502 | the same time. The system knows a built-in attribute macro, `binary`: | |
503 | ||
504 | ------------ | |
505 | *.jpg binary | |
506 | ------------ | |
507 | ||
508 | which is equivalent to the above. Note that the attribute macros can only | |
509 | be "Set" (see the above example that sets "binary" macro as if it were an | |
510 | ordinary attribute --- setting it in turn unsets "crlf" and "diff"). | |
511 | ||
512 | ||
513 | DEFINING ATTRIBUTE MACROS | |
514 | ------------------------- | |
515 | ||
516 | Custom attribute macros can be defined only in the `.gitattributes` file | |
517 | at the toplevel (i.e. not in any subdirectory). The built-in attribute | |
518 | macro "binary" is equivalent to: | |
519 | ||
520 | ------------ | |
521 | [attr]binary -diff -crlf | |
522 | ------------ | |
523 | ||
524 | ||
525 | EXAMPLE | |
526 | ------- | |
527 | ||
528 | If you have these three `gitattributes` file: | |
529 | ||
530 | ---------------------------------------------------------------- | |
531 | (in $GIT_DIR/info/attributes) | |
532 | ||
533 | a* foo !bar -baz | |
534 | ||
535 | (in .gitattributes) | |
536 | abc foo bar baz | |
537 | ||
538 | (in t/.gitattributes) | |
539 | ab* merge=filfre | |
540 | abc -foo -bar | |
541 | *.c frotz | |
542 | ---------------------------------------------------------------- | |
543 | ||
544 | the attributes given to path `t/abc` are computed as follows: | |
545 | ||
546 | 1. By examining `t/.gitattributes` (which is in the same | |
547 | directory as the path in question), git finds that the first | |
548 | line matches. `merge` attribute is set. It also finds that | |
549 | the second line matches, and attributes `foo` and `bar` | |
550 | are unset. | |
551 | ||
552 | 2. Then it examines `.gitattributes` (which is in the parent | |
553 | directory), and finds that the first line matches, but | |
554 | `t/.gitattributes` file already decided how `merge`, `foo` | |
555 | and `bar` attributes should be given to this path, so it | |
556 | leaves `foo` and `bar` unset. Attribute `baz` is set. | |
557 | ||
558 | 3. Finally it examines `$GIT_DIR/info/attributes`. This file | |
559 | is used to override the in-tree settings. The first line is | |
560 | a match, and `foo` is set, `bar` is reverted to unspecified | |
561 | state, and `baz` is unset. | |
562 | ||
563 | As the result, the attributes assignment to `t/abc` becomes: | |
564 | ||
565 | ---------------------------------------------------------------- | |
566 | foo set to true | |
567 | bar unspecified | |
568 | baz set to false | |
569 | merge set to string value "filfre" | |
570 | frotz unspecified | |
571 | ---------------------------------------------------------------- | |
572 | ||
573 | ||
574 | ||
575 | GIT | |
576 | --- | |
577 | Part of the linkgit:git[1] suite |