Rebase — the one people fear

Merge joins two histories and records that the join happened. Rebase rewrites your commits so they appear to have been written on top of the latest main, and the fact that you branched off earlier disappears.

What rebase actually does

git rebase main, run on feature, works in four steps:

1. Find the commits on feature that are not on main: everything after the merge base.
2. Check out the tip of main, with HEAD detached.
3. Re-apply each of those commits, oldest first, as if by git cherry-pick. Each one makes a new commit.
4. Point feature at the last new commit and re-attach HEAD.

A commit's ID is a hash of its contents, and the contents include its parent's ID. A replayed commit has a different parent, so every replayed commit gets a brand-new ID, even if the code change is byte for byte the same. They are copies. The originals still exist, unreferenced, until garbage collection removes them weeks later.

Two details follow from the cherry-pick model. First, rebase skips any commit whose change is already on the new base, by comparing patch IDs (a hash of the diff), so a fix that was cherry-picked to main does not get applied twice. Second, git rebase main is roughly shorthand for git rebase --onto main $(git merge-base main HEAD) HEAD: "take the commits between the merge base and HEAD, and put them on main". Keep that longer form in mind; it explains --onto below.

Interactive rebase: editing history before review

git rebase -i <base> opens a to-do list of every commit after the base, oldest first (the reverse of git log). Each line is an instruction. Change the verb, reorder lines, or delete lines, then save and close; Git executes the list top to bottom.

git rebase -i origin/main

pick 5a90c2e # Add coupon field to cart form
fixup 0c7e1d4 # fixup! Add coupon field to cart form
pick b41f7a3 # Add coupon model
squash 7f2a9b0 # coupon model tests
reword e2c81d0 # Aply coupon before tax
edit 6d3b8c1 # Extract tax helper
drop a4e0f93 # debug logging, remove later
exec npm test

splitting a commit with edit

Stopped at 6d3b8c1...  Extract tax helper
You can amend the commit now, with

  git commit --amend

Once you are satisfied with your changes, run

  git rebase --continue

$ git reset HEAD~
$ git add src/tax.js && git commit -m "Extract tax helper"
$ git add src/cart.js && git commit -m "Use tax helper in cart"
$ git rebase --continue
Successfully rebased and updated refs/heads/feature.

git reset HEAD~ undoes the commit but keeps its changes in your working tree, so you can commit them again in smaller pieces. The finished branch reads as if you knew exactly what you were doing from the start: a few clear commits instead of eleven, each one reviewable and revertable on its own.

Recent versions of Git write the subject after a # as a reminder that only the verb and the ID matter; editing the subject there does not change the commit message. That is what reword is for.

git rebase -x "npm test" origin/main adds an exec line after every commit, so the rebase stops at the first commit that breaks the tests. That is a cheap way to make sure every commit on the branch builds, which keeps git bisect useful later.

--autosquash: fix now, tidy automatically

During review you find a bug in a commit three back. Instead of remembering to fix it up later, make a commit that says which commit it belongs to:

fixup commits

$ git commit --fixup 5a90c2e
[feature 0c7e1d4] fixup! Add coupon field to cart form

$ git commit --squash b41f7a3
$ git commit --fixup=reword:e2c81d0

$ git rebase -i --autosquash origin/main
$ git config --global rebase.autoSquash true

--fixup makes a commit whose subject is fixup! <original subject>. With --autosquash, the to-do list comes up with that commit already moved under its target and marked fixup; you just save. --squash makes a squash! commit that keeps its message for editing, and --fixup=reword: makes an amend! commit that replaces the target's message. With the config set, every interactive rebase does this automatically.

--onto: moving a branch to a different base

The full form is git rebase --onto <newbase> <upstream> <branch>: take the commits in branch that are not in upstream, and replay them on newbase. The classic use is a branch built on top of another branch that has since been squash-merged.

other --onto moves

$ git rebase --onto main feature-a feature-b
$ git rebase --onto release/2.1 main hotfix/login
$ git rebase --onto HEAD~3 HEAD~2
$ git rebase --keep-base main

The second line moves a hotfix you accidentally started from main onto the release branch, without dragging main's new commits along. The third deletes one commit, HEAD~2, from the middle of the branch: replay everything after it onto its parent. --keep-base keeps the branch on its current merge base, which is handy for an interactive clean-up without also pulling in main's new commits.

