Introduction

DubStack is a CLI for stacked diffs — dependent git branches that make code review faster and more focused.

DubStack is a CLI tool for managing tree-shaped stacks of dependent git branches that make code review faster and more focused. It stores all state locally in .git/dubstack/ (with an optional SQLite backend for large stacks), uses GitHub PRs directly via the gh CLI, and includes:

AI across the flow — pluggable providers (Anthropic, Gemini, OpenAI, Bedrock, Ollama, Vercel AI Gateway) for branch names, commit messages, PR descriptions, conflict resolution, and stack-aware Q&A.
Agent integration — every read command emits --json with schemaVersion: 1, and a built-in dub mcp server exposes stack tools to MCP-aware agents under a per-repo security model.
Safe merges and retargeting — dub merge-next picks the next safe PR, dub post-merge repairs metadata after manual merges, and the wiseiodev/dubstack-retarget GitHub Action retargets dependent PR bases automatically.
Multi-level undo & redo — every mutating command is recorded in a 20-entry ring buffer; dub undo/dub redo step freely until the next new mutation.
Shell and IDE integration — dub status for prompts, dub completion <shell> for shell completions, dub man for a generated man page, themable terminal output.

Prerequisites

git installed — Version control must be available on your system.
gh CLI authenticated — Run gh auth login to authenticate.
dub installed — See Installation for details.

Quick Start

1. Start from Trunk

git checkout main
git pull

2. Create a Stack

Create three stacked branches with commits:

# Layer 1
dub create feat/auth-types -am "feat: add auth types"

# Layer 2 (parent: feat/auth-types)
dub create feat/auth-login -am "feat: add login flow"

# Layer 3 (parent: feat/auth-login)
dub create feat/auth-tests -am "test: add auth tests"

3. Inspect and Navigate

# View stack tree
dub log

# Interactive checkout
dub co

# Move around current path
dub up
dub down
dub top
dub bottom

4. Submit Stack PRs

# Submit stack
dub ss

# Preview only
dub ss --dry-run

# Open PR in browser
dub pr

5. Respond to Feedback

When feedback lands on a middle branch:

dub co feat/auth-login

# Amend current commit
dub m -a -m "fix: address review feedback"

# Or create a new commit
dub m -c -a -m "fix: follow-up"

# Push updates
dub ss

6. Keep Stack in Sync

git checkout main
git pull
dub sync

7. Handle Restack Conflicts

dub restack
# Resolve conflicts in files
git add <resolved-files>
dub restack --continue

8. Merge in Safe Order

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

# Run again for the next layer
dub merge-next

# If merges happened manually
dub post-merge

Optional: Enable AI Assistant

# Choose a provider and enter your key via a masked prompt
# (the wizard never writes the key to your shell history)
dub ai setup

# Reload your shell so the new env vars take effect
source ~/.zshrc

# Enable assistant for this repo
dub config ai-assistant on

# Optional: enable AI defaults
dub config ai-defaults create on
dub config ai-defaults submit on
dub config ai-defaults flow on

# Ask a question
dub ai ask "Summarize this stack from trunk to current branch"

# Generate metadata directly
dub create --ai
dub submit --ai

# Configure submit PR lifecycle defaults
dub config submit-default auto

# Run the full AI flow
dub flow --ai -a

Command Reference

Command	Purpose
`dub create <name> -am "msg"`	Stage all + create + commit
`dub m`	Modify current branch commit(s)
`dub log`	Show stack graph
`dub co`	Interactive checkout
`dub ss`	Submit stack PRs
`dub pr`	Open PR in browser
`dub sync`	Sync local state with remote
`dub doctor`	Run stack health checks
`dub ready`	Run pre-submit checklist
`dub restack`	Rebase stack onto updated parents
`dub merge-next`	Merge next safe PR + maintenance
`dub continue` / `dub abort`	Resume/cancel operations
`dub undo` / `dub redo`	Multi-level undo and redo (20-entry ring)
`dub ai ask "..."`	Ask AI assistant
`dub flow --ai -a`	Stage, preview, create, and submit with AI

On this page