Interactive Rebase in Git: Reshape Your Commit History

Interactive rebase is an ordinary rebase where you get to edit the instructions first. Git shows you the list of commits it is about to replay; you change the list; Git executes what you wrote.

That is the entire concept. Everything people do with it — squashing, rewording, reordering, splitting, dropping — is a matter of changing lines in a text file.

Before you start

• Lesson 1 — Git Rebase Explained — the replay mechanism and its safety rules.
• Understanding HEAD — the reflog, for recovery.
• A disposable repository. Do not practise on shared branches.

Only reshape commits nobody else has

Interactive rebase rewrites every commit in the range, giving each a new ID. On a branch someone else has pulled or based work on, that orphans their copy.

Reshape before opening a branch for review, or after review concludes — never during, because reviewers’ comments are anchored to commits that will cease to exist.

Starting one

git rebase -i HEAD~4

HEAD~4 names the commit before the range you want to edit — the four commits after it are the ones listed. To include the very first commit in the repository, use --root; HEAD~N where N is the total number of commits refers to the root’s parent, which does not exist:

fatal: invalid upstream 'HEAD~4'

You can also specify a branch, which is usually clearer:

git rebase -i main

That lists every commit on your branch that is not on main — almost always exactly the set you want.

The todo list

Git opens your editor with something like this:

pick de4df70 Add parser
pick 1aff95b fix typo
pick c413def Add validation
pick f195a48 WIP debug output

# Rebase 9fc05fd..f195a48 onto 9fc05fd (4 commands)
#
# Commands:
# p, pick <commit> = use commit
# r, reword <commit> = use commit, but edit the commit message
# e, edit <commit> = use commit, but stop for amending
# s, squash <commit> = use commit, but meld into previous commit
# f, fixup [-C | -c] <commit> = like "squash" but keep only the previous
#                    commit's log message, unless -C is used, in which case
#                    keep only this commit's message; -c is same as -C but
#                    opens the editor
# x, exec <command> = run command (the rest of the line) using shell
# b, break = stop here (continue rebase later with 'git rebase --continue')
# d, drop <commit> = remove commit
# ...
# These lines can be re-ordered; they are executed from top to bottom.

Two things to notice immediately:

Oldest first. This is the opposite of git log. The commit at the top is replayed first.

The lines are instructions. Change the verb at the start of a line to change what happens to that commit. Reorder the lines to reorder the commits. Delete a line to drop that commit entirely.

The commands

Command	Short	Effect
pick	p	Use the commit unchanged
reword	r	Use it, but open an editor for the message
edit	e	Stop after applying it, so you can amend the content
squash	s	Combine into the previous commit; both messages offered for editing
fixup	f	Combine into the previous commit; discard this one’s message
drop	d	Remove the commit
exec	x	Run a shell command at this point
break	b	Stop here; resume with --continue
label / reset / merge	l / t / m	Reconstruct branch topology, used by --rebase-merges
update-ref	u	Move another branch ref to this point, used by --update-refs

Deleting a line does the same thing as drop. Being explicit is safer: an accidentally deleted line is indistinguishable from a deliberate one, and Git will happily discard a commit you meant to keep.

Squash or fixup?

Use squash when both messages contain information worth combining. Use fixup when the second commit is “fix typo” or “address review comment” and its message adds nothing.

In practice fixup is the more common choice, because most commits being folded in are corrections to the commit before them.

A worked cleanup

A branch with four commits, two of which should not survive review:

git log --oneline

f195a48 WIP debug output
c413def Add validation
1aff95b fix typo
de4df70 Add parser
9fc05fd Initial commit

The intent: fold the typo fix into “Add parser”, drop the debug commit, and give the validation commit a better message.

git rebase -i HEAD~4

Edit the list to:

pick de4df70 Add parser
fixup 1aff95b fix typo
reword c413def Add validation
drop f195a48 WIP debug output

Save and close. Git replays, stops to let you reword, and finishes:

Successfully rebased and updated refs/heads/main.

git log --oneline

00039a8 Add input validation
b02ce4b Add parser
9fc05fd Initial commit

Two commits instead of four, both meaningful. The typo fix is folded into the parser commit — verify it is genuinely there rather than lost:

git show HEAD~1:parser.py

