Documentation/git-merge.txt: Partial rewrite of How Merge Works
The git-merge documentation's "HOW MERGE WORKS" section is confusingly composed and actually omits the most interesting part, the merging of the arguments into HEAD itself, surprisingly not actually mentioning the fast-forward merge anywhere. This patch replaces the "[NOTE]" screenful of highly technical details by a single sentence summing up the interesting information, and instead explains how are the arguments compared with HEAD and the three possible inclusion states that are named "Already up-to-date", "Fast-forward" and "True merge". It also makes it clear that the rest of the section talks only about the true merge situation, and slightly expands the talk on solving conflicts. Junio initiated the removal of the Note screenful altogether and offered many stylistical fixes. Signed-off-by: Petr Baudis <pasky@suse.cz> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Petr Baudis committed
Jul 19, 2008 at 20:17 UTC
c0be8aa06b85f3f18fd4c49dfbda14c2943ccda7
1 file changed
+29
-47
Documentation/git-merge.txt
+29
-47
@@ -57,50 +57,31 @@ HOW MERGE WORKS
57
58
A merge is always between the current `HEAD` and one or more
59
commits (usually, branch head or tag), and the index file must
60
-exactly match the
61
-tree of `HEAD` commit (i.e. the contents of the last commit) when
62
-it happens. In other words, `git diff --cached HEAD` must
63
-report no changes.
64
-
65
-[NOTE]
66
-This is a bit of a lie. In certain special cases, your index is
67
-allowed to be different from the tree of the `HEAD` commit. The most
68
-notable case is when your `HEAD` commit is already ahead of what
69
-is being merged, in which case your index can have arbitrary
70
-differences from your `HEAD` commit. Also, your index entries
71
-may have differences from your `HEAD` commit that match
72
-the result of a trivial merge (e.g. you received the same patch
73
-from an external source to produce the same result as what you are
74
-merging). For example, if a path did not exist in the common
75
-ancestor and your head commit but exists in the tree you are
76
-merging into your repository, and if you already happen to have
77
-that path exactly in your index, the merge does not have to
78
-fail.
79
-
80
-Otherwise, merge will refuse to do any harm to your repository
81
-(that is, it may fetch the objects from remote, and it may even
82
-update the local branch used to keep track of the remote branch
83
-with `git pull remote rbranch:lbranch`, but your working tree,
84
-`.git/HEAD` pointer and index file are left intact). In addition,
85
-merge always sets `.git/ORIG_HEAD` to the original state of HEAD so
86
-a problematic merge can be removed by using `git reset ORIG_HEAD`.
87
-
88
-You may have local modifications in the working tree files. In
89
-other words, 'git-diff' is allowed to report changes.
90
-However, the merge uses your working tree as the working area,
91
-and in order to prevent the merge operation from losing such
92
-changes, it makes sure that they do not interfere with the
93
-merge. Those complex tables in read-tree documentation define
94
-what it means for a path to "interfere with the merge". And if
95
-your local modifications interfere with the merge, again, it
96
-stops before touching anything.
97
-
98
-So in the above two "failed merge" case, you do not have to
99
-worry about loss of data --- you simply were not ready to do
100
-a merge, so no merge happened at all. You may want to finish
101
-whatever you were in the middle of doing, and retry the same
102
-pull after you are done and ready.
103
-
60
+match the tree of `HEAD` commit (i.e. the contents of the last commit)
61
+when it starts out. In other words, `git diff --cached HEAD` must
62
+report no changes. (One exception is when the changed index
63
+entries are already in the same state that would result from
64
+the merge anyway.)
65
+
66
+Three kinds of merge can happen:
67
+
68
+* The merged commit is already contained in `HEAD`. This is the
69
+ simplest case, called "Already up-to-date."
70
+
71
+* `HEAD` is already contained in the merged commit. This is the
72
+ most common case especially when involved through 'git pull':
73
+ you are tracking an upstream repository, committed no local
74
+ changes and now you want to update to a newer upstream revision.
75
+ Your `HEAD` (and the index) is updated to at point the merged
76
+ commit, without creating an extra merge commit. This is
77
+ called "Fast-forward".
78
+
79
+* Both the merged commit and `HEAD` are independent and must be
80
+ tied together by a merge commit that has them both as its parents.
81
+ The rest of this section describes this "True merge" case.
82
+
83
+The chosen merge strategy merges the two commits into a single
84
+new source tree.
85
When things cleanly merge, these things happen:
86
87
1. The results are updated both in the index file and in your
@@ -142,12 +123,13 @@ After seeing a conflict, you can do two things:
123
124
* Decide not to merge. The only clean-up you need are to reset
125
the index file to the `HEAD` commit to reverse 2. and to clean
145
- up working tree changes made by 2. and 3.; 'git-reset' can
126
+ up working tree changes made by 2. and 3.; 'git-reset --hard' can
127
be used for this.
128
129
* Resolve the conflicts. `git diff` would report only the
149
- conflicting paths because of the above 2. and 3. Edit the
150
- working tree files into a desirable shape, 'git-add' or 'git-rm'
130
+ conflicting paths because of the above 2. and 3.
131
+ Edit the working tree files into a desirable shape
132
+ ('git mergetool' can ease this task), 'git-add' or 'git-rm'
133
them, to make the index file contain what the merge result
134
should be, and run 'git-commit' to commit the result.
135