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:
Show 12 quoted lines
> Petr Baudis <pasky@suse.cz> writes:
> > +* `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
> commit, without creating an extra merge commit. This is
> called "Fast-forward".
Show 10 quoted lines
> > +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.
Show 13 quoted lines
> > +... 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.
Show 11 quoted lines
> > +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
Petr Baudis <pasky@suse.cz>