[PATCH 4/6] Documentation: emphasize when git merge terminates early

From

Jonathan Nieder <jrnieder@gmail.com>

Date

Jan 11, 2010, 08:37 UTC

Message-ID

<20100111083754.GD23806@progeny.tock>

In-Reply-To

<20100111082123.GA23742@progeny.tock>

A merge-based operation in git can fail in two ways:

 - One that stops before touching anything (either your index was
   dirty and nothing happened, or your index was clean but you
   had local modifications in your work tree).

 - Another that goes ahead and results in conflicts.

The 'git merge' manual explains half of the first case as follows:

| 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.

Cc: Petr Baudis <pasky@suse.cz>,
Cc: Junio C Hamano <gitster@pobox.com>
Cc: Thomas Rast <trast@student.ethz.ch>
Not-signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
This is not signed off because most of the text is from Junio’s
blog.  I hope that is okay.

 Documentation/git-merge.txt |   34 ++++++++++++++++++++++++----------
 1 files changed, 24 insertions(+), 10 deletions(-)

diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index e29bb97..8950aa4 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -60,6 +60,28 @@ include::merge-options.txt[]
 	least one <remote>.  Specifying more than one <remote>
 	obviously means you are trying an Octopus.
 
+PRE-MERGE CHECKS
+----------------
+
+In some other version control systems, you merge/update and then
+commit, with the risk of clobbering your changes with humongous
+conflicts. You shouldn't be pulling or merging if you haven't got
+your own work into good shape and committed it locally (see also
+linkgit:git-stash[1]).
+
+But novices can make this mistake, and '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.
+
+Also, to avoid unrelated changes in the recorded commit, 'git
+pull' and 'git merge' abort if there are any changes registered
+in the index relative to the contents of the `HEAD` commit.
+(One exception is when the changed index entries are already in
+the same state that would result from the merge anyway.)
+
+If all named commits are already ancestors of `HEAD`, 'git merge'
+will exit early with the message "Already up-to-date."
+
 include::merge-strategies.txt[]
 
 
@@ -70,17 +92,9 @@ 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, 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':

-- 
1.6.6