From: Junio C Hamano Date: Tue, 6 Dec 2005 07:26:10 +0000 (-0800) Subject: Documentaiton (read-tree): update description of 3-way X-Git-Tag: v0.99.9m^2~56 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=bb6d7b893e7f9f22e58a63d871b5b4c87b887513;p=git.git Documentaiton (read-tree): update description of 3-way The merge-one-file used to leave the working tree intact, but it has long been changed to leave the merge result there since 2a68a8659f7dc55fd285d235ae2d19e7a8116c30 commit. Signed-off-by: Junio C Hamano --- diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 4377362df..27ee5909c 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -167,20 +167,26 @@ $ git-read-tree -m and you will end up with an index with all of the entries in "stage1", all of the entries in "stage2" and all of the - entries in "stage3". + entries in "stage3". When performing a merge of another +branch into the current branch, we use the common ancestor tree +as , the current branch head as , and the other +branch head as . Furthermore, `git-read-tree` has special-case logic that says: if you see a file that matches in all respects in the following states, it "collapses" back to "stage0": - stage 2 and 3 are the same; take one or the other (it makes no - difference - the same work has been done on stage 2 and 3) + difference - the same work has been done on our branch in + stage 2 and their branch in stage 3) - stage 1 and stage 2 are the same and stage 3 is different; take - stage 3 (some work has been done on stage 3) + stage 3 (our branch in stage 2 did not do anything since the + ancestor in stage 1 while their branch in stage 3 worked on + it) - stage 1 and stage 3 are the same and stage 2 is different take - stage 2 (some work has been done on stage 2) + stage 2 (we did something while they did nothing) The `git-write-tree` command refuses to write a nonsensical tree, and it will complain about unmerged entries if it sees a single entry that is not @@ -223,11 +229,9 @@ populated. Here is an outline of how the algorithm works: trivial rules .. You would normally use `git-merge-index` with supplied -`git-merge-one-file` to do this last step. The script -does not touch the files in the work tree, and the entire merge -happens in the index file. In other words, there is no need to -worry about what is in the working directory, since it is never -shown and never used. +`git-merge-one-file` to do this last step. The script updates +the files in the working tree as it merges each path and at the +end of a successful merge. When you start a 3-way merge with an index file that is already populated, it is assumed that it represents the state of the @@ -238,7 +242,8 @@ merge refuses to run if it finds an entry in the original index file that does not match stage 2. This is done to prevent you from losing your work-in-progress -changes. To illustrate, suppose you start from what has been +changes, and mixing your random changes in an unrelated merge +commit. To illustrate, suppose you start from what has been commited last to your repository: ---------------- @@ -251,8 +256,8 @@ you notice that the tip of your "upstream" tree has advanced since you pulled from him: ---------------- -$ git-fetch rsync://.... linus -$ LT=`cat .git/MERGE_HEAD` +$ git-fetch git://.... linus +$ LT=`cat .git/FETCH_HEAD` ---------------- Your work tree is still based on your HEAD ($JC), but you have @@ -271,6 +276,20 @@ what you would commit is a pure merge between $JC and $LT without your work-in-progress changes, and your work tree would be updated to the result of the merge. +However, if you have local changes in the working tree that +would be overwritten by this merge,`git-read-tree` will refuse +to run to prevent your changes from being lost. + +In other words, there is no need to worry about what exists only +in the working tree. When you have local changes in a part of +the project that is not involved in the merge, your changes do +not interfere with the merge, and are kept intact. When they +*do* interfere, the merge does not even start (`git-read-tree` +complains loudly and fails without modifying anything). In such +a case, you can simply continue doing what you were in the +middle of doing, and when your working tree is ready (i.e. you +have finished your work-in-progress), attempt the merge again. + See Also --------