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

USING MACRO ATTRIBUTES

1034       You do not want any end-of-line conversions applied to, nor textual
1035       diffs produced for, any binary file you track. You would need to
1036       specify e.g.
1037
1038           *.jpg -text -diff
1039
1040       but that may become cumbersome, when you have many attributes. Using
1041       macro attributes, you can define an attribute that, when set, also sets
1042       or unsets a number of other attributes at the same time. The system
1043       knows a built-in macro attribute, binary:
1044
1045           *.jpg binary
1046
1047       Setting the "binary" attribute also unsets the "text" and "diff"
1048       attributes as above. Note that macro attributes can only be "Set",
1049       though setting one might have the effect of setting or unsetting other
1050       attributes or even returning other attributes to the "Unspecified"
1051       state.
1052

DEFINING MACRO ATTRIBUTES

1054       Custom macro attributes can be defined only in top-level gitattributes
1055       files ($GIT_DIR/info/attributes, the .gitattributes file at the top
1056       level of the working tree, or the global or system-wide gitattributes
1057       files), not in .gitattributes files in working tree subdirectories. The
1058       built-in macro attribute "binary" is equivalent to:
1059
1060           [attr]binary -diff -merge -text
1061

NOTES

1063       Git does not follow symbolic links when accessing a .gitattributes file
1064       in the working tree. This keeps behavior consistent when the file is
1065       accessed from the index or a tree versus from the filesystem.
1066

EXAMPLES

1068       If you have these three gitattributes file:
1069
1070           (in $GIT_DIR/info/attributes)
1071
1072           a*      foo !bar -baz
1073
1074           (in .gitattributes)
1075           abc     foo bar baz
1076
1077           (in t/.gitattributes)
1078           ab*     merge=filfre
1079           abc     -foo -bar
1080           *.c     frotz
1081
1082       the attributes given to path t/abc are computed as follows:
1083
1084        1. By examining t/.gitattributes (which is in the same directory as
1085           the path in question), Git finds that the first line matches.
1086           merge attribute is set. It also finds that the second line matches,
1087           and attributes foo and bar are unset.
1088
1089        2. Then it examines .gitattributes (which is in the parent directory),
1090           and finds that the first line matches, but t/.gitattributes file
1091           already decided how merge, foo and bar attributes should be given
1092           to this path, so it leaves foo and bar unset. Attribute baz is set.
1093
1094        3. Finally it examines $GIT_DIR/info/attributes. This file is used to
1095           override the in-tree settings. The first line is a match, and foo
1096           is set, bar is reverted to unspecified state, and baz is unset.
1097
1098       As the result, the attributes assignment to t/abc becomes:
1099
1100           foo     set to true
1101           bar     unspecified
1102           baz     set to false
1103           merge   set to string value "filfre"
1104           frotz   unspecified
1105

SEE ALSO

1107       git-check-attr(1).
1108

GIT

1110       Part of the git(1) suite
1111
1112
1113
1114Git 2.39.1                        2023-01-13                  GITATTRIBUTES(5)
Impressum