]>
Commit | Line | Data |
---|---|---|
1 | git-cherry-pick(1) | |
2 | ================== | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | git-cherry-pick - Apply the changes introduced by some existing commits | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
10 | [verse] | |
11 | 'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff] | |
12 | [-S[<keyid>]] <commit>... | |
13 | 'git cherry-pick' (--continue | --skip | --abort | --quit) | |
14 | ||
15 | DESCRIPTION | |
16 | ----------- | |
17 | ||
18 | Given one or more existing commits, apply the change each one | |
19 | introduces, recording a new commit for each. This requires your | |
20 | working tree to be clean (no modifications from the HEAD commit). | |
21 | ||
22 | When it is not obvious how to apply a change, the following | |
23 | happens: | |
24 | ||
25 | 1. The current branch and `HEAD` pointer stay at the last commit | |
26 | successfully made. | |
27 | 2. The `CHERRY_PICK_HEAD` ref is set to point at the commit that | |
28 | introduced the change that is difficult to apply. | |
29 | 3. Paths in which the change applied cleanly are updated both | |
30 | in the index file and in your working tree. | |
31 | 4. For conflicting paths, the index file records up to three | |
32 | versions, as described in the "TRUE MERGE" section of | |
33 | linkgit:git-merge[1]. The working tree files will include | |
34 | a description of the conflict bracketed by the usual | |
35 | conflict markers `<<<<<<<` and `>>>>>>>`. | |
36 | 5. No other modifications are made. | |
37 | ||
38 | See linkgit:git-merge[1] for some hints on resolving such | |
39 | conflicts. | |
40 | ||
41 | OPTIONS | |
42 | ------- | |
43 | <commit>...:: | |
44 | Commits to cherry-pick. | |
45 | For a more complete list of ways to spell commits, see | |
46 | linkgit:gitrevisions[7]. | |
47 | Sets of commits can be passed but no traversal is done by | |
48 | default, as if the `--no-walk` option was specified, see | |
49 | linkgit:git-rev-list[1]. Note that specifying a range will | |
50 | feed all <commit>... arguments to a single revision walk | |
51 | (see a later example that uses 'maint master..next'). | |
52 | ||
53 | -e:: | |
54 | --edit:: | |
55 | With this option, 'git cherry-pick' will let you edit the commit | |
56 | message prior to committing. | |
57 | ||
58 | --cleanup=<mode>:: | |
59 | This option determines how the commit message will be cleaned up before | |
60 | being passed on to the commit machinery. See linkgit:git-commit[1] for more | |
61 | details. In particular, if the '<mode>' is given a value of `scissors`, | |
62 | scissors will be appended to `MERGE_MSG` before being passed on in the case | |
63 | of a conflict. | |
64 | ||
65 | -x:: | |
66 | When recording the commit, append a line that says | |
67 | "(cherry picked from commit ...)" to the original commit | |
68 | message in order to indicate which commit this change was | |
69 | cherry-picked from. This is done only for cherry | |
70 | picks without conflicts. Do not use this option if | |
71 | you are cherry-picking from your private branch because | |
72 | the information is useless to the recipient. If on the | |
73 | other hand you are cherry-picking between two publicly | |
74 | visible branches (e.g. backporting a fix to a | |
75 | maintenance branch for an older release from a | |
76 | development branch), adding this information can be | |
77 | useful. | |
78 | ||
79 | -r:: | |
80 | It used to be that the command defaulted to do `-x` | |
81 | described above, and `-r` was to disable it. Now the | |
82 | default is not to do `-x` so this option is a no-op. | |
83 | ||
84 | -m parent-number:: | |
85 | --mainline parent-number:: | |
86 | Usually you cannot cherry-pick a merge because you do not know which | |
87 | side of the merge should be considered the mainline. This | |
88 | option specifies the parent number (starting from 1) of | |
89 | the mainline and allows cherry-pick to replay the change | |
90 | relative to the specified parent. | |
91 | ||
92 | -n:: | |
93 | --no-commit:: | |
94 | Usually the command automatically creates a sequence of commits. | |
95 | This flag applies the changes necessary to cherry-pick | |
96 | each named commit to your working tree and the index, | |
97 | without making any commit. In addition, when this | |
98 | option is used, your index does not have to match the | |
99 | HEAD commit. The cherry-pick is done against the | |
100 | beginning state of your index. | |
101 | + | |
102 | This is useful when cherry-picking more than one commits' | |
103 | effect to your index in a row. | |
104 | ||
105 | -s:: | |
106 | --signoff:: | |
107 | Add Signed-off-by line at the end of the commit message. | |
108 | See the signoff option in linkgit:git-commit[1] for more information. | |
109 | ||
110 | -S[<keyid>]:: | |
111 | --gpg-sign[=<keyid>]:: | |
112 | GPG-sign commits. The `keyid` argument is optional and | |
113 | defaults to the committer identity; if specified, it must be | |
114 | stuck to the option without a space. | |
115 | ||
116 | --ff:: | |
117 | If the current HEAD is the same as the parent of the | |
118 | cherry-pick'ed commit, then a fast forward to this commit will | |
119 | be performed. | |
120 | ||
121 | --allow-empty:: | |
122 | By default, cherry-picking an empty commit will fail, | |
123 | indicating that an explicit invocation of `git commit | |
124 | --allow-empty` is required. This option overrides that | |
125 | behavior, allowing empty commits to be preserved automatically | |
126 | in a cherry-pick. Note that when "--ff" is in effect, empty | |
127 | commits that meet the "fast-forward" requirement will be kept | |
128 | even without this option. Note also, that use of this option only | |
129 | keeps commits that were initially empty (i.e. the commit recorded the | |
130 | same tree as its parent). Commits which are made empty due to a | |
131 | previous commit are dropped. To force the inclusion of those commits | |
132 | use `--keep-redundant-commits`. | |
133 | ||
134 | --allow-empty-message:: | |
135 | By default, cherry-picking a commit with an empty message will fail. | |
136 | This option overrides that behavior, allowing commits with empty | |
137 | messages to be cherry picked. | |
138 | ||
139 | --keep-redundant-commits:: | |
140 | If a commit being cherry picked duplicates a commit already in the | |
141 | current history, it will become empty. By default these | |
142 | redundant commits cause `cherry-pick` to stop so the user can | |
143 | examine the commit. This option overrides that behavior and | |
144 | creates an empty commit object. Implies `--allow-empty`. | |
145 | ||
146 | --strategy=<strategy>:: | |
147 | Use the given merge strategy. Should only be used once. | |
148 | See the MERGE STRATEGIES section in linkgit:git-merge[1] | |
149 | for details. | |
150 | ||
151 | -X<option>:: | |
152 | --strategy-option=<option>:: | |
153 | Pass the merge strategy-specific option through to the | |
154 | merge strategy. See linkgit:git-merge[1] for details. | |
155 | ||
156 | --rerere-autoupdate:: | |
157 | --no-rerere-autoupdate:: | |
158 | Allow the rerere mechanism to update the index with the | |
159 | result of auto-conflict resolution if possible. | |
160 | ||
161 | SEQUENCER SUBCOMMANDS | |
162 | --------------------- | |
163 | include::sequencer.txt[] | |
164 | ||
165 | EXAMPLES | |
166 | -------- | |
167 | `git cherry-pick master`:: | |
168 | ||
169 | Apply the change introduced by the commit at the tip of the | |
170 | master branch and create a new commit with this change. | |
171 | ||
172 | `git cherry-pick ..master`:: | |
173 | `git cherry-pick ^HEAD master`:: | |
174 | ||
175 | Apply the changes introduced by all commits that are ancestors | |
176 | of master but not of HEAD to produce new commits. | |
177 | ||
178 | `git cherry-pick maint next ^master`:: | |
179 | `git cherry-pick maint master..next`:: | |
180 | ||
181 | Apply the changes introduced by all commits that are | |
182 | ancestors of maint or next, but not master or any of its | |
183 | ancestors. Note that the latter does not mean `maint` and | |
184 | everything between `master` and `next`; specifically, | |
185 | `maint` will not be used if it is included in `master`. | |
186 | ||
187 | `git cherry-pick master~4 master~2`:: | |
188 | ||
189 | Apply the changes introduced by the fifth and third last | |
190 | commits pointed to by master and create 2 new commits with | |
191 | these changes. | |
192 | ||
193 | `git cherry-pick -n master~1 next`:: | |
194 | ||
195 | Apply to the working tree and the index the changes introduced | |
196 | by the second last commit pointed to by master and by the last | |
197 | commit pointed to by next, but do not create any commit with | |
198 | these changes. | |
199 | ||
200 | `git cherry-pick --ff ..next`:: | |
201 | ||
202 | If history is linear and HEAD is an ancestor of next, update | |
203 | the working tree and advance the HEAD pointer to match next. | |
204 | Otherwise, apply the changes introduced by those commits that | |
205 | are in next but not HEAD to the current branch, creating a new | |
206 | commit for each new change. | |
207 | ||
208 | `git rev-list --reverse master -- README | git cherry-pick -n --stdin`:: | |
209 | ||
210 | Apply the changes introduced by all commits on the master | |
211 | branch that touched README to the working tree and index, | |
212 | so the result can be inspected and made into a single new | |
213 | commit if suitable. | |
214 | ||
215 | The following sequence attempts to backport a patch, bails out because | |
216 | the code the patch applies to has changed too much, and then tries | |
217 | again, this time exercising more care about matching up context lines. | |
218 | ||
219 | ------------ | |
220 | $ git cherry-pick topic^ <1> | |
221 | $ git diff <2> | |
222 | $ git reset --merge ORIG_HEAD <3> | |
223 | $ git cherry-pick -Xpatience topic^ <4> | |
224 | ------------ | |
225 | <1> apply the change that would be shown by `git show topic^`. | |
226 | In this example, the patch does not apply cleanly, so | |
227 | information about the conflict is written to the index and | |
228 | working tree and no new commit results. | |
229 | <2> summarize changes to be reconciled | |
230 | <3> cancel the cherry-pick. In other words, return to the | |
231 | pre-cherry-pick state, preserving any local modifications | |
232 | you had in the working tree. | |
233 | <4> try to apply the change introduced by `topic^` again, | |
234 | spending extra time to avoid mistakes based on incorrectly | |
235 | matching context lines. | |
236 | ||
237 | SEE ALSO | |
238 | -------- | |
239 | linkgit:git-revert[1] | |
240 | ||
241 | GIT | |
242 | --- | |
243 | Part of the linkgit:git[1] suite |