dubstack（dubstack 命令行）

DubStack CLI Skill

Use this skill whenever the user is working in a repo that uses dub for stacked diffs.

Core Concepts

• Stack: A chain of dependent branches (main -> feat/a -> feat/b)
• Root: Trunk branch for a stack (commonly main)
• Restack: Rebase branches so each child is based on its updated parent
• Submit: Push stack branches and create/update PRs

Fast Command Map

Command Notes

Create

dub create feat/x
dub create feat/x -m "feat: ..."
dub create feat/x -am "feat: ..."
dub create feat/x -um "feat: ..."
dub create feat/x -pm "feat: ..."

• -a: stage all
• -u: stage tracked-file updates
• -p: interactive hunk staging
• staging flags require -m

AI create mode:

dub create --ai
dub create -ai
dub create --no-ai feat/x

• --ai generates both branch name and commit message from staged changes.
• --no-ai overrides repo AI defaults for a single invocation.
• if a repo commit template is configured via git config commit.template, AI create preserves that structure in the generated commit body.

Modify

dub m
dub m -c -m "fix: ..."
dub m -p
dub m -u
dub m -v
dub m -vv
dub m --interactive-rebase

• Restacks descendants after modification.
• -m can be passed multiple times.
• -v prints staged diff, -vv also prints unstaged diff.

Checkout and Navigation

dub co
# or
dub checkout --stack
dub checkout --show-untracked
dub checkout --trunk

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

Sync, Restack, Submit, PR

dub sync
dub sync --all
dub sync --no-interactive
dub sync --force
dub sync --no-restack

dub restack
dub restack --continue
dub continue
dub abort

dub ss
dub submit --dry-run
dub submit --ai
dub submit --no-ai
dub flow --ai -a
dub f --dry-run

dub pr
dub pr feat/a
dub pr 123

Track, Untrack, Delete

dub track
dub track feat/a --parent main

dub untrack feat/a
dub untrack feat/a --downstack

dub delete feat/a
dub delete feat/a --upstack
dub delete feat/a --downstack
dub delete feat/a --force --quiet

Orientation

dub parent
dub children
dub trunk

Recommended Workflow

1. Start from trunk: git checkout main && git pull
2. Create layers with dub create... -am...
3. Inspect stack with dub log
4. Submit with dub ss
5. Iterate with dub m... and dub ss
6. Keep updated with dub sync (or dub restack when needed)

AI Setup

dub ai env --gemini-key "<your-key>"
# or
dub ai env --gateway-key "<your-key>"

dub config ai-assistant on
dub config ai-defaults create on
dub config ai-defaults submit on
dub config ai-defaults flow on

Precedence:

1. command flag such as --ai or --no-ai
2. repo-local dub config ai-defaults...
3. built-in fallback of off

AI Workflow

Manual path:

1. stage changes
2. run dub create <name> -am "type: summary"
3. run dub submit

AI-assisted path:

1. stage changes or use -a, -u, or -p
2. run dub flow --ai
3. review the rendered branch, commit, and PR previews
4. approve or edit
5. let DubStack create and submit

Notes:

• In non-interactive terminals, add -y because dub flow approval prompts require a TTY.
• dub ai ask streams response text live and renders tool/status lines separately in TTY output.

Template Setup

If a repo wants DubStack AI to follow existing formatting, set up templates first.

Pull request templates:

• .github/pull_request_template.md
• .github/PULL_REQUEST_TEMPLATE.md
• .github/PULL_REQUEST_TEMPLATE/*.md
• docs/pull_request_template.md
• pull_request_template.md

Commit message templates:

cat <<'EOF' > .gitmessage
feat(scope): summary

## Testing
- [ ] added coverage
EOF

git config commit.template .gitmessage

Notes:

• PR titles still come from the last commit message.
• AI-generated PR descriptions preserve repo PR template structure when present.
• AI-generated commit bodies preserve repo commit template structure when present, but the first line still needs to be a valid Conventional Commit subject.

Recovery Patterns

Restack conflict

# after conflict
git add <resolved-files>
dub restack --continue

Undo mistaken create/restack

dub undo

Branch not tracked

• Track branch explicitly:

dub track <branch> --parent <parent>

• Verify placement:

dub parent <branch>
dub trunk <branch>

Common Errors

References

• Command Reference
• Workflow Reference