1GITATTRIBUTES(5)                  Git Manual                  GITATTRIBUTES(5)
2
3
4

NAME

6       gitattributes - Defining attributes per path
7

SYNOPSIS

9       $GIT_DIR/info/attributes, .gitattributes
10

DESCRIPTION

12       A gitattributes file is a simple text file that gives attributes to
13       pathnames.
14
15       Each line in gitattributes file is of form:
16
17           pattern attr1 attr2 ...
18
19       That is, a pattern followed by an attributes list, separated by
20       whitespaces. Leading and trailing whitespaces are ignored. Lines that
21       begin with # are ignored. Patterns that begin with a double quote are
22       quoted in C style. When the pattern matches the path in question, the
23       attributes listed on the line are given to the path.
24
25       Each attribute can be in one of these states for a given path:
26
27       Set
28           The path has the attribute with special value "true"; this is
29           specified by listing only the name of the attribute in the
30           attribute list.
31
32       Unset
33           The path has the attribute with special value "false"; this is
34           specified by listing the name of the attribute prefixed with a dash
35           - in the attribute list.
36
37       Set to a value
38           The path has the attribute with specified string value; this is
39           specified by listing the name of the attribute followed by an equal
40           sign = and its value in the attribute list.
41
42       Unspecified
43           No pattern matches the path, and nothing says if the path has or
44           does not have the attribute, the attribute for the path is said to
45           be Unspecified.
46
47       When more than one pattern matches the path, a later line overrides an
48       earlier line. This overriding is done per attribute.
49
50       The rules by which the pattern matches paths are the same as in
51       .gitignore files (see gitignore(5)), with a few exceptions:
52
53       •   negative patterns are forbidden
54
55       •   patterns that match a directory do not recursively match paths
56           inside that directory (so using the trailing-slash path/ syntax is
57           pointless in an attributes file; use path/** instead)
58
59       When deciding what attributes are assigned to a path, Git consults
60       $GIT_DIR/info/attributes file (which has the highest precedence),
61       .gitattributes file in the same directory as the path in question, and
62       its parent directories up to the toplevel of the work tree (the further
63       the directory that contains .gitattributes is from the path in
64       question, the lower its precedence). Finally global and system-wide
65       files are considered (they have the lowest precedence).
66
67       When the .gitattributes file is missing from the work tree, the path in
68       the index is used as a fall-back. During checkout process,
69       .gitattributes in the index is used and then the file in the working
70       tree is used as a fall-back.
71
72       If you wish to affect only a single repository (i.e., to assign
73       attributes to files that are particular to one user’s workflow for that
74       repository), then attributes should be placed in the
75       $GIT_DIR/info/attributes file. Attributes which should be
76       version-controlled and distributed to other repositories (i.e.,
77       attributes of interest to all users) should go into .gitattributes
78       files. Attributes that should affect all repositories for a single user
79       should be placed in a file specified by the core.attributesFile
80       configuration option (see git-config(1)). Its default value is
81       $XDG_CONFIG_HOME/git/attributes. If $XDG_CONFIG_HOME is either not set
82       or empty, $HOME/.config/git/attributes is used instead. Attributes for
83       all users on a system should be placed in the
84       $(prefix)/etc/gitattributes file.
85
86       Sometimes you would need to override a setting of an attribute for a
87       path to Unspecified state. This can be done by listing the name of the
88       attribute prefixed with an exclamation point !.
89

EFFECTS

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

USING MACRO ATTRIBUTES

1071       You do not want any end-of-line conversions applied to, nor textual
1072       diffs produced for, any binary file you track. You would need to
1073       specify e.g.
1074
1075           *.jpg -text -diff
1076
1077       but that may become cumbersome, when you have many attributes. Using
1078       macro attributes, you can define an attribute that, when set, also sets
1079       or unsets a number of other attributes at the same time. The system
1080       knows a built-in macro attribute, binary:
1081
1082           *.jpg binary
1083
1084       Setting the "binary" attribute also unsets the "text" and "diff"
1085       attributes as above. Note that macro attributes can only be "Set",
1086       though setting one might have the effect of setting or unsetting other
1087       attributes or even returning other attributes to the "Unspecified"
1088       state.
1089

DEFINING MACRO ATTRIBUTES

1091       Custom macro attributes can be defined only in top-level gitattributes
1092       files ($GIT_DIR/info/attributes, the .gitattributes file at the top
1093       level of the working tree, or the global or system-wide gitattributes
1094       files), not in .gitattributes files in working tree subdirectories. The
1095       built-in macro attribute "binary" is equivalent to:
1096
1097           [attr]binary -diff -merge -text
1098

NOTES

1100       Git does not follow symbolic links when accessing a .gitattributes file
1101       in the working tree. This keeps behavior consistent when the file is
1102       accessed from the index or a tree versus from the filesystem.
1103

EXAMPLES

1105       If you have these three gitattributes file:
1106
1107           (in $GIT_DIR/info/attributes)
1108
1109           a*      foo !bar -baz
1110
1111           (in .gitattributes)
1112           abc     foo bar baz
1113
1114           (in t/.gitattributes)
1115           ab*     merge=filfre
1116           abc     -foo -bar
1117           *.c     frotz
1118
1119       the attributes given to path t/abc are computed as follows:
1120
1121        1. By examining t/.gitattributes (which is in the same directory as
1122           the path in question), Git finds that the first line matches.
1123           merge attribute is set. It also finds that the second line matches,
1124           and attributes foo and bar are unset.
1125
1126        2. Then it examines .gitattributes (which is in the parent directory),
1127           and finds that the first line matches, but t/.gitattributes file
1128           already decided how merge, foo and bar attributes should be given
1129           to this path, so it leaves foo and bar unset. Attribute baz is set.
1130
1131        3. Finally it examines $GIT_DIR/info/attributes. This file is used to
1132           override the in-tree settings. The first line is a match, and foo
1133           is set, bar is reverted to unspecified state, and baz is unset.
1134
1135       As the result, the attributes assignment to t/abc becomes:
1136
1137           foo     set to true
1138           bar     unspecified
1139           baz     set to false
1140           merge   set to string value "filfre"
1141           frotz   unspecified
1142

SEE ALSO

1144       git-check-attr(1).
1145

GIT

1147       Part of the git(1) suite
1148
1149
1150
1151Git 2.43.0                        11/20/2023                  GITATTRIBUTES(5)
Impressum