Google Git
Sign in
chromium / external / gitster / git-htmldocs / a74e4c319c25bbf547ffb840f4e84d8e709291c5 / . / git-read-tree.html
blob: 4581d10b3383af5480ba38bd3c83269ee9bfb6b1 [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 Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]6<meta name="generator" content="AsciiDoc 8.4.5" />
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 Hamano1a4e8412005-12-27 08:17:23[diff] [blame]121 margin-top: 1.5em;
122 margin-bottom: 1.5em;
123}
124div.admonitionblock {
125 margin-top: 2.5em;
126 margin-bottom: 2.5em;
127}
128
129div.content { /* Block element content. */
130 padding: 0;
131}
132
133/* Block element titles. */
134div.title, caption.title {
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]135 color: #527bbd;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]136 font-family: sans-serif;
137 font-weight: bold;
138 text-align: left;
139 margin-top: 1.0em;
140 margin-bottom: 0.5em;
141}
142div.title + * {
143 margin-top: 0;
144}
145
146td div.title:first-child {
147 margin-top: 0.0em;
148}
149div.content div.title:first-child {
150 margin-top: 0.0em;
151}
152div.content + div.title {
153 margin-top: 0.0em;
154}
155
156div.sidebarblock > div.content {
157 background: #ffffee;
158 border: 1px solid silver;
159 padding: 0.5em;
160}
161
162div.listingblock > div.content {
163 border: 1px solid silver;
164 background: #f4f4f4;
165 padding: 0.5em;
166}
167
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]168div.quoteblock {
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]169 padding-left: 2.0em;
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]170 margin-right: 10%;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]171}
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]172div.quoteblock > div.attribution {
173 padding-top: 0.5em;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]174 text-align: right;
175}
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]176
177div.verseblock {
178 padding-left: 2.0em;
179 margin-right: 10%;
180}
181div.verseblock > div.content {
182 white-space: pre;
183}
184div.verseblock > div.attribution {
185 padding-top: 0.75em;
186 text-align: left;
187}
188/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]189div.verseblock + div.attribution {
190 text-align: left;
191}
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]192
193div.admonitionblock .icon {
194 vertical-align: top;
195 font-size: 1.1em;
196 font-weight: bold;
197 text-decoration: underline;
198 color: #527bbd;
199 padding-right: 0.5em;
200}
201div.admonitionblock td.content {
202 padding-left: 0.5em;
203 border-left: 2px solid silver;
204}
205
206div.exampleblock > div.content {
207 border-left: 2px solid silver;
208 padding: 0.5em;
209}
210
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]211div.imageblock div.content { padding-left: 0; }
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]212span.image img { border-style: none; }
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]213a.image:visited { color: white; }
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]214
215dl {
216 margin-top: 0.8em;
217 margin-bottom: 0.8em;
218}
219dt {
220 margin-top: 0.5em;
221 margin-bottom: 0;
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]222 font-style: normal;
223 color: navy;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]224}
225dd > *:first-child {
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]226 margin-top: 0.1em;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]227}
228
229ul, ol {
230 list-style-position: outside;
231}
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]232ol.arabic {
233 list-style-type: decimal;
234}
235ol.loweralpha {
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]236 list-style-type: lower-alpha;
237}
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]238ol.upperalpha {
239 list-style-type: upper-alpha;
240}
241ol.lowerroman {
242 list-style-type: lower-roman;
243}
244ol.upperroman {
245 list-style-type: upper-roman;
246}
247
248div.compact ul, div.compact ol,
249div.compact p, div.compact p,
250div.compact div, div.compact div {
251 margin-top: 0.1em;
252 margin-bottom: 0.1em;
253}
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]254
255div.tableblock > table {
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]256 border: 3px solid #527bbd;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]257}
258thead {
259 font-family: sans-serif;
260 font-weight: bold;
261}
262tfoot {
263 font-weight: bold;
264}
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]265td > div.verse {
266 white-space: pre;
267}
268p.table {
269 margin-top: 0;
270}
271/* Because the table frame attribute is overriden by CSS in most browsers. */
272div.tableblock > table[frame="void"] {
273 border-style: none;
274}
275div.tableblock > table[frame="hsides"] {
276 border-left-style: none;
277 border-right-style: none;
278}
279div.tableblock > table[frame="vsides"] {
280 border-top-style: none;
281 border-bottom-style: none;
282}
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]283
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]284
285div.hdlist {
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]286 margin-top: 0.8em;
287 margin-bottom: 0.8em;
288}
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]289div.hdlist tr {
290 padding-bottom: 15px;
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]291}
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]292dt.hdlist1.strong, td.hdlist1.strong {
293 font-weight: bold;
294}
295td.hdlist1 {
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]296 vertical-align: top;
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]297 font-style: normal;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]298 padding-right: 0.8em;
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]299 color: navy;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]300}
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]301td.hdlist2 {
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]302 vertical-align: top;
303}
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]304div.hdlist.compact tr {
305 margin: 0;
306 padding-bottom: 0;
307}
308
309.comment {
310 background: yellow;
311}
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]312
313@media print {
314 div#footer-badges { display: none; }
315}
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]316
317div#toctitle {
318 color: #527bbd;
319 font-family: sans-serif;
320 font-size: 1.1em;
321 font-weight: bold;
322 margin-top: 1.0em;
323 margin-bottom: 0.1em;
324}
325
326div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
327 margin-top: 0;
328 margin-bottom: 0;
329}
330div.toclevel2 {
331 margin-left: 2em;
332 font-size: 0.9em;
333}
334div.toclevel3 {
335 margin-left: 4em;
336 font-size: 0.9em;
337}
338div.toclevel4 {
339 margin-left: 6em;
340 font-size: 0.9em;
341}
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]342/* Overrides for manpage documents */
343h1 {
344 padding-top: 0.5em;
345 padding-bottom: 0.5em;
346 border-top: 2px solid silver;
347 border-bottom: 2px solid silver;
348}
349h2 {
350 border-style: none;
351}
352div.sectionbody {
353 margin-left: 5%;
354}
355
356@media print {
357 div#toc { display: none; }
358}
359
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]360/* Workarounds for IE6's broken and incomplete CSS2. */
361
362div.sidebar-content {
363 background: #ffffee;
364 border: 1px solid silver;
365 padding: 0.5em;
366}
367div.sidebar-title, div.image-title {
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]368 color: #527bbd;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]369 font-family: sans-serif;
370 font-weight: bold;
371 margin-top: 0.0em;
372 margin-bottom: 0.5em;
373}
374
375div.listingblock div.content {
376 border: 1px solid silver;
377 background: #f4f4f4;
378 padding: 0.5em;
379}
380
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]381div.quoteblock-attribution {
382 padding-top: 0.5em;
383 text-align: right;
384}
385
386div.verseblock-content {
387 white-space: pre;
388}
389div.verseblock-attribution {
390 padding-top: 0.75em;
391 text-align: left;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]392}
393
394div.exampleblock-content {
395 border-left: 2px solid silver;
396 padding-left: 0.5em;
397}
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]398
399/* IE6 sets dynamically generated links as visited. */
400div#toc a:visited { color: blue; }
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]401</style>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]402</head>
403<body>
404<div id="header">
405<h1>
406git-read-tree(1) Manual Page
407</h1>
408<h2>NAME</h2>
409<div class="sectionbody">
410<p>git-read-tree -
411 Reads tree information into the index
412</p>
413</div>
414</div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]415<h2 id="_synopsis">SYNOPSIS</h2>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]416<div class="sectionbody">
Junio C Hamano15567bc2011-07-23 00:51:59[diff] [blame]417<div class="verseblock">
418<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]419 [-u [--exclude-per-directory=&lt;gitignore&gt;] | -i]]
Junio C Hamano3c8d6702010-01-13 23:09:03[diff] [blame]420 [--index-output=&lt;file&gt;] [--no-sparse-checkout]
Junio C Hamano15567bc2011-07-23 00:51:59[diff] [blame]421 (--empty | &lt;tree-ish1&gt; [&lt;tree-ish2&gt; [&lt;tree-ish3&gt;]])</div>
422<div class="verseblock-attribution">
423</div></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]424</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]425<h2 id="_description">DESCRIPTION</h2>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]426<div class="sectionbody">
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]427<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]428but does not actually <strong>update</strong> any of the files it "caches". (see:
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]429<a href="git-checkout-index.html">git-checkout-index(1)</a>)</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]430<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]431fast-forward (i.e. 2-way) merge, or a 3-way merge, with the <tt>-m</tt>
432flag. 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]433the files in the work tree with the result of the merge.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]434<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]435will be in unmerged state when <em>git read-tree</em> returns.</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]436</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]437<h2 id="_options">OPTIONS</h2>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]438<div class="sectionbody">
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]439<div class="dlist"><dl>
440<dt class="hdlist1">
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]441-m
442</dt>
443<dd>
444<p>
445 Perform a merge, not just a read. The command will
446 refuse to run if your index file has unmerged entries,
447 indicating that you have not finished previous merge you
448 started.
449</p>
450</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]451<dt class="hdlist1">
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]452--reset
453</dt>
454<dd>
455<p>
456 Same as -m, except that unmerged entries are discarded
457 instead of failing.
458</p>
459</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]460<dt class="hdlist1">
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]461-u
462</dt>
463<dd>
464<p>
465 After a successful merge, update the files in the work
466 tree with the result of the merge.
467</p>
468</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]469<dt class="hdlist1">
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]470-i
471</dt>
472<dd>
473<p>
474 Usually a merge requires the index file as well as the
475 files in the working tree are up to date with the
476 current head commit, in order not to lose local
477 changes. This flag disables the check with the working
478 tree and is meant to be used when creating a merge of
479 trees that are not directly related to the current
480 working tree status into a temporary index file.
481</p>
482</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]483<dt class="hdlist1">
Junio C Hamanoef5a2f92011-05-31 19:53:33[diff] [blame]484-n
485</dt>
486<dt class="hdlist1">
487--dry-run
488</dt>
489<dd>
490<p>
491 Check if the command would error out, without updating the index
492 nor the files in the working tree for real.
493</p>
494</dd>
495<dt class="hdlist1">
Junio C Hamano0a18b352008-06-10 04:10:25[diff] [blame]496-v
497</dt>
498<dd>
499<p>
500 Show the progress of checking files out.
501</p>
502</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]503<dt class="hdlist1">
Junio C Hamanoee695f22007-06-21 00:35:36[diff] [blame]504--trivial
505</dt>
506<dd>
507<p>
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]508 Restrict three-way merge by <em>git read-tree</em> to happen
Junio C Hamanoee695f22007-06-21 00:35:36[diff] [blame]509 only if there is no file-level merging required, instead
510 of resolving merge for trivial cases and leaving
511 conflicting files unresolved in the index.
512</p>
513</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]514<dt class="hdlist1">
Junio C Hamano5f327762006-03-02 09:14:51[diff] [blame]515--aggressive
516</dt>
517<dd>
518<p>
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]519 Usually a three-way merge by <em>git read-tree</em> resolves
Junio C Hamano5f327762006-03-02 09:14:51[diff] [blame]520 the merge for really trivial cases and leaves other
521 cases unresolved in the index, so that Porcelains can
522 implement different merge policies. This flag makes the
523 command to resolve a few more cases internally:
524</p>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]525<div class="ulist"><ul>
Junio C Hamano5f327762006-03-02 09:14:51[diff] [blame]526<li>
527<p>
528when one side removes a path and the other side leaves the path
529 unmodified. The resolution is to remove that path.
530</p>
531</li>
532<li>
533<p>
534when both sides remove a path. The resolution is to remove that path.
535</p>
536</li>
537<li>
538<p>
539when both sides adds a path identically. The resolution
540 is to add that path.
541</p>
542</li>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]543</ul></div>
Junio C Hamano5f327762006-03-02 09:14:51[diff] [blame]544</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]545<dt class="hdlist1">
Junio C Hamanoad8c6432006-06-18 09:26:43[diff] [blame]546--prefix=&lt;prefix&gt;/
547</dt>
548<dd>
549<p>
550 Keep the current index contents, and read the contents
551 of named tree-ish under directory at <tt>&lt;prefix&gt;</tt>. The
552 original index file cannot have anything at the path
553 <tt>&lt;prefix&gt;</tt> itself, and have nothing in <tt>&lt;prefix&gt;/</tt>
554 directory. Note that the <tt>&lt;prefix&gt;/</tt> value must end
555 with a slash.
556</p>
557</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]558<dt class="hdlist1">
Junio C Hamanoe7935c42006-12-13 21:32:17[diff] [blame]559--exclude-per-directory=&lt;gitignore&gt;
560</dt>
561<dd>
562<p>
563 When running the command with <tt>-u</tt> and <tt>-m</tt> options, the
564 merge result may need to overwrite paths that are not
565 tracked in the current branch. The command usually
566 refuses to proceed with the merge to avoid losing such a
567 path. However this safety valve sometimes gets in the
568 way. For example, it often happens that the other
569 branch added a file that used to be a generated file in
570 your branch, and the safety valve triggers when you try
571 to switch to that branch after you ran <tt>make</tt> but before
572 running <tt>make clean</tt> to remove the generated file. This
573 option tells the command to read per-directory exclude
574 file (usually <em>.gitignore</em>) and allows such an untracked
575 but explicitly ignored file to be overwritten.
576</p>
577</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]578<dt class="hdlist1">
Junio C Hamano12a3a232007-04-07 10:18:10[diff] [blame]579--index-output=&lt;file&gt;
580</dt>
581<dd>
582<p>
583 Instead of writing the results out to <tt>$GIT_INDEX_FILE</tt>,
584 write the resulting index in the named file. While the
585 command is operating, the original index file is locked
586 with the same mechanism as usual. The file must allow
587 to be rename(2)ed into from a temporary file that is
588 created next to the usual index file; typically this
589 means it needs to be on the same filesystem as the index
590 file itself, and you need write permission to the
591 directories the index file and index output file are
592 located in.
593</p>
594</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]595<dt class="hdlist1">
Junio C Hamano3c8d6702010-01-13 23:09:03[diff] [blame]596--no-sparse-checkout
597</dt>
598<dd>
599<p>
600 Disable sparse checkout support even if <tt>core.sparseCheckout</tt>
601 is true.
602</p>
603</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]604<dt class="hdlist1">
Junio C Hamano3b4609d2010-09-30 00:04:34[diff] [blame]605--empty
606</dt>
607<dd>
608<p>
609 Instead of reading tree object(s) into the index, just empty
610 it.
611</p>
612</dd>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]613<dt class="hdlist1">
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]614&lt;tree-ish#&gt;
615</dt>
616<dd>
617<p>
618 The id of the tree object(s) to be read/merged.
619</p>
620</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]621</dl></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]622</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]623<h2 id="_merging">Merging</h2>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]624<div class="sectionbody">
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]625<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]626merge, a single tree merge if only 1 tree is given, a
627fast-forward merge with 2 trees, or a 3-way merge if 3 trees are
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]628provided.</p></div>
629<h3 id="_single_tree_merge">Single Tree Merge</h3><div style="clear:left"></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]630<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]631specify <tt>-m</tt>, except that if the original index has an entry for a
Junio C Hamanoae2dfa82010-03-17 05:41:52[diff] [blame]632given pathname, and the contents of the path match with the tree
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]633being read, the stat info from the index is used. (In other words, the
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]634index&#8217;s stat()s take precedence over the merged tree&#8217;s).</p></div>
635<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]636<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]637the stuff that really changed.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]638<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]639run after <em>git read-tree</em>.</p></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]640<h3 id="_two_tree_merge">Two Tree Merge</h3><div style="clear:left"></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]641<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]642is the head commit of the current repository, and $M is the head
643of 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]644fast-forward situation).</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]645<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]646the following:</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]647<div class="olist arabic"><ol class="arabic">
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]648<li>
649<p>
650The current index and work tree is derived from $H, but
Junio C Hamanoae2dfa82010-03-17 05:41:52[diff] [blame]651 the user may have local changes in them since $H.
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]652</p>
653</li>
654<li>
655<p>
656The user wants to fast-forward to $M.
657</p>
658</li>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]659</ol></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]660<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]661that no local change is lost as the result of this "merge".
Junio C Hamanoae2dfa82010-03-17 05:41:52[diff] [blame]662Here are the "carry forward" rules, where "I" denotes the index,
663"clean" means that index and work tree coincide, and "exists"/"nothing"
664refer to the presence of a path in the specified commit:</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]665<div class="literalblock">
666<div class="content">
Junio C Hamanoae2dfa82010-03-17 05:41:52[diff] [blame]667<pre><tt> I H M Result
668 -------------------------------------------------------
6690 nothing nothing nothing (does not happen)
6701 nothing nothing exists use M
6712 nothing exists nothing remove path from index
6723 nothing exists exists, use M if "initial checkout",
673 H == M keep index otherwise
674 exists, fail
675 H != M</tt></pre>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]676</div></div>
677<div class="literalblock">
678<div class="content">
Junio C Hamanoae2dfa82010-03-17 05:41:52[diff] [blame]679<pre><tt> clean I==H I==M
680 ------------------
6814 yes N/A N/A nothing nothing keep index
6825 no N/A N/A nothing nothing keep index</tt></pre>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]683</div></div>
684<div class="literalblock">
685<div class="content">
Junio C Hamanoae2dfa82010-03-17 05:41:52[diff] [blame]686<pre><tt>6 yes N/A yes nothing exists keep index
6877 no N/A yes nothing exists keep index
6888 yes N/A no nothing exists fail
6899 no N/A no nothing exists fail</tt></pre>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]690</div></div>
691<div class="literalblock">
692<div class="content">
693<pre><tt>10 yes yes N/A exists nothing remove path from index
69411 no yes N/A exists nothing fail
69512 yes no N/A exists nothing fail
69613 no no N/A exists nothing fail</tt></pre>
697</div></div>
698<div class="literalblock">
699<div class="content">
Junio C Hamanoae2dfa82010-03-17 05:41:52[diff] [blame]700<pre><tt> clean (H==M)
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]701 ------
70214 yes exists exists keep index
70315 no exists exists keep index</tt></pre>
704</div></div>
705<div class="literalblock">
706<div class="content">
707<pre><tt> clean I==H I==M (H!=M)
708 ------------------
70916 yes no no exists exists fail
71017 no no no exists exists fail
71118 yes no yes exists exists keep index
71219 no no yes exists exists keep index
71320 yes yes no exists exists use M
71421 no yes no exists exists fail</tt></pre>
715</div></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]716<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]717original index file. If the entry is not up to date,
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]718<em>git read-tree</em> keeps the copy in the work tree intact when
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]719operating under the -u flag.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]720<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]721see which of the "local changes" that you made were carried forward by running
Junio C Hamanofce7c7e2008-07-02 03:06:38[diff] [blame]722<tt>git diff-index --cached $M</tt>. Note that this does not
Junio C Hamanoae2dfa82010-03-17 05:41:52[diff] [blame]723necessarily match what <tt>git diff-index --cached $H</tt> would have
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]724produced before such a two tree merge. This is because of cases
72518 and 19 --- if you already had the changes in $M (e.g. maybe
Junio C Hamanofce7c7e2008-07-02 03:06:38[diff] [blame]726you picked it up via e-mail in a patch form), <tt>git diff-index
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]727--cached $H</tt> would have told you about the change before this
Junio C Hamanofce7c7e2008-07-02 03:06:38[diff] [blame]728merge, but it would not show in <tt>git diff-index --cached $M</tt>
Junio C Hamanoae2dfa82010-03-17 05:41:52[diff] [blame]729output after the two-tree merge.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]730<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]731rule logically should be to remove the path if the user staged the removal
Junio C Hamanoa476efa2008-10-10 15:31:42[diff] [blame]732of the path and then switching to a new branch. That however will prevent
Junio C Hamano78ec2262008-09-16 19:17:31[diff] [blame]733the initial checkout from happening, so the rule is modified to use M (new
Junio C Hamanoae2dfa82010-03-17 05:41:52[diff] [blame]734tree) only when the content of the index is empty. Otherwise the removal
Junio C Hamano78ec2262008-09-16 19:17:31[diff] [blame]735of 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]736<h3 id="_3_way_merge">3-Way Merge</h3><div style="clear:left"></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]737<div class="paragraph"><p>Each "index" entry has two bits worth of "stage" state. stage 0 is the
738normal one, and is the only one you&#8217;d see in any kind of normal use.</p></div>
739<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]740starts out at 1.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]741<div class="paragraph"><p>This means that you can do</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]742<div class="listingblock">
743<div class="content">
Junio C Hamanofce7c7e2008-07-02 03:06:38[diff] [blame]744<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]745</div></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]746<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]747"stage1", all of the &lt;tree2&gt; entries in "stage2" and all of the
748&lt;tree3&gt; entries in "stage3". When performing a merge of another
749branch into the current branch, we use the common ancestor tree
750as &lt;tree1&gt;, the current branch head as &lt;tree2&gt;, and the other
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]751branch head as &lt;tree3&gt;.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]752<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]753a file that matches in all respects in the following states, it
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]754"collapses" back to "stage0":</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]755<div class="ulist"><ul>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]756<li>
757<p>
758stage 2 and 3 are the same; take one or the other (it makes no
759 difference - the same work has been done on our branch in
760 stage 2 and their branch in stage 3)
761</p>
762</li>
763<li>
764<p>
765stage 1 and stage 2 are the same and stage 3 is different; take
766 stage 3 (our branch in stage 2 did not do anything since the
767 ancestor in stage 1 while their branch in stage 3 worked on
768 it)
769</p>
770</li>
771<li>
772<p>
773stage 1 and stage 3 are the same and stage 2 is different take
774 stage 2 (we did something while they did nothing)
775</p>
776</li>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]777</ul></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]778<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]779will complain about unmerged entries if it sees a single entry that is not
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]780stage 0.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]781<div class="paragraph"><p>OK, this all sounds like a collection of totally nonsensical rules,
782but it&#8217;s actually exactly what you want in order to do a fast
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]783merge. The different stages represent the "result tree" (stage 0, aka
784"merged"), the original tree (stage 1, aka "orig"), and the two trees
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]785you are trying to merge (stage 2 and 3 respectively).</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]786<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]787&lt;tree-ish&gt; command line arguments) are significant when you
788start a 3-way merge with an index file that is already
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]789populated. Here is an outline of how the algorithm works:</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]790<div class="ulist"><ul>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]791<li>
792<p>
793if a file exists in identical format in all three trees, it will
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]794 automatically collapse to "merged" state by <em>git read-tree</em>.
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]795</p>
796</li>
797<li>
798<p>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]799a file that has <em>any</em> difference what-so-ever in the three trees
800 will stay as separate entries in the index. It&#8217;s up to "porcelain
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]801 policy" to determine how to remove the non-0 stages, and insert a
802 merged version.
803</p>
804</li>
805<li>
806<p>
807the index file saves and restores with all this information, so you
808 can merge things incrementally, but as long as it has entries in
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]809 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]810 now the merge algorithm ends up being really simple:
811</p>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]812<div class="ulist"><ul>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]813<li>
814<p>
815you walk the index in order, and ignore all entries of stage 0,
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]816 since they&#8217;ve already been done.
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]817</p>
818</li>
819<li>
820<p>
821if you find a "stage1", but no matching "stage2" or "stage3", you
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]822 know it&#8217;s been removed from both trees (it only existed in the
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]823 original tree), and you remove that entry.
824</p>
825</li>
826<li>
827<p>
828if you find a matching "stage2" and "stage3" tree, you remove one
829 of them, and turn the other into a "stage0" entry. Remove any
830 matching "stage1" entry if it exists too. .. all the normal
831 trivial rules ..
832</p>
833</li>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]834</ul></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]835</li>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]836</ul></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]837<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]838<em>git merge-one-file</em> to do this last step. The script updates
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]839the files in the working tree as it merges each path and at the
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]840end of a successful merge.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]841<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]842populated, it is assumed that it represents the state of the
843files in your work tree, and you can even have files with
844changes unrecorded in the index file. It is further assumed
845that this state is "derived" from the stage 2 tree. The 3-way
846merge refuses to run if it finds an entry in the original index
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]847file that does not match stage 2.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]848<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]849changes, and mixing your random changes in an unrelated merge
850commit. To illustrate, suppose you start from what has been
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]851committed last to your repository:</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]852<div class="listingblock">
853<div class="content">
Junio C Hamanofce7c7e2008-07-02 03:06:38[diff] [blame]854<pre><tt>$ JC=`git rev-parse --verify "HEAD^0"`
855$ git checkout-index -f -u -a $JC</tt></pre>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]856</div></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]857<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]858you notice that the tip of your "upstream" tree has advanced
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]859since you pulled from him:</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]860<div class="listingblock">
861<div class="content">
Junio C Hamanofce7c7e2008-07-02 03:06:38[diff] [blame]862<pre><tt>$ git fetch git://.... linus
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]863$ LT=`cat .git/FETCH_HEAD`</tt></pre>
864</div></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]865<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]866some edits since. Three-way merge makes sure that you have not
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]867added or modified index entries since $JC, and if you haven&#8217;t,
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]868then does the right thing. So with the following sequence:</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]869<div class="listingblock">
870<div class="content">
Junio C Hamanofce7c7e2008-07-02 03:06:38[diff] [blame]871<pre><tt>$ git read-tree -m -u `git merge-base $JC $LT` $JC $LT
872$ git merge-index git-merge-one-file -a
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]873$ echo "Merge with Linus" | \
Junio C Hamanofce7c7e2008-07-02 03:06:38[diff] [blame]874 git commit-tree `git write-tree` -p $JC -p $LT</tt></pre>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]875</div></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]876<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]877your work-in-progress changes, and your work tree would be
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]878updated to the result of the merge.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]879<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]880would be overwritten by this merge, <em>git read-tree</em> will refuse
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]881to run to prevent your changes from being lost.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]882<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]883in the working tree. When you have local changes in a part of
884the project that is not involved in the merge, your changes do
885not interfere with the merge, and are kept intact. When they
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]886<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]887complains loudly and fails without modifying anything). In such
888a case, you can simply continue doing what you were in the
889middle of doing, and when your working tree is ready (i.e. you
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]890have finished your work-in-progress), attempt the merge again.</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]891</div>
Junio C Hamano3c8d6702010-01-13 23:09:03[diff] [blame]892<h2 id="_sparse_checkout">Sparse checkout</h2>
893<div class="sectionbody">
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]894<div class="paragraph"><p>"Sparse checkout" allows to sparsely populate working directory.
Junio C Hamano3c8d6702010-01-13 23:09:03[diff] [blame]895It uses skip-worktree bit (see <a href="git-update-index.html">git-update-index(1)</a>) to tell
896Git whether a file on working directory is worth looking at.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]897<div class="paragraph"><p>"git read-tree" and other merge-based commands ("git merge", "git
Junio C Hamano3c8d6702010-01-13 23:09:03[diff] [blame]898checkout"&#8230;) can help maintaining skip-worktree bitmap and working
899directory update. <tt>$GIT_DIR/info/sparse-checkout</tt> is used to
900define the skip-worktree reference bitmap. When "git read-tree" needs
901to update working directory, it will reset skip-worktree bit in index
902based on this file, which uses the same syntax as .gitignore files.
903If an entry matches a pattern in this file, skip-worktree will be
904set on that entry. Otherwise, skip-worktree will be unset.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]905<div class="paragraph"><p>Then it compares the new skip-worktree value with the previous one. If
Junio C Hamano3c8d6702010-01-13 23:09:03[diff] [blame]906skip-worktree turns from unset to set, it will add the corresponding
907file back. If it turns from set to unset, that file will be removed.</p></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]908<div class="paragraph"><p>While <tt>$GIT_DIR/info/sparse-checkout</tt> is usually used to specify what
909files are in. You can also specify what files are <em>not</em> in, using
Junio C Hamano3c8d6702010-01-13 23:09:03[diff] [blame]910negate patterns. For example, to remove file "unwanted":</p></div>
911<div class="listingblock">
912<div class="content">
913<pre><tt>*
914!unwanted</tt></pre>
915</div></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]916<div class="paragraph"><p>Another tricky thing is fully repopulating working directory when you
Junio C Hamano3c8d6702010-01-13 23:09:03[diff] [blame]917no longer want sparse checkout. You cannot just disable "sparse
918checkout" because skip-worktree are still in the index and you working
919directory is still sparsely populated. You should re-populate working
920directory with the <tt>$GIT_DIR/info/sparse-checkout</tt> file content as
921follows:</p></div>
922<div class="listingblock">
923<div class="content">
924<pre><tt>*</tt></pre>
925</div></div>
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]926<div class="paragraph"><p>Then you can disable sparse checkout. Sparse checkout support in "git
Junio C Hamano3c8d6702010-01-13 23:09:03[diff] [blame]927read-tree" and similar commands is disabled by default. You need to
928turn <tt>core.sparseCheckout</tt> on in order to have sparse checkout
929support.</p></div>
930</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]931<h2 id="_see_also">SEE ALSO</h2>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]932<div class="sectionbody">
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]933<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]934<a href="gitignore.html">gitignore(5)</a></p></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]935</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]936<h2 id="_git">GIT</h2>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]937<div class="sectionbody">
Junio C Hamano5fa6d1a2010-12-23 00:57:39[diff] [blame]938<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]939</div>
940<div id="footer">
941<div id="footer-text">
Junio C Hamano15567bc2011-07-23 00:51:59[diff] [blame]942Last updated 2011-07-23 00:49:30 UTC
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]943</div>
944</div>
945</body>
946</html>