using-git-worktrees

name	using-git-worktrees
version	1.0.0
description	Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification
dependencies	{}

Using Git Worktrees

Overview

Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.

Core principle: Systematic directory selection + safety verification = reliable isolation.

Directory Selection Process

Follow this priority order:

1. Check Existing Directories

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

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

2. Check Project Config

Check CLAUDE.md, AGENTS.md, or similar config for worktree directory preference.

3. Ask User

If no directory exists and no config preference, ask the user.

Safety Verification

For Project-Local Directories

MUST verify directory is ignored before creating worktree:

git check-ignore -q .worktrees 2>/dev/null

If NOT ignored: Add to .gitignore, commit, then proceed.

For Global Directory

No .gitignore verification needed - outside project entirely.

Creation Steps

1. Detect Project Name: project=$(basename "$(git rev-parse --show-toplevel)")
2. Create Worktree: git worktree add "$path" -b "$BRANCH_NAME"
3. Run Project Setup: Auto-detect (package.json → npm install, Cargo.toml → cargo build, etc.)
4. Verify Clean Baseline: Run tests to ensure worktree starts clean
5. Report Location: Confirm worktree path and test status

Quick Reference

Situation	Action
.worktrees/ exists	Use it (verify ignored)
worktrees/ exists	Use it (verify ignored)
Both exist	Use .worktrees/
Neither exists	Check config → Ask user
Directory not ignored	Add to .gitignore + commit
Tests fail during baseline	Report failures + ask

Common Mistakes

• Skipping ignore verification — Worktree contents get tracked, pollute git status
• Assuming directory location — Creates inconsistency, violates project conventions
• Proceeding with failing tests — Can't distinguish new bugs from pre-existing issues
• Hardcoding setup commands — Breaks on projects using different tools

Red Flags

Never:

• Create worktree without verifying it's ignored (project-local)
• Skip baseline test verification
• Proceed with failing tests without asking
• Assume directory location when ambiguous