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.2" />
\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 [--aggressive]| --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 Usually a three-way merge by <tt>git-read-tree</tt> resolves
\r
341 the merge for really trivial cases and leaves other
\r
342 cases unresolved in the index, so that Porcelains can
\r
343 implement different merge policies. This flag makes the
\r
344 command to resolve a few more cases internally:
\r
349 when one side removes a path and the other side leaves the path
\r
350 unmodified. The resolution is to remove that path.
\r
355 when both sides remove a path. The resolution is to remove that path.
\r
360 when both sides adds a path identically. The resolution
\r
361 is to add that path.
\r
371 The id of the tree object(s) to be read/merged.
\r
377 <div class="sectionbody">
\r
378 <p>If <tt>-m</tt> is specified, <tt>git-read-tree</tt> can perform 3 kinds of
\r
379 merge, a single tree merge if only 1 tree is given, a
\r
380 fast-forward merge with 2 trees, or a 3-way merge if 3 trees are
\r
382 <h3>Single Tree Merge</h3>
\r
383 <p>If only 1 tree is specified, git-read-tree operates as if the user did not
\r
384 specify <tt>-m</tt>, except that if the original index has an entry for a
\r
385 given pathname, and the contents of the path matches with the tree
\r
386 being read, the stat info from the index is used. (In other words, the
\r
387 index's stat()s take precedence over the merged tree's).</p>
\r
388 <p>That means that if you do a <tt>git-read-tree -m <newtree></tt> followed by a
\r
389 <tt>git-checkout-index -f -u -a</tt>, the <tt>git-checkout-index</tt> only checks out
\r
390 the stuff that really changed.</p>
\r
391 <p>This is used to avoid unnecessary false hits when <tt>git-diff-files</tt> is
\r
392 run after <tt>git-read-tree</tt>.</p>
\r
393 <h3>Two Tree Merge</h3>
\r
394 <p>Typically, this is invoked as <tt>git-read-tree -m $H $M</tt>, where $H
\r
395 is the head commit of the current repository, and $M is the head
\r
396 of a foreign tree, which is simply ahead of $H (i.e. we are in a
\r
397 fast forward situation).</p>
\r
398 <p>When two trees are specified, the user is telling git-read-tree
\r
403 The current index and work tree is derived from $H, but
\r
404 the user may have local changes in them since $H;
\r
409 The user wants to fast-forward to $M.
\r
413 <p>In this case, the <tt>git-read-tree -m $H $M</tt> command makes sure
\r
414 that no local change is lost as the result of this "merge".
\r
415 Here are the "carry forward" rules:</p>
\r
416 <div class="literalblock">
\r
417 <div class="content">
\r
418 <pre><tt> I (index) H M Result
\r
419 -------------------------------------------------------
\r
420 0 nothing nothing nothing (does not happen)
\r
421 1 nothing nothing exists use M
\r
422 2 nothing exists nothing remove path from index
\r
423 3 nothing exists exists use M</tt></pre>
\r
425 <div class="literalblock">
\r
426 <div class="content">
\r
427 <pre><tt> clean I==H I==M
\r
429 4 yes N/A N/A nothing nothing keep index
\r
430 5 no N/A N/A nothing nothing keep index</tt></pre>
\r
432 <div class="literalblock">
\r
433 <div class="content">
\r
434 <pre><tt>6 yes N/A yes nothing exists keep index
\r
435 7 no N/A yes nothing exists keep index
\r
436 8 yes N/A no nothing exists fail
\r
437 9 no N/A no nothing exists fail</tt></pre>
\r
439 <div class="literalblock">
\r
440 <div class="content">
\r
441 <pre><tt>10 yes yes N/A exists nothing remove path from index
\r
442 11 no yes N/A exists nothing fail
\r
443 12 yes no N/A exists nothing fail
\r
444 13 no no N/A exists nothing fail</tt></pre>
\r
446 <div class="literalblock">
\r
447 <div class="content">
\r
448 <pre><tt> clean (H=M)
\r
450 14 yes exists exists keep index
\r
451 15 no exists exists keep index</tt></pre>
\r
453 <div class="literalblock">
\r
454 <div class="content">
\r
455 <pre><tt> clean I==H I==M (H!=M)
\r
457 16 yes no no exists exists fail
\r
458 17 no no no exists exists fail
\r
459 18 yes no yes exists exists keep index
\r
460 19 no no yes exists exists keep index
\r
461 20 yes yes no exists exists use M
\r
462 21 no yes no exists exists fail</tt></pre>
\r
464 <p>In all "keep index" cases, the index entry stays as in the
\r
465 original index file. If the entry were not up to date,
\r
466 git-read-tree keeps the copy in the work tree intact when
\r
467 operating under the -u flag.</p>
\r
468 <p>When this form of git-read-tree returns successfully, you can
\r
469 see what "local changes" you made are carried forward by running
\r
470 <tt>git-diff-index --cached $M</tt>. Note that this does not
\r
471 necessarily match <tt>git-diff-index --cached $H</tt> would have
\r
472 produced before such a two tree merge. This is because of cases
\r
473 18 and 19 --- if you already had the changes in $M (e.g. maybe
\r
474 you picked it up via e-mail in a patch form), <tt>git-diff-index
\r
475 --cached $H</tt> would have told you about the change before this
\r
476 merge, but it would not show in <tt>git-diff-index --cached $M</tt>
\r
477 output after two-tree merge.</p>
\r
478 <h3>3-Way Merge</h3>
\r
479 <p>Each "index" entry has two bits worth of "stage" state. stage 0 is the
\r
480 normal one, and is the only one you'd see in any kind of normal use.</p>
\r
481 <p>However, when you do <tt>git-read-tree</tt> with three trees, the "stage"
\r
482 starts out at 1.</p>
\r
483 <p>This means that you can do</p>
\r
484 <div class="listingblock">
\r
485 <div class="content">
\r
486 <pre><tt>$ git-read-tree -m <tree1> <tree2> <tree3></tt></pre>
\r
488 <p>and you will end up with an index with all of the <tree1> entries in
\r
489 "stage1", all of the <tree2> entries in "stage2" and all of the
\r
490 <tree3> entries in "stage3". When performing a merge of another
\r
491 branch into the current branch, we use the common ancestor tree
\r
492 as <tree1>, the current branch head as <tree2>, and the other
\r
493 branch head as <tree3>.</p>
\r
494 <p>Furthermore, <tt>git-read-tree</tt> has special-case logic that says: if you see
\r
495 a file that matches in all respects in the following states, it
\r
496 "collapses" back to "stage0":</p>
\r
500 stage 2 and 3 are the same; take one or the other (it makes no
\r
501 difference - the same work has been done on our branch in
\r
502 stage 2 and their branch in stage 3)
\r
507 stage 1 and stage 2 are the same and stage 3 is different; take
\r
508 stage 3 (our branch in stage 2 did not do anything since the
\r
509 ancestor in stage 1 while their branch in stage 3 worked on
\r
515 stage 1 and stage 3 are the same and stage 2 is different take
\r
516 stage 2 (we did something while they did nothing)
\r
520 <p>The <tt>git-write-tree</tt> command refuses to write a nonsensical tree, and it
\r
521 will complain about unmerged entries if it sees a single entry that is not
\r
523 <p>Ok, this all sounds like a collection of totally nonsensical rules,
\r
524 but it's actually exactly what you want in order to do a fast
\r
525 merge. The different stages represent the "result tree" (stage 0, aka
\r
526 "merged"), the original tree (stage 1, aka "orig"), and the two trees
\r
527 you are trying to merge (stage 2 and 3 respectively).</p>
\r
528 <p>The order of stages 1, 2 and 3 (hence the order of three
\r
529 <tree-ish> command line arguments) are significant when you
\r
530 start a 3-way merge with an index file that is already
\r
531 populated. Here is an outline of how the algorithm works:</p>
\r
535 if a file exists in identical format in all three trees, it will
\r
536 automatically collapse to "merged" state by git-read-tree.
\r
541 a file that has _any_ difference what-so-ever in the three trees
\r
542 will stay as separate entries in the index. It's up to "porcelain
\r
543 policy" to determine how to remove the non-0 stages, and insert a
\r
549 the index file saves and restores with all this information, so you
\r
550 can merge things incrementally, but as long as it has entries in
\r
551 stages 1/2/3 (ie "unmerged entries") you can't write the result. So
\r
552 now the merge algorithm ends up being really simple:
\r
557 you walk the index in order, and ignore all entries of stage 0,
\r
558 since they've already been done.
\r
563 if you find a "stage1", but no matching "stage2" or "stage3", you
\r
564 know it's been removed from both trees (it only existed in the
\r
565 original tree), and you remove that entry.
\r
570 if you find a matching "stage2" and "stage3" tree, you remove one
\r
571 of them, and turn the other into a "stage0" entry. Remove any
\r
572 matching "stage1" entry if it exists too. .. all the normal
\r
579 <p>You would normally use <tt>git-merge-index</tt> with supplied
\r
580 <tt>git-merge-one-file</tt> to do this last step. The script updates
\r
581 the files in the working tree as it merges each path and at the
\r
582 end of a successful merge.</p>
\r
583 <p>When you start a 3-way merge with an index file that is already
\r
584 populated, it is assumed that it represents the state of the
\r
585 files in your work tree, and you can even have files with
\r
586 changes unrecorded in the index file. It is further assumed
\r
587 that this state is "derived" from the stage 2 tree. The 3-way
\r
588 merge refuses to run if it finds an entry in the original index
\r
589 file that does not match stage 2.</p>
\r
590 <p>This is done to prevent you from losing your work-in-progress
\r
591 changes, and mixing your random changes in an unrelated merge
\r
592 commit. To illustrate, suppose you start from what has been
\r
593 commited last to your repository:</p>
\r
594 <div class="listingblock">
\r
595 <div class="content">
\r
596 <pre><tt>$ JC=`git-rev-parse --verify "HEAD^0"`
\r
597 $ git-checkout-index -f -u -a $JC</tt></pre>
\r
599 <p>You do random edits, without running git-update-index. And then
\r
600 you notice that the tip of your "upstream" tree has advanced
\r
601 since you pulled from him:</p>
\r
602 <div class="listingblock">
\r
603 <div class="content">
\r
604 <pre><tt>$ git-fetch git://.... linus
\r
605 $ LT=`cat .git/FETCH_HEAD`</tt></pre>
\r
607 <p>Your work tree is still based on your HEAD ($JC), but you have
\r
608 some edits since. Three-way merge makes sure that you have not
\r
609 added or modified index entries since $JC, and if you haven't,
\r
610 then does the right thing. So with the following sequence:</p>
\r
611 <div class="listingblock">
\r
612 <div class="content">
\r
613 <pre><tt>$ git-read-tree -m -u `git-merge-base $JC $LT` $JC $LT
\r
614 $ git-merge-index git-merge-one-file -a
\r
615 $ echo "Merge with Linus" | \
\r
616 git-commit-tree `git-write-tree` -p $JC -p $LT</tt></pre>
\r
618 <p>what you would commit is a pure merge between $JC and $LT without
\r
619 your work-in-progress changes, and your work tree would be
\r
620 updated to the result of the merge.</p>
\r
621 <p>However, if you have local changes in the working tree that
\r
622 would be overwritten by this merge,<tt>git-read-tree</tt> will refuse
\r
623 to run to prevent your changes from being lost.</p>
\r
624 <p>In other words, there is no need to worry about what exists only
\r
625 in the working tree. When you have local changes in a part of
\r
626 the project that is not involved in the merge, your changes do
\r
627 not interfere with the merge, and are kept intact. When they
\r
628 <strong>do</strong> interfere, the merge does not even start (<tt>git-read-tree</tt>
\r
629 complains loudly and fails without modifying anything). In such
\r
630 a case, you can simply continue doing what you were in the
\r
631 middle of doing, and when your working tree is ready (i.e. you
\r
632 have finished your work-in-progress), attempt the merge again.</p>
\r
635 <div class="sectionbody">
\r
636 <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
639 <div class="sectionbody">
\r
640 <p>Written by Linus Torvalds <torvalds@osdl.org></p>
\r
642 <h2>Documentation</h2>
\r
643 <div class="sectionbody">
\r
644 <p>Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.</p>
\r
647 <div class="sectionbody">
\r
648 <p>Part of the <a href="git.html">git(7)</a> suite</p>
\r
651 <div id="footer-text">
\r
652 Last updated 02-Mar-2006 09:14:48 UTC
\r
projects / git.git / blob