Git.pm: fix return value of config method
[git/dscho.git] / Documentation / gitattributes.txt
blob04ca63ca3d8b1c35c849750e66348e42a6b823a0
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 If you wish to affect only a single repository (i.e., to assign
67 attributes to files that are particular to one user's workflow), then
68 attributes should be placed in the `$GIT_DIR/info/attributes` file.
69 Attributes which should be version-controlled and distributed to other
70 repositories (i.e., attributes of interest to all users) should go into
71 `.gitattributes` files.
73 Sometimes you would need to override an setting of an attribute
74 for a path to `unspecified` state.  This can be done by listing
75 the name of the attribute prefixed with an exclamation point `!`.
78 EFFECTS
79 -------
81 Certain operations by git can be influenced by assigning
82 particular attributes to a path.  Currently, the following
83 operations are attributes-aware.
85 Checking-out and checking-in
86 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
88 These attributes affect how the contents stored in the
89 repository are copied to the working tree files when commands
90 such as `git checkout` and `git merge` run.  They also affect how
91 git stores the contents you prepare in the working tree in the
92 repository upon `git add` and `git commit`.
94 `crlf`
95 ^^^^^^
97 This attribute controls the line-ending convention.
99 Set::
101         Setting the `crlf` attribute on a path is meant to mark
102         the path as a "text" file.  'core.autocrlf' conversion
103         takes place without guessing the content type by
104         inspection.
106 Unset::
108         Unsetting the `crlf` attribute on a path is meant to
109         mark the path as a "binary" file.  The path never goes
110         through line endings conversion upon checkin/checkout.
112 Unspecified::
114         Unspecified `crlf` attribute tells git to apply the
115         `core.autocrlf` conversion when the file content looks
116         like text.
118 Set to string value "input"::
120         This is similar to setting the attribute to `true`, but
121         also forces git to act as if `core.autocrlf` is set to
122         `input` for the path.
124 Any other value set to `crlf` attribute is ignored and git acts
125 as if the attribute is left unspecified.
128 The `core.autocrlf` conversion
129 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
131 If the configuration variable `core.autocrlf` is false, no
132 conversion is done.
134 When `core.autocrlf` is true, it means that the platform wants
135 CRLF line endings for files in the working tree, and you want to
136 convert them back to the normal LF line endings when checking
137 in to the repository.
139 When `core.autocrlf` is set to "input", line endings are
140 converted to LF upon checkin, but there is no conversion done
141 upon checkout.
143 If `core.safecrlf` is set to "true" or "warn", git verifies if
144 the conversion is reversible for the current setting of
145 `core.autocrlf`.  For "true", git rejects irreversible
146 conversions; for "warn", git only prints a warning but accepts
147 an irreversible conversion.  The safety triggers to prevent such
148 a conversion done to the files in the work tree, but there are a
149 few exceptions.  Even though...
151 - "git add" itself does not touch the files in the work tree, the
152   next checkout would, so the safety triggers;
154 - "git apply" to update a text file with a patch does touch the files
155   in the work tree, but the operation is about text files and CRLF
156   conversion is about fixing the line ending inconsistencies, so the
157   safety does not trigger;
159 - "git diff" itself does not touch the files in the work tree, it is
160   often run to inspect the changes you intend to next "git add".  To
161   catch potential problems early, safety triggers.
164 `ident`
165 ^^^^^^^
167 When the attribute `ident` is set to a path, git replaces
168 `$Id$` in the blob object with `$Id:`, followed by
169 40-character hexadecimal blob object name, followed by a dollar
170 sign `$` upon checkout.  Any byte sequence that begins with
171 `$Id:` and ends with `$` in the worktree file is replaced
172 with `$Id$` upon check-in.
175 `filter`
176 ^^^^^^^^
178 A `filter` attribute can be set to a string value that names a
179 filter driver specified in the configuration.
181 A filter driver consists of a `clean` command and a `smudge`
182 command, either of which can be left unspecified.  Upon
183 checkout, when the `smudge` command is specified, the command is
184 fed the blob object from its standard input, and its standard
185 output is used to update the worktree file.  Similarly, the
186 `clean` command is used to convert the contents of worktree file
187 upon checkin.
189 A missing filter driver definition in the config is not an error
190 but makes the filter a no-op passthru.
192 The content filtering is done to massage the content into a
193 shape that is more convenient for the platform, filesystem, and
194 the user to use.  The key phrase here is "more convenient" and not
195 "turning something unusable into usable".  In other words, the
196 intent is that if someone unsets the filter driver definition,
197 or does not have the appropriate filter program, the project
198 should still be usable.
201 Interaction between checkin/checkout attributes
202 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
204 In the check-in codepath, the worktree file is first converted
205 with `filter` driver (if specified and corresponding driver
206 defined), then the result is processed with `ident` (if
207 specified), and then finally with `crlf` (again, if specified
208 and applicable).
210 In the check-out codepath, the blob content is first converted
211 with `crlf`, and then `ident` and fed to `filter`.
214 Generating diff text
215 ~~~~~~~~~~~~~~~~~~~~
217 The attribute `diff` affects if `git diff` generates textual
218 patch for the path or just says `Binary files differ`.  It also
219 can affect what line is shown on the hunk header `@@ -k,l +n,m @@`
220 line.
222 Set::
224         A path to which the `diff` attribute is set is treated
225         as text, even when they contain byte values that
226         normally never appear in text files, such as NUL.
228 Unset::
230         A path to which the `diff` attribute is unset will
231         generate `Binary files differ`.
233 Unspecified::
235         A path to which the `diff` attribute is unspecified
236         first gets its contents inspected, and if it looks like
237         text, it is treated as text.  Otherwise it would
238         generate `Binary files differ`.
240 String::
242         Diff is shown using the specified custom diff driver.
243         The driver program is given its input using the same
244         calling convention as used for GIT_EXTERNAL_DIFF
245         program.  This name is also used for custom hunk header
246         selection.
249 Defining a custom diff driver
250 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
252 The definition of a diff driver is done in `gitconfig`, not
253 `gitattributes` file, so strictly speaking this manual page is a
254 wrong place to talk about it.  However...
256 To define a custom diff driver `jcdiff`, add a section to your
257 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
259 ----------------------------------------------------------------
260 [diff "jcdiff"]
261         command = j-c-diff
262 ----------------------------------------------------------------
264 When git needs to show you a diff for the path with `diff`
265 attribute set to `jcdiff`, it calls the command you specified
266 with the above configuration, i.e. `j-c-diff`, with 7
267 parameters, just like `GIT_EXTERNAL_DIFF` program is called.
268 See linkgit:git[7] for details.
271 Defining a custom hunk-header
272 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
274 Each group of changes (called "hunk") in the textual diff output
275 is prefixed with a line of the form:
277         @@ -k,l +n,m @@ TEXT
279 The text is called 'hunk header', and by default a line that
280 begins with an alphabet, an underscore or a dollar sign is used,
281 which matches what GNU `diff -p` output uses.  This default
282 selection however is not suited for some contents, and you can
283 use customized pattern to make a selection.
285 First in .gitattributes, you would assign the `diff` attribute
286 for paths.
288 ------------------------
289 *.tex   diff=tex
290 ------------------------
292 Then, you would define "diff.tex.funcname" configuration to
293 specify a regular expression that matches a line that you would
294 want to appear as the hunk header, like this:
296 ------------------------
297 [diff "tex"]
298         funcname = "^\\(\\\\\\(sub\\)*section{.*\\)$"
299 ------------------------
301 Note.  A single level of backslashes are eaten by the
302 configuration file parser, so you would need to double the
303 backslashes; the pattern above picks a line that begins with a
304 backslash, and zero or more occurrences of `sub` followed by
305 `section` followed by open brace, to the end of line.
307 There are a few built-in patterns to make this easier, and `tex`
308 is one of them, so you do not have to write the above in your
309 configuration file (you still need to enable this with the
310 attribute mechanism, via `.gitattributes`).  Another built-in
311 pattern is defined for `java` that defines a pattern suitable
312 for program text in Java language.
315 Performing a three-way merge
316 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
318 The attribute `merge` affects how three versions of a file is
319 merged when a file-level merge is necessary during `git merge`,
320 and other programs such as `git revert` and `git cherry-pick`.
322 Set::
324         Built-in 3-way merge driver is used to merge the
325         contents in a way similar to `merge` command of `RCS`
326         suite.  This is suitable for ordinary text files.
328 Unset::
330         Take the version from the current branch as the
331         tentative merge result, and declare that the merge has
332         conflicts.  This is suitable for binary files that does
333         not have a well-defined merge semantics.
335 Unspecified::
337         By default, this uses the same built-in 3-way merge
338         driver as is the case the `merge` attribute is set.
339         However, `merge.default` configuration variable can name
340         different merge driver to be used for paths to which the
341         `merge` attribute is unspecified.
343 String::
345         3-way merge is performed using the specified custom
346         merge driver.  The built-in 3-way merge driver can be
347         explicitly specified by asking for "text" driver; the
348         built-in "take the current branch" driver can be
349         requested with "binary".
352 Built-in merge drivers
353 ^^^^^^^^^^^^^^^^^^^^^^
355 There are a few built-in low-level merge drivers defined that
356 can be asked for via the `merge` attribute.
358 text::
360         Usual 3-way file level merge for text files.  Conflicted
361         regions are marked with conflict markers `<<<<<<<`,
362         `=======` and `>>>>>>>`.  The version from your branch
363         appears before the `=======` marker, and the version
364         from the merged branch appears after the `=======`
365         marker.
367 binary::
369         Keep the version from your branch in the work tree, but
370         leave the path in the conflicted state for the user to
371         sort out.
373 union::
375         Run 3-way file level merge for text files, but take
376         lines from both versions, instead of leaving conflict
377         markers.  This tends to leave the added lines in the
378         resulting file in random order and the user should
379         verify the result. Do not use this if you do not
380         understand the implications.
383 Defining a custom merge driver
384 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
386 The definition of a merge driver is done in the `.git/config`
387 file, not in the `gitattributes` file, so strictly speaking this
388 manual page is a wrong place to talk about it.  However...
390 To define a custom merge driver `filfre`, add a section to your
391 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
393 ----------------------------------------------------------------
394 [merge "filfre"]
395         name = feel-free merge driver
396         driver = filfre %O %A %B
397         recursive = binary
398 ----------------------------------------------------------------
400 The `merge.*.name` variable gives the driver a human-readable
401 name.
403 The `merge.*.driver` variable's value is used to construct a
404 command to run to merge ancestor's version (`%O`), current
405 version (`%A`) and the other branches' version (`%B`).  These
406 three tokens are replaced with the names of temporary files that
407 hold the contents of these versions when the command line is
408 built.
410 The merge driver is expected to leave the result of the merge in
411 the file named with `%A` by overwriting it, and exit with zero
412 status if it managed to merge them cleanly, or non-zero if there
413 were conflicts.
415 The `merge.*.recursive` variable specifies what other merge
416 driver to use when the merge driver is called for an internal
417 merge between common ancestors, when there are more than one.
418 When left unspecified, the driver itself is used for both
419 internal merge and the final merge.
422 Checking whitespace errors
423 ~~~~~~~~~~~~~~~~~~~~~~~~~~
425 `whitespace`
426 ^^^^^^^^^^^^
428 The `core.whitespace` configuration variable allows you to define what
429 `diff` and `apply` should consider whitespace errors for all paths in
430 the project (See linkgit:git-config[1]).  This attribute gives you finer
431 control per path.
433 Set::
435         Notice all types of potential whitespace errors known to git.
437 Unset::
439         Do not notice anything as error.
441 Unspecified::
443         Use the value of `core.whitespace` configuration variable to
444         decide what to notice as error.
446 String::
448         Specify a comma separate list of common whitespace problems to
449         notice in the same format as `core.whitespace` configuration
450         variable.
453 EXAMPLE
454 -------
456 If you have these three `gitattributes` file:
458 ----------------------------------------------------------------
459 (in $GIT_DIR/info/attributes)
461 a*      foo !bar -baz
463 (in .gitattributes)
464 abc     foo bar baz
466 (in t/.gitattributes)
467 ab*     merge=filfre
468 abc     -foo -bar
469 *.c     frotz
470 ----------------------------------------------------------------
472 the attributes given to path `t/abc` are computed as follows:
474 1. By examining `t/.gitattributes` (which is in the same
475    directory as the path in question), git finds that the first
476    line matches.  `merge` attribute is set.  It also finds that
477    the second line matches, and attributes `foo` and `bar`
478    are unset.
480 2. Then it examines `.gitattributes` (which is in the parent
481    directory), and finds that the first line matches, but
482    `t/.gitattributes` file already decided how `merge`, `foo`
483    and `bar` attributes should be given to this path, so it
484    leaves `foo` and `bar` unset.  Attribute `baz` is set.
486 3. Finally it examines `$GIT_DIR/info/attributes`.  This file
487    is used to override the in-tree settings.  The first line is
488    a match, and `foo` is set, `bar` is reverted to unspecified
489    state, and `baz` is unset.
491 As the result, the attributes assignment to `t/abc` becomes:
493 ----------------------------------------------------------------
494 foo     set to true
495 bar     unspecified
496 baz     set to false
497 merge   set to string value "filfre"
498 frotz   unspecified
499 ----------------------------------------------------------------
502 Creating an archive
503 ~~~~~~~~~~~~~~~~~~~
505 `export-subst`
506 ^^^^^^^^^^^^^^
508 If the attribute `export-subst` is set for a file then git will expand
509 several placeholders when adding this file to an archive.  The
510 expansion depends on the availability of a commit ID, i.e. if
511 linkgit:git-archive[1] has been given a tree instead of a commit or a
512 tag then no replacement will be done.  The placeholders are the same
513 as those for the option `--pretty=format:` of linkgit:git-log[1],
514 except that they need to be wrapped like this: `$Format:PLACEHOLDERS$`
515 in the file.  E.g. the string `$Format:%H$` will be replaced by the
516 commit hash.
521 Part of the linkgit:git[7] suite