1git-rebase(1) 2============= 3 4NAME 5---- 6git-rebase - Reapply commits on top of another base tip 7 8SYNOPSIS 9-------- 10[verse] 11'git rebase' [-i | --interactive] [<options>] [--exec <cmd>] [--onto <newbase>] 12 [<upstream> [<branch>]] 13'git rebase' [-i | --interactive] [<options>] [--exec <cmd>] [--onto <newbase>] 14 --root [<branch>] 15'git rebase' --continue | --skip | --abort | --quit | --edit-todo | --show-current-patch 16 17DESCRIPTION 18----------- 19If <branch> is specified, 'git rebase' will perform an automatic 20`git checkout <branch>` before doing anything else. Otherwise 21it remains on the current branch. 22 23If <upstream> is not specified, the upstream configured in 24branch.<name>.remote and branch.<name>.merge options will be used (see 25linkgit:git-config[1] for details) and the `--fork-point` option is 26assumed. If you are currently not on any branch or if the current 27branch does not have a configured upstream, the rebase will abort. 28 29All changes made by commits in the current branch but that are not 30in <upstream> are saved to a temporary area. This is the same set 31of commits that would be shown by `git log <upstream>..HEAD`; or by 32`git log 'fork_point'..HEAD`, if `--fork-point` is active (see the 33description on `--fork-point` below); or by `git log HEAD`, if the 34`--root` option is specified. 35 36The current branch is reset to <upstream>, or <newbase> if the 37--onto option was supplied. This has the exact same effect as 38`git reset --hard <upstream>` (or <newbase>). ORIG_HEAD is set 39to point at the tip of the branch before the reset. 40 41The commits that were previously saved into the temporary area are 42then reapplied to the current branch, one by one, in order. Note that 43any commits in HEAD which introduce the same textual changes as a commit 44in HEAD..<upstream> are omitted (i.e., a patch already accepted upstream 45with a different commit message or timestamp will be skipped). 46 47It is possible that a merge failure will prevent this process from being 48completely automatic. You will have to resolve any such merge failure 49and run `git rebase --continue`. Another option is to bypass the commit 50that caused the merge failure with `git rebase --skip`. To check out the 51original <branch> and remove the .git/rebase-apply working files, use the 52command `git rebase --abort` instead. 53 54Assume the following history exists and the current branch is "topic": 55 56------------ 57 A---B---C topic 58 / 59 D---E---F---G master 60------------ 61 62From this point, the result of either of the following commands: 63 64 65 git rebase master 66 git rebase master topic 67 68would be: 69 70------------ 71 A'--B'--C' topic 72 / 73 D---E---F---G master 74------------ 75 76*NOTE:* The latter form is just a short-hand of `git checkout topic` 77followed by `git rebase master`. When rebase exits `topic` will 78remain the checked-out branch. 79 80If the upstream branch already contains a change you have made (e.g., 81because you mailed a patch which was applied upstream), then that commit 82will be skipped. For example, running `git rebase master` on the 83following history (in which `A'` and `A` introduce the same set of changes, 84but have different committer information): 85 86------------ 87 A---B---C topic 88 / 89 D---E---A'---F master 90------------ 91 92will result in: 93 94------------ 95 B'---C' topic 96 / 97 D---E---A'---F master 98------------ 99 100Here is how you would transplant a topic branch based on one 101branch to another, to pretend that you forked the topic branch 102from the latter branch, using `rebase --onto`. 103 104First let's assume your 'topic' is based on branch 'next'. 105For example, a feature developed in 'topic' depends on some 106functionality which is found in 'next'. 107 108------------ 109 o---o---o---o---o master 110 \ 111 o---o---o---o---o next 112 \ 113 o---o---o topic 114------------ 115 116We want to make 'topic' forked from branch 'master'; for example, 117because the functionality on which 'topic' depends was merged into the 118more stable 'master' branch. We want our tree to look like this: 119 120------------ 121 o---o---o---o---o master 122 | \ 123 | o'--o'--o' topic 124 \ 125 o---o---o---o---o next 126------------ 127 128We can get this using the following command: 129 130 git rebase --onto master next topic 131 132 133Another example of --onto option is to rebase part of a 134branch. If we have the following situation: 135 136------------ 137 H---I---J topicB 138 / 139 E---F---G topicA 140 / 141 A---B---C---D master 142------------ 143 144then the command 145 146 git rebase --onto master topicA topicB 147 148would result in: 149 150------------ 151 H'--I'--J' topicB 152 / 153 | E---F---G topicA 154 |/ 155 A---B---C---D master 156------------ 157 158This is useful when topicB does not depend on topicA. 159 160A range of commits could also be removed with rebase. If we have 161the following situation: 162 163------------ 164 E---F---G---H---I---J topicA 165------------ 166 167then the command 168 169 git rebase --onto topicA~5 topicA~3 topicA 170 171would result in the removal of commits F and G: 172 173------------ 174 E---H'---I'---J' topicA 175------------ 176 177This is useful if F and G were flawed in some way, or should not be 178part of topicA. Note that the argument to --onto and the <upstream> 179parameter can be any valid commit-ish. 180 181In case of conflict, 'git rebase' will stop at the first problematic commit 182and leave conflict markers in the tree. You can use 'git diff' to locate 183the markers (<<<<<<) and make edits to resolve the conflict. For each 184file you edit, you need to tell Git that the conflict has been resolved, 185typically this would be done with 186 187 188 git add <filename> 189 190 191After resolving the conflict manually and updating the index with the 192desired resolution, you can continue the rebasing process with 193 194 195 git rebase --continue 196 197 198Alternatively, you can undo the 'git rebase' with 199 200 201 git rebase --abort 202 203CONFIGURATION 204------------- 205 206include::config/rebase.txt[] 207 208OPTIONS 209------- 210--onto <newbase>:: 211 Starting point at which to create the new commits. If the 212 --onto option is not specified, the starting point is 213 <upstream>. May be any valid commit, and not just an 214 existing branch name. 215+ 216As a special case, you may use "A\...B" as a shortcut for the 217merge base of A and B if there is exactly one merge base. You can 218leave out at most one of A and B, in which case it defaults to HEAD. 219 220<upstream>:: 221 Upstream branch to compare against. May be any valid commit, 222 not just an existing branch name. Defaults to the configured 223 upstream for the current branch. 224 225<branch>:: 226 Working branch; defaults to HEAD. 227 228--continue:: 229 Restart the rebasing process after having resolved a merge conflict. 230 231--abort:: 232 Abort the rebase operation and reset HEAD to the original 233 branch. If <branch> was provided when the rebase operation was 234 started, then HEAD will be reset to <branch>. Otherwise HEAD 235 will be reset to where it was when the rebase operation was 236 started. 237 238--quit:: 239 Abort the rebase operation but HEAD is not reset back to the 240 original branch. The index and working tree are also left 241 unchanged as a result. 242 243--keep-empty:: 244 Keep the commits that do not change anything from its 245 parents in the result. 246+ 247See also INCOMPATIBLE OPTIONS below. 248 249--allow-empty-message:: 250 By default, rebasing commits with an empty message will fail. 251 This option overrides that behavior, allowing commits with empty 252 messages to be rebased. 253+ 254See also INCOMPATIBLE OPTIONS below. 255 256--skip:: 257 Restart the rebasing process by skipping the current patch. 258 259--edit-todo:: 260 Edit the todo list during an interactive rebase. 261 262--show-current-patch:: 263 Show the current patch in an interactive rebase or when rebase 264 is stopped because of conflicts. This is the equivalent of 265 `git show REBASE_HEAD`. 266 267-m:: 268--merge:: 269 Use merging strategies to rebase. When the recursive (default) merge 270 strategy is used, this allows rebase to be aware of renames on the 271 upstream side. 272+ 273Note that a rebase merge works by replaying each commit from the working 274branch on top of the <upstream> branch. Because of this, when a merge 275conflict happens, the side reported as 'ours' is the so-far rebased 276series, starting with <upstream>, and 'theirs' is the working branch. In 277other words, the sides are swapped. 278+ 279See also INCOMPATIBLE OPTIONS below. 280 281-s <strategy>:: 282--strategy=<strategy>:: 283 Use the given merge strategy. 284 If there is no `-s` option 'git merge-recursive' is used 285 instead. This implies --merge. 286+ 287Because 'git rebase' replays each commit from the working branch 288on top of the <upstream> branch using the given strategy, using 289the 'ours' strategy simply empties all patches from the <branch>, 290which makes little sense. 291+ 292See also INCOMPATIBLE OPTIONS below. 293 294-X <strategy-option>:: 295--strategy-option=<strategy-option>:: 296 Pass the <strategy-option> through to the merge strategy. 297 This implies `--merge` and, if no strategy has been 298 specified, `-s recursive`. Note the reversal of 'ours' and 299 'theirs' as noted above for the `-m` option. 300+ 301See also INCOMPATIBLE OPTIONS below. 302 303--rerere-autoupdate:: 304--no-rerere-autoupdate:: 305 Allow the rerere mechanism to update the index with the 306 result of auto-conflict resolution if possible. 307 308-S[<keyid>]:: 309--gpg-sign[=<keyid>]:: 310 GPG-sign commits. The `keyid` argument is optional and 311 defaults to the committer identity; if specified, it must be 312 stuck to the option without a space. 313 314-q:: 315--quiet:: 316 Be quiet. Implies --no-stat. 317 318-v:: 319--verbose:: 320 Be verbose. Implies --stat. 321 322--stat:: 323 Show a diffstat of what changed upstream since the last rebase. The 324 diffstat is also controlled by the configuration option rebase.stat. 325 326-n:: 327--no-stat:: 328 Do not show a diffstat as part of the rebase process. 329 330--no-verify:: 331 This option bypasses the pre-rebase hook. See also linkgit:githooks[5]. 332 333--verify:: 334 Allows the pre-rebase hook to run, which is the default. This option can 335 be used to override --no-verify. See also linkgit:githooks[5]. 336 337-C<n>:: 338 Ensure at least <n> lines of surrounding context match before 339 and after each change. When fewer lines of surrounding 340 context exist they all must match. By default no context is 341 ever ignored. 342+ 343See also INCOMPATIBLE OPTIONS below. 344 345--no-ff:: 346--force-rebase:: 347-f:: 348 Individually replay all rebased commits instead of fast-forwarding 349 over the unchanged ones. This ensures that the entire history of 350 the rebased branch is composed of new commits. 351+ 352You may find this helpful after reverting a topic branch merge, as this option 353recreates the topic branch with fresh commits so it can be remerged 354successfully without needing to "revert the reversion" (see the 355link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for 356details). 357 358--fork-point:: 359--no-fork-point:: 360 Use reflog to find a better common ancestor between <upstream> 361 and <branch> when calculating which commits have been 362 introduced by <branch>. 363+ 364When --fork-point is active, 'fork_point' will be used instead of 365<upstream> to calculate the set of commits to rebase, where 366'fork_point' is the result of `git merge-base --fork-point <upstream> 367<branch>` command (see linkgit:git-merge-base[1]). If 'fork_point' 368ends up being empty, the <upstream> will be used as a fallback. 369+ 370If either <upstream> or --root is given on the command line, then the 371default is `--no-fork-point`, otherwise the default is `--fork-point`. 372 373--ignore-whitespace:: 374--whitespace=<option>:: 375 These flag are passed to the 'git apply' program 376 (see linkgit:git-apply[1]) that applies the patch. 377+ 378See also INCOMPATIBLE OPTIONS below. 379 380--committer-date-is-author-date:: 381--ignore-date:: 382 These flags are passed to 'git am' to easily change the dates 383 of the rebased commits (see linkgit:git-am[1]). 384+ 385See also INCOMPATIBLE OPTIONS below. 386 387--signoff:: 388 Add a Signed-off-by: trailer to all the rebased commits. Note 389 that if `--interactive` is given then only commits marked to be 390 picked, edited or reworded will have the trailer added. 391+ 392See also INCOMPATIBLE OPTIONS below. 393 394-i:: 395--interactive:: 396 Make a list of the commits which are about to be rebased. Let the 397 user edit that list before rebasing. This mode can also be used to 398 split commits (see SPLITTING COMMITS below). 399+ 400The commit list format can be changed by setting the configuration option 401rebase.instructionFormat. A customized instruction format will automatically 402have the long commit hash prepended to the format. 403+ 404See also INCOMPATIBLE OPTIONS below. 405 406-r:: 407--rebase-merges[=(rebase-cousins|no-rebase-cousins)]:: 408 By default, a rebase will simply drop merge commits from the todo 409 list, and put the rebased commits into a single, linear branch. 410 With `--rebase-merges`, the rebase will instead try to preserve 411 the branching structure within the commits that are to be rebased, 412 by recreating the merge commits. Any resolved merge conflicts or 413 manual amendments in these merge commits will have to be 414 resolved/re-applied manually. 415+ 416By default, or when `no-rebase-cousins` was specified, commits which do not 417have `<upstream>` as direct ancestor will keep their original branch point, 418i.e. commits that would be excluded by linkgit:git-log[1]'s 419`--ancestry-path` option will keep their original ancestry by default. If 420the `rebase-cousins` mode is turned on, such commits are instead rebased 421onto `<upstream>` (or `<onto>`, if specified). 422+ 423The `--rebase-merges` mode is similar in spirit to the deprecated 424`--preserve-merges`, but in contrast to that option works well in interactive 425rebases: commits can be reordered, inserted and dropped at will. 426+ 427It is currently only possible to recreate the merge commits using the 428`recursive` merge strategy; Different merge strategies can be used only via 429explicit `exec git merge -s <strategy> [...]` commands. 430+ 431See also REBASING MERGES and INCOMPATIBLE OPTIONS below. 432 433-p:: 434--preserve-merges:: 435 [DEPRECATED: use `--rebase-merges` instead] Recreate merge commits 436 instead of flattening the history by replaying commits a merge commit 437 introduces. Merge conflict resolutions or manual amendments to merge 438 commits are not preserved. 439+ 440This uses the `--interactive` machinery internally, but combining it 441with the `--interactive` option explicitly is generally not a good 442idea unless you know what you are doing (see BUGS below). 443+ 444See also INCOMPATIBLE OPTIONS below. 445 446-x <cmd>:: 447--exec <cmd>:: 448 Append "exec <cmd>" after each line creating a commit in the 449 final history. <cmd> will be interpreted as one or more shell 450 commands. Any command that fails will interrupt the rebase, 451 with exit code 1. 452+ 453You may execute several commands by either using one instance of `--exec` 454with several commands: 455+ 456 git rebase -i --exec "cmd1 && cmd2 && ..." 457+ 458or by giving more than one `--exec`: 459+ 460 git rebase -i --exec "cmd1" --exec "cmd2" --exec ... 461+ 462If `--autosquash` is used, "exec" lines will not be appended for 463the intermediate commits, and will only appear at the end of each 464squash/fixup series. 465+ 466This uses the `--interactive` machinery internally, but it can be run 467without an explicit `--interactive`. 468+ 469See also INCOMPATIBLE OPTIONS below. 470 471--root:: 472 Rebase all commits reachable from <branch>, instead of 473 limiting them with an <upstream>. This allows you to rebase 474 the root commit(s) on a branch. When used with --onto, it 475 will skip changes already contained in <newbase> (instead of 476 <upstream>) whereas without --onto it will operate on every change. 477 When used together with both --onto and --preserve-merges, 478 'all' root commits will be rewritten to have <newbase> as parent 479 instead. 480+ 481See also INCOMPATIBLE OPTIONS below. 482 483--autosquash:: 484--no-autosquash:: 485 When the commit log message begins with "squash! ..." (or 486 "fixup! ..."), and there is already a commit in the todo list that 487 matches the same `...`, automatically modify the todo list of rebase 488 -i so that the commit marked for squashing comes right after the 489 commit to be modified, and change the action of the moved commit 490 from `pick` to `squash` (or `fixup`). A commit matches the `...` if 491 the commit subject matches, or if the `...` refers to the commit's 492 hash. As a fall-back, partial matches of the commit subject work, 493 too. The recommended way to create fixup/squash commits is by using 494 the `--fixup`/`--squash` options of linkgit:git-commit[1]. 495+ 496If the `--autosquash` option is enabled by default using the 497configuration variable `rebase.autoSquash`, this option can be 498used to override and disable this setting. 499+ 500See also INCOMPATIBLE OPTIONS below. 501 502--autostash:: 503--no-autostash:: 504 Automatically create a temporary stash entry before the operation 505 begins, and apply it after the operation ends. This means 506 that you can run rebase on a dirty worktree. However, use 507 with care: the final stash application after a successful 508 rebase might result in non-trivial conflicts. 509 510--reschedule-failed-exec:: 511--no-reschedule-failed-exec:: 512 Automatically reschedule `exec` commands that failed. This only makes 513 sense in interactive mode (or when an `--exec` option was provided). 514 515INCOMPATIBLE OPTIONS 516-------------------- 517 518The following options: 519 520 * --committer-date-is-author-date 521 * --ignore-date 522 * --whitespace 523 * --ignore-whitespace 524 * -C 525 526are incompatible with the following options: 527 528 * --merge 529 * --strategy 530 * --strategy-option 531 * --allow-empty-message 532 * --[no-]autosquash 533 * --rebase-merges 534 * --preserve-merges 535 * --interactive 536 * --exec 537 * --keep-empty 538 * --edit-todo 539 * --root when used in combination with --onto 540 541In addition, the following pairs of options are incompatible: 542 543 * --preserve-merges and --interactive 544 * --preserve-merges and --signoff 545 * --preserve-merges and --rebase-merges 546 * --rebase-merges and --strategy 547 * --rebase-merges and --strategy-option 548 549BEHAVIORAL DIFFERENCES 550----------------------- 551 552There are some subtle differences how the backends behave. 553 554Empty commits 555~~~~~~~~~~~~~ 556 557The am backend drops any "empty" commits, regardless of whether the 558commit started empty (had no changes relative to its parent to 559start with) or ended empty (all changes were already applied 560upstream in other commits). 561 562The interactive backend drops commits by default that 563started empty and halts if it hits a commit that ended up empty. 564The `--keep-empty` option exists for the interactive backend to allow 565it to keep commits that started empty. 566 567Directory rename detection 568~~~~~~~~~~~~~~~~~~~~~~~~~~ 569 570Directory rename heuristics are enabled in the merge and interactive 571backends. Due to the lack of accurate tree information, directory 572rename detection is disabled in the am backend. 573 574include::merge-strategies.txt[] 575 576NOTES 577----- 578 579You should understand the implications of using 'git rebase' on a 580repository that you share. See also RECOVERING FROM UPSTREAM REBASE 581below. 582 583When the git-rebase command is run, it will first execute a "pre-rebase" 584hook if one exists. You can use this hook to do sanity checks and 585reject the rebase if it isn't appropriate. Please see the template 586pre-rebase hook script for an example. 587 588Upon completion, <branch> will be the current branch. 589 590INTERACTIVE MODE 591---------------- 592 593Rebasing interactively means that you have a chance to edit the commits 594which are rebased. You can reorder the commits, and you can 595remove them (weeding out bad or otherwise unwanted patches). 596 597The interactive mode is meant for this type of workflow: 598 5991. have a wonderful idea 6002. hack on the code 6013. prepare a series for submission 6024. submit 603 604where point 2. consists of several instances of 605 606a) regular use 607 608 1. finish something worthy of a commit 609 2. commit 610 611b) independent fixup 612 613 1. realize that something does not work 614 2. fix that 615 3. commit it 616 617Sometimes the thing fixed in b.2. cannot be amended to the not-quite 618perfect commit it fixes, because that commit is buried deeply in a 619patch series. That is exactly what interactive rebase is for: use it 620after plenty of "a"s and "b"s, by rearranging and editing 621commits, and squashing multiple commits into one. 622 623Start it with the last commit you want to retain as-is: 624 625 git rebase -i <after-this-commit> 626 627An editor will be fired up with all the commits in your current branch 628(ignoring merge commits), which come after the given commit. You can 629reorder the commits in this list to your heart's content, and you can 630remove them. The list looks more or less like this: 631 632------------------------------------------- 633pick deadbee The oneline of this commit 634pick fa1afe1 The oneline of the next commit 635... 636------------------------------------------- 637 638The oneline descriptions are purely for your pleasure; 'git rebase' will 639not look at them but at the commit names ("deadbee" and "fa1afe1" in this 640example), so do not delete or edit the names. 641 642By replacing the command "pick" with the command "edit", you can tell 643'git rebase' to stop after applying that commit, so that you can edit 644the files and/or the commit message, amend the commit, and continue 645rebasing. 646 647To interrupt the rebase (just like an "edit" command would do, but without 648cherry-picking any commit first), use the "break" command. 649 650If you just want to edit the commit message for a commit, replace the 651command "pick" with the command "reword". 652 653To drop a commit, replace the command "pick" with "drop", or just 654delete the matching line. 655 656If you want to fold two or more commits into one, replace the command 657"pick" for the second and subsequent commits with "squash" or "fixup". 658If the commits had different authors, the folded commit will be 659attributed to the author of the first commit. The suggested commit 660message for the folded commit is the concatenation of the commit 661messages of the first commit and of those with the "squash" command, 662but omits the commit messages of commits with the "fixup" command. 663 664'git rebase' will stop when "pick" has been replaced with "edit" or 665when a command fails due to merge errors. When you are done editing 666and/or resolving conflicts you can continue with `git rebase --continue`. 667 668For example, if you want to reorder the last 5 commits, such that what 669was HEAD~4 becomes the new HEAD. To achieve that, you would call 670'git rebase' like this: 671 672---------------------- 673$ git rebase -i HEAD~5 674---------------------- 675 676And move the first patch to the end of the list. 677 678You might want to recreate merge commits, e.g. if you have a history 679like this: 680 681------------------ 682 X 683 \ 684 A---M---B 685 / 686---o---O---P---Q 687------------------ 688 689Suppose you want to rebase the side branch starting at "A" to "Q". Make 690sure that the current HEAD is "B", and call 691 692----------------------------- 693$ git rebase -i -r --onto Q O 694----------------------------- 695 696Reordering and editing commits usually creates untested intermediate 697steps. You may want to check that your history editing did not break 698anything by running a test, or at least recompiling at intermediate 699points in history by using the "exec" command (shortcut "x"). You may 700do so by creating a todo list like this one: 701 702------------------------------------------- 703pick deadbee Implement feature XXX 704fixup f1a5c00 Fix to feature XXX 705exec make 706pick c0ffeee The oneline of the next commit 707edit deadbab The oneline of the commit after 708exec cd subdir; make test 709... 710------------------------------------------- 711 712The interactive rebase will stop when a command fails (i.e. exits with 713non-0 status) to give you an opportunity to fix the problem. You can 714continue with `git rebase --continue`. 715 716The "exec" command launches the command in a shell (the one specified 717in `$SHELL`, or the default shell if `$SHELL` is not set), so you can 718use shell features (like "cd", ">", ";" ...). The command is run from 719the root of the working tree. 720 721---------------------------------- 722$ git rebase -i --exec "make test" 723---------------------------------- 724 725This command lets you check that intermediate commits are compilable. 726The todo list becomes like that: 727 728-------------------- 729pick 5928aea one 730exec make test 731pick 04d0fda two 732exec make test 733pick ba46169 three 734exec make test 735pick f4593f9 four 736exec make test 737-------------------- 738 739SPLITTING COMMITS 740----------------- 741 742In interactive mode, you can mark commits with the action "edit". However, 743this does not necessarily mean that 'git rebase' expects the result of this 744edit to be exactly one commit. Indeed, you can undo the commit, or you can 745add other commits. This can be used to split a commit into two: 746 747- Start an interactive rebase with `git rebase -i <commit>^`, where 748 <commit> is the commit you want to split. In fact, any commit range 749 will do, as long as it contains that commit. 750 751- Mark the commit you want to split with the action "edit". 752 753- When it comes to editing that commit, execute `git reset HEAD^`. The 754 effect is that the HEAD is rewound by one, and the index follows suit. 755 However, the working tree stays the same. 756 757- Now add the changes to the index that you want to have in the first 758 commit. You can use `git add` (possibly interactively) or 759 'git gui' (or both) to do that. 760 761- Commit the now-current index with whatever commit message is appropriate 762 now. 763 764- Repeat the last two steps until your working tree is clean. 765 766- Continue the rebase with `git rebase --continue`. 767 768If you are not absolutely sure that the intermediate revisions are 769consistent (they compile, pass the testsuite, etc.) you should use 770'git stash' to stash away the not-yet-committed changes 771after each commit, test, and amend the commit if fixes are necessary. 772 773 774RECOVERING FROM UPSTREAM REBASE 775------------------------------- 776 777Rebasing (or any other form of rewriting) a branch that others have 778based work on is a bad idea: anyone downstream of it is forced to 779manually fix their history. This section explains how to do the fix 780from the downstream's point of view. The real fix, however, would be 781to avoid rebasing the upstream in the first place. 782 783To illustrate, suppose you are in a situation where someone develops a 784'subsystem' branch, and you are working on a 'topic' that is dependent 785on this 'subsystem'. You might end up with a history like the 786following: 787 788------------ 789 o---o---o---o---o---o---o---o master 790 \ 791 o---o---o---o---o subsystem 792 \ 793 *---*---* topic 794------------ 795 796If 'subsystem' is rebased against 'master', the following happens: 797 798------------ 799 o---o---o---o---o---o---o---o master 800 \ \ 801 o---o---o---o---o o'--o'--o'--o'--o' subsystem 802 \ 803 *---*---* topic 804------------ 805 806If you now continue development as usual, and eventually merge 'topic' 807to 'subsystem', the commits from 'subsystem' will remain duplicated forever: 808 809------------ 810 o---o---o---o---o---o---o---o master 811 \ \ 812 o---o---o---o---o o'--o'--o'--o'--o'--M subsystem 813 \ / 814 *---*---*-..........-*--* topic 815------------ 816 817Such duplicates are generally frowned upon because they clutter up 818history, making it harder to follow. To clean things up, you need to 819transplant the commits on 'topic' to the new 'subsystem' tip, i.e., 820rebase 'topic'. This becomes a ripple effect: anyone downstream from 821'topic' is forced to rebase too, and so on! 822 823There are two kinds of fixes, discussed in the following subsections: 824 825Easy case: The changes are literally the same.:: 826 827 This happens if the 'subsystem' rebase was a simple rebase and 828 had no conflicts. 829 830Hard case: The changes are not the same.:: 831 832 This happens if the 'subsystem' rebase had conflicts, or used 833 `--interactive` to omit, edit, squash, or fixup commits; or 834 if the upstream used one of `commit --amend`, `reset`, or 835 `filter-branch`. 836 837 838The easy case 839~~~~~~~~~~~~~ 840 841Only works if the changes (patch IDs based on the diff contents) on 842'subsystem' are literally the same before and after the rebase 843'subsystem' did. 844 845In that case, the fix is easy because 'git rebase' knows to skip 846changes that are already present in the new upstream. So if you say 847(assuming you're on 'topic') 848------------ 849 $ git rebase subsystem 850------------ 851you will end up with the fixed history 852------------ 853 o---o---o---o---o---o---o---o master 854 \ 855 o'--o'--o'--o'--o' subsystem 856 \ 857 *---*---* topic 858------------ 859 860 861The hard case 862~~~~~~~~~~~~~ 863 864Things get more complicated if the 'subsystem' changes do not exactly 865correspond to the ones before the rebase. 866 867NOTE: While an "easy case recovery" sometimes appears to be successful 868 even in the hard case, it may have unintended consequences. For 869 example, a commit that was removed via `git rebase 870 --interactive` will be **resurrected**! 871 872The idea is to manually tell 'git rebase' "where the old 'subsystem' 873ended and your 'topic' began", that is, what the old merge-base 874between them was. You will have to find a way to name the last commit 875of the old 'subsystem', for example: 876 877* With the 'subsystem' reflog: after 'git fetch', the old tip of 878 'subsystem' is at `subsystem@{1}`. Subsequent fetches will 879 increase the number. (See linkgit:git-reflog[1].) 880 881* Relative to the tip of 'topic': knowing that your 'topic' has three 882 commits, the old tip of 'subsystem' must be `topic~3`. 883 884You can then transplant the old `subsystem..topic` to the new tip by 885saying (for the reflog case, and assuming you are on 'topic' already): 886------------ 887 $ git rebase --onto subsystem subsystem@{1} 888------------ 889 890The ripple effect of a "hard case" recovery is especially bad: 891'everyone' downstream from 'topic' will now have to perform a "hard 892case" recovery too! 893 894REBASING MERGES 895--------------- 896 897The interactive rebase command was originally designed to handle 898individual patch series. As such, it makes sense to exclude merge 899commits from the todo list, as the developer may have merged the 900then-current `master` while working on the branch, only to rebase 901all the commits onto `master` eventually (skipping the merge 902commits). 903 904However, there are legitimate reasons why a developer may want to 905recreate merge commits: to keep the branch structure (or "commit 906topology") when working on multiple, inter-related branches. 907 908In the following example, the developer works on a topic branch that 909refactors the way buttons are defined, and on another topic branch 910that uses that refactoring to implement a "Report a bug" button. The 911output of `git log --graph --format=%s -5` may look like this: 912 913------------ 914* Merge branch 'report-a-bug' 915|\ 916| * Add the feedback button 917* | Merge branch 'refactor-button' 918|\ \ 919| |/ 920| * Use the Button class for all buttons 921| * Extract a generic Button class from the DownloadButton one 922------------ 923 924The developer might want to rebase those commits to a newer `master` 925while keeping the branch topology, for example when the first topic 926branch is expected to be integrated into `master` much earlier than the 927second one, say, to resolve merge conflicts with changes to the 928DownloadButton class that made it into `master`. 929 930This rebase can be performed using the `--rebase-merges` option. 931It will generate a todo list looking like this: 932 933------------ 934label onto 935 936# Branch: refactor-button 937reset onto 938pick 123456 Extract a generic Button class from the DownloadButton one 939pick 654321 Use the Button class for all buttons 940label refactor-button 941 942# Branch: report-a-bug 943reset refactor-button # Use the Button class for all buttons 944pick abcdef Add the feedback button 945label report-a-bug 946 947reset onto 948merge -C a1b2c3 refactor-button # Merge 'refactor-button' 949merge -C 6f5e4d report-a-bug # Merge 'report-a-bug' 950------------ 951 952In contrast to a regular interactive rebase, there are `label`, `reset` 953and `merge` commands in addition to `pick` ones. 954 955The `label` command associates a label with the current HEAD when that 956command is executed. These labels are created as worktree-local refs 957(`refs/rewritten/<label>`) that will be deleted when the rebase 958finishes. That way, rebase operations in multiple worktrees linked to 959the same repository do not interfere with one another. If the `label` 960command fails, it is rescheduled immediately, with a helpful message how 961to proceed. 962 963The `reset` command resets the HEAD, index and worktree to the specified 964revision. It is similar to an `exec git reset --hard <label>`, but 965refuses to overwrite untracked files. If the `reset` command fails, it is 966rescheduled immediately, with a helpful message how to edit the todo list 967(this typically happens when a `reset` command was inserted into the todo 968list manually and contains a typo). 969 970The `merge` command will merge the specified revision(s) into whatever 971is HEAD at that time. With `-C <original-commit>`, the commit message of 972the specified merge commit will be used. When the `-C` is changed to 973a lower-case `-c`, the message will be opened in an editor after a 974successful merge so that the user can edit the message. 975 976If a `merge` command fails for any reason other than merge conflicts (i.e. 977when the merge operation did not even start), it is rescheduled immediately. 978 979At this time, the `merge` command will *always* use the `recursive` 980merge strategy for regular merges, and `octopus` for octopus merges, 981with no way to choose a different one. To work around 982this, an `exec` command can be used to call `git merge` explicitly, 983using the fact that the labels are worktree-local refs (the ref 984`refs/rewritten/onto` would correspond to the label `onto`, for example). 985 986Note: the first command (`label onto`) labels the revision onto which 987the commits are rebased; The name `onto` is just a convention, as a nod 988to the `--onto` option. 989 990It is also possible to introduce completely new merge commits from scratch 991by adding a command of the form `merge <merge-head>`. This form will 992generate a tentative commit message and always open an editor to let the 993user edit it. This can be useful e.g. when a topic branch turns out to 994address more than a single concern and wants to be split into two or 995even more topic branches. Consider this todo list: 996 997------------ 998pick 192837 Switch from GNU Makefiles to CMake 999pick 5a6c7e Document the switch to CMake1000pick 918273 Fix detection of OpenSSL in CMake1001pick afbecd http: add support for TLS v1.31002pick fdbaec Fix detection of cURL in CMake on Windows1003------------10041005The one commit in this list that is not related to CMake may very well1006have been motivated by working on fixing all those bugs introduced by1007switching to CMake, but it addresses a different concern. To split this1008branch into two topic branches, the todo list could be edited like this:10091010------------1011label onto10121013pick afbecd http: add support for TLS v1.31014label tlsv1.310151016reset onto1017pick 192837 Switch from GNU Makefiles to CMake1018pick 918273 Fix detection of OpenSSL in CMake1019pick fdbaec Fix detection of cURL in CMake on Windows1020pick 5a6c7e Document the switch to CMake1021label cmake10221023reset onto1024merge tlsv1.31025merge cmake1026------------10271028BUGS1029----1030The todo list presented by the deprecated `--preserve-merges --interactive`1031does not represent the topology of the revision graph (use `--rebase-merges`1032instead). Editing commits and rewording their commit messages should work1033fine, but attempts to reorder commits tend to produce counterintuitive results.1034Use `--rebase-merges` in such scenarios instead.10351036For example, an attempt to rearrange1037------------10381 --- 2 --- 3 --- 4 --- 51039------------1040to1041------------10421 --- 2 --- 4 --- 3 --- 51043------------1044by moving the "pick 4" line will result in the following history:1045------------1046 31047 /10481 --- 2 --- 4 --- 51049------------10501051GIT1052---1053Part of the linkgit:git[1] suite