OSDN Git Service

Add Git official document to help
[tortoisegit/TortoiseGitJp.git] / doc / source / en / TortoiseGit / git_doc / gitattributes.html.xml
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&#8217;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&#8230;</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&#8230;</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>&lt;&lt;&lt;&lt;&lt;&lt;&lt;</literal>,\r
530         <literal>=======</literal> and <literal>&gt;&gt;&gt;&gt;&gt;&gt;&gt;</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&#8230;</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 &#8216;merge.*.driver` variable&#8217;s value is used to construct a\r
580 command to run to merge ancestor&#8217;s version (<literal>%O</literal>), current\r
581 version (<literal>%A</literal>) and the other branches&#8217; 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&#8217;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