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 glob attr1 attr2 ...
19 That is, a glob pattern followed by an attributes list, separated by
20 whitespaces. When the glob 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 glob pattern matches the path, and nothing says if the path has
42 or does not have the attribute, the attribute for the path is said
43 to be Unspecified.
44 When more than one glob pattern matches the path, a later line
45 overrides an earlier line. This overriding is done per attribute.
46 When deciding what attributes are assigned to a path, git consults
48 $GIT_DIR/info/attributes file (which has the highest precedence),
49 .gitattributes file in the same directory as the path in question, and
50 its parent directories (the further the directory that contains
51 .gitattributes is from the path in question, the lower its precedence).
52 Sometimes you would need to override an setting of an attribute for a
54 path to unspecified state. This can be done by listing the name of the
55 attribute prefixed with an exclamation point !.
56
58 Certain operations by git can be influenced by assigning particular
59 attributes to a path. Currently, the following operations are
60 attributes-aware.
61 Checking-out and checking-in
63 These attributes affect how the contents stored in the repository are
64 copied to the working tree files when commands such as git checkout and
65 git merge run. They also affect how git stores the contents you prepare
66 in the working tree in the repository upon git add and git commit.
67 crlf
69 This attribute controls the line-ending convention.
70 Set
72 Setting the crlf attribute on a path is meant to mark the
73 path as a "text" file. core.autocrlf conversion takes place
74 without guessing the content type by inspection.
75 Unset
77 Unsetting the crlf attribute on a path is meant to mark the
78 path as a "binary" file. The path never goes through line
79 endings conversion upon checkin/checkout.
80 Unspecified
82 Unspecified crlf attribute tells git to apply the
83 core.autocrlf conversion when the file content looks like
84 text.
85 Set to string value "input"
87 This is similar to setting the attribute to true, but also
88 forces git to act as if core.autocrlf is set to input for
89 the path.
90 Any other value set to crlf attribute is ignored and git acts as
91 if the attribute is left unspecified.
92 The core.autocrlf conversion
94 If the configuration variable core.autocrlf is false, no
95 conversion is done.
96 When core.autocrlf is true, it means that the platform wants
98 CRLF line endings for files in the working tree, and you want to
99 convert them back to the normal LF line endings when checking in
100 to the repository.
101 When core.autocrlf is set to "input", line endings are converted
103 to LF upon checkin, but there is no conversion done upon
104 checkout.
105 ident
107 When the attribute ident is set to a path, git replaces $Id$ in
108 the blob object with $Id:, followed by 40-character hexadecimal
109 blob object name, followed by a dollar sign $ upon checkout. Any
110 byte sequence that begins with $Id: and ends with $ in the
111 worktree file is replaced with $Id$ upon check-in.
112 filter
114 A filter attribute can be set to a string value. This names
115 filter driver specified in the configuration.
116 A filter driver consists of clean command and smudge command,
118 either of which can be left unspecified. Upon checkout, when
119 smudge command is specified, the command is fed the blob object
120 from its standard input, and its standard output is used to
121 update the worktree file. Similarly, clean command is used to
122 convert the contents of worktree file upon checkin.
123 Missing filter driver definition in the config is not an error
125 but makes the filter a no-op passthru.
126 The content filtering is done to massage the content into a
128 shape that is more convenient for the platform, filesystem, and
129 the user to use. The keyword here is "more convenient" and not
130 "turning something unusable into usable". In other words, the
131 intent is that if someone unsets the filter driver definition,
132 or does not have the appropriate filter program, the project
133 should still be usable.
134 Interaction between checkin/checkout attributes
136 In the check-in codepath, the worktree file is first converted
137 with filter driver (if specified and corresponding driver
138 defined), then the result is processed with ident (if
139 specified), and then finally with crlf (again, if specified and
140 applicable).
141 In the check-out codepath, the blob content is first converted
143 with crlf, and then ident and fed to filter.
144 Generating diff text
146 The attribute diff affects if git diff generates textual patch for the
147 path or just says Binary files differ. It also can affect what line is
148 shown on the hunk header @@ -k,l +n,m @@ line.
149 Set
151 A path to which the diff attribute is set is treated as text, even
152 when they contain byte values that normally never appear in text
153 files, such as NUL.
154 Unset
156 A path to which the diff attribute is unset will generate Binary
157 files differ.
158 Unspecified
160 A path to which the diff attribute is unspecified first gets its
161 contents inspected, and if it looks like text, it is treated as
162 text. Otherwise it would generate Binary files differ.
163 String
165 Diff is shown using the specified custom diff driver. The driver
166 program is given its input using the same calling convention as
167 used for GIT_EXTERNAL_DIFF program. This name is also used for
168 custom hunk header selection.
169 Defining a custom diff driver
171 The definition of a diff driver is done in gitconfig, not
172 gitattributes file, so strictly speaking this manual page is a
173 wrong place to talk about it. However...
174 To define a custom diff driver jcdiff, add a section to your
176 $GIT_DIR/config file (or $HOME/.gitconfig file) like this:
177 [diff "jcdiff"]
181 command = j-c-diff
182 When git needs to show you a diff for the path with diff
184 attribute set to jcdiff, it calls the command you specified with
185 the above configuration, i.e. j-c-diff, with 7 parameters, just
186 like GIT_EXTERNAL_DIFF program is called. See git(7) for
187 details.
188 Defining a custom hunk-header
190 Each group of changes (called "hunk") in the textual diff output
191 is prefixed with a line of the form:
192 @@ -k,l +n,m @@ TEXT
195 The text is called hunk header, and by default a line that
196 begins with an alphabet, an underscore or a dollar sign is used,
197 which matches what GNU diff -p output uses. This default
198 selection however is not suited for some contents, and you can
199 use customized pattern to make a selection.
200 First in .gitattributes, you would assign the diff attribute for
202 paths.
203 *.tex diff=tex
207 Then, you would define "diff.tex.funcname" configuration to
209 specify a regular expression that matches a line that you would
210 want to appear as the hunk header, like this:
211 [diff "tex"]
215 funcname = "^\\(\\\\\\(sub\\)*section{.*\\)$"
216 Note. A single level of backslashes are eaten by the
218 configuration file parser, so you would need to double the
219 backslashes; the pattern above picks a line that begins with a
220 backslash, and zero or more occurrences of sub followed by
221 section followed by open brace, to the end of line.
222 There are a few built-in patterns to make this easier, and tex
224 is one of them, so you do not have to write the above in your
225 configuration file (you still need to enable this with the
226 attribute mechanism, via .gitattributes). Another built-in
227 pattern is defined for java that defines a pattern suitable for
228 program text in Java language.
229 Performing a three-way merge
231 The attribute merge affects how three versions of a file is merged when
232 a file-level merge is necessary during git merge, and other programs
233 such as git revert and git cherry-pick.
234 Set
236 Built-in 3-way merge driver is used to merge the contents in a way
237 similar to merge command of RCS suite. This is suitable for
238 ordinary text files.
239 Unset
241 Take the version from the current branch as the tentative merge
242 result, and declare that the merge has conflicts. This is suitable
243 for binary files that does not have a well-defined merge semantics.
244 Unspecified
246 By default, this uses the same built-in 3-way merge driver as is
247 the case the merge attribute is set. However, merge.default
248 configuration variable can name different merge driver to be used
249 for paths to which the merge attribute is unspecified.
250 String
252 3-way merge is performed using the specified custom merge driver.
253 The built-in 3-way merge driver can be explicitly specified by
254 asking for "text" driver; the built-in "take the current branch"
255 driver can be requested with "binary".
256 Defining a custom merge driver
258 The definition of a merge driver is done in gitconfig not
259 gitattributes file, so strictly speaking this manual page is a
260 wrong place to talk about it. However...
261 To define a custom merge driver filfre, add a section to your
263 $GIT_DIR/config file (or $HOME/.gitconfig file) like this:
264 [merge "filfre"]
268 name = feel-free merge driver
269 driver = filfre %O %A %B
270 recursive = binary
271 The merge.*.name variable gives the driver a human-readable
273 name.
274 The merge.*.driver variable´s value is used to construct a
276 command to run to merge ancestor´s version (%O), current version
277 (%A) and the other branches´ version (%B). These three tokens
278 are replaced with the names of temporary files that hold the
279 contents of these versions when the command line is built.
280 The merge driver is expected to leave the result of the merge in
282 the file named with %A by overwriting it, and exit with zero
283 status if it managed to merge them cleanly, or non-zero if there
284 were conflicts.
285 The merge.*.recursive variable specifies what other merge driver
287 to use when the merge driver is called for an internal merge
288 between common ancestors, when there are more than one. When
289 left unspecified, the driver itself is used for both internal
290 merge and the final merge.
291
293 If you have these three gitattributes file:
294 (in $GIT_DIR/info/attributes)
298 a* foo !bar -baz
300 (in .gitattributes)
302 abc foo bar baz
303 (in t/.gitattributes)
305 ab* merge=filfre
306 abc -foo -bar
307 *.c frotz
308 the attributes given to path t/abc are computed as follows:
310 1. By examining t/.gitattributes (which is in the same directory as
313 the path in question), git finds that the first line matches. merge
314 attribute is set. It also finds that the second line matches, and
315 attributes foo and bar are unset.
316 2. Then it examines .gitattributes (which is in the parent
318 directory), and finds that the first line matches, but
319 t/.gitattributes file already decided how merge, foo and bar
320 attributes should be given to this path, so it leaves foo and bar
321 unset. Attribute baz is set.
322 3. Finally it examines $GIT_DIR/info/attributes. This file is used to
324 override the in-tree settings. The first line is a match, and foo
325 is set, bar is reverted to unspecified state, and baz is unset.
326 As the result, the attributes assignment to t/abc becomes:
327 foo set to true
331 bar unspecified
332 baz set to false
333 merge set to string value "filfre"
334 frotz unspecified
335
338 Part of the git(7) suite
339Git 1.5.3.3 10/09/2007 GITATTRIBUTES(5)