Managing Stacked PRs with git-spice

This skill helps you work with git-spice for managing stacked pull requests - breaking large features into smaller, reviewable chunks that build on each other.

Core Concepts

Stacking means creating branches that build on top of each other:

main → feature/database → feature/api → feature/ui

Each branch:

• Builds on the one below it
• Can be reviewed and merged independently
• Stays in sync through restacking

Essential Commands

Creating Stacks

gs bc <branch-name>    # Branch Create - stack new branch on current
gs log short           # View stack structure

Submitting PRs

gs ss                  # Stack Submit - submit all branches as PRs
gs uss                 # Upstack Submit - submit current + above
gs dss                 # Downstack Submit - submit current + below
gs bs                  # Branch Submit - submit only current branch

Keeping in Sync

gs rs                  # Repo Sync - update trunk, clean merged branches
gs sr                  # Stack Restack - rebase all branches
gs upstack restack     # Rebase current branch + above

Quick Workflows

Starting a New Stack

1. Sync with trunk:

   gs rs

2. Create first branch:

   gs bc feature/part-1

3. Make changes, commit normally with git
4. Stack next branch:

   gs bc feature/part-2

5. Repeat for each layer
6. View structure:

   gs log short

7. Submit all:

   gs ss

Handling Review Feedback

1. Checkout the branch:

   git checkout <branch-name>

2. Make changes, commit
3. Restack branches above:

   gs upstack restack

4. Push changes:

   git push --force-with-lease

5. Update upstack PRs:

   gs upstack submit

After Merges

1. Sync:

   gs rs

   (updates trunk, removes merged branches)
2. Restack remaining:

   gs sr

3. Update PRs:

   gs ss

Key Principles

✅ Always use git-spice for rebasing - Never use

git rebase

directly on stacked branches

✅ Sync regularly - Run

gs rs

to stay up-to-date with trunk

✅ Restack after changes - Any change to a lower branch needs

gs upstack restack

✅ Commit with git, manage stack with git-spice - Use normal git for commits, git-spice for stack operations

✅ Test each layer - Each branch should work independently

Common Patterns

Check current state

gs log short                    # See stack structure
git status                      # Check for uncommitted changes
gh pr list --author @me        # View your PRs

Submit for review with GitHub CLI

gs ss                          # Create/update PRs
gh pr view <pr-number>         # View a specific PR
gh pr edit <pr-number> --add-label "stack"

Handle conflicts during restack

# git-spice will pause, showing conflicts
# Fix conflicts in your editor
git add <resolved-files>
git rebase --continue
# Or abort: git rebase --abort

Detailed Workflows

For step-by-step guides:

• Creating stacks → See workflows/creating-stacks.md
• Submitting and updating → See workflows/handling-changes.md

For complete command reference → See reference/commands.md

Integration with GitHub

git-spice works with GitHub CLI (

gh

):

• PRs include navigation comments showing stack relationships
• Use

  gh pr

  commands alongside git-spice
• Edit PR titles/descriptions with

  gh pr edit

Tips

💡 Use shorthands:

gs bc

,

gs ss

,

gs sr

instead of full commands

💡 Run

gs log short

frequently to verify stack structure

💡 Keep branches small and focused - easier to review and manage

💡 Merge PRs bottom-up - lower branches first, then dependencies

💡 Use

--force-with-lease

when force pushing - safer than

--force