blob: 7f9c18503325c4b29f5b31f08ea467c18c1f9724 [file] [log] [blame]
Junio C Hamano1a4e8412005-12-27 08:17:231<!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:115<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
Junio C Hamanoc14e6ad2014-10-31 20:25:536<meta name="generator" content="AsciiDoc 8.6.9" />
Junio C Hamano5fa6d1a2010-12-23 00:57:397<title>git-read-tree(1)</title>
Junio C Hamano1a4e8412005-12-27 08:17:238<style type="text/css">
Junio C Hamano9d971152012-12-19 00:43:119/* 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 Hamano1a4e8412005-12-27 08:17:2324}
25
26body {
27 margin: 1em 5% 1em 5%;
28}
29
Junio C Hamanoba4b9282008-07-06 05:20:3130a {
31 color: blue;
32 text-decoration: underline;
33}
34a:visited {
35 color: fuchsia;
36}
Junio C Hamano1a4e8412005-12-27 08:17:2337
38em {
39 font-style: italic;
Junio C Hamano5fa6d1a2010-12-23 00:57:3940 color: navy;
Junio C Hamano1a4e8412005-12-27 08:17:2341}
42
43strong {
44 font-weight: bold;
Junio C Hamano5fa6d1a2010-12-23 00:57:3945 color: #083194;
Junio C Hamano1a4e8412005-12-27 08:17:2346}
47
Junio C Hamano1a4e8412005-12-27 08:17:2348h1, h2, h3, h4, h5, h6 {
49 color: #527bbd;
Junio C Hamano1a4e8412005-12-27 08:17:2350 margin-top: 1.2em;
51 margin-bottom: 0.5em;
52 line-height: 1.3;
53}
54
Junio C Hamanoba4b9282008-07-06 05:20:3155h1, h2, h3 {
Junio C Hamano1a4e8412005-12-27 08:17:2356 border-bottom: 2px solid silver;
57}
58h2 {
Junio C Hamano1a4e8412005-12-27 08:17:2359 padding-top: 0.5em;
60}
Junio C Hamanoba4b9282008-07-06 05:20:3161h3 {
62 float: left;
63}
64h3 + * {
65 clear: left;
66}
Junio C Hamano9d971152012-12-19 00:43:1167h5 {
68 font-size: 1.0em;
69}
Junio C Hamano1a4e8412005-12-27 08:17:2370
71div.sectionbody {
Junio C Hamano1a4e8412005-12-27 08:17:2372 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 Hamano5fa6d1a2010-12-23 00:57:3984ul, ol, li > p {
85 margin-top: 0;
86}
Junio C Hamano9d971152012-12-19 00:43:1187ul > li { color: #aaa; }
88ul > li > * { color: black; }
Junio C Hamano5fa6d1a2010-12-23 00:57:3989
Junio C Hamanoc14e6ad2014-10-31 20:25:5390.monospaced, code, pre {
91 font-family: "Courier New", Courier, monospace;
92 font-size: inherit;
93 color: navy;
Junio C Hamano1a4e8412005-12-27 08:17:2394 padding: 0;
95 margin: 0;
96}
Junio C Hamanoc14e6ad2014-10-31 20:25:5397pre {
98 white-space: pre-wrap;
99}
Junio C Hamano1a4e8412005-12-27 08:17:23100
Junio C Hamano9d971152012-12-19 00:43:11101#author {
Junio C Hamano1a4e8412005-12-27 08:17:23102 color: #527bbd;
Junio C Hamano1a4e8412005-12-27 08:17:23103 font-weight: bold;
Junio C Hamanoba4b9282008-07-06 05:20:31104 font-size: 1.1em;
Junio C Hamano1a4e8412005-12-27 08:17:23105}
Junio C Hamano9d971152012-12-19 00:43:11106#email {
Junio C Hamano1a4e8412005-12-27 08:17:23107}
Junio C Hamano9d971152012-12-19 00:43:11108#revnumber, #revdate, #revremark {
Junio C Hamano1a4e8412005-12-27 08:17:23109}
110
Junio C Hamano9d971152012-12-19 00:43:11111#footer {
Junio C Hamano1a4e8412005-12-27 08:17:23112 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:11117#footer-text {
Junio C Hamano1a4e8412005-12-27 08:17:23118 float: left;
119 padding-bottom: 0.5em;
120}
Junio C Hamano9d971152012-12-19 00:43:11121#footer-badges {
Junio C Hamano1a4e8412005-12-27 08:17:23122 float: right;
123 padding-bottom: 0.5em;
124}
125
Junio C Hamano9d971152012-12-19 00:43:11126#preamble {
Junio C Hamano5fa6d1a2010-12-23 00:57:39127 margin-top: 1.5em;
128 margin-bottom: 1.5em;
129}
Junio C Hamano9d971152012-12-19 00:43:11130div.imageblock, div.exampleblock, div.verseblock,
Junio C Hamano1a4e8412005-12-27 08:17:23131div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
132div.admonitionblock {
Junio C Hamano7bd050f2011-09-22 06:32:22133 margin-top: 1.0em;
Junio C Hamano1a4e8412005-12-27 08:17:23134 margin-bottom: 1.5em;
135}
136div.admonitionblock {
Junio C Hamano7bd050f2011-09-22 06:32:22137 margin-top: 2.0em;
138 margin-bottom: 2.0em;
139 margin-right: 10%;
140 color: #606060;
Junio C Hamano1a4e8412005-12-27 08:17:23141}
142
143div.content { /* Block element content. */
144 padding: 0;
145}
146
147/* Block element titles. */
148div.title, caption.title {
Junio C Hamano5fa6d1a2010-12-23 00:57:39149 color: #527bbd;
Junio C Hamano1a4e8412005-12-27 08:17:23150 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:11171 border: 1px solid #dddddd;
172 border-left: 4px solid #f0f0f0;
Junio C Hamano1a4e8412005-12-27 08:17:23173 padding: 0.5em;
174}
175
176div.listingblock > div.content {
Junio C Hamano9d971152012-12-19 00:43:11177 border: 1px solid #dddddd;
178 border-left: 5px solid #f0f0f0;
179 background: #f8f8f8;
Junio C Hamano1a4e8412005-12-27 08:17:23180 padding: 0.5em;
181}
182
Junio C Hamano7bd050f2011-09-22 06:32:22183div.quoteblock, div.verseblock {
184 padding-left: 1.0em;
185 margin-left: 1.0em;
Junio C Hamano5fa6d1a2010-12-23 00:57:39186 margin-right: 10%;
Junio C Hamano9d971152012-12-19 00:43:11187 border-left: 5px solid #f0f0f0;
188 color: #888;
Junio C Hamano1a4e8412005-12-27 08:17:23189}
Junio C Hamano7bd050f2011-09-22 06:32:22190
Junio C Hamano5fa6d1a2010-12-23 00:57:39191div.quoteblock > div.attribution {
192 padding-top: 0.5em;
Junio C Hamano1a4e8412005-12-27 08:17:23193 text-align: right;
194}
Junio C Hamano5fa6d1a2010-12-23 00:57:39195
Junio C Hamano9d971152012-12-19 00:43:11196div.verseblock > pre.content {
197 font-family: inherit;
198 font-size: inherit;
Junio C Hamano5fa6d1a2010-12-23 00:57:39199}
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:31205div.verseblock + div.attribution {
206 text-align: left;
207}
Junio C Hamano1a4e8412005-12-27 08:17:23208
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:22219 border-left: 3px solid #dddddd;
Junio C Hamano1a4e8412005-12-27 08:17:23220}
221
222div.exampleblock > div.content {
Junio C Hamano7bd050f2011-09-22 06:32:22223 border-left: 3px solid #dddddd;
224 padding-left: 0.5em;
Junio C Hamano1a4e8412005-12-27 08:17:23225}
226
Junio C Hamano1a4e8412005-12-27 08:17:23227div.imageblock div.content { padding-left: 0; }
Junio C Hamanoc14e6ad2014-10-31 20:25:53228span.image img { border-style: none; vertical-align: text-bottom; }
Junio C Hamano5fa6d1a2010-12-23 00:57:39229a.image:visited { color: white; }
Junio C Hamano1a4e8412005-12-27 08:17:23230
231dl {
232 margin-top: 0.8em;
233 margin-bottom: 0.8em;
234}
235dt {
236 margin-top: 0.5em;
237 margin-bottom: 0;
Junio C Hamano5fa6d1a2010-12-23 00:57:39238 font-style: normal;
239 color: navy;
Junio C Hamano1a4e8412005-12-27 08:17:23240}
241dd > *:first-child {
Junio C Hamano5fa6d1a2010-12-23 00:57:39242 margin-top: 0.1em;
Junio C Hamano1a4e8412005-12-27 08:17:23243}
244
245ul, ol {
246 list-style-position: outside;
247}
Junio C Hamano5fa6d1a2010-12-23 00:57:39248ol.arabic {
249 list-style-type: decimal;
250}
251ol.loweralpha {
Junio C Hamano1a4e8412005-12-27 08:17:23252 list-style-type: lower-alpha;
253}
Junio C Hamano5fa6d1a2010-12-23 00:57:39254ol.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 Hamano1a4e8412005-12-27 08:17:23270
Junio C Hamano1a4e8412005-12-27 08:17:23271tfoot {
272 font-weight: bold;
273}
Junio C Hamano5fa6d1a2010-12-23 00:57:39274td > div.verse {
275 white-space: pre;
276}
Junio C Hamano5fa6d1a2010-12-23 00:57:39277
278div.hdlist {
Junio C Hamano1a4e8412005-12-27 08:17:23279 margin-top: 0.8em;
280 margin-bottom: 0.8em;
281}
Junio C Hamano5fa6d1a2010-12-23 00:57:39282div.hdlist tr {
283 padding-bottom: 15px;
Junio C Hamanoba4b9282008-07-06 05:20:31284}
Junio C Hamano5fa6d1a2010-12-23 00:57:39285dt.hdlist1.strong, td.hdlist1.strong {
286 font-weight: bold;
287}
288td.hdlist1 {
Junio C Hamano1a4e8412005-12-27 08:17:23289 vertical-align: top;
Junio C Hamano5fa6d1a2010-12-23 00:57:39290 font-style: normal;
Junio C Hamano1a4e8412005-12-27 08:17:23291 padding-right: 0.8em;
Junio C Hamano5fa6d1a2010-12-23 00:57:39292 color: navy;
Junio C Hamano1a4e8412005-12-27 08:17:23293}
Junio C Hamano5fa6d1a2010-12-23 00:57:39294td.hdlist2 {
Junio C Hamano1a4e8412005-12-27 08:17:23295 vertical-align: top;
296}
Junio C Hamano5fa6d1a2010-12-23 00:57:39297div.hdlist.compact tr {
298 margin: 0;
299 padding-bottom: 0;
300}
301
302.comment {
303 background: yellow;
304}
Junio C Hamano1a4e8412005-12-27 08:17:23305
Junio C Hamano7bd050f2011-09-22 06:32:22306.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:11333div.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 Hamano1a4e8412005-12-27 08:17:23340}
Junio C Hamanoba4b9282008-07-06 05:20:31341
Junio C Hamano9d971152012-12-19 00:43:11342@media print {
343 #footer-badges { display: none; }
344}
345
346#toc {
Junio C Hamano7bd050f2011-09-22 06:32:22347 margin-bottom: 2.5em;
348}
349
Junio C Hamano9d971152012-12-19 00:43:11350#toctitle {
Junio C Hamanoba4b9282008-07-06 05:20:31351 color: #527bbd;
Junio C Hamanoba4b9282008-07-06 05:20:31352 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:53358div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
Junio C Hamanoba4b9282008-07-06 05:20:31359 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:11374
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:53416div.unbreakable { page-break-inside: avoid; }
417
Junio C Hamano9d971152012-12-19 00:43:11418
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 Hamano5fa6d1a2010-12-23 00:57:39521 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:11526body.manpage h2 {
Junio C Hamano5fa6d1a2010-12-23 00:57:39527 border-style: none;
528}
Junio C Hamano9d971152012-12-19 00:43:11529body.manpage div.sectionbody {
530 margin-left: 3em;
Junio C Hamano5fa6d1a2010-12-23 00:57:39531}
532
533@media print {
Junio C Hamano9d971152012-12-19 00:43:11534 body.manpage div#toc { display: none; }
Junio C Hamano5fa6d1a2010-12-23 00:57:39535}
Junio C Hamanoc14e6ad2014-10-31 20:25:53536
537
Junio C Hamano1a4e8412005-12-27 08:17:23538</style>
Junio C Hamano7bd050f2011-09-22 06:32:22539<script type="text/javascript">
540/*<![CDATA[*/
Junio C Hamano7bd050f2011-09-22 06:32:22541var 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:53582 var re = new RegExp('[hH]([1-'+(toclevels+1)+'])');
Junio C Hamano7bd050f2011-09-22 06:32:22583 // 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:11602 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:53611 if (entry.nodeName.toLowerCase() == 'div'
Junio C Hamano9d971152012-12-19 00:43:11612 && 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:22621 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:11648 // Delete existing footnote entries in case we're reloading the footnodes.
649 var i;
Junio C Hamano7bd050f2011-09-22 06:32:22650 var noteholder = document.getElementById("footnotes");
Junio C Hamano9d971152012-12-19 00:43:11651 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:53657 if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")
Junio C Hamano9d971152012-12-19 00:43:11658 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:22666 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:11672 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:22682 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:22686 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:11705},
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:22727}
728
729}
Junio C Hamano9d971152012-12-19 00:43:11730asciidoc.install();
Junio C Hamano7bd050f2011-09-22 06:32:22731/*]]>*/
732</script>
Junio C Hamano1a4e8412005-12-27 08:17:23733</head>
Junio C Hamano9d971152012-12-19 00:43:11734<body class="manpage">
Junio C Hamano1a4e8412005-12-27 08:17:23735<div id="header">
736<h1>
737git-read-tree(1) Manual Page
738</h1>
739<h2>NAME</h2>
740<div class="sectionbody">
741<p>git-read-tree -
742 Reads tree information into the index
743</p>
744</div>
745</div>
Junio C Hamano7bd050f2011-09-22 06:32:22746<div id="content">
Junio C Hamano9d971152012-12-19 00:43:11747<div class="sect1">
Junio C Hamano5fa6d1a2010-12-23 00:57:39748<h2 id="_synopsis">SYNOPSIS</h2>
Junio C Hamano1a4e8412005-12-27 08:17:23749<div class="sectionbody">
Junio C Hamano15567bc2011-07-23 00:51:59750<div class="verseblock">
Junio C Hamano9d971152012-12-19 00:43:11751<pre class="content"><em>git read-tree</em> [[-m [--trivial] [--aggressive] | --reset | --prefix=&lt;prefix&gt;]
Junio C Hamanofd9274d2009-08-05 21:21:39752 [-u [--exclude-per-directory=&lt;gitignore&gt;] | -i]]
Junio C Hamano3c8d6702010-01-13 23:09:03753 [--index-output=&lt;file&gt;] [--no-sparse-checkout]
Junio C Hamano9d971152012-12-19 00:43:11754 (--empty | &lt;tree-ish1&gt; [&lt;tree-ish2&gt; [&lt;tree-ish3&gt;]])</pre>
755<div class="attribution">
Junio C Hamano15567bc2011-07-23 00:51:59756</div></div>
Junio C Hamano1a4e8412005-12-27 08:17:23757</div>
Junio C Hamano9d971152012-12-19 00:43:11758</div>
759<div class="sect1">
Junio C Hamanoba4b9282008-07-06 05:20:31760<h2 id="_description">DESCRIPTION</h2>
Junio C Hamano1a4e8412005-12-27 08:17:23761<div class="sectionbody">
Junio C Hamano5fa6d1a2010-12-23 00:57:39762<div class="paragraph"><p>Reads the tree information given by &lt;tree-ish&gt; into the index,
Junio C Hamano1a4e8412005-12-27 08:17:23763but does not actually <strong>update</strong> any of the files it "caches". (see:
Junio C Hamanoa28a9202012-06-21 07:08:23764<a href="git-checkout-index.html">git-checkout-index(1)</a>)</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39765<div class="paragraph"><p>Optionally, it can merge a tree into the index, perform a
Junio C Hamanoc14e6ad2014-10-31 20:25:53766fast-forward (i.e. 2-way) merge, or a 3-way merge, with the <code>-m</code>
767flag. When used with <code>-m</code>, the <code>-u</code> flag causes it to also update
Junio C Hamanoba4b9282008-07-06 05:20:31768the files in the work tree with the result of the merge.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39769<div class="paragraph"><p>Trivial merges are done by <em>git read-tree</em> itself. Only conflicting paths
Junio C Hamano1aa40d22010-01-21 17:46:43770will be in unmerged state when <em>git read-tree</em> returns.</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:23771</div>
Junio C Hamano9d971152012-12-19 00:43:11772</div>
773<div class="sect1">
Junio C Hamanoba4b9282008-07-06 05:20:31774<h2 id="_options">OPTIONS</h2>
Junio C Hamano1a4e8412005-12-27 08:17:23775<div class="sectionbody">
Junio C Hamano5fa6d1a2010-12-23 00:57:39776<div class="dlist"><dl>
777<dt class="hdlist1">
Junio C Hamano1a4e8412005-12-27 08:17:23778-m
779</dt>
780<dd>
781<p>
782 Perform a merge, not just a read. The command will
783 refuse to run if your index file has unmerged entries,
784 indicating that you have not finished previous merge you
785 started.
786</p>
787</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39788<dt class="hdlist1">
Junio C Hamano1a4e8412005-12-27 08:17:23789--reset
790</dt>
791<dd>
792<p>
793 Same as -m, except that unmerged entries are discarded
794 instead of failing.
795</p>
796</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39797<dt class="hdlist1">
Junio C Hamano1a4e8412005-12-27 08:17:23798-u
799</dt>
800<dd>
801<p>
802 After a successful merge, update the files in the work
803 tree with the result of the merge.
804</p>
805</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39806<dt class="hdlist1">
Junio C Hamano1a4e8412005-12-27 08:17:23807-i
808</dt>
809<dd>
810<p>
811 Usually a merge requires the index file as well as the
Junio C Hamano8fb66e52011-10-05 20:59:51812 files in the working tree to be up to date with the
Junio C Hamano1a4e8412005-12-27 08:17:23813 current head commit, in order not to lose local
814 changes. This flag disables the check with the working
815 tree and is meant to be used when creating a merge of
816 trees that are not directly related to the current
817 working tree status into a temporary index file.
818</p>
819</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39820<dt class="hdlist1">
Junio C Hamanoef5a2f92011-05-31 19:53:33821-n
822</dt>
823<dt class="hdlist1">
824--dry-run
825</dt>
826<dd>
827<p>
828 Check if the command would error out, without updating the index
Junio C Hamanod75148a2014-04-08 19:48:38829 or the files in the working tree for real.
Junio C Hamanoef5a2f92011-05-31 19:53:33830</p>
831</dd>
832<dt class="hdlist1">
Junio C Hamano0a18b352008-06-10 04:10:25833-v
834</dt>
835<dd>
836<p>
837 Show the progress of checking files out.
838</p>
839</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39840<dt class="hdlist1">
Junio C Hamanoee695f22007-06-21 00:35:36841--trivial
842</dt>
843<dd>
844<p>
Junio C Hamano1aa40d22010-01-21 17:46:43845 Restrict three-way merge by <em>git read-tree</em> to happen
Junio C Hamanoee695f22007-06-21 00:35:36846 only if there is no file-level merging required, instead
847 of resolving merge for trivial cases and leaving
848 conflicting files unresolved in the index.
849</p>
850</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39851<dt class="hdlist1">
Junio C Hamano5f327762006-03-02 09:14:51852--aggressive
853</dt>
854<dd>
855<p>
Junio C Hamano1aa40d22010-01-21 17:46:43856 Usually a three-way merge by <em>git read-tree</em> resolves
Junio C Hamano5f327762006-03-02 09:14:51857 the merge for really trivial cases and leaves other
Junio C Hamano8fb66e52011-10-05 20:59:51858 cases unresolved in the index, so that porcelains can
Junio C Hamano5f327762006-03-02 09:14:51859 implement different merge policies. This flag makes the
Junio C Hamano8fb66e52011-10-05 20:59:51860 command resolve a few more cases internally:
Junio C Hamano5f327762006-03-02 09:14:51861</p>
Junio C Hamano5fa6d1a2010-12-23 00:57:39862<div class="ulist"><ul>
Junio C Hamano5f327762006-03-02 09:14:51863<li>
864<p>
865when one side removes a path and the other side leaves the path
866 unmodified. The resolution is to remove that path.
867</p>
868</li>
869<li>
870<p>
871when both sides remove a path. The resolution is to remove that path.
872</p>
873</li>
874<li>
875<p>
Junio C Hamano8fb66e52011-10-05 20:59:51876when both sides add a path identically. The resolution
Junio C Hamano5f327762006-03-02 09:14:51877 is to add that path.
878</p>
879</li>
Junio C Hamanoba4b9282008-07-06 05:20:31880</ul></div>
Junio C Hamano5f327762006-03-02 09:14:51881</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39882<dt class="hdlist1">
Junio C Hamano7b9cce92018-01-23 22:34:27883--prefix=&lt;prefix&gt;
Junio C Hamanoad8c6432006-06-18 09:26:43884</dt>
885<dd>
886<p>
887 Keep the current index contents, and read the contents
Junio C Hamanoc14e6ad2014-10-31 20:25:53888 of the named tree-ish under the directory at <code>&lt;prefix&gt;</code>.
Junio C Hamanodb472bc2012-01-04 00:22:37889 The command will refuse to overwrite entries that already
Junio C Hamano7b9cce92018-01-23 22:34:27890 existed in the original index file.
Junio C Hamanoad8c6432006-06-18 09:26:43891</p>
892</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39893<dt class="hdlist1">
Junio C Hamanoe7935c42006-12-13 21:32:17894--exclude-per-directory=&lt;gitignore&gt;
895</dt>
896<dd>
897<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53898 When running the command with <code>-u</code> and <code>-m</code> options, the
Junio C Hamanoe7935c42006-12-13 21:32:17899 merge result may need to overwrite paths that are not
900 tracked in the current branch. The command usually
901 refuses to proceed with the merge to avoid losing such a
902 path. However this safety valve sometimes gets in the
903 way. For example, it often happens that the other
904 branch added a file that used to be a generated file in
905 your branch, and the safety valve triggers when you try
Junio C Hamanoc14e6ad2014-10-31 20:25:53906 to switch to that branch after you ran <code>make</code> but before
907 running <code>make clean</code> to remove the generated file. This
Junio C Hamanoe7935c42006-12-13 21:32:17908 option tells the command to read per-directory exclude
909 file (usually <em>.gitignore</em>) and allows such an untracked
910 but explicitly ignored file to be overwritten.
911</p>
912</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39913<dt class="hdlist1">
Junio C Hamano12a3a232007-04-07 10:18:10914--index-output=&lt;file&gt;
915</dt>
916<dd>
917<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53918 Instead of writing the results out to <code>$GIT_INDEX_FILE</code>,
Junio C Hamano12a3a232007-04-07 10:18:10919 write the resulting index in the named file. While the
920 command is operating, the original index file is locked
921 with the same mechanism as usual. The file must allow
922 to be rename(2)ed into from a temporary file that is
923 created next to the usual index file; typically this
924 means it needs to be on the same filesystem as the index
925 file itself, and you need write permission to the
926 directories the index file and index output file are
927 located in.
928</p>
929</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39930<dt class="hdlist1">
Junio C Hamano2affb962017-03-28 22:01:40931--[no-]recurse-submodules
932</dt>
933<dd>
934<p>
935 Using --recurse-submodules will update the content of all initialized
936 submodules according to the commit recorded in the superproject by
937 calling read-tree recursively, also setting the submodules HEAD to be
938 detached at that commit.
939</p>
940</dd>
941<dt class="hdlist1">
Junio C Hamano3c8d6702010-01-13 23:09:03942--no-sparse-checkout
943</dt>
944<dd>
945<p>
Junio C Hamanoc14e6ad2014-10-31 20:25:53946 Disable sparse checkout support even if <code>core.sparseCheckout</code>
Junio C Hamano3c8d6702010-01-13 23:09:03947 is true.
948</p>
949</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39950<dt class="hdlist1">
Junio C Hamano3b4609d2010-09-30 00:04:34951--empty
952</dt>
953<dd>
954<p>
955 Instead of reading tree object(s) into the index, just empty
956 it.
957</p>
958</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39959<dt class="hdlist1">
Junio C Hamano1a4e8412005-12-27 08:17:23960&lt;tree-ish#&gt;
961</dt>
962<dd>
963<p>
964 The id of the tree object(s) to be read/merged.
965</p>
966</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31967</dl></div>
Junio C Hamano1a4e8412005-12-27 08:17:23968</div>
Junio C Hamano9d971152012-12-19 00:43:11969</div>
970<div class="sect1">
Junio C Hamanoba4b9282008-07-06 05:20:31971<h2 id="_merging">Merging</h2>
Junio C Hamano1a4e8412005-12-27 08:17:23972<div class="sectionbody">
Junio C Hamanoc14e6ad2014-10-31 20:25:53973<div class="paragraph"><p>If <code>-m</code> is specified, <em>git read-tree</em> can perform 3 kinds of
Junio C Hamano1a4e8412005-12-27 08:17:23974merge, a single tree merge if only 1 tree is given, a
Junio C Hamano6b6144f2017-05-29 06:20:15975fast-forward merge with 2 trees, or a 3-way merge if 3 or more trees are
Junio C Hamanoba4b9282008-07-06 05:20:31976provided.</p></div>
Junio C Hamano9d971152012-12-19 00:43:11977<div class="sect2">
978<h3 id="_single_tree_merge">Single Tree Merge</h3>
Junio C Hamano5fa6d1a2010-12-23 00:57:39979<div class="paragraph"><p>If only 1 tree is specified, <em>git read-tree</em> operates as if the user did not
Junio C Hamanoc14e6ad2014-10-31 20:25:53980specify <code>-m</code>, except that if the original index has an entry for a
Junio C Hamanoae2dfa82010-03-17 05:41:52981given pathname, and the contents of the path match with the tree
Junio C Hamano1a4e8412005-12-27 08:17:23982being read, the stat info from the index is used. (In other words, the
Junio C Hamano5fa6d1a2010-12-23 00:57:39983index&#8217;s stat()s take precedence over the merged tree&#8217;s).</p></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53984<div class="paragraph"><p>That means that if you do a <code>git read-tree -m &lt;newtree&gt;</code> followed by a
985<code>git checkout-index -f -u -a</code>, the <em>git checkout-index</em> only checks out
Junio C Hamanoba4b9282008-07-06 05:20:31986the stuff that really changed.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39987<div class="paragraph"><p>This is used to avoid unnecessary false hits when <em>git diff-files</em> is
Junio C Hamano1aa40d22010-01-21 17:46:43988run after <em>git read-tree</em>.</p></div>
Junio C Hamano9d971152012-12-19 00:43:11989</div>
990<div class="sect2">
991<h3 id="_two_tree_merge">Two Tree Merge</h3>
Junio C Hamanoc14e6ad2014-10-31 20:25:53992<div class="paragraph"><p>Typically, this is invoked as <code>git read-tree -m $H $M</code>, where $H
Junio C Hamano1a4e8412005-12-27 08:17:23993is the head commit of the current repository, and $M is the head
994of a foreign tree, which is simply ahead of $H (i.e. we are in a
Junio C Hamano3f680f32009-11-16 02:10:54995fast-forward situation).</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39996<div class="paragraph"><p>When two trees are specified, the user is telling <em>git read-tree</em>
Junio C Hamanoba4b9282008-07-06 05:20:31997the following:</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39998<div class="olist arabic"><ol class="arabic">
Junio C Hamano1a4e8412005-12-27 08:17:23999<li>
1000<p>
1001The current index and work tree is derived from $H, but
Junio C Hamanoae2dfa82010-03-17 05:41:521002 the user may have local changes in them since $H.
Junio C Hamano1a4e8412005-12-27 08:17:231003</p>
1004</li>
1005<li>
1006<p>
1007The user wants to fast-forward to $M.
1008</p>
1009</li>
Junio C Hamanoba4b9282008-07-06 05:20:311010</ol></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:531011<div class="paragraph"><p>In this case, the <code>git read-tree -m $H $M</code> command makes sure
Junio C Hamano1a4e8412005-12-27 08:17:231012that no local change is lost as the result of this "merge".
Junio C Hamanoae2dfa82010-03-17 05:41:521013Here are the "carry forward" rules, where "I" denotes the index,
1014"clean" means that index and work tree coincide, and "exists"/"nothing"
1015refer to the presence of a path in the specified commit:</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:231016<div class="literalblock">
1017<div class="content">
Junio C Hamanof0888582017-09-28 06:34:391018<pre><code> I H M Result
1019 -------------------------------------------------------
1020 0 nothing nothing nothing (does not happen)
1021 1 nothing nothing exists use M
1022 2 nothing exists nothing remove path from index
1023 3 nothing exists exists, use M if "initial checkout",
1024 H == M keep index otherwise
1025 exists, fail
1026 H != M
1027
1028 clean I==H I==M
1029 ------------------
1030 4 yes N/A N/A nothing nothing keep index
1031 5 no N/A N/A nothing nothing keep index
1032
1033 6 yes N/A yes nothing exists keep index
1034 7 no N/A yes nothing exists keep index
1035 8 yes N/A no nothing exists fail
1036 9 no N/A no nothing exists fail
1037
1038 10 yes yes N/A exists nothing remove path from index
1039 11 no yes N/A exists nothing fail
1040 12 yes no N/A exists nothing fail
1041 13 no no N/A exists nothing fail
1042
1043 clean (H==M)
1044 ------
1045 14 yes exists exists keep index
1046 15 no exists exists keep index
1047
1048 clean I==H I==M (H!=M)
1049 ------------------
1050 16 yes no no exists exists fail
1051 17 no no no exists exists fail
1052 18 yes no yes exists exists keep index
1053 19 no no yes exists exists keep index
1054 20 yes yes no exists exists use M
1055 21 no yes no exists exists fail</code></pre>
Junio C Hamano1a4e8412005-12-27 08:17:231056</div></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:391057<div class="paragraph"><p>In all "keep index" cases, the index entry stays as in the
Junio C Hamanoae2dfa82010-03-17 05:41:521058original index file. If the entry is not up to date,
Junio C Hamano1aa40d22010-01-21 17:46:431059<em>git read-tree</em> keeps the copy in the work tree intact when
Junio C Hamanoba4b9282008-07-06 05:20:311060operating under the -u flag.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:391061<div class="paragraph"><p>When this form of <em>git read-tree</em> returns successfully, you can
Junio C Hamanoae2dfa82010-03-17 05:41:521062see which of the "local changes" that you made were carried forward by running
Junio C Hamanoc14e6ad2014-10-31 20:25:531063<code>git diff-index --cached $M</code>. Note that this does not
1064necessarily match what <code>git diff-index --cached $H</code> would have
Junio C Hamano1a4e8412005-12-27 08:17:231065produced before such a two tree merge. This is because of cases
106618 and 19 --- if you already had the changes in $M (e.g. maybe
Junio C Hamanoc14e6ad2014-10-31 20:25:531067you picked it up via e-mail in a patch form), <code>git diff-index
1068--cached $H</code> would have told you about the change before this
1069merge, but it would not show in <code>git diff-index --cached $M</code>
Junio C Hamanoae2dfa82010-03-17 05:41:521070output after the two-tree merge.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:391071<div class="paragraph"><p>Case 3 is slightly tricky and needs explanation. The result from this
Junio C Hamano78ec2262008-09-16 19:17:311072rule logically should be to remove the path if the user staged the removal
Junio C Hamanoa476efa2008-10-10 15:31:421073of the path and then switching to a new branch. That however will prevent
Junio C Hamano78ec2262008-09-16 19:17:311074the initial checkout from happening, so the rule is modified to use M (new
Junio C Hamanoae2dfa82010-03-17 05:41:521075tree) only when the content of the index is empty. Otherwise the removal
Junio C Hamano78ec2262008-09-16 19:17:311076of the path is kept as long as $H and $M are the same.</p></div>
Junio C Hamano9d971152012-12-19 00:43:111077</div>
1078<div class="sect2">
1079<h3 id="_3_way_merge">3-Way Merge</h3>
Junio C Hamano5fa6d1a2010-12-23 00:57:391080<div class="paragraph"><p>Each "index" entry has two bits worth of "stage" state. stage 0 is the
1081normal one, and is the only one you&#8217;d see in any kind of normal use.</p></div>
1082<div class="paragraph"><p>However, when you do <em>git read-tree</em> with three trees, the "stage"
Junio C Hamanoba4b9282008-07-06 05:20:311083starts out at 1.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:391084<div class="paragraph"><p>This means that you can do</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:231085<div class="listingblock">
1086<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:531087<pre><code>$ git read-tree -m &lt;tree1&gt; &lt;tree2&gt; &lt;tree3&gt;</code></pre>
Junio C Hamano1a4e8412005-12-27 08:17:231088</div></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:391089<div class="paragraph"><p>and you will end up with an index with all of the &lt;tree1&gt; entries in
Junio C Hamano1a4e8412005-12-27 08:17:231090"stage1", all of the &lt;tree2&gt; entries in "stage2" and all of the
1091&lt;tree3&gt; entries in "stage3". When performing a merge of another
1092branch into the current branch, we use the common ancestor tree
1093as &lt;tree1&gt;, the current branch head as &lt;tree2&gt;, and the other
Junio C Hamanoba4b9282008-07-06 05:20:311094branch head as &lt;tree3&gt;.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:391095<div class="paragraph"><p>Furthermore, <em>git read-tree</em> has special-case logic that says: if you see
Junio C Hamano1a4e8412005-12-27 08:17:231096a file that matches in all respects in the following states, it
Junio C Hamanoba4b9282008-07-06 05:20:311097"collapses" back to "stage0":</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:391098<div class="ulist"><ul>
Junio C Hamano1a4e8412005-12-27 08:17:231099<li>
1100<p>
1101stage 2 and 3 are the same; take one or the other (it makes no
1102 difference - the same work has been done on our branch in
1103 stage 2 and their branch in stage 3)
1104</p>
1105</li>
1106<li>
1107<p>
1108stage 1 and stage 2 are the same and stage 3 is different; take
1109 stage 3 (our branch in stage 2 did not do anything since the
1110 ancestor in stage 1 while their branch in stage 3 worked on
1111 it)
1112</p>
1113</li>
1114<li>
1115<p>
1116stage 1 and stage 3 are the same and stage 2 is different take
1117 stage 2 (we did something while they did nothing)
1118</p>
1119</li>
Junio C Hamanoba4b9282008-07-06 05:20:311120</ul></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:391121<div class="paragraph"><p>The <em>git write-tree</em> command refuses to write a nonsensical tree, and it
Junio C Hamano1a4e8412005-12-27 08:17:231122will complain about unmerged entries if it sees a single entry that is not
Junio C Hamanoba4b9282008-07-06 05:20:311123stage 0.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:391124<div class="paragraph"><p>OK, this all sounds like a collection of totally nonsensical rules,
1125but it&#8217;s actually exactly what you want in order to do a fast
Junio C Hamano1a4e8412005-12-27 08:17:231126merge. The different stages represent the "result tree" (stage 0, aka
1127"merged"), the original tree (stage 1, aka "orig"), and the two trees
Junio C Hamanoba4b9282008-07-06 05:20:311128you are trying to merge (stage 2 and 3 respectively).</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:391129<div class="paragraph"><p>The order of stages 1, 2 and 3 (hence the order of three
Junio C Hamanoe1aeb5e2014-06-06 19:16:291130&lt;tree-ish&gt; command-line arguments) are significant when you
Junio C Hamano1a4e8412005-12-27 08:17:231131start a 3-way merge with an index file that is already
Junio C Hamanoba4b9282008-07-06 05:20:311132populated. Here is an outline of how the algorithm works:</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:391133<div class="ulist"><ul>
Junio C Hamano1a4e8412005-12-27 08:17:231134<li>
1135<p>
1136if a file exists in identical format in all three trees, it will
Junio C Hamano1aa40d22010-01-21 17:46:431137 automatically collapse to "merged" state by <em>git read-tree</em>.
Junio C Hamano1a4e8412005-12-27 08:17:231138</p>
1139</li>
1140<li>
1141<p>
Junio C Hamano5fa6d1a2010-12-23 00:57:391142a file that has <em>any</em> difference what-so-ever in the three trees
1143 will stay as separate entries in the index. It&#8217;s up to "porcelain
Junio C Hamano1a4e8412005-12-27 08:17:231144 policy" to determine how to remove the non-0 stages, and insert a
1145 merged version.
1146</p>
1147</li>
1148<li>
1149<p>
1150the index file saves and restores with all this information, so you
1151 can merge things incrementally, but as long as it has entries in
Junio C Hamano5fa6d1a2010-12-23 00:57:391152 stages 1/2/3 (i.e., "unmerged entries") you can&#8217;t write the result. So
Junio C Hamano1a4e8412005-12-27 08:17:231153 now the merge algorithm ends up being really simple:
1154</p>
Junio C Hamano5fa6d1a2010-12-23 00:57:391155<div class="ulist"><ul>
Junio C Hamano1a4e8412005-12-27 08:17:231156<li>
1157<p>
1158you walk the index in order, and ignore all entries of stage 0,
Junio C Hamano5fa6d1a2010-12-23 00:57:391159 since they&#8217;ve already been done.
Junio C Hamano1a4e8412005-12-27 08:17:231160</p>
1161</li>
1162<li>
1163<p>
1164if you find a "stage1", but no matching "stage2" or "stage3", you
Junio C Hamano5fa6d1a2010-12-23 00:57:391165 know it&#8217;s been removed from both trees (it only existed in the
Junio C Hamano1a4e8412005-12-27 08:17:231166 original tree), and you remove that entry.
1167</p>
1168</li>
1169<li>
1170<p>
1171if you find a matching "stage2" and "stage3" tree, you remove one
1172 of them, and turn the other into a "stage0" entry. Remove any
1173 matching "stage1" entry if it exists too. .. all the normal
1174 trivial rules ..
1175</p>
1176</li>
Junio C Hamanoba4b9282008-07-06 05:20:311177</ul></div>
Junio C Hamano1a4e8412005-12-27 08:17:231178</li>
Junio C Hamanoba4b9282008-07-06 05:20:311179</ul></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:391180<div class="paragraph"><p>You would normally use <em>git merge-index</em> with supplied
Junio C Hamano1aa40d22010-01-21 17:46:431181<em>git merge-one-file</em> to do this last step. The script updates
Junio C Hamano1a4e8412005-12-27 08:17:231182the files in the working tree as it merges each path and at the
Junio C Hamanoba4b9282008-07-06 05:20:311183end of a successful merge.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:391184<div class="paragraph"><p>When you start a 3-way merge with an index file that is already
Junio C Hamano1a4e8412005-12-27 08:17:231185populated, it is assumed that it represents the state of the
1186files in your work tree, and you can even have files with
1187changes unrecorded in the index file. It is further assumed
1188that this state is "derived" from the stage 2 tree. The 3-way
1189merge refuses to run if it finds an entry in the original index
Junio C Hamanoba4b9282008-07-06 05:20:311190file that does not match stage 2.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:391191<div class="paragraph"><p>This is done to prevent you from losing your work-in-progress
Junio C Hamano1a4e8412005-12-27 08:17:231192changes, and mixing your random changes in an unrelated merge
1193commit. To illustrate, suppose you start from what has been
Junio C Hamanoba4b9282008-07-06 05:20:311194committed last to your repository:</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:231195<div class="listingblock">
1196<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:531197<pre><code>$ JC=`git rev-parse --verify "HEAD^0"`
1198$ git checkout-index -f -u -a $JC</code></pre>
Junio C Hamano1a4e8412005-12-27 08:17:231199</div></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:391200<div class="paragraph"><p>You do random edits, without running <em>git update-index</em>. And then
Junio C Hamano1a4e8412005-12-27 08:17:231201you notice that the tip of your "upstream" tree has advanced
Junio C Hamanoba4b9282008-07-06 05:20:311202since you pulled from him:</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:231203<div class="listingblock">
1204<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:531205<pre><code>$ git fetch git://.... linus
1206$ LT=`git rev-parse FETCH_HEAD`</code></pre>
Junio C Hamano1a4e8412005-12-27 08:17:231207</div></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:391208<div class="paragraph"><p>Your work tree is still based on your HEAD ($JC), but you have
Junio C Hamano1a4e8412005-12-27 08:17:231209some edits since. Three-way merge makes sure that you have not
Junio C Hamano5fa6d1a2010-12-23 00:57:391210added or modified index entries since $JC, and if you haven&#8217;t,
Junio C Hamanoba4b9282008-07-06 05:20:311211then does the right thing. So with the following sequence:</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:231212<div class="listingblock">
1213<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:531214<pre><code>$ git read-tree -m -u `git merge-base $JC $LT` $JC $LT
Junio C Hamanofce7c7e2008-07-02 03:06:381215$ git merge-index git-merge-one-file -a
Junio C Hamano1a4e8412005-12-27 08:17:231216$ echo "Merge with Linus" | \
Junio C Hamanoc14e6ad2014-10-31 20:25:531217 git commit-tree `git write-tree` -p $JC -p $LT</code></pre>
Junio C Hamano1a4e8412005-12-27 08:17:231218</div></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:391219<div class="paragraph"><p>what you would commit is a pure merge between $JC and $LT without
Junio C Hamano1a4e8412005-12-27 08:17:231220your work-in-progress changes, and your work tree would be
Junio C Hamanoba4b9282008-07-06 05:20:311221updated to the result of the merge.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:391222<div class="paragraph"><p>However, if you have local changes in the working tree that
Junio C Hamano1aa40d22010-01-21 17:46:431223would be overwritten by this merge, <em>git read-tree</em> will refuse
Junio C Hamanoba4b9282008-07-06 05:20:311224to run to prevent your changes from being lost.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:391225<div class="paragraph"><p>In other words, there is no need to worry about what exists only
Junio C Hamano1a4e8412005-12-27 08:17:231226in the working tree. When you have local changes in a part of
1227the project that is not involved in the merge, your changes do
1228not interfere with the merge, and are kept intact. When they
Junio C Hamano1aa40d22010-01-21 17:46:431229<strong>do</strong> interfere, the merge does not even start (<em>git read-tree</em>
Junio C Hamano1a4e8412005-12-27 08:17:231230complains loudly and fails without modifying anything). In such
1231a case, you can simply continue doing what you were in the
1232middle of doing, and when your working tree is ready (i.e. you
Junio C Hamanoba4b9282008-07-06 05:20:311233have finished your work-in-progress), attempt the merge again.</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:231234</div>
Junio C Hamano9d971152012-12-19 00:43:111235</div>
1236</div>
1237<div class="sect1">
Junio C Hamano3c8d6702010-01-13 23:09:031238<h2 id="_sparse_checkout">Sparse checkout</h2>
1239<div class="sectionbody">
Junio C Hamano8fb66e52011-10-05 20:59:511240<div class="paragraph"><p>"Sparse checkout" allows populating the working directory sparsely.
Junio C Hamanoa28a9202012-06-21 07:08:231241It uses the skip-worktree bit (see <a href="git-update-index.html">git-update-index(1)</a>) to tell
Junio C Hamano8fb66e52011-10-05 20:59:511242Git whether a file in the working directory is worth looking at.</p></div>
1243<div class="paragraph"><p><em>git read-tree</em> and other merge-based commands (<em>git merge</em>, <em>git
1244checkout</em>&#8230;) can help maintaining the skip-worktree bitmap and working
Junio C Hamanoc14e6ad2014-10-31 20:25:531245directory update. <code>$GIT_DIR/info/sparse-checkout</code> is used to
Junio C Hamano8fb66e52011-10-05 20:59:511246define the skip-worktree reference bitmap. When <em>git read-tree</em> needs
1247to update the working directory, it resets the skip-worktree bit in the index
Junio C Hamano3c8d6702010-01-13 23:09:031248based on this file, which uses the same syntax as .gitignore files.
Junio C Hamano8fb66e52011-10-05 20:59:511249If an entry matches a pattern in this file, skip-worktree will not be
1250set on that entry. Otherwise, skip-worktree will be set.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:391251<div class="paragraph"><p>Then it compares the new skip-worktree value with the previous one. If
Junio C Hamano8fb66e52011-10-05 20:59:511252skip-worktree turns from set to unset, it will add the corresponding
1253file back. If it turns from unset to set, that file will be removed.</p></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:531254<div class="paragraph"><p>While <code>$GIT_DIR/info/sparse-checkout</code> is usually used to specify what
Junio C Hamano8fb66e52011-10-05 20:59:511255files are in, you can also specify what files are <em>not</em> in, using
Junio C Hamanoc14e6ad2014-10-31 20:25:531256negate patterns. For example, to remove the file <code>unwanted</code>:</p></div>
Junio C Hamano3c8d6702010-01-13 23:09:031257<div class="listingblock">
1258<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:531259<pre><code>/*
1260!unwanted</code></pre>
Junio C Hamano3c8d6702010-01-13 23:09:031261</div></div>
Junio C Hamano8fb66e52011-10-05 20:59:511262<div class="paragraph"><p>Another tricky thing is fully repopulating the working directory when you
Junio C Hamano3c8d6702010-01-13 23:09:031263no longer want sparse checkout. You cannot just disable "sparse
Junio C Hamano8fb66e52011-10-05 20:59:511264checkout" because skip-worktree bits are still in the index and your working
1265directory is still sparsely populated. You should re-populate the working
Junio C Hamanoc14e6ad2014-10-31 20:25:531266directory with the <code>$GIT_DIR/info/sparse-checkout</code> file content as
Junio C Hamano3c8d6702010-01-13 23:09:031267follows:</p></div>
1268<div class="listingblock">
1269<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:531270<pre><code>/*</code></pre>
Junio C Hamano3c8d6702010-01-13 23:09:031271</div></div>
Junio C Hamano8fb66e52011-10-05 20:59:511272<div class="paragraph"><p>Then you can disable sparse checkout. Sparse checkout support in <em>git
1273read-tree</em> and similar commands is disabled by default. You need to
Junio C Hamanoc14e6ad2014-10-31 20:25:531274turn <code>core.sparseCheckout</code> on in order to have sparse checkout
Junio C Hamano3c8d6702010-01-13 23:09:031275support.</p></div>
1276</div>
Junio C Hamano9d971152012-12-19 00:43:111277</div>
1278<div class="sect1">
Junio C Hamanoba4b9282008-07-06 05:20:311279<h2 id="_see_also">SEE ALSO</h2>
Junio C Hamano1a4e8412005-12-27 08:17:231280<div class="sectionbody">
Junio C Hamanoa28a9202012-06-21 07:08:231281<div class="paragraph"><p><a href="git-write-tree.html">git-write-tree(1)</a>; <a href="git-ls-files.html">git-ls-files(1)</a>;
1282<a href="gitignore.html">gitignore(5)</a></p></div>
Junio C Hamano1a4e8412005-12-27 08:17:231283</div>
Junio C Hamano9d971152012-12-19 00:43:111284</div>
1285<div class="sect1">
Junio C Hamanoba4b9282008-07-06 05:20:311286<h2 id="_git">GIT</h2>
Junio C Hamano1a4e8412005-12-27 08:17:231287<div class="sectionbody">
Junio C Hamanoa28a9202012-06-21 07:08:231288<div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:231289</div>
Junio C Hamano7bd050f2011-09-22 06:32:221290</div>
Junio C Hamano9d971152012-12-19 00:43:111291</div>
Junio C Hamano7bd050f2011-09-22 06:32:221292<div id="footnotes"><hr /></div>
Junio C Hamano1a4e8412005-12-27 08:17:231293<div id="footer">
1294<div id="footer-text">
Junio C Hamano2ef0ba32018-01-26 23:13:531295Last updated
1296 2018-01-26 15:11:04 PST
Junio C Hamano1a4e8412005-12-27 08:17:231297</div>
1298</div>
1299</body>
1300</html>