| 1 | git-rebase(1) |
| 2 | ============= |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | git-rebase - Reapply commits on top of another base tip |
| 7 | |
| 8 | SYNOPSIS |
| 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 | |
| 17 | DESCRIPTION |
| 18 | ----------- |
| 19 | Transplant a series of commits onto a different starting point. |
| 20 | You can also use `git rebase` to reorder or combine commits: see INTERACTIVE |
| 21 | MODE below for how to do that. |
| 22 | |
| 23 | For example, imagine that you have been working on the `topic` branch in this |
| 24 | history, and you want to "catch up" to the work done on the `master` branch. |
| 25 | |
| 26 | ------------ |
| 27 | A---B---C topic |
| 28 | / |
| 29 | D---E---F---G master |
| 30 | ------------ |
| 31 | |
| 32 | You want to transplant the commits you made on `topic` since it diverged from |
| 33 | `master` (i.e. A, B, and C), on top of the current `master`. You can do this |
| 34 | by running `git rebase master` while the `topic` branch is checked out. If you |
| 35 | want to rebase `topic` while on another branch, `git rebase master topic` is a |
| 36 | shortcut for `git checkout topic && git rebase master`. |
| 37 | |
| 38 | ------------ |
| 39 | A'--B'--C' topic |
| 40 | / |
| 41 | D---E---F---G master |
| 42 | ------------ |
| 43 | |
| 44 | |
| 45 | If there is a merge conflict during this process, `git rebase` will stop at the |
| 46 | first problematic commit and leave conflict markers. If this happens, you can do |
| 47 | one of these things: |
| 48 | |
| 49 | 1. Resolve the conflict. You can use `git diff` to find the markers (<<<<<<) |
| 50 | and make edits to resolve the conflict. For each file you edit, you need to |
| 51 | tell Git that the conflict has been resolved. You can mark the conflict as |
| 52 | resolved with `git add <filename>`. After resolving all of the conflicts, |
| 53 | you can continue the rebasing process with |
| 54 | |
| 55 | git rebase --continue |
| 56 | |
| 57 | 2. Stop the `git rebase` and return your branch to its original state with |
| 58 | |
| 59 | git rebase --abort |
| 60 | |
| 61 | 3. Skip the commit that caused the merge conflict with |
| 62 | |
| 63 | git rebase --skip |
| 64 | |
| 65 | If you don't specify an `<upstream>` to rebase onto, the upstream configured in |
| 66 | `branch.<name>.remote` and `branch.<name>.merge` options will be used (see |
| 67 | linkgit:git-config[1] for details) and the `--fork-point` option is |
| 68 | assumed. If you are currently not on any branch or if the current |
| 69 | branch does not have a configured upstream, the rebase will abort. |
| 70 | |
| 71 | Here is a simplified description of what `git rebase <upstream>` does: |
| 72 | |
| 73 | 1. Make a list of all commits on your current branch since it branched |
| 74 | off from `<upstream>` that do not have an equivalent commit in |
| 75 | `<upstream>`. |
| 76 | 2. Check out `<upstream>` with the equivalent of |
| 77 | `git checkout --detach <upstream>`. |
| 78 | 3. Replay the commits, one by one, in order. This is similar to running |
| 79 | `git cherry-pick <commit>` for each commit. See REBASING MERGES for how merges |
| 80 | are handled. |
| 81 | 4. Update your branch to point to the final commit with the equivalent |
| 82 | of `git checkout -B <branch>`. |
| 83 | |
| 84 | [NOTE] |
| 85 | When starting the rebase, `ORIG_HEAD` is set to point to the commit at the tip |
| 86 | of the to-be-rebased branch. However, `ORIG_HEAD` is not guaranteed to still |
| 87 | point to that commit at the end of the rebase if other commands that change |
| 88 | `ORIG_HEAD` (like `git reset`) are used during the rebase. The previous branch |
| 89 | tip, however, is accessible using the reflog of the current branch (i.e. `@{1}`, |
| 90 | see linkgit:gitrevisions[7]). |
| 91 | |
| 92 | TRANSPLANTING A TOPIC BRANCH WITH --ONTO |
| 93 | ---------------------------------------- |
| 94 | |
| 95 | Here is how you would transplant a topic branch based on one |
| 96 | branch to another, to pretend that you forked the topic branch |
| 97 | from the latter branch, using `rebase --onto`. |
| 98 | |
| 99 | First let's assume your 'topic' is based on branch 'next'. |
| 100 | For example, a feature developed in 'topic' depends on some |
| 101 | functionality which is found in 'next'. |
| 102 | |
| 103 | ------------ |
| 104 | o---o---o---o---o master |
| 105 | \ |
| 106 | o---o---o---o---o next |
| 107 | \ |
| 108 | o---o---o topic |
| 109 | ------------ |
| 110 | |
| 111 | We want to make 'topic' forked from branch 'master'; for example, |
| 112 | because the functionality on which 'topic' depends was merged into the |
| 113 | more stable 'master' branch. We want our tree to look like this: |
| 114 | |
| 115 | ------------ |
| 116 | o---o---o---o---o master |
| 117 | | \ |
| 118 | | o'--o'--o' topic |
| 119 | \ |
| 120 | o---o---o---o---o next |
| 121 | ------------ |
| 122 | |
| 123 | We can get this using the following command: |
| 124 | |
| 125 | git rebase --onto master next topic |
| 126 | |
| 127 | |
| 128 | Another example of --onto option is to rebase part of a |
| 129 | branch. If we have the following situation: |
| 130 | |
| 131 | ------------ |
| 132 | H---I---J topicB |
| 133 | / |
| 134 | E---F---G topicA |
| 135 | / |
| 136 | A---B---C---D master |
| 137 | ------------ |
| 138 | |
| 139 | then the command |
| 140 | |
| 141 | git rebase --onto master topicA topicB |
| 142 | |
| 143 | would result in: |
| 144 | |
| 145 | ------------ |
| 146 | H'--I'--J' topicB |
| 147 | / |
| 148 | | E---F---G topicA |
| 149 | |/ |
| 150 | A---B---C---D master |
| 151 | ------------ |
| 152 | |
| 153 | This is useful when topicB does not depend on topicA. |
| 154 | |
| 155 | A range of commits could also be removed with rebase. If we have |
| 156 | the following situation: |
| 157 | |
| 158 | ------------ |
| 159 | E---F---G---H---I---J topicA |
| 160 | ------------ |
| 161 | |
| 162 | then the command |
| 163 | |
| 164 | git rebase --onto topicA~5 topicA~3 topicA |
| 165 | |
| 166 | would result in the removal of commits F and G: |
| 167 | |
| 168 | ------------ |
| 169 | E---H'---I'---J' topicA |
| 170 | ------------ |
| 171 | |
| 172 | This is useful if F and G were flawed in some way, or should not be |
| 173 | part of topicA. Note that the argument to `--onto` and the `<upstream>` |
| 174 | parameter can be any valid commit-ish. |
| 175 | |
| 176 | MODE OPTIONS |
| 177 | ------------ |
| 178 | |
| 179 | The options in this section cannot be used with any other option, |
| 180 | including not with each other: |
| 181 | |
| 182 | --continue:: |
| 183 | Restart the rebasing process after having resolved a merge conflict. |
| 184 | |
| 185 | --skip:: |
| 186 | Restart the rebasing process by skipping the current patch. |
| 187 | |
| 188 | --abort:: |
| 189 | Abort the rebase operation and reset HEAD to the original |
| 190 | branch. If `<branch>` was provided when the rebase operation was |
| 191 | started, then `HEAD` will be reset to `<branch>`. Otherwise `HEAD` |
| 192 | will be reset to where it was when the rebase operation was |
| 193 | started. |
| 194 | |
| 195 | --quit:: |
| 196 | Abort the rebase operation but `HEAD` is not reset back to the |
| 197 | original branch. The index and working tree are also left |
| 198 | unchanged as a result. If a temporary stash entry was created |
| 199 | using `--autostash`, it will be saved to the stash list. |
| 200 | |
| 201 | --edit-todo:: |
| 202 | Edit the todo list during an interactive rebase. |
| 203 | |
| 204 | --show-current-patch:: |
| 205 | Show the current patch in an interactive rebase or when rebase |
| 206 | is stopped because of conflicts. This is the equivalent of |
| 207 | `git show REBASE_HEAD`. |
| 208 | |
| 209 | OPTIONS |
| 210 | ------- |
| 211 | --onto <newbase>:: |
| 212 | Starting point at which to create the new commits. If the |
| 213 | `--onto` option is not specified, the starting point is |
| 214 | `<upstream>`. May be any valid commit, and not just an |
| 215 | existing branch name. |
| 216 | + |
| 217 | As a special case, you may use "A\...B" as a shortcut for the |
| 218 | merge base of A and B if there is exactly one merge base. You can |
| 219 | leave out at most one of A and B, in which case it defaults to HEAD. |
| 220 | |
| 221 | See TRANSPLANTING A TOPIC BRANCH WITH --ONTO above for examples. |
| 222 | |
| 223 | --keep-base:: |
| 224 | Set the starting point at which to create the new commits to the |
| 225 | merge base of `<upstream>` and `<branch>`. Running |
| 226 | `git rebase --keep-base <upstream> <branch>` is equivalent to |
| 227 | running |
| 228 | `git rebase --reapply-cherry-picks --no-fork-point --onto <upstream>...<branch> <upstream> <branch>`. |
| 229 | + |
| 230 | This option is useful in the case where one is developing a feature on |
| 231 | top of an upstream branch. While the feature is being worked on, the |
| 232 | upstream branch may advance and it may not be the best idea to keep |
| 233 | rebasing on top of the upstream but to keep the base commit as-is. As |
| 234 | the base commit is unchanged this option implies `--reapply-cherry-picks` |
| 235 | to avoid losing commits. |
| 236 | + |
| 237 | Although both this option and `--fork-point` find the merge base between |
| 238 | `<upstream>` and `<branch>`, this option uses the merge base as the _starting |
| 239 | point_ on which new commits will be created, whereas `--fork-point` uses |
| 240 | the merge base to determine the _set of commits_ which will be rebased. |
| 241 | + |
| 242 | See also INCOMPATIBLE OPTIONS below. |
| 243 | |
| 244 | <upstream>:: |
| 245 | Upstream branch to compare against. May be any valid commit, |
| 246 | not just an existing branch name. Defaults to the configured |
| 247 | upstream for the current branch. |
| 248 | |
| 249 | <branch>:: |
| 250 | Working branch; defaults to `HEAD`. |
| 251 | |
| 252 | --apply:: |
| 253 | Use applying strategies to rebase (calling `git-am` |
| 254 | internally). This option may become a no-op in the future |
| 255 | once the merge backend handles everything the apply one does. |
| 256 | + |
| 257 | See also INCOMPATIBLE OPTIONS below. |
| 258 | |
| 259 | --empty=(drop|keep|stop):: |
| 260 | How to handle commits that are not empty to start and are not |
| 261 | clean cherry-picks of any upstream commit, but which become |
| 262 | empty after rebasing (because they contain a subset of already |
| 263 | upstream changes): |
| 264 | + |
| 265 | -- |
| 266 | `drop`;; |
| 267 | The commit will be dropped. This is the default behavior. |
| 268 | `keep`;; |
| 269 | The commit will be kept. This option is implied when `--exec` is |
| 270 | specified unless `-i`/`--interactive` is also specified. |
| 271 | `stop`;; |
| 272 | `ask`;; |
| 273 | The rebase will halt when the commit is applied, allowing you to |
| 274 | choose whether to drop it, edit files more, or just commit the empty |
| 275 | changes. This option is implied when `-i`/`--interactive` is |
| 276 | specified. `ask` is a deprecated synonym of `stop`. |
| 277 | -- |
| 278 | + |
| 279 | Note that commits which start empty are kept (unless `--no-keep-empty` |
| 280 | is specified), and commits which are clean cherry-picks (as determined |
| 281 | by `git log --cherry-mark ...`) are detected and dropped as a |
| 282 | preliminary step (unless `--reapply-cherry-picks` or `--keep-base` is |
| 283 | passed). |
| 284 | + |
| 285 | See also INCOMPATIBLE OPTIONS below. |
| 286 | |
| 287 | --no-keep-empty:: |
| 288 | --keep-empty:: |
| 289 | Do not keep commits that start empty before the rebase |
| 290 | (i.e. that do not change anything from its parent) in the |
| 291 | result. The default is to keep commits which start empty, |
| 292 | since creating such commits requires passing the `--allow-empty` |
| 293 | override flag to `git commit`, signifying that a user is very |
| 294 | intentionally creating such a commit and thus wants to keep |
| 295 | it. |
| 296 | + |
| 297 | Usage of this flag will probably be rare, since you can get rid of |
| 298 | commits that start empty by just firing up an interactive rebase and |
| 299 | removing the lines corresponding to the commits you don't want. This |
| 300 | flag exists as a convenient shortcut, such as for cases where external |
| 301 | tools generate many empty commits and you want them all removed. |
| 302 | + |
| 303 | For commits which do not start empty but become empty after rebasing, |
| 304 | see the `--empty` flag. |
| 305 | + |
| 306 | See also INCOMPATIBLE OPTIONS below. |
| 307 | |
| 308 | --reapply-cherry-picks:: |
| 309 | --no-reapply-cherry-picks:: |
| 310 | Reapply all clean cherry-picks of any upstream commit instead |
| 311 | of preemptively dropping them. (If these commits then become |
| 312 | empty after rebasing, because they contain a subset of already |
| 313 | upstream changes, the behavior towards them is controlled by |
| 314 | the `--empty` flag.) |
| 315 | + |
| 316 | In the absence of `--keep-base` (or if `--no-reapply-cherry-picks` is |
| 317 | given), these commits will be automatically dropped. Because this |
| 318 | necessitates reading all upstream commits, this can be expensive in |
| 319 | repositories with a large number of upstream commits that need to be |
| 320 | read. When using the 'merge' backend, warnings will be issued for each |
| 321 | dropped commit (unless `--quiet` is given). Advice will also be issued |
| 322 | unless `advice.skippedCherryPicks` is set to false (see |
| 323 | linkgit:git-config[1]). |
| 324 | + |
| 325 | `--reapply-cherry-picks` allows rebase to forgo reading all upstream |
| 326 | commits, potentially improving performance. |
| 327 | + |
| 328 | See also INCOMPATIBLE OPTIONS below. |
| 329 | |
| 330 | --allow-empty-message:: |
| 331 | No-op. Rebasing commits with an empty message used to fail |
| 332 | and this option would override that behavior, allowing commits |
| 333 | with empty messages to be rebased. Now commits with an empty |
| 334 | message do not cause rebasing to halt. |
| 335 | + |
| 336 | See also INCOMPATIBLE OPTIONS below. |
| 337 | |
| 338 | -m:: |
| 339 | --merge:: |
| 340 | Using merging strategies to rebase (default). |
| 341 | + |
| 342 | Note that a rebase merge works by replaying each commit from the working |
| 343 | branch on top of the `<upstream>` branch. Because of this, when a merge |
| 344 | conflict happens, the side reported as 'ours' is the so-far rebased |
| 345 | series, starting with `<upstream>`, and 'theirs' is the working branch. |
| 346 | In other words, the sides are swapped. |
| 347 | + |
| 348 | See also INCOMPATIBLE OPTIONS below. |
| 349 | |
| 350 | -s <strategy>:: |
| 351 | --strategy=<strategy>:: |
| 352 | Use the given merge strategy, instead of the default `ort`. |
| 353 | This implies `--merge`. |
| 354 | + |
| 355 | Because `git rebase` replays each commit from the working branch |
| 356 | on top of the `<upstream>` branch using the given strategy, using |
| 357 | the `ours` strategy simply empties all patches from the `<branch>`, |
| 358 | which makes little sense. |
| 359 | + |
| 360 | See also INCOMPATIBLE OPTIONS below. |
| 361 | |
| 362 | -X <strategy-option>:: |
| 363 | --strategy-option=<strategy-option>:: |
| 364 | Pass the <strategy-option> through to the merge strategy. |
| 365 | This implies `--merge` and, if no strategy has been |
| 366 | specified, `-s ort`. Note the reversal of 'ours' and |
| 367 | 'theirs' as noted above for the `-m` option. |
| 368 | + |
| 369 | See also INCOMPATIBLE OPTIONS below. |
| 370 | |
| 371 | include::rerere-options.adoc[] |
| 372 | |
| 373 | -S[<keyid>]:: |
| 374 | --gpg-sign[=<keyid>]:: |
| 375 | --no-gpg-sign:: |
| 376 | GPG-sign commits. The `keyid` argument is optional and |
| 377 | defaults to the committer identity; if specified, it must be |
| 378 | stuck to the option without a space. `--no-gpg-sign` is useful to |
| 379 | countermand both `commit.gpgSign` configuration variable, and |
| 380 | earlier `--gpg-sign`. |
| 381 | |
| 382 | -q:: |
| 383 | --quiet:: |
| 384 | Be quiet. Implies `--no-stat`. |
| 385 | |
| 386 | -v:: |
| 387 | --verbose:: |
| 388 | Be verbose. Implies `--stat`. |
| 389 | |
| 390 | --stat:: |
| 391 | Show a diffstat of what changed upstream since the last rebase. The |
| 392 | diffstat is also controlled by the configuration option rebase.stat. |
| 393 | |
| 394 | -n:: |
| 395 | --no-stat:: |
| 396 | Do not show a diffstat as part of the rebase process. |
| 397 | |
| 398 | --no-verify:: |
| 399 | This option bypasses the pre-rebase hook. See also linkgit:githooks[5]. |
| 400 | |
| 401 | --verify:: |
| 402 | Allows the pre-rebase hook to run, which is the default. This option can |
| 403 | be used to override `--no-verify`. See also linkgit:githooks[5]. |
| 404 | |
| 405 | -C<n>:: |
| 406 | Ensure at least `<n>` lines of surrounding context match before |
| 407 | and after each change. When fewer lines of surrounding |
| 408 | context exist they all must match. By default no context is |
| 409 | ever ignored. Implies `--apply`. |
| 410 | + |
| 411 | See also INCOMPATIBLE OPTIONS below. |
| 412 | |
| 413 | --no-ff:: |
| 414 | --force-rebase:: |
| 415 | -f:: |
| 416 | Individually replay all rebased commits instead of fast-forwarding |
| 417 | over the unchanged ones. This ensures that the entire history of |
| 418 | the rebased branch is composed of new commits. |
| 419 | + |
| 420 | You may find this helpful after reverting a topic branch merge, as this option |
| 421 | recreates the topic branch with fresh commits so it can be remerged |
| 422 | successfully without needing to "revert the reversion" (see the |
| 423 | link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for |
| 424 | details). |
| 425 | |
| 426 | --fork-point:: |
| 427 | --no-fork-point:: |
| 428 | Use reflog to find a better common ancestor between `<upstream>` |
| 429 | and `<branch>` when calculating which commits have been |
| 430 | introduced by `<branch>`. |
| 431 | + |
| 432 | When `--fork-point` is active, 'fork_point' will be used instead of |
| 433 | `<upstream>` to calculate the set of commits to rebase, where |
| 434 | 'fork_point' is the result of `git merge-base --fork-point <upstream> |
| 435 | <branch>` command (see linkgit:git-merge-base[1]). If 'fork_point' |
| 436 | ends up being empty, the `<upstream>` will be used as a fallback. |
| 437 | + |
| 438 | If `<upstream>` or `--keep-base` is given on the command line, then |
| 439 | the default is `--no-fork-point`, otherwise the default is |
| 440 | `--fork-point`. See also `rebase.forkpoint` in linkgit:git-config[1]. |
| 441 | + |
| 442 | If your branch was based on `<upstream>` but `<upstream>` was rewound and |
| 443 | your branch contains commits which were dropped, this option can be used |
| 444 | with `--keep-base` in order to drop those commits from your branch. |
| 445 | + |
| 446 | See also INCOMPATIBLE OPTIONS below. |
| 447 | |
| 448 | --ignore-whitespace:: |
| 449 | Ignore whitespace differences when trying to reconcile |
| 450 | differences. Currently, each backend implements an approximation of |
| 451 | this behavior: |
| 452 | + |
| 453 | apply backend;; |
| 454 | When applying a patch, ignore changes in whitespace in context |
| 455 | lines. Unfortunately, this means that if the "old" lines being |
| 456 | replaced by the patch differ only in whitespace from the existing |
| 457 | file, you will get a merge conflict instead of a successful patch |
| 458 | application. |
| 459 | + |
| 460 | merge backend;; |
| 461 | Treat lines with only whitespace changes as unchanged when merging. |
| 462 | Unfortunately, this means that any patch hunks that were intended |
| 463 | to modify whitespace and nothing else will be dropped, even if the |
| 464 | other side had no changes that conflicted. |
| 465 | |
| 466 | --whitespace=<option>:: |
| 467 | This flag is passed to the `git apply` program |
| 468 | (see linkgit:git-apply[1]) that applies the patch. |
| 469 | Implies `--apply`. |
| 470 | + |
| 471 | See also INCOMPATIBLE OPTIONS below. |
| 472 | |
| 473 | --committer-date-is-author-date:: |
| 474 | Instead of using the current time as the committer date, use |
| 475 | the author date of the commit being rebased as the committer |
| 476 | date. This option implies `--force-rebase`. |
| 477 | + |
| 478 | WARNING: The history walking machinery assumes that commits have |
| 479 | non-decreasing commit timestamps. You should consider if you really need |
| 480 | to use this option. Then you should only use this option to override the |
| 481 | committer date when rebasing commits on top of a base which commit is |
| 482 | older (in terms of the commit date) than the oldest commit you are |
| 483 | applying (in terms of the author date). |
| 484 | |
| 485 | --ignore-date:: |
| 486 | --reset-author-date:: |
| 487 | Instead of using the author date of the original commit, use |
| 488 | the current time as the author date of the rebased commit. This |
| 489 | option implies `--force-rebase`. |
| 490 | + |
| 491 | See also INCOMPATIBLE OPTIONS below. |
| 492 | |
| 493 | --signoff:: |
| 494 | Add a `Signed-off-by` trailer to all the rebased commits. Note |
| 495 | that if `--interactive` is given then only commits marked to be |
| 496 | picked, edited or reworded will have the trailer added. |
| 497 | + |
| 498 | See also INCOMPATIBLE OPTIONS below. |
| 499 | |
| 500 | --trailer=<trailer>:: |
| 501 | Append the given trailer to every rebased commit message, processed |
| 502 | via linkgit:git-interpret-trailers[1]. This option implies |
| 503 | `--force-rebase`. |
| 504 | + |
| 505 | See also INCOMPATIBLE OPTIONS below. |
| 506 | |
| 507 | -i:: |
| 508 | --interactive:: |
| 509 | Make a list of the commits which are about to be rebased. Let the |
| 510 | user edit that list before rebasing. This mode can also be used to |
| 511 | split commits (see SPLITTING COMMITS below). |
| 512 | + |
| 513 | The commit list format can be changed by setting the configuration option |
| 514 | rebase.instructionFormat. A customized instruction format will automatically |
| 515 | have the commit hash prepended to the format. |
| 516 | + |
| 517 | See also INCOMPATIBLE OPTIONS below. |
| 518 | |
| 519 | -r:: |
| 520 | --rebase-merges[=(rebase-cousins|no-rebase-cousins)]:: |
| 521 | --no-rebase-merges:: |
| 522 | By default, a rebase will simply drop merge commits from the todo |
| 523 | list, and put the rebased commits into a single, linear branch. |
| 524 | With `--rebase-merges`, the rebase will instead try to preserve |
| 525 | the branching structure within the commits that are to be rebased, |
| 526 | by recreating the merge commits. Any resolved merge conflicts or |
| 527 | manual amendments in these merge commits will have to be |
| 528 | resolved/re-applied manually. `--no-rebase-merges` can be used to |
| 529 | countermand both the `rebase.rebaseMerges` config option and a previous |
| 530 | `--rebase-merges`. |
| 531 | + |
| 532 | When rebasing merges, there are two modes: `rebase-cousins` and |
| 533 | `no-rebase-cousins`. If the mode is not specified, it defaults to |
| 534 | `no-rebase-cousins`. In `no-rebase-cousins` mode, commits which do not have |
| 535 | `<upstream>` as direct ancestor will keep their original branch point, i.e. |
| 536 | commits that would be excluded by linkgit:git-log[1]'s `--ancestry-path` |
| 537 | option will keep their original ancestry by default. In `rebase-cousins` mode, |
| 538 | such commits are instead rebased onto `<upstream>` (or `<onto>`, if |
| 539 | specified). |
| 540 | + |
| 541 | It is currently only possible to recreate the merge commits using the |
| 542 | `ort` merge strategy; different merge strategies can be used only via |
| 543 | explicit `exec git merge -s <strategy> [...]` commands. |
| 544 | + |
| 545 | See also REBASING MERGES and INCOMPATIBLE OPTIONS below. |
| 546 | |
| 547 | -x <cmd>:: |
| 548 | --exec <cmd>:: |
| 549 | Append "exec <cmd>" after each line creating a commit in the |
| 550 | final history. `<cmd>` will be interpreted as one or more shell |
| 551 | commands. Any command that fails will interrupt the rebase, |
| 552 | with exit code 1. |
| 553 | + |
| 554 | You may execute several commands by either using one instance of `--exec` |
| 555 | with several commands: |
| 556 | + |
| 557 | git rebase -i --exec "cmd1 && cmd2 && ..." |
| 558 | + |
| 559 | or by giving more than one `--exec`: |
| 560 | + |
| 561 | git rebase -i --exec "cmd1" --exec "cmd2" --exec ... |
| 562 | + |
| 563 | If `--autosquash` is used, `exec` lines will not be appended for |
| 564 | the intermediate commits, and will only appear at the end of each |
| 565 | squash/fixup series. |
| 566 | + |
| 567 | This uses the `--interactive` machinery internally, but it can be run |
| 568 | without an explicit `--interactive`. |
| 569 | + |
| 570 | See also INCOMPATIBLE OPTIONS below. |
| 571 | |
| 572 | --root:: |
| 573 | Rebase all commits reachable from `<branch>`, instead of |
| 574 | limiting them with an `<upstream>`. This allows you to rebase |
| 575 | the root commit(s) on a branch. |
| 576 | + |
| 577 | See also INCOMPATIBLE OPTIONS below. |
| 578 | |
| 579 | --autosquash:: |
| 580 | --no-autosquash:: |
| 581 | Automatically squash commits with specially formatted messages into |
| 582 | previous commits being rebased. If a commit message starts with |
| 583 | "squash! ", "fixup! " or "amend! ", the remainder of the title |
| 584 | is taken as a commit specifier, which matches a previous commit if it |
| 585 | matches the title or the hash of that commit. If no commit |
| 586 | matches fully, matches of the specifier with the start of commit |
| 587 | titles are considered. |
| 588 | + |
| 589 | In the rebase todo list, the actions of squash, fixup and amend commits are |
| 590 | changed from `pick` to `squash`, `fixup` or `fixup -C`, respectively, and they |
| 591 | are moved right after the commit they modify. The `--interactive` option can |
| 592 | be used to review and edit the todo list before proceeding. |
| 593 | + |
| 594 | The recommended way to create commits with squash markers is by using the |
| 595 | `--squash`, `--fixup`, `--fixup=amend:` or `--fixup=reword:` options of |
| 596 | linkgit:git-commit[1], which take the target commit as an argument and |
| 597 | automatically fill in the title of the new commit from that. |
| 598 | + |
| 599 | Setting configuration variable `rebase.autoSquash` to true enables |
| 600 | auto-squashing by default for interactive rebase. The `--no-autosquash` |
| 601 | option can be used to override that setting. |
| 602 | + |
| 603 | See also INCOMPATIBLE OPTIONS below. |
| 604 | |
| 605 | --autostash:: |
| 606 | --no-autostash:: |
| 607 | Automatically create a temporary stash entry before the operation |
| 608 | begins, and apply it after the operation ends. This means |
| 609 | that you can run rebase on a dirty worktree. However, use |
| 610 | with care: the final stash application after a successful |
| 611 | rebase might result in non-trivial conflicts. |
| 612 | |
| 613 | --reschedule-failed-exec:: |
| 614 | --no-reschedule-failed-exec:: |
| 615 | Automatically reschedule `exec` commands that failed. This only makes |
| 616 | sense in interactive mode (or when an `--exec` option was provided). |
| 617 | + |
| 618 | This option applies once a rebase is started. It is preserved for the whole |
| 619 | rebase based on, in order, the command line option provided to the initial `git |
| 620 | rebase`, the `rebase.rescheduleFailedExec` configuration (see |
| 621 | linkgit:git-config[1] or "CONFIGURATION" below), or it defaults to false. |
| 622 | + |
| 623 | Recording this option for the whole rebase is a convenience feature. Otherwise |
| 624 | an explicit `--no-reschedule-failed-exec` at the start would be overridden by |
| 625 | the presence of a `rebase.rescheduleFailedExec=true` configuration when `git |
| 626 | rebase --continue` is invoked. Currently, you cannot pass |
| 627 | `--[no-]reschedule-failed-exec` to `git rebase --continue`. |
| 628 | |
| 629 | --update-refs:: |
| 630 | --no-update-refs:: |
| 631 | Automatically force-update any branches that point to commits that |
| 632 | are being rebased. Any branches that are checked out in a worktree |
| 633 | are not updated in this way. |
| 634 | + |
| 635 | If the configuration variable `rebase.updateRefs` is set, then this option |
| 636 | can be used to override and disable this setting. |
| 637 | + |
| 638 | See also INCOMPATIBLE OPTIONS below. |
| 639 | |
| 640 | INCOMPATIBLE OPTIONS |
| 641 | -------------------- |
| 642 | |
| 643 | The following options: |
| 644 | |
| 645 | * --apply |
| 646 | * --whitespace |
| 647 | * -C |
| 648 | |
| 649 | are incompatible with the following options: |
| 650 | |
| 651 | * --merge |
| 652 | * --strategy |
| 653 | * --strategy-option |
| 654 | * --autosquash |
| 655 | * --rebase-merges |
| 656 | * --interactive |
| 657 | * --exec |
| 658 | * --no-keep-empty |
| 659 | * --empty= |
| 660 | * --[no-]reapply-cherry-picks when used without --keep-base |
| 661 | * --update-refs |
| 662 | * --root when used without --onto |
| 663 | * --trailer |
| 664 | |
| 665 | In addition, the following pairs of options are incompatible: |
| 666 | |
| 667 | * --keep-base and --onto |
| 668 | * --keep-base and --root |
| 669 | * --fork-point and --root |
| 670 | |
| 671 | BEHAVIORAL DIFFERENCES |
| 672 | ---------------------- |
| 673 | |
| 674 | `git rebase` has two primary backends: 'apply' and 'merge'. (The 'apply' |
| 675 | backend used to be known as the 'am' backend, but the name led to |
| 676 | confusion as it looks like a verb instead of a noun. Also, the 'merge' |
| 677 | backend used to be known as the interactive backend, but it is now |
| 678 | used for non-interactive cases as well. Both were renamed based on |
| 679 | lower-level functionality that underpinned each.) There are some |
| 680 | subtle differences in how these two backends behave: |
| 681 | |
| 682 | Empty commits |
| 683 | ~~~~~~~~~~~~~ |
| 684 | |
| 685 | The 'apply' backend unfortunately drops intentionally empty commits, i.e. |
| 686 | commits that started empty, though these are rare in practice. It |
| 687 | also drops commits that become empty and has no option for controlling |
| 688 | this behavior. |
| 689 | |
| 690 | The 'merge' backend keeps intentionally empty commits by default (though |
| 691 | with `-i` they are marked as empty in the todo list editor, or they can |
| 692 | be dropped automatically with `--no-keep-empty`). |
| 693 | |
| 694 | Similar to the apply backend, by default the merge backend drops |
| 695 | commits that become empty unless `-i`/`--interactive` is specified (in |
| 696 | which case it stops and asks the user what to do). The merge backend |
| 697 | also has an `--empty=(drop|keep|stop)` option for changing the behavior |
| 698 | of handling commits that become empty. |
| 699 | |
| 700 | Directory rename detection |
| 701 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 702 | |
| 703 | Due to the lack of accurate tree information (arising from |
| 704 | constructing fake ancestors with the limited information available in |
| 705 | patches), directory rename detection is disabled in the 'apply' backend. |
| 706 | Disabled directory rename detection means that if one side of history |
| 707 | renames a directory and the other adds new files to the old directory, |
| 708 | then the new files will be left behind in the old directory without |
| 709 | any warning at the time of rebasing that you may want to move these |
| 710 | files into the new directory. |
| 711 | |
| 712 | Directory rename detection works with the 'merge' backend to provide you |
| 713 | warnings in such cases. |
| 714 | |
| 715 | Context |
| 716 | ~~~~~~~ |
| 717 | |
| 718 | The 'apply' backend works by creating a sequence of patches (by calling |
| 719 | `format-patch` internally), and then applying the patches in sequence |
| 720 | (calling `am` internally). Patches are composed of multiple hunks, |
| 721 | each with line numbers, a context region, and the actual changes. The |
| 722 | line numbers have to be taken with some offset, since the other side |
| 723 | will likely have inserted or deleted lines earlier in the file. The |
| 724 | context region is meant to help find how to adjust the line numbers in |
| 725 | order to apply the changes to the right lines. However, if multiple |
| 726 | areas of the code have the same surrounding lines of context, the |
| 727 | wrong one can be picked. There are real-world cases where this has |
| 728 | caused commits to be reapplied incorrectly with no conflicts reported. |
| 729 | Setting `diff.context` to a larger value may prevent such types of |
| 730 | problems, but increases the chance of spurious conflicts (since it |
| 731 | will require more lines of matching context to apply). |
| 732 | |
| 733 | The 'merge' backend works with a full copy of each relevant file, |
| 734 | insulating it from these types of problems. |
| 735 | |
| 736 | Labelling of conflicts markers |
| 737 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 738 | |
| 739 | When there are content conflicts, the merge machinery tries to |
| 740 | annotate each side's conflict markers with the commits where the |
| 741 | content came from. Since the 'apply' backend drops the original |
| 742 | information about the rebased commits and their parents (and instead |
| 743 | generates new fake commits based off limited information in the |
| 744 | generated patches), those commits cannot be identified; instead it has |
| 745 | to fall back to a commit summary. Also, when `merge.conflictStyle` is |
| 746 | set to `diff3` or `zdiff3`, the 'apply' backend will use "constructed merge |
| 747 | base" to label the content from the merge base, and thus provide no |
| 748 | information about the merge base commit whatsoever. |
| 749 | |
| 750 | The 'merge' backend works with the full commits on both sides of history |
| 751 | and thus has no such limitations. |
| 752 | |
| 753 | Hooks |
| 754 | ~~~~~ |
| 755 | |
| 756 | The 'apply' backend has not traditionally called the post-commit hook, |
| 757 | while the 'merge' backend has. Both have called the post-checkout hook, |
| 758 | though the 'merge' backend has squelched its output. Further, both |
| 759 | backends only call the post-checkout hook with the starting point |
| 760 | commit of the rebase, not the intermediate commits nor the final |
| 761 | commit. In each case, the calling of these hooks was by accident of |
| 762 | implementation rather than by design (both backends were originally |
| 763 | implemented as shell scripts and happened to invoke other commands |
| 764 | like `git checkout` or `git commit` that would call the hooks). Both |
| 765 | backends should have the same behavior, though it is not entirely |
| 766 | clear which, if any, is correct. We will likely make rebase stop |
| 767 | calling either of these hooks in the future. |
| 768 | |
| 769 | Interruptability |
| 770 | ~~~~~~~~~~~~~~~~ |
| 771 | |
| 772 | The 'apply' backend has safety problems with an ill-timed interrupt; if |
| 773 | the user presses Ctrl-C at the wrong time to try to abort the rebase, |
| 774 | the rebase can enter a state where it cannot be aborted with a |
| 775 | subsequent `git rebase --abort`. The 'merge' backend does not appear to |
| 776 | suffer from the same shortcoming. (See |
| 777 | https://lore.kernel.org/git/20200207132152.GC2868@szeder.dev/ for |
| 778 | details.) |
| 779 | |
| 780 | Commit Rewording |
| 781 | ~~~~~~~~~~~~~~~~ |
| 782 | |
| 783 | When a conflict occurs while rebasing, rebase stops and asks the user |
| 784 | to resolve. Since the user may need to make notable changes while |
| 785 | resolving conflicts, after conflicts are resolved and the user has run |
| 786 | `git rebase --continue`, the rebase should open an editor and ask the |
| 787 | user to update the commit message. The 'merge' backend does this, while |
| 788 | the 'apply' backend blindly applies the original commit message. |
| 789 | |
| 790 | Miscellaneous differences |
| 791 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 792 | |
| 793 | There are a few more behavioral differences that most folks would |
| 794 | probably consider inconsequential but which are mentioned for |
| 795 | completeness: |
| 796 | |
| 797 | * Reflog: The two backends will use different wording when describing |
| 798 | the changes made in the reflog, though both will make use of the |
| 799 | word "rebase". |
| 800 | |
| 801 | * Progress, informational, and error messages: The two backends |
| 802 | provide slightly different progress and informational messages. |
| 803 | Also, the apply backend writes error messages (such as "Your files |
| 804 | would be overwritten...") to stdout, while the merge backend writes |
| 805 | them to stderr. |
| 806 | |
| 807 | * State directories: The two backends keep their state in different |
| 808 | directories under `.git/` |
| 809 | |
| 810 | include::merge-strategies.adoc[] |
| 811 | |
| 812 | NOTES |
| 813 | ----- |
| 814 | |
| 815 | You should understand the implications of using `git rebase` on a |
| 816 | repository that you share. See also RECOVERING FROM UPSTREAM REBASE |
| 817 | below. |
| 818 | |
| 819 | When the rebase is run, it will first execute a `pre-rebase` hook if one |
| 820 | exists. You can use this hook to do sanity checks and reject the rebase |
| 821 | if it isn't appropriate. Please see the template `pre-rebase` hook script |
| 822 | for an example. |
| 823 | |
| 824 | Upon completion, `<branch>` will be the current branch. |
| 825 | |
| 826 | INTERACTIVE MODE |
| 827 | ---------------- |
| 828 | |
| 829 | Rebasing interactively means that you have a chance to edit the commits |
| 830 | which are rebased. You can reorder the commits, and you can |
| 831 | remove them (weeding out bad or otherwise unwanted patches). |
| 832 | |
| 833 | The interactive mode is meant for this type of workflow: |
| 834 | |
| 835 | 1. have a wonderful idea |
| 836 | 2. hack on the code |
| 837 | 3. prepare a series for submission |
| 838 | 4. submit |
| 839 | |
| 840 | where point 2. consists of several instances of |
| 841 | |
| 842 | a) regular use |
| 843 | |
| 844 | 1. finish something worthy of a commit |
| 845 | 2. commit |
| 846 | |
| 847 | b) independent fixup |
| 848 | |
| 849 | 1. realize that something does not work |
| 850 | 2. fix that |
| 851 | 3. commit it |
| 852 | |
| 853 | Sometimes the thing fixed in b.2. cannot be amended to the not-quite |
| 854 | perfect commit it fixes, because that commit is buried deeply in a |
| 855 | patch series. That is exactly what interactive rebase is for: use it |
| 856 | after plenty of "a"s and "b"s, by rearranging and editing |
| 857 | commits, and squashing multiple commits into one. |
| 858 | |
| 859 | Start it with the last commit you want to retain as-is: |
| 860 | |
| 861 | git rebase -i <after-this-commit> |
| 862 | |
| 863 | An editor will be fired up with all the commits in your current branch |
| 864 | (ignoring merge commits), which come after the given commit. You can |
| 865 | reorder the commits in this list to your heart's content, and you can |
| 866 | remove them. The list looks more or less like this: |
| 867 | |
| 868 | ------------------------------------------- |
| 869 | pick deadbee The oneline of this commit |
| 870 | pick fa1afe1 The oneline of the next commit |
| 871 | ... |
| 872 | ------------------------------------------- |
| 873 | |
| 874 | The oneline descriptions are purely for your pleasure; 'git rebase' will |
| 875 | not look at them but at the commit names ("deadbee" and "fa1afe1" in this |
| 876 | example), so do not delete or edit the names. |
| 877 | |
| 878 | By replacing the command "pick" with the command "edit", you can tell |
| 879 | `git rebase` to stop after applying that commit, so that you can edit |
| 880 | the files and/or the commit message, amend the commit, and continue |
| 881 | rebasing. |
| 882 | |
| 883 | To interrupt the rebase (just like an "edit" command would do, but without |
| 884 | cherry-picking any commit first), use the "break" command. |
| 885 | |
| 886 | If you just want to edit the commit message for a commit, replace the |
| 887 | command "pick" with the command "reword". |
| 888 | |
| 889 | To drop a commit, replace the command "pick" with "drop", or just |
| 890 | delete the matching line. |
| 891 | |
| 892 | If you want to fold two or more commits into one, replace the command |
| 893 | "pick" for the second and subsequent commits with "squash" or "fixup". |
| 894 | If the commits had different authors, the folded commit will be |
| 895 | attributed to the author of the first commit. The suggested commit |
| 896 | message for the folded commit is the concatenation of the first |
| 897 | commit's message with those identified by "squash" commands, omitting the |
| 898 | messages of commits identified by "fixup" commands, unless "fixup -c" |
| 899 | is used. In that case the suggested commit message is only the message |
| 900 | of the "fixup -c" commit, and an editor is opened allowing you to edit |
| 901 | the message. The contents (patch) of the "fixup -c" commit are still |
| 902 | incorporated into the folded commit. If there is more than one "fixup -c" |
| 903 | commit, the message from the final one is used. You can also use |
| 904 | "fixup -C" to get the same behavior as "fixup -c" except without opening |
| 905 | an editor. |
| 906 | |
| 907 | `git rebase` will stop when "pick" has been replaced with "edit" or |
| 908 | when a command fails due to merge errors. When you are done editing |
| 909 | and/or resolving conflicts you can continue with `git rebase --continue`. |
| 910 | |
| 911 | For example, if you want to reorder the last 5 commits, such that what |
| 912 | was `HEAD~4` becomes the new `HEAD`. To achieve that, you would call |
| 913 | `git rebase` like this: |
| 914 | |
| 915 | ---------------------- |
| 916 | $ git rebase -i HEAD~5 |
| 917 | ---------------------- |
| 918 | |
| 919 | And move the first patch to the end of the list. |
| 920 | |
| 921 | You might want to recreate merge commits, e.g. if you have a history |
| 922 | like this: |
| 923 | |
| 924 | ------------------ |
| 925 | X |
| 926 | \ |
| 927 | A---M---B |
| 928 | / |
| 929 | ---o---O---P---Q |
| 930 | ------------------ |
| 931 | |
| 932 | Suppose you want to rebase the side branch starting at "A" to "Q". Make |
| 933 | sure that the current `HEAD` is "B", and call |
| 934 | |
| 935 | ----------------------------- |
| 936 | $ git rebase -i -r --onto Q O |
| 937 | ----------------------------- |
| 938 | |
| 939 | Reordering and editing commits usually creates untested intermediate |
| 940 | steps. You may want to check that your history editing did not break |
| 941 | anything by running a test, or at least recompiling at intermediate |
| 942 | points in history by using the "exec" command (shortcut "x"). You may |
| 943 | do so by creating a todo list like this one: |
| 944 | |
| 945 | ------------------------------------------- |
| 946 | pick deadbee Implement feature XXX |
| 947 | fixup f1a5c00 Fix to feature XXX |
| 948 | exec make |
| 949 | pick c0ffeee The oneline of the next commit |
| 950 | edit deadbab The oneline of the commit after |
| 951 | exec cd subdir; make test |
| 952 | ... |
| 953 | ------------------------------------------- |
| 954 | |
| 955 | The interactive rebase will stop when a command fails (i.e. exits with |
| 956 | non-0 status) to give you an opportunity to fix the problem. You can |
| 957 | continue with `git rebase --continue`. |
| 958 | |
| 959 | The "exec" command launches the command in a shell (the default one, usually |
| 960 | /bin/sh), so you can use shell features (like "cd", ">", ";" ...). The command |
| 961 | is run from the root of the working tree. |
| 962 | |
| 963 | ---------------------------------- |
| 964 | $ git rebase -i --exec "make test" |
| 965 | ---------------------------------- |
| 966 | |
| 967 | This command lets you check that intermediate commits are compilable. |
| 968 | The todo list becomes like that: |
| 969 | |
| 970 | -------------------- |
| 971 | pick 5928aea one |
| 972 | exec make test |
| 973 | pick 04d0fda two |
| 974 | exec make test |
| 975 | pick ba46169 three |
| 976 | exec make test |
| 977 | pick f4593f9 four |
| 978 | exec make test |
| 979 | -------------------- |
| 980 | |
| 981 | SPLITTING COMMITS |
| 982 | ----------------- |
| 983 | |
| 984 | In interactive mode, you can mark commits with the action "edit". However, |
| 985 | this does not necessarily mean that `git rebase` expects the result of this |
| 986 | edit to be exactly one commit. Indeed, you can undo the commit, or you can |
| 987 | add other commits. This can be used to split a commit into two: |
| 988 | |
| 989 | - Start an interactive rebase with `git rebase -i <commit>^`, where |
| 990 | `<commit>` is the commit you want to split. In fact, any commit range |
| 991 | will do, as long as it contains that commit. |
| 992 | |
| 993 | - Mark the commit you want to split with the action "edit". |
| 994 | |
| 995 | - When it comes to editing that commit, execute `git reset HEAD^`. The |
| 996 | effect is that the `HEAD` is rewound by one, and the index follows suit. |
| 997 | However, the working tree stays the same. |
| 998 | |
| 999 | - Now add the changes to the index that you want to have in the first |
| 1000 | commit. You can use `git add` (possibly interactively) or |
| 1001 | `git gui` (or both) to do that. |
| 1002 | |
| 1003 | - Commit the now-current index with whatever commit message is appropriate |
| 1004 | now. |
| 1005 | |
| 1006 | - Repeat the last two steps until your working tree is clean. |
| 1007 | |
| 1008 | - Continue the rebase with `git rebase --continue`. |
| 1009 | |
| 1010 | If you are not absolutely sure that the intermediate revisions are |
| 1011 | consistent (they compile, pass the testsuite, etc.) you should use |
| 1012 | `git stash` to stash away the not-yet-committed changes |
| 1013 | after each commit, test, and amend the commit if fixes are necessary. |
| 1014 | |
| 1015 | |
| 1016 | RECOVERING FROM UPSTREAM REBASE |
| 1017 | ------------------------------- |
| 1018 | |
| 1019 | Rebasing (or any other form of rewriting) a branch that others have |
| 1020 | based work on is a bad idea: anyone downstream of it is forced to |
| 1021 | manually fix their history. This section explains how to do the fix |
| 1022 | from the downstream's point of view. The real fix, however, would be |
| 1023 | to avoid rebasing the upstream in the first place. |
| 1024 | |
| 1025 | To illustrate, suppose you are in a situation where someone develops a |
| 1026 | 'subsystem' branch, and you are working on a 'topic' that is dependent |
| 1027 | on this 'subsystem'. You might end up with a history like the |
| 1028 | following: |
| 1029 | |
| 1030 | ------------ |
| 1031 | o---o---o---o---o---o---o---o master |
| 1032 | \ |
| 1033 | o---o---o---o---o subsystem |
| 1034 | \ |
| 1035 | *---*---* topic |
| 1036 | ------------ |
| 1037 | |
| 1038 | If 'subsystem' is rebased against 'master', the following happens: |
| 1039 | |
| 1040 | ------------ |
| 1041 | o---o---o---o---o---o---o---o master |
| 1042 | \ \ |
| 1043 | o---o---o---o---o o'--o'--o'--o'--o' subsystem |
| 1044 | \ |
| 1045 | *---*---* topic |
| 1046 | ------------ |
| 1047 | |
| 1048 | If you now continue development as usual, and eventually merge 'topic' |
| 1049 | to 'subsystem', the commits from 'subsystem' will remain duplicated forever: |
| 1050 | |
| 1051 | ------------ |
| 1052 | o---o---o---o---o---o---o---o master |
| 1053 | \ \ |
| 1054 | o---o---o---o---o o'--o'--o'--o'--o'--M subsystem |
| 1055 | \ / |
| 1056 | *---*---*-..........-*--* topic |
| 1057 | ------------ |
| 1058 | |
| 1059 | Such duplicates are generally frowned upon because they clutter up |
| 1060 | history, making it harder to follow. To clean things up, you need to |
| 1061 | transplant the commits on 'topic' to the new 'subsystem' tip, i.e., |
| 1062 | rebase 'topic'. This becomes a ripple effect: anyone downstream from |
| 1063 | 'topic' is forced to rebase too, and so on! |
| 1064 | |
| 1065 | There are two kinds of fixes, discussed in the following subsections: |
| 1066 | |
| 1067 | Easy case: The changes are literally the same.:: |
| 1068 | |
| 1069 | This happens if the 'subsystem' rebase was a simple rebase and |
| 1070 | had no conflicts. |
| 1071 | |
| 1072 | Hard case: The changes are not the same.:: |
| 1073 | |
| 1074 | This happens if the 'subsystem' rebase had conflicts, or used |
| 1075 | `--interactive` to omit, edit, squash, or fixup commits; or |
| 1076 | if the upstream used one of `commit --amend`, `reset`, or |
| 1077 | a full history rewriting command like |
| 1078 | https://github.com/newren/git-filter-repo[`filter-repo`]. |
| 1079 | |
| 1080 | |
| 1081 | The easy case |
| 1082 | ~~~~~~~~~~~~~ |
| 1083 | |
| 1084 | Only works if the changes (patch IDs based on the diff contents) on |
| 1085 | 'subsystem' are literally the same before and after the rebase |
| 1086 | 'subsystem' did. |
| 1087 | |
| 1088 | In that case, the fix is easy because 'git rebase' knows to skip |
| 1089 | changes that are already present in the new upstream (unless |
| 1090 | `--reapply-cherry-picks` is given). So if you say |
| 1091 | (assuming you're on 'topic') |
| 1092 | |
| 1093 | ------------ |
| 1094 | $ git rebase subsystem |
| 1095 | ------------ |
| 1096 | you will end up with the fixed history |
| 1097 | |
| 1098 | ------------ |
| 1099 | o---o---o---o---o---o---o---o master |
| 1100 | \ |
| 1101 | o'--o'--o'--o'--o' subsystem |
| 1102 | \ |
| 1103 | *---*---* topic |
| 1104 | ------------ |
| 1105 | |
| 1106 | |
| 1107 | The hard case |
| 1108 | ~~~~~~~~~~~~~ |
| 1109 | |
| 1110 | Things get more complicated if the 'subsystem' changes do not exactly |
| 1111 | correspond to the ones before the rebase. |
| 1112 | |
| 1113 | NOTE: While an "easy case recovery" sometimes appears to be successful |
| 1114 | even in the hard case, it may have unintended consequences. For |
| 1115 | example, a commit that was removed via `git rebase |
| 1116 | --interactive` will be **resurrected**! |
| 1117 | |
| 1118 | The idea is to manually tell `git rebase` "where the old 'subsystem' |
| 1119 | ended and your 'topic' began", that is, what the old merge base |
| 1120 | between them was. You will have to find a way to name the last commit |
| 1121 | of the old 'subsystem', for example: |
| 1122 | |
| 1123 | * With the 'subsystem' reflog: after `git fetch`, the old tip of |
| 1124 | 'subsystem' is at `subsystem@{1}`. Subsequent fetches will |
| 1125 | increase the number. (See linkgit:git-reflog[1].) |
| 1126 | |
| 1127 | * Relative to the tip of 'topic': knowing that your 'topic' has three |
| 1128 | commits, the old tip of 'subsystem' must be `topic~3`. |
| 1129 | |
| 1130 | You can then transplant the old `subsystem..topic` to the new tip by |
| 1131 | saying (for the reflog case, and assuming you are on 'topic' already): |
| 1132 | |
| 1133 | ------------ |
| 1134 | $ git rebase --onto subsystem subsystem@{1} |
| 1135 | ------------ |
| 1136 | |
| 1137 | The ripple effect of a "hard case" recovery is especially bad: |
| 1138 | 'everyone' downstream from 'topic' will now have to perform a "hard |
| 1139 | case" recovery too! |
| 1140 | |
| 1141 | REBASING MERGES |
| 1142 | --------------- |
| 1143 | |
| 1144 | The interactive rebase command was originally designed to handle |
| 1145 | individual patch series. As such, it makes sense to exclude merge |
| 1146 | commits from the todo list, as the developer may have merged the |
| 1147 | then-current `master` while working on the branch, only to rebase |
| 1148 | all the commits onto `master` eventually (skipping the merge |
| 1149 | commits). |
| 1150 | |
| 1151 | However, there are legitimate reasons why a developer may want to |
| 1152 | recreate merge commits: to keep the branch structure (or "commit |
| 1153 | topology") when working on multiple, inter-related branches. |
| 1154 | |
| 1155 | In the following example, the developer works on a topic branch that |
| 1156 | refactors the way buttons are defined, and on another topic branch |
| 1157 | that uses that refactoring to implement a "Report a bug" button. The |
| 1158 | output of `git log --graph --format=%s -5` may look like this: |
| 1159 | |
| 1160 | ------------ |
| 1161 | * Merge branch 'report-a-bug' |
| 1162 | |\ |
| 1163 | | * Add the feedback button |
| 1164 | * | Merge branch 'refactor-button' |
| 1165 | |\ \ |
| 1166 | | |/ |
| 1167 | | * Use the Button class for all buttons |
| 1168 | | * Extract a generic Button class from the DownloadButton one |
| 1169 | ------------ |
| 1170 | |
| 1171 | The developer might want to rebase those commits to a newer `master` |
| 1172 | while keeping the branch topology, for example when the first topic |
| 1173 | branch is expected to be integrated into `master` much earlier than the |
| 1174 | second one, say, to resolve merge conflicts with changes to the |
| 1175 | DownloadButton class that made it into `master`. |
| 1176 | |
| 1177 | This rebase can be performed using the `--rebase-merges` option. |
| 1178 | It will generate a todo list looking like this: |
| 1179 | |
| 1180 | ------------ |
| 1181 | label onto |
| 1182 | |
| 1183 | # Branch: refactor-button |
| 1184 | reset onto |
| 1185 | pick 123456 Extract a generic Button class from the DownloadButton one |
| 1186 | pick 654321 Use the Button class for all buttons |
| 1187 | label refactor-button |
| 1188 | |
| 1189 | # Branch: report-a-bug |
| 1190 | reset refactor-button # Use the Button class for all buttons |
| 1191 | pick abcdef Add the feedback button |
| 1192 | label report-a-bug |
| 1193 | |
| 1194 | reset onto |
| 1195 | merge -C a1b2c3 refactor-button # Merge 'refactor-button' |
| 1196 | merge -C 6f5e4d report-a-bug # Merge 'report-a-bug' |
| 1197 | ------------ |
| 1198 | |
| 1199 | In contrast to a regular interactive rebase, there are `label`, `reset` |
| 1200 | and `merge` commands in addition to `pick` ones. |
| 1201 | |
| 1202 | The `label` command associates a label with the current HEAD when that |
| 1203 | command is executed. These labels are created as worktree-local refs |
| 1204 | (`refs/rewritten/<label>`) that will be deleted when the rebase |
| 1205 | finishes. That way, rebase operations in multiple worktrees linked to |
| 1206 | the same repository do not interfere with one another. If the `label` |
| 1207 | command fails, it is rescheduled immediately, with a helpful message how |
| 1208 | to proceed. |
| 1209 | |
| 1210 | The `reset` command resets the HEAD, index and worktree to the specified |
| 1211 | revision. It is similar to an `exec git reset --hard <label>`, but |
| 1212 | refuses to overwrite untracked files. If the `reset` command fails, it is |
| 1213 | rescheduled immediately, with a helpful message how to edit the todo list |
| 1214 | (this typically happens when a `reset` command was inserted into the todo |
| 1215 | list manually and contains a typo). |
| 1216 | |
| 1217 | The `merge` command will merge the specified revision(s) into whatever |
| 1218 | is HEAD at that time. With `-C <original-commit>`, the commit message of |
| 1219 | the specified merge commit will be used. When the `-C` is changed to |
| 1220 | a lower-case `-c`, the message will be opened in an editor after a |
| 1221 | successful merge so that the user can edit the message. |
| 1222 | |
| 1223 | If a `merge` command fails for any reason other than merge conflicts (i.e. |
| 1224 | when the merge operation did not even start), it is rescheduled immediately. |
| 1225 | |
| 1226 | By default, the `merge` command will use the `ort` merge strategy for |
| 1227 | regular merges, and `octopus` for octopus merges. One can specify a |
| 1228 | default strategy for all merges using the `--strategy` argument when |
| 1229 | invoking rebase, or can override specific merges in the interactive |
| 1230 | list of commands by using an `exec` command to call `git merge` |
| 1231 | explicitly with a `--strategy` argument. Note that when calling `git |
| 1232 | merge` explicitly like this, you can make use of the fact that the |
| 1233 | labels are worktree-local refs (the ref `refs/rewritten/onto` would |
| 1234 | correspond to the label `onto`, for example) in order to refer to the |
| 1235 | branches you want to merge. |
| 1236 | |
| 1237 | Note: the first command (`label onto`) labels the revision onto which |
| 1238 | the commits are rebased; The name `onto` is just a convention, as a nod |
| 1239 | to the `--onto` option. |
| 1240 | |
| 1241 | It is also possible to introduce completely new merge commits from scratch |
| 1242 | by adding a command of the form `merge <merge-head>`. This form will |
| 1243 | generate a tentative commit message and always open an editor to let the |
| 1244 | user edit it. This can be useful e.g. when a topic branch turns out to |
| 1245 | address more than a single concern and wants to be split into two or |
| 1246 | even more topic branches. Consider this todo list: |
| 1247 | |
| 1248 | ------------ |
| 1249 | pick 192837 Switch from GNU Makefiles to CMake |
| 1250 | pick 5a6c7e Document the switch to CMake |
| 1251 | pick 918273 Fix detection of OpenSSL in CMake |
| 1252 | pick afbecd http: add support for TLS v1.3 |
| 1253 | pick fdbaec Fix detection of cURL in CMake on Windows |
| 1254 | ------------ |
| 1255 | |
| 1256 | The one commit in this list that is not related to CMake may very well |
| 1257 | have been motivated by working on fixing all those bugs introduced by |
| 1258 | switching to CMake, but it addresses a different concern. To split this |
| 1259 | branch into two topic branches, the todo list could be edited like this: |
| 1260 | |
| 1261 | ------------ |
| 1262 | label onto |
| 1263 | |
| 1264 | pick afbecd http: add support for TLS v1.3 |
| 1265 | label tlsv1.3 |
| 1266 | |
| 1267 | reset onto |
| 1268 | pick 192837 Switch from GNU Makefiles to CMake |
| 1269 | pick 918273 Fix detection of OpenSSL in CMake |
| 1270 | pick fdbaec Fix detection of cURL in CMake on Windows |
| 1271 | pick 5a6c7e Document the switch to CMake |
| 1272 | label cmake |
| 1273 | |
| 1274 | reset onto |
| 1275 | merge tlsv1.3 |
| 1276 | merge cmake |
| 1277 | ------------ |
| 1278 | |
| 1279 | CONFIGURATION |
| 1280 | ------------- |
| 1281 | |
| 1282 | include::includes/cmd-config-section-all.adoc[] |
| 1283 | |
| 1284 | include::config/rebase.adoc[] |
| 1285 | include::config/sequencer.adoc[] |
| 1286 | |
| 1287 | GIT |
| 1288 | --- |
| 1289 | Part of the linkgit:git[1] suite |