From 30f2bade84a3f6961b38579c1c23c64b72f64f24 Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Sat, 23 Jan 2010 03:44:17 -0600 Subject: [PATCH] Documentation: emphasize when git merge terminates early A merge-based operation in git can fail in two ways: one that stops before touching anything, or one that goes ahead and results in conflicts. As the 'git merge' manual explains: | A merge is always between the current `HEAD` and one or more | commits (usually, branch head or tag), and the index file must | match the tree of `HEAD` commit (i.e. the contents of the last commit) | when it starts out. Unfortunately, the placement of this sentence makes it easy to skip over, and its formulation leaves the important point, that any other attempted merge will be gracefully aborted, unspoken. So give this point its own section and expand upon it. Probably this could be simplified somewhat: after all, a change registered in the index is just a special kind of local uncommited change, so the second added paragraph is only a special case of the first. It seemed more helpful to be explicit here. Inspired by . Signed-off-by: Jonathan Nieder Signed-off-by: Thomas Rast --- Documentation/git-merge.txt | 31 +++++++++++++++++++++---------- 1 file changed, 21 insertions(+), 10 deletions(-) diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index e3c611dd0e..6acee231ba 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -67,21 +67,32 @@ include::merge-options.txt[] obviously means you are trying an Octopus. +PRE-MERGE CHECKS +---------------- + +Before applying outside changes, you should get your own work in +good shape and committed locally, so it will not be clobbered if +there are conflicts. See also linkgit:git-stash[1]. +'git pull' and 'git merge' will stop without doing anything when +local uncommitted changes overlap with files that 'git pull'/'git +merge' may need to update. + +To avoid recording unrelated changes in the merge commit, +'git pull' and 'git merge' will also abort if there are any changes +registered in the index relative to the `HEAD` commit. (One +exception is when the changed index entries are in the state that +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." + HOW MERGE WORKS --------------- A merge is always between the current `HEAD` and one or more -commits (usually, branch head or tag), and the index file must -match the tree of `HEAD` commit (i.e. the contents of the last commit) -when it starts out. In other words, `git diff --cached HEAD` must -report no changes. (One exception is when the changed index -entries are already in the same state that would result from -the merge anyway.) - -Three kinds of merge can happen: +commits (usually a branch head or tag). -* The merged commit is already contained in `HEAD`. This is the - simplest case, called "Already up-to-date." +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':