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

From: Jonathan Nieder <[email-masked]>
Date: Mon, 11 Jan 2010 02:37:54 -0600

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.

The placement of this sentence makes it easy to skip over, and
its formulation is perhaps too formal to be memorable.

So give this point its own section and expand upon it.  Most of
the added text is taken from <http://gitster.livejournal.com/25801.html>.

Cc: Petr Baudis <[email-masked]>,
Cc: Junio C Hamano <[email-masked]>
Cc: Thomas Rast <[email-masked]>
Not-signed-off-by: Jonathan Nieder <[email-masked]>
---
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