p
typo fix

Using edit to change a commit’s content

reword changes a message. edit stops the rebase so you can change the commit itself.

edit b02ce4b Add parser
pick 00039a8 Add input validation

Git applies the commit and then stops:

Stopped at b02ce4b...  Add parser
You can amend the commit now, with

  git commit --amend

Once you are satisfied with your changes, run

  git rebase --continue

git status confirms where you are:

interactive rebase in progress; onto 9fc05fd
Last command done (1 command done):
   edit b02ce4b Add parser
Next command to do (1 remaining command):

Now make changes and fold them in:

echo "more" >> parser.py
git add parser.py
git commit --amend --no-edit
git rebase --continue

Successfully rebased and updated refs/heads/main.

Amending during edit is not the only option

While stopped at an edit, you can do anything: amend, add entirely new commits, or run tests. Adding a commit inserts it into the sequence at that point, which is one way to split work apart.

What you must not do is switch branches or start unrelated operations. Finish or abort the rebase first.

Splitting a commit

A commit that does two unrelated things can be divided. Mark it edit, then undo the commit while keeping its changes:

1. Mark it for editing in the todo list.

2. When Git stops, reset the commit but keep its changes unstaged:

   git reset HEAD^

   A plain reset — no --hard — moves the branch back one commit and leaves the working tree alone. The changes are now uncommitted.

3. Stage and commit the pieces separately:

   git add parser.py
   git commit -m "Add parser"
   git add validate.py
   git commit -m "Add validation"

   git add -p is useful here if the two changes are in the same file.

4. Continue:

   git rebase --continue

Use git reset HEAD^, never git reset --hard HEAD^

git reset HEAD^ moves the branch pointer and keeps your files. git reset --hard HEAD^ moves the pointer and discards the changes, which is exactly the work you were trying to split.

The commit is still recoverable from the reflog if you do this by mistake, but it is a bad two seconds.

Reordering

Reordering is just moving lines. To make the validation commit come first:

pick c413def Add validation
pick de4df70 Add parser

Git replays them in the new order. Whether that works depends on whether the commits are independent — if the validation commit modifies code the parser commit introduces, replaying it first will conflict or fail. Reordering Commits covers dependency handling.

exec: running commands between commits

exec runs a shell command after the commit above it. The rebase stops if the command exits non-zero.

pick de4df70 Add parser
exec npm test
pick c413def Add validation
exec npm test

This is the practical way to verify that every commit on a branch builds — which matters if your team relies on git bisect, or integrates with rebase-and-merge so individual commits land on main.

There is a shortcut that adds an exec after every commit automatically:

git rebase -i --exec "npm test" main

Find the broken commit without editing anything

git rebase --exec "make test" main

No -i needed. Git replays every commit on your branch, running the command after each. It stops at the first commit that fails, leaving you positioned exactly there to fix it.

Autosquash: marking fixups as you go

Deciding which commit a fix belongs to is easier at the time than later. --fixup records the intent in the commit itself.

git commit --fixup=1d51084

This creates a commit whose message is fixup! Add parser — a marker naming its target.

Later, --autosquash reorders the todo list automatically:

git rebase -i --autosquash HEAD~4

pick 1d51084 Add parser
fixup 3b54d21 fixup! Add parser
pick febcef5 Add validation
pick f347f23 Add tests

Git moved the fixup commit next to its target and changed pick to fixup. Save without editing and the history collapses correctly.

Enable it permanently:

git config --global rebase.autoSquash true

git commit --squash=<commit> is the equivalent for squash rather than fixup, keeping both messages.

Autosquash can still conflict

Reordering a fixup next to its target means applying it earlier than it was written. If commits between them touched the same lines, the fixup may no longer apply cleanly.

This is normal, not a failure. Resolve as with any rebase conflict — remembering that “theirs” is your own commit.

Reaching a commit deep in history

git commit --amend only reaches the most recent commit. Interactive rebase reaches any commit, as long as you include it in the range.

To fix the third commit back:

git rebase -i HEAD~3

Mark it edit, make the change, git commit --amend, then --continue. Every commit after it is replayed on top, so they all get new IDs too — a change to one commit necessarily rewrites all its descendants.

Two shortcuts avoid counting commits:

