1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
\r
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
\r
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
\r
5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
\r
6 <meta name="generator" content="AsciiDoc 7.0.1" />
\r
7 <style type="text/css">
\r
9 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
\r
11 border: 1px solid red;
\r
16 margin: 1em 5% 1em 5%;
\r
20 a:visited { color: fuchsia; }
\r
34 h1, h2, h3, h4, h5, h6 {
\r
36 font-family: sans-serif;
\r
38 margin-bottom: 0.5em;
\r
43 border-bottom: 2px solid silver;
\r
46 border-bottom: 2px solid silver;
\r
56 border: 1px solid silver;
\r
61 margin-bottom: 0.5em;
\r
71 font-family: sans-serif;
\r
78 font-family: sans-serif;
\r
82 font-family: sans-serif;
\r
84 border-top: 2px solid silver;
\r
90 padding-bottom: 0.5em;
\r
94 padding-bottom: 0.5em;
\r
98 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
\r
99 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
\r
100 div.admonitionblock {
\r
103 margin-bottom: 1.5em;
\r
105 div.admonitionblock {
\r
107 margin-bottom: 2.5em;
\r
110 div.content { /* Block element content. */
\r
114 /* Block element titles. */
\r
115 div.title, caption.title {
\r
116 font-family: sans-serif;
\r
120 margin-bottom: 0.5em;
\r
126 td div.title:first-child {
\r
129 div.content div.title:first-child {
\r
132 div.content + div.title {
\r
136 div.sidebarblock > div.content {
\r
137 background: #ffffee;
\r
138 border: 1px solid silver;
\r
142 div.listingblock > div.content {
\r
143 border: 1px solid silver;
\r
144 background: #f4f4f4;
\r
148 div.quoteblock > div.content {
\r
149 padding-left: 2.0em;
\r
151 div.quoteblock .attribution {
\r
155 div.admonitionblock .icon {
\r
156 vertical-align: top;
\r
159 text-decoration: underline;
\r
161 padding-right: 0.5em;
\r
163 div.admonitionblock td.content {
\r
164 padding-left: 0.5em;
\r
165 border-left: 2px solid silver;
\r
168 div.exampleblock > div.content {
\r
169 border-left: 2px solid silver;
\r
173 div.verseblock div.content {
\r
177 div.imageblock div.content { padding-left: 0; }
\r
178 div.imageblock img { border: 1px solid silver; }
\r
179 span.image img { border-style: none; }
\r
183 margin-bottom: 0.8em;
\r
188 font-style: italic;
\r
190 dd > *:first-child {
\r
195 list-style-position: outside;
\r
198 list-style-type: lower-alpha;
\r
201 div.tableblock > table {
\r
202 border-color: #527bbd;
\r
206 font-family: sans-serif;
\r
215 margin-bottom: 0.8em;
\r
218 vertical-align: top;
\r
219 font-style: italic;
\r
220 padding-right: 0.8em;
\r
223 vertical-align: top;
\r
227 div#footer-badges { display: none; }
\r
229 include::./stylesheets/xhtml11-manpage.css[]
\r
230 /* Workarounds for IE6's broken and incomplete CSS2. */
\r
232 div.sidebar-content {
\r
233 background: #ffffee;
\r
234 border: 1px solid silver;
\r
237 div.sidebar-title, div.image-title {
\r
238 font-family: sans-serif;
\r
241 margin-bottom: 0.5em;
\r
244 div.listingblock div.content {
\r
245 border: 1px solid silver;
\r
246 background: #f4f4f4;
\r
250 div.quoteblock-content {
\r
251 padding-left: 2.0em;
\r
254 div.exampleblock-content {
\r
255 border-left: 2px solid silver;
\r
256 padding-left: 0.5em;
\r
259 <title>git-read-tree(1)</title>
\r
264 git-read-tree(1) Manual Page
\r
267 <div class="sectionbody">
\r
269 Reads tree information into the index
\r
274 <div class="sectionbody">
\r
275 <p><em>git-read-tree</em> (<tree-ish> | [[-m | --reset] [-u | -i]] <tree-ish1> [<tree-ish2> [<tree-ish3>]])</p>
\r
277 <h2>DESCRIPTION</h2>
\r
278 <div class="sectionbody">
\r
279 <p>Reads the tree information given by <tree-ish> into the index,
\r
280 but does not actually <strong>update</strong> any of the files it "caches". (see:
\r
281 <a href="git-checkout-index.html">git-checkout-index(1)</a>)</p>
\r
282 <p>Optionally, it can merge a tree into the index, perform a
\r
283 fast-forward (i.e. 2-way) merge, or a 3-way merge, with the <tt>-m</tt>
\r
284 flag. When used with <tt>-m</tt>, the <tt>-u</tt> flag causes it to also update
\r
285 the files in the work tree with the result of the merge.</p>
\r
286 <p>Trivial merges are done by <tt>git-read-tree</tt> itself. Only conflicting paths
\r
287 will be in unmerged state when <tt>git-read-tree</tt> returns.</p>
\r
290 <div class="sectionbody">
\r
297 Perform a merge, not just a read. The command will
\r
298 refuse to run if your index file has unmerged entries,
\r
299 indicating that you have not finished previous merge you
\r
308 Same as -m, except that unmerged entries are discarded
\r
309 instead of failing.
\r
317 After a successful merge, update the files in the work
\r
318 tree with the result of the merge.
\r
326 Usually a merge requires the index file as well as the
\r
327 files in the working tree are up to date with the
\r
328 current head commit, in order not to lose local
\r
329 changes. This flag disables the check with the working
\r
330 tree and is meant to be used when creating a merge of
\r
331 trees that are not directly related to the current
\r
332 working tree status into a temporary index file.
\r
340 The id of the tree object(s) to be read/merged.
\r
346 <div class="sectionbody">
\r
347 <p>If <tt>-m</tt> is specified, <tt>git-read-tree</tt> can perform 3 kinds of
\r
348 merge, a single tree merge if only 1 tree is given, a
\r
349 fast-forward merge with 2 trees, or a 3-way merge if 3 trees are
\r
351 <h3>Single Tree Merge</h3>
\r
352 <p>If only 1 tree is specified, git-read-tree operates as if the user did not
\r
353 specify <tt>-m</tt>, except that if the original index has an entry for a
\r
354 given pathname, and the contents of the path matches with the tree
\r
355 being read, the stat info from the index is used. (In other words, the
\r
356 index's stat()s take precedence over the merged tree's).</p>
\r
357 <p>That means that if you do a <tt>git-read-tree -m <newtree></tt> followed by a
\r
358 <tt>git-checkout-index -f -u -a</tt>, the <tt>git-checkout-index</tt> only checks out
\r
359 the stuff that really changed.</p>
\r
360 <p>This is used to avoid unnecessary false hits when <tt>git-diff-files</tt> is
\r
361 run after <tt>git-read-tree</tt>.</p>
\r
362 <h3>Two Tree Merge</h3>
\r
363 <p>Typically, this is invoked as <tt>git-read-tree -m $H $M</tt>, where $H
\r
364 is the head commit of the current repository, and $M is the head
\r
365 of a foreign tree, which is simply ahead of $H (i.e. we are in a
\r
366 fast forward situation).</p>
\r
367 <p>When two trees are specified, the user is telling git-read-tree
\r
372 The current index and work tree is derived from $H, but
\r
373 the user may have local changes in them since $H;
\r
378 The user wants to fast-forward to $M.
\r
382 <p>In this case, the <tt>git-read-tree -m $H $M</tt> command makes sure
\r
383 that no local change is lost as the result of this "merge".
\r
384 Here are the "carry forward" rules:</p>
\r
385 <div class="literalblock">
\r
386 <div class="content">
\r
387 <pre><tt> I (index) H M Result
\r
388 -------------------------------------------------------
\r
389 0 nothing nothing nothing (does not happen)
\r
390 1 nothing nothing exists use M
\r
391 2 nothing exists nothing remove path from index
\r
392 3 nothing exists exists use M</tt></pre>
\r
394 <div class="literalblock">
\r
395 <div class="content">
\r
396 <pre><tt> clean I==H I==M
\r
398 4 yes N/A N/A nothing nothing keep index
\r
399 5 no N/A N/A nothing nothing keep index</tt></pre>
\r
401 <div class="literalblock">
\r
402 <div class="content">
\r
403 <pre><tt>6 yes N/A yes nothing exists keep index
\r
404 7 no N/A yes nothing exists keep index
\r
405 8 yes N/A no nothing exists fail
\r
406 9 no N/A no nothing exists fail</tt></pre>
\r
408 <div class="literalblock">
\r
409 <div class="content">
\r
410 <pre><tt>10 yes yes N/A exists nothing remove path from index
\r
411 11 no yes N/A exists nothing fail
\r
412 12 yes no N/A exists nothing fail
\r
413 13 no no N/A exists nothing fail</tt></pre>
\r
415 <div class="literalblock">
\r
416 <div class="content">
\r
417 <pre><tt> clean (H=M)
\r
419 14 yes exists exists keep index
\r
420 15 no exists exists keep index</tt></pre>
\r
422 <div class="literalblock">
\r
423 <div class="content">
\r
424 <pre><tt> clean I==H I==M (H!=M)
\r
426 16 yes no no exists exists fail
\r
427 17 no no no exists exists fail
\r
428 18 yes no yes exists exists keep index
\r
429 19 no no yes exists exists keep index
\r
430 20 yes yes no exists exists use M
\r
431 21 no yes no exists exists fail</tt></pre>
\r
433 <p>In all "keep index" cases, the index entry stays as in the
\r
434 original index file. If the entry were not up to date,
\r
435 git-read-tree keeps the copy in the work tree intact when
\r
436 operating under the -u flag.</p>
\r
437 <p>When this form of git-read-tree returns successfully, you can
\r
438 see what "local changes" you made are carried forward by running
\r
439 <tt>git-diff-index --cached $M</tt>. Note that this does not
\r
440 necessarily match <tt>git-diff-index --cached $H</tt> would have
\r
441 produced before such a two tree merge. This is because of cases
\r
442 18 and 19 --- if you already had the changes in $M (e.g. maybe
\r
443 you picked it up via e-mail in a patch form), <tt>git-diff-index
\r
444 --cached $H</tt> would have told you about the change before this
\r
445 merge, but it would not show in <tt>git-diff-index --cached $M</tt>
\r
446 output after two-tree merge.</p>
\r
447 <h3>3-Way Merge</h3>
\r
448 <p>Each "index" entry has two bits worth of "stage" state. stage 0 is the
\r
449 normal one, and is the only one you'd see in any kind of normal use.</p>
\r
450 <p>However, when you do <tt>git-read-tree</tt> with three trees, the "stage"
\r
451 starts out at 1.</p>
\r
452 <p>This means that you can do</p>
\r
453 <div class="listingblock">
\r
454 <div class="content">
\r
455 <pre><tt>$ git-read-tree -m <tree1> <tree2> <tree3></tt></pre>
\r
457 <p>and you will end up with an index with all of the <tree1> entries in
\r
458 "stage1", all of the <tree2> entries in "stage2" and all of the
\r
459 <tree3> entries in "stage3". When performing a merge of another
\r
460 branch into the current branch, we use the common ancestor tree
\r
461 as <tree1>, the current branch head as <tree2>, and the other
\r
462 branch head as <tree3>.</p>
\r
463 <p>Furthermore, <tt>git-read-tree</tt> has special-case logic that says: if you see
\r
464 a file that matches in all respects in the following states, it
\r
465 "collapses" back to "stage0":</p>
\r
469 stage 2 and 3 are the same; take one or the other (it makes no
\r
470 difference - the same work has been done on our branch in
\r
471 stage 2 and their branch in stage 3)
\r
476 stage 1 and stage 2 are the same and stage 3 is different; take
\r
477 stage 3 (our branch in stage 2 did not do anything since the
\r
478 ancestor in stage 1 while their branch in stage 3 worked on
\r
484 stage 1 and stage 3 are the same and stage 2 is different take
\r
485 stage 2 (we did something while they did nothing)
\r
489 <p>The <tt>git-write-tree</tt> command refuses to write a nonsensical tree, and it
\r
490 will complain about unmerged entries if it sees a single entry that is not
\r
492 <p>Ok, this all sounds like a collection of totally nonsensical rules,
\r
493 but it's actually exactly what you want in order to do a fast
\r
494 merge. The different stages represent the "result tree" (stage 0, aka
\r
495 "merged"), the original tree (stage 1, aka "orig"), and the two trees
\r
496 you are trying to merge (stage 2 and 3 respectively).</p>
\r
497 <p>The order of stages 1, 2 and 3 (hence the order of three
\r
498 <tree-ish> command line arguments) are significant when you
\r
499 start a 3-way merge with an index file that is already
\r
500 populated. Here is an outline of how the algorithm works:</p>
\r
504 if a file exists in identical format in all three trees, it will
\r
505 automatically collapse to "merged" state by git-read-tree.
\r
510 a file that has _any_ difference what-so-ever in the three trees
\r
511 will stay as separate entries in the index. It's up to "porcelain
\r
512 policy" to determine how to remove the non-0 stages, and insert a
\r
518 the index file saves and restores with all this information, so you
\r
519 can merge things incrementally, but as long as it has entries in
\r
520 stages 1/2/3 (ie "unmerged entries") you can't write the result. So
\r
521 now the merge algorithm ends up being really simple:
\r
526 you walk the index in order, and ignore all entries of stage 0,
\r
527 since they've already been done.
\r
532 if you find a "stage1", but no matching "stage2" or "stage3", you
\r
533 know it's been removed from both trees (it only existed in the
\r
534 original tree), and you remove that entry.
\r
539 if you find a matching "stage2" and "stage3" tree, you remove one
\r
540 of them, and turn the other into a "stage0" entry. Remove any
\r
541 matching "stage1" entry if it exists too. .. all the normal
\r
548 <p>You would normally use <tt>git-merge-index</tt> with supplied
\r
549 <tt>git-merge-one-file</tt> to do this last step. The script updates
\r
550 the files in the working tree as it merges each path and at the
\r
551 end of a successful merge.</p>
\r
552 <p>When you start a 3-way merge with an index file that is already
\r
553 populated, it is assumed that it represents the state of the
\r
554 files in your work tree, and you can even have files with
\r
555 changes unrecorded in the index file. It is further assumed
\r
556 that this state is "derived" from the stage 2 tree. The 3-way
\r
557 merge refuses to run if it finds an entry in the original index
\r
558 file that does not match stage 2.</p>
\r
559 <p>This is done to prevent you from losing your work-in-progress
\r
560 changes, and mixing your random changes in an unrelated merge
\r
561 commit. To illustrate, suppose you start from what has been
\r
562 commited last to your repository:</p>
\r
563 <div class="listingblock">
\r
564 <div class="content">
\r
565 <pre><tt>$ JC=`git-rev-parse --verify "HEAD^0"`
\r
566 $ git-checkout-index -f -u -a $JC</tt></pre>
\r
568 <p>You do random edits, without running git-update-index. And then
\r
569 you notice that the tip of your "upstream" tree has advanced
\r
570 since you pulled from him:</p>
\r
571 <div class="listingblock">
\r
572 <div class="content">
\r
573 <pre><tt>$ git-fetch git://.... linus
\r
574 $ LT=`cat .git/FETCH_HEAD`</tt></pre>
\r
576 <p>Your work tree is still based on your HEAD ($JC), but you have
\r
577 some edits since. Three-way merge makes sure that you have not
\r
578 added or modified index entries since $JC, and if you haven't,
\r
579 then does the right thing. So with the following sequence:</p>
\r
580 <div class="listingblock">
\r
581 <div class="content">
\r
582 <pre><tt>$ git-read-tree -m -u `git-merge-base $JC $LT` $JC $LT
\r
583 $ git-merge-index git-merge-one-file -a
\r
584 $ echo "Merge with Linus" | \
\r
585 git-commit-tree `git-write-tree` -p $JC -p $LT</tt></pre>
\r
587 <p>what you would commit is a pure merge between $JC and $LT without
\r
588 your work-in-progress changes, and your work tree would be
\r
589 updated to the result of the merge.</p>
\r
590 <p>However, if you have local changes in the working tree that
\r
591 would be overwritten by this merge,<tt>git-read-tree</tt> will refuse
\r
592 to run to prevent your changes from being lost.</p>
\r
593 <p>In other words, there is no need to worry about what exists only
\r
594 in the working tree. When you have local changes in a part of
\r
595 the project that is not involved in the merge, your changes do
\r
596 not interfere with the merge, and are kept intact. When they
\r
597 <strong>do</strong> interfere, the merge does not even start (<tt>git-read-tree</tt>
\r
598 complains loudly and fails without modifying anything). In such
\r
599 a case, you can simply continue doing what you were in the
\r
600 middle of doing, and when your working tree is ready (i.e. you
\r
601 have finished your work-in-progress), attempt the merge again.</p>
\r
604 <div class="sectionbody">
\r
605 <p><a href="git-write-tree.html">git-write-tree(1)</a>; <a href="git-ls-files.html">git-ls-files(1)</a></p>
\r
608 <div class="sectionbody">
\r
609 <p>Written by Linus Torvalds <torvalds@osdl.org></p>
\r
611 <h2>Documentation</h2>
\r
612 <div class="sectionbody">
\r
613 <p>Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.</p>
\r
616 <div class="sectionbody">
\r
617 <p>Part of the <a href="git.html">git(7)</a> suite</p>
\r
620 <div id="footer-text">
\r
621 Last updated 27-Dec-2005 00:16:31 PDT
\r
projects / git.git / blob