Git 1.7.6
[git/git.git] / Documentation / git-cherry-pick.txt
CommitLineData
215a7ad1
JH
1git-cherry-pick(1)
2==================
de2b82c6
JH
3
4NAME
5----
89d32d33 6git-cherry-pick - Apply the changes introduced by some existing commits
de2b82c6
JH
7
8SYNOPSIS
9--------
89d32d33 10'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff] <commit>...
de2b82c6
JH
11
12DESCRIPTION
13-----------
89d32d33
CC
14
15Given one or more existing commits, apply the change each one
16introduces, recording a new commit for each. This requires your
17working tree to be clean (no modifications from the HEAD commit).
de2b82c6 18
d7e5c0cb
JS
19When it is not obvious how to apply a change, the following
20happens:
21
221. The current branch and `HEAD` pointer stay at the last commit
23 successfully made.
242. The `CHERRY_PICK_HEAD` ref is set to point at the commit that
25 introduced the change that is difficult to apply.
263. Paths in which the change applied cleanly are updated both
27 in the index file and in your working tree.
284. For conflicting paths, the index file records up to three
29 versions, as described in the "TRUE MERGE" section of
30 linkgit:git-merge[1]. The working tree files will include
31 a description of the conflict bracketed by the usual
32 conflict markers `<<<<<<<` and `>>>>>>>`.
335. No other modifications are made.
34
35See linkgit:git-merge[1] for some hints on resolving such
36conflicts.
37
de2b82c6
JH
38OPTIONS
39-------
89d32d33
CC
40<commit>...::
41 Commits to cherry-pick.
f028cdae 42 For a more complete list of ways to spell commits, see
9d83e382 43 linkgit:gitrevisions[7].
89d32d33
CC
44 Sets of commits can be passed but no traversal is done by
45 default, as if the '--no-walk' option was specified, see
46 linkgit:git-rev-list[1].
de2b82c6 47
3240240f
SB
48-e::
49--edit::
0b444cdb 50 With this option, 'git cherry-pick' will let you edit the commit
233808db 51 message prior to committing.
8bf14d6e 52
abd6970a 53-x::
bea7d16e
SS
54 When recording the commit, append a line that says
55 "(cherry picked from commit ...)" to the original commit
56 message in order to indicate which commit this change was
57 cherry-picked from. This is done only for cherry
dd8175f8
RW
58 picks without conflicts. Do not use this option if
59 you are cherry-picking from your private branch because
60 the information is useless to the recipient. If on the
abd6970a
JH
61 other hand you are cherry-picking between two publicly
62 visible branches (e.g. backporting a fix to a
63 maintenance branch for an older release from a
64 development branch), adding this information can be
65 useful.
66
6b04600a 67-r::
abd6970a
JH
68 It used to be that the command defaulted to do `-x`
69 described above, and `-r` was to disable it. Now the
70 default is not to do `-x` so this option is a no-op.
de2b82c6 71
3240240f
SB
72-m parent-number::
73--mainline parent-number::
84989bd8 74 Usually you cannot cherry-pick a merge because you do not know which
7791ecbc
JH
75 side of the merge should be considered the mainline. This
76 option specifies the parent number (starting from 1) of
77 the mainline and allows cherry-pick to replay the change
78 relative to the specified parent.
79
3240240f
SB
80-n::
81--no-commit::
89d32d33
CC
82 Usually the command automatically creates a sequence of commits.
83 This flag applies the changes necessary to cherry-pick
84 each named commit to your working tree and the index,
85 without making any commit. In addition, when this
37a7744f
BD
86 option is used, your index does not have to match the
87 HEAD commit. The cherry-pick is done against the
8bd867ee 88 beginning state of your index.
df8baa42
JF
89+
90This is useful when cherry-picking more than one commits'
8bd867ee 91effect to your index in a row.
de2b82c6 92
3240240f
SB
93-s::
94--signoff::
cfd9c277
DM
95 Add Signed-off-by line at the end of the commit message.
96
ab7e63e8
CC
97--ff::
98 If the current HEAD is the same as the parent of the
99 cherry-pick'ed commit, then a fast forward to this commit will
100 be performed.
de2b82c6 101
67ac1e1d
JN
102--strategy=<strategy>::
103 Use the given merge strategy. Should only be used once.
104 See the MERGE STRATEGIES section in linkgit:git-merge[1]
105 for details.
106
107-X<option>::
108--strategy-option=<option>::
109 Pass the merge strategy-specific option through to the
110 merge strategy. See linkgit:git-merge[1] for details.
111
89d32d33
CC
112EXAMPLES
113--------
114git cherry-pick master::
115
116 Apply the change introduced by the commit at the tip of the
117 master branch and create a new commit with this change.
118
119git cherry-pick ..master::
120git cherry-pick ^HEAD master::
121
122 Apply the changes introduced by all commits that are ancestors
123 of master but not of HEAD to produce new commits.
124
be1b0558 125git cherry-pick master{tilde}4 master{tilde}2::
89d32d33
CC
126
127 Apply the changes introduced by the fifth and third last
128 commits pointed to by master and create 2 new commits with
129 these changes.
130
131git cherry-pick -n master~1 next::
132
133 Apply to the working tree and the index the changes introduced
134 by the second last commit pointed to by master and by the last
135 commit pointed to by next, but do not create any commit with
136 these changes.
137
138git cherry-pick --ff ..next::
139
140 If history is linear and HEAD is an ancestor of next, update
141 the working tree and advance the HEAD pointer to match next.
142 Otherwise, apply the changes introduced by those commits that
143 are in next but not HEAD to the current branch, creating a new
144 commit for each new change.
145
f873a273
CC
146git rev-list --reverse master \-- README | git cherry-pick -n --stdin::
147
148 Apply the changes introduced by all commits on the master
149 branch that touched README to the working tree and index,
150 so the result can be inspected and made into a single new
151 commit if suitable.
152
67ac1e1d
JN
153The following sequence attempts to backport a patch, bails out because
154the code the patch applies to has changed too much, and then tries
155again, this time exercising more care about matching up context lines.
156
157------------
158$ git cherry-pick topic^ <1>
159$ git diff <2>
160$ git reset --merge ORIG_HEAD <3>
161$ git cherry-pick -Xpatience topic^ <4>
162------------
163<1> apply the change that would be shown by `git show topic^`.
164In this example, the patch does not apply cleanly, so
165information about the conflict is written to the index and
166working tree and no new commit results.
167<2> summarize changes to be reconciled
168<3> cancel the cherry-pick. In other words, return to the
169pre-cherry-pick state, preserving any local modifications you had in
170the working tree.
171<4> try to apply the change introduced by `topic^` again,
172spending extra time to avoid mistakes based on incorrectly matching
173context lines.
174
89d32d33
CC
175SEE ALSO
176--------
177linkgit:git-revert[1]
178
de2b82c6
JH
179GIT
180---
9e1f0a85 181Part of the linkgit:git[1] suite