Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Merging and Rebasing

git rebase command

Reference for git rebase: move a branch onto a new base, use --onto, handle conflicts with --continue, --skip and --abort, and avoid rewriting shared history.

git rebase takes the commits that are on your branch but not on another one, and replays them one by one on top of a new base. The result looks as if you had started your work from the newest commit all along: a straight line instead of a fork and a merge. Each replayed commit has the same message and the same changes but a new parent, so it gets a new id. The old commits stay in the object database (and the reflog) until they are garbage collected.

Because the history changes, the rule of thumb is: rebase your own, unpublished work; do not rebase commits other people already built on. Used well, rebase keeps feature branches tidy and makes history easy to read. The same command also powers interactive rebase for editing a series of commits.

Terminal
git switch feature
git rebase main                      # replay feature on top of main
git rebase --onto main old-base feature
git rebase --continue | --skip | --abort

Try it

Bash Rebase a branch and move a slice with --onto

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Conflicts: continue, skip and abort

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
git rebase [<options>] [<upstream> [<branch>]]
git rebase [<options>] --onto <newbase> <upstream> [<branch>]
git rebase [<options>] --root [--onto <newbase>] [<branch>]
git rebase (--continue | --skip | --abort | --quit | --edit-todo | --show-current-patch)
Name Description
<upstream> Commits reachable from <branch> but not from <upstream> are replayed. The default is the configured upstream of the current branch.
<branch> The branch to rebase. Git switches to it first. Default: the current branch.
--onto <newbase> Where the replayed commits start. Without it, <upstream> is the new base too.
--root Rebase all commits reachable from <branch>, including the very first one.
-i, --interactive Edit the list of commits before replaying. See interactive rebase.
--continue Go on after resolving conflicts and staging the files.
--skip Leave out the current commit and go on.
--abort Stop and return the branch to its state before the rebase.
--quit Stop but keep the current branch and working tree as they are.
--autostash Stash local changes first and re-apply them at the end.
--rebase-merges[=rebase-cousins|no-rebase-cousins] Re-create merge commits instead of flattening them.
--keep-base Rebase onto the merge base of <upstream> and <branch>, so the base stays where it is (handy for squashing without picking up new upstream work).
-X <option>, -s <strategy> Merge strategy options for the replayed commits. In a rebase ours is the new base and theirs is your commit.
--exec <cmd>, -x Run a command after each replayed commit; stop if it fails.
--update-refs Also move other branches that point into the rebased range.
--reapply-cherry-picks Keep commits that duplicate upstream ones (by default they are dropped).
--force-rebase, -f Replay even when a fast-forward would do.
--signoff, --gpg-sign Sign off or sign the replayed commits.

Errors and edge cases: a dirty working tree stops the rebase unless you use --autostash; rebase.autoStash makes that the default. When a conflict happens, the repository is in a "rebase in progress" state until you continue, skip, abort or quit.

Usage notes

  • Never rebase published commits that colleagues have pulled. Their copies still have the old ids, and the next pull creates duplicates and conflicts. If you must, coordinate and use git push --force-with-lease.
  • Rebase versus merge. Merge records that two lines of work joined; rebase pretends they never diverged. Rebase gives a linear log, merge preserves the real timeline. Many teams rebase privately and merge publicly.
  • Ours and theirs are swapped. While replaying, the branch you rebase onto is "ours" (HEAD) and the commit being applied is "theirs". -X theirs therefore favors your own commit.
  • Duplicates are dropped. Commits already present upstream (same patch) are skipped automatically, which is why a rebase after a teammate cherry-picked your work still works.
  • Undo. The branch tip before the rebase is saved as ORIG_HEAD and in the reflog: git reset --hard ORIG_HEAD or git reset --hard feature@{1} recovers it.
  • pull --rebase. git pull --rebase fetches and then rebases your local commits onto the updated upstream. Set pull.rebase true to make it the default.
  • Fork point. If upstream was itself rewritten, plain git rebase upstream can replay old commits too; Git uses the reflog fork point to avoid this (see git merge-base --fork-point).
  • Merge commits are dropped by default and their effects flattened. Use --rebase-merges to keep the topology.
  • rerere helps when you rebase the same branch repeatedly: git rerere.