From: Petr Baudis <pasky@suse•cz>
To: Junio C Hamano <gitster@pobox•com>
Cc: git@vger•kernel.org
Subject: Re: [PATCH] Documentation/git-merge.txt: Expand the How Merge Works section
Date: Thu, 17 Jul 2008 20:54:51 +0200 [thread overview]
Message-ID: <20080717185451.GJ10151@machine.or.cz> (raw)
In-Reply-To: <7v3am8gytp.fsf@gitster.siamese.dyndns.org>
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 <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
^ at
> commit, without creating an extra merge commit. This is
> called "Fast-forward".
Yes, that is better.
> > +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.
> > +... 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.
> > +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
next prev parent reply other threads:[~2008-07-17 18:55 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
2008-07-17 16:29 [PATCH] Documentation/git-merge.txt: Expand the How Merge Works section Petr Baudis
2008-07-17 16:42 ` Petr Baudis
2008-07-17 18:17 ` Junio C Hamano
2008-07-17 18:54 ` Petr Baudis [this message]
2008-07-17 19:34 ` Junio C Hamano
2008-07-18 13:18 ` Petr Baudis
2008-07-18 13:20 ` [PATCH] Documentation/git-merge.txt: Partial rewrite of How Merge Works Petr Baudis
2008-07-19 0:32 ` [PATCH] Documentation/git-merge.txt: Expand the How Merge Works section Junio C Hamano
2008-07-19 18:17 ` [PATCH] Documentation/git-merge.txt: Partial rewrite of How Merge Works Petr Baudis
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20080717185451.GJ10151@machine.or.cz \
--to=pasky@suse$(echo .)cz \
--cc=git@vger$(echo .)kernel.org \
--cc=gitster@pobox$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox