git-cherry-pick.txt: clarify the use of revision range notation

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 lead the user to think that

git cherry-pick A B..C

may apply A and then B..C, but that is not what happens.

Instead the revs are given to a single invocation of rev-list, which
will consider A and C as positive revs and B as a negative one.  The
commit A will not be used if it is an ancestor of B.

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>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt
index fed5097e00b4a031c2992ac3d421f6df975e6152..49ac61c3d02c2a1dd5111550f70f87cbd311c8f8 100644 (file)
--- a/Documentation/git-cherry-pick.txt
+++ b/Documentation/git-cherry-pick.txt
@@ -47,7 +47,9 @@ OPTIONS
        linkgit:gitrevisions[7].
        Sets of commits can be passed but no traversal is done by
        default, as if the '--no-walk' option was specified, see
        linkgit:gitrevisions[7].
        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].
+       linkgit:git-rev-list[1]. Note that specifying a range will
+       feed all <commit>... arguments to a single revision walk
+       (see a later example that uses 'maint master..next').

 
 -e::
 --edit::
 
 -e::
 --edit::


@@ -130,6 +132,15 @@ EXAMPLES
        Apply the changes introduced by all commits that are ancestors
        of master but not of HEAD to produce new commits.
 
        Apply the changes introduced by all commits that are ancestors
        of master but not of HEAD to produce new commits.
 

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

 `git cherry-pick master{tilde}4 master{tilde}2`::
 
        Apply the changes introduced by the fifth and third last
 `git cherry-pick master{tilde}4 master{tilde}2`::
 
        Apply the changes introduced by the fifth and third last