Re: [PATCH 2/2] git-cherry-pick.txt: make clearer when revision walking gets activated

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 15, 2012, 17:52 UTC
Message-ID: <7vehpgbgyb.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1339770796-542-2-git-send-email-cmn@elego.de>

Carlos Martín Nieto <cmn@elego.de> writes:

Show 25 quoted lines

> When given a set of commits, cherry-pick will apply the changes for
> all of them. Specifying a simple range will also work as
> expected. This can cause the user to think that
>
>     git cherry-pick A B..C
>
> will apply A and then B..C. This is not what happens. Instead the revs
> are given to rev-list which will consider A and C as positive revs and
> B as a negative one. Add a note about this and add an example with
> this particular syntax, which has shown up on the list a few times.
>
> Signed-off-by: Carlos Martín Nieto <cmn@elego.de>
> ---
>  Documentation/git-cherry-pick.txt | 10 ++++++++++
>  1 file changed, 10 insertions(+)
>
> diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt
> index 06a0bfd..10abfbf 100644
> --- a/Documentation/git-cherry-pick.txt
> +++ b/Documentation/git-cherry-pick.txt
> @@ -48,6 +48,7 @@ OPTIONS
>  	Sets of commits can be passed but no traversal is done by
>  	default, as if the '--no-walk' option was specified, see
>  	linkgit:git-rev-list[1].
> +	Note that specifying a range will activate revision walking.

That is not wrong per-se, but I do not think it would have helped Yann. How about phrasing it this way?

	Note that specifying a range will feed all
	<commit>... arguments to a single revision walk (see a later
	example that uses 'maint master..next').

Show 12 quoted lines

> @@ -130,6 +131,15 @@ EXAMPLES
>  	Apply the changes introduced by all commits that are ancestors
>  	of master but not of HEAD to produce new commits.
>  
> +`git cherry-pick master next ^maint`::
> +`git cherry-pick master maint..next`::
> +
> +	Apply the changes introduced by all commits that are ancestors
> +	of master or next, but not maint or any of its ancestors. The
> +	second spelling is often a misunderstanding of revision
> +	walking works when trying to apply a range plus a particular
> +	commit and included for completeness.

If you are using these three branches because you expect familiarity with the convention of maint < master < next on the reader's side, I think it should be rewritten like this.

`git cherry-pick maint next ^master`:: `git cherry-pick maint master..next`::

	Apply the changes introduced by all commits that are
	ancestors of maint or next, but not master or any of its
	ancestors.  Note that the latter does not mean `maint` and
	everything between `master` and `next`; specifically,
	`maint` will not be used if it is included in `master`.