Document clarification: gitmodules, gitattributes
[git/dscho.git] / Documentation / gitattributes.txt
1 gitattributes(5)
2 ================
5 ----
6 gitattributes - defining attributes per path
9 --------
10 $GIT_DIR/info/attributes, .gitattributes
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 `!`.
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 tells git not to
109         attempt any end-of-line conversion upon checkin or checkout.
111 Unspecified::
113         Unspecified `crlf` attribute tells git to apply the
114         `core.autocrlf` conversion when the file content looks
115         like text.
117 Set to string value "input"::
119         This is similar to setting the attribute to `true`, but
120         also forces git to act as if `core.autocrlf` is set to
121         `input` for the path.
123 Any other value set to `crlf` attribute is ignored and git acts
124 as if the attribute is left unspecified.
127 The `core.autocrlf` conversion
128 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
130 If the configuration variable `core.autocrlf` is false, no
131 conversion is done.
133 When `core.autocrlf` is true, it means that the platform wants
134 CRLF line endings for files in the working tree, and you want to
135 convert them back to the normal LF line endings when checking
136 in to the repository.
138 When `core.autocrlf` is set to "input", line endings are
139 converted to LF upon checkin, but there is no conversion done
140 upon checkout.
142 If `core.safecrlf` is set to "true" or "warn", git verifies if
143 the conversion is reversible for the current setting of
144 `core.autocrlf`.  For "true", git rejects irreversible
145 conversions; for "warn", git only prints a warning but accepts
146 an irreversible conversion.  The safety triggers to prevent such
147 a conversion done to the files in the work tree, but there are a
148 few exceptions.  Even though...
150 - 'git-add' itself does not touch the files in the work tree, the
151   next checkout would, so the safety triggers;
153 - 'git-apply' to update a text file with a patch does touch the files
154   in the work tree, but the operation is about text files and CRLF
155   conversion is about fixing the line ending inconsistencies, so the
156   safety does not trigger;
158 - 'git-diff' itself does not touch the files in the work tree, it is
159   often run to inspect the changes you intend to next 'git-add'.  To
160   catch potential problems early, safety triggers.
163 `ident`
164 ^^^^^^^
166 When the attribute `ident` is set to a path, git replaces
167 `$Id$` in the blob object with `$Id:`, followed by
168 40-character hexadecimal blob object name, followed by a dollar
169 sign `$` upon checkout.  Any byte sequence that begins with
170 `$Id:` and ends with `$` in the worktree file is replaced
171 with `$Id$` upon check-in.
174 `filter`
175 ^^^^^^^^
177 A `filter` attribute can be set to a string value that names a
178 filter driver specified in the configuration.
180 A filter driver consists of a `clean` command and a `smudge`
181 command, either of which can be left unspecified.  Upon
182 checkout, when the `smudge` command is specified, the command is
183 fed the blob object from its standard input, and its standard
184 output is used to update the worktree file.  Similarly, the
185 `clean` command is used to convert the contents of worktree file
186 upon checkin.
188 A missing filter driver definition in the config is not an error
189 but makes the filter a no-op passthru.
191 The content filtering is done to massage the content into a
192 shape that is more convenient for the platform, filesystem, and
193 the user to use.  The key phrase here is "more convenient" and not
194 "turning something unusable into usable".  In other words, the
195 intent is that if someone unsets the filter driver definition,
196 or does not have the appropriate filter program, the project
197 should still be usable.
200 Interaction between checkin/checkout attributes
201 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
203 In the check-in codepath, the worktree file is first converted
204 with `filter` driver (if specified and corresponding driver
205 defined), then the result is processed with `ident` (if
206 specified), and then finally with `crlf` (again, if specified
207 and applicable).
209 In the check-out codepath, the blob content is first converted
210 with `crlf`, and then `ident` and fed to `filter`.
213 Generating diff text
214 ~~~~~~~~~~~~~~~~~~~~
216 The attribute `diff` affects if 'git-diff' generates textual
217 patch for the path or just says `Binary files differ`.  It also
218 can affect what line is shown on the hunk header `@@ -k,l +n,m @@`
219 line.
221 Set::
223         A path to which the `diff` attribute is set is treated
224         as text, even when they contain byte values that
225         normally never appear in text files, such as NUL.
227 Unset::
229         A path to which the `diff` attribute is unset will
230         generate `Binary files differ`.
232 Unspecified::
234         A path to which the `diff` attribute is unspecified
235         first gets its contents inspected, and if it looks like
236         text, it is treated as text.  Otherwise it would
237         generate `Binary files differ`.
239 String::
241         Diff is shown using the specified custom diff driver.
242         The driver program is given its input using the same
243         calling convention as used for GIT_EXTERNAL_DIFF
244         program.  This name is also used for custom hunk header
245         selection.
248 Defining a custom diff driver
249 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
251 The definition of a diff driver is done in `gitconfig`, not
252 `gitattributes` file, so strictly speaking this manual page is a
253 wrong place to talk about it.  However...
255 To define a custom diff driver `jcdiff`, add a section to your
256 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
258 ----------------------------------------------------------------
259 [diff "jcdiff"]
260         command = j-c-diff
261 ----------------------------------------------------------------
263 When git needs to show you a diff for the path with `diff`
264 attribute set to `jcdiff`, it calls the command you specified
265 with the above configuration, i.e. `j-c-diff`, with 7
266 parameters, just like `GIT_EXTERNAL_DIFF` program is called.
267 See linkgit:git[1] for details.
270 Defining a custom hunk-header
271 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
273 Each group of changes (called "hunk") in the textual diff output
274 is prefixed with a line of the form:
276         @@ -k,l +n,m @@ TEXT
278 The text is called 'hunk header', and by default a line that
279 begins with an alphabet, an underscore or a dollar sign is used,
280 which matches what GNU 'diff -p' output uses.  This default
281 selection however is not suited for some contents, and you can
282 use customized pattern to make a selection.
284 First in .gitattributes, you would assign the `diff` attribute
285 for paths.
287 ------------------------
288 *.tex   diff=tex
289 ------------------------
291 Then, you would define "diff.tex.funcname" configuration to
292 specify a regular expression that matches a line that you would
293 want to appear as the hunk header, like this:
295 ------------------------
296 [diff "tex"]
297         funcname = "^\\(\\\\\\(sub\\)*section{.*\\)$"
298 ------------------------
300 Note.  A single level of backslashes are eaten by the
301 configuration file parser, so you would need to double the
302 backslashes; the pattern above picks a line that begins with a
303 backslash, and zero or more occurrences of `sub` followed by
304 `section` followed by open brace, to the end of line.
306 There are a few built-in patterns to make this easier, and `tex`
307 is one of them, so you do not have to write the above in your
308 configuration file (you still need to enable this with the
309 attribute mechanism, via `.gitattributes`).  The following built in
310 patterns are available:
312 - `bibtex` suitable for files with BibTeX coded references.
314 - `java` suitable for source code in the Java lanugage.
316 - `pascal` suitable for source code in the Pascal/Delphi language.
318 - `ruby` suitable for source code in the Ruby language.
320 - `tex` suitable for source code for LaTeX documents.
323 Performing a three-way merge
324 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
326 The attribute `merge` affects how three versions of a file is
327 merged when a file-level merge is necessary during `git merge`,
328 and other programs such as `git revert` and `git cherry-pick`.
330 Set::
332         Built-in 3-way merge driver is used to merge the
333         contents in a way similar to 'merge' command of `RCS`
334         suite.  This is suitable for ordinary text files.
336 Unset::
338         Take the version from the current branch as the
339         tentative merge result, and declare that the merge has
340         conflicts.  This is suitable for binary files that does
341         not have a well-defined merge semantics.
343 Unspecified::
345         By default, this uses the same built-in 3-way merge
346         driver as is the case the `merge` attribute is set.
347         However, `merge.default` configuration variable can name
348         different merge driver to be used for paths to which the
349         `merge` attribute is unspecified.
351 String::
353         3-way merge is performed using the specified custom
354         merge driver.  The built-in 3-way merge driver can be
355         explicitly specified by asking for "text" driver; the
356         built-in "take the current branch" driver can be
357         requested with "binary".
360 Built-in merge drivers
361 ^^^^^^^^^^^^^^^^^^^^^^
363 There are a few built-in low-level merge drivers defined that
364 can be asked for via the `merge` attribute.
366 text::
368         Usual 3-way file level merge for text files.  Conflicted
369         regions are marked with conflict markers `<<<<<<<`,
370         `=======` and `>>>>>>>`.  The version from your branch
371         appears before the `=======` marker, and the version
372         from the merged branch appears after the `=======`
373         marker.
375 binary::
377         Keep the version from your branch in the work tree, but
378         leave the path in the conflicted state for the user to
379         sort out.
381 union::
383         Run 3-way file level merge for text files, but take
384         lines from both versions, instead of leaving conflict
385         markers.  This tends to leave the added lines in the
386         resulting file in random order and the user should
387         verify the result. Do not use this if you do not
388         understand the implications.
391 Defining a custom merge driver
392 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
394 The definition of a merge driver is done in the `.git/config`
395 file, not in the `gitattributes` file, so strictly speaking this
396 manual page is a wrong place to talk about it.  However...
398 To define a custom merge driver `filfre`, add a section to your
399 `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
401 ----------------------------------------------------------------
402 [merge "filfre"]
403         name = feel-free merge driver
404         driver = filfre %O %A %B
405         recursive = binary
406 ----------------------------------------------------------------
408 The `merge.*.name` variable gives the driver a human-readable
409 name.
411 The `merge.*.driver` variable's value is used to construct a
412 command to run to merge ancestor's version (`%O`), current
413 version (`%A`) and the other branches' version (`%B`).  These
414 three tokens are replaced with the names of temporary files that
415 hold the contents of these versions when the command line is
416 built.
418 The merge driver is expected to leave the result of the merge in
419 the file named with `%A` by overwriting it, and exit with zero
420 status if it managed to merge them cleanly, or non-zero if there
421 were conflicts.
423 The `merge.*.recursive` variable specifies what other merge
424 driver to use when the merge driver is called for an internal
425 merge between common ancestors, when there are more than one.
426 When left unspecified, the driver itself is used for both
427 internal merge and the final merge.
430 Checking whitespace errors
431 ~~~~~~~~~~~~~~~~~~~~~~~~~~
433 `whitespace`
434 ^^^^^^^^^^^^
436 The `core.whitespace` configuration variable allows you to define what
437 'diff' and 'apply' should consider whitespace errors for all paths in
438 the project (See linkgit:git-config[1]).  This attribute gives you finer
439 control per path.
441 Set::
443         Notice all types of potential whitespace errors known to git.
445 Unset::
447         Do not notice anything as error.
449 Unspecified::
451         Use the value of `core.whitespace` configuration variable to
452         decide what to notice as error.
454 String::
456         Specify a comma separate list of common whitespace problems to
457         notice in the same format as `core.whitespace` configuration
458         variable.
461 Creating an archive
462 ~~~~~~~~~~~~~~~~~~~
464 `export-ignore`
465 ^^^^^^^^^^^^^^^
467 Files and directories with the attribute `export-ignore` won't be added to
468 archive files.
470 `export-subst`
471 ^^^^^^^^^^^^^^
473 If the attribute `export-subst` is set for a file then git will expand
474 several placeholders when adding this file to an archive.  The
475 expansion depends on the availability of a commit ID, i.e., if
476 linkgit:git-archive[1] has been given a tree instead of a commit or a
477 tag then no replacement will be done.  The placeholders are the same
478 as those for the option `--pretty=format:` of linkgit:git-log[1],
479 except that they need to be wrapped like this: `$Format:PLACEHOLDERS$`
480 in the file.  E.g. the string `$Format:%H$` will be replaced by the
481 commit hash.
485 ----------------------
487 You do not want any end-of-line conversions applied to, nor textual diffs
488 produced for, any binary file you track.  You would need to specify e.g.
490 ------------
491 *.jpg -crlf -diff
492 ------------
494 but that may become cumbersome, when you have many attributes.  Using
495 attribute macros, you can specify groups of attributes set or unset at
496 the same time.  The system knows a built-in attribute macro, `binary`:
498 ------------
499 *.jpg binary
500 ------------
502 which is equivalent to the above.  Note that the attribute macros can only
503 be "Set" (see the above example that sets "binary" macro as if it were an
504 ordinary attribute --- setting it in turn unsets "crlf" and "diff").
508 -------------------------
510 Custom attribute macros can be defined only in the `.gitattributes` file
511 at the toplevel (i.e. not in any subdirectory).  The built-in attribute
512 macro "binary" is equivalent to:
514 ------------
515 [attr]binary -diff -crlf
516 ------------
520 -------
522 If you have these three `gitattributes` file:
524 ----------------------------------------------------------------
525 (in $GIT_DIR/info/attributes)
527 a*      foo !bar -baz
529 (in .gitattributes)
530 abc     foo bar baz
532 (in t/.gitattributes)
533 ab*     merge=filfre
534 abc     -foo -bar
535 *.c     frotz
536 ----------------------------------------------------------------
538 the attributes given to path `t/abc` are computed as follows:
540 1. By examining `t/.gitattributes` (which is in the same
541    directory as the path in question), git finds that the first
542    line matches.  `merge` attribute is set.  It also finds that
543    the second line matches, and attributes `foo` and `bar`
544    are unset.
546 2. Then it examines `.gitattributes` (which is in the parent
547    directory), and finds that the first line matches, but
548    `t/.gitattributes` file already decided how `merge`, `foo`
549    and `bar` attributes should be given to this path, so it
550    leaves `foo` and `bar` unset.  Attribute `baz` is set.
552 3. Finally it examines `$GIT_DIR/info/attributes`.  This file
553    is used to override the in-tree settings.  The first line is
554    a match, and `foo` is set, `bar` is reverted to unspecified
555    state, and `baz` is unset.
557 As the result, the attributes assignment to `t/abc` becomes:
559 ----------------------------------------------------------------
560 foo     set to true
561 bar     unspecified
562 baz     set to false
563 merge   set to string value "filfre"
564 frotz   unspecified
565 ----------------------------------------------------------------
571 Part of the linkgit:git[1] suite