1GITATTRIBUTES(5) Git Manual GITATTRIBUTES(5)
2
6 gitattributes - defining attributes per path
7
9 $GIT_DIR/info/attributes, .gitattributes
10
12 A gitattributes file is a simple text file that gives attributes to
13 pathnames.
14 Each line in gitattributes file is of form:
16 pattern attr1 attr2 ...
18 That is, a pattern followed by an attributes list, separated by
20 whitespaces. When the pattern matches the path in question, the
21 attributes listed on the line are given to the path.
22 Each attribute can be in one of these states for a given path:
24 Set
26 The path has the attribute with special value "true"; this is
27 specified by listing only the name of the attribute in the
28 attribute list.
29 Unset
31 The path has the attribute with special value "false"; this is
32 specified by listing the name of the attribute prefixed with a dash
33 - in the attribute list.
34 Set to a value
36 The path has the attribute with specified string value; this is
37 specified by listing the name of the attribute followed by an equal
38 sign = and its value in the attribute list.
39 Unspecified
41 No pattern matches the path, and nothing says if the path has or
42 does not have the attribute, the attribute for the path is said to
43 be Unspecified.
44 When more than one pattern matches the path, a later line overrides an
46 earlier line. This overriding is done per attribute. The rules how the
47 pattern matches paths are the same as in .gitignore files; see
48 gitignore(5).
49 When deciding what attributes are assigned to a path, git consults
51 $GIT_DIR/info/attributes file (which has the highest precedence),
52 .gitattributes file in the same directory as the path in question, and
53 its parent directories up to the toplevel of the work tree (the further
54 the directory that contains .gitattributes is from the path in
55 question, the lower its precedence).
56 If you wish to affect only a single repository (i.e., to assign
58 attributes to files that are particular to one user’s workflow), then
59 attributes should be placed in the $GIT_DIR/info/attributes file.
60 Attributes which should be version-controlled and distributed to other
61 repositories (i.e., attributes of interest to all users) should go into
62 .gitattributes files.
63 Sometimes you would need to override an setting of an attribute for a
65 path to unspecified state. This can be done by listing the name of the
66 attribute prefixed with an exclamation point !.
67
69 Certain operations by git can be influenced by assigning particular
70 attributes to a path. Currently, the following operations are
71 attributes-aware.
72 Checking-out and checking-in
74 These attributes affect how the contents stored in the repository are
75 copied to the working tree files when commands such as git checkout and
76 git merge run. They also affect how git stores the contents you prepare
77 in the working tree in the repository upon git add and git commit.
78 crlf
80 This attribute controls the line-ending convention.
81 Set
83 Setting the crlf attribute on a path is meant to mark the path
84 as a "text" file. core.autocrlf conversion takes place without
85 guessing the content type by inspection.
86 Unset
88 Unsetting the crlf attribute on a path tells git not to attempt
89 any end-of-line conversion upon checkin or checkout.
90 Unspecified
92 Unspecified crlf attribute tells git to apply the core.autocrlf
93 conversion when the file content looks like text.
94 Set to string value "input"
96 This is similar to setting the attribute to true, but also
97 forces git to act as if core.autocrlf is set to input for the
98 path.
99 Any other value set to crlf attribute is ignored and git acts as if
101 the attribute is left unspecified.
102 The core.autocrlf conversion
104 If the configuration variable core.autocrlf is false, no conversion
105 is done.
106 When core.autocrlf is true, it means that the platform wants CRLF
108 line endings for files in the working tree, and you want to convert
109 them back to the normal LF line endings when checking in to the
110 repository.
111 When core.autocrlf is set to "input", line endings are converted to
113 LF upon checkin, but there is no conversion done upon checkout.
114 If core.safecrlf is set to "true" or "warn", git verifies if the
116 conversion is reversible for the current setting of core.autocrlf.
117 For "true", git rejects irreversible conversions; for "warn", git
118 only prints a warning but accepts an irreversible conversion. The
119 safety triggers to prevent such a conversion done to the files in
120 the work tree, but there are a few exceptions. Even though...
121 · git add itself does not touch the files in the work tree, the
123 next checkout would, so the safety triggers;
124 · git apply to update a text file with a patch does touch the
126 files in the work tree, but the operation is about text files
127 and CRLF conversion is about fixing the line ending
128 inconsistencies, so the safety does not trigger;
129 · git diff itself does not touch the files in the work tree, it
131 is often run to inspect the changes you intend to next git add.
132 To catch potential problems early, safety triggers.
133 ident
135 When the attribute ident is set for a path, git replaces $Id$ in
136 the blob object with $Id:, followed by the 40-character hexadecimal
137 blob object name, followed by a dollar sign $ upon checkout. Any
138 byte sequence that begins with $Id: and ends with $ in the worktree
139 file is replaced with $Id$ upon check-in.
140 filter
142 A filter attribute can be set to a string value that names a filter
143 driver specified in the configuration.
144 A filter driver consists of a clean command and a smudge command,
146 either of which can be left unspecified. Upon checkout, when the
147 smudge command is specified, the command is fed the blob object
148 from its standard input, and its standard output is used to update
149 the worktree file. Similarly, the clean command is used to convert
150 the contents of worktree file upon checkin.
151 A missing filter driver definition in the config is not an error
153 but makes the filter a no-op passthru.
154 The content filtering is done to massage the content into a shape
156 that is more convenient for the platform, filesystem, and the user
157 to use. The key phrase here is "more convenient" and not "turning
158 something unusable into usable". In other words, the intent is that
159 if someone unsets the filter driver definition, or does not have
160 the appropriate filter program, the project should still be usable.
161 For example, in .gitattributes, you would assign the filter
163 attribute for paths.
164 *.c filter=indent
166 Then you would define a "filter.indent.clean" and
169 "filter.indent.smudge" configuration in your .git/config to specify
170 a pair of commands to modify the contents of C programs when the
171 source files are checked in ("clean" is run) and checked out (no
172 change is made because the command is "cat").
173 [filter "indent"]
175 clean = indent
176 smudge = cat
177 Interaction between checkin/checkout attributes
180 In the check-in codepath, the worktree file is first converted with
181 filter driver (if specified and corresponding driver defined), then
182 the result is processed with ident (if specified), and then finally
183 with crlf (again, if specified and applicable).
184 In the check-out codepath, the blob content is first converted with
186 crlf, and then ident and fed to filter.
187 Generating diff text
189 diff
190 The attribute diff affects how git generates diffs for particular
191 files. It can tell git whether to generate a textual patch for the
192 path or to treat the path as a binary file. It can also affect what
193 line is shown on the hunk header @@ -k,l +n,m @@ line, tell git to
194 use an external command to generate the diff, or ask git to convert
195 binary files to a text format before generating the diff.
196 Set
198 A path to which the diff attribute is set is treated as text,
199 even when they contain byte values that normally never appear
200 in text files, such as NUL.
201 Unset
203 A path to which the diff attribute is unset will generate
204 Binary files differ (or a binary patch, if binary patches are
205 enabled).
206 Unspecified
208 A path to which the diff attribute is unspecified first gets
209 its contents inspected, and if it looks like text, it is
210 treated as text. Otherwise it would generate Binary files
211 differ.
212 String
214 Diff is shown using the specified diff driver. Each driver may
215 specify one or more options, as described in the following
216 section. The options for the diff driver "foo" are defined by
217 the configuration variables in the "diff.foo" section of the
218 git config file.
219 Defining an external diff driver
221 The definition of a diff driver is done in gitconfig, not
222 gitattributes file, so strictly speaking this manual page is a
223 wrong place to talk about it. However...
224 To define an external diff driver jcdiff, add a section to your
226 $GIT_DIR/config file (or $HOME/.gitconfig file) like this:
227 [diff "jcdiff"]
229 command = j-c-diff
230 When git needs to show you a diff for the path with diff attribute
233 set to jcdiff, it calls the command you specified with the above
234 configuration, i.e. j-c-diff, with 7 parameters, just like
235 GIT_EXTERNAL_DIFF program is called. See git(1) for details.
236 Defining a custom hunk-header
238 Each group of changes (called a "hunk") in the textual diff output
239 is prefixed with a line of the form:
240 @@ -k,l +n,m @@ TEXT
242 This is called a hunk header. The "TEXT" portion is by default a
244 line that begins with an alphabet, an underscore or a dollar sign;
245 this matches what GNU diff -p output uses. This default selection
246 however is not suited for some contents, and you can use a
247 customized pattern to make a selection.
248 First, in .gitattributes, you would assign the diff attribute for
250 paths.
251 *.tex diff=tex
253 Then, you would define a "diff.tex.xfuncname" configuration to
256 specify a regular expression that matches a line that you would
257 want to appear as the hunk header "TEXT". Add a section to your
258 $GIT_DIR/config file (or $HOME/.gitconfig file) like this:
259 [diff "tex"]
261 xfuncname = "^(\\\\(sub)*section\\{.*)$"
262 Note. A single level of backslashes are eaten by the configuration
265 file parser, so you would need to double the backslashes; the
266 pattern above picks a line that begins with a backslash, and zero
267 or more occurrences of sub followed by section followed by open
268 brace, to the end of line.
269 There are a few built-in patterns to make this easier, and tex is
271 one of them, so you do not have to write the above in your
272 configuration file (you still need to enable this with the
273 attribute mechanism, via .gitattributes). The following built in
274 patterns are available:
275 · bibtex suitable for files with BibTeX coded references.
277 · cpp suitable for source code in the C and C++ languages.
279 · html suitable for HTML/XHTML documents.
281 · java suitable for source code in the Java language.
283 · objc suitable for source code in the Objective-C language.
285 · pascal suitable for source code in the Pascal/Delphi language.
287 · php suitable for source code in the PHP language.
289 · python suitable for source code in the Python language.
291 · ruby suitable for source code in the Ruby language.
293 · tex suitable for source code for LaTeX documents.
295 Customizing word diff
297 You can customize the rules that git diff --color-words uses to
298 split words in a line, by specifying an appropriate regular
299 expression in the "diff.*.wordRegex" configuration variable. For
300 example, in TeX a backslash followed by a sequence of letters forms
301 a command, but several such commands can be run together without
302 intervening whitespace. To separate them, use a regular expression
303 in your $GIT_DIR/config file (or $HOME/.gitconfig file) like this:
304 [diff "tex"]
306 wordRegex = "\\\\[a-zA-Z]+|[{}]|\\\\.|[^\\{}[:space:]]+"
307 A built-in pattern is provided for all languages listed in the
310 previous section.
311 Performing text diffs of binary files
313 Sometimes it is desirable to see the diff of a text-converted
314 version of some binary files. For example, a word processor
315 document can be converted to an ASCII text representation, and the
316 diff of the text shown. Even though this conversion loses some
317 information, the resulting diff is useful for human viewing (but
318 cannot be applied directly).
319 The textconv config option is used to define a program for
321 performing such a conversion. The program should take a single
322 argument, the name of a file to convert, and produce the resulting
323 text on stdout.
324 For example, to show the diff of the exif information of a file
326 instead of the binary information (assuming you have the exif tool
327 installed), add the following section to your $GIT_DIR/config file
328 (or $HOME/.gitconfig file):
329 [diff "jpg"]
331 textconv = exif
332 Note
335 The text conversion is generally a one-way conversion; in this
336 example, we lose the actual image contents and focus just on
337 the text data. This means that diffs generated by textconv are
338 not suitable for applying. For this reason, only git diff and
339 the git log family of commands (i.e., log, whatchanged, show)
340 will perform text conversion. git format-patch will never
341 generate this output. If you want to send somebody a
342 text-converted diff of a binary file (e.g., because it quickly
343 conveys the changes you have made), you should generate it
344 separately and send it as a comment in addition to the usual
345 binary diff that you might send.
346 Performing a three-way merge
348 merge
349 The attribute merge affects how three versions of a file is merged
350 when a file-level merge is necessary during git merge, and other
351 commands such as git revert and git cherry-pick.
352 Set
354 Built-in 3-way merge driver is used to merge the contents in a
355 way similar to merge command of RCS suite. This is suitable for
356 ordinary text files.
357 Unset
359 Take the version from the current branch as the tentative merge
360 result, and declare that the merge has conflicts. This is
361 suitable for binary files that does not have a well-defined
362 merge semantics.
363 Unspecified
365 By default, this uses the same built-in 3-way merge driver as
366 is the case the merge attribute is set. However, merge.default
367 configuration variable can name different merge driver to be
368 used for paths to which the merge attribute is unspecified.
369 String
371 3-way merge is performed using the specified custom merge
372 driver. The built-in 3-way merge driver can be explicitly
373 specified by asking for "text" driver; the built-in "take the
374 current branch" driver can be requested with "binary".
375 Built-in merge drivers
377 There are a few built-in low-level merge drivers defined that can
378 be asked for via the merge attribute.
379 text
381 Usual 3-way file level merge for text files. Conflicted regions
382 are marked with conflict markers <<<<<<<, ======= and >>>>>>>.
383 The version from your branch appears before the ======= marker,
384 and the version from the merged branch appears after the
385 ======= marker.
386 binary
388 Keep the version from your branch in the work tree, but leave
389 the path in the conflicted state for the user to sort out.
390 union
392 Run 3-way file level merge for text files, but take lines from
393 both versions, instead of leaving conflict markers. This tends
394 to leave the added lines in the resulting file in random order
395 and the user should verify the result. Do not use this if you
396 do not understand the implications.
397 Defining a custom merge driver
399 The definition of a merge driver is done in the .git/config file,
400 not in the gitattributes file, so strictly speaking this manual
401 page is a wrong place to talk about it. However...
402 To define a custom merge driver filfre, add a section to your
404 $GIT_DIR/config file (or $HOME/.gitconfig file) like this:
405 [merge "filfre"]
407 name = feel-free merge driver
408 driver = filfre %O %A %B
409 recursive = binary
410 The merge.*.name variable gives the driver a human-readable name.
413 The ‘merge.*.driver` variable’s value is used to construct a
415 command to run to merge ancestor’s version (%O), current version
416 (%A) and the other branches’ version (%B). These three tokens are
417 replaced with the names of temporary files that hold the contents
418 of these versions when the command line is built. Additionally, %L
419 will be replaced with the conflict marker size (see below).
420 The merge driver is expected to leave the result of the merge in
422 the file named with %A by overwriting it, and exit with zero status
423 if it managed to merge them cleanly, or non-zero if there were
424 conflicts.
425 The merge.*.recursive variable specifies what other merge driver to
427 use when the merge driver is called for an internal merge between
428 common ancestors, when there are more than one. When left
429 unspecified, the driver itself is used for both internal merge and
430 the final merge.
431 conflict-marker-size
433 This attribute controls the length of conflict markers left in the
434 work tree file during a conflicted merge. Only setting to the value
435 to a positive integer has any meaningful effect.
436 For example, this line in .gitattributes can be used to tell the
438 merge machinery to leave much longer (instead of the usual
439 7-character-long) conflict markers when merging the file
440 Documentation/git-merge.txt results in a conflict.
441 Documentation/git-merge.txt conflict-marker-size=32
443 Checking whitespace errors
446 whitespace
447 The core.whitespace configuration variable allows you to define
448 what diff and apply should consider whitespace errors for all paths
449 in the project (See git-config(1)). This attribute gives you finer
450 control per path.
451 Set
453 Notice all types of potential whitespace errors known to git.
454 Unset
456 Do not notice anything as error.
457 Unspecified
459 Use the value of core.whitespace configuration variable to
460 decide what to notice as error.
461 String
463 Specify a comma separate list of common whitespace problems to
464 notice in the same format as core.whitespace configuration
465 variable.
466 Creating an archive
468 export-ignore
469 Files and directories with the attribute export-ignore won’t be
470 added to archive files.
471 export-subst
473 If the attribute export-subst is set for a file then git will
474 expand several placeholders when adding this file to an archive.
475 The expansion depends on the availability of a commit ID, i.e., if
476 git-archive(1) has been given a tree instead of a commit or a tag
477 then no replacement will be done. The placeholders are the same as
478 those for the option --pretty=format: of git-log(1), except that
479 they need to be wrapped like this: $Format:PLACEHOLDERS$ in the
480 file. E.g. the string $Format:%H$ will be replaced by the commit
481 hash.
482 Packing objects
484 delta
485 Delta compression will not be attempted for blobs for paths with
486 the attribute delta set to false.
487 Viewing files in GUI tools
489 encoding
490 The value of this attribute specifies the character encoding that
491 should be used by GUI tools (e.g. gitk(1) and git-gui(1)) to
492 display the contents of the relevant file. Note that due to
493 performance considerations gitk(1) does not use this attribute
494 unless you manually enable per-file encodings in its options.
495 If this attribute is not set or has an invalid value, the value of
497 the gui.encoding configuration variable is used instead (See git-
498 config(1)).
499
501 You do not want any end-of-line conversions applied to, nor textual
502 diffs produced for, any binary file you track. You would need to
503 specify e.g.
504 *.jpg -crlf -diff
506 but that may become cumbersome, when you have many attributes. Using
509 attribute macros, you can specify groups of attributes set or unset at
510 the same time. The system knows a built-in attribute macro, binary:
511 *.jpg binary
513 which is equivalent to the above. Note that the attribute macros can
516 only be "Set" (see the above example that sets "binary" macro as if it
517 were an ordinary attribute --- setting it in turn unsets "crlf" and
518 "diff").
519
521 Custom attribute macros can be defined only in the .gitattributes file
522 at the toplevel (i.e. not in any subdirectory). The built-in attribute
523 macro "binary" is equivalent to:
524 [attr]binary -diff -crlf
526
529 If you have these three gitattributes file:
530 (in $GIT_DIR/info/attributes)
532 a* foo !bar -baz
534 (in .gitattributes)
536 abc foo bar baz
537 (in t/.gitattributes)
539 ab* merge=filfre
540 abc -foo -bar
541 *.c frotz
542 the attributes given to path t/abc are computed as follows:
545 1. By examining t/.gitattributes (which is in the same directory as
547 the path in question), git finds that the first line matches.
548 merge attribute is set. It also finds that the second line matches,
549 and attributes foo and bar are unset.
550 2. Then it examines .gitattributes (which is in the parent directory),
552 and finds that the first line matches, but t/.gitattributes file
553 already decided how merge, foo and bar attributes should be given
554 to this path, so it leaves foo and bar unset. Attribute baz is set.
555 3. Finally it examines $GIT_DIR/info/attributes. This file is used to
557 override the in-tree settings. The first line is a match, and foo
558 is set, bar is reverted to unspecified state, and baz is unset.
559 As the result, the attributes assignment to t/abc becomes:
561 foo set to true
563 bar unspecified
564 baz set to false
565 merge set to string value "filfre"
566 frotz unspecified
567
570 Part of the git(1) suite
571Git 1.7.1 08/16/2017 GITATTRIBUTES(5)