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

2. 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

3. Create the worktree

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

4. Notify the user

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

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

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

6. 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

7. 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