athola/stack-rebase

Stack Rebase

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:

1. stack-rebase:fetch-complete
2. stack-rebase:trigger-identified
3. stack-rebase:rebase-complete
4. stack-rebase:conflicts-resolved
5. stack-rebase:force-pushed
6. 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 master but the stack topology is unchanged. Rebase the root slice onto master; --update-refs carries all descendants.

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.

Step 5: Force-Push Updated Branches (force-pushed)

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