6 gitattributes - defining attributes per path
10 $GIT_DIR/info/attributes, gitattributes
16 A `gitattributes` file is a simple text file that gives
17 `attributes` to pathnames.
19 Each line in `gitattributes` file is of form:
23 That is, a glob pattern followed by an attributes list,
24 separated by whitespaces. When the glob pattern matches the
25 path in question, the attributes listed on the line are given to
28 Each attribute can be in one of these states for a given path:
32 The path has the attribute with special value "true";
33 this is specified by listing only the name of the
34 attribute in the attribute list.
38 The path has the attribute with special value "false";
39 this is specified by listing the name of the attribute
40 prefixed with a dash `-` in the attribute list.
44 The path has the attribute with specified string value;
45 this is specified by listing the name of the attribute
46 followed by an equal sign `=` and its value in the
51 No glob pattern matches the path, and nothing says if
52 the path has or does not have the attribute, the
53 attribute for the path is said to be Unspecified.
55 When more than one glob pattern matches the path, a later line
56 overrides an earlier line. This overriding is done per
59 When deciding what attributes are assigned to a path, git
60 consults `$GIT_DIR/info/attributes` file (which has the highest
61 precedence), `.gitattributes` file in the same directory as the
62 path in question, and its parent directories (the further the
63 directory that contains `.gitattributes` is from the path in
64 question, the lower its precedence).
66 Sometimes you would need to override an setting of an attribute
67 for a path to `unspecified` state. This can be done by listing
68 the name of the attribute prefixed with an exclamation point `!`.
74 Certain operations by git can be influenced by assigning
75 particular attributes to a path. Currently, three operations
78 Checking-out and checking-in
79 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
81 These attributes affect how the contents stored in the
82 repository are copied to the working tree files when commands
83 such as `git checkout` and `git merge` run. They also affect how
84 git stores the contents you prepare in the working tree in the
85 repository upon `git add` and `git commit`.
90 This attribute controls the line-ending convention.
94 Setting the `crlf` attribute on a path is meant to mark
95 the path as a "text" file. 'core.autocrlf' conversion
96 takes place without guessing the content type by
101 Unsetting the `crlf` attribute on a path is meant to
102 mark the path as a "binary" file. The path never goes
103 through line endings conversion upon checkin/checkout.
107 Unspecified `crlf` attribute tells git to apply the
108 `core.autocrlf` conversion when the file content looks
111 Set to string value "input"::
113 This is similar to setting the attribute to `true`, but
114 also forces git to act as if `core.autocrlf` is set to
115 `input` for the path.
117 Any other value set to `crlf` attribute is ignored and git acts
118 as if the attribute is left unspecified.
121 The `core.autocrlf` conversion
122 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
124 If the configuration variable `core.autocrlf` is false, no
127 When `core.autocrlf` is true, it means that the platform wants
128 CRLF line endings for files in the working tree, and you want to
129 convert them back to the normal LF line endings when checking
130 in to the repository.
132 When `core.autocrlf` is set to "input", line endings are
133 converted to LF upon checkin, but there is no conversion done
140 When the attribute `ident` is set to a path, git replaces
141 `$ident$` in the blob object with `$ident:`, followed by
142 40-character hexadecimal blob object name, followed by a dollar
143 sign `$` upon checkout. Any byte sequence that begins with
144 `$ident:` and ends with `$` in the worktree file is replaced
145 with `$ident$` upon check-in.
148 Interaction between checkin/checkout attributes
149 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
151 In the check-in codepath, the worktree file is first converted
152 with `ident` (if specified), and then with `crlf` (again, if
153 specified and applicable).
155 In the check-out codepath, the blob content is first converted
156 with `crlf`, and then `ident`.
162 The attribute `diff` affects if `git diff` generates textual
163 patch for the path or just says `Binary files differ`.
167 A path to which the `diff` attribute is set is treated
168 as text, even when they contain byte values that
169 normally never appear in text files, such as NUL.
173 A path to which the `diff` attribute is unset will
174 generate `Binary files differ`.
178 A path to which the `diff` attribute is unspecified
179 first gets its contents inspected, and if it looks like
180 text, it is treated as text. Otherwise it would
181 generate `Binary files differ`.
185 Diff is shown using the specified custom diff driver.
186 The driver program is given its input using the same
187 calling convention as used for GIT_EXTERNAL_DIFF
191 Defining a custom diff driver
192 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
194 The definition of a diff driver is done in `gitconfig`, not
195 `gitattributes` file, so strictly speaking this manual page is a
196 wrong place to talk about it. However...
198 To define a custom diff driver `jcdiff`, add a section to your
199 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
201 ----------------------------------------------------------------
204 ----------------------------------------------------------------
206 When git needs to show you a diff for the path with `diff`
207 attribute set to `jcdiff`, it calls the command you specified
208 with the above configuration, i.e. `j-c-diff`, with 7
209 parameters, just like `GIT_EXTERNAL_DIFF` program is called.
210 See gitlink:git[7] for details.
213 Performing a three-way merge
214 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
216 The attribute `merge` affects how three versions of a file is
217 merged when a file-level merge is necessary during `git merge`,
218 and other programs such as `git revert` and `git cherry-pick`.
222 Built-in 3-way merge driver is used to merge the
223 contents in a way similar to `merge` command of `RCS`
224 suite. This is suitable for ordinary text files.
228 Take the version from the current branch as the
229 tentative merge result, and declare that the merge has
230 conflicts. This is suitable for binary files that does
231 not have a well-defined merge semantics.
235 By default, this uses the same built-in 3-way merge
236 driver as is the case the `merge` attribute is set.
237 However, `merge.default` configuration variable can name
238 different merge driver to be used for paths to which the
239 `merge` attribute is unspecified.
243 3-way merge is performed using the specified custom
244 merge driver. The built-in 3-way merge driver can be
245 explicitly specified by asking for "text" driver; the
246 built-in "take the current branch" driver can be
247 requested with "binary".
250 Defining a custom merge driver
251 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
253 The definition of a merge driver is done in `gitconfig` not
254 `gitattributes` file, so strictly speaking this manual page is a
255 wrong place to talk about it. However...
257 To define a custom merge driver `filfre`, add a section to your
258 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
260 ----------------------------------------------------------------
262 name = feel-free merge driver
263 driver = filfre %O %A %B
265 ----------------------------------------------------------------
267 The `merge.*.name` variable gives the driver a human-readable
270 The `merge.*.driver` variable's value is used to construct a
271 command to run to merge ancestor's version (`%O`), current
272 version (`%A`) and the other branches' version (`%B`). These
273 three tokens are replaced with the names of temporary files that
274 hold the contents of these versions when the command line is
277 The merge driver is expected to leave the result of the merge in
278 the file named with `%A` by overwriting it, and exit with zero
279 status if it managed to merge them cleanly, or non-zero if there
282 The `merge.*.recursive` variable specifies what other merge
283 driver to use when the merge driver is called for an internal
284 merge between common ancestors, when there are more than one.
285 When left unspecified, the driver itself is used for both
286 internal merge and the final merge.
292 If you have these three `gitattributes` file:
294 ----------------------------------------------------------------
295 (in $GIT_DIR/info/attributes)
302 (in t/.gitattributes)
306 ----------------------------------------------------------------
308 the attributes given to path `t/abc` are computed as follows:
310 1. By examining `t/.gitattributes` (which is in the same
311 diretory as the path in question), git finds that the first
312 line matches. `merge` attribute is set. It also finds that
313 the second line matches, and attributes `foo` and `bar`
316 2. Then it examines `.gitattributes` (which is in the parent
317 directory), and finds that the first line matches, but
318 `t/.gitattributes` file already decided how `merge`, `foo`
319 and `bar` attributes should be given to this path, so it
320 leaves `foo` and `bar` unset. Attribute `baz` is set.
322 3. Finally it examines `$GIT_DIR/info/gitattributes`. This file
323 is used to override the in-tree settings. The first line is
324 a match, and `foo` is set, `bar` is reverted to unspecified
325 state, and `baz` is unset.
327 As the result, the attributes assignement to `t/abc` becomes:
329 ----------------------------------------------------------------
333 merge set to string value "filfre"
335 ----------------------------------------------------------------
340 Part of the gitlink:git[7] suite