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