Skip to content

Git Interactive Rebase: History Shaping for DevOps ​

git rebase -i rewrites commit history by letting you edit, reorder, squash, split, or drop commits before they reach a shared branch. For a DevOps engineer managing CI pipelines, release branches, and audit trails, it is the tool that turns a messy feature branch into a bisect-safe, reviewable sequence of atomic commits.

This guide covers every interactive rebase operation, the todo list mechanics, CI/CD automation patterns, disaster recovery, and the decisions that separate a clean history from a broken one.

Why a DevOps Engineer Needs Interactive Rebase ​

  • Bisect-safe history. A well-structured commit sequence means git bisect can isolate a regression to a single atomic change, not a 20-commit bucket.
  • Clean PR reviews. Reviewers see logical chunks, not "fix typo" followed by "actually fix the typo" followed by "fix the fix."
  • Release branch backports. Squashing a feature into one commit makes cherry-pick to a release branch trivial.
  • CI exec gates. exec steps inside a rebase let you run linters, tests, or compile checks at each commit in the sequence.
  • Audit compliance. Annotated, atomic commits with meaningful messages satisfy changelog generation and compliance queries.

Core Concept: The Todo List ​

When you run git rebase -i HEAD~5, Git opens an editor with a todo list that looks like this:

pick abc1234 feat: add payment gateway
pick def5678 refactor: extract rate limiter
pick 9ab0cde fix: handle timeout in webhook
pick fedcba9 test: add integration tests for payments
pick 0011223 docs: update API references

Each line is an operation and a commit. You edit this list, save, and Git replays the commits in the order you specify, applying your chosen operations. The rebase stops for conflicts, edit markers, or break commands.

The Seven Operations ​

OperationShort formWhat it does
pickpUse the commit as-is. Default action.
rewordrKeep the commit content, edit the message.
editeStop after the commit so you can amend content or split it.
squashsCombine this commit into the previous one. Merge both messages.
fixupfCombine this commit into the previous one. Discard this message.
execxRun a shell command. Non-zero exit stops the rebase.
dropdRemove this commit entirely.
breakbStop the rebase (useful before or after a batch of edits).

There is no reorder operation. You reorder by moving lines in the todo list.

Reword: Fixing Commit Messages ​

The safest interactive operation. It stops at each marked commit, opens the editor with the existing message, and continues after you save.

bash
# Fix messages on the last 3 commits
git rebase -i HEAD~3
# Change 'pick' to 'reword' (or 'r') on the commits whose messages need fixing

Use reword when:

  • A commit message has a typo.
  • The commit body lacks a rationale or breaking change note.
  • A trailer (Signed-off-by, Change-Id) was missing.

Squash vs Fixup: When to Use Each ​

Both combine a commit into the one above it. The difference is the message.

SituationUseEffect
Fixup with meaningful messagesquashOpens editor to merge both messages
Trivial typo fixfixupDiscards the fixup message, keeps original
"Address review feedback" commitfixupKeeps the original commit's message
Multiple commits for one featuresquashCombines into one commit with a combined message
WIP commits before opening a PRfixupCleans history without message noise
bash
# After addressing PR feedback with fixup commits:
git rebase -i --autosquash main
# Git automatically places fixup! commits after their targets

The dedicated docs/devops-workflows/git-fixup-autosquash.md guide covers the full commit --fixup / rebase --autosquash workflow in detail.

Edit: Amending and Splitting Commits ​

Mark a commit as edit (or e) when you need to change its content, not just its message. Git stops after applying that commit and leaves you in a detached HEAD state.

bash
# In the todo list, change 'pick' to 'edit' on the commit you need to change
git rebase -i HEAD~5
# Git applies commits up to and including the edit target, then stops

# Now make your changes
git add <files>
git commit --amend
# Or split: reset to keep changes in the working tree
git reset HEAD^
git add -p   # stage files in logical chunks
git commit -m "first logical change"
git commit -m "second logical change"

git rebase --continue

Splitting a commit into multiple atomic commits is one of the highest-value rebase skills. A commit titled "add payment module" that touches 15 files across 3 concerns becomes three bisect-friendly commits.

Exec: CI Checks Inside the Rebase ​

exec runs a shell command at any point in the replay. If the command exits non-zero, the rebase stops.

bash
# Run lint at each commit
pick abc1234 feat: add payment gateway
exec npm run lint
pick def5678 refactor: extract rate limiter
exec npm run lint
pick 9ab0cde fix: handle timeout in webhook
exec npm run lint

This pattern catches commits that break lint rules. Each commit must independently pass the check. The same approach works for compilation, unit tests, or type checks.

bash
# Compact exec syntax for every commit
git rebase -i --exec "npm run lint" HEAD~5

This inserts exec npm run lint after every commit in the range. If any commit fails lint, the rebase stops at that point and you fix it before continuing.

Break: Pausing Mid-Rebase ​

break stops the rebase so you can inspect state, run manual tests, or take a snapshot.

bash
# In the todo list:
pick abc1234 feat: add payment gateway
pick def5678 refactor: extract rate limiter
break
pick 9ab0cde fix: handle timeout in webhook

After the first two commits are applied, Git stops. Run git log, build the project, verify behavior. Then git rebase --continue to apply the remaining commits.

Update-Refs: Stacked Branches ​

When you have a chain of branches (feature-A depends on feature-B depends on main), rebasing the bottom branch rewrites history that the top branch depends on. --update-refs tells Git to update any refs (branch names) pointing at commits in the rebase range.

bash
git rebase -i main --update-refs

In the todo list, Git inserts update-ref lines automatically:

pick abc1234 feat: add shared types
pick def5678 feat: payment module (base)
update-ref refs/heads/feature/payment-module
pick 9ab0cde feat: webhook integration
update-ref refs/heads/feature/webhook

