Code

Documentation/git-add: clarify -u with path limiting
[git.git] / Documentation / gitattributes.txt
1 gitattributes(5)
2 ================
4 NAME
5 ----
6 gitattributes - defining attributes per path
8 SYNOPSIS
9 --------
10 $GIT_DIR/info/attributes, gitattributes
13 DESCRIPTION
14 -----------
16 A `gitattributes` file is a simple text file that gives
17 `attributes` to pathnames.
19 Each line in `gitattributes` file is of form:
21         glob    attr1 attr2 ...
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
26 the path.
28 Each attribute can be in one of these states for a given path:
30 Set::
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.
36 Unset::
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.
42 Set to a value::
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
47         attribute list.
49 Unspecified::
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
57 attribute.
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 `!`.
71 EFFECTS
72 -------
74 Certain operations by git can be influenced by assigning
75 particular attributes to a path.  Currently, three operations
76 are attributes-aware.
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`.
87 `crlf`
88 ^^^^^^
90 This attribute controls the line-ending convention.
92 Set::
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
97         inspection.
99 Unset::
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.
105 Unspecified::
107         Unspecified `crlf` attribute tells git to apply the
108         `core.autocrlf` conversion when the file content looks
109         like text.
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
125 conversion is done.
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
134 upon checkout.
137 `ident`
138 ^^^^^^^
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`.
159 `filter`
160 ^^^^^^^^
162 A `filter` attribute can be set to a string value.  This names
163 filter driver specified in the configuration.
165 A filter driver consists of `clean` command and `smudge`
166 command, either of which can be left unspecified.  Upon
167 checkout, when `smudge` command is specified, the command is fed
168 the blob object from its standard input, and its standard output
169 is used to update the worktree file.  Similarly, `clean` command
170 is used to convert the contents of worktree file upon checkin.
172 Missing filter driver definition in the config is not an error
173 but makes the filter a no-op passthru.
175 The content filtering is done to massage the content into a
176 shape that is more convenient for the platform, filesystem, and
177 the user to use.  The keyword here is "more convenient" and not
178 "turning something unusable into usable".  In other words, it is
179 "hanging yourself because we gave you a long rope" if your
180 project uses filtering mechanism in such a way that it makes
181 your project unusable unless the checkout is done with a
182 specific filter in effect.
185 Interaction between checkin/checkout attributes
186 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
188 In the check-in codepath, the worktree file is first converted
189 with `filter` driver (if specified and corresponding driver
190 defined), then the result is processed with `ident` (if
191 specified), and then finally with `crlf` (again, if specified
192 and applicable).
194 In the check-out codepath, the blob content is first converted
195 with `crlf`, and then `ident` and fed to `filter`.
198 Generating diff text
199 ~~~~~~~~~~~~~~~~~~~~
201 The attribute `diff` affects if `git diff` generates textual
202 patch for the path or just says `Binary files differ`.
204 Set::
206         A path to which the `diff` attribute is set is treated
207         as text, even when they contain byte values that
208         normally never appear in text files, such as NUL.
210 Unset::
212         A path to which the `diff` attribute is unset will
213         generate `Binary files differ`.
215 Unspecified::
217         A path to which the `diff` attribute is unspecified
218         first gets its contents inspected, and if it looks like
219         text, it is treated as text.  Otherwise it would
220         generate `Binary files differ`.
222 String::
224         Diff is shown using the specified custom diff driver.
225         The driver program is given its input using the same
226         calling convention as used for GIT_EXTERNAL_DIFF
227         program.
230 Defining a custom diff driver
231 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
233 The definition of a diff driver is done in `gitconfig`, not
234 `gitattributes` file, so strictly speaking this manual page is a
235 wrong place to talk about it.  However...
237 To define a custom diff driver `jcdiff`, add a section to your
238 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
240 ----------------------------------------------------------------
241 [diff "jcdiff"]
242         command = j-c-diff
243 ----------------------------------------------------------------
245 When git needs to show you a diff for the path with `diff`
246 attribute set to `jcdiff`, it calls the command you specified
247 with the above configuration, i.e. `j-c-diff`, with 7
248 parameters, just like `GIT_EXTERNAL_DIFF` program is called.
249 See gitlink:git[7] for details.
252 Performing a three-way merge
253 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
255 The attribute `merge` affects how three versions of a file is
256 merged when a file-level merge is necessary during `git merge`,
257 and other programs such as `git revert` and `git cherry-pick`.
259 Set::
261         Built-in 3-way merge driver is used to merge the
262         contents in a way similar to `merge` command of `RCS`
263         suite.  This is suitable for ordinary text files.
265 Unset::
267         Take the version from the current branch as the
268         tentative merge result, and declare that the merge has
269         conflicts.  This is suitable for binary files that does
270         not have a well-defined merge semantics.
272 Unspecified::
274         By default, this uses the same built-in 3-way merge
275         driver as is the case the `merge` attribute is set.
276         However, `merge.default` configuration variable can name
277         different merge driver to be used for paths to which the
278         `merge` attribute is unspecified.
280 String::
282         3-way merge is performed using the specified custom
283         merge driver.  The built-in 3-way merge driver can be
284         explicitly specified by asking for "text" driver; the
285         built-in "take the current branch" driver can be
286         requested with "binary".
289 Defining a custom merge driver
290 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
292 The definition of a merge driver is done in `gitconfig` not
293 `gitattributes` file, so strictly speaking this manual page is a
294 wrong place to talk about it.  However...
296 To define a custom merge driver `filfre`, add a section to your
297 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
299 ----------------------------------------------------------------
300 [merge "filfre"]
301         name = feel-free merge driver
302         driver = filfre %O %A %B
303         recursive = binary
304 ----------------------------------------------------------------
306 The `merge.*.name` variable gives the driver a human-readable
307 name.
309 The `merge.*.driver` variable's value is used to construct a
310 command to run to merge ancestor's version (`%O`), current
311 version (`%A`) and the other branches' version (`%B`).  These
312 three tokens are replaced with the names of temporary files that
313 hold the contents of these versions when the command line is
314 built.
316 The merge driver is expected to leave the result of the merge in
317 the file named with `%A` by overwriting it, and exit with zero
318 status if it managed to merge them cleanly, or non-zero if there
319 were conflicts.
321 The `merge.*.recursive` variable specifies what other merge
322 driver to use when the merge driver is called for an internal
323 merge between common ancestors, when there are more than one.
324 When left unspecified, the driver itself is used for both
325 internal merge and the final merge.
328 EXAMPLE
329 -------
331 If you have these three `gitattributes` file:
333 ----------------------------------------------------------------
334 (in $GIT_DIR/info/attributes)
336 a*      foo !bar -baz
338 (in .gitattributes)
339 abc     foo bar baz
341 (in t/.gitattributes)
342 ab*     merge=filfre
343 abc     -foo -bar
344 *.c     frotz
345 ----------------------------------------------------------------
347 the attributes given to path `t/abc` are computed as follows:
349 1. By examining `t/.gitattributes` (which is in the same
350    diretory as the path in question), git finds that the first
351    line matches.  `merge` attribute is set.  It also finds that
352    the second line matches, and attributes `foo` and `bar`
353    are unset.
355 2. Then it examines `.gitattributes` (which is in the parent
356    directory), and finds that the first line matches, but
357    `t/.gitattributes` file already decided how `merge`, `foo`
358    and `bar` attributes should be given to this path, so it
359    leaves `foo` and `bar` unset.  Attribute `baz` is set.
361 3. Finally it examines `$GIT_DIR/info/gitattributes`.  This file
362    is used to override the in-tree settings.  The first line is
363    a match, and `foo` is set, `bar` is reverted to unspecified
364    state, and `baz` is unset.
366 As the result, the attributes assignement to `t/abc` becomes:
368 ----------------------------------------------------------------
369 foo     set to true
370 bar     unspecified
371 baz     set to false
372 merge   set to string value "filfre"
373 frotz   unspecified
374 ----------------------------------------------------------------
377 GIT
378 ---
379 Part of the gitlink:git[7] suite