Appearance
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 bisectcan 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.
execsteps 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 referencesEach 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
| Operation | Short form | What it does |
|---|---|---|
pick | p | Use the commit as-is. Default action. |
reword | r | Keep the commit content, edit the message. |
edit | e | Stop after the commit so you can amend content or split it. |
squash | s | Combine this commit into the previous one. Merge both messages. |
fixup | f | Combine this commit into the previous one. Discard this message. |
exec | x | Run a shell command. Non-zero exit stops the rebase. |
drop | d | Remove this commit entirely. |
break | b | Stop 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 fixingUse 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.
| Situation | Use | Effect |
|---|---|---|
| Fixup with meaningful message | squash | Opens editor to merge both messages |
| Trivial typo fix | fixup | Discards the fixup message, keeps original |
| "Address review feedback" commit | fixup | Keeps the original commit's message |
| Multiple commits for one feature | squash | Combines into one commit with a combined message |
| WIP commits before opening a PR | fixup | Cleans history without message noise |
bash
# After addressing PR feedback with fixup commits:
git rebase -i --autosquash main
# Git automatically places fixup! commits after their targetsThe 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 --continueSplitting 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 lintThis 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~5This 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 webhookAfter 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-refsIn 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/webhookWithout --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-mergesThe 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 runThe 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 backportPattern 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/mainIf 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 --continueDanger 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 --abortEmpty 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=dropRecovery
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_HEADORIG_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
| Operation | History changes | Safe after push? | Best for |
|---|---|---|---|
| Interactive rebase | Rewrites commits | No | Pre-merge cleanup |
| Merge commit | Adds merge commit | Yes | Integrating shared branches |
| Cherry-pick | Copies commits | Yes | Selective backports |
| Squash merge | Single commit | Yes | Feature completion |
--amend | Rewrites HEAD | No (if pushed) | Last-commit fixes |
Configuration
ini
[rebase]
autoSquash = true
autoStash = true
updateRefs = true
missingCommitsCheck = warn
stat = trueautoSquash = true: Automatically sets fixup/squash lines when runningrebase -iaftercommit --fixup.autoStash = true: Automatically stashes uncommitted changes before rebasing and pops them after.updateRefs = true: Default for--update-refsso 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— Thecommit --fixup/rebase --autosquashworkflow for PR review corrections.docs/devops-workflows/git-rebase-onto.md— Transplanting commits between bases withgit 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.