Google Git
Sign in
chromium / external / gitster / git-htmldocs / c756926d575a42433fb764a16b48327974208afb / . / gitattributes.html
blob: f869933deb0b8552c889a3e001d0f9abfe5bacab [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>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]5<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]6<meta name="generator" content="AsciiDoc 8.6.9" />
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]7<title>gitattributes(5)</title>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]8<style type="text/css">
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]9/* Shared CSS for AsciiDoc xhtml11 and html5 backends */
10
11/* Default font. */
12body {
13 font-family: Georgia,serif;
14}
15
16/* Title font. */
17h1, h2, h3, h4, h5, h6,
18div.title, caption.title,
19thead, p.table.header,
20#toctitle,
21#author, #revnumber, #revdate, #revremark,
22#footer {
23 font-family: Arial,Helvetica,sans-serif;
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]24}
25
26body {
27 margin: 1em 5% 1em 5%;
28}
29
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]30a {
31 color: blue;
32 text-decoration: underline;
33}
34a:visited {
35 color: fuchsia;
36}
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]37
38em {
39 font-style: italic;
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]40 color: navy;
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]41}
42
43strong {
44 font-weight: bold;
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]45 color: #083194;
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]46}
47
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]48h1, h2, h3, h4, h5, h6 {
49 color: #527bbd;
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]50 margin-top: 1.2em;
51 margin-bottom: 0.5em;
52 line-height: 1.3;
53}
54
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]55h1, h2, h3 {
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]56 border-bottom: 2px solid silver;
57}
58h2 {
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]59 padding-top: 0.5em;
60}
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]61h3 {
62 float: left;
63}
64h3 + * {
65 clear: left;
66}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]67h5 {
68 font-size: 1.0em;
69}
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]70
71div.sectionbody {
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]72 margin-left: 0;
73}
74
75hr {
76 border: 1px solid silver;
77}
78
79p {
80 margin-top: 0.5em;
81 margin-bottom: 0.5em;
82}
83
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]84ul, ol, li > p {
85 margin-top: 0;
86}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]87ul > li { color: #aaa; }
88ul > li > * { color: black; }
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]89
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]90.monospaced, code, pre {
91 font-family: "Courier New", Courier, monospace;
92 font-size: inherit;
93 color: navy;
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]94 padding: 0;
95 margin: 0;
96}
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]97pre {
98 white-space: pre-wrap;
99}
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]100
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]101#author {
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]102 color: #527bbd;
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]103 font-weight: bold;
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]104 font-size: 1.1em;
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]105}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]106#email {
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]107}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]108#revnumber, #revdate, #revremark {
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]109}
110
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]111#footer {
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]112 font-size: small;
113 border-top: 2px solid silver;
114 padding-top: 0.5em;
115 margin-top: 4.0em;
116}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]117#footer-text {
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]118 float: left;
119 padding-bottom: 0.5em;
120}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]121#footer-badges {
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]122 float: right;
123 padding-bottom: 0.5em;
124}
125
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]126#preamble {
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]127 margin-top: 1.5em;
128 margin-bottom: 1.5em;
129}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]130div.imageblock, div.exampleblock, div.verseblock,
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]131div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
132div.admonitionblock {
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]133 margin-top: 1.0em;
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]134 margin-bottom: 1.5em;
135}
136div.admonitionblock {
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]137 margin-top: 2.0em;
138 margin-bottom: 2.0em;
139 margin-right: 10%;
140 color: #606060;
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]141}
142
143div.content { /* Block element content. */
144 padding: 0;
145}
146
147/* Block element titles. */
148div.title, caption.title {
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]149 color: #527bbd;
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]150 font-weight: bold;
151 text-align: left;
152 margin-top: 1.0em;
153 margin-bottom: 0.5em;
154}
155div.title + * {
156 margin-top: 0;
157}
158
159td div.title:first-child {
160 margin-top: 0.0em;
161}
162div.content div.title:first-child {
163 margin-top: 0.0em;
164}
165div.content + div.title {
166 margin-top: 0.0em;
167}
168
169div.sidebarblock > div.content {
170 background: #ffffee;
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]171 border: 1px solid #dddddd;
172 border-left: 4px solid #f0f0f0;
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]173 padding: 0.5em;
174}
175
176div.listingblock > div.content {
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]177 border: 1px solid #dddddd;
178 border-left: 5px solid #f0f0f0;
179 background: #f8f8f8;
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]180 padding: 0.5em;
181}
182
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]183div.quoteblock, div.verseblock {
184 padding-left: 1.0em;
185 margin-left: 1.0em;
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]186 margin-right: 10%;
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]187 border-left: 5px solid #f0f0f0;
188 color: #888;
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]189}
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]190
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]191div.quoteblock > div.attribution {
192 padding-top: 0.5em;
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]193 text-align: right;
194}
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]195
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]196div.verseblock > pre.content {
197 font-family: inherit;
198 font-size: inherit;
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]199}
200div.verseblock > div.attribution {
201 padding-top: 0.75em;
202 text-align: left;
203}
204/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]205div.verseblock + div.attribution {
206 text-align: left;
207}
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]208
209div.admonitionblock .icon {
210 vertical-align: top;
211 font-size: 1.1em;
212 font-weight: bold;
213 text-decoration: underline;
214 color: #527bbd;
215 padding-right: 0.5em;
216}
217div.admonitionblock td.content {
218 padding-left: 0.5em;
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]219 border-left: 3px solid #dddddd;
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]220}
221
222div.exampleblock > div.content {
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]223 border-left: 3px solid #dddddd;
224 padding-left: 0.5em;
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]225}
226
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]227div.imageblock div.content { padding-left: 0; }
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]228span.image img { border-style: none; vertical-align: text-bottom; }
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]229a.image:visited { color: white; }
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]230
231dl {
232 margin-top: 0.8em;
233 margin-bottom: 0.8em;
234}
235dt {
236 margin-top: 0.5em;
237 margin-bottom: 0;
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]238 font-style: normal;
239 color: navy;
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]240}
241dd > *:first-child {
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]242 margin-top: 0.1em;
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]243}
244
245ul, ol {
246 list-style-position: outside;
247}
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]248ol.arabic {
249 list-style-type: decimal;
250}
251ol.loweralpha {
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]252 list-style-type: lower-alpha;
253}
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]254ol.upperalpha {
255 list-style-type: upper-alpha;
256}
257ol.lowerroman {
258 list-style-type: lower-roman;
259}
260ol.upperroman {
261 list-style-type: upper-roman;
262}
263
264div.compact ul, div.compact ol,
265div.compact p, div.compact p,
266div.compact div, div.compact div {
267 margin-top: 0.1em;
268 margin-bottom: 0.1em;
269}
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]270
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]271tfoot {
272 font-weight: bold;
273}
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]274td > div.verse {
275 white-space: pre;
276}
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]277
278div.hdlist {
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]279 margin-top: 0.8em;
280 margin-bottom: 0.8em;
281}
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]282div.hdlist tr {
283 padding-bottom: 15px;
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]284}
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]285dt.hdlist1.strong, td.hdlist1.strong {
286 font-weight: bold;
287}
288td.hdlist1 {
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]289 vertical-align: top;
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]290 font-style: normal;
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]291 padding-right: 0.8em;
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]292 color: navy;
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]293}
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]294td.hdlist2 {
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]295 vertical-align: top;
296}
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]297div.hdlist.compact tr {
298 margin: 0;
299 padding-bottom: 0;
300}
301
302.comment {
303 background: yellow;
304}
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]305
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]306.footnote, .footnoteref {
307 font-size: 0.8em;
308}
309
310span.footnote, span.footnoteref {
311 vertical-align: super;
312}
313
314#footnotes {
315 margin: 20px 0 20px 0;
316 padding: 7px 0 0 0;
317}
318
319#footnotes div.footnote {
320 margin: 0 0 5px 0;
321}
322
323#footnotes hr {
324 border: none;
325 border-top: 1px solid silver;
326 height: 1px;
327 text-align: left;
328 margin-left: 0;
329 width: 20%;
330 min-width: 100px;
331}
332
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]333div.colist td {
334 padding-right: 0.5em;
335 padding-bottom: 0.3em;
336 vertical-align: top;
337}
338div.colist td img {
339 margin-top: 0.3em;
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]340}
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]341
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]342@media print {
343 #footer-badges { display: none; }
344}
345
346#toc {
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]347 margin-bottom: 2.5em;
348}
349
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]350#toctitle {
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]351 color: #527bbd;
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]352 font-size: 1.1em;
353 font-weight: bold;
354 margin-top: 1.0em;
355 margin-bottom: 0.1em;
356}
357
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]358div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]359 margin-top: 0;
360 margin-bottom: 0;
361}
362div.toclevel2 {
363 margin-left: 2em;
364 font-size: 0.9em;
365}
366div.toclevel3 {
367 margin-left: 4em;
368 font-size: 0.9em;
369}
370div.toclevel4 {
371 margin-left: 6em;
372 font-size: 0.9em;
373}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]374
375span.aqua { color: aqua; }
376span.black { color: black; }
377span.blue { color: blue; }
378span.fuchsia { color: fuchsia; }
379span.gray { color: gray; }
380span.green { color: green; }
381span.lime { color: lime; }
382span.maroon { color: maroon; }
383span.navy { color: navy; }
384span.olive { color: olive; }
385span.purple { color: purple; }
386span.red { color: red; }
387span.silver { color: silver; }
388span.teal { color: teal; }
389span.white { color: white; }
390span.yellow { color: yellow; }
391
392span.aqua-background { background: aqua; }
393span.black-background { background: black; }
394span.blue-background { background: blue; }
395span.fuchsia-background { background: fuchsia; }
396span.gray-background { background: gray; }
397span.green-background { background: green; }
398span.lime-background { background: lime; }
399span.maroon-background { background: maroon; }
400span.navy-background { background: navy; }
401span.olive-background { background: olive; }
402span.purple-background { background: purple; }
403span.red-background { background: red; }
404span.silver-background { background: silver; }
405span.teal-background { background: teal; }
406span.white-background { background: white; }
407span.yellow-background { background: yellow; }
408
409span.big { font-size: 2em; }
410span.small { font-size: 0.6em; }
411
412span.underline { text-decoration: underline; }
413span.overline { text-decoration: overline; }
414span.line-through { text-decoration: line-through; }
415
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]416div.unbreakable { page-break-inside: avoid; }
417
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]418
419/*
420 * xhtml11 specific
421 *
422 * */
423
424div.tableblock {
425 margin-top: 1.0em;
426 margin-bottom: 1.5em;
427}
428div.tableblock > table {
429 border: 3px solid #527bbd;
430}
431thead, p.table.header {
432 font-weight: bold;
433 color: #527bbd;
434}
435p.table {
436 margin-top: 0;
437}
438/* Because the table frame attribute is overriden by CSS in most browsers. */
439div.tableblock > table[frame="void"] {
440 border-style: none;
441}
442div.tableblock > table[frame="hsides"] {
443 border-left-style: none;
444 border-right-style: none;
445}
446div.tableblock > table[frame="vsides"] {
447 border-top-style: none;
448 border-bottom-style: none;
449}
450
451
452/*
453 * html5 specific
454 *
455 * */
456
457table.tableblock {
458 margin-top: 1.0em;
459 margin-bottom: 1.5em;
460}
461thead, p.tableblock.header {
462 font-weight: bold;
463 color: #527bbd;
464}
465p.tableblock {
466 margin-top: 0;
467}
468table.tableblock {
469 border-width: 3px;
470 border-spacing: 0px;
471 border-style: solid;
472 border-color: #527bbd;
473 border-collapse: collapse;
474}
475th.tableblock, td.tableblock {
476 border-width: 1px;
477 padding: 4px;
478 border-style: solid;
479 border-color: #527bbd;
480}
481
482table.tableblock.frame-topbot {
483 border-left-style: hidden;
484 border-right-style: hidden;
485}
486table.tableblock.frame-sides {
487 border-top-style: hidden;
488 border-bottom-style: hidden;
489}
490table.tableblock.frame-none {
491 border-style: hidden;
492}
493
494th.tableblock.halign-left, td.tableblock.halign-left {
495 text-align: left;
496}
497th.tableblock.halign-center, td.tableblock.halign-center {
498 text-align: center;
499}
500th.tableblock.halign-right, td.tableblock.halign-right {
501 text-align: right;
502}
503
504th.tableblock.valign-top, td.tableblock.valign-top {
505 vertical-align: top;
506}
507th.tableblock.valign-middle, td.tableblock.valign-middle {
508 vertical-align: middle;
509}
510th.tableblock.valign-bottom, td.tableblock.valign-bottom {
511 vertical-align: bottom;
512}
513
514
515/*
516 * manpage specific
517 *
518 * */
519
520body.manpage h1 {
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]521 padding-top: 0.5em;
522 padding-bottom: 0.5em;
523 border-top: 2px solid silver;
524 border-bottom: 2px solid silver;
525}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]526body.manpage h2 {
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]527 border-style: none;
528}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]529body.manpage div.sectionbody {
530 margin-left: 3em;
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]531}
532
533@media print {
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]534 body.manpage div#toc { display: none; }
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]535}
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]536
537
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]538</style>
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]539<script type="text/javascript">
540/*<![CDATA[*/
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]541var asciidoc = { // Namespace.
542
543/////////////////////////////////////////////////////////////////////
544// Table Of Contents generator
545/////////////////////////////////////////////////////////////////////
546
547/* Author: Mihai Bazon, September 2002
548 * http://students.infoiasi.ro/~mishoo
549 *
550 * Table Of Content generator
551 * Version: 0.4
552 *
553 * Feel free to use this script under the terms of the GNU General Public
554 * License, as long as you do not remove or alter this notice.
555 */
556
557 /* modified by Troy D. Hanson, September 2006. License: GPL */
558 /* modified by Stuart Rackham, 2006, 2009. License: GPL */
559
560// toclevels = 1..4.
561toc: function (toclevels) {
562
563 function getText(el) {
564 var text = "";
565 for (var i = el.firstChild; i != null; i = i.nextSibling) {
566 if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
567 text += i.data;
568 else if (i.firstChild != null)
569 text += getText(i);
570 }
571 return text;
572 }
573
574 function TocEntry(el, text, toclevel) {
575 this.element = el;
576 this.text = text;
577 this.toclevel = toclevel;
578 }
579
580 function tocEntries(el, toclevels) {
581 var result = new Array;
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]582 var re = new RegExp('[hH]([1-'+(toclevels+1)+'])');
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]583 // Function that scans the DOM tree for header elements (the DOM2
584 // nodeIterator API would be a better technique but not supported by all
585 // browsers).
586 var iterate = function (el) {
587 for (var i = el.firstChild; i != null; i = i.nextSibling) {
588 if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
589 var mo = re.exec(i.tagName);
590 if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
591 result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
592 }
593 iterate(i);
594 }
595 }
596 }
597 iterate(el);
598 return result;
599 }
600
601 var toc = document.getElementById("toc");
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]602 if (!toc) {
603 return;
604 }
605
606 // Delete existing TOC entries in case we're reloading the TOC.
607 var tocEntriesToRemove = [];
608 var i;
609 for (i = 0; i < toc.childNodes.length; i++) {
610 var entry = toc.childNodes[i];
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]611 if (entry.nodeName.toLowerCase() == 'div'
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]612 && entry.getAttribute("class")
613 && entry.getAttribute("class").match(/^toclevel/))
614 tocEntriesToRemove.push(entry);
615 }
616 for (i = 0; i < tocEntriesToRemove.length; i++) {
617 toc.removeChild(tocEntriesToRemove[i]);
618 }
619
620 // Rebuild TOC entries.
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]621 var entries = tocEntries(document.getElementById("content"), toclevels);
622 for (var i = 0; i < entries.length; ++i) {
623 var entry = entries[i];
624 if (entry.element.id == "")
625 entry.element.id = "_toc_" + i;
626 var a = document.createElement("a");
627 a.href = "#" + entry.element.id;
628 a.appendChild(document.createTextNode(entry.text));
629 var div = document.createElement("div");
630 div.appendChild(a);
631 div.className = "toclevel" + entry.toclevel;
632 toc.appendChild(div);
633 }
634 if (entries.length == 0)
635 toc.parentNode.removeChild(toc);
636},
637
638
639/////////////////////////////////////////////////////////////////////
640// Footnotes generator
641/////////////////////////////////////////////////////////////////////
642
643/* Based on footnote generation code from:
644 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
645 */
646
647footnotes: function () {
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]648 // Delete existing footnote entries in case we're reloading the footnodes.
649 var i;
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]650 var noteholder = document.getElementById("footnotes");
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]651 if (!noteholder) {
652 return;
653 }
654 var entriesToRemove = [];
655 for (i = 0; i < noteholder.childNodes.length; i++) {
656 var entry = noteholder.childNodes[i];
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]657 if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]658 entriesToRemove.push(entry);
659 }
660 for (i = 0; i < entriesToRemove.length; i++) {
661 noteholder.removeChild(entriesToRemove[i]);
662 }
663
664 // Rebuild footnote entries.
665 var cont = document.getElementById("content");
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]666 var spans = cont.getElementsByTagName("span");
667 var refs = {};
668 var n = 0;
669 for (i=0; i<spans.length; i++) {
670 if (spans[i].className == "footnote") {
671 n++;
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]672 var note = spans[i].getAttribute("data-note");
673 if (!note) {
674 // Use [\s\S] in place of . so multi-line matches work.
675 // Because JavaScript has no s (dotall) regex flag.
676 note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
677 spans[i].innerHTML =
678 "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
679 "' title='View footnote' class='footnote'>" + n + "</a>]";
680 spans[i].setAttribute("data-note", note);
681 }
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]682 noteholder.innerHTML +=
683 "<div class='footnote' id='_footnote_" + n + "'>" +
684 "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
685 n + "</a>. " + note + "</div>";
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]686 var id =spans[i].getAttribute("id");
687 if (id != null) refs["#"+id] = n;
688 }
689 }
690 if (n == 0)
691 noteholder.parentNode.removeChild(noteholder);
692 else {
693 // Process footnoterefs.
694 for (i=0; i<spans.length; i++) {
695 if (spans[i].className == "footnoteref") {
696 var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
697 href = href.match(/#.*/)[0]; // Because IE return full URL.
698 n = refs[href];
699 spans[i].innerHTML =
700 "[<a href='#_footnote_" + n +
701 "' title='View footnote' class='footnote'>" + n + "</a>]";
702 }
703 }
704 }
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]705},
706
707install: function(toclevels) {
708 var timerId;
709
710 function reinstall() {
711 asciidoc.footnotes();
712 if (toclevels) {
713 asciidoc.toc(toclevels);
714 }
715 }
716
717 function reinstallAndRemoveTimer() {
718 clearInterval(timerId);
719 reinstall();
720 }
721
722 timerId = setInterval(reinstall, 500);
723 if (document.addEventListener)
724 document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
725 else
726 window.onload = reinstallAndRemoveTimer;
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]727}
728
729}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]730asciidoc.install();
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]731/*]]>*/
732</script>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]733</head>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]734<body class="manpage">
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]735<div id="header">
736<h1>
737gitattributes(5) Manual Page
738</h1>
739<h2>NAME</h2>
740<div class="sectionbody">
741<p>gitattributes -
742 defining attributes per path
743</p>
744</div>
745</div>
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]746<div id="content">
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]747<div class="sect1">
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]748<h2 id="_synopsis">SYNOPSIS</h2>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]749<div class="sectionbody">
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]750<div class="paragraph"><p>$GIT_DIR/info/attributes, .gitattributes</p></div>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]751</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]752</div>
753<div class="sect1">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]754<h2 id="_description">DESCRIPTION</h2>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]755<div class="sectionbody">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]756<div class="paragraph"><p>A <code>gitattributes</code> file is a simple text file that gives
757<code>attributes</code> to pathnames.</p></div>
758<div class="paragraph"><p>Each line in <code>gitattributes</code> file is of form:</p></div>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]759<div class="literalblock">
760<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]761<pre><code>pattern attr1 attr2 ...</code></pre>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]762</div></div>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]763<div class="paragraph"><p>That is, a pattern followed by an attributes list,
Junio C Hamanocbe0eb22017-02-27 23:37:49[diff] [blame]764separated by whitespaces. Leading and trailing whitespaces are
765ignored. Lines that begin with <em>#</em> are ignored. Patterns
766that begin with a double quote are quoted in C style.
767When the pattern matches the path in question, the attributes
768listed on the line are given to the path.</p></div>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]769<div class="paragraph"><p>Each attribute can be in one of these states for a given path:</p></div>
770<div class="dlist"><dl>
771<dt class="hdlist1">
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]772Set
773</dt>
774<dd>
775<p>
776 The path has the attribute with special value "true";
777 this is specified by listing only the name of the
778 attribute in the attribute list.
779</p>
780</dd>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]781<dt class="hdlist1">
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]782Unset
783</dt>
784<dd>
785<p>
786 The path has the attribute with special value "false";
787 this is specified by listing the name of the attribute
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]788 prefixed with a dash <code>-</code> in the attribute list.
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]789</p>
790</dd>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]791<dt class="hdlist1">
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]792Set to a value
793</dt>
794<dd>
795<p>
796 The path has the attribute with specified string value;
797 this is specified by listing the name of the attribute
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]798 followed by an equal sign <code>=</code> and its value in the
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]799 attribute list.
800</p>
801</dd>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]802<dt class="hdlist1">
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]803Unspecified
804</dt>
805<dd>
806<p>
Junio C Hamanod533bdb2009-02-25 09:56:58[diff] [blame]807 No pattern matches the path, and nothing says if
Junio C Hamano22572e72007-04-25 05:59:25[diff] [blame]808 the path has or does not have the attribute, the
809 attribute for the path is said to be Unspecified.
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]810</p>
811</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]812</dl></div>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]813<div class="paragraph"><p>When more than one pattern matches the path, a later line
Junio C Hamano22572e72007-04-25 05:59:25[diff] [blame]814overrides an earlier line. This overriding is done per
Junio C Hamanod533bdb2009-02-25 09:56:58[diff] [blame]815attribute. The rules how the pattern matches paths are the
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]816same as in <code>.gitignore</code> files; see <a href="gitignore.html">gitignore(5)</a>.
817Unlike <code>.gitignore</code>, negative patterns are forbidden.</p></div>
Junio C Hamano076ffcc2013-02-06 05:13:21[diff] [blame]818<div class="paragraph"><p>When deciding what attributes are assigned to a path, Git
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]819consults <code>$GIT_DIR/info/attributes</code> file (which has the highest
820precedence), <code>.gitattributes</code> file in the same directory as the
Junio C Hamanob4a9ede2009-04-08 07:36:32[diff] [blame]821path in question, and its parent directories up to the toplevel of the
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]822work tree (the further the directory that contains <code>.gitattributes</code>
Junio C Hamano3b4609d2010-09-30 00:04:34[diff] [blame]823is from the path in question, the lower its precedence). Finally
824global and system-wide files are considered (they have the lowest
825precedence).</p></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]826<div class="paragraph"><p>When the <code>.gitattributes</code> file is missing from the work tree, the
Junio C Hamano6631a092012-10-10 22:50:57[diff] [blame]827path in the index is used as a fall-back. During checkout process,
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]828<code>.gitattributes</code> in the index is used and then the file in the
Junio C Hamano6631a092012-10-10 22:50:57[diff] [blame]829working tree is used as a fall-back.</p></div>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]830<div class="paragraph"><p>If you wish to affect only a single repository (i.e., to assign
Junio C Hamano3b4609d2010-09-30 00:04:34[diff] [blame]831attributes to files that are particular to
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]832one user&#8217;s workflow for that repository), then
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]833attributes should be placed in the <code>$GIT_DIR/info/attributes</code> file.
Junio C Hamano99dc24a2008-03-27 23:49:50[diff] [blame]834Attributes which should be version-controlled and distributed to other
835repositories (i.e., attributes of interest to all users) should go into
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]836<code>.gitattributes</code> files. Attributes that should affect all repositories
Junio C Hamano3b4609d2010-09-30 00:04:34[diff] [blame]837for a single user should be placed in a file specified by the
Junio C Hamano322c6242015-03-23 21:32:46[diff] [blame]838<code>core.attributesFile</code> configuration option (see <a href="git-config.html">git-config(1)</a>).
Junio C Hamano8edb4c72012-07-09 20:33:55[diff] [blame]839Its default value is $XDG_CONFIG_HOME/git/attributes. If $XDG_CONFIG_HOME
840is either not set or empty, $HOME/.config/git/attributes is used instead.
Junio C Hamano3b4609d2010-09-30 00:04:34[diff] [blame]841Attributes for all users on a system should be placed in the
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]842<code>$(prefix)/etc/gitattributes</code> file.</p></div>
Junio C Hamanocbe0eb22017-02-27 23:37:49[diff] [blame]843<div class="paragraph"><p>Sometimes you would need to override a setting of an attribute
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]844for a path to <code>Unspecified</code> state. This can be done by listing
845the name of the attribute prefixed with an exclamation point <code>!</code>.</p></div>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]846</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]847</div>
848<div class="sect1">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]849<h2 id="_effects">EFFECTS</h2>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]850<div class="sectionbody">
Junio C Hamano076ffcc2013-02-06 05:13:21[diff] [blame]851<div class="paragraph"><p>Certain operations by Git can be influenced by assigning
Junio C Hamano2a8f6dc2007-07-09 08:48:38[diff] [blame]852particular attributes to a path. Currently, the following
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]853operations are attributes-aware.</p></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]854<div class="sect2">
855<h3 id="_checking_out_and_checking_in">Checking-out and checking-in</h3>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]856<div class="paragraph"><p>These attributes affect how the contents stored in the
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]857repository are copied to the working tree files when commands
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]858such as <em>git checkout</em> and <em>git merge</em> run. They also affect how
Junio C Hamano076ffcc2013-02-06 05:13:21[diff] [blame]859Git stores the contents you prepare in the working tree in the
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]860repository upon <em>git add</em> and <em>git commit</em>.</p></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]861<div class="sect3">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]862<h4 id="_code_text_code"><code>text</code></h4>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]863<div class="paragraph"><p>This attribute enables and controls end-of-line normalization. When a
Junio C Hamanobb88cf42010-06-21 15:23:55[diff] [blame]864text file is normalized, its line endings are converted to LF in the
865repository. To control what line ending style is used in the working
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]866directory, use the <code>eol</code> attribute for a single file and the
Junio C Hamanoeed15af2016-07-25 22:49:42[diff] [blame]867<code>core.eol</code> configuration variable for all text files.
868Note that <code>core.autocrlf</code> overrides <code>core.eol</code></p></div>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]869<div class="dlist"><dl>
870<dt class="hdlist1">
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]871Set
872</dt>
873<dd>
874<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]875 Setting the <code>text</code> attribute on a path enables end-of-line
Junio C Hamanobb88cf42010-06-21 15:23:55[diff] [blame]876 normalization and marks the path as a text file. End-of-line
877 conversion takes place without guessing the content type.
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]878</p>
879</dd>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]880<dt class="hdlist1">
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]881Unset
882</dt>
883<dd>
884<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]885 Unsetting the <code>text</code> attribute on a path tells Git not to
Junio C Hamanofcb740a2008-08-31 06:32:05[diff] [blame]886 attempt any end-of-line conversion upon checkin or checkout.
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]887</p>
888</dd>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]889<dt class="hdlist1">
Junio C Hamanobb88cf42010-06-21 15:23:55[diff] [blame]890Set to string value "auto"
891</dt>
892<dd>
893<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]894 When <code>text</code> is set to "auto", the path is marked for automatic
Junio C Hamanoeed15af2016-07-25 22:49:42[diff] [blame]895 end-of-line conversion. If Git decides that the content is
896 text, its line endings are converted to LF on checkin.
Junio C Hamano0f1d17c2016-08-12 19:42:26[diff] [blame]897 When the file has been committed with CRLF, no conversion is done.
Junio C Hamanobb88cf42010-06-21 15:23:55[diff] [blame]898</p>
899</dd>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]900<dt class="hdlist1">
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]901Unspecified
902</dt>
903<dd>
904<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]905 If the <code>text</code> attribute is unspecified, Git uses the
906 <code>core.autocrlf</code> configuration variable to determine if the
Junio C Hamanobb88cf42010-06-21 15:23:55[diff] [blame]907 file should be converted.
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]908</p>
909</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]910</dl></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]911<div class="paragraph"><p>Any other value causes Git to act as if <code>text</code> has been left
Junio C Hamanobb88cf42010-06-21 15:23:55[diff] [blame]912unspecified.</p></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]913</div>
914<div class="sect3">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]915<h4 id="_code_eol_code"><code>eol</code></h4>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]916<div class="paragraph"><p>This attribute sets a specific line-ending style to be used in the
Junio C Hamanoeed15af2016-07-25 22:49:42[diff] [blame]917working directory. It enables end-of-line conversion without any
Junio C Hamano8d57fa92017-09-19 05:01:08[diff] [blame]918content checks, effectively setting the <code>text</code> attribute. Note that
919setting this attribute on paths which are in the index with CRLF line
920endings may make the paths to be considered dirty. Adding the path to
921the index again will normalize the line endings in the index.</p></div>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]922<div class="dlist"><dl>
923<dt class="hdlist1">
Junio C Hamanobb88cf42010-06-21 15:23:55[diff] [blame]924Set to string value "crlf"
925</dt>
926<dd>
927<p>
Junio C Hamano076ffcc2013-02-06 05:13:21[diff] [blame]928 This setting forces Git to normalize line endings for this
Junio C Hamanobb88cf42010-06-21 15:23:55[diff] [blame]929 file on checkin and convert them to CRLF when the file is
930 checked out.
931</p>
932</dd>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]933<dt class="hdlist1">
Junio C Hamanobb88cf42010-06-21 15:23:55[diff] [blame]934Set to string value "lf"
935</dt>
936<dd>
937<p>
Junio C Hamano076ffcc2013-02-06 05:13:21[diff] [blame]938 This setting forces Git to normalize line endings to LF on
Junio C Hamanobb88cf42010-06-21 15:23:55[diff] [blame]939 checkin and prevents conversion to CRLF when the file is
940 checked out.
941</p>
942</dd>
943</dl></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]944</div>
945<div class="sect3">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]946<h4 id="_backwards_compatibility_with_code_crlf_code_attribute">Backwards compatibility with <code>crlf</code> attribute</h4>
947<div class="paragraph"><p>For backwards compatibility, the <code>crlf</code> attribute is interpreted as
Junio C Hamanobb88cf42010-06-21 15:23:55[diff] [blame]948follows:</p></div>
949<div class="listingblock">
950<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]951<pre><code>crlf text
Junio C Hamanobb88cf42010-06-21 15:23:55[diff] [blame]952-crlf -text
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]953crlf=input eol=lf</code></pre>
Junio C Hamanobb88cf42010-06-21 15:23:55[diff] [blame]954</div></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]955</div>
956<div class="sect3">
Junio C Hamanobb88cf42010-06-21 15:23:55[diff] [blame]957<h4 id="_end_of_line_conversion">End-of-line conversion</h4>
Junio C Hamano076ffcc2013-02-06 05:13:21[diff] [blame]958<div class="paragraph"><p>While Git normally leaves file contents alone, it can be configured to
Junio C Hamanobb88cf42010-06-21 15:23:55[diff] [blame]959normalize line endings to LF in the repository and, optionally, to
960convert them to CRLF when files are checked out.</p></div>
Junio C Hamanoe7808d72016-08-26 21:48:01[diff] [blame]961<div class="paragraph"><p>If you simply want to have CRLF line endings in your working directory
962regardless of the repository you are working with, you can set the
963config variable "core.autocrlf" without using any attributes.</p></div>
964<div class="listingblock">
965<div class="content">
966<pre><code>[core]
967 autocrlf = true</code></pre>
968</div></div>
969<div class="paragraph"><p>This does not force normalization of text files, but does ensure
970that text files that you introduce to the repository have their line
971endings normalized to LF when they are added, and that files that are
972already normalized in the repository stay normalized.</p></div>
973<div class="paragraph"><p>If you want to ensure that text files that any contributor introduces to
974the repository have their line endings normalized, you can set the
975<code>text</code> attribute to "auto" for <em>all</em> files.</p></div>
976<div class="listingblock">
977<div class="content">
978<pre><code>* text=auto</code></pre>
979</div></div>
980<div class="paragraph"><p>The attributes allow a fine-grained control, how the line endings
981are converted.
982Here is an example that will make Git normalize .txt, .vcproj and .sh
Junio C Hamanobb88cf42010-06-21 15:23:55[diff] [blame]983files, ensure that .vcproj files have CRLF and .sh files have LF in
984the working directory, and prevent .jpg files from being normalized
985regardless of their content.</p></div>
986<div class="listingblock">
987<div class="content">
Junio C Hamanoeed15af2016-07-25 22:49:42[diff] [blame]988<pre><code>* text=auto
989*.txt text
990*.vcproj text eol=crlf
991*.sh text eol=lf
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]992*.jpg -text</code></pre>
Junio C Hamanobb88cf42010-06-21 15:23:55[diff] [blame]993</div></div>
Junio C Hamanobb88cf42010-06-21 15:23:55[diff] [blame]994<div class="admonitionblock">
995<table><tr>
996<td class="icon">
997<div class="title">Note</div>
998</td>
Junio C Hamanoe7808d72016-08-26 21:48:01[diff] [blame]999<td class="content">When <code>text=auto</code> conversion is enabled in a cross-platform
1000project using push and pull to a central repository the text files
1001containing CRLFs should be normalized.</td>
Junio C Hamanobb88cf42010-06-21 15:23:55[diff] [blame]1002</tr></table>
1003</div>
Junio C Hamanoe7808d72016-08-26 21:48:01[diff] [blame]1004<div class="paragraph"><p>From a clean working directory:</p></div>
Junio C Hamanobb88cf42010-06-21 15:23:55[diff] [blame]1005<div class="listingblock">
1006<div class="content">
Junio C Hamanoe7808d72016-08-26 21:48:01[diff] [blame]1007<pre><code>$ echo "* text=auto" &gt;.gitattributes
Junio C Hamano4886c772017-11-27 03:33:28[diff] [blame]1008$ git add --renormalize .
Junio C Hamanobb88cf42010-06-21 15:23:55[diff] [blame]1009$ git status # Show files that will be normalized
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1010$ git commit -m "Introduce end-of-line normalization"</code></pre>
Junio C Hamanobb88cf42010-06-21 15:23:55[diff] [blame]1011</div></div>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1012<div class="paragraph"><p>If any files that should not be normalized show up in <em>git status</em>,
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1013unset their <code>text</code> attribute before running <em>git add -u</em>.</p></div>
Junio C Hamanobb88cf42010-06-21 15:23:55[diff] [blame]1014<div class="listingblock">
1015<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1016<pre><code>manual.pdf -text</code></pre>
Junio C Hamanobb88cf42010-06-21 15:23:55[diff] [blame]1017</div></div>
Junio C Hamano076ffcc2013-02-06 05:13:21[diff] [blame]1018<div class="paragraph"><p>Conversely, text files that Git does not detect can have normalization
Junio C Hamanobb88cf42010-06-21 15:23:55[diff] [blame]1019enabled manually.</p></div>
1020<div class="listingblock">
1021<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1022<pre><code>weirdchars.txt text</code></pre>
Junio C Hamanobb88cf42010-06-21 15:23:55[diff] [blame]1023</div></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1024<div class="paragraph"><p>If <code>core.safecrlf</code> is set to "true" or "warn", Git verifies if
Junio C Hamano26e590a2008-02-17 03:53:51[diff] [blame]1025the conversion is reversible for the current setting of
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1026<code>core.autocrlf</code>. For "true", Git rejects irreversible
Junio C Hamano076ffcc2013-02-06 05:13:21[diff] [blame]1027conversions; for "warn", Git only prints a warning but accepts
Junio C Hamano26e590a2008-02-17 03:53:51[diff] [blame]1028an irreversible conversion. The safety triggers to prevent such
1029a conversion done to the files in the work tree, but there are a
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1030few exceptions. Even though&#8230;</p></div>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1031<div class="ulist"><ul>
Junio C Hamano26e590a2008-02-17 03:53:51[diff] [blame]1032<li>
1033<p>
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]1034<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]1035 next checkout would, so the safety triggers;
1036</p>
1037</li>
1038<li>
1039<p>
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]1040<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]1041 in the work tree, but the operation is about text files and CRLF
1042 conversion is about fixing the line ending inconsistencies, so the
1043 safety does not trigger;
1044</p>
1045</li>
1046<li>
1047<p>
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]1048<em>git diff</em> itself does not touch the files in the work tree, it is
1049 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]1050 catch potential problems early, safety triggers.
1051</p>
1052</li>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1053</ul></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1054</div>
1055<div class="sect3">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1056<h4 id="_code_ident_code"><code>ident</code></h4>
1057<div class="paragraph"><p>When the attribute <code>ident</code> is set for a path, Git replaces
1058<code>$Id$</code> in the blob object with <code>$Id:</code>, followed by the
Junio C Hamano469d60e2007-04-29 18:30:34[diff] [blame]105940-character hexadecimal blob object name, followed by a dollar
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1060sign <code>$</code> upon checkout. Any byte sequence that begins with
1061<code>$Id:</code> and ends with <code>$</code> in the worktree file is replaced
1062with <code>$Id$</code> upon check-in.</p></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1063</div>
1064<div class="sect3">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1065<h4 id="_code_filter_code"><code>filter</code></h4>
1066<div class="paragraph"><p>A <code>filter</code> attribute can be set to a string value that names a
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1067filter driver specified in the configuration.</p></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1068<div class="paragraph"><p>A filter driver consists of a <code>clean</code> command and a <code>smudge</code>
Junio C Hamano469d60e2007-04-29 18:30:34[diff] [blame]1069command, either of which can be left unspecified. Upon
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1070checkout, when the <code>smudge</code> command is specified, the command is
Junio C Hamano361c1332007-11-14 12:17:22[diff] [blame]1071fed the blob object from its standard input, and its standard
1072output is used to update the worktree file. Similarly, the
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1073<code>clean</code> command is used to convert the contents of worktree file
Junio C Hamanof2f28b12016-10-31 21:41:58[diff] [blame]1074upon checkin. By default these commands process only a single
1075blob and terminate. If a long running <code>process</code> filter is used
1076in place of <code>clean</code> and/or <code>smudge</code> filters, then Git can process
1077all blobs with a single filter command invocation for the entire
1078life of a single Git command, for example <code>git add --all</code>. If a
1079long running <code>process</code> filter is configured then it always takes
1080precedence over a configured single blob filter. See section
1081below for the description of the protocol used to communicate with
1082a <code>process</code> filter.</p></div>
Junio C Hamano90a5b7b2012-02-28 23:40:31[diff] [blame]1083<div class="paragraph"><p>One use of the content filtering is to massage the content into a shape
1084that is more convenient for the platform, filesystem, and the user to use.
1085For this mode of operation, the key phrase here is "more convenient" and
1086not "turning something unusable into usable". In other words, the intent
1087is that if someone unsets the filter driver definition, or does not have
1088the appropriate filter program, the project should still be usable.</p></div>
1089<div class="paragraph"><p>Another use of the content filtering is to store the content that cannot
1090be directly used in the repository (e.g. a UUID that refers to the true
Junio C Hamano076ffcc2013-02-06 05:13:21[diff] [blame]1091content stored outside Git, or an encrypted content) and turn it into a
Junio C Hamano90a5b7b2012-02-28 23:40:31[diff] [blame]1092usable form upon checkout (e.g. download the external content, or decrypt
1093the encrypted content).</p></div>
1094<div class="paragraph"><p>These two filters behave differently, and by default, a filter is taken as
1095the former, massaging the contents into more convenient shape. A missing
1096filter driver definition in the config, or a filter driver that exits with
1097a non-zero status, is not an error but makes the filter a no-op passthru.</p></div>
1098<div class="paragraph"><p>You can declare that a filter turns a content that by itself is unusable
1099into a usable content by setting the filter.&lt;driver&gt;.required configuration
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1100variable to <code>true</code>.</p></div>
Junio C Hamano4886c772017-11-27 03:33:28[diff] [blame]1101<div class="paragraph"><p>Note: Whenever the clean filter is changed, the repo should be renormalized:
1102$ git add --renormalize .</p></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1103<div class="paragraph"><p>For example, in .gitattributes, you would assign the <code>filter</code>
Junio C Hamano6a548ef2009-12-17 00:16:20[diff] [blame]1104attribute for paths.</p></div>
1105<div class="listingblock">
1106<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1107<pre><code>*.c filter=indent</code></pre>
Junio C Hamano6a548ef2009-12-17 00:16:20[diff] [blame]1108</div></div>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1109<div class="paragraph"><p>Then you would define a "filter.indent.clean" and "filter.indent.smudge"
Junio C Hamano6a548ef2009-12-17 00:16:20[diff] [blame]1110configuration in your .git/config to specify a pair of commands to
1111modify the contents of C programs when the source files are checked
1112in ("clean" is run) and checked out (no change is made because the
1113command is "cat").</p></div>
1114<div class="listingblock">
1115<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1116<pre><code>[filter "indent"]
Junio C Hamano6a548ef2009-12-17 00:16:20[diff] [blame]1117 clean = indent
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1118 smudge = cat</code></pre>
Junio C Hamano6a548ef2009-12-17 00:16:20[diff] [blame]1119</div></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1120<div class="paragraph"><p>For best results, <code>clean</code> should not alter its output further if it is
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1121run twice ("clean&#8594;clean" should be equivalent to "clean"), and
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1122multiple <code>smudge</code> commands should not alter <code>clean</code>'s output
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1123("smudge&#8594;smudge&#8594;clean" should be equivalent to "clean"). See the
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]1124section on merging below.</p></div>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1125<div class="paragraph"><p>The "indent" filter is well-behaved in this regard: it will not modify
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]1126input that is already correctly indented. In this case, the lack of a
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1127smudge filter means that the clean filter <em>must</em> accept its own output
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]1128without modifying it.</p></div>
Junio C Hamano90a5b7b2012-02-28 23:40:31[diff] [blame]1129<div class="paragraph"><p>If a filter <em>must</em> succeed in order to make the stored contents usable,
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1130you can declare that the filter is <code>required</code>, in the configuration:</p></div>
Junio C Hamano90a5b7b2012-02-28 23:40:31[diff] [blame]1131<div class="listingblock">
1132<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1133<pre><code>[filter "crypt"]
Junio C Hamano90a5b7b2012-02-28 23:40:31[diff] [blame]1134 clean = openssl enc ...
1135 smudge = openssl enc -d ...
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1136 required</code></pre>
Junio C Hamano90a5b7b2012-02-28 23:40:31[diff] [blame]1137</div></div>
Junio C Hamanoe0552e42011-01-06 00:34:47[diff] [blame]1138<div class="paragraph"><p>Sequence "%f" on the filter command line is replaced with the name of
1139the file the filter is working on. A filter might use this in keyword
1140substitution. For example:</p></div>
1141<div class="listingblock">
1142<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1143<pre><code>[filter "p4"]
Junio C Hamanoe0552e42011-01-06 00:34:47[diff] [blame]1144 clean = git-p4-filter --clean %f
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1145 smudge = git-p4-filter --smudge %f</code></pre>
Junio C Hamanoe0552e42011-01-06 00:34:47[diff] [blame]1146</div></div>
Junio C Hamanoe548d1b2016-08-08 22:26:49[diff] [blame]1147<div class="paragraph"><p>Note that "%f" is the name of the path that is being worked on. Depending
1148on the version that is being filtered, the corresponding file on disk may
1149not exist, or may have different contents. So, smudge and clean commands
1150should not try to access the file on disk, but only act as filters on the
1151content provided to them on standard input.</p></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1152</div>
1153<div class="sect3">
Junio C Hamanof2f28b12016-10-31 21:41:58[diff] [blame]1154<h4 id="_long_running_filter_process">Long Running Filter Process</h4>
1155<div class="paragraph"><p>If the filter command (a string value) is defined via
1156<code>filter.&lt;driver&gt;.process</code> then Git can process all blobs with a
1157single filter invocation for the entire life of a single Git
Junio C Hamano640779d2018-02-14 01:29:14[diff] [blame]1158command. This is achieved by using the long-running process protocol
1159(described in technical/long-running-process-protocol.txt).</p></div>
1160<div class="paragraph"><p>When Git encounters the first file that needs to be cleaned or smudged,
1161it starts the filter and performs the handshake. In the handshake, the
1162welcome message sent by Git is "git-filter-client", only version 2 is
1163suppported, and the supported capabilities are "clean", "smudge", and
1164"delay".</p></div>
Junio C Hamanof2f28b12016-10-31 21:41:58[diff] [blame]1165<div class="paragraph"><p>Afterwards Git sends a list of "key=value" pairs terminated with
1166a flush packet. The list will contain at least the filter command
1167(based on the supported capabilities) and the pathname of the file
1168to filter relative to the repository root. Right after the flush packet
1169Git sends the content split in zero or more pkt-line packets and a
1170flush packet to terminate content. Please note, that the filter
1171must not send any response before it received the content and the
Junio C Hamano9e35abf2016-12-27 22:37:27[diff] [blame]1172final flush packet. Also note that the "value" of a "key=value" pair
1173can contain the "=" character whereas the key would never contain
1174that character.</p></div>
Junio C Hamanof2f28b12016-10-31 21:41:58[diff] [blame]1175<div class="listingblock">
1176<div class="content">
1177<pre><code>packet: git&gt; command=smudge
1178packet: git&gt; pathname=path/testfile.dat
1179packet: git&gt; 0000
1180packet: git&gt; CONTENT
1181packet: git&gt; 0000</code></pre>
1182</div></div>
1183<div class="paragraph"><p>The filter is expected to respond with a list of "key=value" pairs
1184terminated with a flush packet. If the filter does not experience
1185problems then the list must contain a "success" status. Right after
1186these packets the filter is expected to send the content in zero
1187or more pkt-line packets and a flush packet at the end. Finally, a
1188second list of "key=value" pairs terminated with a flush packet
1189is expected. The filter can change the status in the second list
1190or keep the status as is with an empty list. Please note that the
1191empty list must be terminated with a flush packet regardless.</p></div>
1192<div class="listingblock">
1193<div class="content">
1194<pre><code>packet: git&lt; status=success
1195packet: git&lt; 0000
1196packet: git&lt; SMUDGED_CONTENT
1197packet: git&lt; 0000
1198packet: git&lt; 0000 # empty list, keep "status=success" unchanged!</code></pre>
1199</div></div>
1200<div class="paragraph"><p>If the result content is empty then the filter is expected to respond
1201with a "success" status and a flush packet to signal the empty content.</p></div>
1202<div class="listingblock">
1203<div class="content">
1204<pre><code>packet: git&lt; status=success
1205packet: git&lt; 0000
1206packet: git&lt; 0000 # empty content!
1207packet: git&lt; 0000 # empty list, keep "status=success" unchanged!</code></pre>
1208</div></div>
1209<div class="paragraph"><p>In case the filter cannot or does not want to process the content,
1210it is expected to respond with an "error" status.</p></div>
1211<div class="listingblock">
1212<div class="content">
1213<pre><code>packet: git&lt; status=error
1214packet: git&lt; 0000</code></pre>
1215</div></div>
1216<div class="paragraph"><p>If the filter experiences an error during processing, then it can
1217send the status "error" after the content was (partially or
1218completely) sent.</p></div>
1219<div class="listingblock">
1220<div class="content">
1221<pre><code>packet: git&lt; status=success
1222packet: git&lt; 0000
1223packet: git&lt; HALF_WRITTEN_ERRONEOUS_CONTENT
1224packet: git&lt; 0000
1225packet: git&lt; status=error
1226packet: git&lt; 0000</code></pre>
1227</div></div>
1228<div class="paragraph"><p>In case the filter cannot or does not want to process the content
1229as well as any future content for the lifetime of the Git process,
1230then it is expected to respond with an "abort" status at any point
1231in the protocol.</p></div>
1232<div class="listingblock">
1233<div class="content">
1234<pre><code>packet: git&lt; status=abort
1235packet: git&lt; 0000</code></pre>
1236</div></div>
1237<div class="paragraph"><p>Git neither stops nor restarts the filter process in case the
1238"error"/"abort" status is set. However, Git sets its exit code
1239according to the <code>filter.&lt;driver&gt;.required</code> flag, mimicking the
1240behavior of the <code>filter.&lt;driver&gt;.clean</code> / <code>filter.&lt;driver&gt;.smudge</code>
1241mechanism.</p></div>
1242<div class="paragraph"><p>If the filter dies during the communication or does not adhere to
1243the protocol then Git will stop the filter process and restart it
1244with the next file that needs to be processed. Depending on the
1245<code>filter.&lt;driver&gt;.required</code> flag Git will interpret that as error.</p></div>
Junio C Hamano4b2a6c12017-08-22 18:32:37[diff] [blame]1246</div>
1247<div class="sect3">
1248<h4 id="_delay">Delay</h4>
1249<div class="paragraph"><p>If the filter supports the "delay" capability, then Git can send the
1250flag "can-delay" after the filter command and pathname. This flag
1251denotes that the filter can delay filtering the current blob (e.g. to
1252compensate network latencies) by responding with no content but with
1253the status "delayed" and a flush packet.</p></div>
1254<div class="listingblock">
1255<div class="content">
1256<pre><code>packet: git&gt; command=smudge
1257packet: git&gt; pathname=path/testfile.dat
1258packet: git&gt; can-delay=1
1259packet: git&gt; 0000
1260packet: git&gt; CONTENT
1261packet: git&gt; 0000
1262packet: git&lt; status=delayed
1263packet: git&lt; 0000</code></pre>
1264</div></div>
1265<div class="paragraph"><p>If the filter supports the "delay" capability then it must support the
1266"list_available_blobs" command. If Git sends this command, then the
1267filter is expected to return a list of pathnames representing blobs
1268that have been delayed earlier and are now available.
1269The list must be terminated with a flush packet followed
1270by a "success" status that is also terminated with a flush packet. If
1271no blobs for the delayed paths are available, yet, then the filter is
1272expected to block the response until at least one blob becomes
1273available. The filter can tell Git that it has no more delayed blobs
1274by sending an empty list. As soon as the filter responds with an empty
1275list, Git stops asking. All blobs that Git has not received at this
1276point are considered missing and will result in an error.</p></div>
1277<div class="listingblock">
1278<div class="content">
1279<pre><code>packet: git&gt; command=list_available_blobs
1280packet: git&gt; 0000
1281packet: git&lt; pathname=path/testfile.dat
1282packet: git&lt; pathname=path/otherfile.dat
1283packet: git&lt; 0000
1284packet: git&lt; status=success
1285packet: git&lt; 0000</code></pre>
1286</div></div>
1287<div class="paragraph"><p>After Git received the pathnames, it will request the corresponding
1288blobs again. These requests contain a pathname and an empty content
1289section. The filter is expected to respond with the smudged content
1290in the usual way as explained above.</p></div>
1291<div class="listingblock">
1292<div class="content">
1293<pre><code>packet: git&gt; command=smudge
1294packet: git&gt; pathname=path/testfile.dat
1295packet: git&gt; 0000
1296packet: git&gt; 0000 # empty content!
1297packet: git&lt; status=success
1298packet: git&lt; 0000
1299packet: git&lt; SMUDGED_CONTENT
1300packet: git&lt; 0000
1301packet: git&lt; 0000 # empty list, keep "status=success" unchanged!</code></pre>
1302</div></div>
1303</div>
1304<div class="sect3">
1305<h4 id="_example">Example</h4>
Junio C Hamanof2f28b12016-10-31 21:41:58[diff] [blame]1306<div class="paragraph"><p>A long running filter demo implementation can be found in
1307<code>contrib/long-running-filter/example.pl</code> located in the Git
1308core repository. If you develop your own long running filter
1309process then the <code>GIT_TRACE_PACKET</code> environment variables can be
1310very helpful for debugging (see <a href="git.html">git(1)</a>).</p></div>
1311<div class="paragraph"><p>Please note that you cannot use an existing <code>filter.&lt;driver&gt;.clean</code>
1312or <code>filter.&lt;driver&gt;.smudge</code> command with <code>filter.&lt;driver&gt;.process</code>
1313because the former two use a different inter process communication
1314protocol than the latter one.</p></div>
1315</div>
1316<div class="sect3">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1317<h4 id="_interaction_between_checkin_checkout_attributes">Interaction between checkin/checkout attributes</h4>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1318<div class="paragraph"><p>In the check-in codepath, the worktree file is first converted
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1319with <code>filter</code> driver (if specified and corresponding driver
1320defined), then the result is processed with <code>ident</code> (if
1321specified), and then finally with <code>text</code> (again, if specified
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1322and applicable).</p></div>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1323<div class="paragraph"><p>In the check-out codepath, the blob content is first converted
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1324with <code>text</code>, and then <code>ident</code> and fed to <code>filter</code>.</p></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1325</div>
1326<div class="sect3">
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]1327<h4 id="_merging_branches_with_differing_checkin_checkout_attributes">Merging branches with differing checkin/checkout attributes</h4>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1328<div class="paragraph"><p>If you have added attributes to a file that cause the canonical
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]1329repository format for that file to change, such as adding a
1330clean/smudge filter or text/eol/ident attributes, merging anything
1331where the attribute is not in place would normally cause merge
1332conflicts.</p></div>
Junio C Hamano076ffcc2013-02-06 05:13:21[diff] [blame]1333<div class="paragraph"><p>To prevent these unnecessary merge conflicts, Git can be told to run a
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]1334virtual check-out and check-in of all three stages of a file when
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1335resolving a three-way merge by setting the <code>merge.renormalize</code>
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]1336configuration variable. This prevents changes caused by check-in
1337conversion from causing spurious merge conflicts when a converted file
1338is merged with an unconverted file.</p></div>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1339<div class="paragraph"><p>As long as a "smudge&#8594;clean" results in the same output as a "clean"
Junio C Hamano2db3e752010-09-03 21:33:06[diff] [blame]1340even on files that are already smudged, this strategy will
1341automatically resolve all filter-related conflicts. Filters that do
1342not act in this way may cause additional merge conflicts that must be
1343resolved manually.</p></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1344</div>
1345</div>
1346<div class="sect2">
1347<h3 id="_generating_diff_text">Generating diff text</h3>
1348<div class="sect3">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1349<h4 id="_code_diff_code"><code>diff</code></h4>
1350<div class="paragraph"><p>The attribute <code>diff</code> affects how Git generates diffs for particular
Junio C Hamano076ffcc2013-02-06 05:13:21[diff] [blame]1351files. It can tell Git whether to generate a textual patch for the path
Junio C Hamano28363492008-11-14 08:26:31[diff] [blame]1352or to treat the path as a binary file. It can also affect what line is
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1353shown on the hunk header <code>@@ -k,l +n,m @@</code> line, tell Git to use an
Junio C Hamano076ffcc2013-02-06 05:13:21[diff] [blame]1354external command to generate the diff, or ask Git to convert binary
Junio C Hamano28363492008-11-14 08:26:31[diff] [blame]1355files to a text format before generating the diff.</p></div>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1356<div class="dlist"><dl>
1357<dt class="hdlist1">
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]1358Set
1359</dt>
1360<dd>
1361<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1362 A path to which the <code>diff</code> attribute is set is treated
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]1363 as text, even when they contain byte values that
1364 normally never appear in text files, such as NUL.
1365</p>
1366</dd>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1367<dt class="hdlist1">
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]1368Unset
1369</dt>
1370<dd>
1371<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1372 A path to which the <code>diff</code> attribute is unset will
1373 generate <code>Binary files differ</code> (or a binary patch, if
Junio C Hamano28363492008-11-14 08:26:31[diff] [blame]1374 binary patches are enabled).
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]1375</p>
1376</dd>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1377<dt class="hdlist1">
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]1378Unspecified
1379</dt>
1380<dd>
1381<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1382 A path to which the <code>diff</code> attribute is unspecified
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]1383 first gets its contents inspected, and if it looks like
Junio C Hamano8e61f1f2014-09-11 21:53:45[diff] [blame]1384 text and is smaller than core.bigFileThreshold, it is treated
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1385 as text. Otherwise it would generate <code>Binary files differ</code>.
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]1386</p>
1387</dd>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1388<dt class="hdlist1">
Junio C Hamano9db95ca2007-04-23 07:27:05[diff] [blame]1389String
1390</dt>
1391<dd>
1392<p>
Junio C Hamano28363492008-11-14 08:26:31[diff] [blame]1393 Diff is shown using the specified diff driver. Each driver may
1394 specify one or more options, as described in the following
1395 section. The options for the diff driver "foo" are defined
1396 by the configuration variables in the "diff.foo" section of the
Junio C Hamano076ffcc2013-02-06 05:13:21[diff] [blame]1397 Git config file.
Junio C Hamano9db95ca2007-04-23 07:27:05[diff] [blame]1398</p>
1399</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1400</dl></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1401</div>
1402<div class="sect3">
Junio C Hamano28363492008-11-14 08:26:31[diff] [blame]1403<h4 id="_defining_an_external_diff_driver">Defining an external diff driver</h4>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1404<div class="paragraph"><p>The definition of a diff driver is done in <code>gitconfig</code>, not
1405<code>gitattributes</code> file, so strictly speaking this manual page is a
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1406wrong place to talk about it. However&#8230;</p></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1407<div class="paragraph"><p>To define an external diff driver <code>jcdiff</code>, add a section to your
1408<code>$GIT_DIR/config</code> file (or <code>$HOME/.gitconfig</code> file) like this:</p></div>
Junio C Hamano9db95ca2007-04-23 07:27:05[diff] [blame]1409<div class="listingblock">
1410<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1411<pre><code>[diff "jcdiff"]
1412 command = j-c-diff</code></pre>
Junio C Hamano9db95ca2007-04-23 07:27:05[diff] [blame]1413</div></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1414<div class="paragraph"><p>When Git needs to show you a diff for the path with <code>diff</code>
1415attribute set to <code>jcdiff</code>, it calls the command you specified
1416with the above configuration, i.e. <code>j-c-diff</code>, with 7
1417parameters, just like <code>GIT_EXTERNAL_DIFF</code> program is called.
Junio C Hamanoa28a9202012-06-21 07:08:23[diff] [blame]1418See <a href="git.html">git(1)</a> for details.</p></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1419</div>
1420<div class="sect3">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1421<h4 id="_defining_a_custom_hunk_header">Defining a custom hunk-header</h4>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1422<div class="paragraph"><p>Each group of changes (called a "hunk") in the textual diff output
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1423is prefixed with a line of the form:</p></div>
Junio C Hamano2a8f6dc2007-07-09 08:48:38[diff] [blame]1424<div class="literalblock">
1425<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1426<pre><code>@@ -k,l +n,m @@ TEXT</code></pre>
Junio C Hamano2a8f6dc2007-07-09 08:48:38[diff] [blame]1427</div></div>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1428<div class="paragraph"><p>This is called a <em>hunk header</em>. The "TEXT" portion is by default a line
Junio C Hamano5e4d8de2008-09-19 06:27:02[diff] [blame]1429that begins with an alphabet, an underscore or a dollar sign; this
1430matches what GNU <em>diff -p</em> output uses. This default selection however
1431is not suited for some contents, and you can use a customized pattern
1432to make a selection.</p></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1433<div class="paragraph"><p>First, in .gitattributes, you would assign the <code>diff</code> attribute
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1434for paths.</p></div>
Junio C Hamano2a8f6dc2007-07-09 08:48:38[diff] [blame]1435<div class="listingblock">
1436<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1437<pre><code>*.tex diff=tex</code></pre>
Junio C Hamano2a8f6dc2007-07-09 08:48:38[diff] [blame]1438</div></div>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1439<div class="paragraph"><p>Then, you would define a "diff.tex.xfuncname" configuration to
Junio C Hamano2a8f6dc2007-07-09 08:48:38[diff] [blame]1440specify a regular expression that matches a line that you would
Junio C Hamano3bd66e92009-04-18 06:17:56[diff] [blame]1441want to appear as the hunk header "TEXT". Add a section to your
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1442<code>$GIT_DIR/config</code> file (or <code>$HOME/.gitconfig</code> file) like this:</p></div>
Junio C Hamano2a8f6dc2007-07-09 08:48:38[diff] [blame]1443<div class="listingblock">
1444<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1445<pre><code>[diff "tex"]
1446 xfuncname = "^(\\\\(sub)*section\\{.*)$"</code></pre>
Junio C Hamano2a8f6dc2007-07-09 08:48:38[diff] [blame]1447</div></div>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1448<div class="paragraph"><p>Note. A single level of backslashes are eaten by the
Junio C Hamano2a8f6dc2007-07-09 08:48:38[diff] [blame]1449configuration file parser, so you would need to double the
1450backslashes; the pattern above picks a line that begins with a
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1451backslash, and zero or more occurrences of <code>sub</code> followed by
1452<code>section</code> followed by open brace, to the end of line.</p></div>
1453<div class="paragraph"><p>There are a few built-in patterns to make this easier, and <code>tex</code>
Junio C Hamano2a8f6dc2007-07-09 08:48:38[diff] [blame]1454is one of them, so you do not have to write the above in your
1455configuration file (you still need to enable this with the
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1456attribute mechanism, via <code>.gitattributes</code>). The following built in
Junio C Hamanoa76cb0d2008-08-13 20:04:10[diff] [blame]1457patterns are available:</p></div>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1458<div class="ulist"><ul>
Junio C Hamanoa76cb0d2008-08-13 20:04:10[diff] [blame]1459<li>
1460<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1461<code>ada</code> suitable for source code in the Ada language.
Junio C Hamano4f07aec2012-09-25 19:08:44[diff] [blame]1462</p>
1463</li>
1464<li>
1465<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1466<code>bibtex</code> suitable for files with BibTeX coded references.
Junio C Hamanoa76cb0d2008-08-13 20:04:10[diff] [blame]1467</p>
1468</li>
1469<li>
1470<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1471<code>cpp</code> suitable for source code in the C and C++ languages.
Junio C Hamano20d47e32009-01-26 06:36:02[diff] [blame]1472</p>
1473</li>
1474<li>
1475<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1476<code>csharp</code> suitable for source code in the C# language.
Junio C Hamano53ba6d02010-08-22 07:25:12[diff] [blame]1477</p>
1478</li>
1479<li>
1480<p>
Junio C Hamanofedb1b42016-06-20 21:23:40[diff] [blame]1481<code>css</code> suitable for cascading style sheets.
1482</p>
1483</li>
1484<li>
1485<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1486<code>fortran</code> suitable for source code in the Fortran language.
Junio C Hamano3b4609d2010-09-30 00:04:34[diff] [blame]1487</p>
1488</li>
1489<li>
1490<p>
Junio C Hamanod7ed4042015-08-03 19:43:00[diff] [blame]1491<code>fountain</code> suitable for Fountain documents.
1492</p>
1493</li>
1494<li>
1495<p>
Junio C Hamanoa25ccc42018-03-08 21:36:14[diff] [blame]1496<code>golang</code> suitable for source code in the Go language.
1497</p>
1498</li>
1499<li>
1500<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1501<code>html</code> suitable for HTML/XHTML documents.
Junio C Hamanof24b8062008-09-09 01:34:39[diff] [blame]1502</p>
1503</li>
1504<li>
1505<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1506<code>java</code> suitable for source code in the Java language.
Junio C Hamanoa76cb0d2008-08-13 20:04:10[diff] [blame]1507</p>
1508</li>
1509<li>
1510<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1511<code>matlab</code> suitable for source code in the MATLAB language.
Junio C Hamano92887a32011-12-07 00:26:29[diff] [blame]1512</p>
1513</li>
1514<li>
1515<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1516<code>objc</code> suitable for source code in the Objective-C language.
Junio C Hamanoa476efa2008-10-10 15:31:42[diff] [blame]1517</p>
1518</li>
1519<li>
1520<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1521<code>pascal</code> suitable for source code in the Pascal/Delphi language.
Junio C Hamanoa76cb0d2008-08-13 20:04:10[diff] [blame]1522</p>
1523</li>
1524<li>
1525<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1526<code>perl</code> suitable for source code in the Perl language.
Junio C Hamano9b6fafe2011-01-14 00:43:22[diff] [blame]1527</p>
1528</li>
1529<li>
1530<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1531<code>php</code> suitable for source code in the PHP language.
Junio C Hamanof24b8062008-09-09 01:34:39[diff] [blame]1532</p>
1533</li>
1534<li>
1535<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1536<code>python</code> suitable for source code in the Python language.
Junio C Hamano3f2f6e52008-08-21 10:34:22[diff] [blame]1537</p>
1538</li>
1539<li>
1540<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1541<code>ruby</code> suitable for source code in the Ruby language.
Junio C Hamanoa76cb0d2008-08-13 20:04:10[diff] [blame]1542</p>
1543</li>
1544<li>
1545<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1546<code>tex</code> suitable for source code for LaTeX documents.
Junio C Hamanoa76cb0d2008-08-13 20:04:10[diff] [blame]1547</p>
1548</li>
1549</ul></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1550</div>
1551<div class="sect3">
Junio C Hamano20d47e32009-01-26 06:36:02[diff] [blame]1552<h4 id="_customizing_word_diff">Customizing word diff</h4>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1553<div class="paragraph"><p>You can customize the rules that <code>git diff --word-diff</code> uses to
Junio C Hamano20d47e32009-01-26 06:36:02[diff] [blame]1554split words in a line, by specifying an appropriate regular expression
1555in the "diff.*.wordRegex" configuration variable. For example, in TeX
1556a backslash followed by a sequence of letters forms a command, but
1557several such commands can be run together without intervening
Junio C Hamano3bd66e92009-04-18 06:17:56[diff] [blame]1558whitespace. To separate them, use a regular expression in your
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1559<code>$GIT_DIR/config</code> file (or <code>$HOME/.gitconfig</code> file) like this:</p></div>
Junio C Hamano20d47e32009-01-26 06:36:02[diff] [blame]1560<div class="listingblock">
1561<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1562<pre><code>[diff "tex"]
1563 wordRegex = "\\\\[a-zA-Z]+|[{}]|\\\\.|[^\\{}[:space:]]+"</code></pre>
Junio C Hamano20d47e32009-01-26 06:36:02[diff] [blame]1564</div></div>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1565<div class="paragraph"><p>A built-in pattern is provided for all languages listed in the
Junio C Hamano20d47e32009-01-26 06:36:02[diff] [blame]1566previous section.</p></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1567</div>
1568<div class="sect3">
Junio C Hamano28363492008-11-14 08:26:31[diff] [blame]1569<h4 id="_performing_text_diffs_of_binary_files">Performing text diffs of binary files</h4>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1570<div class="paragraph"><p>Sometimes it is desirable to see the diff of a text-converted
Junio C Hamano28363492008-11-14 08:26:31[diff] [blame]1571version of some binary files. For example, a word processor
1572document can be converted to an ASCII text representation, and
1573the diff of the text shown. Even though this conversion loses
1574some information, the resulting diff is useful for human
1575viewing (but cannot be applied directly).</p></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1576<div class="paragraph"><p>The <code>textconv</code> config option is used to define a program for
Junio C Hamano28363492008-11-14 08:26:31[diff] [blame]1577performing such a conversion. The program should take a single
1578argument, the name of a file to convert, and produce the
1579resulting text on stdout.</p></div>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1580<div class="paragraph"><p>For example, to show the diff of the exif information of a
Junio C Hamano28363492008-11-14 08:26:31[diff] [blame]1581file instead of the binary information (assuming you have the
Junio C Hamano3bd66e92009-04-18 06:17:56[diff] [blame]1582exif tool installed), add the following section to your
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1583<code>$GIT_DIR/config</code> file (or <code>$HOME/.gitconfig</code> file):</p></div>
Junio C Hamano28363492008-11-14 08:26:31[diff] [blame]1584<div class="listingblock">
1585<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1586<pre><code>[diff "jpg"]
1587 textconv = exif</code></pre>
Junio C Hamano28363492008-11-14 08:26:31[diff] [blame]1588</div></div>
1589<div class="admonitionblock">
1590<table><tr>
1591<td class="icon">
1592<div class="title">Note</div>
1593</td>
1594<td class="content">The text conversion is generally a one-way conversion;
1595in this example, we lose the actual image contents and focus
1596just on the text data. This means that diffs generated by
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1597textconv are <em>not</em> suitable for applying. For this reason,
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1598only <code>git diff</code> and the <code>git log</code> family of commands (i.e.,
1599log, whatchanged, show) will perform text conversion. <code>git
1600format-patch</code> will never generate this output. If you want to
Junio C Hamano28363492008-11-14 08:26:31[diff] [blame]1601send somebody a text-converted diff of a binary file (e.g.,
1602because it quickly conveys the changes you have made), you
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1603should generate it separately and send it as a comment <em>in
1604addition to</em> the usual binary diff that you might send.</td>
Junio C Hamano28363492008-11-14 08:26:31[diff] [blame]1605</tr></table>
1606</div>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1607<div class="paragraph"><p>Because text conversion can be slow, especially when doing a
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1608large number of them with <code>git log -p</code>, Git provides a mechanism
Junio C Hamanocb39aea2010-05-09 07:24:48[diff] [blame]1609to cache the output and use it in future diffs. To enable
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1610caching, set the "cachetextconv" variable in your diff driver&#8217;s
Junio C Hamanocb39aea2010-05-09 07:24:48[diff] [blame]1611config. For example:</p></div>
1612<div class="listingblock">
1613<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1614<pre><code>[diff "jpg"]
Junio C Hamanocb39aea2010-05-09 07:24:48[diff] [blame]1615 textconv = exif
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1616 cachetextconv = true</code></pre>
Junio C Hamanocb39aea2010-05-09 07:24:48[diff] [blame]1617</div></div>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1618<div class="paragraph"><p>This will cache the result of running "exif" on each blob
Junio C Hamanocb39aea2010-05-09 07:24:48[diff] [blame]1619indefinitely. If you change the textconv config variable for a
Junio C Hamano076ffcc2013-02-06 05:13:21[diff] [blame]1620diff driver, Git will automatically invalidate the cache entries
Junio C Hamanocb39aea2010-05-09 07:24:48[diff] [blame]1621and re-run the textconv filter. If you want to invalidate the
1622cache manually (e.g., because your version of "exif" was updated
1623and now produces better output), you can remove the cache
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1624manually with <code>git update-ref -d refs/notes/textconv/jpg</code> (where
Junio C Hamanocb39aea2010-05-09 07:24:48[diff] [blame]1625"jpg" is the name of the diff driver, as in the example above).</p></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1626</div>
1627<div class="sect3">
Junio C Hamanof93530e2011-05-25 23:59:59[diff] [blame]1628<h4 id="_choosing_textconv_versus_external_diff">Choosing textconv versus external diff</h4>
1629<div class="paragraph"><p>If you want to show differences between binary or specially-formatted
1630blobs in your repository, you can choose to use either an external diff
1631command, or to use textconv to convert them to a diff-able text format.
1632Which method you choose depends on your exact situation.</p></div>
1633<div class="paragraph"><p>The advantage of using an external diff command is flexibility. You are
1634not bound to find line-oriented changes, nor is it necessary for the
1635output to resemble unified diff. You are free to locate and report
1636changes in the most appropriate way for your data format.</p></div>
1637<div class="paragraph"><p>A textconv, by comparison, is much more limiting. You provide a
Junio C Hamano076ffcc2013-02-06 05:13:21[diff] [blame]1638transformation of the data into a line-oriented text format, and Git
Junio C Hamanof93530e2011-05-25 23:59:59[diff] [blame]1639uses its regular diff tools to generate the output. There are several
1640advantages to choosing this method:</p></div>
1641<div class="olist arabic"><ol class="arabic">
1642<li>
1643<p>
1644Ease of use. It is often much simpler to write a binary to text
1645 transformation than it is to perform your own diff. In many cases,
1646 existing programs can be used as textconv filters (e.g., exif,
1647 odt2txt).
1648</p>
1649</li>
1650<li>
1651<p>
1652Git diff features. By performing only the transformation step
Junio C Hamano076ffcc2013-02-06 05:13:21[diff] [blame]1653 yourself, you can still utilize many of Git&#8217;s diff features,
Junio C Hamanof93530e2011-05-25 23:59:59[diff] [blame]1654 including colorization, word-diff, and combined diffs for merges.
1655</p>
1656</li>
1657<li>
1658<p>
1659Caching. Textconv caching can speed up repeated diffs, such as those
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1660 you might trigger by running <code>git log -p</code>.
Junio C Hamanof93530e2011-05-25 23:59:59[diff] [blame]1661</p>
1662</li>
1663</ol></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1664</div>
1665<div class="sect3">
Junio C Hamano9b6fafe2011-01-14 00:43:22[diff] [blame]1666<h4 id="_marking_files_as_binary">Marking files as binary</h4>
1667<div class="paragraph"><p>Git usually guesses correctly whether a blob contains text or binary
1668data by examining the beginning of the contents. However, sometimes you
1669may want to override its decision, either because a blob contains binary
1670data later in the file, or because the content, while technically
1671composed of text characters, is opaque to a human reader. For example,
Junio C Hamanofb5ffde2014-11-04 22:38:56[diff] [blame]1672many postscript files contain only ASCII characters, but produce noisy
Junio C Hamano9b6fafe2011-01-14 00:43:22[diff] [blame]1673and meaningless diffs.</p></div>
1674<div class="paragraph"><p>The simplest way to mark a file as binary is to unset the diff
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1675attribute in the <code>.gitattributes</code> file:</p></div>
Junio C Hamano9b6fafe2011-01-14 00:43:22[diff] [blame]1676<div class="listingblock">
1677<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1678<pre><code>*.ps -diff</code></pre>
Junio C Hamano9b6fafe2011-01-14 00:43:22[diff] [blame]1679</div></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1680<div class="paragraph"><p>This will cause Git to generate <code>Binary files differ</code> (or a binary
Junio C Hamano9b6fafe2011-01-14 00:43:22[diff] [blame]1681patch, if binary patches are enabled) instead of a regular diff.</p></div>
1682<div class="paragraph"><p>However, one may also want to specify other diff driver attributes. For
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1683example, you might want to use <code>textconv</code> to convert postscript files to
Junio C Hamanofb5ffde2014-11-04 22:38:56[diff] [blame]1684an ASCII representation for human viewing, but otherwise treat them as
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1685binary files. You cannot specify both <code>-diff</code> and <code>diff=ps</code> attributes.
1686The solution is to use the <code>diff.*.binary</code> config option:</p></div>
Junio C Hamano9b6fafe2011-01-14 00:43:22[diff] [blame]1687<div class="listingblock">
1688<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1689<pre><code>[diff "ps"]
Junio C Hamano9b6fafe2011-01-14 00:43:22[diff] [blame]1690 textconv = ps2ascii
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1691 binary = true</code></pre>
Junio C Hamano9b6fafe2011-01-14 00:43:22[diff] [blame]1692</div></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1693</div>
1694</div>
1695<div class="sect2">
1696<h3 id="_performing_a_three_way_merge">Performing a three-way merge</h3>
1697<div class="sect3">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1698<h4 id="_code_merge_code"><code>merge</code></h4>
1699<div class="paragraph"><p>The attribute <code>merge</code> affects how three versions of a file are
1700merged when a file-level merge is necessary during <code>git merge</code>,
1701and other commands such as <code>git revert</code> and <code>git cherry-pick</code>.</p></div>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1702<div class="dlist"><dl>
1703<dt class="hdlist1">
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]1704Set
1705</dt>
1706<dd>
1707<p>
1708 Built-in 3-way merge driver is used to merge the
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1709 contents in a way similar to <em>merge</em> command of <code>RCS</code>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]1710 suite. This is suitable for ordinary text files.
1711</p>
1712</dd>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1713<dt class="hdlist1">
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]1714Unset
1715</dt>
1716<dd>
1717<p>
1718 Take the version from the current branch as the
1719 tentative merge result, and declare that the merge has
Junio C Hamanofa28cb12011-03-19 01:35:35[diff] [blame]1720 conflicts. This is suitable for binary files that do
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]1721 not have a well-defined merge semantics.
1722</p>
1723</dd>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1724<dt class="hdlist1">
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]1725Unspecified
1726</dt>
1727<dd>
1728<p>
1729 By default, this uses the same built-in 3-way merge
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1730 driver as is the case when the <code>merge</code> attribute is set.
1731 However, the <code>merge.default</code> configuration variable can name
Junio C Hamanofa28cb12011-03-19 01:35:35[diff] [blame]1732 different merge driver to be used with paths for which the
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1733 <code>merge</code> attribute is unspecified.
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]1734</p>
1735</dd>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1736<dt class="hdlist1">
Junio C Hamano9db95ca2007-04-23 07:27:05[diff] [blame]1737String
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]1738</dt>
1739<dd>
1740<p>
1741 3-way merge is performed using the specified custom
1742 merge driver. The built-in 3-way merge driver can be
1743 explicitly specified by asking for "text" driver; the
1744 built-in "take the current branch" driver can be
Junio C Hamano22572e72007-04-25 05:59:25[diff] [blame]1745 requested with "binary".
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]1746</p>
1747</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1748</dl></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1749</div>
1750<div class="sect3">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1751<h4 id="_built_in_merge_drivers">Built-in merge drivers</h4>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1752<div class="paragraph"><p>There are a few built-in low-level merge drivers defined that
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1753can be asked for via the <code>merge</code> attribute.</p></div>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1754<div class="dlist"><dl>
1755<dt class="hdlist1">
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]1756text
1757</dt>
1758<dd>
1759<p>
1760 Usual 3-way file level merge for text files. Conflicted
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1761 regions are marked with conflict markers <code>&lt;&lt;&lt;&lt;&lt;&lt;&lt;</code>,
1762 <code>=======</code> and <code>&gt;&gt;&gt;&gt;&gt;&gt;&gt;</code>. The version from your branch
1763 appears before the <code>=======</code> marker, and the version
1764 from the merged branch appears after the <code>=======</code>
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]1765 marker.
1766</p>
1767</dd>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1768<dt class="hdlist1">
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]1769binary
1770</dt>
1771<dd>
1772<p>
1773 Keep the version from your branch in the work tree, but
1774 leave the path in the conflicted state for the user to
1775 sort out.
1776</p>
1777</dd>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1778<dt class="hdlist1">
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]1779union
1780</dt>
1781<dd>
1782<p>
1783 Run 3-way file level merge for text files, but take
1784 lines from both versions, instead of leaving conflict
1785 markers. This tends to leave the added lines in the
1786 resulting file in random order and the user should
1787 verify the result. Do not use this if you do not
1788 understand the implications.
1789</p>
1790</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1791</dl></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1792</div>
1793<div class="sect3">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1794<h4 id="_defining_a_custom_merge_driver">Defining a custom merge driver</h4>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1795<div class="paragraph"><p>The definition of a merge driver is done in the <code>.git/config</code>
1796file, not in the <code>gitattributes</code> file, so strictly speaking this
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1797manual page is a wrong place to talk about it. However&#8230;</p></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1798<div class="paragraph"><p>To define a custom merge driver <code>filfre</code>, add a section to your
1799<code>$GIT_DIR/config</code> file (or <code>$HOME/.gitconfig</code> file) like this:</p></div>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]1800<div class="listingblock">
1801<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1802<pre><code>[merge "filfre"]
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]1803 name = feel-free merge driver
Junio C Hamanodf5384b2015-06-24 21:12:12[diff] [blame]1804 driver = filfre %O %A %B %L %P
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1805 recursive = binary</code></pre>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]1806</div></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1807<div class="paragraph"><p>The <code>merge.*.name</code> variable gives the driver a human-readable
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1808name.</p></div>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1809<div class="paragraph"><p>The &#8216;merge.*.driver` variable&#8217;s value is used to construct a
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1810command to run to merge ancestor&#8217;s version (<code>%O</code>), current
1811version (<code>%A</code>) and the other branches&#8217; version (<code>%B</code>). These
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]1812three tokens are replaced with the names of temporary files that
1813hold the contents of these versions when the command line is
Junio C Hamano86660db2010-02-24 01:12:54[diff] [blame]1814built. Additionally, %L will be replaced with the conflict marker
1815size (see below).</p></div>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1816<div class="paragraph"><p>The merge driver is expected to leave the result of the merge in
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1817the file named with <code>%A</code> by overwriting it, and exit with zero
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]1818status if it managed to merge them cleanly, or non-zero if there
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1819were conflicts.</p></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1820<div class="paragraph"><p>The <code>merge.*.recursive</code> variable specifies what other merge
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]1821driver to use when the merge driver is called for an internal
1822merge between common ancestors, when there are more than one.
1823When left unspecified, the driver itself is used for both
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1824internal merge and the final merge.</p></div>
Junio C Hamanodf5384b2015-06-24 21:12:12[diff] [blame]1825<div class="paragraph"><p>The merge driver can learn the pathname in which the merged result
1826will be stored via placeholder <code>%P</code>.</p></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1827</div>
1828<div class="sect3">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1829<h4 id="_code_conflict_marker_size_code"><code>conflict-marker-size</code></h4>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1830<div class="paragraph"><p>This attribute controls the length of conflict markers left in
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]1831the work tree file during a conflicted merge. Only setting to
1832the value to a positive integer has any meaningful effect.</p></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1833<div class="paragraph"><p>For example, this line in <code>.gitattributes</code> can be used to tell the merge
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]1834machinery to leave much longer (instead of the usual 7-character-long)
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1835conflict markers when merging the file <code>Documentation/git-merge.txt</code>
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]1836results in a conflict.</p></div>
1837<div class="listingblock">
1838<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1839<pre><code>Documentation/git-merge.txt conflict-marker-size=32</code></pre>
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]1840</div></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1841</div>
1842</div>
1843<div class="sect2">
1844<h3 id="_checking_whitespace_errors">Checking whitespace errors</h3>
1845<div class="sect3">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1846<h4 id="_code_whitespace_code"><code>whitespace</code></h4>
1847<div class="paragraph"><p>The <code>core.whitespace</code> configuration variable allows you to define what
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1848<em>diff</em> and <em>apply</em> should consider whitespace errors for all paths in
Junio C Hamanoa28a9202012-06-21 07:08:23[diff] [blame]1849the 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]1850control per path.</p></div>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1851<div class="dlist"><dl>
1852<dt class="hdlist1">
Junio C Hamano942b35e2007-12-09 10:19:33[diff] [blame]1853Set
1854</dt>
1855<dd>
1856<p>
Junio C Hamano076ffcc2013-02-06 05:13:21[diff] [blame]1857 Notice all types of potential whitespace errors known to Git.
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1858 The tab width is taken from the value of the <code>core.whitespace</code>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1859 configuration variable.
Junio C Hamano942b35e2007-12-09 10:19:33[diff] [blame]1860</p>
1861</dd>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1862<dt class="hdlist1">
Junio C Hamano942b35e2007-12-09 10:19:33[diff] [blame]1863Unset
1864</dt>
1865<dd>
1866<p>
1867 Do not notice anything as error.
1868</p>
1869</dd>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1870<dt class="hdlist1">
Junio C Hamano942b35e2007-12-09 10:19:33[diff] [blame]1871Unspecified
1872</dt>
1873<dd>
1874<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1875 Use the value of the <code>core.whitespace</code> configuration variable to
Junio C Hamano942b35e2007-12-09 10:19:33[diff] [blame]1876 decide what to notice as error.
1877</p>
1878</dd>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1879<dt class="hdlist1">
Junio C Hamano942b35e2007-12-09 10:19:33[diff] [blame]1880String
1881</dt>
1882<dd>
1883<p>
1884 Specify a comma separate list of common whitespace problems to
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1885 notice in the same format as the <code>core.whitespace</code> configuration
Junio C Hamano942b35e2007-12-09 10:19:33[diff] [blame]1886 variable.
1887</p>
1888</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1889</dl></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1890</div>
1891</div>
1892<div class="sect2">
1893<h3 id="_creating_an_archive">Creating an archive</h3>
1894<div class="sect3">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1895<h4 id="_code_export_ignore_code"><code>export-ignore</code></h4>
1896<div class="paragraph"><p>Files and directories with the attribute <code>export-ignore</code> won&#8217;t be added to
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1897archive files.</p></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1898</div>
1899<div class="sect3">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1900<h4 id="_code_export_subst_code"><code>export-subst</code></h4>
1901<div class="paragraph"><p>If the attribute <code>export-subst</code> is set for a file then Git will expand
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1902several placeholders when adding this file to an archive. The
1903expansion depends on the availability of a commit ID, i.e., if
Junio C Hamanoa28a9202012-06-21 07:08:23[diff] [blame]1904<a href="git-archive.html">git-archive(1)</a> has been given a tree instead of a commit or a
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1905tag then no replacement will be done. The placeholders are the same
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1906as those for the option <code>--pretty=format:</code> of <a href="git-log.html">git-log(1)</a>,
1907except that they need to be wrapped like this: <code>$Format:PLACEHOLDERS$</code>
1908in the file. E.g. the string <code>$Format:%H$</code> will be replaced by the
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1909commit hash.</p></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1910</div>
1911</div>
1912<div class="sect2">
1913<h3 id="_packing_objects">Packing objects</h3>
1914<div class="sect3">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1915<h4 id="_code_delta_code"><code>delta</code></h4>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1916<div class="paragraph"><p>Delta compression will not be attempted for blobs for paths with the
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1917attribute <code>delta</code> set to false.</p></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1918</div>
1919</div>
1920<div class="sect2">
1921<h3 id="_viewing_files_in_gui_tools">Viewing files in GUI tools</h3>
1922<div class="sect3">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1923<h4 id="_code_encoding_code"><code>encoding</code></h4>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1924<div class="paragraph"><p>The value of this attribute specifies the character encoding that should
Junio C Hamanoa28a9202012-06-21 07:08:23[diff] [blame]1925be used by GUI tools (e.g. <a href="gitk.html">gitk(1)</a> and <a href="git-gui.html">git-gui(1)</a>) to
Junio C Hamanod3452a02008-11-15 08:07:55[diff] [blame]1926display the contents of the relevant file. Note that due to performance
Junio C Hamanoa28a9202012-06-21 07:08:23[diff] [blame]1927considerations <a href="gitk.html">gitk(1)</a> does not use this attribute unless you
Junio C Hamanod3452a02008-11-15 08:07:55[diff] [blame]1928manually enable per-file encodings in its options.</p></div>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1929<div class="paragraph"><p>If this attribute is not set or has an invalid value, the value of the
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1930<code>gui.encoding</code> configuration variable is used instead
Junio C Hamanoa28a9202012-06-21 07:08:23[diff] [blame]1931(See <a href="git-config.html">git-config(1)</a>).</p></div>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]1932</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1933</div>
1934</div>
1935</div>
1936<div class="sect1">
Junio C Hamano86d84362011-08-04 00:21:51[diff] [blame]1937<h2 id="_using_macro_attributes">USING MACRO ATTRIBUTES</h2>
Junio C Hamanofcb740a2008-08-31 06:32:05[diff] [blame]1938<div class="sectionbody">
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1939<div class="paragraph"><p>You do not want any end-of-line conversions applied to, nor textual diffs
Junio C Hamanofcb740a2008-08-31 06:32:05[diff] [blame]1940produced for, any binary file you track. You would need to specify e.g.</p></div>
1941<div class="listingblock">
1942<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1943<pre><code>*.jpg -text -diff</code></pre>
Junio C Hamanofcb740a2008-08-31 06:32:05[diff] [blame]1944</div></div>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1945<div class="paragraph"><p>but that may become cumbersome, when you have many attributes. Using
Junio C Hamano86d84362011-08-04 00:21:51[diff] [blame]1946macro attributes, you can define an attribute that, when set, also
1947sets or unsets a number of other attributes at the same time. The
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1948system knows a built-in macro attribute, <code>binary</code>:</p></div>
Junio C Hamanofcb740a2008-08-31 06:32:05[diff] [blame]1949<div class="listingblock">
1950<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1951<pre><code>*.jpg binary</code></pre>
Junio C Hamanofcb740a2008-08-31 06:32:05[diff] [blame]1952</div></div>
Junio C Hamano86d84362011-08-04 00:21:51[diff] [blame]1953<div class="paragraph"><p>Setting the "binary" attribute also unsets the "text" and "diff"
1954attributes as above. Note that macro attributes can only be "Set",
1955though setting one might have the effect of setting or unsetting other
1956attributes or even returning other attributes to the "Unspecified"
1957state.</p></div>
Junio C Hamanofcb740a2008-08-31 06:32:05[diff] [blame]1958</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1959</div>
1960<div class="sect1">
Junio C Hamano86d84362011-08-04 00:21:51[diff] [blame]1961<h2 id="_defining_macro_attributes">DEFINING MACRO ATTRIBUTES</h2>
Junio C Hamanofcb740a2008-08-31 06:32:05[diff] [blame]1962<div class="sectionbody">
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1963<div class="paragraph"><p>Custom macro attributes can be defined only in top-level gitattributes
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1964files (<code>$GIT_DIR/info/attributes</code>, the <code>.gitattributes</code> file at the
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1965top level of the working tree, or the global or system-wide
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1966gitattributes files), not in <code>.gitattributes</code> files in working tree
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1967subdirectories. The built-in macro attribute "binary" is equivalent
1968to:</p></div>
Junio C Hamanofcb740a2008-08-31 06:32:05[diff] [blame]1969<div class="listingblock">
1970<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1971<pre><code>[attr]binary -diff -merge -text</code></pre>
Junio C Hamanofcb740a2008-08-31 06:32:05[diff] [blame]1972</div></div>
1973</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1974</div>
1975<div class="sect1">
Junio C Hamano4b2a6c12017-08-22 18:32:37[diff] [blame]1976<h2 id="_example_2">EXAMPLE</h2>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]1977<div class="sectionbody">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1978<div class="paragraph"><p>If you have these three <code>gitattributes</code> file:</p></div>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]1979<div class="listingblock">
1980<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1981<pre><code>(in $GIT_DIR/info/attributes)
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]1982
1983a* foo !bar -baz
1984
1985(in .gitattributes)
1986abc foo bar baz
1987
1988(in t/.gitattributes)
1989ab* merge=filfre
1990abc -foo -bar
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1991*.c frotz</code></pre>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]1992</div></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1993<div class="paragraph"><p>the attributes given to path <code>t/abc</code> are computed as follows:</p></div>
Junio C Hamanoeef01fe2010-12-13 08:31:58[diff] [blame]1994<div class="olist arabic"><ol class="arabic">
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]1995<li>
1996<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1997By examining <code>t/.gitattributes</code> (which is in the same
Junio C Hamano076ffcc2013-02-06 05:13:21[diff] [blame]1998 directory as the path in question), Git finds that the first
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1999 line matches. <code>merge</code> attribute is set. It also finds that
2000 the second line matches, and attributes <code>foo</code> and <code>bar</code>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]2001 are unset.
2002</p>
2003</li>
2004<li>
2005<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]2006Then it examines <code>.gitattributes</code> (which is in the parent
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]2007 directory), and finds that the first line matches, but
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]2008 <code>t/.gitattributes</code> file already decided how <code>merge</code>, <code>foo</code>
2009 and <code>bar</code> attributes should be given to this path, so it
2010 leaves <code>foo</code> and <code>bar</code> unset. Attribute <code>baz</code> is set.
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]2011</p>
2012</li>
2013<li>
2014<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]2015Finally it examines <code>$GIT_DIR/info/attributes</code>. This file
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]2016 is used to override the in-tree settings. The first line is
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]2017 a match, and <code>foo</code> is set, <code>bar</code> is reverted to unspecified
2018 state, and <code>baz</code> is unset.
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]2019</p>
2020</li>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2021</ol></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]2022<div class="paragraph"><p>As the result, the attributes assignment to <code>t/abc</code> becomes:</p></div>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]2023<div class="listingblock">
2024<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]2025<pre><code>foo set to true
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]2026bar unspecified
2027baz set to false
2028merge set to string value "filfre"
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]2029frotz unspecified</code></pre>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]2030</div></div>
2031</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]2032</div>
2033<div class="sect1">
Junio C Hamanof7279012011-08-18 06:13:13[diff] [blame]2034<h2 id="_see_also">SEE ALSO</h2>
2035<div class="sectionbody">
Junio C Hamanoa28a9202012-06-21 07:08:23[diff] [blame]2036<div class="paragraph"><p><a href="git-check-attr.html">git-check-attr(1)</a>.</p></div>
Junio C Hamanof7279012011-08-18 06:13:13[diff] [blame]2037</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]2038</div>
2039<div class="sect1">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2040<h2 id="_git">GIT</h2>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]2041<div class="sectionbody">
Junio C Hamanoa28a9202012-06-21 07:08:23[diff] [blame]2042<div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]2043</div>
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]2044</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]2045</div>
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]2046<div id="footnotes"><hr /></div>
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]2047<div id="footer">
2048<div id="footer-text">
Junio C Hamano2ef0ba32018-01-26 23:13:53[diff] [blame]2049Last updated
Junio C Hamanoa25ccc42018-03-08 21:36:14[diff] [blame]2050 2018-03-08 13:35:19 PST
Junio C Hamanoe90436a2007-04-22 07:22:13[diff] [blame]2051</div>
2052</div>
2053</body>
2054</html>