]>
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 | pattern attr1 attr2 ... | |
22 | ||
23 | That is, a pattern followed by an attributes list, | |
24 | separated by whitespaces. When the 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 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 pattern matches the path, a later line | |
56 | overrides an earlier line. This overriding is done per | |
57 | attribute. The rules how the pattern matches paths are the | |
58 | same as in `.gitignore` files; see linkgit:gitignore[5]. | |
59 | Unlike `.gitignore`, negative patterns are forbidden. | |
60 | ||
61 | When deciding what attributes are assigned to a path, git | |
62 | consults `$GIT_DIR/info/attributes` file (which has the highest | |
63 | precedence), `.gitattributes` file in the same directory as the | |
64 | path in question, and its parent directories up to the toplevel of the | |
65 | work tree (the further the directory that contains `.gitattributes` | |
66 | is from the path in question, the lower its precedence). Finally | |
67 | global and system-wide files are considered (they have the lowest | |
68 | precedence). | |
69 | ||
70 | When the `.gitattributes` file is missing from the work tree, the | |
71 | path in the index is used as a fall-back. During checkout process, | |
72 | `.gitattributes` in the index is used and then the file in the | |
73 | working tree is used as a fall-back. | |
74 | ||
75 | If you wish to affect only a single repository (i.e., to assign | |
76 | attributes to files that are particular to | |
77 | one user's workflow for that repository), then | |
78 | attributes should be placed in the `$GIT_DIR/info/attributes` file. | |
79 | Attributes which should be version-controlled and distributed to other | |
80 | repositories (i.e., attributes of interest to all users) should go into | |
81 | `.gitattributes` files. Attributes that should affect all repositories | |
82 | for a single user should be placed in a file specified by the | |
83 | `core.attributesfile` configuration option (see linkgit:git-config[1]). | |
84 | Its default value is $XDG_CONFIG_HOME/git/attributes. If $XDG_CONFIG_HOME | |
85 | is either not set or empty, $HOME/.config/git/attributes is used instead. | |
86 | Attributes for all users on a system should be placed in the | |
87 | `$(prefix)/etc/gitattributes` file. | |
88 | ||
89 | Sometimes you would need to override an setting of an attribute | |
90 | for a path to `Unspecified` state. This can be done by listing | |
91 | the name of the attribute prefixed with an exclamation point `!`. | |
92 | ||
93 | ||
94 | EFFECTS | |
95 | ------- | |
96 | ||
97 | Certain operations by git can be influenced by assigning | |
98 | particular attributes to a path. Currently, the following | |
99 | operations are attributes-aware. | |
100 | ||
101 | Checking-out and checking-in | |
102 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
103 | ||
104 | These attributes affect how the contents stored in the | |
105 | repository are copied to the working tree files when commands | |
106 | such as 'git checkout' and 'git merge' run. They also affect how | |
107 | git stores the contents you prepare in the working tree in the | |
108 | repository upon 'git add' and 'git commit'. | |
109 | ||
110 | `text` | |
111 | ^^^^^^ | |
112 | ||
113 | This attribute enables and controls end-of-line normalization. When a | |
114 | text file is normalized, its line endings are converted to LF in the | |
115 | repository. To control what line ending style is used in the working | |
116 | directory, use the `eol` attribute for a single file and the | |
117 | `core.eol` configuration variable for all text files. | |
118 | ||
119 | Set:: | |
120 | ||
121 | Setting the `text` attribute on a path enables end-of-line | |
122 | normalization and marks the path as a text file. End-of-line | |
123 | conversion takes place without guessing the content type. | |
124 | ||
125 | Unset:: | |
126 | ||
127 | Unsetting the `text` attribute on a path tells git not to | |
128 | attempt any end-of-line conversion upon checkin or checkout. | |
129 | ||
130 | Set to string value "auto":: | |
131 | ||
132 | When `text` is set to "auto", the path is marked for automatic | |
133 | end-of-line normalization. If git decides that the content is | |
134 | text, its line endings are normalized to LF on checkin. | |
135 | ||
136 | Unspecified:: | |
137 | ||
138 | If the `text` attribute is unspecified, git uses the | |
139 | `core.autocrlf` configuration variable to determine if the | |
140 | file should be converted. | |
141 | ||
142 | Any other value causes git to act as if `text` has been left | |
143 | unspecified. | |
144 | ||
145 | `eol` | |
146 | ^^^^^ | |
147 | ||
148 | This attribute sets a specific line-ending style to be used in the | |
149 | working directory. It enables end-of-line normalization without any | |
150 | content checks, effectively setting the `text` attribute. | |
151 | ||
152 | Set to string value "crlf":: | |
153 | ||
154 | This setting forces git to normalize line endings for this | |
155 | file on checkin and convert them to CRLF when the file is | |
156 | checked out. | |
157 | ||
158 | Set to string value "lf":: | |
159 | ||
160 | This setting forces git to normalize line endings to LF on | |
161 | checkin and prevents conversion to CRLF when the file is | |
162 | checked out. | |
163 | ||
164 | Backwards compatibility with `crlf` attribute | |
165 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
166 | ||
167 | For backwards compatibility, the `crlf` attribute is interpreted as | |
168 | follows: | |
169 | ||
170 | ------------------------ | |
171 | crlf text | |
172 | -crlf -text | |
173 | crlf=input eol=lf | |
174 | ------------------------ | |
175 | ||
176 | End-of-line conversion | |
177 | ^^^^^^^^^^^^^^^^^^^^^^ | |
178 | ||
179 | While git normally leaves file contents alone, it can be configured to | |
180 | normalize line endings to LF in the repository and, optionally, to | |
181 | convert them to CRLF when files are checked out. | |
182 | ||
183 | Here is an example that will make git normalize .txt, .vcproj and .sh | |
184 | files, ensure that .vcproj files have CRLF and .sh files have LF in | |
185 | the working directory, and prevent .jpg files from being normalized | |
186 | regardless of their content. | |
187 | ||
188 | ------------------------ | |
189 | *.txt text | |
190 | *.vcproj eol=crlf | |
191 | *.sh eol=lf | |
192 | *.jpg -text | |
193 | ------------------------ | |
194 | ||
195 | Other source code management systems normalize all text files in their | |
196 | repositories, and there are two ways to enable similar automatic | |
197 | normalization in git. | |
198 | ||
199 | If you simply want to have CRLF line endings in your working directory | |
200 | regardless of the repository you are working with, you can set the | |
201 | config variable "core.autocrlf" without changing any attributes. | |
202 | ||
203 | ------------------------ | |
204 | [core] | |
205 | autocrlf = true | |
206 | ------------------------ | |
207 | ||
208 | This does not force normalization of all text files, but does ensure | |
209 | that text files that you introduce to the repository have their line | |
210 | endings normalized to LF when they are added, and that files that are | |
211 | already normalized in the repository stay normalized. | |
212 | ||
213 | If you want to interoperate with a source code management system that | |
214 | enforces end-of-line normalization, or you simply want all text files | |
215 | in your repository to be normalized, you should instead set the `text` | |
216 | attribute to "auto" for _all_ files. | |
217 | ||
218 | ------------------------ | |
219 | * text=auto | |
220 | ------------------------ | |
221 | ||
222 | This ensures that all files that git considers to be text will have | |
223 | normalized (LF) line endings in the repository. The `core.eol` | |
224 | configuration variable controls which line endings git will use for | |
225 | normalized files in your working directory; the default is to use the | |
226 | native line ending for your platform, or CRLF if `core.autocrlf` is | |
227 | set. | |
228 | ||
229 | NOTE: When `text=auto` normalization is enabled in an existing | |
230 | repository, any text files containing CRLFs should be normalized. If | |
231 | they are not they will be normalized the next time someone tries to | |
232 | change them, causing unfortunate misattribution. From a clean working | |
233 | directory: | |
234 | ||
235 | ------------------------------------------------- | |
236 | $ echo "* text=auto" >>.gitattributes | |
237 | $ rm .git/index # Remove the index to force git to | |
238 | $ git reset # re-scan the working directory | |
239 | $ git status # Show files that will be normalized | |
240 | $ git add -u | |
241 | $ git add .gitattributes | |
242 | $ git commit -m "Introduce end-of-line normalization" | |
243 | ------------------------------------------------- | |
244 | ||
245 | If any files that should not be normalized show up in 'git status', | |
246 | unset their `text` attribute before running 'git add -u'. | |
247 | ||
248 | ------------------------ | |
249 | manual.pdf -text | |
250 | ------------------------ | |
251 | ||
252 | Conversely, text files that git does not detect can have normalization | |
253 | enabled manually. | |
254 | ||
255 | ------------------------ | |
256 | weirdchars.txt text | |
257 | ------------------------ | |
258 | ||
259 | If `core.safecrlf` is set to "true" or "warn", git verifies if | |
260 | the conversion is reversible for the current setting of | |
261 | `core.autocrlf`. For "true", git rejects irreversible | |
262 | conversions; for "warn", git only prints a warning but accepts | |
263 | an irreversible conversion. The safety triggers to prevent such | |
264 | a conversion done to the files in the work tree, but there are a | |
265 | few exceptions. Even though... | |
266 | ||
267 | - 'git add' itself does not touch the files in the work tree, the | |
268 | next checkout would, so the safety triggers; | |
269 | ||
270 | - 'git apply' to update a text file with a patch does touch the files | |
271 | in the work tree, but the operation is about text files and CRLF | |
272 | conversion is about fixing the line ending inconsistencies, so the | |
273 | safety does not trigger; | |
274 | ||
275 | - 'git diff' itself does not touch the files in the work tree, it is | |
276 | often run to inspect the changes you intend to next 'git add'. To | |
277 | catch potential problems early, safety triggers. | |
278 | ||
279 | ||
280 | `ident` | |
281 | ^^^^^^^ | |
282 | ||
283 | When the attribute `ident` is set for a path, git replaces | |
284 | `$Id$` in the blob object with `$Id:`, followed by the | |
285 | 40-character hexadecimal blob object name, followed by a dollar | |
286 | sign `$` upon checkout. Any byte sequence that begins with | |
287 | `$Id:` and ends with `$` in the worktree file is replaced | |
288 | with `$Id$` upon check-in. | |
289 | ||
290 | ||
291 | `filter` | |
292 | ^^^^^^^^ | |
293 | ||
294 | A `filter` attribute can be set to a string value that names a | |
295 | filter driver specified in the configuration. | |
296 | ||
297 | A filter driver consists of a `clean` command and a `smudge` | |
298 | command, either of which can be left unspecified. Upon | |
299 | checkout, when the `smudge` command is specified, the command is | |
300 | fed the blob object from its standard input, and its standard | |
301 | output is used to update the worktree file. Similarly, the | |
302 | `clean` command is used to convert the contents of worktree file | |
303 | upon checkin. | |
304 | ||
305 | One use of the content filtering is to massage the content into a shape | |
306 | that is more convenient for the platform, filesystem, and the user to use. | |
307 | For this mode of operation, the key phrase here is "more convenient" and | |
308 | not "turning something unusable into usable". In other words, the intent | |
309 | is that if someone unsets the filter driver definition, or does not have | |
310 | the appropriate filter program, the project should still be usable. | |
311 | ||
312 | Another use of the content filtering is to store the content that cannot | |
313 | be directly used in the repository (e.g. a UUID that refers to the true | |
314 | content stored outside git, or an encrypted content) and turn it into a | |
315 | usable form upon checkout (e.g. download the external content, or decrypt | |
316 | the encrypted content). | |
317 | ||
318 | These two filters behave differently, and by default, a filter is taken as | |
319 | the former, massaging the contents into more convenient shape. A missing | |
320 | filter driver definition in the config, or a filter driver that exits with | |
321 | a non-zero status, is not an error but makes the filter a no-op passthru. | |
322 | ||
323 | You can declare that a filter turns a content that by itself is unusable | |
324 | into a usable content by setting the filter.<driver>.required configuration | |
325 | variable to `true`. | |
326 | ||
327 | For example, in .gitattributes, you would assign the `filter` | |
328 | attribute for paths. | |
329 | ||
330 | ------------------------ | |
331 | *.c filter=indent | |
332 | ------------------------ | |
333 | ||
334 | Then you would define a "filter.indent.clean" and "filter.indent.smudge" | |
335 | configuration in your .git/config to specify a pair of commands to | |
336 | modify the contents of C programs when the source files are checked | |
337 | in ("clean" is run) and checked out (no change is made because the | |
338 | command is "cat"). | |
339 | ||
340 | ------------------------ | |
341 | [filter "indent"] | |
342 | clean = indent | |
343 | smudge = cat | |
344 | ------------------------ | |
345 | ||
346 | For best results, `clean` should not alter its output further if it is | |
347 | run twice ("clean->clean" should be equivalent to "clean"), and | |
348 | multiple `smudge` commands should not alter `clean`'s output | |
349 | ("smudge->smudge->clean" should be equivalent to "clean"). See the | |
350 | section on merging below. | |
351 | ||
352 | The "indent" filter is well-behaved in this regard: it will not modify | |
353 | input that is already correctly indented. In this case, the lack of a | |
354 | smudge filter means that the clean filter _must_ accept its own output | |
355 | without modifying it. | |
356 | ||
357 | If a filter _must_ succeed in order to make the stored contents usable, | |
358 | you can declare that the filter is `required`, in the configuration: | |
359 | ||
360 | ------------------------ | |
361 | [filter "crypt"] | |
362 | clean = openssl enc ... | |
363 | smudge = openssl enc -d ... | |
364 | required | |
365 | ------------------------ | |
366 | ||
367 | Sequence "%f" on the filter command line is replaced with the name of | |
368 | the file the filter is working on. A filter might use this in keyword | |
369 | substitution. For example: | |
370 | ||
371 | ------------------------ | |
372 | [filter "p4"] | |
373 | clean = git-p4-filter --clean %f | |
374 | smudge = git-p4-filter --smudge %f | |
375 | ------------------------ | |
376 | ||
377 | ||
378 | Interaction between checkin/checkout attributes | |
379 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
380 | ||
381 | In the check-in codepath, the worktree file is first converted | |
382 | with `filter` driver (if specified and corresponding driver | |
383 | defined), then the result is processed with `ident` (if | |
384 | specified), and then finally with `text` (again, if specified | |
385 | and applicable). | |
386 | ||
387 | In the check-out codepath, the blob content is first converted | |
388 | with `text`, and then `ident` and fed to `filter`. | |
389 | ||
390 | ||
391 | Merging branches with differing checkin/checkout attributes | |
392 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
393 | ||
394 | If you have added attributes to a file that cause the canonical | |
395 | repository format for that file to change, such as adding a | |
396 | clean/smudge filter or text/eol/ident attributes, merging anything | |
397 | where the attribute is not in place would normally cause merge | |
398 | conflicts. | |
399 | ||
400 | To prevent these unnecessary merge conflicts, git can be told to run a | |
401 | virtual check-out and check-in of all three stages of a file when | |
402 | resolving a three-way merge by setting the `merge.renormalize` | |
403 | configuration variable. This prevents changes caused by check-in | |
404 | conversion from causing spurious merge conflicts when a converted file | |
405 | is merged with an unconverted file. | |
406 | ||
407 | As long as a "smudge->clean" results in the same output as a "clean" | |
408 | even on files that are already smudged, this strategy will | |
409 | automatically resolve all filter-related conflicts. Filters that do | |
410 | not act in this way may cause additional merge conflicts that must be | |
411 | resolved manually. | |
412 | ||
413 | ||
414 | Generating diff text | |
415 | ~~~~~~~~~~~~~~~~~~~~ | |
416 | ||
417 | `diff` | |
418 | ^^^^^^ | |
419 | ||
420 | The attribute `diff` affects how 'git' generates diffs for particular | |
421 | files. It can tell git whether to generate a textual patch for the path | |
422 | or to treat the path as a binary file. It can also affect what line is | |
423 | shown on the hunk header `@@ -k,l +n,m @@` line, tell git to use an | |
424 | external command to generate the diff, or ask git to convert binary | |
425 | files to a text format before generating the diff. | |
426 | ||
427 | Set:: | |
428 | ||
429 | A path to which the `diff` attribute is set is treated | |
430 | as text, even when they contain byte values that | |
431 | normally never appear in text files, such as NUL. | |
432 | ||
433 | Unset:: | |
434 | ||
435 | A path to which the `diff` attribute is unset will | |
436 | generate `Binary files differ` (or a binary patch, if | |
437 | binary patches are enabled). | |
438 | ||
439 | Unspecified:: | |
440 | ||
441 | A path to which the `diff` attribute is unspecified | |
442 | first gets its contents inspected, and if it looks like | |
443 | text, it is treated as text. Otherwise it would | |
444 | generate `Binary files differ`. | |
445 | ||
446 | String:: | |
447 | ||
448 | Diff is shown using the specified diff driver. Each driver may | |
449 | specify one or more options, as described in the following | |
450 | section. The options for the diff driver "foo" are defined | |
451 | by the configuration variables in the "diff.foo" section of the | |
452 | git config file. | |
453 | ||
454 | ||
455 | Defining an external diff driver | |
456 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
457 | ||
458 | The definition of a diff driver is done in `gitconfig`, not | |
459 | `gitattributes` file, so strictly speaking this manual page is a | |
460 | wrong place to talk about it. However... | |
461 | ||
462 | To define an external diff driver `jcdiff`, add a section to your | |
463 | `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: | |
464 | ||
465 | ---------------------------------------------------------------- | |
466 | [diff "jcdiff"] | |
467 | command = j-c-diff | |
468 | ---------------------------------------------------------------- | |
469 | ||
470 | When git needs to show you a diff for the path with `diff` | |
471 | attribute set to `jcdiff`, it calls the command you specified | |
472 | with the above configuration, i.e. `j-c-diff`, with 7 | |
473 | parameters, just like `GIT_EXTERNAL_DIFF` program is called. | |
474 | See linkgit:git[1] for details. | |
475 | ||
476 | ||
477 | Defining a custom hunk-header | |
478 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
479 | ||
480 | Each group of changes (called a "hunk") in the textual diff output | |
481 | is prefixed with a line of the form: | |
482 | ||
483 | @@ -k,l +n,m @@ TEXT | |
484 | ||
485 | This is called a 'hunk header'. The "TEXT" portion is by default a line | |
486 | that begins with an alphabet, an underscore or a dollar sign; this | |
487 | matches what GNU 'diff -p' output uses. This default selection however | |
488 | is not suited for some contents, and you can use a customized pattern | |
489 | to make a selection. | |
490 | ||
491 | First, in .gitattributes, you would assign the `diff` attribute | |
492 | for paths. | |
493 | ||
494 | ------------------------ | |
495 | *.tex diff=tex | |
496 | ------------------------ | |
497 | ||
498 | Then, you would define a "diff.tex.xfuncname" configuration to | |
499 | specify a regular expression that matches a line that you would | |
500 | want to appear as the hunk header "TEXT". Add a section to your | |
501 | `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: | |
502 | ||
503 | ------------------------ | |
504 | [diff "tex"] | |
505 | xfuncname = "^(\\\\(sub)*section\\{.*)$" | |
506 | ------------------------ | |
507 | ||
508 | Note. A single level of backslashes are eaten by the | |
509 | configuration file parser, so you would need to double the | |
510 | backslashes; the pattern above picks a line that begins with a | |
511 | backslash, and zero or more occurrences of `sub` followed by | |
512 | `section` followed by open brace, to the end of line. | |
513 | ||
514 | There are a few built-in patterns to make this easier, and `tex` | |
515 | is one of them, so you do not have to write the above in your | |
516 | configuration file (you still need to enable this with the | |
517 | attribute mechanism, via `.gitattributes`). The following built in | |
518 | patterns are available: | |
519 | ||
520 | - `ada` suitable for source code in the Ada language. | |
521 | ||
522 | - `bibtex` suitable for files with BibTeX coded references. | |
523 | ||
524 | - `cpp` suitable for source code in the C and C++ languages. | |
525 | ||
526 | - `csharp` suitable for source code in the C# language. | |
527 | ||
528 | - `fortran` suitable for source code in the Fortran language. | |
529 | ||
530 | - `html` suitable for HTML/XHTML documents. | |
531 | ||
532 | - `java` suitable for source code in the Java language. | |
533 | ||
534 | - `matlab` suitable for source code in the MATLAB language. | |
535 | ||
536 | - `objc` suitable for source code in the Objective-C language. | |
537 | ||
538 | - `pascal` suitable for source code in the Pascal/Delphi language. | |
539 | ||
540 | - `perl` suitable for source code in the Perl language. | |
541 | ||
542 | - `php` suitable for source code in the PHP language. | |
543 | ||
544 | - `python` suitable for source code in the Python language. | |
545 | ||
546 | - `ruby` suitable for source code in the Ruby language. | |
547 | ||
548 | - `tex` suitable for source code for LaTeX documents. | |
549 | ||
550 | ||
551 | Customizing word diff | |
552 | ^^^^^^^^^^^^^^^^^^^^^ | |
553 | ||
554 | You can customize the rules that `git diff --word-diff` uses to | |
555 | split words in a line, by specifying an appropriate regular expression | |
556 | in the "diff.*.wordRegex" configuration variable. For example, in TeX | |
557 | a backslash followed by a sequence of letters forms a command, but | |
558 | several such commands can be run together without intervening | |
559 | whitespace. To separate them, use a regular expression in your | |
560 | `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: | |
561 | ||
562 | ------------------------ | |
563 | [diff "tex"] | |
564 | wordRegex = "\\\\[a-zA-Z]+|[{}]|\\\\.|[^\\{}[:space:]]+" | |
565 | ------------------------ | |
566 | ||
567 | A built-in pattern is provided for all languages listed in the | |
568 | previous section. | |
569 | ||
570 | ||
571 | Performing text diffs of binary files | |
572 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
573 | ||
574 | Sometimes it is desirable to see the diff of a text-converted | |
575 | version of some binary files. For example, a word processor | |
576 | document can be converted to an ASCII text representation, and | |
577 | the diff of the text shown. Even though this conversion loses | |
578 | some information, the resulting diff is useful for human | |
579 | viewing (but cannot be applied directly). | |
580 | ||
581 | The `textconv` config option is used to define a program for | |
582 | performing such a conversion. The program should take a single | |
583 | argument, the name of a file to convert, and produce the | |
584 | resulting text on stdout. | |
585 | ||
586 | For example, to show the diff of the exif information of a | |
587 | file instead of the binary information (assuming you have the | |
588 | exif tool installed), add the following section to your | |
589 | `$GIT_DIR/config` file (or `$HOME/.gitconfig` file): | |
590 | ||
591 | ------------------------ | |
592 | [diff "jpg"] | |
593 | textconv = exif | |
594 | ------------------------ | |
595 | ||
596 | NOTE: The text conversion is generally a one-way conversion; | |
597 | in this example, we lose the actual image contents and focus | |
598 | just on the text data. This means that diffs generated by | |
599 | textconv are _not_ suitable for applying. For this reason, | |
600 | only `git diff` and the `git log` family of commands (i.e., | |
601 | log, whatchanged, show) will perform text conversion. `git | |
602 | format-patch` will never generate this output. If you want to | |
603 | send somebody a text-converted diff of a binary file (e.g., | |
604 | because it quickly conveys the changes you have made), you | |
605 | should generate it separately and send it as a comment _in | |
606 | addition to_ the usual binary diff that you might send. | |
607 | ||
608 | Because text conversion can be slow, especially when doing a | |
609 | large number of them with `git log -p`, git provides a mechanism | |
610 | to cache the output and use it in future diffs. To enable | |
611 | caching, set the "cachetextconv" variable in your diff driver's | |
612 | config. For example: | |
613 | ||
614 | ------------------------ | |
615 | [diff "jpg"] | |
616 | textconv = exif | |
617 | cachetextconv = true | |
618 | ------------------------ | |
619 | ||
620 | This will cache the result of running "exif" on each blob | |
621 | indefinitely. If you change the textconv config variable for a | |
622 | diff driver, git will automatically invalidate the cache entries | |
623 | and re-run the textconv filter. If you want to invalidate the | |
624 | cache manually (e.g., because your version of "exif" was updated | |
625 | and now produces better output), you can remove the cache | |
626 | manually with `git update-ref -d refs/notes/textconv/jpg` (where | |
627 | "jpg" is the name of the diff driver, as in the example above). | |
628 | ||
629 | Choosing textconv versus external diff | |
630 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
631 | ||
632 | If you want to show differences between binary or specially-formatted | |
633 | blobs in your repository, you can choose to use either an external diff | |
634 | command, or to use textconv to convert them to a diff-able text format. | |
635 | Which method you choose depends on your exact situation. | |
636 | ||
637 | The advantage of using an external diff command is flexibility. You are | |
638 | not bound to find line-oriented changes, nor is it necessary for the | |
639 | output to resemble unified diff. You are free to locate and report | |
640 | changes in the most appropriate way for your data format. | |
641 | ||
642 | A textconv, by comparison, is much more limiting. You provide a | |
643 | transformation of the data into a line-oriented text format, and git | |
644 | uses its regular diff tools to generate the output. There are several | |
645 | advantages to choosing this method: | |
646 | ||
647 | 1. Ease of use. It is often much simpler to write a binary to text | |
648 | transformation than it is to perform your own diff. In many cases, | |
649 | existing programs can be used as textconv filters (e.g., exif, | |
650 | odt2txt). | |
651 | ||
652 | 2. Git diff features. By performing only the transformation step | |
653 | yourself, you can still utilize many of git's diff features, | |
654 | including colorization, word-diff, and combined diffs for merges. | |
655 | ||
656 | 3. Caching. Textconv caching can speed up repeated diffs, such as those | |
657 | you might trigger by running `git log -p`. | |
658 | ||
659 | ||
660 | Marking files as binary | |
661 | ^^^^^^^^^^^^^^^^^^^^^^^ | |
662 | ||
663 | Git usually guesses correctly whether a blob contains text or binary | |
664 | data by examining the beginning of the contents. However, sometimes you | |
665 | may want to override its decision, either because a blob contains binary | |
666 | data later in the file, or because the content, while technically | |
667 | composed of text characters, is opaque to a human reader. For example, | |
668 | many postscript files contain only ascii characters, but produce noisy | |
669 | and meaningless diffs. | |
670 | ||
671 | The simplest way to mark a file as binary is to unset the diff | |
672 | attribute in the `.gitattributes` file: | |
673 | ||
674 | ------------------------ | |
675 | *.ps -diff | |
676 | ------------------------ | |
677 | ||
678 | This will cause git to generate `Binary files differ` (or a binary | |
679 | patch, if binary patches are enabled) instead of a regular diff. | |
680 | ||
681 | However, one may also want to specify other diff driver attributes. For | |
682 | example, you might want to use `textconv` to convert postscript files to | |
683 | an ascii representation for human viewing, but otherwise treat them as | |
684 | binary files. You cannot specify both `-diff` and `diff=ps` attributes. | |
685 | The solution is to use the `diff.*.binary` config option: | |
686 | ||
687 | ------------------------ | |
688 | [diff "ps"] | |
689 | textconv = ps2ascii | |
690 | binary = true | |
691 | ------------------------ | |
692 | ||
693 | Performing a three-way merge | |
694 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
695 | ||
696 | `merge` | |
697 | ^^^^^^^ | |
698 | ||
699 | The attribute `merge` affects how three versions of a file are | |
700 | merged when a file-level merge is necessary during `git merge`, | |
701 | and other commands such as `git revert` and `git cherry-pick`. | |
702 | ||
703 | Set:: | |
704 | ||
705 | Built-in 3-way merge driver is used to merge the | |
706 | contents in a way similar to 'merge' command of `RCS` | |
707 | suite. This is suitable for ordinary text files. | |
708 | ||
709 | Unset:: | |
710 | ||
711 | Take the version from the current branch as the | |
712 | tentative merge result, and declare that the merge has | |
713 | conflicts. This is suitable for binary files that do | |
714 | not have a well-defined merge semantics. | |
715 | ||
716 | Unspecified:: | |
717 | ||
718 | By default, this uses the same built-in 3-way merge | |
719 | driver as is the case when the `merge` attribute is set. | |
720 | However, the `merge.default` configuration variable can name | |
721 | different merge driver to be used with paths for which the | |
722 | `merge` attribute is unspecified. | |
723 | ||
724 | String:: | |
725 | ||
726 | 3-way merge is performed using the specified custom | |
727 | merge driver. The built-in 3-way merge driver can be | |
728 | explicitly specified by asking for "text" driver; the | |
729 | built-in "take the current branch" driver can be | |
730 | requested with "binary". | |
731 | ||
732 | ||
733 | Built-in merge drivers | |
734 | ^^^^^^^^^^^^^^^^^^^^^^ | |
735 | ||
736 | There are a few built-in low-level merge drivers defined that | |
737 | can be asked for via the `merge` attribute. | |
738 | ||
739 | text:: | |
740 | ||
741 | Usual 3-way file level merge for text files. Conflicted | |
742 | regions are marked with conflict markers `<<<<<<<`, | |
743 | `=======` and `>>>>>>>`. The version from your branch | |
744 | appears before the `=======` marker, and the version | |
745 | from the merged branch appears after the `=======` | |
746 | marker. | |
747 | ||
748 | binary:: | |
749 | ||
750 | Keep the version from your branch in the work tree, but | |
751 | leave the path in the conflicted state for the user to | |
752 | sort out. | |
753 | ||
754 | union:: | |
755 | ||
756 | Run 3-way file level merge for text files, but take | |
757 | lines from both versions, instead of leaving conflict | |
758 | markers. This tends to leave the added lines in the | |
759 | resulting file in random order and the user should | |
760 | verify the result. Do not use this if you do not | |
761 | understand the implications. | |
762 | ||
763 | ||
764 | Defining a custom merge driver | |
765 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
766 | ||
767 | The definition of a merge driver is done in the `.git/config` | |
768 | file, not in the `gitattributes` file, so strictly speaking this | |
769 | manual page is a wrong place to talk about it. However... | |
770 | ||
771 | To define a custom merge driver `filfre`, add a section to your | |
772 | `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: | |
773 | ||
774 | ---------------------------------------------------------------- | |
775 | [merge "filfre"] | |
776 | name = feel-free merge driver | |
777 | driver = filfre %O %A %B | |
778 | recursive = binary | |
779 | ---------------------------------------------------------------- | |
780 | ||
781 | The `merge.*.name` variable gives the driver a human-readable | |
782 | name. | |
783 | ||
784 | The `merge.*.driver` variable's value is used to construct a | |
785 | command to run to merge ancestor's version (`%O`), current | |
786 | version (`%A`) and the other branches' version (`%B`). These | |
787 | three tokens are replaced with the names of temporary files that | |
788 | hold the contents of these versions when the command line is | |
789 | built. Additionally, %L will be replaced with the conflict marker | |
790 | size (see below). | |
791 | ||
792 | The merge driver is expected to leave the result of the merge in | |
793 | the file named with `%A` by overwriting it, and exit with zero | |
794 | status if it managed to merge them cleanly, or non-zero if there | |
795 | were conflicts. | |
796 | ||
797 | The `merge.*.recursive` variable specifies what other merge | |
798 | driver to use when the merge driver is called for an internal | |
799 | merge between common ancestors, when there are more than one. | |
800 | When left unspecified, the driver itself is used for both | |
801 | internal merge and the final merge. | |
802 | ||
803 | ||
804 | `conflict-marker-size` | |
805 | ^^^^^^^^^^^^^^^^^^^^^^ | |
806 | ||
807 | This attribute controls the length of conflict markers left in | |
808 | the work tree file during a conflicted merge. Only setting to | |
809 | the value to a positive integer has any meaningful effect. | |
810 | ||
811 | For example, this line in `.gitattributes` can be used to tell the merge | |
812 | machinery to leave much longer (instead of the usual 7-character-long) | |
813 | conflict markers when merging the file `Documentation/git-merge.txt` | |
814 | results in a conflict. | |
815 | ||
816 | ------------------------ | |
817 | Documentation/git-merge.txt conflict-marker-size=32 | |
818 | ------------------------ | |
819 | ||
820 | ||
821 | Checking whitespace errors | |
822 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
823 | ||
824 | `whitespace` | |
825 | ^^^^^^^^^^^^ | |
826 | ||
827 | The `core.whitespace` configuration variable allows you to define what | |
828 | 'diff' and 'apply' should consider whitespace errors for all paths in | |
829 | the project (See linkgit:git-config[1]). This attribute gives you finer | |
830 | control per path. | |
831 | ||
832 | Set:: | |
833 | ||
834 | Notice all types of potential whitespace errors known to git. | |
835 | The tab width is taken from the value of the `core.whitespace` | |
836 | configuration variable. | |
837 | ||
838 | Unset:: | |
839 | ||
840 | Do not notice anything as error. | |
841 | ||
842 | Unspecified:: | |
843 | ||
844 | Use the value of the `core.whitespace` configuration variable to | |
845 | decide what to notice as error. | |
846 | ||
847 | String:: | |
848 | ||
849 | Specify a comma separate list of common whitespace problems to | |
850 | notice in the same format as the `core.whitespace` configuration | |
851 | variable. | |
852 | ||
853 | ||
854 | Creating an archive | |
855 | ~~~~~~~~~~~~~~~~~~~ | |
856 | ||
857 | `export-ignore` | |
858 | ^^^^^^^^^^^^^^^ | |
859 | ||
860 | Files and directories with the attribute `export-ignore` won't be added to | |
861 | archive files. | |
862 | ||
863 | `export-subst` | |
864 | ^^^^^^^^^^^^^^ | |
865 | ||
866 | If the attribute `export-subst` is set for a file then git will expand | |
867 | several placeholders when adding this file to an archive. The | |
868 | expansion depends on the availability of a commit ID, i.e., if | |
869 | linkgit:git-archive[1] has been given a tree instead of a commit or a | |
870 | tag then no replacement will be done. The placeholders are the same | |
871 | as those for the option `--pretty=format:` of linkgit:git-log[1], | |
872 | except that they need to be wrapped like this: `$Format:PLACEHOLDERS$` | |
873 | in the file. E.g. the string `$Format:%H$` will be replaced by the | |
874 | commit hash. | |
875 | ||
876 | ||
877 | Packing objects | |
878 | ~~~~~~~~~~~~~~~ | |
879 | ||
880 | `delta` | |
881 | ^^^^^^^ | |
882 | ||
883 | Delta compression will not be attempted for blobs for paths with the | |
884 | attribute `delta` set to false. | |
885 | ||
886 | ||
887 | Viewing files in GUI tools | |
888 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
889 | ||
890 | `encoding` | |
891 | ^^^^^^^^^^ | |
892 | ||
893 | The value of this attribute specifies the character encoding that should | |
894 | be used by GUI tools (e.g. linkgit:gitk[1] and linkgit:git-gui[1]) to | |
895 | display the contents of the relevant file. Note that due to performance | |
896 | considerations linkgit:gitk[1] does not use this attribute unless you | |
897 | manually enable per-file encodings in its options. | |
898 | ||
899 | If this attribute is not set or has an invalid value, the value of the | |
900 | `gui.encoding` configuration variable is used instead | |
901 | (See linkgit:git-config[1]). | |
902 | ||
903 | ||
904 | USING MACRO ATTRIBUTES | |
905 | ---------------------- | |
906 | ||
907 | You do not want any end-of-line conversions applied to, nor textual diffs | |
908 | produced for, any binary file you track. You would need to specify e.g. | |
909 | ||
910 | ------------ | |
911 | *.jpg -text -diff | |
912 | ------------ | |
913 | ||
914 | but that may become cumbersome, when you have many attributes. Using | |
915 | macro attributes, you can define an attribute that, when set, also | |
916 | sets or unsets a number of other attributes at the same time. The | |
917 | system knows a built-in macro attribute, `binary`: | |
918 | ||
919 | ------------ | |
920 | *.jpg binary | |
921 | ------------ | |
922 | ||
923 | Setting the "binary" attribute also unsets the "text" and "diff" | |
924 | attributes as above. Note that macro attributes can only be "Set", | |
925 | though setting one might have the effect of setting or unsetting other | |
926 | attributes or even returning other attributes to the "Unspecified" | |
927 | state. | |
928 | ||
929 | ||
930 | DEFINING MACRO ATTRIBUTES | |
931 | ------------------------- | |
932 | ||
933 | Custom macro attributes can be defined only in the `.gitattributes` | |
934 | file at the toplevel (i.e. not in any subdirectory). The built-in | |
935 | macro attribute "binary" is equivalent to: | |
936 | ||
937 | ------------ | |
938 | [attr]binary -diff -merge -text | |
939 | ------------ | |
940 | ||
941 | ||
942 | EXAMPLE | |
943 | ------- | |
944 | ||
945 | If you have these three `gitattributes` file: | |
946 | ||
947 | ---------------------------------------------------------------- | |
948 | (in $GIT_DIR/info/attributes) | |
949 | ||
950 | a* foo !bar -baz | |
951 | ||
952 | (in .gitattributes) | |
953 | abc foo bar baz | |
954 | ||
955 | (in t/.gitattributes) | |
956 | ab* merge=filfre | |
957 | abc -foo -bar | |
958 | *.c frotz | |
959 | ---------------------------------------------------------------- | |
960 | ||
961 | the attributes given to path `t/abc` are computed as follows: | |
962 | ||
963 | 1. By examining `t/.gitattributes` (which is in the same | |
964 | directory as the path in question), git finds that the first | |
965 | line matches. `merge` attribute is set. It also finds that | |
966 | the second line matches, and attributes `foo` and `bar` | |
967 | are unset. | |
968 | ||
969 | 2. Then it examines `.gitattributes` (which is in the parent | |
970 | directory), and finds that the first line matches, but | |
971 | `t/.gitattributes` file already decided how `merge`, `foo` | |
972 | and `bar` attributes should be given to this path, so it | |
973 | leaves `foo` and `bar` unset. Attribute `baz` is set. | |
974 | ||
975 | 3. Finally it examines `$GIT_DIR/info/attributes`. This file | |
976 | is used to override the in-tree settings. The first line is | |
977 | a match, and `foo` is set, `bar` is reverted to unspecified | |
978 | state, and `baz` is unset. | |
979 | ||
980 | As the result, the attributes assignment to `t/abc` becomes: | |
981 | ||
982 | ---------------------------------------------------------------- | |
983 | foo set to true | |
984 | bar unspecified | |
985 | baz set to false | |
986 | merge set to string value "filfre" | |
987 | frotz unspecified | |
988 | ---------------------------------------------------------------- | |
989 | ||
990 | ||
991 | SEE ALSO | |
992 | -------- | |
993 | linkgit:git-check-attr[1]. | |
994 | ||
995 | GIT | |
996 | --- | |
997 | Part of the linkgit:git[1] suite |