]> git.ipfire.org Git - thirdparty/git.git/blob - Documentation/gitattributes.txt
Merge branch 'en/filter-branch-deprecation'
[thirdparty/git.git] / Documentation / gitattributes.txt
1 gitattributes(5)
2 ================
3
4 NAME
5 ----
6 gitattributes - Defining attributes per path
7
8 SYNOPSIS
9 --------
10 $GIT_DIR/info/attributes, .gitattributes
11
12
13 DESCRIPTION
14 -----------
15
16 A `gitattributes` file is a simple text file that gives
17 `attributes` to pathnames.
18
19 Each line in `gitattributes` file is of form:
20
21 pattern attr1 attr2 ...
22
23 That is, a pattern followed by an attributes list,
24 separated by whitespaces. Leading and trailing whitespaces are
25 ignored. Lines that begin with '#' are ignored. Patterns
26 that begin with a double quote are quoted in C style.
27 When the pattern matches the path in question, the attributes
28 listed on the line are given to the path.
29
30 Each attribute can be in one of these states for a given path:
31
32 Set::
33
34 The path has the attribute with special value "true";
35 this is specified by listing only the name of the
36 attribute in the attribute list.
37
38 Unset::
39
40 The path has the attribute with special value "false";
41 this is specified by listing the name of the attribute
42 prefixed with a dash `-` in the attribute list.
43
44 Set to a value::
45
46 The path has the attribute with specified string value;
47 this is specified by listing the name of the attribute
48 followed by an equal sign `=` and its value in the
49 attribute list.
50
51 Unspecified::
52
53 No pattern matches the path, and nothing says if
54 the path has or does not have the attribute, the
55 attribute for the path is said to be Unspecified.
56
57 When more than one pattern matches the path, a later line
58 overrides an earlier line. This overriding is done per
59 attribute.
60
61 The rules by which the pattern matches paths are the same as in
62 `.gitignore` files (see linkgit:gitignore[5]), with a few exceptions:
63
64 - negative patterns are forbidden
65
66 - patterns that match a directory do not recursively match paths
67 inside that directory (so using the trailing-slash `path/` syntax is
68 pointless in an attributes file; use `path/**` instead)
69
70 When deciding what attributes are assigned to a path, Git
71 consults `$GIT_DIR/info/attributes` file (which has the highest
72 precedence), `.gitattributes` file in the same directory as the
73 path in question, and its parent directories up to the toplevel of the
74 work tree (the further the directory that contains `.gitattributes`
75 is from the path in question, the lower its precedence). Finally
76 global and system-wide files are considered (they have the lowest
77 precedence).
78
79 When the `.gitattributes` file is missing from the work tree, the
80 path in the index is used as a fall-back. During checkout process,
81 `.gitattributes` in the index is used and then the file in the
82 working tree is used as a fall-back.
83
84 If you wish to affect only a single repository (i.e., to assign
85 attributes to files that are particular to
86 one user's workflow for that repository), then
87 attributes should be placed in the `$GIT_DIR/info/attributes` file.
88 Attributes which should be version-controlled and distributed to other
89 repositories (i.e., attributes of interest to all users) should go into
90 `.gitattributes` files. Attributes that should affect all repositories
91 for a single user should be placed in a file specified by the
92 `core.attributesFile` configuration option (see linkgit:git-config[1]).
93 Its default value is $XDG_CONFIG_HOME/git/attributes. If $XDG_CONFIG_HOME
94 is either not set or empty, $HOME/.config/git/attributes is used instead.
95 Attributes for all users on a system should be placed in the
96 `$(prefix)/etc/gitattributes` file.
97
98 Sometimes you would need to override a setting of an attribute
99 for a path to `Unspecified` state. This can be done by listing
100 the name of the attribute prefixed with an exclamation point `!`.
101
102
103 EFFECTS
104 -------
105
106 Certain operations by Git can be influenced by assigning
107 particular attributes to a path. Currently, the following
108 operations are attributes-aware.
109
110 Checking-out and checking-in
111 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
112
113 These attributes affect how the contents stored in the
114 repository are copied to the working tree files when commands
115 such as 'git switch', 'git checkout' and 'git merge' run.
116 They also affect how
117 Git stores the contents you prepare in the working tree in the
118 repository upon 'git add' and 'git commit'.
119
120 `text`
121 ^^^^^^
122
123 This attribute enables and controls end-of-line normalization. When a
124 text file is normalized, its line endings are converted to LF in the
125 repository. To control what line ending style is used in the working
126 directory, use the `eol` attribute for a single file and the
127 `core.eol` configuration variable for all text files.
128 Note that setting `core.autocrlf` to `true` or `input` overrides
129 `core.eol` (see the definitions of those options in
130 linkgit:git-config[1]).
131
132 Set::
133
134 Setting the `text` attribute on a path enables end-of-line
135 normalization and marks the path as a text file. End-of-line
136 conversion takes place without guessing the content type.
137
138 Unset::
139
140 Unsetting the `text` attribute on a path tells Git not to
141 attempt any end-of-line conversion upon checkin or checkout.
142
143 Set to string value "auto"::
144
145 When `text` is set to "auto", the path is marked for automatic
146 end-of-line conversion. If Git decides that the content is
147 text, its line endings are converted to LF on checkin.
148 When the file has been committed with CRLF, no conversion is done.
149
150 Unspecified::
151
152 If the `text` attribute is unspecified, Git uses the
153 `core.autocrlf` configuration variable to determine if the
154 file should be converted.
155
156 Any other value causes Git to act as if `text` has been left
157 unspecified.
158
159 `eol`
160 ^^^^^
161
162 This attribute sets a specific line-ending style to be used in the
163 working directory. It enables end-of-line conversion without any
164 content checks, effectively setting the `text` attribute. Note that
165 setting this attribute on paths which are in the index with CRLF line
166 endings may make the paths to be considered dirty. Adding the path to
167 the index again will normalize the line endings in the index.
168
169 Set to string value "crlf"::
170
171 This setting forces Git to normalize line endings for this
172 file on checkin and convert them to CRLF when the file is
173 checked out.
174
175 Set to string value "lf"::
176
177 This setting forces Git to normalize line endings to LF on
178 checkin and prevents conversion to CRLF when the file is
179 checked out.
180
181 Backwards compatibility with `crlf` attribute
182 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
183
184 For backwards compatibility, the `crlf` attribute is interpreted as
185 follows:
186
187 ------------------------
188 crlf text
189 -crlf -text
190 crlf=input eol=lf
191 ------------------------
192
193 End-of-line conversion
194 ^^^^^^^^^^^^^^^^^^^^^^
195
196 While Git normally leaves file contents alone, it can be configured to
197 normalize line endings to LF in the repository and, optionally, to
198 convert them to CRLF when files are checked out.
199
200 If you simply want to have CRLF line endings in your working directory
201 regardless of the repository you are working with, you can set the
202 config variable "core.autocrlf" without using any attributes.
203
204 ------------------------
205 [core]
206 autocrlf = true
207 ------------------------
208
209 This does not force normalization of text files, but does ensure
210 that text files that you introduce to the repository have their line
211 endings normalized to LF when they are added, and that files that are
212 already normalized in the repository stay normalized.
213
214 If you want to ensure that text files that any contributor introduces to
215 the repository have their line endings normalized, you can set the
216 `text` attribute to "auto" for _all_ files.
217
218 ------------------------
219 * text=auto
220 ------------------------
221
222 The attributes allow a fine-grained control, how the line endings
223 are converted.
224 Here is an example that will make Git normalize .txt, .vcproj and .sh
225 files, ensure that .vcproj files have CRLF and .sh files have LF in
226 the working directory, and prevent .jpg files from being normalized
227 regardless of their content.
228
229 ------------------------
230 * text=auto
231 *.txt text
232 *.vcproj text eol=crlf
233 *.sh text eol=lf
234 *.jpg -text
235 ------------------------
236
237 NOTE: When `text=auto` conversion is enabled in a cross-platform
238 project using push and pull to a central repository the text files
239 containing CRLFs should be normalized.
240
241 From a clean working directory:
242
243 -------------------------------------------------
244 $ echo "* text=auto" >.gitattributes
245 $ git add --renormalize .
246 $ git status # Show files that will be normalized
247 $ git commit -m "Introduce end-of-line normalization"
248 -------------------------------------------------
249
250 If any files that should not be normalized show up in 'git status',
251 unset their `text` attribute before running 'git add -u'.
252
253 ------------------------
254 manual.pdf -text
255 ------------------------
256
257 Conversely, text files that Git does not detect can have normalization
258 enabled manually.
259
260 ------------------------
261 weirdchars.txt text
262 ------------------------
263
264 If `core.safecrlf` is set to "true" or "warn", Git verifies if
265 the conversion is reversible for the current setting of
266 `core.autocrlf`. For "true", Git rejects irreversible
267 conversions; for "warn", Git only prints a warning but accepts
268 an irreversible conversion. The safety triggers to prevent such
269 a conversion done to the files in the work tree, but there are a
270 few exceptions. Even though...
271
272 - 'git add' itself does not touch the files in the work tree, the
273 next checkout would, so the safety triggers;
274
275 - 'git apply' to update a text file with a patch does touch the files
276 in the work tree, but the operation is about text files and CRLF
277 conversion is about fixing the line ending inconsistencies, so the
278 safety does not trigger;
279
280 - 'git diff' itself does not touch the files in the work tree, it is
281 often run to inspect the changes you intend to next 'git add'. To
282 catch potential problems early, safety triggers.
283
284
285 `working-tree-encoding`
286 ^^^^^^^^^^^^^^^^^^^^^^^
287
288 Git recognizes files encoded in ASCII or one of its supersets (e.g.
289 UTF-8, ISO-8859-1, ...) as text files. Files encoded in certain other
290 encodings (e.g. UTF-16) are interpreted as binary and consequently
291 built-in Git text processing tools (e.g. 'git diff') as well as most Git
292 web front ends do not visualize the contents of these files by default.
293
294 In these cases you can tell Git the encoding of a file in the working
295 directory with the `working-tree-encoding` attribute. If a file with this
296 attribute is added to Git, then Git reencodes the content from the
297 specified encoding to UTF-8. Finally, Git stores the UTF-8 encoded
298 content in its internal data structure (called "the index"). On checkout
299 the content is reencoded back to the specified encoding.
300
301 Please note that using the `working-tree-encoding` attribute may have a
302 number of pitfalls:
303
304 - Alternative Git implementations (e.g. JGit or libgit2) and older Git
305 versions (as of March 2018) do not support the `working-tree-encoding`
306 attribute. If you decide to use the `working-tree-encoding` attribute
307 in your repository, then it is strongly recommended to ensure that all
308 clients working with the repository support it.
309 +
310 For example, Microsoft Visual Studio resources files (`*.rc`) or
311 PowerShell script files (`*.ps1`) are sometimes encoded in UTF-16.
312 If you declare `*.ps1` as files as UTF-16 and you add `foo.ps1` with
313 a `working-tree-encoding` enabled Git client, then `foo.ps1` will be
314 stored as UTF-8 internally. A client without `working-tree-encoding`
315 support will checkout `foo.ps1` as UTF-8 encoded file. This will
316 typically cause trouble for the users of this file.
317 +
318 If a Git client that does not support the `working-tree-encoding`
319 attribute adds a new file `bar.ps1`, then `bar.ps1` will be
320 stored "as-is" internally (in this example probably as UTF-16).
321 A client with `working-tree-encoding` support will interpret the
322 internal contents as UTF-8 and try to convert it to UTF-16 on checkout.
323 That operation will fail and cause an error.
324
325 - Reencoding content to non-UTF encodings can cause errors as the
326 conversion might not be UTF-8 round trip safe. If you suspect your
327 encoding to not be round trip safe, then add it to
328 `core.checkRoundtripEncoding` to make Git check the round trip
329 encoding (see linkgit:git-config[1]). SHIFT-JIS (Japanese character
330 set) is known to have round trip issues with UTF-8 and is checked by
331 default.
332
333 - Reencoding content requires resources that might slow down certain
334 Git operations (e.g 'git checkout' or 'git add').
335
336 Use the `working-tree-encoding` attribute only if you cannot store a file
337 in UTF-8 encoding and if you want Git to be able to process the content
338 as text.
339
340 As an example, use the following attributes if your '*.ps1' files are
341 UTF-16 encoded with byte order mark (BOM) and you want Git to perform
342 automatic line ending conversion based on your platform.
343
344 ------------------------
345 *.ps1 text working-tree-encoding=UTF-16
346 ------------------------
347
348 Use the following attributes if your '*.ps1' files are UTF-16 little
349 endian encoded without BOM and you want Git to use Windows line endings
350 in the working directory (use `UTF-16LE-BOM` instead of `UTF-16LE` if
351 you want UTF-16 little endian with BOM).
352 Please note, it is highly recommended to
353 explicitly define the line endings with `eol` if the `working-tree-encoding`
354 attribute is used to avoid ambiguity.
355
356 ------------------------
357 *.ps1 text working-tree-encoding=UTF-16LE eol=CRLF
358 ------------------------
359
360 You can get a list of all available encodings on your platform with the
361 following command:
362
363 ------------------------
364 iconv --list
365 ------------------------
366
367 If you do not know the encoding of a file, then you can use the `file`
368 command to guess the encoding:
369
370 ------------------------
371 file foo.ps1
372 ------------------------
373
374
375 `ident`
376 ^^^^^^^
377
378 When the attribute `ident` is set for a path, Git replaces
379 `$Id$` in the blob object with `$Id:`, followed by the
380 40-character hexadecimal blob object name, followed by a dollar
381 sign `$` upon checkout. Any byte sequence that begins with
382 `$Id:` and ends with `$` in the worktree file is replaced
383 with `$Id$` upon check-in.
384
385
386 `filter`
387 ^^^^^^^^
388
389 A `filter` attribute can be set to a string value that names a
390 filter driver specified in the configuration.
391
392 A filter driver consists of a `clean` command and a `smudge`
393 command, either of which can be left unspecified. Upon
394 checkout, when the `smudge` command is specified, the command is
395 fed the blob object from its standard input, and its standard
396 output is used to update the worktree file. Similarly, the
397 `clean` command is used to convert the contents of worktree file
398 upon checkin. By default these commands process only a single
399 blob and terminate. If a long running `process` filter is used
400 in place of `clean` and/or `smudge` filters, then Git can process
401 all blobs with a single filter command invocation for the entire
402 life of a single Git command, for example `git add --all`. If a
403 long running `process` filter is configured then it always takes
404 precedence over a configured single blob filter. See section
405 below for the description of the protocol used to communicate with
406 a `process` filter.
407
408 One use of the content filtering is to massage the content into a shape
409 that is more convenient for the platform, filesystem, and the user to use.
410 For this mode of operation, the key phrase here is "more convenient" and
411 not "turning something unusable into usable". In other words, the intent
412 is that if someone unsets the filter driver definition, or does not have
413 the appropriate filter program, the project should still be usable.
414
415 Another use of the content filtering is to store the content that cannot
416 be directly used in the repository (e.g. a UUID that refers to the true
417 content stored outside Git, or an encrypted content) and turn it into a
418 usable form upon checkout (e.g. download the external content, or decrypt
419 the encrypted content).
420
421 These two filters behave differently, and by default, a filter is taken as
422 the former, massaging the contents into more convenient shape. A missing
423 filter driver definition in the config, or a filter driver that exits with
424 a non-zero status, is not an error but makes the filter a no-op passthru.
425
426 You can declare that a filter turns a content that by itself is unusable
427 into a usable content by setting the filter.<driver>.required configuration
428 variable to `true`.
429
430 Note: Whenever the clean filter is changed, the repo should be renormalized:
431 $ git add --renormalize .
432
433 For example, in .gitattributes, you would assign the `filter`
434 attribute for paths.
435
436 ------------------------
437 *.c filter=indent
438 ------------------------
439
440 Then you would define a "filter.indent.clean" and "filter.indent.smudge"
441 configuration in your .git/config to specify a pair of commands to
442 modify the contents of C programs when the source files are checked
443 in ("clean" is run) and checked out (no change is made because the
444 command is "cat").
445
446 ------------------------
447 [filter "indent"]
448 clean = indent
449 smudge = cat
450 ------------------------
451
452 For best results, `clean` should not alter its output further if it is
453 run twice ("clean->clean" should be equivalent to "clean"), and
454 multiple `smudge` commands should not alter `clean`'s output
455 ("smudge->smudge->clean" should be equivalent to "clean"). See the
456 section on merging below.
457
458 The "indent" filter is well-behaved in this regard: it will not modify
459 input that is already correctly indented. In this case, the lack of a
460 smudge filter means that the clean filter _must_ accept its own output
461 without modifying it.
462
463 If a filter _must_ succeed in order to make the stored contents usable,
464 you can declare that the filter is `required`, in the configuration:
465
466 ------------------------
467 [filter "crypt"]
468 clean = openssl enc ...
469 smudge = openssl enc -d ...
470 required
471 ------------------------
472
473 Sequence "%f" on the filter command line is replaced with the name of
474 the file the filter is working on. A filter might use this in keyword
475 substitution. For example:
476
477 ------------------------
478 [filter "p4"]
479 clean = git-p4-filter --clean %f
480 smudge = git-p4-filter --smudge %f
481 ------------------------
482
483 Note that "%f" is the name of the path that is being worked on. Depending
484 on the version that is being filtered, the corresponding file on disk may
485 not exist, or may have different contents. So, smudge and clean commands
486 should not try to access the file on disk, but only act as filters on the
487 content provided to them on standard input.
488
489 Long Running Filter Process
490 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
491
492 If the filter command (a string value) is defined via
493 `filter.<driver>.process` then Git can process all blobs with a
494 single filter invocation for the entire life of a single Git
495 command. This is achieved by using the long-running process protocol
496 (described in technical/long-running-process-protocol.txt).
497
498 When Git encounters the first file that needs to be cleaned or smudged,
499 it starts the filter and performs the handshake. In the handshake, the
500 welcome message sent by Git is "git-filter-client", only version 2 is
501 suppported, and the supported capabilities are "clean", "smudge", and
502 "delay".
503
504 Afterwards Git sends a list of "key=value" pairs terminated with
505 a flush packet. The list will contain at least the filter command
506 (based on the supported capabilities) and the pathname of the file
507 to filter relative to the repository root. Right after the flush packet
508 Git sends the content split in zero or more pkt-line packets and a
509 flush packet to terminate content. Please note, that the filter
510 must not send any response before it received the content and the
511 final flush packet. Also note that the "value" of a "key=value" pair
512 can contain the "=" character whereas the key would never contain
513 that character.
514 ------------------------
515 packet: git> command=smudge
516 packet: git> pathname=path/testfile.dat
517 packet: git> 0000
518 packet: git> CONTENT
519 packet: git> 0000
520 ------------------------
521
522 The filter is expected to respond with a list of "key=value" pairs
523 terminated with a flush packet. If the filter does not experience
524 problems then the list must contain a "success" status. Right after
525 these packets the filter is expected to send the content in zero
526 or more pkt-line packets and a flush packet at the end. Finally, a
527 second list of "key=value" pairs terminated with a flush packet
528 is expected. The filter can change the status in the second list
529 or keep the status as is with an empty list. Please note that the
530 empty list must be terminated with a flush packet regardless.
531
532 ------------------------
533 packet: git< status=success
534 packet: git< 0000
535 packet: git< SMUDGED_CONTENT
536 packet: git< 0000
537 packet: git< 0000 # empty list, keep "status=success" unchanged!
538 ------------------------
539
540 If the result content is empty then the filter is expected to respond
541 with a "success" status and a flush packet to signal the empty content.
542 ------------------------
543 packet: git< status=success
544 packet: git< 0000
545 packet: git< 0000 # empty content!
546 packet: git< 0000 # empty list, keep "status=success" unchanged!
547 ------------------------
548
549 In case the filter cannot or does not want to process the content,
550 it is expected to respond with an "error" status.
551 ------------------------
552 packet: git< status=error
553 packet: git< 0000
554 ------------------------
555
556 If the filter experiences an error during processing, then it can
557 send the status "error" after the content was (partially or
558 completely) sent.
559 ------------------------
560 packet: git< status=success
561 packet: git< 0000
562 packet: git< HALF_WRITTEN_ERRONEOUS_CONTENT
563 packet: git< 0000
564 packet: git< status=error
565 packet: git< 0000
566 ------------------------
567
568 In case the filter cannot or does not want to process the content
569 as well as any future content for the lifetime of the Git process,
570 then it is expected to respond with an "abort" status at any point
571 in the protocol.
572 ------------------------
573 packet: git< status=abort
574 packet: git< 0000
575 ------------------------
576
577 Git neither stops nor restarts the filter process in case the
578 "error"/"abort" status is set. However, Git sets its exit code
579 according to the `filter.<driver>.required` flag, mimicking the
580 behavior of the `filter.<driver>.clean` / `filter.<driver>.smudge`
581 mechanism.
582
583 If the filter dies during the communication or does not adhere to
584 the protocol then Git will stop the filter process and restart it
585 with the next file that needs to be processed. Depending on the
586 `filter.<driver>.required` flag Git will interpret that as error.
587
588 Delay
589 ^^^^^
590
591 If the filter supports the "delay" capability, then Git can send the
592 flag "can-delay" after the filter command and pathname. This flag
593 denotes that the filter can delay filtering the current blob (e.g. to
594 compensate network latencies) by responding with no content but with
595 the status "delayed" and a flush packet.
596 ------------------------
597 packet: git> command=smudge
598 packet: git> pathname=path/testfile.dat
599 packet: git> can-delay=1
600 packet: git> 0000
601 packet: git> CONTENT
602 packet: git> 0000
603 packet: git< status=delayed
604 packet: git< 0000
605 ------------------------
606
607 If the filter supports the "delay" capability then it must support the
608 "list_available_blobs" command. If Git sends this command, then the
609 filter is expected to return a list of pathnames representing blobs
610 that have been delayed earlier and are now available.
611 The list must be terminated with a flush packet followed
612 by a "success" status that is also terminated with a flush packet. If
613 no blobs for the delayed paths are available, yet, then the filter is
614 expected to block the response until at least one blob becomes
615 available. The filter can tell Git that it has no more delayed blobs
616 by sending an empty list. As soon as the filter responds with an empty
617 list, Git stops asking. All blobs that Git has not received at this
618 point are considered missing and will result in an error.
619
620 ------------------------
621 packet: git> command=list_available_blobs
622 packet: git> 0000
623 packet: git< pathname=path/testfile.dat
624 packet: git< pathname=path/otherfile.dat
625 packet: git< 0000
626 packet: git< status=success
627 packet: git< 0000
628 ------------------------
629
630 After Git received the pathnames, it will request the corresponding
631 blobs again. These requests contain a pathname and an empty content
632 section. The filter is expected to respond with the smudged content
633 in the usual way as explained above.
634 ------------------------
635 packet: git> command=smudge
636 packet: git> pathname=path/testfile.dat
637 packet: git> 0000
638 packet: git> 0000 # empty content!
639 packet: git< status=success
640 packet: git< 0000
641 packet: git< SMUDGED_CONTENT
642 packet: git< 0000
643 packet: git< 0000 # empty list, keep "status=success" unchanged!
644 ------------------------
645
646 Example
647 ^^^^^^^
648
649 A long running filter demo implementation can be found in
650 `contrib/long-running-filter/example.pl` located in the Git
651 core repository. If you develop your own long running filter
652 process then the `GIT_TRACE_PACKET` environment variables can be
653 very helpful for debugging (see linkgit:git[1]).
654
655 Please note that you cannot use an existing `filter.<driver>.clean`
656 or `filter.<driver>.smudge` command with `filter.<driver>.process`
657 because the former two use a different inter process communication
658 protocol than the latter one.
659
660
661 Interaction between checkin/checkout attributes
662 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
663
664 In the check-in codepath, the worktree file is first converted
665 with `filter` driver (if specified and corresponding driver
666 defined), then the result is processed with `ident` (if
667 specified), and then finally with `text` (again, if specified
668 and applicable).
669
670 In the check-out codepath, the blob content is first converted
671 with `text`, and then `ident` and fed to `filter`.
672
673
674 Merging branches with differing checkin/checkout attributes
675 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
676
677 If you have added attributes to a file that cause the canonical
678 repository format for that file to change, such as adding a
679 clean/smudge filter or text/eol/ident attributes, merging anything
680 where the attribute is not in place would normally cause merge
681 conflicts.
682
683 To prevent these unnecessary merge conflicts, Git can be told to run a
684 virtual check-out and check-in of all three stages of a file when
685 resolving a three-way merge by setting the `merge.renormalize`
686 configuration variable. This prevents changes caused by check-in
687 conversion from causing spurious merge conflicts when a converted file
688 is merged with an unconverted file.
689
690 As long as a "smudge->clean" results in the same output as a "clean"
691 even on files that are already smudged, this strategy will
692 automatically resolve all filter-related conflicts. Filters that do
693 not act in this way may cause additional merge conflicts that must be
694 resolved manually.
695
696
697 Generating diff text
698 ~~~~~~~~~~~~~~~~~~~~
699
700 `diff`
701 ^^^^^^
702
703 The attribute `diff` affects how Git generates diffs for particular
704 files. It can tell Git whether to generate a textual patch for the path
705 or to treat the path as a binary file. It can also affect what line is
706 shown on the hunk header `@@ -k,l +n,m @@` line, tell Git to use an
707 external command to generate the diff, or ask Git to convert binary
708 files to a text format before generating the diff.
709
710 Set::
711
712 A path to which the `diff` attribute is set is treated
713 as text, even when they contain byte values that
714 normally never appear in text files, such as NUL.
715
716 Unset::
717
718 A path to which the `diff` attribute is unset will
719 generate `Binary files differ` (or a binary patch, if
720 binary patches are enabled).
721
722 Unspecified::
723
724 A path to which the `diff` attribute is unspecified
725 first gets its contents inspected, and if it looks like
726 text and is smaller than core.bigFileThreshold, it is treated
727 as text. Otherwise it would generate `Binary files differ`.
728
729 String::
730
731 Diff is shown using the specified diff driver. Each driver may
732 specify one or more options, as described in the following
733 section. The options for the diff driver "foo" are defined
734 by the configuration variables in the "diff.foo" section of the
735 Git config file.
736
737
738 Defining an external diff driver
739 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
740
741 The definition of a diff driver is done in `gitconfig`, not
742 `gitattributes` file, so strictly speaking this manual page is a
743 wrong place to talk about it. However...
744
745 To define an external diff driver `jcdiff`, add a section to your
746 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
747
748 ----------------------------------------------------------------
749 [diff "jcdiff"]
750 command = j-c-diff
751 ----------------------------------------------------------------
752
753 When Git needs to show you a diff for the path with `diff`
754 attribute set to `jcdiff`, it calls the command you specified
755 with the above configuration, i.e. `j-c-diff`, with 7
756 parameters, just like `GIT_EXTERNAL_DIFF` program is called.
757 See linkgit:git[1] for details.
758
759
760 Defining a custom hunk-header
761 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
762
763 Each group of changes (called a "hunk") in the textual diff output
764 is prefixed with a line of the form:
765
766 @@ -k,l +n,m @@ TEXT
767
768 This is called a 'hunk header'. The "TEXT" portion is by default a line
769 that begins with an alphabet, an underscore or a dollar sign; this
770 matches what GNU 'diff -p' output uses. This default selection however
771 is not suited for some contents, and you can use a customized pattern
772 to make a selection.
773
774 First, in .gitattributes, you would assign the `diff` attribute
775 for paths.
776
777 ------------------------
778 *.tex diff=tex
779 ------------------------
780
781 Then, you would define a "diff.tex.xfuncname" configuration to
782 specify a regular expression that matches a line that you would
783 want to appear as the hunk header "TEXT". Add a section to your
784 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
785
786 ------------------------
787 [diff "tex"]
788 xfuncname = "^(\\\\(sub)*section\\{.*)$"
789 ------------------------
790
791 Note. A single level of backslashes are eaten by the
792 configuration file parser, so you would need to double the
793 backslashes; the pattern above picks a line that begins with a
794 backslash, and zero or more occurrences of `sub` followed by
795 `section` followed by open brace, to the end of line.
796
797 There are a few built-in patterns to make this easier, and `tex`
798 is one of them, so you do not have to write the above in your
799 configuration file (you still need to enable this with the
800 attribute mechanism, via `.gitattributes`). The following built in
801 patterns are available:
802
803 - `ada` suitable for source code in the Ada language.
804
805 - `bibtex` suitable for files with BibTeX coded references.
806
807 - `cpp` suitable for source code in the C and C++ languages.
808
809 - `csharp` suitable for source code in the C# language.
810
811 - `css` suitable for cascading style sheets.
812
813 - `dts` suitable for devicetree (DTS) files.
814
815 - `fortran` suitable for source code in the Fortran language.
816
817 - `fountain` suitable for Fountain documents.
818
819 - `golang` suitable for source code in the Go language.
820
821 - `html` suitable for HTML/XHTML documents.
822
823 - `java` suitable for source code in the Java language.
824
825 - `matlab` suitable for source code in the MATLAB and Octave languages.
826
827 - `objc` suitable for source code in the Objective-C language.
828
829 - `pascal` suitable for source code in the Pascal/Delphi language.
830
831 - `perl` suitable for source code in the Perl language.
832
833 - `php` suitable for source code in the PHP language.
834
835 - `python` suitable for source code in the Python language.
836
837 - `ruby` suitable for source code in the Ruby language.
838
839 - `rust` suitable for source code in the Rust language.
840
841 - `tex` suitable for source code for LaTeX documents.
842
843
844 Customizing word diff
845 ^^^^^^^^^^^^^^^^^^^^^
846
847 You can customize the rules that `git diff --word-diff` uses to
848 split words in a line, by specifying an appropriate regular expression
849 in the "diff.*.wordRegex" configuration variable. For example, in TeX
850 a backslash followed by a sequence of letters forms a command, but
851 several such commands can be run together without intervening
852 whitespace. To separate them, use a regular expression in your
853 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
854
855 ------------------------
856 [diff "tex"]
857 wordRegex = "\\\\[a-zA-Z]+|[{}]|\\\\.|[^\\{}[:space:]]+"
858 ------------------------
859
860 A built-in pattern is provided for all languages listed in the
861 previous section.
862
863
864 Performing text diffs of binary files
865 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
866
867 Sometimes it is desirable to see the diff of a text-converted
868 version of some binary files. For example, a word processor
869 document can be converted to an ASCII text representation, and
870 the diff of the text shown. Even though this conversion loses
871 some information, the resulting diff is useful for human
872 viewing (but cannot be applied directly).
873
874 The `textconv` config option is used to define a program for
875 performing such a conversion. The program should take a single
876 argument, the name of a file to convert, and produce the
877 resulting text on stdout.
878
879 For example, to show the diff of the exif information of a
880 file instead of the binary information (assuming you have the
881 exif tool installed), add the following section to your
882 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file):
883
884 ------------------------
885 [diff "jpg"]
886 textconv = exif
887 ------------------------
888
889 NOTE: The text conversion is generally a one-way conversion;
890 in this example, we lose the actual image contents and focus
891 just on the text data. This means that diffs generated by
892 textconv are _not_ suitable for applying. For this reason,
893 only `git diff` and the `git log` family of commands (i.e.,
894 log, whatchanged, show) will perform text conversion. `git
895 format-patch` will never generate this output. If you want to
896 send somebody a text-converted diff of a binary file (e.g.,
897 because it quickly conveys the changes you have made), you
898 should generate it separately and send it as a comment _in
899 addition to_ the usual binary diff that you might send.
900
901 Because text conversion can be slow, especially when doing a
902 large number of them with `git log -p`, Git provides a mechanism
903 to cache the output and use it in future diffs. To enable
904 caching, set the "cachetextconv" variable in your diff driver's
905 config. For example:
906
907 ------------------------
908 [diff "jpg"]
909 textconv = exif
910 cachetextconv = true
911 ------------------------
912
913 This will cache the result of running "exif" on each blob
914 indefinitely. If you change the textconv config variable for a
915 diff driver, Git will automatically invalidate the cache entries
916 and re-run the textconv filter. If you want to invalidate the
917 cache manually (e.g., because your version of "exif" was updated
918 and now produces better output), you can remove the cache
919 manually with `git update-ref -d refs/notes/textconv/jpg` (where
920 "jpg" is the name of the diff driver, as in the example above).
921
922 Choosing textconv versus external diff
923 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
924
925 If you want to show differences between binary or specially-formatted
926 blobs in your repository, you can choose to use either an external diff
927 command, or to use textconv to convert them to a diff-able text format.
928 Which method you choose depends on your exact situation.
929
930 The advantage of using an external diff command is flexibility. You are
931 not bound to find line-oriented changes, nor is it necessary for the
932 output to resemble unified diff. You are free to locate and report
933 changes in the most appropriate way for your data format.
934
935 A textconv, by comparison, is much more limiting. You provide a
936 transformation of the data into a line-oriented text format, and Git
937 uses its regular diff tools to generate the output. There are several
938 advantages to choosing this method:
939
940 1. Ease of use. It is often much simpler to write a binary to text
941 transformation than it is to perform your own diff. In many cases,
942 existing programs can be used as textconv filters (e.g., exif,
943 odt2txt).
944
945 2. Git diff features. By performing only the transformation step
946 yourself, you can still utilize many of Git's diff features,
947 including colorization, word-diff, and combined diffs for merges.
948
949 3. Caching. Textconv caching can speed up repeated diffs, such as those
950 you might trigger by running `git log -p`.
951
952
953 Marking files as binary
954 ^^^^^^^^^^^^^^^^^^^^^^^
955
956 Git usually guesses correctly whether a blob contains text or binary
957 data by examining the beginning of the contents. However, sometimes you
958 may want to override its decision, either because a blob contains binary
959 data later in the file, or because the content, while technically
960 composed of text characters, is opaque to a human reader. For example,
961 many postscript files contain only ASCII characters, but produce noisy
962 and meaningless diffs.
963
964 The simplest way to mark a file as binary is to unset the diff
965 attribute in the `.gitattributes` file:
966
967 ------------------------
968 *.ps -diff
969 ------------------------
970
971 This will cause Git to generate `Binary files differ` (or a binary
972 patch, if binary patches are enabled) instead of a regular diff.
973
974 However, one may also want to specify other diff driver attributes. For
975 example, you might want to use `textconv` to convert postscript files to
976 an ASCII representation for human viewing, but otherwise treat them as
977 binary files. You cannot specify both `-diff` and `diff=ps` attributes.
978 The solution is to use the `diff.*.binary` config option:
979
980 ------------------------
981 [diff "ps"]
982 textconv = ps2ascii
983 binary = true
984 ------------------------
985
986 Performing a three-way merge
987 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
988
989 `merge`
990 ^^^^^^^
991
992 The attribute `merge` affects how three versions of a file are
993 merged when a file-level merge is necessary during `git merge`,
994 and other commands such as `git revert` and `git cherry-pick`.
995
996 Set::
997
998 Built-in 3-way merge driver is used to merge the
999 contents in a way similar to 'merge' command of `RCS`
1000 suite. This is suitable for ordinary text files.
1001
1002 Unset::
1003
1004 Take the version from the current branch as the
1005 tentative merge result, and declare that the merge has
1006 conflicts. This is suitable for binary files that do
1007 not have a well-defined merge semantics.
1008
1009 Unspecified::
1010
1011 By default, this uses the same built-in 3-way merge
1012 driver as is the case when the `merge` attribute is set.
1013 However, the `merge.default` configuration variable can name
1014 different merge driver to be used with paths for which the
1015 `merge` attribute is unspecified.
1016
1017 String::
1018
1019 3-way merge is performed using the specified custom
1020 merge driver. The built-in 3-way merge driver can be
1021 explicitly specified by asking for "text" driver; the
1022 built-in "take the current branch" driver can be
1023 requested with "binary".
1024
1025
1026 Built-in merge drivers
1027 ^^^^^^^^^^^^^^^^^^^^^^
1028
1029 There are a few built-in low-level merge drivers defined that
1030 can be asked for via the `merge` attribute.
1031
1032 text::
1033
1034 Usual 3-way file level merge for text files. Conflicted
1035 regions are marked with conflict markers `<<<<<<<`,
1036 `=======` and `>>>>>>>`. The version from your branch
1037 appears before the `=======` marker, and the version
1038 from the merged branch appears after the `=======`
1039 marker.
1040
1041 binary::
1042
1043 Keep the version from your branch in the work tree, but
1044 leave the path in the conflicted state for the user to
1045 sort out.
1046
1047 union::
1048
1049 Run 3-way file level merge for text files, but take
1050 lines from both versions, instead of leaving conflict
1051 markers. This tends to leave the added lines in the
1052 resulting file in random order and the user should
1053 verify the result. Do not use this if you do not
1054 understand the implications.
1055
1056
1057 Defining a custom merge driver
1058 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1059
1060 The definition of a merge driver is done in the `.git/config`
1061 file, not in the `gitattributes` file, so strictly speaking this
1062 manual page is a wrong place to talk about it. However...
1063
1064 To define a custom merge driver `filfre`, add a section to your
1065 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
1066
1067 ----------------------------------------------------------------
1068 [merge "filfre"]
1069 name = feel-free merge driver
1070 driver = filfre %O %A %B %L %P
1071 recursive = binary
1072 ----------------------------------------------------------------
1073
1074 The `merge.*.name` variable gives the driver a human-readable
1075 name.
1076
1077 The `merge.*.driver` variable's value is used to construct a
1078 command to run to merge ancestor's version (`%O`), current
1079 version (`%A`) and the other branches' version (`%B`). These
1080 three tokens are replaced with the names of temporary files that
1081 hold the contents of these versions when the command line is
1082 built. Additionally, %L will be replaced with the conflict marker
1083 size (see below).
1084
1085 The merge driver is expected to leave the result of the merge in
1086 the file named with `%A` by overwriting it, and exit with zero
1087 status if it managed to merge them cleanly, or non-zero if there
1088 were conflicts.
1089
1090 The `merge.*.recursive` variable specifies what other merge
1091 driver to use when the merge driver is called for an internal
1092 merge between common ancestors, when there are more than one.
1093 When left unspecified, the driver itself is used for both
1094 internal merge and the final merge.
1095
1096 The merge driver can learn the pathname in which the merged result
1097 will be stored via placeholder `%P`.
1098
1099
1100 `conflict-marker-size`
1101 ^^^^^^^^^^^^^^^^^^^^^^
1102
1103 This attribute controls the length of conflict markers left in
1104 the work tree file during a conflicted merge. Only setting to
1105 the value to a positive integer has any meaningful effect.
1106
1107 For example, this line in `.gitattributes` can be used to tell the merge
1108 machinery to leave much longer (instead of the usual 7-character-long)
1109 conflict markers when merging the file `Documentation/git-merge.txt`
1110 results in a conflict.
1111
1112 ------------------------
1113 Documentation/git-merge.txt conflict-marker-size=32
1114 ------------------------
1115
1116
1117 Checking whitespace errors
1118 ~~~~~~~~~~~~~~~~~~~~~~~~~~
1119
1120 `whitespace`
1121 ^^^^^^^^^^^^
1122
1123 The `core.whitespace` configuration variable allows you to define what
1124 'diff' and 'apply' should consider whitespace errors for all paths in
1125 the project (See linkgit:git-config[1]). This attribute gives you finer
1126 control per path.
1127
1128 Set::
1129
1130 Notice all types of potential whitespace errors known to Git.
1131 The tab width is taken from the value of the `core.whitespace`
1132 configuration variable.
1133
1134 Unset::
1135
1136 Do not notice anything as error.
1137
1138 Unspecified::
1139
1140 Use the value of the `core.whitespace` configuration variable to
1141 decide what to notice as error.
1142
1143 String::
1144
1145 Specify a comma separate list of common whitespace problems to
1146 notice in the same format as the `core.whitespace` configuration
1147 variable.
1148
1149
1150 Creating an archive
1151 ~~~~~~~~~~~~~~~~~~~
1152
1153 `export-ignore`
1154 ^^^^^^^^^^^^^^^
1155
1156 Files and directories with the attribute `export-ignore` won't be added to
1157 archive files.
1158
1159 `export-subst`
1160 ^^^^^^^^^^^^^^
1161
1162 If the attribute `export-subst` is set for a file then Git will expand
1163 several placeholders when adding this file to an archive. The
1164 expansion depends on the availability of a commit ID, i.e., if
1165 linkgit:git-archive[1] has been given a tree instead of a commit or a
1166 tag then no replacement will be done. The placeholders are the same
1167 as those for the option `--pretty=format:` of linkgit:git-log[1],
1168 except that they need to be wrapped like this: `$Format:PLACEHOLDERS$`
1169 in the file. E.g. the string `$Format:%H$` will be replaced by the
1170 commit hash.
1171
1172
1173 Packing objects
1174 ~~~~~~~~~~~~~~~
1175
1176 `delta`
1177 ^^^^^^^
1178
1179 Delta compression will not be attempted for blobs for paths with the
1180 attribute `delta` set to false.
1181
1182
1183 Viewing files in GUI tools
1184 ~~~~~~~~~~~~~~~~~~~~~~~~~~
1185
1186 `encoding`
1187 ^^^^^^^^^^
1188
1189 The value of this attribute specifies the character encoding that should
1190 be used by GUI tools (e.g. linkgit:gitk[1] and linkgit:git-gui[1]) to
1191 display the contents of the relevant file. Note that due to performance
1192 considerations linkgit:gitk[1] does not use this attribute unless you
1193 manually enable per-file encodings in its options.
1194
1195 If this attribute is not set or has an invalid value, the value of the
1196 `gui.encoding` configuration variable is used instead
1197 (See linkgit:git-config[1]).
1198
1199
1200 USING MACRO ATTRIBUTES
1201 ----------------------
1202
1203 You do not want any end-of-line conversions applied to, nor textual diffs
1204 produced for, any binary file you track. You would need to specify e.g.
1205
1206 ------------
1207 *.jpg -text -diff
1208 ------------
1209
1210 but that may become cumbersome, when you have many attributes. Using
1211 macro attributes, you can define an attribute that, when set, also
1212 sets or unsets a number of other attributes at the same time. The
1213 system knows a built-in macro attribute, `binary`:
1214
1215 ------------
1216 *.jpg binary
1217 ------------
1218
1219 Setting the "binary" attribute also unsets the "text" and "diff"
1220 attributes as above. Note that macro attributes can only be "Set",
1221 though setting one might have the effect of setting or unsetting other
1222 attributes or even returning other attributes to the "Unspecified"
1223 state.
1224
1225
1226 DEFINING MACRO ATTRIBUTES
1227 -------------------------
1228
1229 Custom macro attributes can be defined only in top-level gitattributes
1230 files (`$GIT_DIR/info/attributes`, the `.gitattributes` file at the
1231 top level of the working tree, or the global or system-wide
1232 gitattributes files), not in `.gitattributes` files in working tree
1233 subdirectories. The built-in macro attribute "binary" is equivalent
1234 to:
1235
1236 ------------
1237 [attr]binary -diff -merge -text
1238 ------------
1239
1240
1241 EXAMPLES
1242 --------
1243
1244 If you have these three `gitattributes` file:
1245
1246 ----------------------------------------------------------------
1247 (in $GIT_DIR/info/attributes)
1248
1249 a* foo !bar -baz
1250
1251 (in .gitattributes)
1252 abc foo bar baz
1253
1254 (in t/.gitattributes)
1255 ab* merge=filfre
1256 abc -foo -bar
1257 *.c frotz
1258 ----------------------------------------------------------------
1259
1260 the attributes given to path `t/abc` are computed as follows:
1261
1262 1. By examining `t/.gitattributes` (which is in the same
1263 directory as the path in question), Git finds that the first
1264 line matches. `merge` attribute is set. It also finds that
1265 the second line matches, and attributes `foo` and `bar`
1266 are unset.
1267
1268 2. Then it examines `.gitattributes` (which is in the parent
1269 directory), and finds that the first line matches, but
1270 `t/.gitattributes` file already decided how `merge`, `foo`
1271 and `bar` attributes should be given to this path, so it
1272 leaves `foo` and `bar` unset. Attribute `baz` is set.
1273
1274 3. Finally it examines `$GIT_DIR/info/attributes`. This file
1275 is used to override the in-tree settings. The first line is
1276 a match, and `foo` is set, `bar` is reverted to unspecified
1277 state, and `baz` is unset.
1278
1279 As the result, the attributes assignment to `t/abc` becomes:
1280
1281 ----------------------------------------------------------------
1282 foo set to true
1283 bar unspecified
1284 baz set to false
1285 merge set to string value "filfre"
1286 frotz unspecified
1287 ----------------------------------------------------------------
1288
1289
1290 SEE ALSO
1291 --------
1292 linkgit:git-check-attr[1].
1293
1294 GIT
1295 ---
1296 Part of the linkgit:git[1] suite