1git-rebase(1) 2============= 3 4NAME 5---- 6git-rebase - Forward-port local commits to the updated upstream head 7 8SYNOPSIS 9-------- 10[verse] 11'git rebase' [-i | --interactive] [options] [--onto <newbase>] 12 <upstream> [<branch>] 13'git rebase' [-i | --interactive] [options] --onto <newbase> 14 --root [<branch>] 15 16'git rebase' --continue | --skip | --abort 17 18DESCRIPTION 19----------- 20If <branch> is specified, 'git rebase' will perform an automatic 21`git checkout <branch>` before doing anything else. Otherwise 22it remains on the current branch. 23 24All changes made by commits in the current branch but that are not 25in <upstream> are saved to a temporary area. This is the same set 26of commits that would be shown by `git log <upstream>..HEAD` (or 27`git log HEAD`, if --root is specified). 28 29The current branch is reset to <upstream>, or <newbase> if the 30--onto option was supplied. This has the exact same effect as 31`git reset --hard <upstream>` (or <newbase>). ORIG_HEAD is set 32to point at the tip of the branch before the reset. 33 34The commits that were previously saved into the temporary area are 35then reapplied to the current branch, one by one, in order. Note that 36any commits in HEAD which introduce the same textual changes as a commit 37in HEAD..<upstream> are omitted (i.e., a patch already accepted upstream 38with a different commit message or timestamp will be skipped). 39 40It is possible that a merge failure will prevent this process from being 41completely automatic. You will have to resolve any such merge failure 42and run `git rebase --continue`. Another option is to bypass the commit 43that caused the merge failure with `git rebase --skip`. To restore the 44original <branch> and remove the .git/rebase-apply working files, use the 45command `git rebase --abort` instead. 46 47Assume the following history exists and the current branch is "topic": 48 49------------ 50 A---B---C topic 51 / 52 D---E---F---G master 53------------ 54 55From this point, the result of either of the following commands: 56 57 58 git rebase master 59 git rebase master topic 60 61would be: 62 63------------ 64 A'--B'--C' topic 65 / 66 D---E---F---G master 67------------ 68 69The latter form is just a short-hand of `git checkout topic` 70followed by `git rebase master`. 71 72If the upstream branch already contains a change you have made (e.g., 73because you mailed a patch which was applied upstream), then that commit 74will be skipped. For example, running `git rebase master` on the 75following history (in which A' and A introduce the same set of changes, 76but have different committer information): 77 78------------ 79 A---B---C topic 80 / 81 D---E---A'---F master 82------------ 83 84will result in: 85 86------------ 87 B'---C' topic 88 / 89 D---E---A'---F master 90------------ 91 92Here is how you would transplant a topic branch based on one 93branch to another, to pretend that you forked the topic branch 94from the latter branch, using `rebase --onto`. 95 96First let's assume your 'topic' is based on branch 'next'. 97For example, a feature developed in 'topic' depends on some 98functionality which is found in 'next'. 99 100------------ 101 o---o---o---o---o master 102 \ 103 o---o---o---o---o next 104 \ 105 o---o---o topic 106------------ 107 108We want to make 'topic' forked from branch 'master'; for example, 109because the functionality on which 'topic' depends was merged into the 110more stable 'master' branch. We want our tree to look like this: 111 112------------ 113 o---o---o---o---o master 114 | \ 115 | o'--o'--o' topic 116 \ 117 o---o---o---o---o next 118------------ 119 120We can get this using the following command: 121 122 git rebase --onto master next topic 123 124 125Another example of --onto option is to rebase part of a 126branch. If we have the following situation: 127 128------------ 129 H---I---J topicB 130 / 131 E---F---G topicA 132 / 133 A---B---C---D master 134------------ 135 136then the command 137 138 git rebase --onto master topicA topicB 139 140would result in: 141 142------------ 143 H'--I'--J' topicB 144 / 145 | E---F---G topicA 146 |/ 147 A---B---C---D master 148------------ 149 150This is useful when topicB does not depend on topicA. 151 152A range of commits could also be removed with rebase. If we have 153the following situation: 154 155------------ 156 E---F---G---H---I---J topicA 157------------ 158 159then the command 160 161 git rebase --onto topicA~5 topicA~3 topicA 162 163would result in the removal of commits F and G: 164 165------------ 166 E---H'---I'---J' topicA 167------------ 168 169This is useful if F and G were flawed in some way, or should not be 170part of topicA. Note that the argument to --onto and the <upstream> 171parameter can be any valid commit-ish. 172 173In case of conflict, 'git rebase' will stop at the first problematic commit 174and leave conflict markers in the tree. You can use 'git diff' to locate 175the markers (<<<<<<) and make edits to resolve the conflict. For each 176file you edit, you need to tell git that the conflict has been resolved, 177typically this would be done with 178 179 180 git add <filename> 181 182 183After resolving the conflict manually and updating the index with the 184desired resolution, you can continue the rebasing process with 185 186 187 git rebase --continue 188 189 190Alternatively, you can undo the 'git rebase' with 191 192 193 git rebase --abort 194 195CONFIGURATION 196------------- 197 198rebase.stat:: 199 Whether to show a diffstat of what changed upstream since the last 200 rebase. False by default. 201 202rebase.autosquash:: 203 If set to true enable '--autosquash' option by default. 204 205OPTIONS 206------- 207<newbase>:: 208 Starting point at which to create the new commits. If the 209 --onto option is not specified, the starting point is 210 <upstream>. May be any valid commit, and not just an 211 existing branch name. 212+ 213As a special case, you may use "A...B" as a shortcut for the 214merge base of A and B if there is exactly one merge base. You can 215leave out at most one of A and B, in which case it defaults to HEAD. 216 217<upstream>:: 218 Upstream branch to compare against. May be any valid commit, 219 not just an existing branch name. 220 221<branch>:: 222 Working branch; defaults to HEAD. 223 224--continue:: 225 Restart the rebasing process after having resolved a merge conflict. 226 227--abort:: 228 Restore the original branch and abort the rebase operation. 229 230--skip:: 231 Restart the rebasing process by skipping the current patch. 232 233-m:: 234--merge:: 235 Use merging strategies to rebase. When the recursive (default) merge 236 strategy is used, this allows rebase to be aware of renames on the 237 upstream side. 238+ 239Note that a rebase merge works by replaying each commit from the working 240branch on top of the <upstream> branch. Because of this, when a merge 241conflict happens, the side reported as 'ours' is the so-far rebased 242series, starting with <upstream>, and 'theirs' is the working branch. In 243other words, the sides are swapped. 244 245-s <strategy>:: 246--strategy=<strategy>:: 247 Use the given merge strategy. 248 If there is no `-s` option 'git merge-recursive' is used 249 instead. This implies --merge. 250+ 251Because 'git rebase' replays each commit from the working branch 252on top of the <upstream> branch using the given strategy, using 253the 'ours' strategy simply discards all patches from the <branch>, 254which makes little sense. 255 256-q:: 257--quiet:: 258 Be quiet. Implies --no-stat. 259 260-v:: 261--verbose:: 262 Be verbose. Implies --stat. 263 264--stat:: 265 Show a diffstat of what changed upstream since the last rebase. The 266 diffstat is also controlled by the configuration option rebase.stat. 267 268-n:: 269--no-stat:: 270 Do not show a diffstat as part of the rebase process. 271 272--no-verify:: 273 This option bypasses the pre-rebase hook. See also linkgit:githooks[5]. 274 275-C<n>:: 276 Ensure at least <n> lines of surrounding context match before 277 and after each change. When fewer lines of surrounding 278 context exist they all must match. By default no context is 279 ever ignored. 280 281-f:: 282--force-rebase:: 283 Force the rebase even if the current branch is a descendant 284 of the commit you are rebasing onto. Normally non-interactive rebase will 285 exit with the message "Current branch is up to date" in such a 286 situation. 287 Incompatible with the --interactive option. 288+ 289You may find this (or --no-ff with an interactive rebase) helpful after 290reverting a topic branch merge, as this option recreates the topic branch with 291fresh commits so it can be remerged successfully without needing to "revert 292the reversion" (see the 293link:howto/revert-a-faulty-merge.txt[revert-a-faulty-merge How-To] for details). 294 295--ignore-whitespace:: 296--whitespace=<option>:: 297 These flag are passed to the 'git apply' program 298 (see linkgit:git-apply[1]) that applies the patch. 299 Incompatible with the --interactive option. 300 301--committer-date-is-author-date:: 302--ignore-date:: 303 These flags are passed to 'git am' to easily change the dates 304 of the rebased commits (see linkgit:git-am[1]). 305 Incompatible with the --interactive option. 306 307-i:: 308--interactive:: 309 Make a list of the commits which are about to be rebased. Let the 310 user edit that list before rebasing. This mode can also be used to 311 split commits (see SPLITTING COMMITS below). 312 313-p:: 314--preserve-merges:: 315 Instead of ignoring merges, try to recreate them. 316+ 317This uses the `--interactive` machinery internally, but combining it 318with the `--interactive` option explicitly is generally not a good 319idea unless you know what you are doing (see BUGS below). 320 321 322--root:: 323 Rebase all commits reachable from <branch>, instead of 324 limiting them with an <upstream>. This allows you to rebase 325 the root commit(s) on a branch. Must be used with --onto, and 326 will skip changes already contained in <newbase> (instead of 327 <upstream>). When used together with --preserve-merges, 'all' 328 root commits will be rewritten to have <newbase> as parent 329 instead. 330 331--autosquash:: 332--no-autosquash:: 333 When the commit log message begins with "squash! ..." (or 334 "fixup! ..."), and there is a commit whose title begins with 335 the same ..., automatically modify the todo list of rebase -i 336 so that the commit marked for squashing comes right after the 337 commit to be modified, and change the action of the moved 338 commit from `pick` to `squash` (or `fixup`). 339+ 340This option is only valid when the '--interactive' option is used. 341+ 342If the '--autosquash' option is enabled by default using the 343configuration variable `rebase.autosquash`, this option can be 344used to override and disable this setting. 345 346--no-ff:: 347 With --interactive, cherry-pick all rebased commits instead of 348 fast-forwarding over the unchanged ones. This ensures that the 349 entire history of the rebased branch is composed of new commits. 350+ 351Without --interactive, this is a synonym for --force-rebase. 352+ 353You may find this helpful after reverting a topic branch merge, as this option 354recreates the topic branch with fresh commits so it can be remerged 355successfully without needing to "revert the reversion" (see the 356link:howto/revert-a-faulty-merge.txt[revert-a-faulty-merge How-To] for details). 357 358include::merge-strategies.txt[] 359 360NOTES 361----- 362 363You should understand the implications of using 'git rebase' on a 364repository that you share. See also RECOVERING FROM UPSTREAM REBASE 365below. 366 367When the git-rebase command is run, it will first execute a "pre-rebase" 368hook if one exists. You can use this hook to do sanity checks and 369reject the rebase if it isn't appropriate. Please see the template 370pre-rebase hook script for an example. 371 372Upon completion, <branch> will be the current branch. 373 374INTERACTIVE MODE 375---------------- 376 377Rebasing interactively means that you have a chance to edit the commits 378which are rebased. You can reorder the commits, and you can 379remove them (weeding out bad or otherwise unwanted patches). 380 381The interactive mode is meant for this type of workflow: 382 3831. have a wonderful idea 3842. hack on the code 3853. prepare a series for submission 3864. submit 387 388where point 2. consists of several instances of 389 390a. regular use 391 1. finish something worthy of a commit 392 2. commit 393b. independent fixup 394 1. realize that something does not work 395 2. fix that 396 3. commit it 397 398Sometimes the thing fixed in b.2. cannot be amended to the not-quite 399perfect commit it fixes, because that commit is buried deeply in a 400patch series. That is exactly what interactive rebase is for: use it 401after plenty of "a"s and "b"s, by rearranging and editing 402commits, and squashing multiple commits into one. 403 404Start it with the last commit you want to retain as-is: 405 406 git rebase -i <after-this-commit> 407 408An editor will be fired up with all the commits in your current branch 409(ignoring merge commits), which come after the given commit. You can 410reorder the commits in this list to your heart's content, and you can 411remove them. The list looks more or less like this: 412 413------------------------------------------- 414pick deadbee The oneline of this commit 415pick fa1afe1 The oneline of the next commit 416... 417------------------------------------------- 418 419The oneline descriptions are purely for your pleasure; 'git rebase' will 420not look at them but at the commit names ("deadbee" and "fa1afe1" in this 421example), so do not delete or edit the names. 422 423By replacing the command "pick" with the command "edit", you can tell 424'git rebase' to stop after applying that commit, so that you can edit 425the files and/or the commit message, amend the commit, and continue 426rebasing. 427 428If you just want to edit the commit message for a commit, replace the 429command "pick" with the command "reword". 430 431If you want to fold two or more commits into one, replace the command 432"pick" for the second and subsequent commits with "squash" or "fixup". 433If the commits had different authors, the folded commit will be 434attributed to the author of the first commit. The suggested commit 435message for the folded commit is the concatenation of the commit 436messages of the first commit and of those with the "squash" command, 437but omits the commit messages of commits with the "fixup" command. 438 439'git rebase' will stop when "pick" has been replaced with "edit" or 440when a command fails due to merge errors. When you are done editing 441and/or resolving conflicts you can continue with `git rebase --continue`. 442 443For example, if you want to reorder the last 5 commits, such that what 444was HEAD~4 becomes the new HEAD. To achieve that, you would call 445'git rebase' like this: 446 447---------------------- 448$ git rebase -i HEAD~5 449---------------------- 450 451And move the first patch to the end of the list. 452 453You might want to preserve merges, if you have a history like this: 454 455------------------ 456 X 457 \ 458 A---M---B 459 / 460---o---O---P---Q 461------------------ 462 463Suppose you want to rebase the side branch starting at "A" to "Q". Make 464sure that the current HEAD is "B", and call 465 466----------------------------- 467$ git rebase -i -p --onto Q O 468----------------------------- 469 470 471SPLITTING COMMITS 472----------------- 473 474In interactive mode, you can mark commits with the action "edit". However, 475this does not necessarily mean that 'git rebase' expects the result of this 476edit to be exactly one commit. Indeed, you can undo the commit, or you can 477add other commits. This can be used to split a commit into two: 478 479- Start an interactive rebase with `git rebase -i <commit>^`, where 480 <commit> is the commit you want to split. In fact, any commit range 481 will do, as long as it contains that commit. 482 483- Mark the commit you want to split with the action "edit". 484 485- When it comes to editing that commit, execute `git reset HEAD^`. The 486 effect is that the HEAD is rewound by one, and the index follows suit. 487 However, the working tree stays the same. 488 489- Now add the changes to the index that you want to have in the first 490 commit. You can use `git add` (possibly interactively) or 491 'git gui' (or both) to do that. 492 493- Commit the now-current index with whatever commit message is appropriate 494 now. 495 496- Repeat the last two steps until your working tree is clean. 497 498- Continue the rebase with `git rebase --continue`. 499 500If you are not absolutely sure that the intermediate revisions are 501consistent (they compile, pass the testsuite, etc.) you should use 502'git stash' to stash away the not-yet-committed changes 503after each commit, test, and amend the commit if fixes are necessary. 504 505 506RECOVERING FROM UPSTREAM REBASE 507------------------------------- 508 509Rebasing (or any other form of rewriting) a branch that others have 510based work on is a bad idea: anyone downstream of it is forced to 511manually fix their history. This section explains how to do the fix 512from the downstream's point of view. The real fix, however, would be 513to avoid rebasing the upstream in the first place. 514 515To illustrate, suppose you are in a situation where someone develops a 516'subsystem' branch, and you are working on a 'topic' that is dependent 517on this 'subsystem'. You might end up with a history like the 518following: 519 520------------ 521 o---o---o---o---o---o---o---o---o master 522 \ 523 o---o---o---o---o subsystem 524 \ 525 *---*---* topic 526------------ 527 528If 'subsystem' is rebased against 'master', the following happens: 529 530------------ 531 o---o---o---o---o---o---o---o master 532 \ \ 533 o---o---o---o---o o'--o'--o'--o'--o' subsystem 534 \ 535 *---*---* topic 536------------ 537 538If you now continue development as usual, and eventually merge 'topic' 539to 'subsystem', the commits from 'subsystem' will remain duplicated forever: 540 541------------ 542 o---o---o---o---o---o---o---o master 543 \ \ 544 o---o---o---o---o o'--o'--o'--o'--o'--M subsystem 545 \ / 546 *---*---*-..........-*--* topic 547------------ 548 549Such duplicates are generally frowned upon because they clutter up 550history, making it harder to follow. To clean things up, you need to 551transplant the commits on 'topic' to the new 'subsystem' tip, i.e., 552rebase 'topic'. This becomes a ripple effect: anyone downstream from 553'topic' is forced to rebase too, and so on! 554 555There are two kinds of fixes, discussed in the following subsections: 556 557Easy case: The changes are literally the same.:: 558 559 This happens if the 'subsystem' rebase was a simple rebase and 560 had no conflicts. 561 562Hard case: The changes are not the same.:: 563 564 This happens if the 'subsystem' rebase had conflicts, or used 565 `\--interactive` to omit, edit, squash, or fixup commits; or 566 if the upstream used one of `commit \--amend`, `reset`, or 567 `filter-branch`. 568 569 570The easy case 571~~~~~~~~~~~~~ 572 573Only works if the changes (patch IDs based on the diff contents) on 574'subsystem' are literally the same before and after the rebase 575'subsystem' did. 576 577In that case, the fix is easy because 'git rebase' knows to skip 578changes that are already present in the new upstream. So if you say 579(assuming you're on 'topic') 580------------ 581 $ git rebase subsystem 582------------ 583you will end up with the fixed history 584------------ 585 o---o---o---o---o---o---o---o master 586 \ 587 o'--o'--o'--o'--o' subsystem 588 \ 589 *---*---* topic 590------------ 591 592 593The hard case 594~~~~~~~~~~~~~ 595 596Things get more complicated if the 'subsystem' changes do not exactly 597correspond to the ones before the rebase. 598 599NOTE: While an "easy case recovery" sometimes appears to be successful 600 even in the hard case, it may have unintended consequences. For 601 example, a commit that was removed via `git rebase 602 \--interactive` will be **resurrected**! 603 604The idea is to manually tell 'git rebase' "where the old 'subsystem' 605ended and your 'topic' began", that is, what the old merge-base 606between them was. You will have to find a way to name the last commit 607of the old 'subsystem', for example: 608 609* With the 'subsystem' reflog: after 'git fetch', the old tip of 610 'subsystem' is at `subsystem@\{1}`. Subsequent fetches will 611 increase the number. (See linkgit:git-reflog[1].) 612 613* Relative to the tip of 'topic': knowing that your 'topic' has three 614 commits, the old tip of 'subsystem' must be `topic~3`. 615 616You can then transplant the old `subsystem..topic` to the new tip by 617saying (for the reflog case, and assuming you are on 'topic' already): 618------------ 619 $ git rebase --onto subsystem subsystem@{1} 620------------ 621 622The ripple effect of a "hard case" recovery is especially bad: 623'everyone' downstream from 'topic' will now have to perform a "hard 624case" recovery too! 625 626 627BUGS 628---- 629The todo list presented by `--preserve-merges --interactive` does not 630represent the topology of the revision graph. Editing commits and 631rewording their commit messages should work fine, but attempts to 632reorder commits tend to produce counterintuitive results. 633 634For example, an attempt to rearrange 635------------ 6361 --- 2 --- 3 --- 4 --- 5 637------------ 638to 639------------ 6401 --- 2 --- 4 --- 3 --- 5 641------------ 642by moving the "pick 4" line will result in the following history: 643------------ 644 3 645 / 6461 --- 2 --- 4 --- 5 647------------ 648 649Authors 650------ 651Written by Junio C Hamano <gitster@pobox.com> and 652Johannes E. Schindelin <johannes.schindelin@gmx.de> 653 654Documentation 655-------------- 656Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. 657 658GIT 659--- 660Part of the linkgit:git[1] suite