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

[Junio C Hamano <gitster@pobox.com>]

Petr Baudis <pasky@suse.cz> writes:

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

When I send my review comments out, I generally expect an updated version,
unless I explicitly say "will apply with tweaks, no need to resend".  I am
way too lazy to munge patches myself ;-) but more importantly, unlike
Linus, I am not perfect.  My comments are _not_ "I'll show you the right
way", but more often are "Here is what I think is better, but I may well
be wrong, in which case I want you to defend your position better so that
even I can understand why you are right".

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

I agree this does not belong to the same "advanced details" section that
talks about a theoretical corner case where the user:

 - has a perfect foresight,
 - applies (but not commits yet) a patch and stages the change,
 - keeps the working tree and the index dirty, and then
 - pulls from somewhere else in that dirty state,

knowing what will be merged has that exact same patch to trigger that
corner case logic (yes, I am strongly hinting to drop that description; it
is not even remotely interesting).

However, I think we may want to talk about "How to tell if your merge did
not even touch your index nor working tree" somewhere in the manual.
"When there are conflicts, these things happen" part talks about how to
resolve conflicts, but when merge refuses to avoid losing local changes,
the instruction in that part does not apply.