GIT 1.5.4
[git/gitweb.git] / Documentation / gitattributes.txt
blob35a29fd60c4aa70fbbd7c05ed40e4b545225c74d
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, the following
76 operations 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 `$Id$` in the blob object with `$Id:`, followed by
142 40-character hexadecimal blob object name, followed by a dollar
143 sign `$` upon checkout.  Any byte sequence that begins with
144 `$Id:` and ends with `$` in the worktree file is replaced
145 with `$Id$` upon check-in.
148 `filter`
149 ^^^^^^^^
151 A `filter` attribute can be set to a string value that names a
152 filter driver specified in the configuration.
154 A filter driver consists of a `clean` command and a `smudge`
155 command, either of which can be left unspecified.  Upon
156 checkout, when the `smudge` command is specified, the command is
157 fed the blob object from its standard input, and its standard
158 output is used to update the worktree file.  Similarly, the
159 `clean` command is used to convert the contents of worktree file
160 upon checkin.
162 A missing filter driver definition in the config is not an error
163 but makes the filter a no-op passthru.
165 The content filtering is done to massage the content into a
166 shape that is more convenient for the platform, filesystem, and
167 the user to use.  The key phrase here is "more convenient" and not
168 "turning something unusable into usable".  In other words, the
169 intent is that if someone unsets the filter driver definition,
170 or does not have the appropriate filter program, the project
171 should still be usable.
174 Interaction between checkin/checkout attributes
175 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
177 In the check-in codepath, the worktree file is first converted
178 with `filter` driver (if specified and corresponding driver
179 defined), then the result is processed with `ident` (if
180 specified), and then finally with `crlf` (again, if specified
181 and applicable).
183 In the check-out codepath, the blob content is first converted
184 with `crlf`, and then `ident` and fed to `filter`.
187 Generating diff text
188 ~~~~~~~~~~~~~~~~~~~~
190 The attribute `diff` affects if `git diff` generates textual
191 patch for the path or just says `Binary files differ`.  It also
192 can affect what line is shown on the hunk header `@@ -k,l +n,m @@`
193 line.
195 Set::
197         A path to which the `diff` attribute is set is treated
198         as text, even when they contain byte values that
199         normally never appear in text files, such as NUL.
201 Unset::
203         A path to which the `diff` attribute is unset will
204         generate `Binary files differ`.
206 Unspecified::
208         A path to which the `diff` attribute is unspecified
209         first gets its contents inspected, and if it looks like
210         text, it is treated as text.  Otherwise it would
211         generate `Binary files differ`.
213 String::
215         Diff is shown using the specified custom diff driver.
216         The driver program is given its input using the same
217         calling convention as used for GIT_EXTERNAL_DIFF
218         program.  This name is also used for custom hunk header
219         selection.
222 Defining a custom diff driver
223 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
225 The definition of a diff driver is done in `gitconfig`, not
226 `gitattributes` file, so strictly speaking this manual page is a
227 wrong place to talk about it.  However...
229 To define a custom diff driver `jcdiff`, add a section to your
230 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
232 ----------------------------------------------------------------
233 [diff "jcdiff"]
234         command = j-c-diff
235 ----------------------------------------------------------------
237 When git needs to show you a diff for the path with `diff`
238 attribute set to `jcdiff`, it calls the command you specified
239 with the above configuration, i.e. `j-c-diff`, with 7
240 parameters, just like `GIT_EXTERNAL_DIFF` program is called.
241 See linkgit:git[7] for details.
244 Defining a custom hunk-header
245 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
247 Each group of changes (called "hunk") in the textual diff output
248 is prefixed with a line of the form:
250         @@ -k,l +n,m @@ TEXT
252 The text is called 'hunk header', and by default a line that
253 begins with an alphabet, an underscore or a dollar sign is used,
254 which matches what GNU `diff -p` output uses.  This default
255 selection however is not suited for some contents, and you can
256 use customized pattern to make a selection.
258 First in .gitattributes, you would assign the `diff` attribute
259 for paths.
261 ------------------------
262 *.tex   diff=tex
263 ------------------------
265 Then, you would define "diff.tex.funcname" configuration to
266 specify a regular expression that matches a line that you would
267 want to appear as the hunk header, like this:
269 ------------------------
270 [diff "tex"]
271         funcname = "^\\(\\\\\\(sub\\)*section{.*\\)$"
272 ------------------------
274 Note.  A single level of backslashes are eaten by the
275 configuration file parser, so you would need to double the
276 backslashes; the pattern above picks a line that begins with a
277 backslash, and zero or more occurrences of `sub` followed by
278 `section` followed by open brace, to the end of line.
280 There are a few built-in patterns to make this easier, and `tex`
281 is one of them, so you do not have to write the above in your
282 configuration file (you still need to enable this with the
283 attribute mechanism, via `.gitattributes`).  Another built-in
284 pattern is defined for `java` that defines a pattern suitable
285 for program text in Java language.
288 Performing a three-way merge
289 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
291 The attribute `merge` affects how three versions of a file is
292 merged when a file-level merge is necessary during `git merge`,
293 and other programs such as `git revert` and `git cherry-pick`.
295 Set::
297         Built-in 3-way merge driver is used to merge the
298         contents in a way similar to `merge` command of `RCS`
299         suite.  This is suitable for ordinary text files.
301 Unset::
303         Take the version from the current branch as the
304         tentative merge result, and declare that the merge has
305         conflicts.  This is suitable for binary files that does
306         not have a well-defined merge semantics.
308 Unspecified::
310         By default, this uses the same built-in 3-way merge
311         driver as is the case the `merge` attribute is set.
312         However, `merge.default` configuration variable can name
313         different merge driver to be used for paths to which the
314         `merge` attribute is unspecified.
316 String::
318         3-way merge is performed using the specified custom
319         merge driver.  The built-in 3-way merge driver can be
320         explicitly specified by asking for "text" driver; the
321         built-in "take the current branch" driver can be
322         requested with "binary".
325 Built-in merge drivers
326 ^^^^^^^^^^^^^^^^^^^^^^
328 There are a few built-in low-level merge drivers defined that
329 can be asked for via the `merge` attribute.
331 text::
333         Usual 3-way file level merge for text files.  Conflicted
334         regions are marked with conflict markers `<<<<<<<`,
335         `=======` and `>>>>>>>`.  The version from your branch
336         appears before the `=======` marker, and the version
337         from the merged branch appears after the `=======`
338         marker.
340 binary::
342         Keep the version from your branch in the work tree, but
343         leave the path in the conflicted state for the user to
344         sort out.
346 union::
348         Run 3-way file level merge for text files, but take
349         lines from both versions, instead of leaving conflict
350         markers.  This tends to leave the added lines in the
351         resulting file in random order and the user should
352         verify the result. Do not use this if you do not
353         understand the implications.
356 Defining a custom merge driver
357 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
359 The definition of a merge driver is done in the `.git/config`
360 file, not in the `gitattributes` file, so strictly speaking this
361 manual page is a wrong place to talk about it.  However...
363 To define a custom merge driver `filfre`, add a section to your
364 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
366 ----------------------------------------------------------------
367 [merge "filfre"]
368         name = feel-free merge driver
369         driver = filfre %O %A %B
370         recursive = binary
371 ----------------------------------------------------------------
373 The `merge.*.name` variable gives the driver a human-readable
374 name.
376 The `merge.*.driver` variable's value is used to construct a
377 command to run to merge ancestor's version (`%O`), current
378 version (`%A`) and the other branches' version (`%B`).  These
379 three tokens are replaced with the names of temporary files that
380 hold the contents of these versions when the command line is
381 built.
383 The merge driver is expected to leave the result of the merge in
384 the file named with `%A` by overwriting it, and exit with zero
385 status if it managed to merge them cleanly, or non-zero if there
386 were conflicts.
388 The `merge.*.recursive` variable specifies what other merge
389 driver to use when the merge driver is called for an internal
390 merge between common ancestors, when there are more than one.
391 When left unspecified, the driver itself is used for both
392 internal merge and the final merge.
395 Checking whitespace errors
396 ~~~~~~~~~~~~~~~~~~~~~~~~~~
398 `whitespace`
399 ^^^^^^^^^^^^
401 The `core.whitespace` configuration variable allows you to define what
402 `diff` and `apply` should consider whitespace errors for all paths in
403 the project (See linkgit:git-config[1]).  This attribute gives you finer
404 control per path.
406 Set::
408         Notice all types of potential whitespace errors known to git.
410 Unset::
412         Do not notice anything as error.
414 Unspecified::
416         Use the value of `core.whitespace` configuration variable to
417         decide what to notice as error.
419 String::
421         Specify a comma separate list of common whitespace problems to
422         notice in the same format as `core.whitespace` configuration
423         variable.
426 EXAMPLE
427 -------
429 If you have these three `gitattributes` file:
431 ----------------------------------------------------------------
432 (in $GIT_DIR/info/attributes)
434 a*      foo !bar -baz
436 (in .gitattributes)
437 abc     foo bar baz
439 (in t/.gitattributes)
440 ab*     merge=filfre
441 abc     -foo -bar
442 *.c     frotz
443 ----------------------------------------------------------------
445 the attributes given to path `t/abc` are computed as follows:
447 1. By examining `t/.gitattributes` (which is in the same
448    directory as the path in question), git finds that the first
449    line matches.  `merge` attribute is set.  It also finds that
450    the second line matches, and attributes `foo` and `bar`
451    are unset.
453 2. Then it examines `.gitattributes` (which is in the parent
454    directory), and finds that the first line matches, but
455    `t/.gitattributes` file already decided how `merge`, `foo`
456    and `bar` attributes should be given to this path, so it
457    leaves `foo` and `bar` unset.  Attribute `baz` is set.
459 3. Finally it examines `$GIT_DIR/info/attributes`.  This file
460    is used to override the in-tree settings.  The first line is
461    a match, and `foo` is set, `bar` is reverted to unspecified
462    state, and `baz` is unset.
464 As the result, the attributes assignment to `t/abc` becomes:
466 ----------------------------------------------------------------
467 foo     set to true
468 bar     unspecified
469 baz     set to false
470 merge   set to string value "filfre"
471 frotz   unspecified
472 ----------------------------------------------------------------
475 Creating an archive
476 ~~~~~~~~~~~~~~~~~~~
478 `export-subst`
479 ^^^^^^^^^^^^^^
481 If the attribute `export-subst` is set for a file then git will expand
482 several placeholders when adding this file to an archive.  The
483 expansion depends on the availability of a commit ID, i.e. if
484 linkgit:git-archive[1] has been given a tree instead of a commit or a
485 tag then no replacement will be done.  The placeholders are the same
486 as those for the option `--pretty=format:` of linkgit:git-log[1],
487 except that they need to be wrapped like this: `$Format:PLACEHOLDERS$`
488 in the file.  E.g. the string `$Format:%H$` will be replaced by the
489 commit hash.
494 Part of the linkgit:git[7] suite