Workflows

Copy-paste playbooks for the most common stacked PR operations.

1. Create and Submit a New Stack

git checkout main
git pull

dub create feat/base -am "feat: add base layer"
dub create feat/middle -am "feat: add middle layer"
dub create feat/top -am "feat: add top layer"

dub log
dub ss

2. Update a Middle Branch After Review

dub co feat/middle

# edit files...
dub m -a -m "fix: address review feedback"

# optional diff check before modify
dub m -vv

dub ss

3. Sync After Trunk Moves

git checkout main
git pull

dub sync

For deterministic non-interactive behavior:

dub sync --no-interactive

For explicit destructive reconciliation:

dub sync --force

4. Conflict Recovery During Restack

dub restack
# conflict occurs

# resolve files
git add <resolved-files>

dub restack --continue

If you are already mid-operation, use the unified recovery commands:

dub continue
# or
dub abort

5. Open PR Quickly

dub pr
# or
dub pr feat/top
# or
dub pr 123

6. Recover from Mistakes

# Undo the most recent mutating dub command
dub undo

# Undo multiple steps in sequence
dub undo --steps 3

# Replay the most recently undone op
dub redo

undo/redo is multi-level, backed by a 20-entry ring buffer at .git/dubstack/undo-log.json.
Covers create, restack, move, reorder, absorb, unlink, rename, pop, modify, freeze/unfreeze, track/untrack, delete, sync, split, and submit (PR body restore only).
See Recovery for the full operation table and limitations.

7. Repair Untracked Branch Metadata

# Branch created outside dub create
git checkout feat/manual

dub track feat/manual --parent main

# Verify placement
dub parent feat/manual
dub trunk feat/manual

8. Remove Metadata or Delete Branches Safely

# Metadata-only removal
dub untrack feat/top

# Remove branch + descendants from metadata
dub untrack feat/middle --downstack

# Delete branch with confirmation
dub delete feat/top

# Delete branch and descendants non-interactively
dub delete feat/middle --upstack --force --quiet

9. Stack Inspection Modes

dub log --stack
dub log --all
dub log --reverse

dub up
dub up 2
dub down
dub down --steps 2
dub top
dub bottom

11. Checkout Patterns

# Interactive
dub checkout

# Interactive current stack only
dub checkout --stack

# Include untracked branches
dub checkout --show-untracked

# Jump to trunk
dub checkout --trunk

12. Merge Stacks Safely (Bottom-Up)

# Merge next safe PR in stack order
dub merge-next

# Run again for the next layer
dub merge-next

If you merged manually, normalize state and retarget remaining PRs:

dub post-merge