Cleaning Up Branch History with Git Interactive Rebase

Problem: A Messy Feature Branch

When working on a feature, developers often create several small commits: “add helper function”, “fix typo”, “update docs”, etc. When the feature is ready, the branch history looks cluttered, making it hard to review and to merge cleanly into main. The question is: how can we tidy this history without losing work?

Thesis: Use git rebase -i to rewrite a branch’s history locally, then force‑push the cleaned version to the remote.

Interactive rebase lets you reorder, squash, edit, or drop commits. It operates on a local copy, so you can experiment safely before sharing. Once satisfied, a git push --force-with-lease updates the remote branch to reflect the new linear history.

Understanding Interactive Rebase

Running git rebase -i BASE creates a temporary list of commits between BASE and HEAD. The editor opens a todo list that looks like this:

# Rebase 3a1b2c3..HEAD onto 3a1b2c3 (3 commands)
#
# Commands:
#  pick  commit-message  # use this commit
#  reword  commit-message  # edit the commit message
#  edit  commit-message  # pause to amend the commit
#  squash  commit-message  # combine with previous commit
#  fixup  commit-message  # same as squash, but discard message
#  drop  commit-message  # remove the commit
#
# If you remove a line, that commit will be dropped.
# If you change a command, the rebase will do what you say.

pick e3a1b2c Add helper function
pick f4d5e6f Fix typo in docs
pick 7a8b9c0 Update README

Each line represents a commit. You can reorder lines, replace pick with squash or drop, or add edit to pause and modify a commit’s content.

Typical Use Cases

• Squash small work items. Combine a series of incremental commits into a single logical change.
• Reorder commits. Put related changes together for a cleaner history.
• Fix commit messages. Use reword to correct typos or add missing context.
• Drop accidental commits. Remove a commit that was added by mistake.

Practical Example

Assume a feature branch contains three commits on top of main. We want to squash the first two into a single commit.

1. Start the rebase. Run in the feature branch:

   git rebase -i HEAD~3
   

   Permissions: you need write access to the local repository. HEAD~3 refers to the third commit before HEAD.

2. Edit the todo list. Change the second line from pick to squash:

   pick e3a1b2c Add helper function
   squash f4d5e6f Fix typo in docs
   pick 7a8b9c0 Update README
   

   Save and close the editor.

3. Resolve the squash message. Git will open a new editor to combine the two commit messages. Edit as desired, then save.
4. Continue the rebase. If no conflicts arise, Git finishes automatically. If a conflict occurs, Git pauses:

   git status
   # On branch feature
   # You are currently rebasing.
   # Conflict in file.txt
   

   Resolve the conflict, stage the file, then run:

   git rebase --continue
   

   Repeat until the rebase completes.

5. Verify the new history. Run:

   git log --oneline
   

   You should now see two commits: the squashed commit and Update README.

6. Push the updated branch. Because history has changed, force‑push safely:

   git push --force-with-lease origin feature
   

   Checks: --force-with-lease ensures you don’t overwrite a newer remote commit that you haven’t fetched.

Trade‑Offs and Limitations

• History rewriting. After a rebase, commit IDs change. Anyone who has pulled the old branch will have divergent histories, leading to merge conflicts or duplicated work.
• Collaboration risk. Rewriting shared history can break teammates’ local copies. Use rebase only on branches that haven’t been merged into shared branches.
• Complex conflicts. If many commits conflict, the rebase can become tedious. Consider using git merge instead if the branch is large and widely shared.

Best‑Practice Checklist

• Run git fetch and git status before rebasing.
• Only rebase local, unshared branches.
• Test the rebase in a clone to catch surprises.
• Use --force-with-lease and coordinate with teammates.
• Document the rebase in the PR description so reviewers know the history was rewritten.

Actionable Closing

Interactive rebase is a powerful tool for keeping your repository history tidy. By following the workflow above—editing the todo list, resolving conflicts, and force‑pushing with care—you can create clear, logical commit histories that make code reviews and future maintenance easier. Remember: rewrite only what you control, test thoroughly, and communicate with your team before altering shared history.