Using git-spice (gs/gsp)

Pick the CLI name (gs vs gsp)

Prefer gsp if it exists (some setups rename git-spice to avoid clashing with Ghostscript’s gs):

command -v gsp >/dev/null && SPICE=gsp || SPICE=gs
$SPICE --version

Use $SPICE in all commands below.

Key concepts (quick refresher)

• Trunk: main integration branch (usually main or master).
• Stack: branches connected to your current branch (parents + children).
• Downstack: branches between current branch and trunk (ancestors).
• Upstack: branches above current branch (descendants).
• Restack: rebase tracked branches onto updated bases to keep stack relationships intact.

Example:

main (trunk)
└── feature-a
    └── feature-b
        └── feature-c

When on feature-b:

• Upstack: feature-c
• Downstack: feature-a, main

Safety checklist

• Require a clean working tree before restack, submit, sync, edit, or any delete.
• Avoid manual history surgery on tracked branches (git rebase, git push --force). Prefer git-spice restack + submit.
• Never run destructive commands (stack delete, upstack delete, repo init --reset) unless the user explicitly asked.

Quick reference

Core workflows

1) Initialize repo (once per repo)

$SPICE repo init
# or explicit:
$SPICE repo init --trunk=main --remote=origin

Optional forge auth:

$SPICE auth status || $SPICE auth login

2) Start or extend a stack

Track the current branch (useful for the first branch in a stack):

git add -A
$SPICE branch track

Create a new branch on top of the current one (commits staged changes + tracks it):

git add -A
$SPICE branch create feat/foo-ui

Inspect stacks:

$SPICE log short
$SPICE log long
$SPICE log short --all

3) Navigate

$SPICE up
$SPICE down
$SPICE top
$SPICE bottom
$SPICE trunk

4) Edit in the middle of a stack (restack)

After modifying a lower branch, restack everything above it:

git add -A
git commit -m "…"
$SPICE upstack restack

Or do commit + restack in one step:

git add -A
$SPICE commit create -m "…"
# shorthand: $SPICE cc -m "…"

If conflicts happen, use the rebase helpers:

$SPICE rebase continue
$SPICE rebase abort

5) Submit PRs/MRs (“Change Requests”)

Submit/update:

$SPICE branch submit        # current only
$SPICE upstack submit       # current + descendants
$SPICE downstack submit     # current + ancestors to trunk
$SPICE stack submit         # whole stack
$SPICE stack submit --fill  # derive title/body from commits
$SPICE stack submit --update-only --fill
$SPICE stack submit --fill --draft --web

6) Sync with trunk + prune merged branches

$SPICE repo sync
$SPICE repo sync --restack

If the repo has many tracked branches and needs full alignment:

$SPICE repo restack

7) Adopt existing branches into a stack

Track a single existing branch:

git checkout feature/big
$SPICE branch track --base main

Track an existing chain of branches (run from the topmost branch):

git checkout <top-branch>
$SPICE downstack track

8) Stack surgery (reorder / delete)

Reorder branches:

$SPICE stack edit

Destructive (require explicit user confirmation):

$SPICE stack delete --force
$SPICE upstack delete --force

When to use git vs git-spice

Use git-spice for:

• Creating/tracking stacked branches: $SPICE branch create, $SPICE branch track, $SPICE downstack track
• Keeping stacks aligned: $SPICE upstack restack, $SPICE stack restack, $SPICE repo restack
• PR/MR workflows: $SPICE branch submit, $SPICE stack submit, $SPICE repo sync
• Navigation & inspection: $SPICE up, $SPICE down, $SPICE log short

Use git for:

• Editing and committing: git add, git commit, git status, git diff
• One-off investigation: git log, git blame

Common mistakes / red flags

Red flags:

• You’re about to run git rebase or git push --force on a tracked branch.
• You’re not sure whether you want upstack vs stack vs downstack scope.

When in doubt:

$SPICE log short
$SPICE <command> --help

Handling conflicts (during restack)

If restack hits conflicts:

1. Resolve conflicts using normal git tools (git status, edit files, git add …).
2. Continue with either $SPICE rebase continue (preferred) or git rebase --continue.
3. After it finishes, update remotes with $SPICE upstack submit or $SPICE stack submit.

Config knobs (git config)

git config spice.submit.draft true
git config spice.submit.label "stacked,foo"
git config spice.submit.navigationComment multiple
git config spice.repoSync.closedChanges ignore

References

• Deep-dive guide and examples: references/using-git-spice.md
• Test prompts / scenarios: test-scenarios.md
• For a specific subtopic, search the deep-dive for: “Adopting”, “Stack surgery”, “Agent-friendly snippets”, “repo sync”.