[PATCH 7/8] 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>
---
Documentation/git-cherry-pick.txt | 64 +++++++++++++++++++++++++++++--------
1 files changed, 50 insertions(+), 14 deletions(-)
diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt
index d71607a..df2742a 100644
--- a/Documentation/git-cherry-pick.txt
+++ b/Documentation/git-cherry-pick.txt
@@ -3,24 +3,29 @@ git-cherry-pick(1)
NAME
----
-git-cherry-pick - Apply the change introduced by an existing commit
+git-cherry-pick - Apply the change 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 changes that the related
+patches introduce, and record some new commits that record them. 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 also be given but no traversal is done
+ by default, see linkgit:git-rev-list[1] and its '--no-walk'
+ option.
-e::
--edit::
@@ -55,13 +60,12 @@ 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
- 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.
+ Usually the command automatically creates some commits. This
+ flag applies the change necessary to cherry-pick the named
+ commits to your working tree and the index, but does not make
+ the commits. 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.
+
This is useful when cherry-picking more than one commits'
effect to your index in a row.
@@ -75,6 +79,38 @@ 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 changes specified by the commit pointed to by master
+ and create a new commit with these changes.
+
+git cherry-pick master~3..master::
+git cherry-pick ^master~3 master::
+
+ Apply the changes specified by the last 3 commits pointed to
+ by master and create 3 new commits with these changes.
+
+git cherry-pick master\~3 master~2::
+
+ Apply the changes specified by the fourth 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 specified
+ 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 possible fast forward to the existing commits already in
+ next but not in HEAD, otherwise apply the changes specified by
+ these commits and create new commits with these changes.
+
Author
------
Written by Junio C Hamano <gitster@pobox.com>
--
1.7.1.361.g42de.dirty
Christian Couder <chriscool@tuxfamily.org>