dev_manage_git-worktrees

Using Git Worktrees

Overview

Use git worktrees to create isolated workspaces sharing the same repository, enabling work on multiple branches simultaneously without switching.

Core principle: Apply systematic directory selection + safety verification to ensure reliable isolation.

Announce at start: "I'm using the dev_manage_git-worktrees skill to set up an isolated workspace."

Primary Sources

Git Documentation:

• git worktree --help - Complete git worktree reference
• git worktree list - Show all worktrees
• git worktree remove - Cleanup worktrees

Integration:

• .claude/agents/git-operations/ - Delegates worktree setup to this skill
• finishing-a-development-branch skill - REQUIRED for cleanup after work complete

Directory Selection Process

Follow this priority order:

1. Check Existing Directories

# Check in priority order
ls -d .worktrees 2>/dev/null     # Preferred (hidden)
ls -d worktrees 2>/dev/null      # Alternative

If found: Use that directory. If both exist, prefer .worktrees.

2. Check AGENTS.md

grep -i "worktree.*director" AGENTS.md 2>/dev/null

If preference specified: Use it without asking.

3. Ask User

If no directory exists and no AGENTS.md preference:

No worktree directory found. Where should I create worktrees?

1. .worktrees/ (project-local, hidden)
2. ~/.config/superpowers/worktrees/<project-name>/ (global location)

Which would you prefer?

Safety Verification

For Project-Local Directories (.worktrees or worktrees)

MUST verify .gitignore before creating worktree:

# Check if directory pattern in .gitignore
grep -q "^\.worktrees/$" .gitignore || grep -q "^worktrees/$" .gitignore

If NOT in .gitignore:

Per "Fix broken things immediately" principle:

1. Add appropriate line to .gitignore
2. Commit the change
3. Proceed with worktree creation

Why critical: Prevents accidentally committing worktree contents to repository.