Google Git
Sign in
chromium / external / gitster / git-htmldocs / 4fd24422bd6290e0c8fce4a22cb9612a23e7e349 / . / git-read-tree.html
blob: b127622b5ef9e2171c6f10ef2e632b508dd3802f [file] [log] [blame]
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]6<meta name="generator" content="AsciiDoc 8.5.2" />
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]7<title>git-read-tree(1)</title>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]8<style type="text/css">
9/* Debug borders */
10p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
11/*
12 border: 1px solid red;
13*/
14}
15
16body {
17 margin: 1em 5% 1em 5%;
18}
19
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]20a {
21 color: blue;
22 text-decoration: underline;
23}
24a:visited {
25 color: fuchsia;
26}
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]27
28em {
29 font-style: italic;
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]30 color: navy;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]31}
32
33strong {
34 font-weight: bold;
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]35 color: #083194;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]36}
37
38tt {
39 color: navy;
40}
41
42h1, h2, h3, h4, h5, h6 {
43 color: #527bbd;
44 font-family: sans-serif;
45 margin-top: 1.2em;
46 margin-bottom: 0.5em;
47 line-height: 1.3;
48}
49
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]50h1, h2, h3 {
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]51 border-bottom: 2px solid silver;
52}
53h2 {
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]54 padding-top: 0.5em;
55}
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]56h3 {
57 float: left;
58}
59h3 + * {
60 clear: left;
61}
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]62
63div.sectionbody {
64 font-family: serif;
65 margin-left: 0;
66}
67
68hr {
69 border: 1px solid silver;
70}
71
72p {
73 margin-top: 0.5em;
74 margin-bottom: 0.5em;
75}
76
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]77ul, ol, li > p {
78 margin-top: 0;
79}
80
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]81pre {
82 padding: 0;
83 margin: 0;
84}
85
86span#author {
87 color: #527bbd;
88 font-family: sans-serif;
89 font-weight: bold;
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]90 font-size: 1.1em;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]91}
92span#email {
93}
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]94span#revnumber, span#revdate, span#revremark {
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]95 font-family: sans-serif;
96}
97
98div#footer {
99 font-family: sans-serif;
100 font-size: small;
101 border-top: 2px solid silver;
102 padding-top: 0.5em;
103 margin-top: 4.0em;
104}
105div#footer-text {
106 float: left;
107 padding-bottom: 0.5em;
108}
109div#footer-badges {
110 float: right;
111 padding-bottom: 0.5em;
112}
113
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]114div#preamble {
115 margin-top: 1.5em;
116 margin-bottom: 1.5em;
117}
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]118div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
119div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
120div.admonitionblock {
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]121 margin-top: 1.0em;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]122 margin-bottom: 1.5em;
123}
124div.admonitionblock {
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]125 margin-top: 2.0em;
126 margin-bottom: 2.0em;
127 margin-right: 10%;
128 color: #606060;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]129}
130
131div.content { /* Block element content. */
132 padding: 0;
133}
134
135/* Block element titles. */
136div.title, caption.title {
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]137 color: #527bbd;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]138 font-family: sans-serif;
139 font-weight: bold;
140 text-align: left;
141 margin-top: 1.0em;
142 margin-bottom: 0.5em;
143}
144div.title + * {
145 margin-top: 0;
146}
147
148td div.title:first-child {
149 margin-top: 0.0em;
150}
151div.content div.title:first-child {
152 margin-top: 0.0em;
153}
154div.content + div.title {
155 margin-top: 0.0em;
156}
157
158div.sidebarblock > div.content {
159 background: #ffffee;
160 border: 1px solid silver;
161 padding: 0.5em;
162}
163
164div.listingblock > div.content {
165 border: 1px solid silver;
166 background: #f4f4f4;
167 padding: 0.5em;
168}
169
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]170div.quoteblock, div.verseblock {
171 padding-left: 1.0em;
172 margin-left: 1.0em;
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]173 margin-right: 10%;
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]174 border-left: 5px solid #dddddd;
175 color: #777777;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]176}
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]177
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]178div.quoteblock > div.attribution {
179 padding-top: 0.5em;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]180 text-align: right;
181}
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]182
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]183div.verseblock > div.content {
184 white-space: pre;
185}
186div.verseblock > div.attribution {
187 padding-top: 0.75em;
188 text-align: left;
189}
190/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]191div.verseblock + div.attribution {
192 text-align: left;
193}
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]194
195div.admonitionblock .icon {
196 vertical-align: top;
197 font-size: 1.1em;
198 font-weight: bold;
199 text-decoration: underline;
200 color: #527bbd;
201 padding-right: 0.5em;
202}
203div.admonitionblock td.content {
204 padding-left: 0.5em;
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]205 border-left: 3px solid #dddddd;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]206}
207
208div.exampleblock > div.content {
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]209 border-left: 3px solid #dddddd;
210 padding-left: 0.5em;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]211}
212
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]213div.imageblock div.content { padding-left: 0; }
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]214span.image img { border-style: none; }
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]215a.image:visited { color: white; }
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]216
217dl {
218 margin-top: 0.8em;
219 margin-bottom: 0.8em;
220}
221dt {
222 margin-top: 0.5em;
223 margin-bottom: 0;
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]224 font-style: normal;
225 color: navy;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]226}
227dd > *:first-child {
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]228 margin-top: 0.1em;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]229}
230
231ul, ol {
232 list-style-position: outside;
233}
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]234ol.arabic {
235 list-style-type: decimal;
236}
237ol.loweralpha {
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]238 list-style-type: lower-alpha;
239}
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]240ol.upperalpha {
241 list-style-type: upper-alpha;
242}
243ol.lowerroman {
244 list-style-type: lower-roman;
245}
246ol.upperroman {
247 list-style-type: upper-roman;
248}
249
250div.compact ul, div.compact ol,
251div.compact p, div.compact p,
252div.compact div, div.compact div {
253 margin-top: 0.1em;
254 margin-bottom: 0.1em;
255}
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]256
257div.tableblock > table {
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]258 border: 3px solid #527bbd;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]259}
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]260thead, p.table.header {
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]261 font-family: sans-serif;
262 font-weight: bold;
263}
264tfoot {
265 font-weight: bold;
266}
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]267td > div.verse {
268 white-space: pre;
269}
270p.table {
271 margin-top: 0;
272}
273/* Because the table frame attribute is overriden by CSS in most browsers. */
274div.tableblock > table[frame="void"] {
275 border-style: none;
276}
277div.tableblock > table[frame="hsides"] {
278 border-left-style: none;
279 border-right-style: none;
280}
281div.tableblock > table[frame="vsides"] {
282 border-top-style: none;
283 border-bottom-style: none;
284}
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]285
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]286
287div.hdlist {
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]288 margin-top: 0.8em;
289 margin-bottom: 0.8em;
290}
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]291div.hdlist tr {
292 padding-bottom: 15px;
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]293}
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]294dt.hdlist1.strong, td.hdlist1.strong {
295 font-weight: bold;
296}
297td.hdlist1 {
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]298 vertical-align: top;
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]299 font-style: normal;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]300 padding-right: 0.8em;
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]301 color: navy;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]302}
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]303td.hdlist2 {
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]304 vertical-align: top;
305}
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]306div.hdlist.compact tr {
307 margin: 0;
308 padding-bottom: 0;
309}
310
311.comment {
312 background: yellow;
313}
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]314
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]315.footnote, .footnoteref {
316 font-size: 0.8em;
317}
318
319span.footnote, span.footnoteref {
320 vertical-align: super;
321}
322
323#footnotes {
324 margin: 20px 0 20px 0;
325 padding: 7px 0 0 0;
326}
327
328#footnotes div.footnote {
329 margin: 0 0 5px 0;
330}
331
332#footnotes hr {
333 border: none;
334 border-top: 1px solid silver;
335 height: 1px;
336 text-align: left;
337 margin-left: 0;
338 width: 20%;
339 min-width: 100px;
340}
341
342
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]343@media print {
344 div#footer-badges { display: none; }
345}
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]346
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]347div#toc {
348 margin-bottom: 2.5em;
349}
350
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]351div#toctitle {
352 color: #527bbd;
353 font-family: sans-serif;
354 font-size: 1.1em;
355 font-weight: bold;
356 margin-top: 1.0em;
357 margin-bottom: 0.1em;
358}
359
360div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
361 margin-top: 0;
362 margin-bottom: 0;
363}
364div.toclevel2 {
365 margin-left: 2em;
366 font-size: 0.9em;
367}
368div.toclevel3 {
369 margin-left: 4em;
370 font-size: 0.9em;
371}
372div.toclevel4 {
373 margin-left: 6em;
374 font-size: 0.9em;
375}
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]376/* Overrides for manpage documents */
377h1 {
378 padding-top: 0.5em;
379 padding-bottom: 0.5em;
380 border-top: 2px solid silver;
381 border-bottom: 2px solid silver;
382}
383h2 {
384 border-style: none;
385}
386div.sectionbody {
387 margin-left: 5%;
388}
389
390@media print {
391 div#toc { display: none; }
392}
393
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]394/* Workarounds for IE6's broken and incomplete CSS2. */
395
396div.sidebar-content {
397 background: #ffffee;
398 border: 1px solid silver;
399 padding: 0.5em;
400}
401div.sidebar-title, div.image-title {
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]402 color: #527bbd;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]403 font-family: sans-serif;
404 font-weight: bold;
405 margin-top: 0.0em;
406 margin-bottom: 0.5em;
407}
408
409div.listingblock div.content {
410 border: 1px solid silver;
411 background: #f4f4f4;
412 padding: 0.5em;
413}
414
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]415div.quoteblock-attribution {
416 padding-top: 0.5em;
417 text-align: right;
418}
419
420div.verseblock-content {
421 white-space: pre;
422}
423div.verseblock-attribution {
424 padding-top: 0.75em;
425 text-align: left;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]426}
427
428div.exampleblock-content {
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]429 border-left: 3px solid #dddddd;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]430 padding-left: 0.5em;
431}
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]432
433/* IE6 sets dynamically generated links as visited. */
434div#toc a:visited { color: blue; }
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]435</style>
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]436<script type="text/javascript">
437/*<![CDATA[*/
438window.onload = function(){asciidoc.footnotes();}
439var asciidoc = { // Namespace.
440
441/////////////////////////////////////////////////////////////////////
442// Table Of Contents generator
443/////////////////////////////////////////////////////////////////////
444
445/* Author: Mihai Bazon, September 2002
446 * http://students.infoiasi.ro/~mishoo
447 *
448 * Table Of Content generator
449 * Version: 0.4
450 *
451 * Feel free to use this script under the terms of the GNU General Public
452 * License, as long as you do not remove or alter this notice.
453 */
454
455 /* modified by Troy D. Hanson, September 2006. License: GPL */
456 /* modified by Stuart Rackham, 2006, 2009. License: GPL */
457
458// toclevels = 1..4.
459toc: function (toclevels) {
460
461 function getText(el) {
462 var text = "";
463 for (var i = el.firstChild; i != null; i = i.nextSibling) {
464 if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
465 text += i.data;
466 else if (i.firstChild != null)
467 text += getText(i);
468 }
469 return text;
470 }
471
472 function TocEntry(el, text, toclevel) {
473 this.element = el;
474 this.text = text;
475 this.toclevel = toclevel;
476 }
477
478 function tocEntries(el, toclevels) {
479 var result = new Array;
480 var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
481 // Function that scans the DOM tree for header elements (the DOM2
482 // nodeIterator API would be a better technique but not supported by all
483 // browsers).
484 var iterate = function (el) {
485 for (var i = el.firstChild; i != null; i = i.nextSibling) {
486 if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
487 var mo = re.exec(i.tagName);
488 if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
489 result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
490 }
491 iterate(i);
492 }
493 }
494 }
495 iterate(el);
496 return result;
497 }
498
499 var toc = document.getElementById("toc");
500 var entries = tocEntries(document.getElementById("content"), toclevels);
501 for (var i = 0; i < entries.length; ++i) {
502 var entry = entries[i];
503 if (entry.element.id == "")
504 entry.element.id = "_toc_" + i;
505 var a = document.createElement("a");
506 a.href = "#" + entry.element.id;
507 a.appendChild(document.createTextNode(entry.text));
508 var div = document.createElement("div");
509 div.appendChild(a);
510 div.className = "toclevel" + entry.toclevel;
511 toc.appendChild(div);
512 }
513 if (entries.length == 0)
514 toc.parentNode.removeChild(toc);
515},
516
517
518/////////////////////////////////////////////////////////////////////
519// Footnotes generator
520/////////////////////////////////////////////////////////////////////
521
522/* Based on footnote generation code from:
523 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
524 */
525
526footnotes: function () {
527 var cont = document.getElementById("content");
528 var noteholder = document.getElementById("footnotes");
529 var spans = cont.getElementsByTagName("span");
530 var refs = {};
531 var n = 0;
532 for (i=0; i<spans.length; i++) {
533 if (spans[i].className == "footnote") {
534 n++;
535 // Use [\s\S] in place of . so multi-line matches work.
536 // Because JavaScript has no s (dotall) regex flag.
537 note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
538 noteholder.innerHTML +=
539 "<div class='footnote' id='_footnote_" + n + "'>" +
540 "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
541 n + "</a>. " + note + "</div>";
542 spans[i].innerHTML =
543 "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
544 "' title='View footnote' class='footnote'>" + n + "</a>]";
545 var id =spans[i].getAttribute("id");
546 if (id != null) refs["#"+id] = n;
547 }
548 }
549 if (n == 0)
550 noteholder.parentNode.removeChild(noteholder);
551 else {
552 // Process footnoterefs.
553 for (i=0; i<spans.length; i++) {
554 if (spans[i].className == "footnoteref") {
555 var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
556 href = href.match(/#.*/)[0]; // Because IE return full URL.
557 n = refs[href];
558 spans[i].innerHTML =
559 "[<a href='#_footnote_" + n +
560 "' title='View footnote' class='footnote'>" + n + "</a>]";
561 }
562 }
563 }
564}
565
566}
567/*]]>*/
568</script>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]569</head>
570<body>
571<div id="header">
572<h1>
573git-read-tree(1) Manual Page
574</h1>
575<h2>NAME</h2>
576<div class="sectionbody">
577<p>git-read-tree -
578 Reads tree information into the index
579</p>
580</div>
581</div>
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]582<div id="content">
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]583<h2 id="_synopsis">SYNOPSIS</h2>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]584<div class="sectionbody">
Junio C Hamano15567bc2011-07-23 00:51:59[diff] [blame]585<div class="verseblock">
586<div class="verseblock-content"><em>git read-tree</em> [[-m [--trivial] [--aggressive] | --reset | --prefix=&lt;prefix&gt;]
Junio C Hamanofd9274d2009-08-05 21:21:39[diff] [blame]587 [-u [--exclude-per-directory=&lt;gitignore&gt;] | -i]]
Junio C Hamano3c8d6702010-01-13 23:09:03[diff] [blame]588 [--index-output=&lt;file&gt;] [--no-sparse-checkout]
Junio C Hamano15567bc2011-07-23 00:51:59[diff] [blame]589 (--empty | &lt;tree-ish1&gt; [&lt;tree-ish2&gt; [&lt;tree-ish3&gt;]])</div>
590<div class="verseblock-attribution">
591</div></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]592</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]593<h2 id="_description">DESCRIPTION</h2>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]594<div class="sectionbody">
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]595<div class="paragraph"><p>Reads the tree information given by &lt;tree-ish&gt; into the index,
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]596but does not actually <strong>update</strong> any of the files it "caches". (see:
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]597<a href="git-checkout-index.html">git-checkout-index(1)</a>)</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]598<div class="paragraph"><p>Optionally, it can merge a tree into the index, perform a
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]599fast-forward (i.e. 2-way) merge, or a 3-way merge, with the <tt>-m</tt>
600flag. When used with <tt>-m</tt>, the <tt>-u</tt> flag causes it to also update
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]601the files in the work tree with the result of the merge.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]602<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:43[diff] [blame]603will be in unmerged state when <em>git read-tree</em> returns.</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]604</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]605<h2 id="_options">OPTIONS</h2>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]606<div class="sectionbody">
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]607<div class="dlist"><dl>
608<dt class="hdlist1">
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]609-m
610</dt>
611<dd>
612<p>
613 Perform a merge, not just a read. The command will
614 refuse to run if your index file has unmerged entries,
615 indicating that you have not finished previous merge you
616 started.
617</p>
618</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]619<dt class="hdlist1">
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]620--reset
621</dt>
622<dd>
623<p>
624 Same as -m, except that unmerged entries are discarded
625 instead of failing.
626</p>
627</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]628<dt class="hdlist1">
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]629-u
630</dt>
631<dd>
632<p>
633 After a successful merge, update the files in the work
634 tree with the result of the merge.
635</p>
636</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]637<dt class="hdlist1">
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]638-i
639</dt>
640<dd>
641<p>
642 Usually a merge requires the index file as well as the
Junio C Hamano8fb66e52011-10-05 20:59:51[diff] [blame]643 files in the working tree to be up to date with the
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]644 current head commit, in order not to lose local
645 changes. This flag disables the check with the working
646 tree and is meant to be used when creating a merge of
647 trees that are not directly related to the current
648 working tree status into a temporary index file.
649</p>
650</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]651<dt class="hdlist1">
Junio C Hamanoef5a2f92011-05-31 19:53:33[diff] [blame]652-n
653</dt>
654<dt class="hdlist1">
655--dry-run
656</dt>
657<dd>
658<p>
659 Check if the command would error out, without updating the index
660 nor the files in the working tree for real.
661</p>
662</dd>
663<dt class="hdlist1">
Junio C Hamano0a18b352008-06-10 04:10:25[diff] [blame]664-v
665</dt>
666<dd>
667<p>
668 Show the progress of checking files out.
669</p>
670</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]671<dt class="hdlist1">
Junio C Hamanoee695f22007-06-21 00:35:36[diff] [blame]672--trivial
673</dt>
674<dd>
675<p>
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]676 Restrict three-way merge by <em>git read-tree</em> to happen
Junio C Hamanoee695f22007-06-21 00:35:36[diff] [blame]677 only if there is no file-level merging required, instead
678 of resolving merge for trivial cases and leaving
679 conflicting files unresolved in the index.
680</p>
681</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]682<dt class="hdlist1">
Junio C Hamano5f327762006-03-02 09:14:51[diff] [blame]683--aggressive
684</dt>
685<dd>
686<p>
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]687 Usually a three-way merge by <em>git read-tree</em> resolves
Junio C Hamano5f327762006-03-02 09:14:51[diff] [blame]688 the merge for really trivial cases and leaves other
Junio C Hamano8fb66e52011-10-05 20:59:51[diff] [blame]689 cases unresolved in the index, so that porcelains can
Junio C Hamano5f327762006-03-02 09:14:51[diff] [blame]690 implement different merge policies. This flag makes the
Junio C Hamano8fb66e52011-10-05 20:59:51[diff] [blame]691 command resolve a few more cases internally:
Junio C Hamano5f327762006-03-02 09:14:51[diff] [blame]692</p>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]693<div class="ulist"><ul>
Junio C Hamano5f327762006-03-02 09:14:51[diff] [blame]694<li>
695<p>
696when one side removes a path and the other side leaves the path
697 unmodified. The resolution is to remove that path.
698</p>
699</li>
700<li>
701<p>
702when both sides remove a path. The resolution is to remove that path.
703</p>
704</li>
705<li>
706<p>
Junio C Hamano8fb66e52011-10-05 20:59:51[diff] [blame]707when both sides add a path identically. The resolution
Junio C Hamano5f327762006-03-02 09:14:51[diff] [blame]708 is to add that path.
709</p>
710</li>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]711</ul></div>
Junio C Hamano5f327762006-03-02 09:14:51[diff] [blame]712</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]713<dt class="hdlist1">
Junio C Hamanoad8c6432006-06-18 09:26:43[diff] [blame]714--prefix=&lt;prefix&gt;/
715</dt>
716<dd>
717<p>
718 Keep the current index contents, and read the contents
Junio C Hamanodb472bc2012-01-04 00:22:37[diff] [blame]719 of the named tree-ish under the directory at <tt>&lt;prefix&gt;</tt>.
720 The command will refuse to overwrite entries that already
721 existed in the original index file. Note that the <tt>&lt;prefix&gt;/</tt>
722 value must end with a slash.
Junio C Hamanoad8c6432006-06-18 09:26:43[diff] [blame]723</p>
724</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]725<dt class="hdlist1">
Junio C Hamanoe7935c42006-12-13 21:32:17[diff] [blame]726--exclude-per-directory=&lt;gitignore&gt;
727</dt>
728<dd>
729<p>
730 When running the command with <tt>-u</tt> and <tt>-m</tt> options, the
731 merge result may need to overwrite paths that are not
732 tracked in the current branch. The command usually
733 refuses to proceed with the merge to avoid losing such a
734 path. However this safety valve sometimes gets in the
735 way. For example, it often happens that the other
736 branch added a file that used to be a generated file in
737 your branch, and the safety valve triggers when you try
738 to switch to that branch after you ran <tt>make</tt> but before
739 running <tt>make clean</tt> to remove the generated file. This
740 option tells the command to read per-directory exclude
741 file (usually <em>.gitignore</em>) and allows such an untracked
742 but explicitly ignored file to be overwritten.
743</p>
744</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]745<dt class="hdlist1">
Junio C Hamano12a3a232007-04-07 10:18:10[diff] [blame]746--index-output=&lt;file&gt;
747</dt>
748<dd>
749<p>
750 Instead of writing the results out to <tt>$GIT_INDEX_FILE</tt>,
751 write the resulting index in the named file. While the
752 command is operating, the original index file is locked
753 with the same mechanism as usual. The file must allow
754 to be rename(2)ed into from a temporary file that is
755 created next to the usual index file; typically this
756 means it needs to be on the same filesystem as the index
757 file itself, and you need write permission to the
758 directories the index file and index output file are
759 located in.
760</p>
761</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]762<dt class="hdlist1">
Junio C Hamano3c8d6702010-01-13 23:09:03[diff] [blame]763--no-sparse-checkout
764</dt>
765<dd>
766<p>
767 Disable sparse checkout support even if <tt>core.sparseCheckout</tt>
768 is true.
769</p>
770</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]771<dt class="hdlist1">
Junio C Hamano3b4609d2010-09-30 00:04:34[diff] [blame]772--empty
773</dt>
774<dd>
775<p>
776 Instead of reading tree object(s) into the index, just empty
777 it.
778</p>
779</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]780<dt class="hdlist1">
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]781&lt;tree-ish#&gt;
782</dt>
783<dd>
784<p>
785 The id of the tree object(s) to be read/merged.
786</p>
787</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]788</dl></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]789</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]790<h2 id="_merging">Merging</h2>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]791<div class="sectionbody">
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]792<div class="paragraph"><p>If <tt>-m</tt> is specified, <em>git read-tree</em> can perform 3 kinds of
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]793merge, a single tree merge if only 1 tree is given, a
794fast-forward merge with 2 trees, or a 3-way merge if 3 trees are
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]795provided.</p></div>
796<h3 id="_single_tree_merge">Single Tree Merge</h3><div style="clear:left"></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]797<div class="paragraph"><p>If only 1 tree is specified, <em>git read-tree</em> operates as if the user did not
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]798specify <tt>-m</tt>, except that if the original index has an entry for a
Junio C Hamanoae2dfa82010-03-17 05:41:52[diff] [blame]799given pathname, and the contents of the path match with the tree
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]800being read, the stat info from the index is used. (In other words, the
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]801index&#8217;s stat()s take precedence over the merged tree&#8217;s).</p></div>
802<div class="paragraph"><p>That means that if you do a <tt>git read-tree -m &lt;newtree&gt;</tt> followed by a
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]803<tt>git checkout-index -f -u -a</tt>, the <em>git checkout-index</em> only checks out
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]804the stuff that really changed.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]805<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:43[diff] [blame]806run after <em>git read-tree</em>.</p></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]807<h3 id="_two_tree_merge">Two Tree Merge</h3><div style="clear:left"></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]808<div class="paragraph"><p>Typically, this is invoked as <tt>git read-tree -m $H $M</tt>, where $H
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]809is the head commit of the current repository, and $M is the head
810of a foreign tree, which is simply ahead of $H (i.e. we are in a
Junio C Hamano3f680f32009-11-16 02:10:54[diff] [blame]811fast-forward situation).</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]812<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:31[diff] [blame]813the following:</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]814<div class="olist arabic"><ol class="arabic">
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]815<li>
816<p>
817The current index and work tree is derived from $H, but
Junio C Hamanoae2dfa82010-03-17 05:41:52[diff] [blame]818 the user may have local changes in them since $H.
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]819</p>
820</li>
821<li>
822<p>
823The user wants to fast-forward to $M.
824</p>
825</li>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]826</ol></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]827<div class="paragraph"><p>In this case, the <tt>git read-tree -m $H $M</tt> command makes sure
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]828that no local change is lost as the result of this "merge".
Junio C Hamanoae2dfa82010-03-17 05:41:52[diff] [blame]829Here are the "carry forward" rules, where "I" denotes the index,
830"clean" means that index and work tree coincide, and "exists"/"nothing"
831refer to the presence of a path in the specified commit:</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]832<div class="literalblock">
833<div class="content">
Junio C Hamanoae2dfa82010-03-17 05:41:52[diff] [blame]834<pre><tt> I H M Result
835 -------------------------------------------------------
8360 nothing nothing nothing (does not happen)
8371 nothing nothing exists use M
8382 nothing exists nothing remove path from index
8393 nothing exists exists, use M if "initial checkout",
840 H == M keep index otherwise
841 exists, fail
842 H != M</tt></pre>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]843</div></div>
844<div class="literalblock">
845<div class="content">
Junio C Hamanoae2dfa82010-03-17 05:41:52[diff] [blame]846<pre><tt> clean I==H I==M
847 ------------------
8484 yes N/A N/A nothing nothing keep index
8495 no N/A N/A nothing nothing keep index</tt></pre>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]850</div></div>
851<div class="literalblock">
852<div class="content">
Junio C Hamanoae2dfa82010-03-17 05:41:52[diff] [blame]853<pre><tt>6 yes N/A yes nothing exists keep index
8547 no N/A yes nothing exists keep index
8558 yes N/A no nothing exists fail
8569 no N/A no nothing exists fail</tt></pre>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]857</div></div>
858<div class="literalblock">
859<div class="content">
860<pre><tt>10 yes yes N/A exists nothing remove path from index
86111 no yes N/A exists nothing fail
86212 yes no N/A exists nothing fail
86313 no no N/A exists nothing fail</tt></pre>
864</div></div>
865<div class="literalblock">
866<div class="content">
Junio C Hamanoae2dfa82010-03-17 05:41:52[diff] [blame]867<pre><tt> clean (H==M)
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]868 ------
86914 yes exists exists keep index
87015 no exists exists keep index</tt></pre>
871</div></div>
872<div class="literalblock">
873<div class="content">
874<pre><tt> clean I==H I==M (H!=M)
875 ------------------
87616 yes no no exists exists fail
87717 no no no exists exists fail
87818 yes no yes exists exists keep index
87919 no no yes exists exists keep index
88020 yes yes no exists exists use M
88121 no yes no exists exists fail</tt></pre>
882</div></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]883<div class="paragraph"><p>In all "keep index" cases, the index entry stays as in the
Junio C Hamanoae2dfa82010-03-17 05:41:52[diff] [blame]884original index file. If the entry is not up to date,
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]885<em>git read-tree</em> keeps the copy in the work tree intact when
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]886operating under the -u flag.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]887<div class="paragraph"><p>When this form of <em>git read-tree</em> returns successfully, you can
Junio C Hamanoae2dfa82010-03-17 05:41:52[diff] [blame]888see which of the "local changes" that you made were carried forward by running
Junio C Hamanofce7c7e2008-07-02 03:06:38[diff] [blame]889<tt>git diff-index --cached $M</tt>. Note that this does not
Junio C Hamanoae2dfa82010-03-17 05:41:52[diff] [blame]890necessarily match what <tt>git diff-index --cached $H</tt> would have
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]891produced before such a two tree merge. This is because of cases
89218 and 19 --- if you already had the changes in $M (e.g. maybe
Junio C Hamanofce7c7e2008-07-02 03:06:38[diff] [blame]893you picked it up via e-mail in a patch form), <tt>git diff-index
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]894--cached $H</tt> would have told you about the change before this
Junio C Hamanofce7c7e2008-07-02 03:06:38[diff] [blame]895merge, but it would not show in <tt>git diff-index --cached $M</tt>
Junio C Hamanoae2dfa82010-03-17 05:41:52[diff] [blame]896output after the two-tree merge.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]897<div class="paragraph"><p>Case 3 is slightly tricky and needs explanation. The result from this
Junio C Hamano78ec2262008-09-16 19:17:31[diff] [blame]898rule logically should be to remove the path if the user staged the removal
Junio C Hamanoa476efa2008-10-10 15:31:42[diff] [blame]899of the path and then switching to a new branch. That however will prevent
Junio C Hamano78ec2262008-09-16 19:17:31[diff] [blame]900the initial checkout from happening, so the rule is modified to use M (new
Junio C Hamanoae2dfa82010-03-17 05:41:52[diff] [blame]901tree) only when the content of the index is empty. Otherwise the removal
Junio C Hamano78ec2262008-09-16 19:17:31[diff] [blame]902of the path is kept as long as $H and $M are the same.</p></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]903<h3 id="_3_way_merge">3-Way Merge</h3><div style="clear:left"></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]904<div class="paragraph"><p>Each "index" entry has two bits worth of "stage" state. stage 0 is the
905normal one, and is the only one you&#8217;d see in any kind of normal use.</p></div>
906<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:31[diff] [blame]907starts out at 1.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]908<div class="paragraph"><p>This means that you can do</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]909<div class="listingblock">
910<div class="content">
Junio C Hamanofce7c7e2008-07-02 03:06:38[diff] [blame]911<pre><tt>$ git read-tree -m &lt;tree1&gt; &lt;tree2&gt; &lt;tree3&gt;</tt></pre>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]912</div></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]913<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:23[diff] [blame]914"stage1", all of the &lt;tree2&gt; entries in "stage2" and all of the
915&lt;tree3&gt; entries in "stage3". When performing a merge of another
916branch into the current branch, we use the common ancestor tree
917as &lt;tree1&gt;, the current branch head as &lt;tree2&gt;, and the other
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]918branch head as &lt;tree3&gt;.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]919<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:23[diff] [blame]920a file that matches in all respects in the following states, it
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]921"collapses" back to "stage0":</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]922<div class="ulist"><ul>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]923<li>
924<p>
925stage 2 and 3 are the same; take one or the other (it makes no
926 difference - the same work has been done on our branch in
927 stage 2 and their branch in stage 3)
928</p>
929</li>
930<li>
931<p>
932stage 1 and stage 2 are the same and stage 3 is different; take
933 stage 3 (our branch in stage 2 did not do anything since the
934 ancestor in stage 1 while their branch in stage 3 worked on
935 it)
936</p>
937</li>
938<li>
939<p>
940stage 1 and stage 3 are the same and stage 2 is different take
941 stage 2 (we did something while they did nothing)
942</p>
943</li>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]944</ul></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]945<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:23[diff] [blame]946will complain about unmerged entries if it sees a single entry that is not
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]947stage 0.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]948<div class="paragraph"><p>OK, this all sounds like a collection of totally nonsensical rules,
949but it&#8217;s actually exactly what you want in order to do a fast
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]950merge. The different stages represent the "result tree" (stage 0, aka
951"merged"), the original tree (stage 1, aka "orig"), and the two trees
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]952you are trying to merge (stage 2 and 3 respectively).</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]953<div class="paragraph"><p>The order of stages 1, 2 and 3 (hence the order of three
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]954&lt;tree-ish&gt; command line arguments) are significant when you
955start a 3-way merge with an index file that is already
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]956populated. Here is an outline of how the algorithm works:</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]957<div class="ulist"><ul>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]958<li>
959<p>
960if a file exists in identical format in all three trees, it will
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]961 automatically collapse to "merged" state by <em>git read-tree</em>.
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]962</p>
963</li>
964<li>
965<p>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]966a file that has <em>any</em> difference what-so-ever in the three trees
967 will stay as separate entries in the index. It&#8217;s up to "porcelain
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]968 policy" to determine how to remove the non-0 stages, and insert a
969 merged version.
970</p>
971</li>
972<li>
973<p>
974the index file saves and restores with all this information, so you
975 can merge things incrementally, but as long as it has entries in
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]976 stages 1/2/3 (i.e., "unmerged entries") you can&#8217;t write the result. So
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]977 now the merge algorithm ends up being really simple:
978</p>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]979<div class="ulist"><ul>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]980<li>
981<p>
982you walk the index in order, and ignore all entries of stage 0,
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]983 since they&#8217;ve already been done.
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]984</p>
985</li>
986<li>
987<p>
988if you find a "stage1", but no matching "stage2" or "stage3", you
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]989 know it&#8217;s been removed from both trees (it only existed in the
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]990 original tree), and you remove that entry.
991</p>
992</li>
993<li>
994<p>
995if you find a matching "stage2" and "stage3" tree, you remove one
996 of them, and turn the other into a "stage0" entry. Remove any
997 matching "stage1" entry if it exists too. .. all the normal
998 trivial rules ..
999</p>
1000</li>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1001</ul></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1002</li>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1003</ul></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]1004<div class="paragraph"><p>You would normally use <em>git merge-index</em> with supplied
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]1005<em>git merge-one-file</em> to do this last step. The script updates
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1006the files in the working tree as it merges each path and at the
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1007end of a successful merge.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]1008<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:23[diff] [blame]1009populated, it is assumed that it represents the state of the
1010files in your work tree, and you can even have files with
1011changes unrecorded in the index file. It is further assumed
1012that this state is "derived" from the stage 2 tree. The 3-way
1013merge refuses to run if it finds an entry in the original index
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1014file that does not match stage 2.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]1015<div class="paragraph"><p>This is done to prevent you from losing your work-in-progress
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1016changes, and mixing your random changes in an unrelated merge
1017commit. To illustrate, suppose you start from what has been
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1018committed last to your repository:</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1019<div class="listingblock">
1020<div class="content">
Junio C Hamanofce7c7e2008-07-02 03:06:38[diff] [blame]1021<pre><tt>$ JC=`git rev-parse --verify "HEAD^0"`
1022$ git checkout-index -f -u -a $JC</tt></pre>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1023</div></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]1024<div class="paragraph"><p>You do random edits, without running <em>git update-index</em>. And then
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1025you notice that the tip of your "upstream" tree has advanced
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1026since you pulled from him:</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1027<div class="listingblock">
1028<div class="content">
Junio C Hamanofce7c7e2008-07-02 03:06:38[diff] [blame]1029<pre><tt>$ git fetch git://.... linus
Junio C Hamano4fd24422012-01-06 21:52:43[diff] [blame^]1030$ LT=`git rev-parse FETCH_HEAD`</tt></pre>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1031</div></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]1032<div class="paragraph"><p>Your work tree is still based on your HEAD ($JC), but you have
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1033some edits since. Three-way merge makes sure that you have not
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]1034added or modified index entries since $JC, and if you haven&#8217;t,
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1035then does the right thing. So with the following sequence:</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1036<div class="listingblock">
1037<div class="content">
Junio C Hamanofce7c7e2008-07-02 03:06:38[diff] [blame]1038<pre><tt>$ git read-tree -m -u `git merge-base $JC $LT` $JC $LT
1039$ git merge-index git-merge-one-file -a
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1040$ echo "Merge with Linus" | \
Junio C Hamanofce7c7e2008-07-02 03:06:38[diff] [blame]1041 git commit-tree `git write-tree` -p $JC -p $LT</tt></pre>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1042</div></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]1043<div class="paragraph"><p>what you would commit is a pure merge between $JC and $LT without
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1044your work-in-progress changes, and your work tree would be
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1045updated to the result of the merge.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]1046<div class="paragraph"><p>However, if you have local changes in the working tree that
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]1047would be overwritten by this merge, <em>git read-tree</em> will refuse
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1048to run to prevent your changes from being lost.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]1049<div class="paragraph"><p>In other words, there is no need to worry about what exists only
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1050in the working tree. When you have local changes in a part of
1051the project that is not involved in the merge, your changes do
1052not interfere with the merge, and are kept intact. When they
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]1053<strong>do</strong> interfere, the merge does not even start (<em>git read-tree</em>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1054complains loudly and fails without modifying anything). In such
1055a case, you can simply continue doing what you were in the
1056middle of doing, and when your working tree is ready (i.e. you
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1057have finished your work-in-progress), attempt the merge again.</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1058</div>
Junio C Hamano3c8d6702010-01-13 23:09:03[diff] [blame]1059<h2 id="_sparse_checkout">Sparse checkout</h2>
1060<div class="sectionbody">
Junio C Hamano8fb66e52011-10-05 20:59:51[diff] [blame]1061<div class="paragraph"><p>"Sparse checkout" allows populating the working directory sparsely.
1062It uses the skip-worktree bit (see <a href="git-update-index.html">git-update-index(1)</a>) to tell
1063Git whether a file in the working directory is worth looking at.</p></div>
1064<div class="paragraph"><p><em>git read-tree</em> and other merge-based commands (<em>git merge</em>, <em>git
1065checkout</em>&#8230;) can help maintaining the skip-worktree bitmap and working
Junio C Hamano3c8d6702010-01-13 23:09:03[diff] [blame]1066directory update. <tt>$GIT_DIR/info/sparse-checkout</tt> is used to
Junio C Hamano8fb66e52011-10-05 20:59:51[diff] [blame]1067define the skip-worktree reference bitmap. When <em>git read-tree</em> needs
1068to update the working directory, it resets the skip-worktree bit in the index
Junio C Hamano3c8d6702010-01-13 23:09:03[diff] [blame]1069based on this file, which uses the same syntax as .gitignore files.
Junio C Hamano8fb66e52011-10-05 20:59:51[diff] [blame]1070If an entry matches a pattern in this file, skip-worktree will not be
1071set on that entry. Otherwise, skip-worktree will be set.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]1072<div class="paragraph"><p>Then it compares the new skip-worktree value with the previous one. If
Junio C Hamano8fb66e52011-10-05 20:59:51[diff] [blame]1073skip-worktree turns from set to unset, it will add the corresponding
1074file back. If it turns from unset to set, that file will be removed.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]1075<div class="paragraph"><p>While <tt>$GIT_DIR/info/sparse-checkout</tt> is usually used to specify what
Junio C Hamano8fb66e52011-10-05 20:59:51[diff] [blame]1076files are in, you can also specify what files are <em>not</em> in, using
1077negate patterns. For example, to remove the file <tt>unwanted</tt>:</p></div>
Junio C Hamano3c8d6702010-01-13 23:09:03[diff] [blame]1078<div class="listingblock">
1079<div class="content">
Junio C Hamano58700662011-10-10 23:42:27[diff] [blame]1080<pre><tt>/*
Junio C Hamano3c8d6702010-01-13 23:09:03[diff] [blame]1081!unwanted</tt></pre>
1082</div></div>
Junio C Hamano8fb66e52011-10-05 20:59:51[diff] [blame]1083<div class="paragraph"><p>Another tricky thing is fully repopulating the working directory when you
Junio C Hamano3c8d6702010-01-13 23:09:03[diff] [blame]1084no longer want sparse checkout. You cannot just disable "sparse
Junio C Hamano8fb66e52011-10-05 20:59:51[diff] [blame]1085checkout" because skip-worktree bits are still in the index and your working
1086directory is still sparsely populated. You should re-populate the working
Junio C Hamano3c8d6702010-01-13 23:09:03[diff] [blame]1087directory with the <tt>$GIT_DIR/info/sparse-checkout</tt> file content as
1088follows:</p></div>
1089<div class="listingblock">
1090<div class="content">
Junio C Hamano58700662011-10-10 23:42:27[diff] [blame]1091<pre><tt>/*</tt></pre>
Junio C Hamano3c8d6702010-01-13 23:09:03[diff] [blame]1092</div></div>
Junio C Hamano8fb66e52011-10-05 20:59:51[diff] [blame]1093<div class="paragraph"><p>Then you can disable sparse checkout. Sparse checkout support in <em>git
1094read-tree</em> and similar commands is disabled by default. You need to
Junio C Hamano3c8d6702010-01-13 23:09:03[diff] [blame]1095turn <tt>core.sparseCheckout</tt> on in order to have sparse checkout
1096support.</p></div>
1097</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1098<h2 id="_see_also">SEE ALSO</h2>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1099<div class="sectionbody">
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]1100<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>;
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1101<a href="gitignore.html">gitignore(5)</a></p></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1102</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1103<h2 id="_git">GIT</h2>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1104<div class="sectionbody">
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]1105<div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1106</div>
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]1107</div>
1108<div id="footnotes"><hr /></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1109<div id="footer">
1110<div id="footer-text">
Junio C Hamano4fd24422012-01-06 21:52:43[diff] [blame^]1111Last updated 2012-01-06 13:52:20 PDT
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1112</div>
1113</div>
1114</body>
1115</html>