Google Git
Sign in
chromium / external / gitster / git-htmldocs / 6f1bbb744abfc4656c864209edfbed8f195593b9 / . / gitattributes.html
blob: 55ff9956598d40ac981d122ab46868945c465792 [file] [log] [blame]
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]6<meta name="generator" content="AsciiDoc 8.2.5" />
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]7<style type="text/css">
8/* Debug borders */
9p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
10/*
11 border: 1px solid red;
12*/
13}
14
15body {
16 margin: 1em 5% 1em 5%;
17}
18
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]19a {
20 color: blue;
21 text-decoration: underline;
22}
23a:visited {
24 color: fuchsia;
25}
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]26
27em {
28 font-style: italic;
29}
30
31strong {
32 font-weight: bold;
33}
34
35tt {
36 color: navy;
37}
38
39h1, h2, h3, h4, h5, h6 {
40 color: #527bbd;
41 font-family: sans-serif;
42 margin-top: 1.2em;
43 margin-bottom: 0.5em;
44 line-height: 1.3;
45}
46
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]47h1, h2, h3 {
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]48 border-bottom: 2px solid silver;
49}
50h2 {
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]51 padding-top: 0.5em;
52}
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]53h3 {
54 float: left;
55}
56h3 + * {
57 clear: left;
58}
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]59
60div.sectionbody {
61 font-family: serif;
62 margin-left: 0;
63}
64
65hr {
66 border: 1px solid silver;
67}
68
69p {
70 margin-top: 0.5em;
71 margin-bottom: 0.5em;
72}
73
74pre {
75 padding: 0;
76 margin: 0;
77}
78
79span#author {
80 color: #527bbd;
81 font-family: sans-serif;
82 font-weight: bold;
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]83 font-size: 1.1em;
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]84}
85span#email {
86}
87span#revision {
88 font-family: sans-serif;
89}
90
91div#footer {
92 font-family: sans-serif;
93 font-size: small;
94 border-top: 2px solid silver;
95 padding-top: 0.5em;
96 margin-top: 4.0em;
97}
98div#footer-text {
99 float: left;
100 padding-bottom: 0.5em;
101}
102div#footer-badges {
103 float: right;
104 padding-bottom: 0.5em;
105}
106
107div#preamble,
108div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
109div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
110div.admonitionblock {
111 margin-right: 10%;
112 margin-top: 1.5em;
113 margin-bottom: 1.5em;
114}
115div.admonitionblock {
116 margin-top: 2.5em;
117 margin-bottom: 2.5em;
118}
119
120div.content { /* Block element content. */
121 padding: 0;
122}
123
124/* Block element titles. */
125div.title, caption.title {
126 font-family: sans-serif;
127 font-weight: bold;
128 text-align: left;
129 margin-top: 1.0em;
130 margin-bottom: 0.5em;
131}
132div.title + * {
133 margin-top: 0;
134}
135
136td div.title:first-child {
137 margin-top: 0.0em;
138}
139div.content div.title:first-child {
140 margin-top: 0.0em;
141}
142div.content + div.title {
143 margin-top: 0.0em;
144}
145
146div.sidebarblock > div.content {
147 background: #ffffee;
148 border: 1px solid silver;
149 padding: 0.5em;
150}
151
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]152div.listingblock {
153 margin-right: 0%;
154}
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]155div.listingblock > div.content {
156 border: 1px solid silver;
157 background: #f4f4f4;
158 padding: 0.5em;
159}
160
161div.quoteblock > div.content {
162 padding-left: 2.0em;
163}
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]164
165div.attribution {
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]166 text-align: right;
167}
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]168div.verseblock + div.attribution {
169 text-align: left;
170}
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]171
172div.admonitionblock .icon {
173 vertical-align: top;
174 font-size: 1.1em;
175 font-weight: bold;
176 text-decoration: underline;
177 color: #527bbd;
178 padding-right: 0.5em;
179}
180div.admonitionblock td.content {
181 padding-left: 0.5em;
182 border-left: 2px solid silver;
183}
184
185div.exampleblock > div.content {
186 border-left: 2px solid silver;
187 padding: 0.5em;
188}
189
190div.verseblock div.content {
191 white-space: pre;
192}
193
194div.imageblock div.content { padding-left: 0; }
195div.imageblock img { border: 1px solid silver; }
196span.image img { border-style: none; }
197
198dl {
199 margin-top: 0.8em;
200 margin-bottom: 0.8em;
201}
202dt {
203 margin-top: 0.5em;
204 margin-bottom: 0;
205 font-style: italic;
206}
207dd > *:first-child {
208 margin-top: 0;
209}
210
211ul, ol {
212 list-style-position: outside;
213}
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]214div.olist2 ol {
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]215 list-style-type: lower-alpha;
216}
217
218div.tableblock > table {
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]219 border: 3px solid #527bbd;
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]220}
221thead {
222 font-family: sans-serif;
223 font-weight: bold;
224}
225tfoot {
226 font-weight: bold;
227}
228
229div.hlist {
230 margin-top: 0.8em;
231 margin-bottom: 0.8em;
232}
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]233div.hlist td {
234 padding-bottom: 5px;
235}
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]236td.hlist1 {
237 vertical-align: top;
238 font-style: italic;
239 padding-right: 0.8em;
240}
241td.hlist2 {
242 vertical-align: top;
243}
244
245@media print {
246 div#footer-badges { display: none; }
247}
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]248
249div#toctitle {
250 color: #527bbd;
251 font-family: sans-serif;
252 font-size: 1.1em;
253 font-weight: bold;
254 margin-top: 1.0em;
255 margin-bottom: 0.1em;
256}
257
258div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
259 margin-top: 0;
260 margin-bottom: 0;
261}
262div.toclevel2 {
263 margin-left: 2em;
264 font-size: 0.9em;
265}
266div.toclevel3 {
267 margin-left: 4em;
268 font-size: 0.9em;
269}
270div.toclevel4 {
271 margin-left: 6em;
272 font-size: 0.9em;
273}
274include1::./stylesheets/xhtml11-manpage.css[]
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]275/* Workarounds for IE6's broken and incomplete CSS2. */
276
277div.sidebar-content {
278 background: #ffffee;
279 border: 1px solid silver;
280 padding: 0.5em;
281}
282div.sidebar-title, div.image-title {
283 font-family: sans-serif;
284 font-weight: bold;
285 margin-top: 0.0em;
286 margin-bottom: 0.5em;
287}
288
289div.listingblock div.content {
290 border: 1px solid silver;
291 background: #f4f4f4;
292 padding: 0.5em;
293}
294
295div.quoteblock-content {
296 padding-left: 2.0em;
297}
298
299div.exampleblock-content {
300 border-left: 2px solid silver;
301 padding-left: 0.5em;
302}
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]303
304/* IE6 sets dynamically generated links as visited. */
305div#toc a:visited { color: blue; }
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]306</style>
307<title>gitattributes(5)</title>
308</head>
309<body>
310<div id="header">
311<h1>
312gitattributes(5) Manual Page
313</h1>
314<h2>NAME</h2>
315<div class="sectionbody">
316<p>gitattributes -
317 defining attributes per path
318</p>
319</div>
320</div>
321<h2>SYNOPSIS</h2>
322<div class="sectionbody">
Junio C Hamano17bd2272008-09-01 06:11:17[diff] [blame]323<div class="para"><p>$GIT_DIR/info/attributes, .gitattributes</p></div>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]324</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]325<h2 id="_description">DESCRIPTION</h2>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]326<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]327<div class="para"><p>A <tt>gitattributes</tt> file is a simple text file that gives
328<tt>attributes</tt> to pathnames.</p></div>
329<div class="para"><p>Each line in <tt>gitattributes</tt> file is of form:</p></div>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]330<div class="literalblock">
331<div class="content">
332<pre><tt>glob attr1 attr2 ...</tt></pre>
333</div></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]334<div class="para"><p>That is, a glob pattern followed by an attributes list,
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]335separated by whitespaces. When the glob pattern matches the
336path in question, the attributes listed on the line are given to
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]337the path.</p></div>
338<div class="para"><p>Each attribute can be in one of these states for a given path:</p></div>
339<div class="vlist"><dl>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]340<dt>
341Set
342</dt>
343<dd>
344<p>
345 The path has the attribute with special value "true";
346 this is specified by listing only the name of the
347 attribute in the attribute list.
348</p>
349</dd>
350<dt>
351Unset
352</dt>
353<dd>
354<p>
355 The path has the attribute with special value "false";
356 this is specified by listing the name of the attribute
357 prefixed with a dash <tt>-</tt> in the attribute list.
358</p>
359</dd>
360<dt>
361Set to a value
362</dt>
363<dd>
364<p>
365 The path has the attribute with specified string value;
366 this is specified by listing the name of the attribute
367 followed by an equal sign <tt>=</tt> and its value in the
368 attribute list.
369</p>
370</dd>
371<dt>
372Unspecified
373</dt>
374<dd>
375<p>
376 No glob pattern matches the path, and nothing says if
Junio C Hamano22572e72007-04-25 05:59:25[diff] [blame]377 the path has or does not have the attribute, the
378 attribute for the path is said to be Unspecified.
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]379</p>
380</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]381</dl></div>
382<div class="para"><p>When more than one glob pattern matches the path, a later line
Junio C Hamano22572e72007-04-25 05:59:25[diff] [blame]383overrides an earlier line. This overriding is done per
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]384attribute.</p></div>
385<div class="para"><p>When deciding what attributes are assigned to a path, git
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]386consults <tt>$GIT_DIR/info/attributes</tt> file (which has the highest
387precedence), <tt>.gitattributes</tt> file in the same directory as the
388path in question, and its parent directories (the further the
389directory that contains <tt>.gitattributes</tt> is from the path in
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]390question, the lower its precedence).</p></div>
391<div class="para"><p>If you wish to affect only a single repository (i.e., to assign
Junio C Hamano99dc24a2008-03-27 23:49:50[diff] [blame]392attributes to files that are particular to one user's workflow), then
393attributes should be placed in the <tt>$GIT_DIR/info/attributes</tt> file.
394Attributes which should be version-controlled and distributed to other
395repositories (i.e., attributes of interest to all users) should go into
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]396<tt>.gitattributes</tt> files.</p></div>
397<div class="para"><p>Sometimes you would need to override an setting of an attribute
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]398for a path to <tt>unspecified</tt> state. This can be done by listing
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]399the name of the attribute prefixed with an exclamation point <tt>!</tt>.</p></div>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]400</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]401<h2 id="_effects">EFFECTS</h2>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]402<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]403<div class="para"><p>Certain operations by git can be influenced by assigning
Junio C Hamano2a8f6dc2007-07-09 08:48:38[diff] [blame]404particular attributes to a path. Currently, the following
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]405operations are attributes-aware.</p></div>
406<h3 id="_checking_out_and_checking_in">Checking-out and checking-in</h3><div style="clear:left"></div>
407<div class="para"><p>These attributes affect how the contents stored in the
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]408repository are copied to the working tree files when commands
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]409such as <em>git-checkout</em> and <em>git-merge</em> run. They also affect how
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]410git stores the contents you prepare in the working tree in the
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]411repository upon <em>git-add</em> and <em>git-commit</em>.</p></div>
412<h4 id="_tt_crlf_tt"><tt>crlf</tt></h4>
413<div class="para"><p>This attribute controls the line-ending convention.</p></div>
414<div class="vlist"><dl>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]415<dt>
416Set
417</dt>
418<dd>
419<p>
420 Setting the <tt>crlf</tt> attribute on a path is meant to mark
421 the path as a "text" file. <em>core.autocrlf</em> conversion
422 takes place without guessing the content type by
423 inspection.
424</p>
425</dd>
426<dt>
427Unset
428</dt>
429<dd>
430<p>
Junio C Hamanofcb740a2008-08-31 06:32:05[diff] [blame]431 Unsetting the <tt>crlf</tt> attribute on a path tells git not to
432 attempt any end-of-line conversion upon checkin or checkout.
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]433</p>
434</dd>
435<dt>
436Unspecified
437</dt>
438<dd>
439<p>
440 Unspecified <tt>crlf</tt> attribute tells git to apply the
441 <tt>core.autocrlf</tt> conversion when the file content looks
442 like text.
443</p>
444</dd>
445<dt>
446Set to string value "input"
447</dt>
448<dd>
449<p>
450 This is similar to setting the attribute to <tt>true</tt>, but
451 also forces git to act as if <tt>core.autocrlf</tt> is set to
452 <tt>input</tt> for the path.
453</p>
454</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]455</dl></div>
456<div class="para"><p>Any other value set to <tt>crlf</tt> attribute is ignored and git acts
457as if the attribute is left unspecified.</p></div>
458<h4 id="_the_tt_core_autocrlf_tt_conversion">The <tt>core.autocrlf</tt> conversion</h4>
459<div class="para"><p>If the configuration variable <tt>core.autocrlf</tt> is false, no
460conversion is done.</p></div>
461<div class="para"><p>When <tt>core.autocrlf</tt> is true, it means that the platform wants
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]462CRLF line endings for files in the working tree, and you want to
463convert them back to the normal LF line endings when checking
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]464in to the repository.</p></div>
465<div class="para"><p>When <tt>core.autocrlf</tt> is set to "input", line endings are
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]466converted to LF upon checkin, but there is no conversion done
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]467upon checkout.</p></div>
468<div class="para"><p>If <tt>core.safecrlf</tt> is set to "true" or "warn", git verifies if
Junio C Hamano26e590a2008-02-17 03:53:51[diff] [blame]469the conversion is reversible for the current setting of
470<tt>core.autocrlf</tt>. For "true", git rejects irreversible
471conversions; for "warn", git only prints a warning but accepts
472an irreversible conversion. The safety triggers to prevent such
473a conversion done to the files in the work tree, but there are a
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]474few exceptions. Even though&#8230;</p></div>
475<div class="ilist"><ul>
Junio C Hamano26e590a2008-02-17 03:53:51[diff] [blame]476<li>
477<p>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]478<em>git-add</em> itself does not touch the files in the work tree, the
Junio C Hamano26e590a2008-02-17 03:53:51[diff] [blame]479 next checkout would, so the safety triggers;
480</p>
481</li>
482<li>
483<p>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]484<em>git-apply</em> to update a text file with a patch does touch the files
Junio C Hamano26e590a2008-02-17 03:53:51[diff] [blame]485 in the work tree, but the operation is about text files and CRLF
486 conversion is about fixing the line ending inconsistencies, so the
487 safety does not trigger;
488</p>
489</li>
490<li>
491<p>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]492<em>git-diff</em> itself does not touch the files in the work tree, it is
493 often run to inspect the changes you intend to next <em>git-add</em>. To
Junio C Hamano26e590a2008-02-17 03:53:51[diff] [blame]494 catch potential problems early, safety triggers.
495</p>
496</li>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]497</ul></div>
498<h4 id="_tt_ident_tt"><tt>ident</tt></h4>
Junio C Hamano6f1bbb72008-10-31 11:32:55[diff] [blame^]499<div class="para"><p>When the attribute <tt>ident</tt> is set for a path, git replaces
500<tt>$Id$</tt> in the blob object with <tt>$Id:</tt>, followed by the
Junio C Hamano469d60e2007-04-29 18:30:34[diff] [blame]50140-character hexadecimal blob object name, followed by a dollar
502sign <tt>$</tt> upon checkout. Any byte sequence that begins with
Junio C Hamano0430e3a2007-05-15 03:13:17[diff] [blame]503<tt>$Id:</tt> and ends with <tt>$</tt> in the worktree file is replaced
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]504with <tt>$Id$</tt> upon check-in.</p></div>
505<h4 id="_tt_filter_tt"><tt>filter</tt></h4>
506<div class="para"><p>A <tt>filter</tt> attribute can be set to a string value that names a
507filter driver specified in the configuration.</p></div>
508<div class="para"><p>A filter driver consists of a <tt>clean</tt> command and a <tt>smudge</tt>
Junio C Hamano469d60e2007-04-29 18:30:34[diff] [blame]509command, either of which can be left unspecified. Upon
Junio C Hamano361c1332007-11-14 12:17:22[diff] [blame]510checkout, when the <tt>smudge</tt> command is specified, the command is
511fed the blob object from its standard input, and its standard
512output is used to update the worktree file. Similarly, the
513<tt>clean</tt> command is used to convert the contents of worktree file
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]514upon checkin.</p></div>
515<div class="para"><p>A missing filter driver definition in the config is not an error
516but makes the filter a no-op passthru.</p></div>
517<div class="para"><p>The content filtering is done to massage the content into a
Junio C Hamano469d60e2007-04-29 18:30:34[diff] [blame]518shape that is more convenient for the platform, filesystem, and
Junio C Hamano361c1332007-11-14 12:17:22[diff] [blame]519the user to use. The key phrase here is "more convenient" and not
Junio C Hamano4fd58d42007-09-30 00:51:14[diff] [blame]520"turning something unusable into usable". In other words, the
521intent is that if someone unsets the filter driver definition,
522or does not have the appropriate filter program, the project
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]523should still be usable.</p></div>
524<h4 id="_interaction_between_checkin_checkout_attributes">Interaction between checkin/checkout attributes</h4>
525<div class="para"><p>In the check-in codepath, the worktree file is first converted
Junio C Hamano469d60e2007-04-29 18:30:34[diff] [blame]526with <tt>filter</tt> driver (if specified and corresponding driver
527defined), then the result is processed with <tt>ident</tt> (if
528specified), and then finally with <tt>crlf</tt> (again, if specified
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]529and applicable).</p></div>
530<div class="para"><p>In the check-out codepath, the blob content is first converted
531with <tt>crlf</tt>, and then <tt>ident</tt> and fed to <tt>filter</tt>.</p></div>
532<h3 id="_generating_diff_text">Generating diff text</h3><div style="clear:left"></div>
533<div class="para"><p>The attribute <tt>diff</tt> affects if <em>git-diff</em> generates textual
Junio C Hamano2a8f6dc2007-07-09 08:48:38[diff] [blame]534patch for the path or just says <tt>Binary files differ</tt>. It also
535can affect what line is shown on the hunk header <tt>@@ -k,l +n,m @@</tt>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]536line.</p></div>
537<div class="vlist"><dl>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]538<dt>
539Set
540</dt>
541<dd>
542<p>
543 A path to which the <tt>diff</tt> attribute is set is treated
544 as text, even when they contain byte values that
545 normally never appear in text files, such as NUL.
546</p>
547</dd>
548<dt>
549Unset
550</dt>
551<dd>
552<p>
553 A path to which the <tt>diff</tt> attribute is unset will
554 generate <tt>Binary files differ</tt>.
555</p>
556</dd>
557<dt>
558Unspecified
559</dt>
560<dd>
561<p>
562 A path to which the <tt>diff</tt> attribute is unspecified
563 first gets its contents inspected, and if it looks like
564 text, it is treated as text. Otherwise it would
565 generate <tt>Binary files differ</tt>.
566</p>
567</dd>
Junio C Hamano9db95ca2007-04-23 07:27:05[diff] [blame]568<dt>
569String
570</dt>
571<dd>
572<p>
573 Diff is shown using the specified custom diff driver.
574 The driver program is given its input using the same
575 calling convention as used for GIT_EXTERNAL_DIFF
Junio C Hamano2a8f6dc2007-07-09 08:48:38[diff] [blame]576 program. This name is also used for custom hunk header
577 selection.
Junio C Hamano9db95ca2007-04-23 07:27:05[diff] [blame]578</p>
579</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]580</dl></div>
581<h4 id="_defining_a_custom_diff_driver">Defining a custom diff driver</h4>
582<div class="para"><p>The definition of a diff driver is done in <tt>gitconfig</tt>, not
Junio C Hamano9db95ca2007-04-23 07:27:05[diff] [blame]583<tt>gitattributes</tt> file, so strictly speaking this manual page is a
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]584wrong place to talk about it. However&#8230;</p></div>
585<div class="para"><p>To define a custom diff driver <tt>jcdiff</tt>, add a section to your
586<tt>$GIT_DIR/config</tt> file (or <tt>$HOME/.gitconfig</tt> file) like this:</p></div>
Junio C Hamano9db95ca2007-04-23 07:27:05[diff] [blame]587<div class="listingblock">
588<div class="content">
589<pre><tt>[diff "jcdiff"]
590 command = j-c-diff</tt></pre>
591</div></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]592<div class="para"><p>When git needs to show you a diff for the path with <tt>diff</tt>
Junio C Hamano9db95ca2007-04-23 07:27:05[diff] [blame]593attribute set to <tt>jcdiff</tt>, it calls the command you specified
594with the above configuration, i.e. <tt>j-c-diff</tt>, with 7
595parameters, just like <tt>GIT_EXTERNAL_DIFF</tt> program is called.
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]596See <a href="git.html">git(1)</a> for details.</p></div>
597<h4 id="_defining_a_custom_hunk_header">Defining a custom hunk-header</h4>
Junio C Hamano5e4d8de2008-09-19 06:27:02[diff] [blame]598<div class="para"><p>Each group of changes (called a "hunk") in the textual diff output
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]599is prefixed with a line of the form:</p></div>
Junio C Hamano2a8f6dc2007-07-09 08:48:38[diff] [blame]600<div class="literalblock">
601<div class="content">
602<pre><tt>@@ -k,l +n,m @@ TEXT</tt></pre>
603</div></div>
Junio C Hamano5e4d8de2008-09-19 06:27:02[diff] [blame]604<div class="para"><p>This is called a <em>hunk header</em>. The "TEXT" portion is by default a line
605that begins with an alphabet, an underscore or a dollar sign; this
606matches what GNU <em>diff -p</em> output uses. This default selection however
607is not suited for some contents, and you can use a customized pattern
608to make a selection.</p></div>
609<div class="para"><p>First, in .gitattributes, you would assign the <tt>diff</tt> attribute
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]610for paths.</p></div>
Junio C Hamano2a8f6dc2007-07-09 08:48:38[diff] [blame]611<div class="listingblock">
612<div class="content">
613<pre><tt>*.tex diff=tex</tt></pre>
614</div></div>
Junio C Hamanoa476efa2008-10-10 15:31:42[diff] [blame]615<div class="para"><p>Then, you would define a "diff.tex.xfuncname" configuration to
Junio C Hamano2a8f6dc2007-07-09 08:48:38[diff] [blame]616specify a regular expression that matches a line that you would
Junio C Hamano5e4d8de2008-09-19 06:27:02[diff] [blame]617want to appear as the hunk header "TEXT", like this:</p></div>
Junio C Hamano2a8f6dc2007-07-09 08:48:38[diff] [blame]618<div class="listingblock">
619<div class="content">
620<pre><tt>[diff "tex"]
Junio C Hamanoa476efa2008-10-10 15:31:42[diff] [blame]621 xfuncname = "^(\\\\(sub)*section\\{.*)$"</tt></pre>
Junio C Hamano2a8f6dc2007-07-09 08:48:38[diff] [blame]622</div></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]623<div class="para"><p>Note. A single level of backslashes are eaten by the
Junio C Hamano2a8f6dc2007-07-09 08:48:38[diff] [blame]624configuration file parser, so you would need to double the
625backslashes; the pattern above picks a line that begins with a
Junio C Hamanoa6387422007-08-25 03:54:27[diff] [blame]626backslash, and zero or more occurrences of <tt>sub</tt> followed by
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]627<tt>section</tt> followed by open brace, to the end of line.</p></div>
628<div class="para"><p>There are a few built-in patterns to make this easier, and <tt>tex</tt>
Junio C Hamano2a8f6dc2007-07-09 08:48:38[diff] [blame]629is one of them, so you do not have to write the above in your
630configuration file (you still need to enable this with the
Junio C Hamanoa76cb0d2008-08-13 20:04:10[diff] [blame]631attribute mechanism, via <tt>.gitattributes</tt>). The following built in
632patterns are available:</p></div>
633<div class="ilist"><ul>
634<li>
635<p>
636<tt>bibtex</tt> suitable for files with BibTeX coded references.
637</p>
638</li>
639<li>
640<p>
Junio C Hamanof24b8062008-09-09 01:34:39[diff] [blame]641<tt>html</tt> suitable for HTML/XHTML documents.
642</p>
643</li>
644<li>
645<p>
Junio C Hamano675570c2008-09-13 06:07:28[diff] [blame]646<tt>java</tt> suitable for source code in the Java language.
Junio C Hamanoa76cb0d2008-08-13 20:04:10[diff] [blame]647</p>
648</li>
649<li>
650<p>
Junio C Hamanoa476efa2008-10-10 15:31:42[diff] [blame]651<tt>objc</tt> suitable for source code in the Objective-C language.
652</p>
653</li>
654<li>
655<p>
Junio C Hamanoa76cb0d2008-08-13 20:04:10[diff] [blame]656<tt>pascal</tt> suitable for source code in the Pascal/Delphi language.
657</p>
658</li>
659<li>
660<p>
Junio C Hamanof24b8062008-09-09 01:34:39[diff] [blame]661<tt>php</tt> suitable for source code in the PHP language.
662</p>
663</li>
664<li>
665<p>
Junio C Hamano3f2f6e52008-08-21 10:34:22[diff] [blame]666<tt>python</tt> suitable for source code in the Python language.
667</p>
668</li>
669<li>
670<p>
Junio C Hamanoa76cb0d2008-08-13 20:04:10[diff] [blame]671<tt>ruby</tt> suitable for source code in the Ruby language.
672</p>
673</li>
674<li>
675<p>
676<tt>tex</tt> suitable for source code for LaTeX documents.
677</p>
678</li>
679</ul></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]680<h3 id="_performing_a_three_way_merge">Performing a three-way merge</h3><div style="clear:left"></div>
681<div class="para"><p>The attribute <tt>merge</tt> affects how three versions of a file is
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]682merged when a file-level merge is necessary during <tt>git merge</tt>,
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]683and other programs such as <tt>git revert</tt> and <tt>git cherry-pick</tt>.</p></div>
684<div class="vlist"><dl>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]685<dt>
686Set
687</dt>
688<dd>
689<p>
690 Built-in 3-way merge driver is used to merge the
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]691 contents in a way similar to <em>merge</em> command of <tt>RCS</tt>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]692 suite. This is suitable for ordinary text files.
693</p>
694</dd>
695<dt>
696Unset
697</dt>
698<dd>
699<p>
700 Take the version from the current branch as the
701 tentative merge result, and declare that the merge has
702 conflicts. This is suitable for binary files that does
703 not have a well-defined merge semantics.
704</p>
705</dd>
706<dt>
707Unspecified
708</dt>
709<dd>
710<p>
711 By default, this uses the same built-in 3-way merge
712 driver as is the case the <tt>merge</tt> attribute is set.
713 However, <tt>merge.default</tt> configuration variable can name
714 different merge driver to be used for paths to which the
715 <tt>merge</tt> attribute is unspecified.
716</p>
717</dd>
718<dt>
Junio C Hamano9db95ca2007-04-23 07:27:05[diff] [blame]719String
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]720</dt>
721<dd>
722<p>
723 3-way merge is performed using the specified custom
724 merge driver. The built-in 3-way merge driver can be
725 explicitly specified by asking for "text" driver; the
726 built-in "take the current branch" driver can be
Junio C Hamano22572e72007-04-25 05:59:25[diff] [blame]727 requested with "binary".
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]728</p>
729</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]730</dl></div>
731<h4 id="_built_in_merge_drivers">Built-in merge drivers</h4>
732<div class="para"><p>There are a few built-in low-level merge drivers defined that
733can be asked for via the <tt>merge</tt> attribute.</p></div>
734<div class="vlist"><dl>
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]735<dt>
736text
737</dt>
738<dd>
739<p>
740 Usual 3-way file level merge for text files. Conflicted
741 regions are marked with conflict markers <tt>&lt;&lt;&lt;&lt;&lt;&lt;&lt;</tt>,
742 <tt>=======</tt> and <tt>&gt;&gt;&gt;&gt;&gt;&gt;&gt;</tt>. The version from your branch
743 appears before the <tt>=======</tt> marker, and the version
744 from the merged branch appears after the <tt>=======</tt>
745 marker.
746</p>
747</dd>
748<dt>
749binary
750</dt>
751<dd>
752<p>
753 Keep the version from your branch in the work tree, but
754 leave the path in the conflicted state for the user to
755 sort out.
756</p>
757</dd>
758<dt>
759union
760</dt>
761<dd>
762<p>
763 Run 3-way file level merge for text files, but take
764 lines from both versions, instead of leaving conflict
765 markers. This tends to leave the added lines in the
766 resulting file in random order and the user should
767 verify the result. Do not use this if you do not
768 understand the implications.
769</p>
770</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]771</dl></div>
772<h4 id="_defining_a_custom_merge_driver">Defining a custom merge driver</h4>
773<div class="para"><p>The definition of a merge driver is done in the <tt>.git/config</tt>
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]774file, not in the <tt>gitattributes</tt> file, so strictly speaking this
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]775manual page is a wrong place to talk about it. However&#8230;</p></div>
776<div class="para"><p>To define a custom merge driver <tt>filfre</tt>, add a section to your
777<tt>$GIT_DIR/config</tt> file (or <tt>$HOME/.gitconfig</tt> file) like this:</p></div>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]778<div class="listingblock">
779<div class="content">
780<pre><tt>[merge "filfre"]
781 name = feel-free merge driver
782 driver = filfre %O %A %B
783 recursive = binary</tt></pre>
784</div></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]785<div class="para"><p>The <tt>merge.*.name</tt> variable gives the driver a human-readable
786name.</p></div>
787<div class="para"><p>The <tt>merge.*.driver</tt> variable's value is used to construct a
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]788command to run to merge ancestor's version (<tt>%O</tt>), current
789version (<tt>%A</tt>) and the other branches' version (<tt>%B</tt>). These
790three tokens are replaced with the names of temporary files that
791hold the contents of these versions when the command line is
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]792built.</p></div>
793<div class="para"><p>The merge driver is expected to leave the result of the merge in
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]794the file named with <tt>%A</tt> by overwriting it, and exit with zero
795status if it managed to merge them cleanly, or non-zero if there
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]796were conflicts.</p></div>
797<div class="para"><p>The <tt>merge.*.recursive</tt> variable specifies what other merge
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]798driver to use when the merge driver is called for an internal
799merge between common ancestors, when there are more than one.
800When left unspecified, the driver itself is used for both
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]801internal merge and the final merge.</p></div>
802<h3 id="_checking_whitespace_errors">Checking whitespace errors</h3><div style="clear:left"></div>
803<h4 id="_tt_whitespace_tt"><tt>whitespace</tt></h4>
804<div class="para"><p>The <tt>core.whitespace</tt> configuration variable allows you to define what
805<em>diff</em> and <em>apply</em> should consider whitespace errors for all paths in
Junio C Hamano942b35e2007-12-09 10:19:33[diff] [blame]806the project (See <a href="git-config.html">git-config(1)</a>). This attribute gives you finer
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]807control per path.</p></div>
808<div class="vlist"><dl>
Junio C Hamano942b35e2007-12-09 10:19:33[diff] [blame]809<dt>
810Set
811</dt>
812<dd>
813<p>
814 Notice all types of potential whitespace errors known to git.
815</p>
816</dd>
817<dt>
818Unset
819</dt>
820<dd>
821<p>
822 Do not notice anything as error.
823</p>
824</dd>
825<dt>
826Unspecified
827</dt>
828<dd>
829<p>
830 Use the value of <tt>core.whitespace</tt> configuration variable to
831 decide what to notice as error.
832</p>
833</dd>
834<dt>
835String
836</dt>
837<dd>
838<p>
839 Specify a comma separate list of common whitespace problems to
840 notice in the same format as <tt>core.whitespace</tt> configuration
841 variable.
842</p>
843</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]844</dl></div>
845<h3 id="_creating_an_archive">Creating an archive</h3><div style="clear:left"></div>
846<h4 id="_tt_export_ignore_tt"><tt>export-ignore</tt></h4>
847<div class="para"><p>Files and directories with the attribute <tt>export-ignore</tt> won't be added to
848archive files.</p></div>
849<h4 id="_tt_export_subst_tt"><tt>export-subst</tt></h4>
850<div class="para"><p>If the attribute <tt>export-subst</tt> is set for a file then git will expand
851several placeholders when adding this file to an archive. The
852expansion depends on the availability of a commit ID, i.e., if
853<a href="git-archive.html">git-archive(1)</a> has been given a tree instead of a commit or a
854tag then no replacement will be done. The placeholders are the same
855as those for the option <tt>--pretty=format:</tt> of <a href="git-log.html">git-log(1)</a>,
856except that they need to be wrapped like this: <tt>$Format:PLACEHOLDERS$</tt>
857in the file. E.g. the string <tt>$Format:%H$</tt> will be replaced by the
858commit hash.</p></div>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]859</div>
Junio C Hamanofcb740a2008-08-31 06:32:05[diff] [blame]860<h2 id="_using_attribute_macros">USING ATTRIBUTE MACROS</h2>
861<div class="sectionbody">
862<div class="para"><p>You do not want any end-of-line conversions applied to, nor textual diffs
863produced for, any binary file you track. You would need to specify e.g.</p></div>
864<div class="listingblock">
865<div class="content">
866<pre><tt>*.jpg -crlf -diff</tt></pre>
867</div></div>
868<div class="para"><p>but that may become cumbersome, when you have many attributes. Using
869attribute macros, you can specify groups of attributes set or unset at
870the same time. The system knows a built-in attribute macro, <tt>binary</tt>:</p></div>
871<div class="listingblock">
872<div class="content">
873<pre><tt>*.jpg binary</tt></pre>
874</div></div>
875<div class="para"><p>which is equivalent to the above. Note that the attribute macros can only
876be "Set" (see the above example that sets "binary" macro as if it were an
877ordinary attribute --- setting it in turn unsets "crlf" and "diff").</p></div>
878</div>
879<h2 id="_defining_attribute_macros">DEFINING ATTRIBUTE MACROS</h2>
880<div class="sectionbody">
881<div class="para"><p>Custom attribute macros can be defined only in the <tt>.gitattributes</tt> file
882at the toplevel (i.e. not in any subdirectory). The built-in attribute
883macro "binary" is equivalent to:</p></div>
884<div class="listingblock">
885<div class="content">
886<pre><tt>[attr]binary -diff -crlf</tt></pre>
887</div></div>
888</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]889<h2 id="_example">EXAMPLE</h2>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]890<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]891<div class="para"><p>If you have these three <tt>gitattributes</tt> file:</p></div>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]892<div class="listingblock">
893<div class="content">
894<pre><tt>(in $GIT_DIR/info/attributes)
895
896a* foo !bar -baz
897
898(in .gitattributes)
899abc foo bar baz
900
901(in t/.gitattributes)
902ab* merge=filfre
903abc -foo -bar
904*.c frotz</tt></pre>
905</div></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]906<div class="para"><p>the attributes given to path <tt>t/abc</tt> are computed as follows:</p></div>
907<div class="olist"><ol>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]908<li>
909<p>
910By examining <tt>t/.gitattributes</tt> (which is in the same
Junio C Hamanoa6387422007-08-25 03:54:27[diff] [blame]911 directory as the path in question), git finds that the first
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]912 line matches. <tt>merge</tt> attribute is set. It also finds that
913 the second line matches, and attributes <tt>foo</tt> and <tt>bar</tt>
914 are unset.
915</p>
916</li>
917<li>
918<p>
919Then it examines <tt>.gitattributes</tt> (which is in the parent
920 directory), and finds that the first line matches, but
921 <tt>t/.gitattributes</tt> file already decided how <tt>merge</tt>, <tt>foo</tt>
922 and <tt>bar</tt> attributes should be given to this path, so it
923 leaves <tt>foo</tt> and <tt>bar</tt> unset. Attribute <tt>baz</tt> is set.
924</p>
925</li>
926<li>
927<p>
Junio C Hamanobdeff822007-07-30 09:07:17[diff] [blame]928Finally it examines <tt>$GIT_DIR/info/attributes</tt>. This file
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]929 is used to override the in-tree settings. The first line is
930 a match, and <tt>foo</tt> is set, <tt>bar</tt> is reverted to unspecified
931 state, and <tt>baz</tt> is unset.
932</p>
933</li>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]934</ol></div>
935<div class="para"><p>As the result, the attributes assignment to <tt>t/abc</tt> becomes:</p></div>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]936<div class="listingblock">
937<div class="content">
938<pre><tt>foo set to true
939bar unspecified
940baz set to false
941merge set to string value "filfre"
942frotz unspecified</tt></pre>
943</div></div>
944</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]945<h2 id="_git">GIT</h2>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]946<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]947<div class="para"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]948</div>
949<div id="footer">
950<div id="footer-text">
Junio C Hamano6f1bbb72008-10-31 11:32:55[diff] [blame^]951Last updated 2008-10-31 11:28:59 UTC
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]952</div>
953</div>
954</body>
955</html>