create-worktree（创建工作树）

Create Worktree

Creates and bootstraps a git worktree for isolated development work.

Arguments

• name (required): Name for the worktree directory and branch
• --spec=<path>: Path to a spec file to copy into the worktree's specs directory
• --base=<branch>: Base branch to create worktree from (default: current branch or configured default)
• --no-bootstrap: Skip the onBootstrap hook

Configuration

Check for .claude/spec-workflow/config.yaml:

paths:
  worktrees: "./worktrees"      # Where worktrees are created
  specs: "./specs"              # Where specs live (for copying)

worktree:
  branchNaming: "{name}"        # Branch naming pattern
  defaultBase: null             # Default base branch (null = current)
  onBootstrap: null             # Hook script to run after creation

Branch Naming

The branchNaming pattern supports these tokens:

• {name} - The worktree name
• {date} - Current date (YYYY-MM-DD)

Examples:

• "{name}" → my-feature
• "feature/{name}" → feature/my-feature
• "{date}-{name}" → 2024-01-15-my-feature

Bootstrap Hook

If worktree.onBootstrap is configured, it runs after worktree creation with these environment variables:

Example hook script:

#!/bin/bash
cd "$WORKTREE_PATH"
npm install
# ... any other setup

Steps

1. Check if worktree exists

- Check if a worktree with the given name already exists at the configured path - If it does, respond with "Worktree already exists at [path]" and exit - If it does not exist, proceed

1. Determine paths and branch name

- Worktree path: {config.paths.worktrees}/{name} (default: ./worktrees/{name}) - Branch name: Apply branchNaming pattern (default: {name}) - Base branch: --base argument, or worktree.defaultBase, or current branch

1. Create the worktree

   git worktree add -b [branch-name] [worktree-path] [base-branch]

1. Notify the user

   Worktree created at [path] on branch [branch-name].

1. Handle spec file (if --spec provided)

- Copy the spec file to the worktree's specs directory - Update spec frontmatter with worktree and branch info

1. Run bootstrap hook (unless --no-bootstrap)

- If worktree.onBootstrap is configured, run it with environment variables - If not configured, skip this step - Report success or failure

1. Final confirmation

   Worktree ready at [path].

   To work in this worktree:
   - Open a new terminal in [path]
   - Or use: cd [path]

Example Usage

# Basic worktree creation
/create-worktree feature-login

# Create worktree with a spec file
/create-worktree user-notifications --spec=specs/2024-01-15-notifications-spec.md

# Create worktree from a different base branch
/create-worktree hotfix-auth --base=release/v2.0

# Create worktree without running bootstrap
/create-worktree quick-fix --no-bootstrap

Notes

• Worktrees are typically gitignored (add worktrees/ to .gitignore)
• Each worktree has its own working directory but shares git history
• Worktrees allow parallel work on different features without stashing
• Use /worktree-cleanup (if available) to remove stale worktrees