Documentation/cherry-pick: describe passing more than one commit

And while at it, add an "EXAMPLES" section.

Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt
index d71607a85d03062c76f7d17d4fd8e8b4168a279d..bcb4c758b748b53b7a990455bf4ef9d89f901079 100644 (file)
--- a/Documentation/git-cherry-pick.txt
+++ b/Documentation/git-cherry-pick.txt
@@ -3,24 +3,28 @@ git-cherry-pick(1)
 
 NAME
 ----
-git-cherry-pick - Apply the change introduced by an existing commit
+git-cherry-pick - Apply the changes introduced by some existing commits
 
 SYNOPSIS
 --------
-'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff] <commit>
+'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff] <commit>...
 
 DESCRIPTION
 -----------
-Given one existing commit, apply the change the patch introduces, and record a
-new commit that records it.  This requires your working tree to be clean (no
-modifications from the HEAD commit).
+
+Given one or more existing commits, apply the change each one
+introduces, recording a new commit for each.  This requires your
+working tree to be clean (no modifications from the HEAD commit).
 
 OPTIONS
 -------
-<commit>::
-       Commit to cherry-pick.
+<commit>...::
+       Commits to cherry-pick.
        For a more complete list of ways to spell commits, see the
        "SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1].
+       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].
 
 -e::
 --edit::
@@ -55,10 +59,10 @@ OPTIONS
 
 -n::
 --no-commit::
-       Usually the command automatically creates a commit.
-       This flag applies the change necessary to cherry-pick
-       the named commit to your working tree and the index,
-       but does not make the commit.  In addition, when this
+       Usually the command automatically creates a sequence of commits.
+       This flag applies the changes necessary to cherry-pick
+       each named commit to your working tree and the index,
+       without making any commit.  In addition, when this
        option is used, your index does not have to match the
        HEAD commit.  The cherry-pick is done against the
        beginning state of your index.
@@ -75,6 +79,40 @@ effect to your index in a row.
        cherry-pick'ed commit, then a fast forward to this commit will
        be performed.
 
+EXAMPLES
+--------
+git cherry-pick master::
+
+       Apply the change introduced by the commit at the tip of the
+       master branch and create a new commit with this change.
+
+git cherry-pick ..master::
+git cherry-pick ^HEAD master::
+
+       Apply the changes introduced by all commits that are ancestors
+       of master but not of HEAD to produce new commits.
+
+git cherry-pick master\~4 master~2::
+
+       Apply the changes introduced by the fifth and third last
+       commits pointed to by master and create 2 new commits with
+       these changes.
+
+git cherry-pick -n master~1 next::
+
+       Apply to the working tree and the index the changes introduced
+       by the second last commit pointed to by master and by the last
+       commit pointed to by next, but do not create any commit with
+       these changes.
+
+git cherry-pick --ff ..next::
+
+       If history is linear and HEAD is an ancestor of next, update
+       the working tree and advance the HEAD pointer to match next.
+       Otherwise, apply the changes introduced by those commits that
+       are in next but not HEAD to the current branch, creating a new
+       commit for each new change.
+
 Author
 ------
 Written by Junio C Hamano <gitster@pobox.com>
@@ -83,6 +121,10 @@ Documentation
 --------------
 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 
+SEE ALSO
+--------
+linkgit:git-revert[1]
+
 GIT
 ---
 Part of the linkgit:git[1] suite