`git rebase --onto` Is the Branch Surgery Command You Need When One Topic Branch Contains Two Stories

Why this command matters: a lot of Git pain comes from realizing your branch is based on the wrong place, or that one feature branch secretly contains two unrelated ideas. git rebase --onto is the clean tool for that exact mess.

What git rebase --onto actually does

Most developers learn git rebase as “move my branch on top of another branch.” That is useful, but incomplete. The more powerful form is:

git rebase --onto <newbase> <upstream> <branch>

Git’s own documentation shows the classic example:

git rebase --onto master next topic

That means: take the commits in topic that are not in next, and replay them onto master.

The reason this matters is that Git is not rebasing “the whole branch” in a vague way. It is rebasing a specific commit range. Once you understand that, the command stops feeling magical and starts feeling surgical.

The real-world problem it solves

Here is the mistake many teams make:

1. you branch from feature-a
2. you start working on feature-b
3. later you realize feature-b should have been based on main

Now your branch history contains valid work, but it is attached to the wrong parent line. If you merge as-is, reviewers have to mentally subtract the unrelated base commits. That makes review worse and riskier.

git rebase --onto lets you transplant only the part you actually want.

A concrete example

Suppose your graph looks like this:

1. main has stable commits
2. feature-a adds old experimental work
3. feature-b was created from feature-a, but should really stand on its own

You can move feature-b off feature-a and onto main like this:

git rebase --onto main feature-a feature-b

That says:

1. find commits reachable from feature-b
2. exclude the part already contained in feature-a
3. replay the remaining commits onto main

This is much cleaner than making a new branch and cherry-picking commit by commit unless you truly need manual control over each commit.

Why this is better than panic-cherry-picking

Cherry-pick is fine, but many developers use it as a reflex because they do not trust rebase. The problem is that panic-cherry-picking often creates:

1. duplicated commits
2. missed commits
3. changed order
4. extra cleanup work when conflicts happen

git rebase --onto works better when the underlying problem is “this contiguous set of commits belongs somewhere else.” That is exactly its job.

Where people get confused

The command becomes dangerous when you do not know what <upstream> means in your case. Developers often guess, and guessing in history surgery is how you end up rewriting the wrong slice.

Before using it, inspect the graph:

git log --oneline --graph --decorate --all

That one command is often the difference between a clean history repair and an avoidable cleanup session.

Conflict handling is still normal Git work

git rebase --onto does not remove the need for judgment. If the rebased commits depended on code from the old base, conflicts may be legitimate. That is not Git being hostile. It is Git telling you the old branch relationship mattered more than you thought.

When conflicts appear:

1. resolve them carefully
2. run tests
3. continue with git rebase --continue
4. abort with git rebase --abort if the plan was wrong

The right response is not fear. It is verification.

The highest-value use case

The best use of --onto is not “being clever with Git.” It is making review smaller and more truthful. If one branch accidentally contains two stories, separate them before review instead of asking teammates to decode your accident.

That directly improves:

1. PR clarity
2. rollback safety
3. merge confidence
4. team trust in history

Final recommendation

Learn git rebase --onto before you need it under pressure. It is one of the few Git commands that can turn a messy branch situation into a clean, reviewable history without forcing you into manual cherry-pick theater.

Sources

• Git rebase documentation