Re: [PATCH] Documentation: 'cherry' does not cope well with merges from upstream

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 1, 2010, 23:52 UTC
Message-ID: <7vbpaq3glt.fsf@alter.siamese.dyndns.org>
In-Reply-To: <20100701210919.GA4283@burratino>

Jonathan Nieder <jrnieder@gmail.com> writes:

Show 20 quoted lines

> Example:
>
>  o---o---F---X'---G---U [upstream]
>           \        \
>            X----Y---M---T [topic]
>
> Suppose the author of the ‘topic’ branch starts from upstream
> commit F and makes a few changes.  One is applied upstream, and
> additionally there is some other useful upstream change, so he
> performs a merge to include the upstream updates into topic.
> The expected output from ‘cherry’ is:
>
>  + T
>  + Y
>  - X
>
> Consider the author of a different branch, also called ‘topic’, but
> this one starts from commit G.  Some infrastructure from an existing 
> branch is needed, so first she merges that.  Then she adds her own
> commit.

Sorry, but it is unclear to me what kind of history you have in mind at this point. What "existing branch" are you talking about? Presumably it is not the [topic] in an earlier example, nor it is [upstream] right?

o---o---o---o----G-------.---U [upstream]
                  \       \ 
                   X---Y---M---T

Something like this?

Show 11 quoted lines

> The expected output from ‘cherry’ is:
>
>  + T
>  + Y
>  + X
>
> since none of the new commits have been applied upstream since
> the fork point.
>
> ‘cherry’ cannot distinguish between these two cases, in part because
> it does not distinguish between parents in a merge commit.

Now you completely lost me. I guess the biggest reason is you only talk about "the expected output" without talking about "what it actually gives". Hence it is unclear what the significant difference "between these two cases" you are trying to stress here.

> Thoughts?  Improvements?

I think the actual patch text has the same problem. You say "these commits" without saying which ones they are; perhaps saing "the commits represented by asterisks in the picture" or something may help, but I dunno.