Clean Git Commit History with Interactive Rebase
Squash, reorder, edit, and split commits with git rebase interactive. Covers pick, squash, fixup, reword, drop, and conflict resolution.
Overview
Interactive rebase lets you rewrite commit history before merging. You can squash related commits, reorder them, fix their messages, split big commits, and drop the ones that shouldn’t ship. The result is a branch history reviewers can actually follow — and git blame stays useful months later. This recipe walks through every interactive rebase action with real examples, including the two things that confuse people most on a first run: the todo list shows commits oldest first, and edit pauses the replay mid-flight rather than at the end.
When to Use
- You’re cleaning up a feature branch before opening or updating a pull request — a tidy history pairs well with a pull request template so reviewers get one clean narrative.
- You’ve got
WIP,fix, ortypocommits that belong inside a larger, meaningful commit. - Only the message is wrong — bad scope, a typo, context that never made it in.
- The commits landed in the wrong order, or one commit packs several changes that should be reviewed separately.
- A commit doesn’t belong in the branch at all — a debug helper or a reverted experiment.
Skip the rebase when the branch is already pushed and teammates have pulled it. Rewriting shared history forces everyone to reconcile their clones, and --force-with-lease only protects the remote, not their local work. Use git revert on public commits or merge normally. For a solo branch with trivial history, squash-merge from the PR UI is usually enough.
Solution
Start an interactive rebase
# Rebase last 5 commits
git rebase -i HEAD~5
# Rebase onto a specific commit — everything after it gets rewritten
git rebase -i <commit-hash>
# Rebase onto a branch (common before merge)
git rebase -i main
The second form saves you from counting commits: pass the hash of the commit just before the ones you want to touch.
Git drops you into an editor showing the todo list:
pick 1a2b3c4 Add user model
pick 5d6e7f8 WIP: fix validation
pick 9a0b1c2 WIP: tests
pick 3d4e5f6 Add user API endpoints
pick 7a8b9c0 Fix typo in endpoint
# Rebase commands:
# pick = use commit as-is
# reword = use commit, edit message
# edit = use commit, pause to amend
# squash = combine with previous commit
# fixup = like squash, discard message
# drop = remove commit
Watch the order here: the list runs oldest commit first, the reverse of git log. The top pick is the first commit Git will replay, so when you squash you’re always merging into the line above. People routinely mark the wrong direction the first time they see this.
Companion files: the git-rebase-interactive-tutorial companion repo has a demo.sh that builds a toy repository with these exact commits, so you can practice every action for real.
Squash commits
pick 1a2b3c4 Add user model
squash 5d6e7f8 WIP: fix validation
squash 9a0b1c2 WIP: tests
pick 3d4e5f6 Add user API endpoints
pick 7a8b9c0 Fix typo in endpoint
After saving, Git opens an editor to combine commit messages:
# This is a combination of 3 commits.
# This is the 1st commit message:
Add user model
# The commit messages of commits being squashed:
WIP: fix validation
WIP: tests
Edit to a single clean message:
Add user model with validation and tests
Fixup — squash and discard message
pick 1a2b3c4 Add user model
fixup 5d6e7f8 WIP: fix validation
fixup 9a0b1c2 WIP: tests
pick 3d4e5f6 Add user API endpoints
Fixup merges the commit into the previous one and throws its message away — no second editor prompt, which makes it the faster option for WIP noise.
Reword a commit message
pick 1a2b3c4 Add user model
reword 3d4e5f6 Add user API endpoints
pick 7a8b9c0 Fix typo in endpoint
Git pauses and opens an editor on that commit’s message. Type the new text, save, and the replay continues.
Edit a commit (pause to modify)
pick 1a2b3c4 Add user model
edit 3d4e5f6 Add user API endpoints
pick 7a8b9c0 Fix typo in endpoint
Git stops at the marked commit with its changes already applied. You can modify files, stage them, and amend in place:
# Make changes
vim src/api/users.py
git add src/api/users.py
# Amend the commit
git commit --amend
# Continue rebase
git rebase --continue
Drop a commit
pick 1a2b3c4 Add user model
drop 5d6e7f8 Add debug logging
pick 3d4e5f6 Add user API endpoints
Removing the line from the list works the same way. If a later commit depended on the dropped change, expect a conflict on the next pick.
Reorder commits
pick 3d4e5f6 Add user API endpoints
pick 1a2b3c4 Add user model
pick 7a8b9c0 Fix typo in endpoint
Git replays them in the new order. Reordering commits that touch the same code can produce conflicts even though each commit applied cleanly in the original order.
Split a commit
edit 1a2b3c4 Add user model and API endpoints
pick 3d4e5f6 Add tests
pick 7a8b9c0 Fix typo
Once Git pauses on the edit line, you’re sitting at that commit with its changes already applied. Unstage them and recommit in pieces:
# Roll back the commit, keep its changes in the working tree
git reset HEAD^
# Stage and commit the first part
git add src/models/user.py
git commit -m "Add user model"
# Stage and commit the second part
git add src/api/users.py
git commit -m "Add user API endpoints"
# Continue rebase — Git replays the remaining picks
git rebase --continue
git reset HEAD^ uses the default mixed mode: it drops the commit but keeps the file contents, which is exactly what splitting needs.
Resolve conflicts during rebase
git rebase -i main
# CONFLICT (content): Merge conflict in src/models/user.py
Resolve the conflict:
# 1. Edit the file to resolve conflicts
vim src/models/user.py
# 2. Stage the resolved file
git add src/models/user.py
# 3. Continue the rebase
git rebase --continue
If you want to abort:
git rebase --abort
If you want to skip the conflicting commit:
git rebase --skip
Autosquash with fixup commits
# Create a fixup commit targeting a specific commit
git commit --fixup 1a2b3c4
# Rebase with autosquash — Git reorders fixups next to their targets
git rebase -i --autosquash HEAD~5
Git 2.32 added two more useful forms for when the fix should also touch the original message:
git commit --fixup=amend:1a2b3c4 # apply the fix and amend the target message
git commit --fixup=reword:1a2b3c4 # same, but opens the editor for confirmation
Git places fixup commits right after their target and marks them automatically:
pick 1a2b3c4 Add user model
fixup 9a0b1c2 fixup! Add user model
pick 3d4e5f6 Add user API endpoints
Force push after rebase
# Safe force push — fails if someone else pushed since your last fetch
git push --force-with-lease origin feature-branch
# Never use plain force push on shared branches
# git push --force # DANGEROUS
Explanation
Interactive rebase replays commits one by one, applying your chosen action to each. Nothing is edited in place — every commit after the first touched one gets a new hash, which is exactly why rebase and shared branches don’t mix.
The available actions:
- pick: keep the commit as-is. The default.
- reword: keep the commit, but open an editor to change the message.
- edit: pause at the commit so you can modify files and
git commit --amend. Thengit rebase --continuepicks the replay back up where it stopped. - squash: merge the commit into the previous one and open an editor to combine both messages.
- fixup: merge into the previous commit but discard the message — no editor prompt.
- drop: remove the commit entirely. Same effect as deleting the line.
- exec: run a shell command at that point in the replay.
- break: halt the rebase at that point;
git rebase --continueresumes.
Key concepts:
- Rebase rewrites history. Old commits are replaced by new ones with different hashes — anyone who pulled the old ones now lives on a diverged branch.
- Never rebase commits already pushed to shared branches. Teammates’ clones will no longer match the remote.
--force-with-leaseis the safe way to push rewritten history: it fails if the remote moved since your last fetch instead of silently overwriting someone else’s work.--autosquashmovesfixup!andsquash!commits next to their targets in the todo list, sogit commit --fixupbecomes your default way to fix forward.- Conflicts appear when commits depend on each other — resolve, stage, continue. If the same conflict keeps coming back at every pick,
git rererecan remember how you resolved it.
Recovery and advanced moves
If a rebase goes sideways, you get two escape hatches. git rebase --abort mid-session returns the branch to its pre-rebase state. After it finished, ORIG_HEAD still points to the old tip, so git reset --hard ORIG_HEAD is the fastest undo — and git reflog records every head movement if you need an older point.
To review what a rebase actually changed — for example before force-pushing over a branch a teammate already saw — git range-diff <old-tip>..<new-tip> compares the two commit series rather than the trees. It surfaces reworded messages, dropped commits, and real code changes in one view.
Two flags worth keeping in your pocket:
git rebase -i --rootrewrites all the way back to the first commit — handy on fresh repos.GIT_SEQUENCE_EDITOR=true git rebase -i HEAD~3accepts the todo list as-is, which is how scripts and aliases run a rebase without opening an editor.
An exec line runs a shell command at that point in the replay. Put one between picks to stop the rebase if an intermediate commit doesn’t build:
pick 1a2b3c4 Add user model
exec npm test
pick 3d4e5f6 Add user API endpoints
exec npm test
Variants
Choosing between squash, fixup and friends mostly comes down to what survives: the change itself, and its message.
| Action | Effect | Use When |
|---|---|---|
| squash | Combine + edit message | Related commits, want one message |
| fixup | Combine + discard message | WIP commits, message not needed |
| reword | Edit message only | Fix typo, improve clarity |
| edit | Pause and modify | Split commit, add forgotten file |
| drop | Remove commit | Revert unwanted change |
| exec | Run shell command | Run tests at specific commit |
exec and break don’t touch commits — they control the replay itself.
Guidelines
- Rebase your feature branch before merging — a linear, squashed history is what makes
git log --onelineandgit bisectactually usable months later. - Reach for
squashwhen the individual messages carry context you’ll want in the final commit; usefixupforWIPandtypocommits whose messages are pure noise. - Force-push with
--force-with-lease, never plain--force: it refuses to overwrite the remote if someone pushed after your last fetch. - Fix forward with
git commit --fixup <sha>plus--autosquashwhile you work, then let the rebase assemble the clean history at the end. - Keep commits small and single-purpose — they’re dramatically easier to reorder, split, and review than big mixed ones.
- Write the squashed message for the reviewer, not for yourself: it should describe the whole change, not the journey.
- Run your test suite after a rebase that touched code. Replayed commits can produce a tree that applies cleanly but behaves differently — at minimum, run the tests covering the files you squashed, dropped, or reordered.
- Only rebase branches you own.
main,develop, and anything teammates have pulled are off-limits —git revertexists for fixing public history. - Keep
git reflogin the back of your mind. It records every head movement for roughly 90 days, so a botched rebase is almost always recoverable.
Common Mistakes
- Rebasing commits that are already on a shared branch — everyone else’s history diverges and they’ll spend an afternoon untangling their clones.
- Using
git push --forcewhere--force-with-leasewould have refused: you can overwrite a teammate’s push without noticing. - Squashing ten commits into one giant “feature” commit — it’s impossible to review and painful to revert. Squash into logical units instead.
- Skipping tests after replaying commits. A squash that applies cleanly can still produce a broken tree when intermediate states conflicted semantically.
- Dropping a commit that later commits depend on — you’ll hit a conflict at every following pick, and the fix is usually
--abortand a fresh todo list. - Editing files during a conflict and then forgetting
git rebase --continue; the rebase sits paused while you keep typing commands into a half-replayed state. - Panicking mid-rebase and closing the terminal.
--abortputs the branch back exactly as it was — there’s no reason to start deleting things. - Forgetting
git reflogexists. When--abortis no longer an option, reflog — orORIG_HEAD— still gets your old tip back.
Further Reading
- git-rebase — official Git documentation
- Using Git rebase on the command line — GitHub Docs
- git commit —fixup reference
- git range-diff — compare two versions of a commit series
- The Git workflow recipe covers the day-to-day branch model these commands slot into, and the Git branching strategy document helps you write your team’s rules down.
Frequently Asked Questions
Is interactive rebase safe?
Yes — on a feature branch only you work on, with --abort and git reflog as a safety net. It becomes unsafe the moment the commits live on a shared branch like main or develop, because everyone else would inherit a diverged history.
What is the difference between squash and fixup?
Both merge a commit into the one above it. Squash opens an editor so you can combine the messages; fixup discards the message entirely and skips the editor. Reach for squash when the message has context worth keeping, fixup for WIP and typo-fix commits.
How do I recover from a bad rebase?
During the session, git rebase --abort restores the pre-rebase state. After it finished, git reset --hard ORIG_HEAD returns to the old tip in one step, and git reflog lists every head movement so nothing is truly lost.
Should I rebase before merging a PR?
Yes — rebasing onto the latest main first gives reviewers a linear history and catches conflicts on your branch instead of inside the merge. Squash the WIP commits, reword unclear messages, and drop dead ends before asking for review.
What is the difference between git rebase and git merge?
git merge joins two branches with a merge commit that keeps both parent histories. git rebase replays your commits on top of the target branch, producing a linear history with no merge commit. Merge for shared branches where preserving context matters; rebase for private feature branches where readability does. The branching strategies guide compares when each model fits a team.
How do I resolve conflicts during an interactive rebase?
When a conflict appears, Git pauses the replay. Fix the markers in the file, git add it, then git rebase --continue. If the commit isn't worth the trouble, git rebase --skip drops it; --abort cancels the whole thing. Resolving one commit at a time keeps conflicts small — a todo list full of squash and reordering is what turns one conflict into five.
Related Resources
Team Git Workflow: Feature Branches, PRs and Clean History
A practical Git workflow for teams: feature branches, pull requests, conventional commits, and how to pick the right branching model.
GuideGit Branching Strategies Compared (GitFlow, GitHub, Trunk)
Trunk-based development, GitFlow, GitHub Flow, and GitLab Flow compared — with a decision framework for team size, release cadence, and CI/CD maturity.
DocGit Branching Strategy Document
A document template for defining Git workflow, branching conventions, merge requirements, and release procedures for engineering teams.
DocPull Request Template
A thorough pull request template to standardize code reviews and improve merge quality.
DocCode Review Checklist Template
A structured checklist template for conducting consistent, thorough code reviews that catch bugs, improve readability, and share knowledge across the team.
RecipeGitHub Actions Workflow Examples: CI/CD, Matrix & Secrets
How to build and deploy with GitHub Actions using workflows, matrices, caching, secrets, environments, and reusable workflows.