[PATCH 6/6] Documentation: tweak How Merge Works

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Jan 11, 2010, 08:43 UTC
Message-ID: <20100111084355.GF23806@progeny.tock>
In-Reply-To: <20100111082123.GA23742@progeny.tock>

Change heading to TRUE MERGE. The whole manual page is about how merges work.

Start to explain what it means to merge two commits into a single tree.

Do not assume the commits named on the 'git merge' command line come from another repository. For simplicity, still assume they are branch heads for now, though.

Do not give start any list items with `code`; a toolchain bug makes the resulting nroff look wrong.

Recommend reset --merged for safely cancelling a failed merge.

Cc: Petr Baudis <pasky@suse.cz>
Cc: Junio C Hamano <gitster@pobox.com>
Cc: Thomas Rast <trast@student.ethz.ch>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/git-merge.txt |   56 +++++++++++++++++++-----------------------
 1 files changed, 25 insertions(+), 31 deletions(-)

diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index ec9c6d3..7ae0f65 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -96,62 +96,56 @@ merge commit.
 
 This behavior can be suppressed with the `--no-ff` option.
 
-include::merge-strategies.txt[]
-
-
-If you tried a merge which resulted in complex conflicts and
-want to start over, you can recover with 'git-reset'.
-
-HOW MERGE WORKS
----------------
-
-A merge is always between the current `HEAD` and one or more
-commits (usually, branch head or tag).
+TRUE MERGE
+----------
 
 Except in a fast-forward merge (see above), the branches to be
 merged must be tied together by a merge commit that has both of them
 as its parents.
 The rest of this section describes this "True merge" case.
 
-The chosen merge strategy merges the two commits into a single
-new source tree.
 When things merge cleanly, this is what happens:
 
-1. The results are updated both in the index file and in your
-   working tree;
-2. Index file is written out as a tree;
+1. A version reconciling the changes from all branches to be
+   merged is written to the index file and your working tree;
+2. The index file is written out as a tree;
 3. The tree gets committed; and
 4. The `HEAD` pointer gets advanced.
 
 Because of 2., we require that the original state of the index
 file matches exactly the current `HEAD` commit; otherwise we
-will write out your local changes already registered in your
+would write out your local changes already registered in your
 index file along with the merge result, which is not good.
 Because 1. involves only those paths differing between your
-branch and the remote branch you are pulling from during the
-merge (which is typically a fraction of the whole tree), you can
-have local modifications in your working tree as long as they do
-not overlap with what the merge updates.
-
-When there are conflicts, the following happens:
+branch and the other branches (which is typically a fraction of
+the whole tree), you can have local modifications in your
+working tree as long as they do not overlap with what the merge
+updates.
 
-1. `HEAD` stays the same.
+When it is not obvious how to reconcile the changes, the following
+happens:
 
-2. Cleanly merged paths are updated both in the index file and
+1. The `HEAD` pointer stays the same.
+2. The `MERGE_HEAD` ref is set to point to the other branch head.
+3. Paths that merged cleanly are updated both in the index file and
    in your working tree.
-
-3. For conflicting paths, the index file records up to three
+4. For conflicting paths, the index file records up to three
    versions; stage1 stores the version from the common ancestor,
-   stage2 from `HEAD`, and stage3 from the remote branch (you
+   stage2 from `HEAD`, and stage3 from `MERGE_HEAD` (you
    can inspect the stages with `git ls-files -u`).  The working
    tree files contain the result of the "merge" program; i.e. 3-way
-   merge results with familiar conflict markers `<<< === >>>`.
-
-4. No other changes are done.  In particular, the local
+   merge results with familiar conflict markers `<<<` `===` `>>>`.
+5. No other changes are done.  In particular, the local
    modifications you had before you started merge will stay the
    same and the index entries for them stay as they were,
    i.e. matching `HEAD`.
 
+If you tried a merge which resulted in complex conflicts and
+want to start over, you can recover with `git reset --merged`.
+
+include::merge-strategies.txt[]
+
+
 HOW CONFLICTS ARE PRESENTED
 ---------------------------

-- 
1.6.6