git rebase -i <commit>^        # edit <commit> and everything after it
git rebase -i main             # edit every commit not on main

The first is the useful one when you know which commit is wrong: append ^ to name its parent, which is where the range must start.

Rewriting one commit rewrites everything after it

Because each commit’s ID includes its parent, changing a commit changes every descendant’s ID. Editing a commit ten back in a fifty-commit branch rewrites forty-one commits.

That is fine on a private branch and disruptive on a shared one. It is also why “just fix that old commit” is more expensive than it sounds when others have based work on the branch.

The todo list is a file you can edit mid-rebase

While a rebase is paused, the remaining plan lives in the repository and can be changed:

git rebase --edit-todo

This reopens the editor on the remaining commands. Useful when a conflict reveals that your original plan was wrong — you can drop a commit you now know is redundant, or convert a pick into an edit so you can fix something at that point.

After editing, continue as normal:

git rebase --continue

You can also see where you are without changing anything. During a rebase Git provides two extra refs:

Ref	Names
REBASE_HEAD	The commit currently being applied
ORIG_HEAD	Where your branch pointed before the rebase started

git show REBASE_HEAD          # what am I resolving?
git log --oneline ORIG_HEAD   # what did the branch look like before?

git show REBASE_HEAD is the command to run before considering --skip — it tells you precisely which commit’s work you would be discarding.

Rebasing onto main versus reshaping in place

Two different jobs use the same command, and mixing them makes conflicts harder to reason about.

Reshaping in place — squashing, rewording, reordering — with no change of base:

git rebase -i HEAD~5

The commits replay onto the same parent they already had. Conflicts here are only between your own commits, which is unusual and usually means the reorder was invalid.

Rebasing onto a newer base, optionally with reshaping:

git rebase -i main

Now you are doing both at once: moving onto main’s current tip and editing the plan. Conflicts may come from either source, and telling them apart mid-rebase is harder.

Do them separately when the branch is messy

git rebase -i HEAD~5      # first: clean up the commits
git rebase main           # then: move onto the new base

Two smaller operations, each with one cause of conflict. On a branch with a tangled history this is noticeably less frustrating than doing both at once, and either step can be aborted independently.

When things go wrong

Situation	Command
Cancel the whole rebase	git rebase --abort
Change the remaining plan mid-rebase	git rebase --edit-todo
A commit is now empty	git rebase --skip
Finished, but the result is wrong	git reset --hard <pre-rebase-id>

git rebase --abort restores the branch exactly. It always works while the rebase is in progress.

Once the rebase has finished, the reflog is the way back:

git reflog

eee8f01 HEAD@{0}: rebase (finish): returning to refs/heads/feature
84b5d12 HEAD@{1}: rebase (pick): D: first feature commit
68cbf80 HEAD@{2}: rebase (start): checkout main
a1d07c2 HEAD@{3}: commit: E: second feature commit

HEAD@{3} is the pre-rebase tip:

git reset --hard HEAD@{3}

Take a backup branch first

git branch backup-before-cleanup
git rebase -i main

Recovery becomes git reset --hard backup-before-cleanup, with no reflog reading required. Delete the backup when you are satisfied.

A practical cleanup routine

Before opening a branch for review:

1. See what you have.

   git log --oneline main..HEAD

2. Back it up.

   git branch backup-$(git rev-parse --abbrev-ref HEAD)

3. Reshape.

   git rebase -i main

   Fold fixups into their targets, drop debugging commits, reword anything unclear, and order the commits so they read as a sequence of deliberate steps.

4. Verify every commit builds.

   git rebase --exec "make test" main

5. Check the net change is unaltered.

   git diff backup-feature HEAD

   This should print nothing. Reshaping history must not change the code.

6. Push.

   git push --force-with-lease

7. Delete the backup once review is under way.

Step 5 is the safety check that makes the whole routine trustworthy: an empty diff proves you reorganised the history without altering the outcome.

What makes a good final history

Interactive rebase gives you the ability to reshape a branch. It does not tell you what shape to aim for.

A useful target: each commit should be a change a reviewer could evaluate on its own, and the sequence should read as the order in which someone would sensibly have done the work.

That usually means:

