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.

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
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 trueThe todo list uses these commands, one per line:
| Command | Short | Effect |
|---|---|---|
pick | p | Keep the commit as-is |
reword | r | Keep the commit, edit its message |
edit | e | Stop to amend the commit, then --continue |
squash | s | Fold into the previous commit, combine messages |
fixup | f | Fold into the previous commit, discard this message |
drop | d | Remove the commit |
break | b | Stop for a shell in the middle of the list |
exec | x | Run a command after the previous commit |
Key Comparison Table
| Command | Rewrites history | New hashes | Handles merge commits | Typical use |
|---|---|---|---|---|
git rebase main | Yes, current branch | Yes | By flattening, unless --rebase-merges | Keep a branch current |
git rebase -i | Yes, selected range | Yes | No | Clean up before review |
git rebase --onto | Yes, a subset | Yes | No | Extract or transplant commits |
git rebase --rebase-merges | Yes | Yes | Yes, recreates topology | Long-lived branches with merges |
git merge main | No | No | Yes | Preserve real topology |
git cherry-pick | No, copies | New commits elsewhere | With -m | Take one commit across branches |
| Situation | Safe command | Reason |
|---|---|---|
| Local branch, not pushed | git rebase -i main | Nothing depends on those hashes |
| Pushed feature branch, solo | git rebase then --force-with-lease | Collaborators must be told |
Shared branch (main, develop) | Merge, never rebase | Rewriting shared history breaks everyone |
| Branch started from the wrong base | git rebase --onto | Moves only the intended commits |
| Need one commit from a branch | cherry-pick | No 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:
# 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 featureReading 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:
pick 1a2b3c4 feat(api): add retry budget
fixup 5d6e7f8 fixup! feat(api): add retry budget
fixup 9a0b1c2 fixup! feat(api): add retry budgetWith 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:
git fetch origin
git rebase -i origin/main
git push --force-with-lease origin feature/loginThere 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:
git switch feature/part-3
git rebase --update-refs main
# feature/part-1 and feature/part-2 are moved to the new commitsIt 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:
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-2part-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
| Symptom | Cause | Fix |
|---|---|---|
| Duplicate commits after a rebase and merge | Branch rebased and merged into main | Pick one policy; revert the duplicates or reset |
| Push rejected after rebase | History rewritten locally | --force-with-lease after fetching |
| Rebase drops a commit | drop left in the todo list by accident | git reflog, restore the hash |
| "Cannot rebase: You have unstaged changes" | Dirty tree | Commit, or enable rebase.autoStash |
Conflict resolution lost after --abort | --abort restores the pre-rebase state | Resolve again; enable rerere |
| Empty commit stops the rebase | Change already present upstream | git rebase --skip |
--onto produced an empty branch | Arguments in the wrong order | new-base old-base branch, verify with --graph |
| Merge commits vanished from history | Plain -i rebase flattened them | --rebase-merges, or rebase only the leaf |
Try matching browser tools
All toolsSmall utilities that fit Git work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Git guides
All Git guidesGit config: Aliases, rerere, and Credential Helpers
Five config scopes decide one value at a time. Aliases are user-level shorthand, rerere records conflict resolutions, and credential helpers choose where your secret lives.
Git Hooks: pre-commit, commit-msg, and Husky Automation
Hooks live in .git/hooks, which a clone never receives, so core.hooksPath and Husky are how they travel. Exit codes abort the operation, and every hook is bypassable.
Git bisect: Binary Search, Automated Scripts, and Bug Hunting
Mark one bad and one good commit and Git halves the range each step. bisect run automates it through exit codes, and monotonicity is the assumption that must hold.
Git ignore: Patterns, Negation, and Untracking Cached Files
Patterns are relative and last match wins, but a negation cannot revive a file inside an excluded directory. Ignore rules never touch tracked files: rm --cached first.
More in Git
All Git guidesThe guides filed next to this one in Git, in library order.