From 29280311f0282857360add2b49db5fc7148d4813 Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Sat, 23 Jan 2010 03:45:33 -0600 Subject: [PATCH] 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 Signed-off-by: Thomas Rast --- Documentation/git-merge.txt | 31 ++++++++++++++++++------------- 1 file changed, 18 insertions(+), 13 deletions(-) diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 6acee231b..6bebada97 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -86,25 +86,30 @@ would result from the merge already.) If all named commits are already ancestors of `HEAD`, 'git merge' will exit early with the message "Already up-to-date." +FAST-FORWARD MERGE +------------------ + +Often the current branch head is an ancestor of the named commit. +This is the most common case especially when invoked from 'git +pull': you are tracking an upstream repository, you have committed +no local changes, and now you want to update to a newer upstream +revision. In this case, a new commit is not needed to store the +combined history; instead, the `HEAD` (along with the index) is +updated to point at the named commit, without creating an extra +merge commit. + +This behavior can be suppressed with the `--no-ff` option. + HOW MERGE WORKS --------------- A merge is always between the current `HEAD` and one or more commits (usually a branch head or tag). -Two kinds of merge can happen: - -* `HEAD` is already contained in the merged commit. This is the - most common case especially when invoked from 'git pull': - you are tracking an upstream repository, have committed no local - changes and now you want to update to a newer upstream revision. - Your `HEAD` (and the index) is updated to point at the merged - commit, without creating an extra merge commit. This is - called "Fast-forward". - -* Both the merged commit and `HEAD` are independent and must be - tied together by a merge commit that has both of them as its parents. - The rest of this section describes this "True merge" case. +Except in a fast-forward merge (see above), the branches to be +merged must be tied together by a merge commit that has both of them +as its parents. +The rest of this section describes this "True merge" case. The chosen merge strategy merges the two commits into a single new source tree. -- 2.30.2