Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Git Interactive Rebase: Squash, Fixup, and --onto Workflows

Rebase replays commits onto a new base; --onto moves only a subset. Autosquash folds fixups without editing the todo list, and force-with-lease makes the result shareable.

~5 min readGit
#Git#Rebase#History#CLI
3D illustration of commit blocks lifted onto a new base line and fused into one cube

Quick Summary

git rebase replays commits onto a new base, producing new commits with new hashes. The normal use is linear history: a feature branch stays on top of main instead of accumulating merge commits. The interactive form (-i) adds a script of instructions — reorder, squash, reword, drop, edit — that turns history into something reviewable before it is shared.

--onto is the part most people never learn and most cleanup requires: it rebases a subset of commits onto a different base, which extracts a branch that was started from the wrong point, or removes a commit from the middle of a chain.

Autosquash ties the workflow together. git commit --fixup=<sha> records intent, and git rebase -i --autosquash folds the fix into the original commit without you reordering anything by hand.

Basic Syntax & Core Signatures

bash
git rebase main # replay current branch onto main git rebase -i HEAD~5 # edit the last five commits git rebase -i --root # include the very first commit git rebase main feature/login # checkout feature/login and rebase it onto main git rebase --onto main old-base feature/x # take feature/x's commits after old-base onto main git rebase --update-refs main # also move branches that point into the rebased range git rebase --continue # after resolving a conflict git rebase --skip # drop the commit that cannot apply git rebase --abort # restore everything git commit --fixup=3f2a1b9 git commit --squash=3f2a1b9 GIT_SEQUENCE_EDITOR=: git rebase -i --autosquash main # accept the todo list as generated git pull --rebase # fetch then rebase instead of merging git config --global rebase.autoStash true git config --global rebase.autoSquash true

The todo list uses these commands, one per line:

CommandShortEffect
pickpKeep the commit as-is
rewordrKeep the commit, edit its message
editeStop to amend the commit, then --continue
squashsFold into the previous commit, combine messages
fixupfFold into the previous commit, discard this message
dropdRemove the commit
breakbStop for a shell in the middle of the list
execxRun a command after the previous commit

Key Comparison Table

CommandRewrites historyNew hashesHandles merge commitsTypical use
git rebase mainYes, current branchYesBy flattening, unless --rebase-mergesKeep a branch current
git rebase -iYes, selected rangeYesNoClean up before review
git rebase --ontoYes, a subsetYesNoExtract or transplant commits
git rebase --rebase-mergesYesYesYes, recreates topologyLong-lived branches with merges
git merge mainNoNoYesPreserve real topology
git cherry-pickNo, copiesNew commits elsewhereWith -mTake one commit across branches
SituationSafe commandReason
Local branch, not pushedgit rebase -i mainNothing depends on those hashes
Pushed feature branch, sologit rebase then --force-with-leaseCollaborators must be told
Shared branch (main, develop)Merge, never rebaseRewriting shared history breaks everyone
Branch started from the wrong basegit rebase --ontoMoves only the intended commits
Need one commit from a branchcherry-pickNo history rewrite of either branch

Practical Edge Cases & Deep Dives

1. --onto to drop commits from the middle

The parameter order is --onto <new-base> <old-base> <branch>: everything reachable from <branch> but not from <old-base> is replayed onto <new-base>. That is how you remove a base commit and everything below it:

bash
# main: A - B - C # feature: A - B - C - D - E (started from a wrong branch that has D) # want: A - B - C - E (drop D) git rebase --onto feature~1 feature~2 feature

Reading it aloud: take feature, find commits after feature~2 (i.e. D, E), skip the ones up to feature~1 (D), and replay E onto feature~1. Getting the arguments backwards silently produces an empty or duplicated branch, so verify with git log --oneline --graph before pushing.

2. Squash while keeping one message

squash concatenates messages, which is usually noise; fixup discards them. The pattern that reads well is a fixup for corrections and a single reword on the first commit of the group:

text
pick 1a2b3c4 feat(api): add retry budget fixup 5d6e7f8 fixup! feat(api): add retry budget fixup 9a0b1c2 fixup! feat(api): add retry budget

With rebase.autoSquash true, the fixup lines are placed automatically and the todo list is accepted with GIT_SEQUENCE_EDITOR=:.

3. Rewriting a branch others have pulled

After a rebase, the remote still has the old commits. A normal push is rejected; a plain --force can delete a colleague's work. --force-with-lease compares the remote ref with your remote-tracking ref and refuses if they differ:

bash
git fetch origin git rebase -i origin/main git push --force-with-lease origin feature/login

There is no way to make this invisible to collaborators. Announce the rewrite, or rebase only branches nobody else has fetched.

4. Conflicts that repeat, and --skip versus --allow-empty

A rebase applies commits one at a time, so the same conflict can appear on several commits. rerere records the resolution and replays it. When a commit becomes empty because its change is already upstream, use git rebase --skip; the commit disappears, which is correct. Using --allow-empty keeps an empty commit that later confuses git log and bisect.

5. Rebase and merges in the range

A plain rebase -i flattens merge commits: the range is linearised and the merge structure is lost, sometimes producing an unexpected set of commits. --rebase-merges recreates the merges from the todo list, which is the only safe option for a branch containing integration merges. It is slower and more conflict-prone, so the common alternative is to rebase only the leaf branch and merge the integration branch separately.

6. --update-refs and stacked branches

A stack of branches where each is based on the previous one normally needs a manual git branch -f after every rebase. --update-refs (Git 2.38+) moves the other refs automatically:

bash
git switch feature/part-3 git rebase --update-refs main # feature/part-1 and feature/part-2 are moved to the new commits

It is conservative: it only updates refs that point into the rebased range, and it does not touch refs on remotes.

Stacked pull requests. A stack of three branches, each reviewed separately, is the most common reason --onto shows up in a real workflow. When the bottom branch changes during review, the two above it must move without dragging the bottom's commits along. The sequence is always the same shape:

bash
git fetch origin git switch part-1 git rebase -i origin/main # address review comments git push --force-with-lease origin part-1 git switch part-2 git rebase --onto part-1 part-1@{1} part-2 git push --force-with-lease origin part-2

part-1@{1} is the old tip of the branch, read from its reflog, so the range is exactly the commits that part-2 added. One habit makes the whole thing cheaper: after every push of a stacked branch, note the pushed hash (the push output prints it), because the reflog entry will be overwritten by the next operation and the old base is the thing every subsequent --onto needs.

Common Git Operation Mistakes

SymptomCauseFix
Duplicate commits after a rebase and mergeBranch rebased and merged into mainPick one policy; revert the duplicates or reset
Push rejected after rebaseHistory rewritten locally--force-with-lease after fetching
Rebase drops a commitdrop left in the todo list by accidentgit reflog, restore the hash
"Cannot rebase: You have unstaged changes"Dirty treeCommit, or enable rebase.autoStash
Conflict resolution lost after --abort--abort restores the pre-rebase stateResolve again; enable rerere
Empty commit stops the rebaseChange already present upstreamgit rebase --skip
--onto produced an empty branchArguments in the wrong ordernew-base old-base branch, verify with --graph
Merge commits vanished from historyPlain -i rebase flattened them--rebase-merges, or rebase only the leaf

Try matching browser tools

All tools

Small utilities that fit Git work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Git guides

More in Git

All Git guides

The guides filed next to this one in Git, in library order.