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