1GIT-REBASE(1) Git Manual GIT-REBASE(1)
2
6 git-rebase - Forward-port local commits to the updated upstream head
7
9 git-rebase [-i | --interactive] [-v | --verbose] [-m | --merge] [-C<n>]
10 [-p | --preserve-merges] [--onto <newbase>] <upstream> [<branch>]
11 git-rebase --continue | --skip | --abort
12
14 If <branch> is specified, git-rebase will perform an automatic git
15 checkout <branch> before doing anything else. Otherwise it remains on
16 the current branch.
17 All changes made by commits in the current branch but that are not in
19 <upstream> are saved to a temporary area. This is the same set of
20 commits that would be shown by git log <upstream>..HEAD.
21 The current branch is reset to <upstream>, or <newbase> if the --onto
23 option was supplied. This has the exact same effect as git reset --hard
24 <upstream> (or <newbase>).
25 The commits that were previously saved into the temporary area are then
27 reapplied to the current branch, one by one, in order.
28 It is possible that a merge failure will prevent this process from
30 being completely automatic. You will have to resolve any such merge
31 failure and run git rebase --continue. Another option is to bypass the
32 commit that caused the merge failure with git rebase --skip. To restore
33 the original <branch> and remove the .dotest working files, use the
34 command git rebase --abort instead.
35 Assume the following history exists and the current branch is "topic":
37 A---B---C topic
41 /
42 D---E---F---G master
43 From this point, the result of either of the following commands:
45 git-rebase master
48 git-rebase master topic
49 would be:
50 A´--B´--C´ topic
54 /
55 D---E---F---G master
56 The latter form is just a short-hand of git checkout topic followed by
58 git rebase master.
59 Here is how you would transplant a topic branch based on one branch to
61 another, to pretend that you forked the topic branch from the latter
62 branch, using rebase --onto.
63 First let´s assume your topic is based on branch next. For example
65 feature developed in topic depends on some functionality which is found
66 in next.
67 o---o---o---o---o master
71 \
72 o---o---o---o---o next
73 \
74 o---o---o topic
75 We would want to make topic forked from branch master, for example
77 because the functionality topic branch depend on got merged into more
78 stable master branch, like this:
79 o---o---o---o---o master
83 | \
84 | o´--o´--o´ topic
85 \
86 o---o---o---o---o next
87 We can get this using the following command:
89 git-rebase --onto master next topic
92 Another example of --onto option is to rebase part of a branch. If we
93 have the following situation:
94 H---I---J topicB
98 /
99 E---F---G topicA
100 /
101 A---B---C---D master
102 then the command
104 git-rebase --onto master topicA topicB
107 would result in:
108 H´--I´--J´ topicB
112 /
113 | E---F---G topicA
114 |/
115 A---B---C---D master
116 This is useful when topicB does not depend on topicA.
118 A range of commits could also be removed with rebase. If we have the
120 following situation:
121 E---F---G---H---I---J topicA
125 then the command
127 git-rebase --onto topicA~5 topicA~3 topicA
130 would result in the removal of commits F and G:
131 E---H´---I´---J´ topicA
135 This is useful if F and G were flawed in some way, or should not be
137 part of topicA. Note that the argument to --onto and the <upstream>
138 parameter can be any valid commit-ish.
139 In case of conflict, git-rebase will stop at the first problematic
141 commit and leave conflict markers in the tree. You can use git diff to
142 locate the markers (<<<<<<) and make edits to resolve the conflict. For
143 each file you edit, you need to tell git that the conflict has been
144 resolved, typically this would be done with
145 git add <filename>
148 After resolving the conflict manually and updating the index with the
149 desired resolution, you can continue the rebasing process with
150 git rebase --continue
153 Alternatively, you can undo the git-rebase with
154 git rebase --abort
157
159 <newbase>
160 Starting point at which to create the new commits. If the --onto
161 option is not specified, the starting point is <upstream>. May be
162 any valid commit, and not just an existing branch name.
163 <upstream>
165 Upstream branch to compare against. May be any valid commit, not
166 just an existing branch name.
167 <branch>
169 Working branch; defaults to HEAD.
170 --continue
172 Restart the rebasing process after having resolved a merge
173 conflict.
174 --abort
176 Restore the original branch and abort the rebase operation.
177 --skip
179 Restart the rebasing process by skipping the current patch.
180 -m, --merge
182 Use merging strategies to rebase. When the recursive (default)
183 merge strategy is used, this allows rebase to be aware of renames
184 on the upstream side.
185 -s <strategy>, --strategy=<strategy>
187 Use the given merge strategy; can be supplied more than once to
188 specify them in the order they should be tried. If there is no -s
189 option, a built-in list of strategies is used instead
190 (git-merge-recursive when merging a single head, git-merge-octopus
191 otherwise). This implies --merge.
192 -v, --verbose
194 Display a diffstat of what changed upstream since the last rebase.
195 -C<n>
197 Ensure at least <n> lines of surrounding context match before and
198 after each change. When fewer lines of surrounding context exist
199 they all must match. By default no context is ever ignored.
200 -i, --interactive
202 Make a list of the commits which are about to be rebased. Let the
203 user edit that list before rebasing. This mode can also be used to
204 split commits (see SPLITTING COMMITS below).
205 -p, --preserve-merges
207 Instead of ignoring merges, try to recreate them. This option only
208 works in interactive mode.
209
211 resolve
212 This can only resolve two heads (i.e. the current branch and
213 another branch you pulled from) using 3-way merge algorithm. It
214 tries to carefully detect criss-cross merge ambiguities and is
215 considered generally safe and fast.
216 recursive
218 This can only resolve two heads using 3-way merge algorithm. When
219 there are more than one common ancestors that can be used for 3-way
220 merge, it creates a merged tree of the common ancestors and uses
221 that as the reference tree for the 3-way merge. This has been
222 reported to result in fewer merge conflicts without causing
223 mis-merges by tests done on actual merge commits taken from Linux
224 2.6 kernel development history. Additionally this can detect and
225 handle merges involving renames. This is the default merge strategy
226 when pulling or merging one branch.
227 octopus
229 This resolves more than two-head case, but refuses to do complex
230 merge that needs manual resolution. It is primarily meant to be
231 used for bundling topic branch heads together. This is the default
232 merge strategy when pulling or merging more than one branches.
233 ours
235 This resolves any number of heads, but the result of the merge is
236 always the current branch head. It is meant to be used to supersede
237 old development history of side branches.
238
240 When you rebase a branch, you are changing its history in a way that
241 will cause problems for anyone who already has a copy of the branch in
242 their repository and tries to pull updates from you. You should
243 understand the implications of using git rebase on a repository that
244 you share.
245 When the git rebase command is run, it will first execute a
247 "pre-rebase" hook if one exists. You can use this hook to do sanity
248 checks and reject the rebase if it isn´t appropriate. Please see the
249 template pre-rebase hook script for an example.
250 You must be in the top directory of your project to start (or continue)
252 a rebase. Upon completion, <branch> will be the current branch.
253
255 Rebasing interactively means that you have a chance to edit the commits
256 which are rebased. You can reorder the commits, and you can remove them
257 (weeding out bad or otherwise unwanted patches).
258 The interactive mode is meant for this type of workflow:
260 1. have a wonderful idea
263 2. hack on the code
265 3. prepare a series for submission
267 4. submit
269 where point 2. consists of several instances of
270 1. regular use
273 1. finish something worthy of a commit
276 2. commit
278 2. independent fixup
280 1. realize that something does not work
283 2. fix that
285 3. commit it
287 Sometimes the thing fixed in b.2. cannot be amended to the not-quite
288 perfect commit it fixes, because that commit is buried deeply in a
289 patch series. That is exactly what interactive rebase is for: use it
290 after plenty of "a"s and "b"s, by rearranging and editing commits, and
291 squashing multiple commits into one.
292 Start it with the last commit you want to retain as-is:
294 git rebase -i <after-this-commit>
297 An editor will be fired up with all the commits in your current branch
298 (ignoring merge commits), which come after the given commit. You can
299 reorder the commits in this list to your heart´s content, and you can
300 remove them. The list looks more or less like this:
301 pick deadbee The oneline of this commit
305 pick fa1afe1 The oneline of the next commit
306 The oneline descriptions are purely for your pleasure; git-rebase will
308 not look at them but at the commit names ("deadbee" and "fa1afe1" in
309 this example), so do not delete or edit the names.
310 By replacing the command "pick" with the command "edit", you can tell
312 git-rebase to stop after applying that commit, so that you can edit the
313 files and/or the commit message, amend the commit, and continue
314 rebasing.
315 If you want to fold two or more commits into one, replace the command
317 "pick" with "squash" for the second and subsequent commit. If the
318 commits had different authors, it will attribute the squashed commit to
319 the author of the last commit.
320 In both cases, or when a "pick" does not succeed (because of merge
322 errors), the loop will stop to let you fix things, and you can continue
323 the loop with git rebase --continue.
324 For example, if you want to reorder the last 5 commits, such that what
326 was HEAD~4 becomes the new HEAD. To achieve that, you would call
327 git-rebase like this:
328 $ git rebase -i HEAD~5
332 And move the first patch to the end of the list.
334 You might want to preserve merges, if you have a history like this:
336 X
340 \
341 A---M---B
342 /
343 ---o---O---P---Q
344 Suppose you want to rebase the side branch starting at "A" to "Q". Make
346 sure that the current HEAD is "B", and call
347 $ git rebase -i -p --onto Q O
351
354 In interactive mode, you can mark commits with the action "edit".
355 However, this does not necessarily mean that git rebase expects the
356 result of this edit to be exactly one commit. Indeed, you can undo the
357 commit, or you can add other commits. This can be used to split a
358 commit into two:
359 · Start an interactive rebase with git rebase -i <commit>^, where
362 <commit> is the commit you want to split. In fact, any commit range
363 will do, as long as it contains that commit.
364 · Mark the commit you want to split with the action "edit".
366 · When it comes to editing that commit, execute git reset HEAD^. The
368 effect is that the HEAD is rewound by one, and the index follows
369 suit. However, the working tree stays the same.
370 · Now add the changes to the index that you want to have in the first
372 commit. You can use git-add(1) (possibly interactively) and/or git-
373 gui(1) to do that.
374 · Commit the now-current index with whatever commit message is
376 appropriate now.
377 · Repeat the last two steps until your working tree is clean.
379 · Continue the rebase with git rebase --continue.
381 If you are not absolutely sure that the intermediate revisions are
382 consistent (they compile, pass the testsuite, etc.) you should use git-
383 stash(1) to stash away the not-yet-committed changes after each commit,
384 test, and amend the commit if fixes are necessary.
385
387 Written by Junio C Hamano <junkio@cox.net> and Johannes E. Schindelin
388 <johannes.schindelin@gmx.de>
389
391 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
392
394 Part of the git(7) suite
395Git 1.5.3.3 10/09/2007 GIT-REBASE(1)