worktree（工作树）

Git Worktree Manager

Manages the full lifecycle of git worktrees: creation, monitoring, cleanup, and maintenance.

Subcommands

Default: No subcommand or unrecognized arg = create

When to use

• Creating isolated workspace for new feature/fix
• Viewing all active worktrees across a repo
• Cleaning up after merging PRs
• Removing abandoned/stale worktrees
• Protecting important worktrees on portable storage

When not to use

• Simple branch switching (use git checkout)
• Temporary file exploration (use git stash or read-only)
• Submodule management (different concept)

Subcommand: create

Creates new worktree in sibling directory with conventional commit branch naming.

Workflow

1. Get name: From args or ask user (e.g., "alerts", "fix-login")
2. Prompt for type: Use AskUserQuestion

- Header: "Commit type" - Options: feat, fix, chore, docs, refactor, test, perf, ci

1. Construct branch: {type}/{name} (e.g., feat/alerts)
2. Determine path:

- Get repo name from remote/directory - Path: ../{repo}-{type}-{name} (slashes → hyphens)

1. Create: git worktree add -b {branch} {path}
2. Confirm: Show branch name, path, and cd command

Error handling

• Branch exists → offer to use existing or suggest new name
• Directory exists → warn and ask to proceed or rename
• Dirty working tree → warn but allow (worktree add works regardless)

Subcommand: list

Shows all worktrees with status information.

Workflow

1. Run: git worktree list -v
2. Parse and display:

- Path - Branch name (or "detached HEAD") - Status flags: locked, prunable, bare - Commit SHA (short)

1. Enhance (optional): For each worktree, show:

- Uncommitted changes count: git -C {path} status --porcelain | wc -l - Ahead/behind upstream: git -C {path} rev-list --left-right --count @{u}...HEAD

Example output

Worktrees for my-project:
  /path/to/main          [main]           clean, up-to-date
  /path/to/feat-alerts   [feat/alerts]    3 uncommitted, 2 ahead
  /path/to/old-feature   [fix/old]        prunable (directory missing)

Subcommand: remove

Removes single worktree with full branch cleanup.

Workflow

1. Identify target: From args or show list and ask
2. Check status: git -C {path} status --porcelain

- If uncommitted changes → warn and confirm force removal

1. Get branch name for cleanup: git -C {path} branch --show-current
2. Remove worktree: git worktree remove {path} # clean git worktree remove -f {path} # if uncommitted changes git worktree remove -ff {path} # if locked
3. Delete local branch: git branch -d {branch} # safe (fails if unmerged) git branch -D {branch} # force (if user confirms)
4. Offer remote branch deletion (AskUserQuestion):

- Check if remote exists: git ls-remote --heads origin {branch} - If yes, ask: "Delete remote branch too?" - If yes: git push origin --delete {branch}

1. Confirm: Summarize what was removed

Safety checks

• Never remove main worktree (the original repo)
• Warn if branch has unpushed commits
• Warn if PR is still open for this branch

Subcommand: cleanup

Interactive batch removal of multiple worktrees.

Workflow

1. List all worktrees: git worktree list --porcelain
2. Filter candidates:

- Exclude main worktree - Flag: prunable, merged branches, old (no commits in 2+ weeks)

1. Present selection (AskUserQuestion with multiSelect):

- Header: "Cleanup" - Question: "Which worktrees should be removed?" - Options: List each non-main worktree with status

1. For each selected: Run remove workflow
2. Run prune: git worktree prune -v
3. Summary: Show what was cleaned up

Subcommand: prune

Removes stale worktree administrative files.

Workflow

1. Preview: git worktree prune -n -v
2. If stale entries found:

- Show what will be pruned - Confirm with user

1. Prune: git worktree prune -v
2. Report: Show removed entries

When to use

• After manually deleting worktree directories
• After moving worktree without git worktree move
• Periodic maintenance

Subcommand: lock / unlock

Protects worktree from automatic pruning.

Lock workflow

1. Identify worktree: From args or list and ask
2. Prompt for reason (optional):

- "Why lock this worktree?" (e.g., "portable drive", "long-running experiment")

1. Lock: git worktree lock --reason "{reason}" {path} # or without reason: git worktree lock {path}
2. Confirm: Show locked status

Unlock workflow

1. Identify worktree: From args or list locked ones
2. Unlock: git worktree unlock {path}
3. Confirm: Show unlocked status

Validation checklist

• Correct subcommand identified from args
• Branch naming follows {type}/{name} convention
• Worktree path is sibling directory, not nested
• No uncommitted changes lost without warning
• Local branch deleted only after worktree removal
• Remote branch deletion is opt-in, not automatic
• Main worktree protected from removal
• Prune only runs after user confirmation

Examples

Example 1: Create

User: /worktree queue-alerts
Claude: [asks commit type] → User: feat
Claude: Created worktree
  Branch: feat/queue-alerts
  Path: ../my-project-feat-queue-alerts
  Run: cd ../my-project-feat-queue-alerts

Example 2: List

User: /worktree list
Claude: Worktrees for my-project:
  /Users/me/my-project              [main]           clean
  /Users/me/my-project-feat-alerts  [feat/alerts]    2 uncommitted
  /Users/me/my-project-fix-bug      [fix/bug-123]    prunable

Example 3: Remove with cleanup

User: /worktree remove ../my-project-feat-alerts
Claude: Worktree has 2 uncommitted changes. Force remove?
User: yes
Claude: [asks about remote branch deletion] → User: yes
Claude: Removed:
  - Worktree: ../my-project-feat-alerts
  - Local branch: feat/alerts
  - Remote branch: origin/feat/alerts

Example 4: Interactive cleanup

User: /worktree cleanup
Claude: [shows multiselect with 3 worktrees]
User: [selects 2]
Claude: Removed 2 worktrees, pruned 1 stale entry
  - feat/old-feature (merged)
  - fix/abandoned (no remote)

Notes

• Worktrees share git objects but have separate working directories
• Each worktree can have different branch checked out simultaneously
• Locked worktrees survive git gc and won't be auto-pruned
• Use git worktree move to relocate (not manual mv)
• See WORKFLOWS.md for detailed step-by-step procedures

Evaluation Prompts

Test 1: Activation - create (should trigger)

User: /worktree new-dashboard
Expected: Skill activates, asks for commit type, creates worktree

Test 2: Activation - list (should trigger)

User: /worktree list
Expected: Skill activates, runs git worktree list, shows formatted output

Test 3: Activation - cleanup (should trigger)

User: /worktree cleanup
Expected: Skill activates, lists worktrees with multiselect, processes removals

Test 4: Activation - natural language (should trigger)

User: I need to clean up my old worktrees
Expected: Skill activates with cleanup subcommand context

Test 5: Non-activation (should NOT trigger)

User: How do I switch to a different branch?
Expected: Normal response about git checkout/switch, NOT worktree skill

Test 6: Non-activation (should NOT trigger)

User: Delete the feature-x branch
Expected: Normal git branch -d advice, NOT worktree removal

Test 7: Edge case - remove main worktree

User: /worktree remove .
Expected: Skill refuses with clear error "Cannot remove main worktree"

Test 8: Edge case - remove with uncommitted changes

User: /worktree remove ../project-feat-wip
Context: Worktree has uncommitted changes
Expected: Warning shown, asks for confirmation before force removal

Test 9: Edge case - no worktrees to cleanup

User: /worktree cleanup
Context: Only main worktree exists
Expected: "No worktrees available for cleanup" message