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.
54 When more than one glob pattern matches the path, a later line
55 overrides an earlier line.
57 When deciding what attributes are assigned to a path, git
58 consults `$GIT_DIR/info/attributes` file (which has the highest
59 precedence), `.gitattributes` file in the same directory as the
60 path in question, and its parent directories (the further the
61 directory that contains `.gitattributes` is from the path in
62 question, the lower its precedence).
64 Sometimes you would need to override an setting of an attribute
65 for a path to `unspecified` state. This can be done by listing
66 the name of the attribute prefixed with an exclamation point `!`.
72 Certain operations by git can be influenced by assigning
73 particular attributes to a path. Currently, three operations
76 Checking-out and checking-in
77 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
79 The attribute `crlf` affects how the contents stored in the
80 repository are copied to the working tree files when commands
81 such as `git checkout` and `git merge` run. It also affects how
82 git stores the contents you prepare in the working tree in the
83 repository upon `git add` and `git commit`.
87 Setting the `crlf` attribute on a path is meant to mark
88 the path as a "text" file. 'core.autocrlf' conversion
89 takes place without guessing the content type by
94 Unsetting the `crlf` attribute on a path is meant to
95 mark the path as a "binary" file. The path never goes
96 through line endings conversion upon checkin/checkout.
100 Unspecified `crlf` attribute tells git to apply the
101 `core.autocrlf` conversion when the file content looks
104 Set to string value "input"::
106 This is similar to setting the attribute to `true`, but
107 also forces git to act as if `core.autocrlf` is set to
108 `input` for the path.
110 Any other value set to `crlf` attribute is ignored and git acts
111 as if the attribute is left unspecified.
114 The `core.autocrlf` conversion
115 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
117 If the configuration variable `core.autocrlf` is false, no
120 When `core.autocrlf` is true, it means that the platform wants
121 CRLF line endings for files in the working tree, and you want to
122 convert them back to the normal LF line endings when checking
123 in to the repository.
125 When `core.autocrlf` is set to "input", line endings are
126 converted to LF upon checkin, but there is no conversion done
133 The attribute `diff` affects if `git diff` generates textual
134 patch for the path or just says `Binary files differ`.
138 A path to which the `diff` attribute is set is treated
139 as text, even when they contain byte values that
140 normally never appear in text files, such as NUL.
144 A path to which the `diff` attribute is unset will
145 generate `Binary files differ`.
149 A path to which the `diff` attribute is unspecified
150 first gets its contents inspected, and if it looks like
151 text, it is treated as text. Otherwise it would
152 generate `Binary files differ`.
156 Diff is shown using the specified custom diff driver.
157 The driver program is given its input using the same
158 calling convention as used for GIT_EXTERNAL_DIFF
162 Defining a custom diff driver
163 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
165 The definition of a diff driver is done in `gitconfig`, not
166 `gitattributes` file, so strictly speaking this manual page is a
167 wrong place to talk about it. However...
169 To define a custom diff driver `jcdiff`, add a section to your
170 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
172 ----------------------------------------------------------------
175 ----------------------------------------------------------------
177 When git needs to show you a diff for the path with `diff`
178 attribute set to `jcdiff`, it calls the command you specified
179 with the above configuration, i.e. `j-c-diff`, with 7
180 parameters, just like `GIT_EXTERNAL_DIFF` program is called.
181 See gitlink:git[7] for details.
184 Performing a three-way merge
185 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
187 The attribute `merge` affects how three versions of a file is
188 merged when a file-level merge is necessary during `git merge`,
189 and other programs such as `git revert` and `git cherry-pick`.
193 Built-in 3-way merge driver is used to merge the
194 contents in a way similar to `merge` command of `RCS`
195 suite. This is suitable for ordinary text files.
199 Take the version from the current branch as the
200 tentative merge result, and declare that the merge has
201 conflicts. This is suitable for binary files that does
202 not have a well-defined merge semantics.
206 By default, this uses the same built-in 3-way merge
207 driver as is the case the `merge` attribute is set.
208 However, `merge.default` configuration variable can name
209 different merge driver to be used for paths to which the
210 `merge` attribute is unspecified.
214 3-way merge is performed using the specified custom
215 merge driver. The built-in 3-way merge driver can be
216 explicitly specified by asking for "text" driver; the
217 built-in "take the current branch" driver can be
218 requested by "binary".
221 Defining a custom merge driver
222 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
224 The definition of a merge driver is done in `gitconfig` not
225 `gitattributes` file, so strictly speaking this manual page is a
226 wrong place to talk about it. However...
228 To define a custom merge driver `filfre`, add a section to your
229 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
231 ----------------------------------------------------------------
233 name = feel-free merge driver
234 driver = filfre %O %A %B
236 ----------------------------------------------------------------
238 The `merge.*.name` variable gives the driver a human-readable
241 The `merge.*.driver` variable's value is used to construct a
242 command to run to merge ancestor's version (`%O`), current
243 version (`%A`) and the other branches' version (`%B`). These
244 three tokens are replaced with the names of temporary files that
245 hold the contents of these versions when the command line is
248 The merge driver is expected to leave the result of the merge in
249 the file named with `%A` by overwriting it, and exit with zero
250 status if it managed to merge them cleanly, or non-zero if there
253 The `merge.*.recursive` variable specifies what other merge
254 driver to use when the merge driver is called for an internal
255 merge between common ancestors, when there are more than one.
256 When left unspecified, the driver itself is used for both
257 internal merge and the final merge.
263 If you have these three `gitattributes` file:
265 ----------------------------------------------------------------
266 (in $GIT_DIR/info/attributes)
273 (in t/.gitattributes)
277 ----------------------------------------------------------------
279 the attributes given to path `t/abc` are computed as follows:
281 1. By examining `t/.gitattributes` (which is in the same
282 diretory as the path in question), git finds that the first
283 line matches. `merge` attribute is set. It also finds that
284 the second line matches, and attributes `foo` and `bar`
287 2. Then it examines `.gitattributes` (which is in the parent
288 directory), and finds that the first line matches, but
289 `t/.gitattributes` file already decided how `merge`, `foo`
290 and `bar` attributes should be given to this path, so it
291 leaves `foo` and `bar` unset. Attribute `baz` is set.
293 3. Finally it examines `$GIT_DIR/info/gitattributes`. This file
294 is used to override the in-tree settings. The first line is
295 a match, and `foo` is set, `bar` is reverted to unspecified
296 state, and `baz` is unset.
298 As the result, the attributes assignement to `t/abc` becomes:
300 ----------------------------------------------------------------
304 merge set to string value "filfre"
306 ----------------------------------------------------------------
311 Part of the gitlink:git[7] suite