split-branch.md

description
Break up a large branch into smaller stacked PRs using git-spice

Split a large branch into smaller, reviewable stacked PRs using git-spice (gs).

Workflow

Phase 1: Analyze the branch

1. Run gs ll to see current stack position
2. Run git diff main --stat (or appropriate base) to see all changed files
3. Run git log main..HEAD --oneline to understand commit history
4. Group changes into logical chunks for separate PRs:
   • By package (client vs server)
   • By feature/module
   • By dependency order (types first, then implementation)

Present the proposed split to the user with:

• Branch names (prefix with jordan/)
• Which files/directories go in each
• Suggested order (what should be reviewed first)

Phase 2: Create the stack

Important: Always checkout files from the TOP branch (the original large branch being split), not the immediate parent.

For each chunk, starting from the bottom of the stack (first to be reviewed):

1. Run gs ll to identify the top branch (marked with ◀) - this is the source for all checkouts

2. From current position, create child branch:

   gs bc --below --no-commit jordan/<branch-name>

3. Checkout files from the TOP branch (not parent):

   git checkout <top-branch> -- <paths>

4. Stage and commit:

   git add -A
   git commit -m "<message>"

5. Navigate back up to continue:

   gs up

Phase 3: Restack and sync

After creating all child branches:

1. Run gs restack to ensure stack is properly ordered

2. Run gs ll to show the final stack structure

3. Ask user if they want to run gs stack sync to push all branches and create PRs

Key Commands Reference

• gs ll - list stack (◀ marks current branch)
• gs up / gs down - navigate stack
• gs bc --below --no-commit <name> - create branch below current
• gs restack - reorder/fix stack after changes
• gs stack sync - push all branches and create PRs
• gs bsq - squash branch commits

Input Format

You can invoke this command two ways:

1. Auto-analyze mode (no args)

/split-branch

Claude analyzes the diff and proposes a split plan for approval.

2. Explicit split plan

/split-branch
jordan/types-and-schema: packages/schema/
jordan/server-changes: packages/server/
jordan/client-ui: packages/client/src/modules/foo/

Each line: <branch-name>: <paths...> (space or comma separated paths)

Branches listed top-to-bottom = bottom-to-top in stack (first line = first to review).

Args

$ARGUMENTS - Optional split plan. If empty, analyzes current branch and proposes split.