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 <http://gitster.livejournal.com/25801.html>. 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:44 UTC 30f2bade84a3f6961b38579c1c23c64b72f64f24

1 file changed +21 -10

Documentation/git-merge.txt

+21 -10

@@ -67,21 +67,32 @@ include::merge-options.txt[]

67 <commit> obviously means you are trying an Octopus.

70 +PRE-MERGE CHECKS

71 +----------------

72 +

73 +Before applying outside changes, you should get your own work in

74 +good shape and committed locally, so it will not be clobbered if

75 +there are conflicts. See also linkgit:git-stash[1].

76 +'git pull' and 'git merge' will stop without doing anything when

77 +local uncommitted changes overlap with files that 'git pull'/'git

78 +merge' may need to update.

79 +

80 +To avoid recording unrelated changes in the merge commit,

81 +'git pull' and 'git merge' will also abort if there are any changes

82 +registered in the index relative to the `HEAD` commit. (One

83 +exception is when the changed index entries are in the state that

84 +would result from the merge already.)

85 +

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 HOW MERGE WORKS

90 ---------------

92 A merge is always between the current `HEAD` and one or more

74 -commits (usually, branch head or tag), and the index file must

75 -match the tree of `HEAD` commit (i.e. the contents of the last commit)

76 -when it starts out. In other words, `git diff --cached HEAD` must

77 -report no changes. (One exception is when the changed index

78 -entries are already in the same state that would result from

79 -the merge anyway.)

80 -

81 -Three kinds of merge can happen:

93 +commits (usually a branch head or tag).

83 -* The merged commit is already contained in `HEAD`. This is the

84 - simplest case, called "Already up-to-date."

95 +Two kinds of merge can happen:

97 * `HEAD` is already contained in the merged commit. This is the

98 most common case especially when invoked from 'git pull':