Appearance
Git Rebase --onto — Quick Reference
Core syntax
bash
# Three-argument form
git rebase --onto <newbase> <upstream> <branch>
# Two-argument (uses HEAD as branch)
git rebase --onto <newbase> <upstream>
# One-argument (uses HEAD and its tracking branch)
git rebase --onto <newbase>The three arguments read as: "take commits from <upstream>..<branch> and replay them onto <newbase>."
Common one-liners
bash
# Move whole branch to current main
git rebase --onto main feature-branch@{upstream}
# Move only the last N commits
git rebase --onto main HEAD~N HEAD
# Cherry-pick a range onto a target branch
git rebase --onto target-branch start-commit end-commit
# Recover from rewound upstream
git rebase --onto origin/main main
# Transplant entire history onto unrelated base
git rebase --onto unrelated-branch --root
# Split a branch: keep first M, move last N to main
git rebase --onto main HEAD~N HEADRange-diff verification
bash
# Before rebase
OLD_TIP=$(git rev-parse HEAD)
# Rebase
git rebase --onto main feature~4
# Verify
git range-diff $OLD_TIP..HEAD origin/main..HEADA clean range-diff means the transplant preserved intent.
CI automation
bash
# Backport commits N through M from main to release branch
git rebase --onto release/v2.3 main~N main~M
# Place a generated commit on a release branch
git add VERSION && git commit -m "chore: bump"
git rebase --onto release/v2.4 HEAD~1 HEADArgument order memory aid
Read --onto A B C as: "replay commits B..C onto A."
- A = new base (where the commits land)
- B = exclusive cut point (what stays behind)
- C = branch to move (defaults to HEAD)
Swapping A and B is the most common mistake.
When to use --onto vs something else
| Need | Use |
|---|---|
| Move whole branch | git rebase main (simpler) |
| Move only trailing commits | git rebase --onto main HEAD~N HEAD |
| Cherry-pick a single commit | git cherry-pick <sha> |
| Cherry-pick 3+ commits | git rebase --onto target start end |
| Rewind to recover from force-push | git rebase --onto origin/main main |
| Move commits to unrelated repo | git rebase --onto other/main --root |
See also
docs/devops-workflows/git-rebase-onto.md— full guidescripts/rebase-onto-manage.sh— automation script