Separate mechanical changes from behavioural ones. A commit that renames a function across forty files is trivially reviewable. The same rename mixed with a logic change is not, because the reviewer has to find the real change among the noise.

Introduce before you use. Add the new helper in one commit, call it in the next. A reviewer reading forwards never encounters something undefined.

Keep refactors reversible. A commit that only moves code should produce no behaviour change, and it is worth saying so in the message so a reviewer knows what to check.

Delete in its own commit. Removing the old implementation after the new one is in place makes the switch obvious and the revert easy.

One reason per commit. If the message needs “and”, consider splitting.

A branch reshaped this way is faster to review, and its commits remain useful years later when someone runs git blame on a line and wants to know why it looks like that.

This is effort, and it is optional

Not every branch justifies careful curation. A two-line fix does not need a narrative. Teams that squash on merge get a clean main without anyone doing this work at all.

Where it pays off: substantial changes, refactors that touch a lot of code, anything a reviewer would otherwise struggle with, and repositories where history is read often. Judge per branch rather than adopting a blanket rule.

Common mistakes

Rebasing a shared branch. The one with the widest impact.

Deleting a line by accident. Deleting drops the commit. Use drop explicitly so intent is visible.

Squashing in the wrong direction. squash and fixup fold into the commit above. A fixup on the first line has nothing to fold into and Git will refuse.

Using git reset --hard HEAD^ when splitting. Discards the changes you were splitting.

Forgetting the range excludes its endpoint. git rebase -i HEAD~3 edits three commits, starting from the one after HEAD~3.

Rewriting during review. Comments lose their anchors.

Not verifying afterwards. Run step 5. An empty diff against your backup is cheap certainty.

Reaching for --skip on a conflict. It drops the commit. Only use it when the change is genuinely already applied.

Mental Model

Interactive rebase is a script Git writes for you and lets you edit.

Git lists the commands it intended to run — pick each commit in order. You rewrite the script: change verbs, reorder lines, delete some. Then Git runs your version instead of its own.

The commits it produces are all new. You are not editing history; you are writing a new history that tells a better story about the same changes.

What You Learned

• Interactive rebase shows the replay plan as an editable todo list, oldest commit first.
• pick, reword, edit, squash, fixup and drop cover almost all real use.
• squash combines messages; fixup discards the second one.
• edit stops so you can amend, add commits, or split one commit into several with git reset HEAD^.
• Reordering is moving lines, and only works when the commits are independent.
• exec runs commands between commits; --exec adds one after every commit.
• --fixup plus --autosquash records fold-in intent at commit time and applies it later.
• --abort cancels; the reflog or a backup branch recovers after completion.

Try It Yourself

Build a messy branch and clean it up. Disposable repository only.

1. Create the repository and four commits, deliberately messy:

   mkdir ~/rebase-lab && cd ~/rebase-lab && git init
   echo "# Demo" > README.md && git add . && git commit -m "Initial commit"
   echo p > parser.py && git add . && git commit -m "Add parser"
   echo "typo fix" >> parser.py && git commit -am "fix typo"
   echo v > validate.py && git add . && git commit -m "Add validation"
   echo debug >> validate.py && git commit -am "WIP debug output"

2. Back it up: git branch backup.

3. Look at the plan without changing anything: git rebase -i HEAD~4, then quit your editor without saving. Confirm git log --oneline is unchanged.

4. Now reshape. Run it again and set the list to:

   pick <id> Add parser
   fixup <id> fix typo
   reword <id> Add validation
   drop <id> WIP debug output

5. Verify the fixup landed: git show HEAD~1:parser.py should contain both lines.

6. Verify nothing else changed. git diff backup HEAD — predict the output before running it.

7. Practise recovery: git reset --hard backup and confirm all four commits return.

8. Try edit: rebase again, mark the first commit edit, add a line, git commit --amend --no-edit, then git rebase --continue.

Step 6 should print nothing. If it does not, the reshape changed the code as well as the history — which is exactly the mistake this check catches.

Next Lesson

Reordering deserves its own treatment, because commit dependencies make it the operation most likely to conflict.

Lesson 3 — Reordering CommitsDependencies, conflicts and verification when changing commit order.

Lesson 4 — Squashing CommitsSquash versus fixup, autosquash, and when granularity is worth keeping.