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] <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).
+
+When it is not obvious how to apply a change, the following
+happens:
+
+1. The current branch and `HEAD` pointer stay at the last commit
+ successfully made.
+2. The `CHERRY_PICK_HEAD` ref is set to point at the commit that
+ introduced the change that is difficult to apply.
+3. Paths in which the change applied cleanly are updated both
+ in the index file and in your working tree.
+4. For conflicting paths, the index file records up to three
+ versions, as described in the "TRUE MERGE" section of
+ linkgit:git-merge[1]. The working tree files will include
+ a description of the conflict bracketed by the usual
+ conflict markers `<<<<<<<` and `>>>>>>>`.
+5. No other modifications are made.
+
+See linkgit:git-merge[1] for some hints on resolving such
+conflicts.
OPTIONS
-------
-<commit>::
- Commit to cherry-pick.
- For a more complete list of ways to spell commits, see the
- "SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1].
+<commit>...::
+ Commits to cherry-pick.
+ For a more complete list of ways to spell commits, 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].
-e::
--edit::
message prior to committing.
-x::
- When recording the commit, append to the original commit
- message a note that indicates which commit this change
- was cherry-picked from. Append the note only for cherry
+ When recording the commit, append a line that says
+ "(cherry picked from commit ...)" to the original commit
+ message in order to indicate which commit this change was
+ cherry-picked from. This is done only for cherry
picks without conflicts. Do not use this option if
you are cherry-picking from your private branch because
the information is useless to the recipient. If on the
-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.
--signoff::
Add Signed-off-by line at the end of the commit message.
+--ff::
+ If the current HEAD is the same as the parent of the
+ cherry-pick'ed commit, then a fast forward to this commit will
+ be performed.
+
+--strategy=<strategy>::
+ Use the given merge strategy. Should only be used once.
+ See the MERGE STRATEGIES section in linkgit:git-merge[1]
+ for details.
+
+-X<option>::
+--strategy-option=<option>::
+ Pass the merge strategy-specific option through to the
+ merge strategy. See linkgit:git-merge[1] for details.
+
+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.
-Author
-------
-Written by Junio C Hamano <gitster@pobox.com>
+git cherry-pick master{tilde}4 master{tilde}2::
-Documentation
---------------
-Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
+ 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.
+
+git rev-list --reverse master \-- README | git cherry-pick -n --stdin::
+
+ Apply the changes introduced by all commits on the master
+ branch that touched README to the working tree and index,
+ so the result can be inspected and made into a single new
+ commit if suitable.
+
+The following sequence attempts to backport a patch, bails out because
+the code the patch applies to has changed too much, and then tries
+again, this time exercising more care about matching up context lines.
+
+------------
+$ git cherry-pick topic^ <1>
+$ git diff <2>
+$ git reset --merge ORIG_HEAD <3>
+$ git cherry-pick -Xpatience topic^ <4>
+------------
+<1> apply the change that would be shown by `git show topic^`.
+In this example, the patch does not apply cleanly, so
+information about the conflict is written to the index and
+working tree and no new commit results.
+<2> summarize changes to be reconciled
+<3> cancel the cherry-pick. In other words, return to the
+pre-cherry-pick state, preserving any local modifications you had in
+the working tree.
+<4> try to apply the change introduced by `topic^` again,
+spending extra time to avoid mistakes based on incorrectly matching
+context lines.
+
+SEE ALSO
+--------
+linkgit:git-revert[1]
GIT
---