Appearance
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:
- Check out
<branch>. - Collect all commits reachable from
<branch>but not from<upstream>. - Replay those commits onto
<newbase>. - 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' featureOnly 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 HEADThis 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-commitThis 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 mainBefore 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 --rootThis 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~5This 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.3In 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-branchA 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 HEADCommon 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
| Task | Simple rebase | rebase --onto |
|---|---|---|
| Move whole branch to new base | git rebase main | git rebase --onto main main~10 |
| Move only last N commits | Not possible directly | git rebase --onto main HEAD~N HEAD |
| Cherry-pick a range | N/A | git rebase --onto target start end |
| Recover from rewound upstream | git rebase origin/main (can duplicate) | git rebase --onto origin/main main |
| Transplant across repos | N/A | git rebase --onto other/main --root |
| Split branch at commit X | N/A | git rebase --onto main X feature |
See also
docs/devops-workflows/git-rebase-interactive.md— reword, squash, fixup, execdocs/devops-workflows/git-merge-base.md— ancestor resolution that--ontorelies ondocs/devops-workflows/git-range-diff.md— verify rebase resultsdocs/devops-workflows/git-cherry-pick.md— alternative for single commitsdocs/recipes/rebase-onto-quick.md— one-page cheat sheetscripts/rebase-onto-manage.sh— automation script