blob: f1e6b2fd6d15809f5180fe705c3d571bf247ff1d [file] [log] [blame]
Junio C Hamano215a7ad2005-09-07 17:26:23 -07001git-cherry-pick(1)
2==================
Junio C Hamanode2b82c2005-08-28 03:01:09 -07003
4NAME
5----
Christian Couder89d32d32010-06-02 07:58:40 +02006git-cherry-pick - Apply the changes introduced by some existing commits
Junio C Hamanode2b82c2005-08-28 03:01:09 -07007
8SYNOPSIS
9--------
Martin von Zweigbergk7791a1d2011-07-01 22:38:26 -040010[verse]
Nicolas Vigier32535532014-01-24 00:50:58 +000011'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff]
12 [-S[<keyid>]] <commit>...
Ramkumar Ramachandra5a5d80f2011-08-04 16:09:15 +053013'git cherry-pick' --continue
Jonathan Niederf80a8722011-11-22 05:14:29 -060014'git cherry-pick' --quit
Jonathan Nieder539047c2011-11-22 19:27:21 -060015'git cherry-pick' --abort
Junio C Hamanode2b82c2005-08-28 03:01:09 -070016
17DESCRIPTION
18-----------
Christian Couder89d32d32010-06-02 07:58:40 +020019
20Given one or more existing commits, apply the change each one
21introduces, recording a new commit for each. This requires your
22working tree to be clean (no modifications from the HEAD commit).
Junio C Hamanode2b82c2005-08-28 03:01:09 -070023
Jay Soffiand7e5c0c2011-02-19 23:12:27 -050024When it is not obvious how to apply a change, the following
25happens:
26
271. The current branch and `HEAD` pointer stay at the last commit
28 successfully made.
292. The `CHERRY_PICK_HEAD` ref is set to point at the commit that
30 introduced the change that is difficult to apply.
313. Paths in which the change applied cleanly are updated both
32 in the index file and in your working tree.
334. For conflicting paths, the index file records up to three
34 versions, as described in the "TRUE MERGE" section of
35 linkgit:git-merge[1]. The working tree files will include
36 a description of the conflict bracketed by the usual
37 conflict markers `<<<<<<<` and `>>>>>>>`.
385. No other modifications are made.
39
40See linkgit:git-merge[1] for some hints on resolving such
41conflicts.
42
Junio C Hamanode2b82c2005-08-28 03:01:09 -070043OPTIONS
44-------
Christian Couder89d32d32010-06-02 07:58:40 +020045<commit>...::
46 Commits to cherry-pick.
Michael J Gruberf028cda2010-07-05 18:11:41 +020047 For a more complete list of ways to spell commits, see
Jonathan Nieder9d83e382010-10-11 11:03:32 -050048 linkgit:gitrevisions[7].
Christian Couder89d32d32010-06-02 07:58:40 +020049 Sets of commits can be passed but no traversal is done by
50 default, as if the '--no-walk' option was specified, see
Carlos Martín Nietob98878e2012-06-15 16:33:16 +020051 linkgit:git-rev-list[1]. Note that specifying a range will
52 feed all <commit>... arguments to a single revision walk
53 (see a later example that uses 'maint master..next').
Junio C Hamanode2b82c2005-08-28 03:01:09 -070054
Stephan Beyer32402402008-06-08 03:36:09 +020055-e::
56--edit::
Thomas Rast0b444cd2010-01-10 00:33:00 +010057 With this option, 'git cherry-pick' will let you edit the commit
Jim Meyering233808d2008-01-19 16:23:32 +010058 message prior to committing.
Petr Baudis8bf14d62005-11-26 23:12:44 +010059
Junio C Hamanoabd69702006-10-05 17:54:14 -070060-x::
Sebastian Schuberthbea7d162011-04-15 19:53:51 +020061 When recording the commit, append a line that says
62 "(cherry picked from commit ...)" to the original commit
63 message in order to indicate which commit this change was
64 cherry-picked from. This is done only for cherry
Ralf Wildenhuesdd8175f2007-10-21 11:36:19 +020065 picks without conflicts. Do not use this option if
66 you are cherry-picking from your private branch because
67 the information is useless to the recipient. If on the
Junio C Hamanoabd69702006-10-05 17:54:14 -070068 other hand you are cherry-picking between two publicly
69 visible branches (e.g. backporting a fix to a
70 maintenance branch for an older release from a
71 development branch), adding this information can be
72 useful.
73
Andrew Ruder6b046002007-04-18 22:03:26 -050074-r::
Junio C Hamanoabd69702006-10-05 17:54:14 -070075 It used to be that the command defaulted to do `-x`
76 described above, and `-r` was to disable it. Now the
77 default is not to do `-x` so this option is a no-op.
Junio C Hamanode2b82c2005-08-28 03:01:09 -070078
Stephan Beyer32402402008-06-08 03:36:09 +020079-m parent-number::
80--mainline parent-number::
Mike Ralphson84989bd2008-02-29 17:00:38 +000081 Usually you cannot cherry-pick a merge because you do not know which
Junio C Hamano7791ecb2007-10-23 13:33:26 -070082 side of the merge should be considered the mainline. This
83 option specifies the parent number (starting from 1) of
84 the mainline and allows cherry-pick to replay the change
85 relative to the specified parent.
86
Stephan Beyer32402402008-06-08 03:36:09 +020087-n::
88--no-commit::
Christian Couder89d32d32010-06-02 07:58:40 +020089 Usually the command automatically creates a sequence of commits.
90 This flag applies the changes necessary to cherry-pick
91 each named commit to your working tree and the index,
92 without making any commit. In addition, when this
Bryan Drewery37a77442008-11-19 23:11:42 -060093 option is used, your index does not have to match the
94 HEAD commit. The cherry-pick is done against the
Petr Baudis8bd867e2008-07-16 14:35:22 +020095 beginning state of your index.
Jonas Fonsecadf8baa42005-10-03 19:16:30 +020096+
97This is useful when cherry-picking more than one commits'
Petr Baudis8bd867e2008-07-16 14:35:22 +020098effect to your index in a row.
Junio C Hamanode2b82c2005-08-28 03:01:09 -070099
Stephan Beyer32402402008-06-08 03:36:09 +0200100-s::
101--signoff::
Dan McGeecfd9c272008-04-26 15:14:28 -0500102 Add Signed-off-by line at the end of the commit message.
103
Nicolas Vigier32535532014-01-24 00:50:58 +0000104-S[<keyid>]::
105--gpg-sign[=<keyid>]::
106 GPG-sign commits.
107
Christian Couderab7e63e2010-03-06 21:34:44 +0100108--ff::
109 If the current HEAD is the same as the parent of the
110 cherry-pick'ed commit, then a fast forward to this commit will
111 be performed.
Junio C Hamanode2b82c2005-08-28 03:01:09 -0700112
Neil Hormandf478b72012-04-11 16:21:53 -0400113--allow-empty::
114 By default, cherry-picking an empty commit will fail,
115 indicating that an explicit invocation of `git commit
116 --allow-empty` is required. This option overrides that
117 behavior, allowing empty commits to be preserved automatically
118 in a cherry-pick. Note that when "--ff" is in effect, empty
119 commits that meet the "fast-forward" requirement will be kept
Neil Hormanb27cfb02012-04-20 10:36:15 -0400120 even without this option. Note also, that use of this option only
121 keeps commits that were initially empty (i.e. the commit recorded the
122 same tree as its parent). Commits which are made empty due to a
123 previous commit are dropped. To force the inclusion of those commits
124 use `--keep-redundant-commits`.
125
Chris Webb4bee9582012-08-02 11:38:51 +0100126--allow-empty-message::
127 By default, cherry-picking a commit with an empty message will fail.
128 This option overrides that behaviour, allowing commits with empty
129 messages to be cherry picked.
130
Neil Hormanb27cfb02012-04-20 10:36:15 -0400131--keep-redundant-commits::
132 If a commit being cherry picked duplicates a commit already in the
133 current history, it will become empty. By default these
134 redundant commits are ignored. This option overrides that behavior and
135 creates an empty commit object. Implies `--allow-empty`.
Neil Hormandf478b72012-04-11 16:21:53 -0400136
Jonathan Nieder67ac1e12010-12-10 18:51:44 -0600137--strategy=<strategy>::
138 Use the given merge strategy. Should only be used once.
139 See the MERGE STRATEGIES section in linkgit:git-merge[1]
140 for details.
141
142-X<option>::
143--strategy-option=<option>::
144 Pass the merge strategy-specific option through to the
145 merge strategy. See linkgit:git-merge[1] for details.
146
Ramkumar Ramachandra26ae3372011-08-04 16:09:11 +0530147SEQUENCER SUBCOMMANDS
148---------------------
149include::sequencer.txt[]
150
Christian Couder89d32d32010-06-02 07:58:40 +0200151EXAMPLES
152--------
Jeff King5d2fc912011-08-03 20:13:29 -0600153`git cherry-pick master`::
Christian Couder89d32d32010-06-02 07:58:40 +0200154
155 Apply the change introduced by the commit at the tip of the
156 master branch and create a new commit with this change.
157
Jeff King5d2fc912011-08-03 20:13:29 -0600158`git cherry-pick ..master`::
159`git cherry-pick ^HEAD master`::
Christian Couder89d32d32010-06-02 07:58:40 +0200160
161 Apply the changes introduced by all commits that are ancestors
162 of master but not of HEAD to produce new commits.
163
Carlos Martín Nietob98878e2012-06-15 16:33:16 +0200164`git cherry-pick maint next ^master`::
165`git cherry-pick maint master..next`::
166
167 Apply the changes introduced by all commits that are
168 ancestors of maint or next, but not master or any of its
169 ancestors. Note that the latter does not mean `maint` and
170 everything between `master` and `next`; specifically,
171 `maint` will not be used if it is included in `master`.
172
Jeff King6cf378f2012-04-26 04:51:57 -0400173`git cherry-pick master~4 master~2`::
Christian Couder89d32d32010-06-02 07:58:40 +0200174
175 Apply the changes introduced by the fifth and third last
176 commits pointed to by master and create 2 new commits with
177 these changes.
178
Jeff King5d2fc912011-08-03 20:13:29 -0600179`git cherry-pick -n master~1 next`::
Christian Couder89d32d32010-06-02 07:58:40 +0200180
181 Apply to the working tree and the index the changes introduced
182 by the second last commit pointed to by master and by the last
183 commit pointed to by next, but do not create any commit with
184 these changes.
185
Jeff King5d2fc912011-08-03 20:13:29 -0600186`git cherry-pick --ff ..next`::
Christian Couder89d32d32010-06-02 07:58:40 +0200187
188 If history is linear and HEAD is an ancestor of next, update
189 the working tree and advance the HEAD pointer to match next.
190 Otherwise, apply the changes introduced by those commits that
191 are in next but not HEAD to the current branch, creating a new
192 commit for each new change.
193
Jeff King6cf378f2012-04-26 04:51:57 -0400194`git rev-list --reverse master -- README | git cherry-pick -n --stdin`::
Christian Couderf873a272010-06-14 00:29:38 -0500195
196 Apply the changes introduced by all commits on the master
197 branch that touched README to the working tree and index,
198 so the result can be inspected and made into a single new
199 commit if suitable.
200
Jonathan Nieder67ac1e12010-12-10 18:51:44 -0600201The following sequence attempts to backport a patch, bails out because
202the code the patch applies to has changed too much, and then tries
203again, this time exercising more care about matching up context lines.
204
205------------
206$ git cherry-pick topic^ <1>
207$ git diff <2>
208$ git reset --merge ORIG_HEAD <3>
209$ git cherry-pick -Xpatience topic^ <4>
210------------
211<1> apply the change that would be shown by `git show topic^`.
212In this example, the patch does not apply cleanly, so
213information about the conflict is written to the index and
214working tree and no new commit results.
215<2> summarize changes to be reconciled
216<3> cancel the cherry-pick. In other words, return to the
217pre-cherry-pick state, preserving any local modifications you had in
218the working tree.
219<4> try to apply the change introduced by `topic^` again,
220spending extra time to avoid mistakes based on incorrectly matching
221context lines.
222
Christian Couder89d32d32010-06-02 07:58:40 +0200223SEE ALSO
224--------
225linkgit:git-revert[1]
226
Junio C Hamanode2b82c2005-08-28 03:01:09 -0700227GIT
228---
Christian Couder9e1f0a82008-06-06 09:07:32 +0200229Part of the linkgit:git[1] suite