]>
Commit | Line | Data |
---|---|---|
88e7fdf2 JH |
1 | gitattributes(5) |
2 | ================ | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | gitattributes - defining attributes per path | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
e5b5c1d2 | 10 | $GIT_DIR/info/attributes, .gitattributes |
88e7fdf2 JH |
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 | ||
3f74c8e8 | 21 | pattern attr1 attr2 ... |
88e7fdf2 | 22 | |
3f74c8e8 JS |
23 | That is, a pattern followed by an attributes list, |
24 | separated by whitespaces. When the pattern matches the | |
88e7fdf2 JH |
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 | ||
3f74c8e8 | 51 | No 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 | 54 | |
3f74c8e8 | 55 | When more than one pattern matches the path, a later line |
b9d14ffb | 56 | overrides an earlier line. This overriding is done per |
3f74c8e8 JS |
57 | attribute. The rules how the pattern matches paths are the |
58 | same as in `.gitignore` files; see linkgit:gitignore[5]. | |
88e7fdf2 JH |
59 | |
60 | When deciding what attributes are assigned to a path, git | |
61 | consults `$GIT_DIR/info/attributes` file (which has the highest | |
62 | precedence), `.gitattributes` file in the same directory as the | |
20ff3ec2 JM |
63 | path in question, and its parent directories up to the toplevel of the |
64 | work tree (the further the directory that contains `.gitattributes` | |
65 | is from the path in question, the lower its precedence). | |
88e7fdf2 | 66 | |
90b22907 JK |
67 | If you wish to affect only a single repository (i.e., to assign |
68 | attributes to files that are particular to one user's workflow), then | |
69 | attributes should be placed in the `$GIT_DIR/info/attributes` file. | |
70 | Attributes which should be version-controlled and distributed to other | |
71 | repositories (i.e., attributes of interest to all users) should go into | |
72 | `.gitattributes` files. | |
73 | ||
88e7fdf2 JH |
74 | Sometimes you would need to override an setting of an attribute |
75 | for a path to `unspecified` state. This can be done by listing | |
76 | the name of the attribute prefixed with an exclamation point `!`. | |
77 | ||
78 | ||
79 | EFFECTS | |
80 | ------- | |
81 | ||
82 | Certain operations by git can be influenced by assigning | |
ae7aa499 JH |
83 | particular attributes to a path. Currently, the following |
84 | operations are attributes-aware. | |
88e7fdf2 JH |
85 | |
86 | Checking-out and checking-in | |
87 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
88 | ||
3fed15f5 | 89 | These attributes affect how the contents stored in the |
88e7fdf2 | 90 | repository are copied to the working tree files when commands |
0b444cdb | 91 | such as 'git checkout' and 'git merge' run. They also affect how |
88e7fdf2 | 92 | git stores the contents you prepare in the working tree in the |
0b444cdb | 93 | repository upon 'git add' and 'git commit'. |
88e7fdf2 | 94 | |
3fed15f5 JH |
95 | `crlf` |
96 | ^^^^^^ | |
97 | ||
98 | This attribute controls the line-ending convention. | |
99 | ||
88e7fdf2 JH |
100 | Set:: |
101 | ||
102 | Setting the `crlf` attribute on a path is meant to mark | |
103 | the path as a "text" file. 'core.autocrlf' conversion | |
104 | takes place without guessing the content type by | |
105 | inspection. | |
106 | ||
107 | Unset:: | |
108 | ||
bbb896d8 JH |
109 | Unsetting the `crlf` attribute on a path tells git not to |
110 | attempt any end-of-line conversion upon checkin or checkout. | |
88e7fdf2 JH |
111 | |
112 | Unspecified:: | |
113 | ||
114 | Unspecified `crlf` attribute tells git to apply the | |
115 | `core.autocrlf` conversion when the file content looks | |
116 | like text. | |
117 | ||
118 | Set 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 | ||
124 | Any other value set to `crlf` attribute is ignored and git acts | |
125 | as if the attribute is left unspecified. | |
126 | ||
127 | ||
128 | The `core.autocrlf` conversion | |
129 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
130 | ||
131 | If the configuration variable `core.autocrlf` is false, no | |
132 | conversion is done. | |
133 | ||
134 | When `core.autocrlf` is true, it means that the platform wants | |
135 | CRLF line endings for files in the working tree, and you want to | |
136 | convert them back to the normal LF line endings when checking | |
137 | in to the repository. | |
138 | ||
139 | When `core.autocrlf` is set to "input", line endings are | |
140 | converted to LF upon checkin, but there is no conversion done | |
141 | upon checkout. | |
142 | ||
21e5ad50 SP |
143 | If `core.safecrlf` is set to "true" or "warn", git verifies if |
144 | the conversion is reversible for the current setting of | |
145 | `core.autocrlf`. For "true", git rejects irreversible | |
146 | conversions; for "warn", git only prints a warning but accepts | |
147 | an irreversible conversion. The safety triggers to prevent such | |
148 | a conversion done to the files in the work tree, but there are a | |
149 | few exceptions. Even though... | |
150 | ||
0b444cdb | 151 | - 'git add' itself does not touch the files in the work tree, the |
21e5ad50 SP |
152 | next checkout would, so the safety triggers; |
153 | ||
0b444cdb | 154 | - 'git apply' to update a text file with a patch does touch the files |
21e5ad50 SP |
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 | ||
0b444cdb TR |
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 | |
21e5ad50 SP |
161 | catch potential problems early, safety triggers. |
162 | ||
88e7fdf2 | 163 | |
3fed15f5 JH |
164 | `ident` |
165 | ^^^^^^^ | |
166 | ||
2c850f12 JK |
167 | When the attribute `ident` is set for a path, git replaces |
168 | `$Id$` in the blob object with `$Id:`, followed by the | |
3fed15f5 JH |
169 | 40-character hexadecimal blob object name, followed by a dollar |
170 | sign `$` upon checkout. Any byte sequence that begins with | |
af9b54bb AP |
171 | `$Id:` and ends with `$` in the worktree file is replaced |
172 | with `$Id$` upon check-in. | |
3fed15f5 JH |
173 | |
174 | ||
aa4ed402 JH |
175 | `filter` |
176 | ^^^^^^^^ | |
177 | ||
c05ef938 | 178 | A `filter` attribute can be set to a string value that names a |
aa4ed402 JH |
179 | filter driver specified in the configuration. |
180 | ||
c05ef938 | 181 | A filter driver consists of a `clean` command and a `smudge` |
aa4ed402 | 182 | command, either of which can be left unspecified. Upon |
c05ef938 WC |
183 | checkout, when the `smudge` command is specified, the command is |
184 | fed the blob object from its standard input, and its standard | |
185 | output is used to update the worktree file. Similarly, the | |
186 | `clean` command is used to convert the contents of worktree file | |
187 | upon checkin. | |
aa4ed402 | 188 | |
c05ef938 | 189 | A missing filter driver definition in the config is not an error |
aa4ed402 JH |
190 | but makes the filter a no-op passthru. |
191 | ||
192 | The content filtering is done to massage the content into a | |
193 | shape that is more convenient for the platform, filesystem, and | |
c05ef938 | 194 | the user to use. The key phrase here is "more convenient" and not |
4d84aff3 JS |
195 | "turning something unusable into usable". In other words, the |
196 | intent is that if someone unsets the filter driver definition, | |
197 | or does not have the appropriate filter program, the project | |
198 | should still be usable. | |
aa4ed402 | 199 | |
d79f5d17 NS |
200 | For example, in .gitattributes, you would assign the `filter` |
201 | attribute for paths. | |
202 | ||
203 | ------------------------ | |
204 | *.c filter=indent | |
205 | ------------------------ | |
206 | ||
207 | Then you would define a "filter.indent.clean" and "filter.indent.smudge" | |
208 | configuration in your .git/config to specify a pair of commands to | |
209 | modify the contents of C programs when the source files are checked | |
210 | in ("clean" is run) and checked out (no change is made because the | |
211 | command is "cat"). | |
212 | ||
213 | ------------------------ | |
214 | [filter "indent"] | |
215 | clean = indent | |
216 | smudge = cat | |
217 | ------------------------ | |
218 | ||
aa4ed402 JH |
219 | |
220 | Interaction between checkin/checkout attributes | |
221 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
222 | ||
223 | In the check-in codepath, the worktree file is first converted | |
224 | with `filter` driver (if specified and corresponding driver | |
225 | defined), then the result is processed with `ident` (if | |
226 | specified), and then finally with `crlf` (again, if specified | |
227 | and applicable). | |
228 | ||
229 | In the check-out codepath, the blob content is first converted | |
230 | with `crlf`, and then `ident` and fed to `filter`. | |
231 | ||
232 | ||
88e7fdf2 JH |
233 | Generating diff text |
234 | ~~~~~~~~~~~~~~~~~~~~ | |
235 | ||
4f73e240 JN |
236 | `diff` |
237 | ^^^^^^ | |
238 | ||
678852d9 JK |
239 | The attribute `diff` affects how 'git' generates diffs for particular |
240 | files. It can tell git whether to generate a textual patch for the path | |
241 | or to treat the path as a binary file. It can also affect what line is | |
242 | shown on the hunk header `@@ -k,l +n,m @@` line, tell git to use an | |
243 | external command to generate the diff, or ask git to convert binary | |
244 | files to a text format before generating the diff. | |
88e7fdf2 JH |
245 | |
246 | Set:: | |
247 | ||
248 | A path to which the `diff` attribute is set is treated | |
249 | as text, even when they contain byte values that | |
250 | normally never appear in text files, such as NUL. | |
251 | ||
252 | Unset:: | |
253 | ||
254 | A path to which the `diff` attribute is unset will | |
678852d9 JK |
255 | generate `Binary files differ` (or a binary patch, if |
256 | binary patches are enabled). | |
88e7fdf2 JH |
257 | |
258 | Unspecified:: | |
259 | ||
260 | A path to which the `diff` attribute is unspecified | |
261 | first gets its contents inspected, and if it looks like | |
262 | text, it is treated as text. Otherwise it would | |
263 | generate `Binary files differ`. | |
264 | ||
2cc3167c JH |
265 | String:: |
266 | ||
678852d9 JK |
267 | Diff is shown using the specified diff driver. Each driver may |
268 | specify one or more options, as described in the following | |
269 | section. The options for the diff driver "foo" are defined | |
270 | by the configuration variables in the "diff.foo" section of the | |
271 | git config file. | |
2cc3167c JH |
272 | |
273 | ||
678852d9 JK |
274 | Defining an external diff driver |
275 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
2cc3167c JH |
276 | |
277 | The definition of a diff driver is done in `gitconfig`, not | |
278 | `gitattributes` file, so strictly speaking this manual page is a | |
279 | wrong place to talk about it. However... | |
280 | ||
678852d9 | 281 | To define an external diff driver `jcdiff`, add a section to your |
2cc3167c JH |
282 | `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: |
283 | ||
284 | ---------------------------------------------------------------- | |
285 | [diff "jcdiff"] | |
286 | command = j-c-diff | |
287 | ---------------------------------------------------------------- | |
288 | ||
289 | When git needs to show you a diff for the path with `diff` | |
290 | attribute set to `jcdiff`, it calls the command you specified | |
291 | with the above configuration, i.e. `j-c-diff`, with 7 | |
292 | parameters, just like `GIT_EXTERNAL_DIFF` program is called. | |
9e1f0a85 | 293 | See linkgit:git[1] for details. |
88e7fdf2 JH |
294 | |
295 | ||
ae7aa499 JH |
296 | Defining a custom hunk-header |
297 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
298 | ||
c882c01e | 299 | Each group of changes (called a "hunk") in the textual diff output |
ae7aa499 JH |
300 | is prefixed with a line of the form: |
301 | ||
302 | @@ -k,l +n,m @@ TEXT | |
303 | ||
c882c01e GD |
304 | This is called a 'hunk header'. The "TEXT" portion is by default a line |
305 | that begins with an alphabet, an underscore or a dollar sign; this | |
306 | matches what GNU 'diff -p' output uses. This default selection however | |
307 | is not suited for some contents, and you can use a customized pattern | |
308 | to make a selection. | |
ae7aa499 | 309 | |
c882c01e | 310 | First, in .gitattributes, you would assign the `diff` attribute |
ae7aa499 JH |
311 | for paths. |
312 | ||
313 | ------------------------ | |
314 | *.tex diff=tex | |
315 | ------------------------ | |
316 | ||
edb7e82f | 317 | Then, you would define a "diff.tex.xfuncname" configuration to |
ae7aa499 | 318 | specify a regular expression that matches a line that you would |
c4c86d23 JK |
319 | want to appear as the hunk header "TEXT". Add a section to your |
320 | `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: | |
ae7aa499 JH |
321 | |
322 | ------------------------ | |
323 | [diff "tex"] | |
45d9414f | 324 | xfuncname = "^(\\\\(sub)*section\\{.*)$" |
ae7aa499 JH |
325 | ------------------------ |
326 | ||
327 | Note. A single level of backslashes are eaten by the | |
328 | configuration file parser, so you would need to double the | |
329 | backslashes; the pattern above picks a line that begins with a | |
02783075 | 330 | backslash, and zero or more occurrences of `sub` followed by |
ae7aa499 JH |
331 | `section` followed by open brace, to the end of line. |
332 | ||
333 | There are a few built-in patterns to make this easier, and `tex` | |
334 | is one of them, so you do not have to write the above in your | |
335 | configuration file (you still need to enable this with the | |
d08ed6d6 GH |
336 | attribute mechanism, via `.gitattributes`). The following built in |
337 | patterns are available: | |
338 | ||
23b5beb2 GH |
339 | - `bibtex` suitable for files with BibTeX coded references. |
340 | ||
80c49c3d TR |
341 | - `cpp` suitable for source code in the C and C++ languages. |
342 | ||
af9ce1ff AE |
343 | - `html` suitable for HTML/XHTML documents. |
344 | ||
b66e00f1 | 345 | - `java` suitable for source code in the Java language. |
d08ed6d6 | 346 | |
5d1e958e JS |
347 | - `objc` suitable for source code in the Objective-C language. |
348 | ||
d08ed6d6 GH |
349 | - `pascal` suitable for source code in the Pascal/Delphi language. |
350 | ||
af9ce1ff AE |
351 | - `php` suitable for source code in the PHP language. |
352 | ||
7c17205b KS |
353 | - `python` suitable for source code in the Python language. |
354 | ||
d08ed6d6 GH |
355 | - `ruby` suitable for source code in the Ruby language. |
356 | ||
357 | - `tex` suitable for source code for LaTeX documents. | |
ae7aa499 JH |
358 | |
359 | ||
80c49c3d TR |
360 | Customizing word diff |
361 | ^^^^^^^^^^^^^^^^^^^^^ | |
362 | ||
363 | You can customize the rules that `git diff --color-words` uses to | |
364 | split words in a line, by specifying an appropriate regular expression | |
ae3b970a | 365 | in the "diff.*.wordRegex" configuration variable. For example, in TeX |
80c49c3d TR |
366 | a backslash followed by a sequence of letters forms a command, but |
367 | several such commands can be run together without intervening | |
c4c86d23 JK |
368 | whitespace. To separate them, use a regular expression in your |
369 | `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: | |
80c49c3d TR |
370 | |
371 | ------------------------ | |
372 | [diff "tex"] | |
ae3b970a | 373 | wordRegex = "\\\\[a-zA-Z]+|[{}]|\\\\.|[^\\{}[:space:]]+" |
80c49c3d TR |
374 | ------------------------ |
375 | ||
376 | A built-in pattern is provided for all languages listed in the | |
377 | previous section. | |
378 | ||
379 | ||
678852d9 JK |
380 | Performing text diffs of binary files |
381 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
382 | ||
383 | Sometimes it is desirable to see the diff of a text-converted | |
384 | version of some binary files. For example, a word processor | |
385 | document can be converted to an ASCII text representation, and | |
386 | the diff of the text shown. Even though this conversion loses | |
387 | some information, the resulting diff is useful for human | |
388 | viewing (but cannot be applied directly). | |
389 | ||
390 | The `textconv` config option is used to define a program for | |
391 | performing such a conversion. The program should take a single | |
392 | argument, the name of a file to convert, and produce the | |
393 | resulting text on stdout. | |
394 | ||
395 | For example, to show the diff of the exif information of a | |
396 | file instead of the binary information (assuming you have the | |
c4c86d23 JK |
397 | exif tool installed), add the following section to your |
398 | `$GIT_DIR/config` file (or `$HOME/.gitconfig` file): | |
678852d9 JK |
399 | |
400 | ------------------------ | |
401 | [diff "jpg"] | |
402 | textconv = exif | |
403 | ------------------------ | |
404 | ||
405 | NOTE: The text conversion is generally a one-way conversion; | |
406 | in this example, we lose the actual image contents and focus | |
407 | just on the text data. This means that diffs generated by | |
408 | textconv are _not_ suitable for applying. For this reason, | |
409 | only `git diff` and the `git log` family of commands (i.e., | |
410 | log, whatchanged, show) will perform text conversion. `git | |
411 | format-patch` will never generate this output. If you want to | |
412 | send somebody a text-converted diff of a binary file (e.g., | |
413 | because it quickly conveys the changes you have made), you | |
414 | should generate it separately and send it as a comment _in | |
415 | addition to_ the usual binary diff that you might send. | |
416 | ||
417 | ||
88e7fdf2 JH |
418 | Performing a three-way merge |
419 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
420 | ||
4f73e240 JN |
421 | `merge` |
422 | ^^^^^^^ | |
423 | ||
88e7fdf2 JH |
424 | The attribute `merge` affects how three versions of a file is |
425 | merged when a file-level merge is necessary during `git merge`, | |
57f6ec02 | 426 | and other commands such as `git revert` and `git cherry-pick`. |
88e7fdf2 JH |
427 | |
428 | Set:: | |
429 | ||
430 | Built-in 3-way merge driver is used to merge the | |
2fd02c92 | 431 | contents in a way similar to 'merge' command of `RCS` |
88e7fdf2 JH |
432 | suite. This is suitable for ordinary text files. |
433 | ||
434 | Unset:: | |
435 | ||
436 | Take the version from the current branch as the | |
437 | tentative merge result, and declare that the merge has | |
438 | conflicts. This is suitable for binary files that does | |
439 | not have a well-defined merge semantics. | |
440 | ||
441 | Unspecified:: | |
442 | ||
443 | By default, this uses the same built-in 3-way merge | |
444 | driver as is the case the `merge` attribute is set. | |
445 | However, `merge.default` configuration variable can name | |
446 | different merge driver to be used for paths to which the | |
447 | `merge` attribute is unspecified. | |
448 | ||
2cc3167c | 449 | String:: |
88e7fdf2 JH |
450 | |
451 | 3-way merge is performed using the specified custom | |
452 | merge driver. The built-in 3-way merge driver can be | |
453 | explicitly specified by asking for "text" driver; the | |
454 | built-in "take the current branch" driver can be | |
b9d14ffb | 455 | requested with "binary". |
88e7fdf2 JH |
456 | |
457 | ||
0e545f75 JH |
458 | Built-in merge drivers |
459 | ^^^^^^^^^^^^^^^^^^^^^^ | |
460 | ||
461 | There are a few built-in low-level merge drivers defined that | |
462 | can be asked for via the `merge` attribute. | |
463 | ||
464 | text:: | |
465 | ||
466 | Usual 3-way file level merge for text files. Conflicted | |
467 | regions are marked with conflict markers `<<<<<<<`, | |
468 | `=======` and `>>>>>>>`. The version from your branch | |
469 | appears before the `=======` marker, and the version | |
470 | from the merged branch appears after the `=======` | |
471 | marker. | |
472 | ||
473 | binary:: | |
474 | ||
475 | Keep the version from your branch in the work tree, but | |
476 | leave the path in the conflicted state for the user to | |
477 | sort out. | |
478 | ||
479 | union:: | |
480 | ||
481 | Run 3-way file level merge for text files, but take | |
482 | lines from both versions, instead of leaving conflict | |
483 | markers. This tends to leave the added lines in the | |
484 | resulting file in random order and the user should | |
485 | verify the result. Do not use this if you do not | |
486 | understand the implications. | |
487 | ||
488 | ||
88e7fdf2 JH |
489 | Defining a custom merge driver |
490 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
491 | ||
0e545f75 JH |
492 | The definition of a merge driver is done in the `.git/config` |
493 | file, not in the `gitattributes` file, so strictly speaking this | |
494 | manual page is a wrong place to talk about it. However... | |
88e7fdf2 JH |
495 | |
496 | To define a custom merge driver `filfre`, add a section to your | |
497 | `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: | |
498 | ||
499 | ---------------------------------------------------------------- | |
500 | [merge "filfre"] | |
501 | name = feel-free merge driver | |
502 | driver = filfre %O %A %B | |
503 | recursive = binary | |
504 | ---------------------------------------------------------------- | |
505 | ||
506 | The `merge.*.name` variable gives the driver a human-readable | |
507 | name. | |
508 | ||
509 | The `merge.*.driver` variable's value is used to construct a | |
510 | command to run to merge ancestor's version (`%O`), current | |
511 | version (`%A`) and the other branches' version (`%B`). These | |
512 | three tokens are replaced with the names of temporary files that | |
513 | hold the contents of these versions when the command line is | |
514 | built. | |
515 | ||
516 | The merge driver is expected to leave the result of the merge in | |
517 | the file named with `%A` by overwriting it, and exit with zero | |
518 | status if it managed to merge them cleanly, or non-zero if there | |
519 | were conflicts. | |
520 | ||
521 | The `merge.*.recursive` variable specifies what other merge | |
522 | driver to use when the merge driver is called for an internal | |
523 | merge between common ancestors, when there are more than one. | |
524 | When left unspecified, the driver itself is used for both | |
525 | internal merge and the final merge. | |
526 | ||
527 | ||
4c734803 JH |
528 | `conflict-marker-size` |
529 | ^^^^^^^^^^^^^^^^^^^^^^ | |
530 | ||
531 | This attribute controls the length of conflict markers left in | |
532 | the work tree file during a conflicted merge. Only setting to | |
533 | the value to a positive integer has any meaningful effect. | |
534 | ||
535 | For example, this line in `.gitattributes` can be used to tell the merge | |
536 | machinery to leave much longer (instead of the usual 7-character-long) | |
537 | conflict markers when merging the file `Documentation/git-merge.txt` | |
538 | results in a conflict. | |
539 | ||
540 | ------------------------ | |
541 | Documentation/git-merge.txt conflict-marker-size=32 | |
542 | ------------------------ | |
543 | ||
544 | ||
cf1b7869 JH |
545 | Checking whitespace errors |
546 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
547 | ||
548 | `whitespace` | |
549 | ^^^^^^^^^^^^ | |
550 | ||
551 | The `core.whitespace` configuration variable allows you to define what | |
2fd02c92 | 552 | 'diff' and 'apply' should consider whitespace errors for all paths in |
5162e697 | 553 | the project (See linkgit:git-config[1]). This attribute gives you finer |
cf1b7869 JH |
554 | control per path. |
555 | ||
556 | Set:: | |
557 | ||
558 | Notice all types of potential whitespace errors known to git. | |
559 | ||
560 | Unset:: | |
561 | ||
562 | Do not notice anything as error. | |
563 | ||
564 | Unspecified:: | |
565 | ||
566 | Use the value of `core.whitespace` configuration variable to | |
567 | decide what to notice as error. | |
568 | ||
569 | String:: | |
570 | ||
571 | Specify a comma separate list of common whitespace problems to | |
572 | notice in the same format as `core.whitespace` configuration | |
573 | variable. | |
574 | ||
575 | ||
8a33dd8b JH |
576 | Creating an archive |
577 | ~~~~~~~~~~~~~~~~~~~ | |
578 | ||
08b51f51 JH |
579 | `export-ignore` |
580 | ^^^^^^^^^^^^^^^ | |
581 | ||
582 | Files and directories with the attribute `export-ignore` won't be added to | |
583 | archive files. | |
584 | ||
8a33dd8b JH |
585 | `export-subst` |
586 | ^^^^^^^^^^^^^^ | |
587 | ||
588 | If the attribute `export-subst` is set for a file then git will expand | |
589 | several placeholders when adding this file to an archive. The | |
08b51f51 | 590 | expansion depends on the availability of a commit ID, i.e., if |
8a33dd8b JH |
591 | linkgit:git-archive[1] has been given a tree instead of a commit or a |
592 | tag then no replacement will be done. The placeholders are the same | |
593 | as those for the option `--pretty=format:` of linkgit:git-log[1], | |
594 | except that they need to be wrapped like this: `$Format:PLACEHOLDERS$` | |
595 | in the file. E.g. the string `$Format:%H$` will be replaced by the | |
596 | commit hash. | |
597 | ||
598 | ||
975457f1 NG |
599 | Packing objects |
600 | ~~~~~~~~~~~~~~~ | |
601 | ||
602 | `delta` | |
603 | ^^^^^^^ | |
604 | ||
605 | Delta compression will not be attempted for blobs for paths with the | |
606 | attribute `delta` set to false. | |
607 | ||
608 | ||
a2df1fb2 AG |
609 | Viewing files in GUI tools |
610 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
611 | ||
612 | `encoding` | |
613 | ^^^^^^^^^^ | |
614 | ||
615 | The value of this attribute specifies the character encoding that should | |
616 | be used by GUI tools (e.g. linkgit:gitk[1] and linkgit:git-gui[1]) to | |
617 | display the contents of the relevant file. Note that due to performance | |
618 | considerations linkgit:gitk[1] does not use this attribute unless you | |
619 | manually enable per-file encodings in its options. | |
620 | ||
621 | If this attribute is not set or has an invalid value, the value of the | |
622 | `gui.encoding` configuration variable is used instead | |
623 | (See linkgit:git-config[1]). | |
624 | ||
625 | ||
bbb896d8 JH |
626 | USING ATTRIBUTE MACROS |
627 | ---------------------- | |
628 | ||
629 | You do not want any end-of-line conversions applied to, nor textual diffs | |
630 | produced for, any binary file you track. You would need to specify e.g. | |
631 | ||
632 | ------------ | |
633 | *.jpg -crlf -diff | |
634 | ------------ | |
635 | ||
636 | but that may become cumbersome, when you have many attributes. Using | |
637 | attribute macros, you can specify groups of attributes set or unset at | |
638 | the same time. The system knows a built-in attribute macro, `binary`: | |
639 | ||
640 | ------------ | |
641 | *.jpg binary | |
642 | ------------ | |
643 | ||
644 | which is equivalent to the above. Note that the attribute macros can only | |
645 | be "Set" (see the above example that sets "binary" macro as if it were an | |
646 | ordinary attribute --- setting it in turn unsets "crlf" and "diff"). | |
647 | ||
648 | ||
649 | DEFINING ATTRIBUTE MACROS | |
650 | ------------------------- | |
651 | ||
652 | Custom attribute macros can be defined only in the `.gitattributes` file | |
653 | at the toplevel (i.e. not in any subdirectory). The built-in attribute | |
654 | macro "binary" is equivalent to: | |
655 | ||
656 | ------------ | |
657 | [attr]binary -diff -crlf | |
658 | ------------ | |
659 | ||
660 | ||
88e7fdf2 JH |
661 | EXAMPLE |
662 | ------- | |
663 | ||
664 | If you have these three `gitattributes` file: | |
665 | ||
666 | ---------------------------------------------------------------- | |
667 | (in $GIT_DIR/info/attributes) | |
668 | ||
669 | a* foo !bar -baz | |
670 | ||
671 | (in .gitattributes) | |
672 | abc foo bar baz | |
673 | ||
674 | (in t/.gitattributes) | |
675 | ab* merge=filfre | |
676 | abc -foo -bar | |
677 | *.c frotz | |
678 | ---------------------------------------------------------------- | |
679 | ||
680 | the attributes given to path `t/abc` are computed as follows: | |
681 | ||
682 | 1. By examining `t/.gitattributes` (which is in the same | |
02783075 | 683 | directory as the path in question), git finds that the first |
88e7fdf2 JH |
684 | line matches. `merge` attribute is set. It also finds that |
685 | the second line matches, and attributes `foo` and `bar` | |
686 | are unset. | |
687 | ||
688 | 2. Then it examines `.gitattributes` (which is in the parent | |
689 | directory), and finds that the first line matches, but | |
690 | `t/.gitattributes` file already decided how `merge`, `foo` | |
691 | and `bar` attributes should be given to this path, so it | |
692 | leaves `foo` and `bar` unset. Attribute `baz` is set. | |
693 | ||
5c759f96 | 694 | 3. Finally it examines `$GIT_DIR/info/attributes`. This file |
88e7fdf2 JH |
695 | is used to override the in-tree settings. The first line is |
696 | a match, and `foo` is set, `bar` is reverted to unspecified | |
697 | state, and `baz` is unset. | |
698 | ||
02783075 | 699 | As the result, the attributes assignment to `t/abc` becomes: |
88e7fdf2 JH |
700 | |
701 | ---------------------------------------------------------------- | |
702 | foo set to true | |
703 | bar unspecified | |
704 | baz set to false | |
705 | merge set to string value "filfre" | |
706 | frotz unspecified | |
707 | ---------------------------------------------------------------- | |
708 | ||
709 | ||
8460b2fc | 710 | |
88e7fdf2 JH |
711 | GIT |
712 | --- | |
9e1f0a85 | 713 | Part of the linkgit:git[1] suite |