StackPractices
intermediate By Mathias Paulenko

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.

Topics: devops

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, or typo commits 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.

Interactive rebase turns a messy todo list of pick and squash entries into a clean two-commit history.

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. Then git rebase --continue picks 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 --continue resumes.

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-lease is 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.
  • --autosquash moves fixup! and squash! commits next to their targets in the todo list, so git commit --fixup becomes 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 rerere can 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 --root rewrites all the way back to the first commit — handy on fresh repos.
  • GIT_SEQUENCE_EDITOR=true git rebase -i HEAD~3 accepts 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.

ActionEffectUse When
squashCombine + edit messageRelated commits, want one message
fixupCombine + discard messageWIP commits, message not needed
rewordEdit message onlyFix typo, improve clarity
editPause and modifySplit commit, add forgotten file
dropRemove commitRevert unwanted change
execRun shell commandRun 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 --oneline and git bisect actually usable months later.
  • Reach for squash when the individual messages carry context you’ll want in the final commit; use fixup for WIP and typo commits 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 --autosquash while 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 revert exists for fixing public history.
  • Keep git reflog in 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 --force where --force-with-lease would 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 --abort and 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. --abort puts the branch back exactly as it was — there’s no reason to start deleting things.
  • Forgetting git reflog exists. When --abort is no longer an option, reflog — or ORIG_HEAD — still gets your old tip back.

Further Reading

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.