Skip to content

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 HEAD

Range-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..HEAD

A 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 HEAD

Argument 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 ​

NeedUse
Move whole branchgit rebase main (simpler)
Move only trailing commitsgit rebase --onto main HEAD~N HEAD
Cherry-pick a single commitgit cherry-pick <sha>
Cherry-pick 3+ commitsgit rebase --onto target start end
Rewind to recover from force-pushgit rebase --onto origin/main main
Move commits to unrelated repogit rebase --onto other/main --root

See also ​

  • docs/devops-workflows/git-rebase-onto.md — full guide
  • scripts/rebase-onto-manage.sh — automation script

Git Master — Git Reference for Every Skill Level