Git Rebase Onto Vs Interactive

Legacy context

This archive preserves technical notes and editorial material from a software operations context, with a focus on development practices and team culture. The site now serves as an independent educational reference for those studying version control workflows, particularly the distinctions between rebasing onto a branch and interactive rebasing.

The preserved excerpts reference a cloud-based email archiving project and its engineering team, but no current affiliation, product, or service is implied. Content here is offered solely for historical and instructional purposes.

For those exploring `git rebase` options: a standard rebase onto a target branch replays commits linearly, while interactive rebase allows reordering, squashing, or editing commits before applying them. Both alter commit history, so caution is advised when working on shared branches. No proprietary tools, certifications, or guarantees are provided—only general guidance drawn from archived notes.

Git Rebase Onto vs Interactive: A Practical Comparison. When you work with Git on a shared or personal branch, two rebase variants solve different problems: `git rebase --onto` and `git rebase -i` (interactive). Both rewrite commit history, but they operate on different axes. This guide explains what each does, when to choose one over the other, and the mistakes that trip up even experienced developers.

What git rebase --onto Actually Does

`git rebase --onto <new-base> <old-base> <target>` takes the commits that exist between `<old-base>` and `<target>`, and replays them on top of `<new-base>`. The key insight is that `<old-base>` is not necessarily an ancestor of `<new-base>`. You are effectively saying: "Take the patch series from this range, and transplant it elsewhere."

Example scenario: You have a feature branch `feature/X` that was accidentally branched from `main` two weeks ago. Meanwhile, `main` has moved forward with unrelated changes. You want to move only the commits that are unique to `feature/X` onto the current tip of `main`.

git checkout feature/X. git rebase --onto main main~5 feature/X

Here, `main~5` is the old base (the point where `feature/X` diverged). Git finds commits from `main~5` to `feature/X`, excludes any that are already in `main`, and replays them onto the current `main`. The result is a clean feature branch with no merge commits and no unrelated history.

The `--onto` form is also the standard fix for a "lost" branch after an accidental rebase. If you rebased `feature/A` onto `main` but meant to rebase onto `release`, you can use `git reflog` to find the original commit hash, then `git rebase --onto release <old-base> feature/A` to restore the correct base.

What Interactive Rebase Does. `git rebase -i <base>` opens an editor with a list of commits from `<base>` (exclusive) to the current branch tip. You can reorder, squash, fixup, edit, drop, or reword each commit. The base is typically `HEAD~N` or a branch point like `main`.

Interactive rebase is a history-editing tool, not a transplant tool. It changes the content and structure of commits within a single branch. For example, you can squash three noisy commits into one clean commit, or split a large commit into two logical ones.

The critical difference: interactive rebase keeps the same base (unless you explicitly change it with `--onto` inside the rebase todo list). It rewrites the commits themselves. `--onto` keeps the commits as-is but changes where they sit.

Decision Criteria: Which One Do You Need?

Ask yourself two questions before choosing.

Question 1: Is the problem about location or content?

• If the commits are correct but sitting on the wrong parent branch, use `--onto`.
• If the commits have wrong messages, are too granular, or contain debugging artifacts, use interactive.

Question 2: Do you need to preserve the original commit identities?

• `--onto` preserves the patch content but creates new commit hashes because the parent changes. However, the commit messages, authors, and timestamps remain unchanged.
• Interactive rebase also creates new hashes, but you control the metadata. You can reword messages, change authorship, or combine commits.

Practical rule of thumb: Use `--onto` when you know the commit range is correct but the base is wrong. Use interactive when you need to clean up the range itself. In many workflows, you will use both together: first `git rebase -i` to squash and reword, then `git rebase --onto` to move the cleaned branch onto a new base.

Mistake 1: Confusing the old-base argument in `--onto`.. The syntax is `git rebase --onto <new-base> <old-base> <target>`. A frequent error is passing the branch point as the new base. For example, if you want to move `feature/X` from `main~5` to `main`, you must write `git rebase --onto main main~5 feature/X`. Writing `git rebase --onto main~5 main feature/X` will replay the wrong range, often producing an empty branch or a massive conflict.