Re: [RFC PATCH] Revamp git-cherry(1)

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 21, 2013, 19:26 UTC
Message-ID: <xmqqli0h4kvj.fsf@gitster.dls.corp.google.com>
In-Reply-To: <3af3069696e3a59d513f1fef0ca797d103f6d882.1385033403.git.tr@thomasrast.ch>

Thomas Rast <tr@thomasrast.ch> writes:

>  NAME
>  ----
> -git-cherry - Find commits not merged upstream
> +git-cherry - Find commits not applied in upstream

Good.

Show 11 quoted lines

> +Determine whether there are commits in `<head>..<upstream>` that are
> +equivalent to those in the range `<limit>..<head>`.
>  
> +The equivalence test is based on the diff, after removing whitespace
> +and line numbers.  git-cherry therefore detects when commits have been
> +"copied" by means of linkgit:git-cherry-pick[1], linkgit:git-am[1] or
> +linkgit:git-rebase[1].
>  
> +Outputs the SHA1 of every commit in `<limit>..<head>`, prefixed with
> +`-` for commits that have an equivalent in <upstream>, and `+` for
> +commits that do not.

Yeah, short-sweet-and-sufficient.

Show 6 quoted lines

>  OPTIONS
>  -------
>  -v::
> -	Verbose.
> +	Verbose.  Currently shows the commit subjects next to their
> +	SHA1.

Whenever I see "Currently", it makes me wonder "why does it need to say that? Is there a plan to change it soon, and if so where is the plan described?".

Show 8 quoted lines

> +EXAMPLES
> +--------
> +
> +git-cherry is frequently used in patch-based workflows (see
> +linkgit:gitworkflows[7]) to determine if a series of patches has been
> +applied by the upstream maintainer.  In such a workflow you might
> +create and send a topic branch like this (fill in appropriate
> +arguments for `...`):

I think the ASCII art commit graph that shows topology which we lost by this patch gave a more intiutive sense of what "a topic branch like this" looked like than an incomplete skeleton of a command sequence that would be understood by those who already know how to work with multiple branches. Perhaps we want both?

Thanks.

Show 7 quoted lines

> ++
> +------------
> +git checkout -b topic origin/master
> +# work and create some commits
> +git format-patch origin/master
> +git send-email ... 00*
> +------------

Show 15 quoted lines

> +Later, you can whether your changes have been applied by saying (still
> +on `topic`):
> ++
> +------------
> +git fetch  # update your notion of origin/master
> +git cherry -v
> +------------
> ++
> +Note that this uses , and assumes that
> +`core.autosetupmerge` is enabled (the default).
> +
> +
>  SEE ALSO
>  --------
>  linkgit:git-patch-id[1]