Cascades a rebase through an entire PR stack after a base PR merges or upstream changes. Use when a stack needs to incorporate new base branch commits.
Cascades a rebase through an entire PR stack after a base PR merges or upstream changes. Use when a stack needs to incorporate new base branch commits.
Cascade a rebase through an entire PR stack after a base
PR merges or the upstream base branch changes.
When To Use
Run stack-rebase in any of these situations:
The first PR in the stack merged into master; the
second PR now needs to target master directly
master has moved forward and stack branches need to
incorporate the new commits
A mid-stack PR was revised and descendants need to
pick up the change
When NOT To Use
The stack has never been published (use sanctum:stack-push)
The stack does not exist yet (use sanctum:stack-create)
Prerequisites
All slice branches exist locally (git branch --list)
Remote is up to date (git fetch origin)
Working tree is clean (git status)
Git 2.38+ for --update-refs
Required Progress Tracking
Create TodoWrite items before starting:
stack-rebase:fetch-complete
stack-rebase:trigger-identified
stack-rebase:rebase-complete
stack-rebase:conflicts-resolved
stack-rebase:force-pushed
stack-rebase:prs-updated
Step 1: Fetch Remote State (fetch-complete)
git fetch origin
If the merged PR's branch still exists on remote, note
that GitHub retains the branch after merge.
The merged branch itself is no longer a valid stack base.
Step 2: Identify the Trigger (trigger-identified)
Determine what changed:
Case A, Base PR merged into master:
The slice that was the old "root" is now in master.
All remaining slices need to rebase onto master.
# Confirm the merged branch is now in master
git branch -r --merged origin/master | grep "${MERGED_BRANCH}"
Case B, Master moved forward:
Slices are behind but the stack topology is
unchanged.
Rebase the root slice onto ;
carries all descendants.
master
master
--update-refs
Case C, Mid-stack revision:
A slice was amended.
All descendant slices need to rebase onto it.
Step 3: Run the Cascading Rebase (rebase-complete)
Case A and B: Rebase root slice onto master
STACK=stack/my-feature
BASE=master
# Check out the root slice
ROOT_SLICE=$(git branch --list "${STACK}/*" \
| sed 's/^[* ]*//' | sort | head -1)
git checkout "${ROOT_SLICE}"# Rebase with --update-refs rewrites all stack branches
git rebase --update-refs origin/${BASE}
--update-refs scans the reflog and updates every local
branch ref that points to a commit being rebased.
All slice branches in the stack are rewritten in one pass.
Case C: Rebase from a mid-stack slice
# Check out the first slice BELOW the amended one
CHILD_SLICE=stack/my-feature/add-api # example
git checkout "${CHILD_SLICE}"
git rebase --update-refs stack/my-feature/add-schema
jj Accelerator (if available)
# jj rebases all descendants automatically on any change# To rebase the whole stack onto master:
jj rebase -d master \
-r "ancestors(${STACK}/add-ui) & !ancestors(master)"
Step 4: Resolve Conflicts (conflicts-resolved)
If the rebase pauses with conflicts:
# See which file conflicts
git status
# After resolving each file:
git add <resolved-file>
git rebase --continue
Repeat until the rebase completes.
If a conflict is too complex, abort and investigate:
git rebase --abort
Then examine the diff between the conflicting commits
before retrying.
After a successful rebase, push all slice branches.
Use --force-with-lease to guard against remote changes
made since the last fetch:
for branch in $(git branch --list "${STACK}/*" \
| sed 's/^[* ]*//' | sort); do
git push --force-with-lease origin "${branch}"echo"force-pushed: ${branch}"done
Never use --force (drops the remote-change guard).
jj Accelerator (if available)
jj git push --all --allow-new
Step 6: Update PR Bases (prs-updated)
Case A only: After the root slice merged and you
rebased remaining slices onto master, the next PR in
the stack now targets the wrong base.
Update its base via the GitHub CLI:
NEXT_PR=456 # PR number of the new stack root
gh pr edit "${NEXT_PR}" --base master
For PRs further down the stack, their bases remain the
previous slice branch, which --update-refs already
rewrote; no base edit is needed for them.
Verify the full stack is consistent:
for branch in $(git branch --list "${STACK}/*" \
| sed 's/^[* ]*//' | sort); do
pr_num=$(gh pr list --head"${branch}" \
--json number,baseRefName \
--jq '.[0] | "#\(.number) base=\(.baseRefName)"')
echo"${branch}: ${pr_num}"done
Conflict Prevention Tips
Keep slices small: the smaller each PR, the less surface
area for conflicts during rebase
Rebase frequently: rebasing onto a freshly merged master
once a day is cheaper than resolving a week of drift
Avoid amending commits that are already under review;
prefer a fixup commit and squash at merge time
Notes
git rebase --update-refs requires Git 2.38+; confirm
with git version before running
If --update-refs is unavailable, manually check out
and rebase each slice branch in order from root to tip
After force-pushing, GitHub automatically marks PR
reviews as stale; remind reviewers to re-approve
The stack-push skill documents how to re-post the
stack summary comment after a rebase changes PR SHAs
Exit Criteria
All 6 TodoWrite items (stack-rebase:fetch-complete through
stack-rebase:prs-updated) are created before the rebase starts
and marked complete in order
git fetch origin completes before the rebase trigger is
identified and classified as Case A, B, or C
git rebase --update-refs completes without abort for Cases A
and B; if conflicts occur, each is resolved before continuing
All slice branches force-pushed with --force-with-lease; plain
--force is never used
For Case A only: gh pr edit <next-pr> --base master updates
the new stack root's base target and the full stack topology
verified with gh pr list output