--update-refs: rebasing a stack of branches

Many teams split large work into stacked pull requests: branch billing-schema, then billing-api on top of it, then billing-ui on top of that. Rebasing the top branch used to leave the lower branches pointing at the old, pre-rebase commits. Since Git 2.38, --update-refs moves every branch that points into the rebased range, and says so when it finishes (Updated the following refs with --update-refs:):

git rebase -i --update-refs main, run on billing-ui

pick 1a2b3c4 # Add billing tables
pick 5d6e7f8 # Add billing migration
update-ref refs/heads/billing-schema

pick 9a0b1c2 # Add invoice endpoint
update-ref refs/heads/billing-api

pick 3d4e5f6 # Add invoice page

Git writes the update-ref lines for you. Edit a commit low in the stack, and after one rebase all three branches point at the right new commits. Set rebase.updateRefs true to make it the default, then push each branch with --force-with-lease.

Conflicts in the middle of a rebase

Because rebase applies commits one at a time, you can hit a conflict on any of them, and you may resolve several in a row.

a rebase that stops

$ git rebase main
Auto-merging src/cart.js
CONFLICT (content): Merge conflict in src/cart.js
error: could not apply e2c81d0... Apply coupon before tax
hint: Resolve all conflicts manually, mark them as resolved with
hint: "git add/rm <conflicted_files>", then run "git rebase --continue".
hint: You can instead skip this commit: run "git rebase --skip".
hint: To abort and get back to the state before "git rebase", run "git rebase --abort".
hint: Disable this message with "git config set advice.mergeConflict false"
Could not apply e2c81d0... # Apply coupon before tax

$ git status
interactive rebase in progress; onto d41c8e2
Last commands done (3 commands done):
   pick b41f7a3 # Add coupon model
   pick e2c81d0 # Apply coupon before tax
  (see more in file .git/rebase-merge/done)
No commands remaining.
You are currently rebasing branch 'feature' on 'd41c8e2'.
  (fix conflicts and then run "git rebase --continue")
  (use "git rebase --skip" to skip this patch)
  (use "git rebase --abort" to check out the original branch)

Unmerged paths:
  (use "git restore --staged <file>..." to unstage)
  (use "git add <file>..." to mark resolution)
	both modified:   src/cart.js

$ git add src/cart.js
$ git rebase --continue

Status says "interactive rebase" even though you typed a plain git rebase. Both run on the same machinery and the same to-do list, and the "Last commands done" lines show which commit you are stopped on.

Two settings make this less painful. rerere.enabled remembers resolutions, so rebasing the same branch again does not ask the same question twice. rebase.autoStash true stashes uncommitted edits before the rebase and restores them after, instead of refusing to start.

ORIG_HEAD and the reflog: undoing a rebase

A finished rebase feels permanent. It is not. Before it starts, rebase records the old tip in ORIG_HEAD, and every step is written to the reflog.

recovering the branch as it was

$ git reflog -6
58b3e6f (HEAD -> feature) HEAD@{0}: rebase (finish): returning to refs/heads/feature
58b3e6f (HEAD -> feature) HEAD@{1}: rebase (pick): Apply coupon before tax
c7d2a51 HEAD@{2}: rebase (pick): Add coupon model
9e4f10b HEAD@{3}: rebase (pick): Add coupon field to cart form
d41c8e2 (main) HEAD@{4}: rebase (start): checkout main
e2c81d0 HEAD@{5}: commit: Apply coupon before tax

$ git reset --hard ORIG_HEAD
$ git reset --hard feature@{1}
$ git reset --hard e2c81d0

$ git range-diff ORIG_HEAD...HEAD

Any of the three resets puts the branch back on the old commits. ORIG_HEAD is quickest but is overwritten by the next reset, merge or rebase. feature@{1} uses the branch's own reflog: "where feature was one move ago", and a whole rebase is a single move for the branch. The raw hash from HEAD@{5} always works. git range-diff compares the old series with the new one commit by commit, which is the best way to check a rebase did what you meant before you force-push it.

Rebase or merge?

Most teams use both: rebase your own branch onto main while you work, clean it up with rebase -i before review, and let the merge button (a merge commit, a squash, or a rebase merge, as the team prefers) land it on main.