| blob | 4b4f47950c87c4a9f0c17683aacc142b45a9d314 |
1 <?xml version="1.0" encoding="UTF-8"?>\r
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">\r
3 \r
4 <article lang="en" id="gitattributes(5)">\r
5 <articleinfo>\r
6 <title>gitattributes(5)</title>\r
7 <indexterm>\r
8 <primary>gitattributes(5)</primary>\r
9 </indexterm>\r
10 </articleinfo>\r
11 <simplesect id="_name">\r
12 <title>NAME</title>\r
13 <simpara>gitattributes - defining attributes per path</simpara>\r
14 </simplesect>\r
15 <simplesect id="_synopsis">\r
16 <title>SYNOPSIS</title>\r
17 <simpara>$GIT_DIR/info/attributes, .gitattributes</simpara>\r
18 </simplesect>\r
19 <simplesect id="_description">\r
20 <title>DESCRIPTION</title>\r
21 <simpara>A <literal>gitattributes</literal> file is a simple text file that gives\r
22 <literal>attributes</literal> to pathnames.</simpara>\r
23 <simpara>Each line in <literal>gitattributes</literal> file is of form:</simpara>\r
24 <literallayout class="monospaced">glob attr1 attr2 ...</literallayout>\r
25 <simpara>That is, a glob pattern followed by an attributes list,\r
26 separated by whitespaces. When the glob pattern matches the\r
27 path in question, the attributes listed on the line are given to\r
28 the path.</simpara>\r
29 <simpara>Each attribute can be in one of these states for a given path:</simpara>\r
30 <variablelist>\r
31 <varlistentry>\r
32 <term>\r
33 Set\r
34 </term>\r
35 <listitem>\r
36 <simpara>\r
37 The path has the attribute with special value "true";\r
38 this is specified by listing only the name of the\r
39 attribute in the attribute list.\r
40 </simpara>\r
41 </listitem>\r
42 </varlistentry>\r
43 <varlistentry>\r
44 <term>\r
45 Unset\r
46 </term>\r
47 <listitem>\r
48 <simpara>\r
49 The path has the attribute with special value "false";\r
50 this is specified by listing the name of the attribute\r
51 prefixed with a dash <literal>-</literal> in the attribute list.\r
52 </simpara>\r
53 </listitem>\r
54 </varlistentry>\r
55 <varlistentry>\r
56 <term>\r
57 Set to a value\r
58 </term>\r
59 <listitem>\r
60 <simpara>\r
61 The path has the attribute with specified string value;\r
62 this is specified by listing the name of the attribute\r
63 followed by an equal sign <literal>=</literal> and its value in the\r
64 attribute list.\r
65 </simpara>\r
66 </listitem>\r
67 </varlistentry>\r
68 <varlistentry>\r
69 <term>\r
70 Unspecified\r
71 </term>\r
72 <listitem>\r
73 <simpara>\r
74 No glob pattern matches the path, and nothing says if\r
75 the path has or does not have the attribute, the\r
76 attribute for the path is said to be Unspecified.\r
77 </simpara>\r
78 </listitem>\r
79 </varlistentry>\r
80 </variablelist>\r
81 <simpara>When more than one glob pattern matches the path, a later line\r
82 overrides an earlier line. This overriding is done per\r
83 attribute.</simpara>\r
84 <simpara>When deciding what attributes are assigned to a path, git\r
85 consults <literal>$GIT_DIR/info/attributes</literal> file (which has the highest\r
86 precedence), <literal>.gitattributes</literal> file in the same directory as the\r
87 path in question, and its parent directories (the further the\r
88 directory that contains <literal>.gitattributes</literal> is from the path in\r
89 question, the lower its precedence).</simpara>\r
90 <simpara>If you wish to affect only a single repository (i.e., to assign\r
91 attributes to files that are particular to one user’s workflow), then\r
92 attributes should be placed in the <literal>$GIT_DIR/info/attributes</literal> file.\r
93 Attributes which should be version-controlled and distributed to other\r
94 repositories (i.e., attributes of interest to all users) should go into\r
95 <literal>.gitattributes</literal> files.</simpara>\r
96 <simpara>Sometimes you would need to override an setting of an attribute\r
97 for a path to <literal>unspecified</literal> state. This can be done by listing\r
98 the name of the attribute prefixed with an exclamation point <literal>!</literal>.</simpara>\r
99 </simplesect>\r
100 <simplesect id="_effects">\r
101 <title>EFFECTS</title>\r
102 <simpara>Certain operations by git can be influenced by assigning\r
103 particular attributes to a path. Currently, the following\r
104 operations are attributes-aware.</simpara>\r
105 <simplesect id="_checking_out_and_checking_in">\r
106 <title>Checking-out and checking-in</title>\r
107 <simpara>These attributes affect how the contents stored in the\r
108 repository are copied to the working tree files when commands\r
109 such as <emphasis>git-checkout</emphasis> and <emphasis>git-merge</emphasis> run. They also affect how\r
110 git stores the contents you prepare in the working tree in the\r
111 repository upon <emphasis>git-add</emphasis> and <emphasis>git-commit</emphasis>.</simpara>\r
112 <simplesect id="_literal_crlf_literal">\r
113 <title><literal>crlf</literal></title>\r
114 <simpara>This attribute controls the line-ending convention.</simpara>\r
115 <variablelist>\r
116 <varlistentry>\r
117 <term>\r
118 Set\r
119 </term>\r
120 <listitem>\r
121 <simpara>\r
122 Setting the <literal>crlf</literal> attribute on a path is meant to mark\r
123 the path as a "text" file. <emphasis>core.autocrlf</emphasis> conversion\r
124 takes place without guessing the content type by\r
125 inspection.\r
126 </simpara>\r
127 </listitem>\r
128 </varlistentry>\r
129 <varlistentry>\r
130 <term>\r
131 Unset\r
132 </term>\r
133 <listitem>\r
134 <simpara>\r
135 Unsetting the <literal>crlf</literal> attribute on a path tells git not to\r
136 attempt any end-of-line conversion upon checkin or checkout.\r
137 </simpara>\r
138 </listitem>\r
139 </varlistentry>\r
140 <varlistentry>\r
141 <term>\r
142 Unspecified\r
143 </term>\r
144 <listitem>\r
145 <simpara>\r
146 Unspecified <literal>crlf</literal> attribute tells git to apply the\r
147 <literal>core.autocrlf</literal> conversion when the file content looks\r
148 like text.\r
149 </simpara>\r
150 </listitem>\r
151 </varlistentry>\r
152 <varlistentry>\r
153 <term>\r
154 Set to string value "input"\r
155 </term>\r
156 <listitem>\r
157 <simpara>\r
158 This is similar to setting the attribute to <literal>true</literal>, but\r
159 also forces git to act as if <literal>core.autocrlf</literal> is set to\r
160 <literal>input</literal> for the path.\r
161 </simpara>\r
162 </listitem>\r
163 </varlistentry>\r
164 </variablelist>\r
165 <simpara>Any other value set to <literal>crlf</literal> attribute is ignored and git acts\r
166 as if the attribute is left unspecified.</simpara>\r
167 </simplesect>\r
168 <simplesect id="_the_literal_core_autocrlf_literal_conversion">\r
169 <title>The <literal>core.autocrlf</literal> conversion</title>\r
170 <simpara>If the configuration variable <literal>core.autocrlf</literal> is false, no\r
171 conversion is done.</simpara>\r
172 <simpara>When <literal>core.autocrlf</literal> is true, it means that the platform wants\r
173 CRLF line endings for files in the working tree, and you want to\r
174 convert them back to the normal LF line endings when checking\r
175 in to the repository.</simpara>\r
176 <simpara>When <literal>core.autocrlf</literal> is set to "input", line endings are\r
177 converted to LF upon checkin, but there is no conversion done\r
178 upon checkout.</simpara>\r
179 <simpara>If <literal>core.safecrlf</literal> is set to "true" or "warn", git verifies if\r
180 the conversion is reversible for the current setting of\r
181 <literal>core.autocrlf</literal>. For "true", git rejects irreversible\r
182 conversions; for "warn", git only prints a warning but accepts\r
183 an irreversible conversion. The safety triggers to prevent such\r
184 a conversion done to the files in the work tree, but there are a\r
185 few exceptions. Even though…</simpara>\r
186 <itemizedlist>\r
187 <listitem>\r
188 <simpara>\r
189 <emphasis>git-add</emphasis> itself does not touch the files in the work tree, the\r
190 next checkout would, so the safety triggers;\r
191 </simpara>\r
192 </listitem>\r
193 <listitem>\r
194 <simpara>\r
195 <emphasis>git-apply</emphasis> to update a text file with a patch does touch the files\r
196 in the work tree, but the operation is about text files and CRLF\r
197 conversion is about fixing the line ending inconsistencies, so the\r
198 safety does not trigger;\r
199 </simpara>\r
200 </listitem>\r
201 <listitem>\r
202 <simpara>\r
203 <emphasis>git-diff</emphasis> itself does not touch the files in the work tree, it is\r
204 often run to inspect the changes you intend to next <emphasis>git-add</emphasis>. To\r
205 catch potential problems early, safety triggers.\r
206 </simpara>\r
207 </listitem>\r
208 </itemizedlist>\r
209 </simplesect>\r
210 <simplesect id="_literal_ident_literal">\r
211 <title><literal>ident</literal></title>\r
212 <simpara>When the attribute <literal>ident</literal> is set for a path, git replaces\r
213 <literal>$Id$</literal> in the blob object with <literal>$Id:</literal>, followed by the\r
214 40-character hexadecimal blob object name, followed by a dollar\r
215 sign <literal>$</literal> upon checkout. Any byte sequence that begins with\r
216 <literal>$Id:</literal> and ends with <literal>$</literal> in the worktree file is replaced\r
217 with <literal>$Id$</literal> upon check-in.</simpara>\r
218 </simplesect>\r
219 <simplesect id="_literal_filter_literal">\r
220 <title><literal>filter</literal></title>\r
221 <simpara>A <literal>filter</literal> attribute can be set to a string value that names a\r
222 filter driver specified in the configuration.</simpara>\r
223 <simpara>A filter driver consists of a <literal>clean</literal> command and a <literal>smudge</literal>\r
224 command, either of which can be left unspecified. Upon\r
225 checkout, when the <literal>smudge</literal> command is specified, the command is\r
226 fed the blob object from its standard input, and its standard\r
227 output is used to update the worktree file. Similarly, the\r
228 <literal>clean</literal> command is used to convert the contents of worktree file\r
229 upon checkin.</simpara>\r
230 <simpara>A missing filter driver definition in the config is not an error\r
231 but makes the filter a no-op passthru.</simpara>\r
232 <simpara>The content filtering is done to massage the content into a\r
233 shape that is more convenient for the platform, filesystem, and\r
234 the user to use. The key phrase here is "more convenient" and not\r
235 "turning something unusable into usable". In other words, the\r
236 intent is that if someone unsets the filter driver definition,\r
237 or does not have the appropriate filter program, the project\r
238 should still be usable.</simpara>\r
239 </simplesect>\r
240 <simplesect id="_interaction_between_checkin_checkout_attributes">\r
241 <title>Interaction between checkin/checkout attributes</title>\r
242 <simpara>In the check-in codepath, the worktree file is first converted\r
243 with <literal>filter</literal> driver (if specified and corresponding driver\r
244 defined), then the result is processed with <literal>ident</literal> (if\r
245 specified), and then finally with <literal>crlf</literal> (again, if specified\r
246 and applicable).</simpara>\r
247 <simpara>In the check-out codepath, the blob content is first converted\r
248 with <literal>crlf</literal>, and then <literal>ident</literal> and fed to <literal>filter</literal>.</simpara>\r
249 </simplesect>\r
250 </simplesect>\r
251 <simplesect id="_generating_diff_text">\r
252 <title>Generating diff text</title>\r
253 <simplesect id="_literal_diff_literal">\r
254 <title><literal>diff</literal></title>\r
255 <simpara>The attribute <literal>diff</literal> affects how <emphasis>git</emphasis> generates diffs for particular\r
256 files. It can tell git whether to generate a textual patch for the path\r
257 or to treat the path as a binary file. It can also affect what line is\r
258 shown on the hunk header <literal>@@ -k,l +n,m @@</literal> line, tell git to use an\r
259 external command to generate the diff, or ask git to convert binary\r
260 files to a text format before generating the diff.</simpara>\r
261 <variablelist>\r
262 <varlistentry>\r
263 <term>\r
264 Set\r
265 </term>\r
266 <listitem>\r
267 <simpara>\r
268 A path to which the <literal>diff</literal> attribute is set is treated\r
269 as text, even when they contain byte values that\r
270 normally never appear in text files, such as NUL.\r
271 </simpara>\r
272 </listitem>\r
273 </varlistentry>\r
274 <varlistentry>\r
275 <term>\r
276 Unset\r
277 </term>\r
278 <listitem>\r
279 <simpara>\r
280 A path to which the <literal>diff</literal> attribute is unset will\r
281 generate <literal>Binary files differ</literal> (or a binary patch, if\r
282 binary patches are enabled).\r
283 </simpara>\r
284 </listitem>\r
285 </varlistentry>\r
286 <varlistentry>\r
287 <term>\r
288 Unspecified\r
289 </term>\r
290 <listitem>\r
291 <simpara>\r
292 A path to which the <literal>diff</literal> attribute is unspecified\r
293 first gets its contents inspected, and if it looks like\r
294 text, it is treated as text. Otherwise it would\r
295 generate <literal>Binary files differ</literal>.\r
296 </simpara>\r
297 </listitem>\r
298 </varlistentry>\r
299 <varlistentry>\r
300 <term>\r
301 String\r
302 </term>\r
303 <listitem>\r
304 <simpara>\r
305 Diff is shown using the specified diff driver. Each driver may\r
306 specify one or more options, as described in the following\r
307 section. The options for the diff driver "foo" are defined\r
308 by the configuration variables in the "diff.foo" section of the\r
309 git config file.\r
310 </simpara>\r
311 </listitem>\r
312 </varlistentry>\r
313 </variablelist>\r
314 </simplesect>\r
315 <simplesect id="_defining_an_external_diff_driver">\r
316 <title>Defining an external diff driver</title>\r
317 <simpara>The definition of a diff driver is done in <literal>gitconfig</literal>, not\r
318 <literal>gitattributes</literal> file, so strictly speaking this manual page is a\r
319 wrong place to talk about it. However…</simpara>\r
320 <simpara>To define an external diff driver <literal>jcdiff</literal>, add a section to your\r
321 <literal>$GIT_DIR/config</literal> file (or <literal>$HOME/.gitconfig</literal> file) like this:</simpara>\r
322 <literallayout>[diff "jcdiff"]\r
323 command = j-c-diff</literallayout>\r
324 <simpara>When git needs to show you a diff for the path with <literal>diff</literal>\r
325 attribute set to <literal>jcdiff</literal>, it calls the command you specified\r
326 with the above configuration, i.e. <literal>j-c-diff</literal>, with 7\r
327 parameters, just like <literal>GIT_EXTERNAL_DIFF</literal> program is called.\r
328 See <xref linkend="git(1)"/> for details.</simpara>\r
329 </simplesect>\r
330 <simplesect id="_defining_a_custom_hunk_header">\r
331 <title>Defining a custom hunk-header</title>\r
332 <simpara>Each group of changes (called a "hunk") in the textual diff output\r
333 is prefixed with a line of the form:</simpara>\r
334 <literallayout class="monospaced">@@ -k,l +n,m @@ TEXT</literallayout>\r
335 <simpara>This is called a <emphasis>hunk header</emphasis>. The "TEXT" portion is by default a line\r
336 that begins with an alphabet, an underscore or a dollar sign; this\r
337 matches what GNU <emphasis>diff -p</emphasis> output uses. This default selection however\r
338 is not suited for some contents, and you can use a customized pattern\r
339 to make a selection.</simpara>\r
340 <simpara>First, in .gitattributes, you would assign the <literal>diff</literal> attribute\r
341 for paths.</simpara>\r
342 <literallayout>*.tex diff=tex</literallayout>\r
343 <simpara>Then, you would define a "diff.tex.xfuncname" configuration to\r
344 specify a regular expression that matches a line that you would\r
345 want to appear as the hunk header "TEXT", like this:</simpara>\r
346 <literallayout>[diff "tex"]\r
347 xfuncname = "^(\\\\(sub)*section\\{.*)$"</literallayout>\r
348 <simpara>Note. A single level of backslashes are eaten by the\r
349 configuration file parser, so you would need to double the\r
350 backslashes; the pattern above picks a line that begins with a\r
351 backslash, and zero or more occurrences of <literal>sub</literal> followed by\r
352 <literal>section</literal> followed by open brace, to the end of line.</simpara>\r
353 <simpara>There are a few built-in patterns to make this easier, and <literal>tex</literal>\r
354 is one of them, so you do not have to write the above in your\r
355 configuration file (you still need to enable this with the\r
356 attribute mechanism, via <literal>.gitattributes</literal>). The following built in\r
357 patterns are available:</simpara>\r
358 <itemizedlist>\r
359 <listitem>\r
360 <simpara>\r
361 <literal>bibtex</literal> suitable for files with BibTeX coded references.\r
362 </simpara>\r
363 </listitem>\r
364 <listitem>\r
365 <simpara>\r
366 <literal>cpp</literal> suitable for source code in the C and C++ languages.\r
367 </simpara>\r
368 </listitem>\r
369 <listitem>\r
370 <simpara>\r
371 <literal>html</literal> suitable for HTML/XHTML documents.\r
372 </simpara>\r
373 </listitem>\r
374 <listitem>\r
375 <simpara>\r
376 <literal>java</literal> suitable for source code in the Java language.\r
377 </simpara>\r
378 </listitem>\r
379 <listitem>\r
380 <simpara>\r
381 <literal>objc</literal> suitable for source code in the Objective-C language.\r
382 </simpara>\r
383 </listitem>\r
384 <listitem>\r
385 <simpara>\r
386 <literal>pascal</literal> suitable for source code in the Pascal/Delphi language.\r
387 </simpara>\r
388 </listitem>\r
389 <listitem>\r
390 <simpara>\r
391 <literal>php</literal> suitable for source code in the PHP language.\r
392 </simpara>\r
393 </listitem>\r
394 <listitem>\r
395 <simpara>\r
396 <literal>python</literal> suitable for source code in the Python language.\r
397 </simpara>\r
398 </listitem>\r
399 <listitem>\r
400 <simpara>\r
401 <literal>ruby</literal> suitable for source code in the Ruby language.\r
402 </simpara>\r
403 </listitem>\r
404 <listitem>\r
405 <simpara>\r
406 <literal>tex</literal> suitable for source code for LaTeX documents.\r
407 </simpara>\r
408 </listitem>\r
409 </itemizedlist>\r
410 </simplesect>\r
411 <simplesect id="_customizing_word_diff">\r
412 <title>Customizing word diff</title>\r
413 <simpara>You can customize the rules that <literal>git diff --color-words</literal> uses to\r
414 split words in a line, by specifying an appropriate regular expression\r
415 in the "diff.*.wordRegex" configuration variable. For example, in TeX\r
416 a backslash followed by a sequence of letters forms a command, but\r
417 several such commands can be run together without intervening\r
418 whitespace. To separate them, use a regular expression such as</simpara>\r
419 <literallayout>[diff "tex"]\r
420 wordRegex = "\\\\[a-zA-Z]+|[{}]|\\\\.|[^\\{}[:space:]]+"</literallayout>\r
421 <simpara>A built-in pattern is provided for all languages listed in the\r
422 previous section.</simpara>\r
423 </simplesect>\r
424 <simplesect id="_performing_text_diffs_of_binary_files">\r
425 <title>Performing text diffs of binary files</title>\r
426 <simpara>Sometimes it is desirable to see the diff of a text-converted\r
427 version of some binary files. For example, a word processor\r
428 document can be converted to an ASCII text representation, and\r
429 the diff of the text shown. Even though this conversion loses\r
430 some information, the resulting diff is useful for human\r
431 viewing (but cannot be applied directly).</simpara>\r
432 <simpara>The <literal>textconv</literal> config option is used to define a program for\r
433 performing such a conversion. The program should take a single\r
434 argument, the name of a file to convert, and produce the\r
435 resulting text on stdout.</simpara>\r
436 <simpara>For example, to show the diff of the exif information of a\r
437 file instead of the binary information (assuming you have the\r
438 exif tool installed):</simpara>\r
439 <literallayout>[diff "jpg"]\r
440 textconv = exif</literallayout>\r
441 <note><simpara>The text conversion is generally a one-way conversion;\r
442 in this example, we lose the actual image contents and focus\r
443 just on the text data. This means that diffs generated by\r
444 textconv are <emphasis>not</emphasis> suitable for applying. For this reason,\r
445 only <literal>git diff</literal> and the <literal>git log</literal> family of commands (i.e.,\r
446 log, whatchanged, show) will perform text conversion. <literal>git\r
447 format-patch</literal> will never generate this output. If you want to\r
448 send somebody a text-converted diff of a binary file (e.g.,\r
449 because it quickly conveys the changes you have made), you\r
450 should generate it separately and send it as a comment <emphasis>in\r
451 addition to</emphasis> the usual binary diff that you might send.</simpara></note>\r
452 </simplesect>\r
453 </simplesect>\r
454 <simplesect id="_performing_a_three_way_merge">\r
455 <title>Performing a three-way merge</title>\r
456 <simplesect id="_literal_merge_literal">\r
457 <title><literal>merge</literal></title>\r
458 <simpara>The attribute <literal>merge</literal> affects how three versions of a file is\r
459 merged when a file-level merge is necessary during <literal>git merge</literal>,\r
460 and other programs such as <literal>git revert</literal> and <literal>git cherry-pick</literal>.</simpara>\r
461 <variablelist>\r
462 <varlistentry>\r
463 <term>\r
464 Set\r
465 </term>\r
466 <listitem>\r
467 <simpara>\r
468 Built-in 3-way merge driver is used to merge the\r
469 contents in a way similar to <emphasis>merge</emphasis> command of <literal>RCS</literal>\r
470 suite. This is suitable for ordinary text files.\r
471 </simpara>\r
472 </listitem>\r
473 </varlistentry>\r
474 <varlistentry>\r
475 <term>\r
476 Unset\r
477 </term>\r
478 <listitem>\r
479 <simpara>\r
480 Take the version from the current branch as the\r
481 tentative merge result, and declare that the merge has\r
482 conflicts. This is suitable for binary files that does\r
483 not have a well-defined merge semantics.\r
484 </simpara>\r
485 </listitem>\r
486 </varlistentry>\r
487 <varlistentry>\r
488 <term>\r
489 Unspecified\r
490 </term>\r
491 <listitem>\r
492 <simpara>\r
493 By default, this uses the same built-in 3-way merge\r
494 driver as is the case the <literal>merge</literal> attribute is set.\r
495 However, <literal>merge.default</literal> configuration variable can name\r
496 different merge driver to be used for paths to which the\r
497 <literal>merge</literal> attribute is unspecified.\r
498 </simpara>\r
499 </listitem>\r
500 </varlistentry>\r
501 <varlistentry>\r
502 <term>\r
503 String\r
504 </term>\r
505 <listitem>\r
506 <simpara>\r
507 3-way merge is performed using the specified custom\r
508 merge driver. The built-in 3-way merge driver can be\r
509 explicitly specified by asking for "text" driver; the\r
510 built-in "take the current branch" driver can be\r
511 requested with "binary".\r
512 </simpara>\r
513 </listitem>\r
514 </varlistentry>\r
515 </variablelist>\r
516 </simplesect>\r
517 <simplesect id="_built_in_merge_drivers">\r
518 <title>Built-in merge drivers</title>\r
519 <simpara>There are a few built-in low-level merge drivers defined that\r
520 can be asked for via the <literal>merge</literal> attribute.</simpara>\r
521 <variablelist>\r
522 <varlistentry>\r
523 <term>\r
524 text\r
525 </term>\r
526 <listitem>\r
527 <simpara>\r
528 Usual 3-way file level merge for text files. Conflicted\r
529 regions are marked with conflict markers <literal><<<<<<<</literal>,\r
530 <literal>=======</literal> and <literal>>>>>>>></literal>. The version from your branch\r
531 appears before the <literal>=======</literal> marker, and the version\r
532 from the merged branch appears after the <literal>=======</literal>\r
533 marker.\r
534 </simpara>\r
535 </listitem>\r
536 </varlistentry>\r
537 <varlistentry>\r
538 <term>\r
539 binary\r
540 </term>\r
541 <listitem>\r
542 <simpara>\r
543 Keep the version from your branch in the work tree, but\r
544 leave the path in the conflicted state for the user to\r
545 sort out.\r
546 </simpara>\r
547 </listitem>\r
548 </varlistentry>\r
549 <varlistentry>\r
550 <term>\r
551 union\r
552 </term>\r
553 <listitem>\r
554 <simpara>\r
555 Run 3-way file level merge for text files, but take\r
556 lines from both versions, instead of leaving conflict\r
557 markers. This tends to leave the added lines in the\r
558 resulting file in random order and the user should\r
559 verify the result. Do not use this if you do not\r
560 understand the implications.\r
561 </simpara>\r
562 </listitem>\r
563 </varlistentry>\r
564 </variablelist>\r
565 </simplesect>\r
566 <simplesect id="_defining_a_custom_merge_driver">\r
567 <title>Defining a custom merge driver</title>\r
568 <simpara>The definition of a merge driver is done in the <literal>.git/config</literal>\r
569 file, not in the <literal>gitattributes</literal> file, so strictly speaking this\r
570 manual page is a wrong place to talk about it. However…</simpara>\r
571 <simpara>To define a custom merge driver <literal>filfre</literal>, add a section to your\r
572 <literal>$GIT_DIR/config</literal> file (or <literal>$HOME/.gitconfig</literal> file) like this:</simpara>\r
573 <literallayout>[merge "filfre"]\r
574 name = feel-free merge driver\r
575 driver = filfre %O %A %B\r
576 recursive = binary</literallayout>\r
577 <simpara>The <literal>merge.*.name</literal> variable gives the driver a human-readable\r
578 name.</simpara>\r
579 <simpara>The ‘merge.*.driver` variable’s value is used to construct a\r
580 command to run to merge ancestor’s version (<literal>%O</literal>), current\r
581 version (<literal>%A</literal>) and the other branches’ version (<literal>%B</literal>). These\r
582 three tokens are replaced with the names of temporary files that\r
583 hold the contents of these versions when the command line is\r
584 built.</simpara>\r
585 <simpara>The merge driver is expected to leave the result of the merge in\r
586 the file named with <literal>%A</literal> by overwriting it, and exit with zero\r
587 status if it managed to merge them cleanly, or non-zero if there\r
588 were conflicts.</simpara>\r
589 <simpara>The <literal>merge.*.recursive</literal> variable specifies what other merge\r
590 driver to use when the merge driver is called for an internal\r
591 merge between common ancestors, when there are more than one.\r
592 When left unspecified, the driver itself is used for both\r
593 internal merge and the final merge.</simpara>\r
594 </simplesect>\r
595 </simplesect>\r
596 <simplesect id="_checking_whitespace_errors">\r
597 <title>Checking whitespace errors</title>\r
598 <simplesect id="_literal_whitespace_literal">\r
599 <title><literal>whitespace</literal></title>\r
600 <simpara>The <literal>core.whitespace</literal> configuration variable allows you to define what\r
601 <emphasis>diff</emphasis> and <emphasis>apply</emphasis> should consider whitespace errors for all paths in\r
602 the project (See <xref linkend="git-config(1)"/>). This attribute gives you finer\r
603 control per path.</simpara>\r
604 <variablelist>\r
605 <varlistentry>\r
606 <term>\r
607 Set\r
608 </term>\r
609 <listitem>\r
610 <simpara>\r
611 Notice all types of potential whitespace errors known to git.\r
612 </simpara>\r
613 </listitem>\r
614 </varlistentry>\r
615 <varlistentry>\r
616 <term>\r
617 Unset\r
618 </term>\r
619 <listitem>\r
620 <simpara>\r
621 Do not notice anything as error.\r
622 </simpara>\r
623 </listitem>\r
624 </varlistentry>\r
625 <varlistentry>\r
626 <term>\r
627 Unspecified\r
628 </term>\r
629 <listitem>\r
630 <simpara>\r
631 Use the value of <literal>core.whitespace</literal> configuration variable to\r
632 decide what to notice as error.\r
633 </simpara>\r
634 </listitem>\r
635 </varlistentry>\r
636 <varlistentry>\r
637 <term>\r
638 String\r
639 </term>\r
640 <listitem>\r
641 <simpara>\r
642 Specify a comma separate list of common whitespace problems to\r
643 notice in the same format as <literal>core.whitespace</literal> configuration\r
644 variable.\r
645 </simpara>\r
646 </listitem>\r
647 </varlistentry>\r
648 </variablelist>\r
649 </simplesect>\r
650 </simplesect>\r
651 <simplesect id="_creating_an_archive">\r
652 <title>Creating an archive</title>\r
653 <simplesect id="_literal_export_ignore_literal">\r
654 <title><literal>export-ignore</literal></title>\r
655 <simpara>Files and directories with the attribute <literal>export-ignore</literal> won’t be added to\r
656 archive files.</simpara>\r
657 </simplesect>\r
658 <simplesect id="_literal_export_subst_literal">\r
659 <title><literal>export-subst</literal></title>\r
660 <simpara>If the attribute <literal>export-subst</literal> is set for a file then git will expand\r
661 several placeholders when adding this file to an archive. The\r
662 expansion depends on the availability of a commit ID, i.e., if\r
663 <xref linkend="git-archive(1)"/> has been given a tree instead of a commit or a\r
664 tag then no replacement will be done. The placeholders are the same\r
665 as those for the option <literal>--pretty=format:</literal> of <xref linkend="git-log(1)"/>,\r
666 except that they need to be wrapped like this: <literal>$Format:PLACEHOLDERS$</literal>\r
667 in the file. E.g. the string <literal>$Format:%H$</literal> will be replaced by the\r
668 commit hash.</simpara>\r
669 </simplesect>\r
670 </simplesect>\r
671 <simplesect id="_viewing_files_in_gui_tools">\r
672 <title>Viewing files in GUI tools</title>\r
673 <simplesect id="_literal_encoding_literal">\r
674 <title><literal>encoding</literal></title>\r
675 <simpara>The value of this attribute specifies the character encoding that should\r
676 be used by GUI tools (e.g. <xref linkend="gitk(1)"/> and <xref linkend="git-gui(1)"/>) to\r
677 display the contents of the relevant file. Note that due to performance\r
678 considerations <xref linkend="gitk(1)"/> does not use this attribute unless you\r
679 manually enable per-file encodings in its options.</simpara>\r
680 <simpara>If this attribute is not set or has an invalid value, the value of the\r
681 <literal>gui.encoding</literal> configuration variable is used instead\r
682 (See <xref linkend="git-config(1)"/>).</simpara>\r
683 </simplesect>\r
684 </simplesect>\r
685 </simplesect>\r
686 <simplesect id="_using_attribute_macros">\r
687 <title>USING ATTRIBUTE MACROS</title>\r
688 <simpara>You do not want any end-of-line conversions applied to, nor textual diffs\r
689 produced for, any binary file you track. You would need to specify e.g.</simpara>\r
690 <literallayout>*.jpg -crlf -diff</literallayout>\r
691 <simpara>but that may become cumbersome, when you have many attributes. Using\r
692 attribute macros, you can specify groups of attributes set or unset at\r
693 the same time. The system knows a built-in attribute macro, <literal>binary</literal>:</simpara>\r
694 <literallayout>*.jpg binary</literallayout>\r
695 <simpara>which is equivalent to the above. Note that the attribute macros can only\r
696 be "Set" (see the above example that sets "binary" macro as if it were an\r
697 ordinary attribute --- setting it in turn unsets "crlf" and "diff").</simpara>\r
698 </simplesect>\r
699 <simplesect id="_defining_attribute_macros">\r
700 <title>DEFINING ATTRIBUTE MACROS</title>\r
701 <simpara>Custom attribute macros can be defined only in the <literal>.gitattributes</literal> file\r
702 at the toplevel (i.e. not in any subdirectory). The built-in attribute\r
703 macro "binary" is equivalent to:</simpara>\r
704 <literallayout>[attr]binary -diff -crlf</literallayout>\r
705 </simplesect>\r
706 <simplesect id="_example">\r
707 <title>EXAMPLE</title>\r
708 <simpara>If you have these three <literal>gitattributes</literal> file:</simpara>\r
709 <literallayout>(in $GIT_DIR/info/attributes)\r
710 \r
711 a* foo !bar -baz\r
712 \r
713 (in .gitattributes)\r
714 abc foo bar baz\r
715 \r
716 (in t/.gitattributes)\r
717 ab* merge=filfre\r
718 abc -foo -bar\r
719 *.c frotz</literallayout>\r
720 <simpara>the attributes given to path <literal>t/abc</literal> are computed as follows:</simpara>\r
721 <orderedlist numeration="arabic">\r
722 <listitem>\r
723 <simpara>\r
724 By examining <literal>t/.gitattributes</literal> (which is in the same\r
725 directory as the path in question), git finds that the first\r
726 line matches. <literal>merge</literal> attribute is set. It also finds that\r
727 the second line matches, and attributes <literal>foo</literal> and <literal>bar</literal>\r
728 are unset.\r
729 </simpara>\r
730 </listitem>\r
731 <listitem>\r
732 <simpara>\r
733 Then it examines <literal>.gitattributes</literal> (which is in the parent\r
734 directory), and finds that the first line matches, but\r
735 <literal>t/.gitattributes</literal> file already decided how <literal>merge</literal>, <literal>foo</literal>\r
736 and <literal>bar</literal> attributes should be given to this path, so it\r
737 leaves <literal>foo</literal> and <literal>bar</literal> unset. Attribute <literal>baz</literal> is set.\r
738 </simpara>\r
739 </listitem>\r
740 <listitem>\r
741 <simpara>\r
742 Finally it examines <literal>$GIT_DIR/info/attributes</literal>. This file\r
743 is used to override the in-tree settings. The first line is\r
744 a match, and <literal>foo</literal> is set, <literal>bar</literal> is reverted to unspecified\r
745 state, and <literal>baz</literal> is unset.\r
746 </simpara>\r
747 </listitem>\r
748 </orderedlist>\r
749 <simpara>As the result, the attributes assignment to <literal>t/abc</literal> becomes:</simpara>\r
750 <literallayout>foo set to true\r
751 bar unspecified\r
752 baz set to false\r
753 merge set to string value "filfre"\r
754 frotz unspecified</literallayout>\r
755 </simplesect>\r
756 <simplesect id="_git">\r
757 <title>GIT</title>\r
758 <simpara>Part of the <xref linkend="git(1)"/> suite</simpara>\r
759 </simplesect>\r
760 </article>\r