Skip to content

commands.md

Latest commit

 

History

History
184 lines (117 loc) · 4.62 KB

commands.md

File metadata and controls

184 lines (117 loc) · 4.62 KB

Commands

stack new <branch-name> [parent]

Create a new branch in the stack, optionally specifying a parent branch.

The new branch will be created from the specified parent (or current branch if not specified), and the parent relationship will be stored in git config.

# Create a stack: main <- A <- B <- C
stack new A main                         # A based on main
stack new B                              # B based on current (A)
stack new C                              # C based on current (B)

# Preview without creating
stack new feature-xyz --dry-run

stack status

Display the stack structure as a tree, showing branch hierarchy, current branch (marked with *), and PR status.

stack status

# Show without PR info (faster)
stack status --no-pr

Flags:

  • --no-pr - Skip fetching PR information (faster)

stack sync

Perform a full sync of the stack:

  1. Fetch latest changes from origin
  2. Rebase each stack branch onto its parent (in bottom-to-top order)
  3. Force push each branch to origin
  4. Update PR base branches to match the stack (if PRs exist)
# Sync all branches and update PRs
stack sync

# Preview what would happen
stack sync --dry-run

# Force push even if branches have diverged
stack sync --force

Flags:

  • --force, -f - Use --force instead of --force-with-lease for push (bypasses safety checks)

stack parent [new-parent]

Show or change the parent branch of the current branch in the stack.

Without arguments, displays the current parent. With a branch argument, changes the parent to the specified branch and updates the PR base if a PR exists.

# Show parent of current branch
stack parent

# Change current branch to be based on a different parent
stack parent feature-auth

# Preview what would happen
stack parent main --dry-run

stack prune

Remove branches with merged PRs from stack tracking and delete them locally.

# Clean up merged stack branches
stack prune

# Clean up all merged branches (including non-stack branches)
stack prune --all

# Force delete even if branches have unmerged commits
stack prune --force

# Preview what would be deleted
stack prune --dry-run

Flags:

  • --all, -a - Check all local branches, not just stack branches
  • --force, -f - Force delete branches even if they have unmerged commits

stack rename <new-name>

Rename the current branch while preserving all stack relationships.

This command will rename the git branch, update the branch's parent reference, and update all child branches to point to the new name.

# Rename current branch
stack rename feature-improved-name

# Preview without making changes
stack rename feature-improved-name --dry-run

stack worktree <branch-name> [base-branch]

Create a git worktree in the configured worktrees directory for the specified branch.

If the branch exists locally or on the remote, it will be used. If the branch doesn't exist, a new branch will be created from the current branch (or from base-branch if specified) and stack tracking will be set up automatically.

By default, worktrees are created under ~/.stack/worktrees/<reponame>. You can change this with:

git config stack.worktreesDir ~/worktrees

stack config

Show the current configuration for this repo.

stack config get

Show the current configuration for this repo (same as stack config).

stack config set

Interactively choose where worktrees are created for this repo:

  • ~/.stack/worktrees (default)
  • ./.worktrees (project-local)
# Create worktree for new branch (from current branch, with stack tracking)
stack worktree my-feature

# Create worktree from a fresh main branch
stack worktree my-feature main

# Create worktree for existing local or remote branch
stack worktree existing-branch

# Clean up worktrees for merged branches
stack worktree --prune

Flags:

  • --prune - Remove worktrees for branches with merged PRs

stack skill install

Install the stack skill for AI coding tools so they know how to use the stack CLI.

Automatically detects which supported tools are installed and installs for all of them:

  • Claude Code - via plugin marketplace (claude CLI required)
  • Codex - writes SKILL.md to ~/.agents/skills/stack/ (codex CLI required)
  • Cursor - writes stack.mdc to ~/.cursor/rules/ (cursor CLI or ~/.cursor/ directory required)
stack skill install

stack version

Print version information.

stack version

Global Flags

These flags are available on all commands:

  • --dry-run - Show what would happen without executing
  • --verbose, -v - Show detailed output