Without --update-refs, the stacked branch pointers become stale after the rebase. With it, they track the rewritten commits.

Rebase Merges: Preserving Merge Topology ​

By default, git rebase -i linearizes history, dropping merge commits. --rebase-merges preserves the merge structure.

bash
git rebase -i main --rebase-merges

The todo list includes label, reset, and merge commands that reproduce the original branch topology. Use this when:

  • Your feature branch has merges from other branches that you want to keep.
  • You are rebasing a shared branch and need to preserve its structure.
  • The merge commits carry meaningful context (merge of a dependency branch).

Without --rebase-merges, those merge commits become linear commits and their second-parent context is lost.

Strategy Options ​

Interactive rebase accepts the same strategy options as git merge:

bash
git rebase -i main --strategy-option theirs
git rebase -i main -X theirs   # short form
git rebase -i main --rerere-autoupdate

-X theirs auto-resolves conflicts in favor of the rebased branch. Dangerous but useful for bulk dependency updates where you always want the new upstream. --rerere-autoupdate applies any cached rerere resolutions automatically.

CI/CD Patterns ​

Pattern 1: Pre-Merge History Cleanup ​

Before merging a feature branch, clean up the commit history:

bash
# From the feature branch
git rebase -i main

# In the todo list:
# - Move fixup! commits to land after their targets
# - Squash WIP and "fix review" commits
# - Drop debug commits and temporary logging
# - Exec lint at each commit
# Save and let the rebase run

The result is a linear, bisect-safe sequence of atomic commits.

Pattern 2: Backport Squashing ​

When cherry-picking a feature to a release branch, squash it into one commit first:

bash
git checkout v2.3-release
git rebase -i $(git merge-base v2.3-release feature/new-payment)

# Squash all commits into the first one
# Reword the first commit with a descriptive message
# Save and finish the rebase

git cherry-pick HEAD  # now it's one commit to backport

Pattern 3: CI Gate with Exec ​

Insert exec steps after every commit in a rebase to enforce quality gates:

bash
# In CI or pre-merge hook:
git rebase -i --exec "npm run lint && npm run typecheck" origin/main

If any commit fails, the rebase stops at the failing commit. The developer must fix it before continuing.

Pattern 4: Commit Splitting for Audit ​

Split a large commit into atomic pieces for compliance or review:

bash
# In the todo list, mark the large commit as 'edit'
git rebase -i HEAD~3
# Git stops after the large commit

git reset HEAD^
git add -p service/feature-a.py
git commit -m "feat: add core feature A logic"
git add -p service/feature-b.py
git commit -m "feat: add supporting feature B"
git rebase --continue

Danger Zones ​

Published Branches ​

Rebasing a branch that others have based work on rewrites its history. Every downstream branch needs a force-push recovery. Rule: rebase only branches that exist on your machine. Use merge or revert for shared branches.

Dropped Commits ​

Marking a commit as drop (or deleting its line) removes it from history. If the commit has changes not present elsewhere in the branch, those changes vanish. Recovery is possible from the reflog, but only if you catch it within 90 days (default gc window).

Conflicts During Rebase ​

If a conflict occurs during replay, Git stops at the conflicting commit. Resolve the conflict, git add the resolved files, and git rebase --continue. To abort the entire rebase and return to the original state:

bash
git rebase --abort

Empty Commits After Rebase ​

If a commit's changes are already present in the upstream (because it was cherry-picked or is a duplicate), the rebase produces an empty commit. Git asks if you want to keep it. Answer no (or use --empty=drop):

bash
git rebase -i main --empty=drop

Recovery ​

If a rebase goes wrong, you have three recovery paths:

bash
# 1. Abort and return to the pre-rebase state
git rebase --abort

# 2. After a completed rebase, use the reflog
git reflog
# Find the SHA before the rebase started
git reset --hard HEAD@{5}

# 3. Use ORIG_HEAD (set by rebase before starting)
git reset --hard ORIG_HEAD

ORIG_HEAD is the most reliable recovery. Git sets it to the original HEAD before any rebase, merge, or reset. It stays until the next destructive operation overwrites it.

Comparison Table ​

OperationHistory changesSafe after push?Best for
Interactive rebaseRewrites commitsNoPre-merge cleanup
Merge commitAdds merge commitYesIntegrating shared branches
Cherry-pickCopies commitsYesSelective backports
Squash mergeSingle commitYesFeature completion
--amendRewrites HEADNo (if pushed)Last-commit fixes

Configuration ​

ini
[rebase]
    autoSquash = true
    autoStash = true
    updateRefs = true
    missingCommitsCheck = warn
    stat = true
  • autoSquash = true: Automatically sets fixup/squash lines when running rebase -i after commit --fixup.
  • autoStash = true: Automatically stashes uncommitted changes before rebasing and pops them after.
  • updateRefs = true: Default for --update-refs so stacked branches stay valid.
  • missingCommitsCheck = warn: Warns if commits in the todo list don't exist (because they were already rebased or dropped).
  • stat = true: Show a diffstat at the start of the rebase so you know what changed.

See Also ​

  • docs/devops-workflows/git-fixup-autosquash.md — The commit --fixup / rebase --autosquash workflow for PR review corrections.
  • docs/devops-workflows/git-rebase-onto.md — Transplanting commits between bases with git rebase --onto.
  • docs/devops-workflows/git-range-diff.md — Comparing commit ranges after a rebase to verify nothing was lost.
  • docs/recipes/rebase-interactive-quick.md — One-page cheat sheet.
  • scripts/rebase-interactive-manage.sh — Automation script for interactive rebase operations.
  • git-rebase(1) manual — complete command reference.

Git Master — Git Reference for Every Skill Level