Skip to content

Git Rebase --onto: Transplant Commits Between Bases ​

git rebase --onto lets you cut a sequence of commits from one point in the graph and replay them onto a different base. The basic git rebase moves your whole branch. --onto moves only the part you choose.

If you've ever wanted to "take these three commits but not those five," or "move that branch onto main without dragging its ancestor branch along," or "cherry-pick a range without the overhead of cherry-pick," --onto is the command.

How it works ​

The three-argument form is the core:

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

It does this:

  1. Check out <branch>.
  2. Collect all commits reachable from <branch> but not from <upstream>.
  3. Replay those commits onto <newbase>.
  4. Point <branch> (and HEAD) at the result.

The <branch> argument is optional. If you omit it, HEAD is used. If you omit <upstream>, it defaults to the upstream tracking branch.

Visual: You have a branch that forked from main at commit X. You want to rebase it onto a different point, Y.

Before:
  A---B---C main
       \
        D---E---F feature

After (git rebase --onto main feature~2 feature):
  A---B---C main
               \
                D'---E' feature

Only D and E moved. F stayed behind (it was part of <upstream>'s ancestry from the cut point).

Five patterns every DevOps engineer needs ​

1. Move a whole branch onto a new base ​

The most common use. Your feature branch was based on an old main. Main has moved on.

git checkout feature-branch
git rebase --onto main feature-branch@{upstream}

This replays only the commits you wrote (the ones not in the upstream tracking branch) onto the current tip of main. It's safer than git rebase main when you don't know exactly where the upstream is.

2. Move only the trailing commits (split a branch) ​

Your branch has 10 commits. You want the first 6 to stay where they are and the last 4 to move onto main.

git rebase --onto main HEAD~4 HEAD

This takes the last 4 commits (the ones reachable from HEAD but not from HEAD~4) and replays them onto main. HEAD ends up pointing at the new tip.

Useful when you realized part of your branch belongs in a different PR, or when the first commits are shared infrastructure and the rest are the actual feature.

3. Cherry-pick a range without cherry-pick ​

git cherry-pick start..end works, but it creates detached commits with the same message. rebase --onto is more faithful: it preserves the original commit message, author, and timestamp, and handles conflicts with the standard rebase machinery (rerere, continue, skip).

git rebase --onto target-branch start-commit end-commit

This takes every commit between start-commit (exclusive) and end-commit (inclusive) and replays them onto target-branch. The difference from cherry-pick: rebase updates committer date and SHA, but the commit message, author, and patch content come through identically. Cherry-pick does the same thing but skips rerere and requires a separate git checkout first.

For a single commit, cherry-pick is simpler. For a range of 3+ commits, --onto is cleaner.

4. Recover from an upstream that rewound ​

Someone force-pushed to the shared branch you were based on. Your branch history is now a fork of a fork. The fork-point detection in git rebase --onto handles this.

git rebase --onto origin/main main

Before this command, main is your local copy of the old upstream. origin/main is the new truth. This replays your local-only commits (the ones reachable from HEAD but not from main) onto the real upstream. The result is a clean branch based on the current origin/main, with none of the commits that the upstream already has.

This pattern is the safe replacement for git rebase origin/main when your local tracking branch is stale.

5. Transplant onto unrelated history ​

--onto works across unrelated histories. You can move commits from one repository's branch to another's, as long as the content applies cleanly.

git rebase --onto unrelated-repo/main --root

This replays every commit from the current branch onto the root of unrelated-repo/main. It's the plumbing equivalent of a full branch transplant. The --root flag tells rebase to start from the first commit.

More practically, use it to extract a subdirectory's history into a new orphan branch:

git checkout --orphan new-root
git rm -rf .
git commit --allow-empty -m "new root"
git checkout -b feature-branch
git rebase --onto new-root main~5

This creates a clean root commit, then transplants the last 5 commits of main onto it. The result is a branch with no connection to the main line of development.

CI/CD automation patterns ​

Backport a range of commits to a release branch ​

When a release branch needs a specific set of fixes but not everything that landed on main:

bash
# From the release branch
git rebase --onto release/v2.3 main~N main~M
# Moves commits N through M from main onto release/v2.3

In a CI pipeline, this is more predictable than cherry-pick because rebase handles the full conflict resolution workflow (marker files, rerere, continue/abort).

Verify a rebase before pushing ​

Combine with git range-diff to validate that a rebase preserved intent:

bash
# Before rebase -- capture the old range
OLD_RANGE=$(git rev-parse feature-branch)

# Perform the transplant
git rebase --onto main feature-branch~5 feature-branch

# Compare old vs new
git range-diff $OLD_RANGE..feature-branch origin/main..feature-branch

A clean range-diff means the transplant was safe. Any changes in the diff are the actual semantic differences introduced by the new base.

Synthetic commits in the right place ​

When CI generates version bumps or changelog commits, --onto can place them precisely without a checkout:

bash
# Create a version bump commit on detached HEAD
echo "2.4.1" > VERSION
git add VERSION
git commit -m "chore(release): bump to 2.4.1"

# Move it onto the release branch without moving anything else
git rebase --onto release/v2.4 HEAD~1 HEAD

Common mistakes ​

Forgetting the upstream argument. git rebase --onto main with no upstream moves the entire current branch (including commits shared with its parent) onto main. The result is often a duplicate of every commit. Always specify where the cut should happen.

Confusing argument order. The syntax is --onto <newbase> <upstream> <branch>, not --onto <branch> <newbase>. Reading it as "onto newbase, cut after upstream, move branch" helps. If the result is wrong, you probably swapped newbase and upstream.

Using --onto where a simple rebase works. If you want to move your whole branch onto main, git rebase main does the same thing as git rebase --onto main $(git merge-base main HEAD). The simpler form is less error-prone. Only use --onto when the simple form doesn't express what you need.

Not understanding the cut semantics. The <upstream> argument is the exclusive boundary. Commits reachable from <upstream> are excluded. Commits not reachable from <upstream> but reachable from <branch> are moved. This is the same logic as git log upstream..branch.

Comparison table ​

TaskSimple rebaserebase --onto
Move whole branch to new basegit rebase maingit rebase --onto main main~10
Move only last N commitsNot possible directlygit rebase --onto main HEAD~N HEAD
Cherry-pick a rangeN/Agit rebase --onto target start end
Recover from rewound upstreamgit rebase origin/main (can duplicate)git rebase --onto origin/main main
Transplant across reposN/Agit rebase --onto other/main --root
Split branch at commit XN/Agit rebase --onto main X feature

See also ​

  • docs/devops-workflows/git-rebase-interactive.md — reword, squash, fixup, exec
  • docs/devops-workflows/git-merge-base.md — ancestor resolution that --onto relies on
  • docs/devops-workflows/git-range-diff.md — verify rebase results
  • docs/devops-workflows/git-cherry-pick.md — alternative for single commits
  • docs/recipes/rebase-onto-quick.md — one-page cheat sheet
  • scripts/rebase-onto-manage.sh — automation script

Git Master — Git Reference for Every Skill Level