Documentation/git-merge.txt: Partial rewrite of How Merge Works

The git-merge documentation's "HOW MERGE WORKS" section is confusingly
composed and actually omits the most interesting part, the merging of
the arguments into HEAD itself, surprisingly not actually mentioning
the fast-forward merge anywhere.

This patch replaces the "[NOTE]" screenful of highly technical details
by a single sentence summing up the interesting information, and instead
explains how are the arguments compared with HEAD and the three possible
inclusion states that are named "Already up-to-date", "Fast-forward"
and "True merge". It also makes it clear that the rest of the section
talks only about the true merge situation, and slightly expands the
talk on solving conflicts.

Junio initiated the removal of the Note screenful altogether and
offered many stylistical fixes.

Signed-off-by: Petr Baudis <pasky@suse.cz>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

Documentation/git-merge.txt

@@ -57,50 +57,31 @@ 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
-exactly match the
+match the tree of `HEAD` commit (i.e. the contents of the last commit)
-tree of `HEAD` commit (i.e. the contents of the last commit) when
+when it starts out.  In other words, `git diff --cached HEAD` must
-it happens.  In other words, `git diff --cached HEAD` must
+report no changes.  (One exception is when the changed index
-report no changes.
+entries are already in the same state that would result from
+the merge anyway.)
 
-[NOTE]
+Three kinds of merge can happen:
-This is a bit of a lie.  In certain special cases, your index is
-allowed to be different from the tree of the `HEAD` commit.  The most
-notable case is when your `HEAD` commit is already ahead of what
-is being merged, in which case your index can have arbitrary
-differences from your `HEAD` commit.  Also, your index entries
-may have differences from your `HEAD` commit that match
-the result of a trivial merge (e.g. you received the same patch
-from an external source to produce the same result as what you are
-merging).  For example, if a path did not exist in the common
-ancestor and your head commit but exists in the tree you are
-merging into your repository, and if you already happen to have
-that path exactly in your index, the merge does not have to
-fail.
 
-Otherwise, merge will refuse to do any harm to your repository
+* The merged commit is already contained in `HEAD`. This is the
-(that is, it may fetch the objects from remote, and it may even
+  simplest case, called "Already up-to-date."
-update the local branch used to keep track of the remote branch
-with `git pull remote rbranch:lbranch`, but your working tree,
-`.git/HEAD` pointer and index file are left intact).  In addition,
-merge always sets `.git/ORIG_HEAD` to the original state of HEAD so
-a problematic merge can be removed by using `git reset ORIG_HEAD`.
 
-You may have local modifications in the working tree files.  In
+* `HEAD` is already contained in the merged commit. This is the
-other words, 'git-diff' is allowed to report changes.
+  most common case especially when involved through 'git pull':
-However, the merge uses your working tree as the working area,
+  you are tracking an upstream repository, committed no local
-and in order to prevent the merge operation from losing such
+  changes and now you want to update to a newer upstream revision.
-changes, it makes sure that they do not interfere with the
+  Your `HEAD` (and the index) is updated to at point the merged
-merge. Those complex tables in read-tree documentation define
+  commit, without creating an extra merge commit.  This is
-what it means for a path to "interfere with the merge".  And if
+  called "Fast-forward".
-your local modifications interfere with the merge, again, it
-stops before touching anything.
 
-So in the above two "failed merge" case, you do not have to
+* Both the merged commit and `HEAD` are independent and must be
-worry about loss of data --- you simply were not ready to do
+  tied together by a merge commit that has them both as its parents.
-a merge, so no merge happened at all.  You may want to finish
+  The rest of this section describes this "True merge" case.
-whatever you were in the middle of doing, and retry the same
-pull after you are done and ready.
 
+The chosen merge strategy merges the two commits into a single
+new source tree.
 When things cleanly merge, these things happen:
 
 1. The results are updated both in the index file and in your
@@ -142,12 +123,13 @@ After seeing a conflict, you can do two things:
 
  * Decide not to merge.  The only clean-up you need are to reset
    the index file to the `HEAD` commit to reverse 2. and to clean
-   up working tree changes made by 2. and 3.; 'git-reset' can
+   up working tree changes made by 2. and 3.; 'git-reset --hard' can
    be used for this.
 
  * Resolve the conflicts.  `git diff` would report only the
-   conflicting paths because of the above 2. and 3.  Edit the
+   conflicting paths because of the above 2. and 3.
-   working tree files into a desirable shape, 'git-add' or 'git-rm'
+   Edit the working tree files into a desirable shape
+   ('git mergetool' can ease this task), 'git-add' or 'git-rm'
    them, to make the index file contain what the merge result
    should be, and run 'git-commit' to commit the result.