Re: [PATCH] Documentation/git-merge.txt: Expand the How Merge Works section

  Hi,

  I'm not sure if I should resend the updated patch, or if you already
included your comments yourself.

On Thu, Jul 17, 2008 at 11:17:22AM -0700, Junio C Hamano wrote:

Petr Baudis [off-list ref] writes:

quoted

+* `HEAD` is already contained in the merged commit. This is the
+  most common case especially when involved through 'git pull':
+  you are tracking an upstream repository, committed no local
+  changes and now you want to update to a newer upstream revision.
+  So-called "fast-forward merge" is performed, simply repointing
+  your `HEAD` (and index) to the merged commit; no extra merge
+  commit is created.

I'd suggest rewording the last three lines:

	Your `HEAD` (and the index) is updated to point the merged

							^ at

        commit, without creating an extra merge commit.  This is
        called "Fast-forward".

  Yes, that is better.

quoted

+Pre-flight requirements note
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+In certain special cases, your index is
+allowed to be different from the tree of the `HEAD` commit.

Now this paragraph is moved far away from the original context that said
"your index must be clean before you start your merge", you would need to
re-introduce that in this sentenece:

	... tree of the `HEAD` before you run 'git-merge'.

  Done.

  I have to admit that I didn't even carefully read the rest of this
subsection, but I agree that we might as well update it when moving it
around already.

quoted

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

I originally wrote the above paragraph purely for completeness, but I
wonder if this happens a lot in practice.  This is not something the user
can easily anticipate anyway, so we might want to drop this.

  I think that we can expect only users that have real interest in these
details to read through this, so I would keep it for the completeness.

quoted

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

I am not sure what two cases we were describing.  It could be that this
paragraph was taken from a mailing list message responding to a question
(e.g. "I got this merge failure message and my tree is screwed up.  Please
help me get back to a good state, I am lost...") without copying the
original sample failure scenario.

  Yes, I got confused by this too. I would perhaps simply drop this
paragraph altogether.

-- 
				Petr "Pasky" Baudis
GNU, n. An animal of South Africa, which in its domesticated state
resembles a horse, a buffalo and a stag. In its wild condition it is
something like a thunderbolt, an earthquake and a cyclone. -- A. Pierce