Documentation: merge: add a section about fast-forward
Novices sometimes find the behavior of 'git merge' in the fast-forward case surprising. Describe it thoroughly. Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Thomas Rast <trast@student.ethz.ch>
Jonathan Nieder committed
Jan 23, 2010 at 03:45 UTC
29280311f0282857360add2b49db5fc7148d4813
1 file changed
+18
-13
Documentation/git-merge.txt
+18
-13
@@ -86,25 +86,30 @@ would result from the merge already.)
86
If all named commits are already ancestors of `HEAD`, 'git merge'
87
will exit early with the message "Already up-to-date."
88
89
+FAST-FORWARD MERGE
90
+------------------
91
+
92
+Often the current branch head is an ancestor of the named commit.
93
+This is the most common case especially when invoked from 'git
94
+pull': you are tracking an upstream repository, you have committed
95
+no local changes, and now you want to update to a newer upstream
96
+revision. In this case, a new commit is not needed to store the
97
+combined history; instead, the `HEAD` (along with the index) is
98
+updated to point at the named commit, without creating an extra
99
+merge commit.
100
+
101
+This behavior can be suppressed with the `--no-ff` option.
102
+
103
HOW MERGE WORKS
104
---------------
105
106
A merge is always between the current `HEAD` and one or more
107
commits (usually a branch head or tag).
108
95
-Two kinds of merge can happen:
96
-
97
-* `HEAD` is already contained in the merged commit. This is the
98
- most common case especially when invoked from 'git pull':
99
- you are tracking an upstream repository, have committed no local
100
- changes and now you want to update to a newer upstream revision.
101
- Your `HEAD` (and the index) is updated to point at the merged
102
- commit, without creating an extra merge commit. This is
103
- called "Fast-forward".
104
-
105
-* Both the merged commit and `HEAD` are independent and must be
106
- tied together by a merge commit that has both of them as its parents.
107
- The rest of this section describes this "True merge" case.
109
+Except in a fast-forward merge (see above), the branches to be
110
+merged must be tied together by a merge commit that has both of them
111
+as its parents.
112
+The rest of this section describes this "True merge" case.
113
114
The chosen merge strategy merges the two commits into a single
115
new source tree.