Autogenerated HTML docs for v1.5.6.4-433-g09651

1 files changed, 40 insertions, 50 deletions

diff --git a/git-merge.html b/git-merge.html
index 46166165c..1e0bf58a0 100644
--- a/git-merge.html
+++ b/git-merge.html
@@ -657,52 +657,41 @@ branch.<name>.mergeoptions
 <div class="sectionbody">

 <div class="para"><p>A merge is always between the current <tt>HEAD</tt> and one or more

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

-exactly match the

-tree of <tt>HEAD</tt> commit (i.e. the contents of the last commit) when

-it happens.  In other words, <tt>git diff --cached HEAD</tt> must

-report no changes.</p></div>

-<div class="admonitionblock">

-<table><tr>

-<td class="icon">

-<div class="title">Note</div>

-</td>

-<td class="content">This is a bit of a lie.  In certain special cases, your index is

-allowed to be different from the tree of the <tt>HEAD</tt> commit.  The most

-notable case is when your <tt>HEAD</tt> commit is already ahead of what

-is being merged, in which case your index can have arbitrary

-differences from your <tt>HEAD</tt> commit.  Also, your index entries

-may have differences from your <tt>HEAD</tt> 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.</td>

-</tr></table>

-</div>

-<div class="para"><p>Otherwise, merge will refuse to do any harm to your repository

-(that is, it may fetch the objects from remote, and it may even

-update the local branch used to keep track of the remote branch

-with <tt>git pull remote rbranch:lbranch</tt>, but your working tree,

-<tt>.git/HEAD</tt> pointer and index file are left intact).  In addition,

-merge always sets <tt>.git/ORIG_HEAD</tt> to the original state of HEAD so

-a problematic merge can be removed by using <tt>git reset ORIG_HEAD</tt>.</p></div>

-<div class="para"><p>You may have local modifications in the working tree files.  In

-other words, <em>git-diff</em> is allowed to report changes.

-However, the merge uses your working tree as the working area,

-and in order to prevent the merge operation from losing such

-changes, it makes sure that they do not interfere with the

-merge. Those complex tables in read-tree documentation define

-what it means for a path to "interfere with the merge".  And if

-your local modifications interfere with the merge, again, it

-stops before touching anything.</p></div>

-<div class="para"><p>So in the above two "failed merge" case, you do not have to

-worry about loss of data --- you simply were not ready to do

-a merge, so no merge happened at all.  You may want to finish

-whatever you were in the middle of doing, and retry the same

-pull after you are done and ready.</p></div>

-<div class="para"><p>When things cleanly merge, these things happen:</p></div>

+match the tree of <tt>HEAD</tt> commit (i.e. the contents of the last commit)

+when it starts out.  In other words, <tt>git diff --cached HEAD</tt> 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.)</p></div>

+<div class="para"><p>Three kinds of merge can happen:</p></div>

+<div class="ilist"><ul>

+<li>

+<p>

+The merged commit is already contained in <tt>HEAD</tt>. This is the

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

+</p>

+</li>

+<li>

+<p>

+<tt>HEAD</tt> is already contained in the merged commit. This is the

+  most common case especially when involved through <em>git pull</em>:

+  you are tracking an upstream repository, committed no local

+  changes and now you want to update to a newer upstream revision.

+  Your <tt>HEAD</tt> (and the index) is updated to at point the merged

+  commit, without creating an extra merge commit.  This is

+  called "Fast-forward".

+</p>

+</li>

+<li>

+<p>

+Both the merged commit and <tt>HEAD</tt> are independent and must be

+  tied together by a merge commit that has them both as its parents.

+  The rest of this section describes this "True merge" case.

+</p>

+</li>

+</ul></div>

+<div class="para"><p>The chosen merge strategy merges the two commits into a single

+new source tree.

+When things cleanly merge, these things happen:</p></div>

 <div class="olist"><ol>

 <li>

 <p>

@@ -773,15 +762,16 @@ No other changes are done.  In particular, the local
 <p>

 Decide not to merge.  The only clean-up you need are to reset

    the index file to the <tt>HEAD</tt> commit to reverse 2. and to clean

-   up working tree changes made by 2. and 3.; <em>git-reset</em> can

+   up working tree changes made by 2. and 3.; <em>git-reset --hard</em> can

    be used for this.

 </p>

 </li>

 <li>

 <p>

 Resolve the conflicts.  <tt>git diff</tt> would report only the

-   conflicting paths because of the above 2. and 3.  Edit the

-   working tree files into a desirable shape, <em>git-add</em> or <em>git-rm</em>

+   conflicting paths because of the above 2. and 3.

+   Edit the working tree files into a desirable shape

+   (<em>git mergetool</em> can ease this task), <em>git-add</em> or <em>git-rm</em>

    them, to make the index file contain what the merge result

    should be, and run <em>git-commit</em> to commit the result.

 </p>

@@ -811,7 +801,7 @@ Resolve the conflicts.  <tt>git diff</tt> would report only the
 </div>

 <div id="footer">

 <div id="footer-text">

-Last updated 2008-07-15 15:48:34 UTC

+Last updated 2008-07-20 01:23:33 UTC

 </div>

 </div>

 </body>