rebase

Rebase Branch

Rebase a branch onto its upstream target.

• $ARGUMENTS is a PR number (all digits) → check out the PR branch and rebase onto the PR's base branch.
• $ARGUMENTS is a branch name → rebase current branch onto that target.
• $ARGUMENTS is empty → rebase current branch onto the upstream default branch.

Critical Rules

• Never rebase without a backup. Always create a backup ref before starting.
• Never use --force. Always use --force-with-lease when pushing.
• Never rebase shared branches without explicit user confirmation.
• Don't rewrite history unless asked. The goal is to replay commits onto a new base — not to squash, fixup, or reword. Only offer commit cleanup if the user explicitly requests it.
• Verify the result. Always diff the tree before and after.
• Conflict sides are swapped from merge. During rebase: ours = upstream, theirs = your branch. The opposite of what you expect.

Phase 1: Assess

Step 1: Determine target and current state

If $ARGUMENTS is all digits, treat it as a PR number:

# Fetch PR metadata
gh pr view "$ARGUMENTS" --json headRefName,baseRefName,headRepository,headRepositoryOwner \
  --jq '{head: .headRefName, base: .baseRefName, repo: .headRepository.name, owner: .headRepositoryOwner.login}'

Check out the PR branch locally and capture its tracking remote:

gh pr checkout "$ARGUMENTS"
CURRENT=$(git rev-parse --abbrev-ref HEAD)
TARGET="<baseRefName from above>"
REMOTE=$(git config "branch.$CURRENT.remote" 2>/dev/null || echo origin)

Otherwise, determine target from the argument or defaults:

TARGET="${ARGUMENTS:-$(git rev-parse --abbrev-ref origin/HEAD 2>/dev/null | sed 's|origin/||')}"
DEFAULT_BRANCH="${PRIMARY_BRANCH:-master}"
TARGET="${TARGET:-$DEFAULT_BRANCH}"
CURRENT=$(git rev-parse --abbrev-ref HEAD)
REMOTE="origin"

echo "Rebasing $CURRENT onto $TARGET"
git status --porcelain

If there are uncommitted changes, stop. Ask the user: stash, commit, or abort.