tomevault-io Using Git Worktrees
Overview
Create isolated workspaces sharing the same repository for parallel branch work. Follow systematic directory selection and safety verification to ensure reliable isolation.
Violating the letter of the rules is violating the spirit of the rules. Skipping safety verification "just this once" or assuming directory locations are the most common causes of worktree problems.
When to Use
- Starting feature work requiring isolation from current workspace
- Working on multiple branches simultaneously
- Executing implementation plans in a clean environment (OPTIONAL: pairs with
humaninloop:plan) - Testing changes without affecting the main working directory
- Parallel code review while continuing development
When NOT to Use
- Single-branch workflows: No need for isolation when working linearly
- Quick fixes on current branch: Worktrees add overhead for simple changes
- Non-git repositories: Worktrees are git-specific
- Temporary experiments: A simple branch may suffice
- When disk space is constrained: Each worktree duplicates working files
Red Flags - STOP and Restart Properly
If any of these thoughts arise, STOP immediately:
- "The directory is probably already ignored"
- "I know where worktrees go in this project"
- "Tests are slow, I'll skip baseline verification"
- "This is a simple project, safety checks are overkill"
- "User wants to start quickly, I'll verify later"
- "I've done this before, I can skip the priority order"
All of these mean: Rationalization is occurring. Restart with proper process.
Common Rationalizations
| Excuse | Reality |
|---|---|
| "Directory is probably ignored" | Probably =/= verified. One git check-ignore command takes seconds. Always verify. |
| "I know where worktrees go here" | Knowledge =/= following process. Check existing directories, then CLAUDE.md, then ask. |
| "Tests are slow" | Slow tests =/= skip tests. Baseline verification prevents hours of debugging wrong baseline. |
| "Simple project" | Simple projects have caused the biggest worktree pollution. Process exists because of them. |
| "Will verify later" | Later rarely comes. Worktree contents in git history are permanent mistakes. Do it now. |
| "User seems impatient" | Impatience is not permission. Explain why verification matters. |
Core Process
Step 1: Directory Selection
Follow this priority order strictly:
1.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, .worktrees takes precedence.
1.2 Check CLAUDE.md Configuration
grep -i "worktree.*director" CLAUDE.md 2>/dev/null
If a preference is specified, use it without asking.
1.3 Ask User
Only when no directory exists AND no CLAUDE.md preference:
No worktree directory found. Where should worktrees be created?
1. .worktrees/ (project-local, hidden)
2. ~/worktrees/<project-name>/ (global location)
Which is preferred?
No exceptions:
- Not for "obvious" projects
- Not for "standard" setups
- Not when "everyone uses .worktrees"
- Not even if user says "just use the usual place"
Step 2: Safety Verification
For project-local directories (.worktrees or worktrees):
MUST verify directory is ignored before creating worktree:
# Verify directory is ignored (respects local, global, and system gitignore)
git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
If NOT ignored:
- Add appropriate line to
.gitignore - Commit the change:
git add .gitignore && git commit -m "chore: add worktree directory to gitignore" - Proceed with worktree creation
Why critical: Prevents accidentally committing worktree contents to repository. Worktree contents in git history cannot be fully removed without history rewriting.
For global directories (e.g., ~/worktrees):
No gitignore verification needed - outside project entirely.
No exceptions:
- Not for "I'm pretty sure it's already ignored"
- Not for "this repo has good gitignore defaults"
- Not when "I'll check after creating the worktree"
- Not even for "the user said don't worry about it"
Step 3: Create Worktree
# Get project name
project=$(basename "$(git rev-parse --show-toplevel)")
# Determine full path based on location type
# For project-local:
path=".worktrees/$BRANCH_NAME"
# For global:
path="$HOME/worktrees/$project/$BRANCH_NAME"
# Create worktree with new branch
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"
Step 4: Run Project Setup
Auto-detect and run appropriate setup commands:
| File | Setup Command |
|---|---|
package.json |
npm install or yarn install or pnpm install |
Cargo.toml |
cargo build |
requirements.txt |
pip install -r requirements.txt |
pyproject.toml |
poetry install or pip install -e . |
go.mod |
go mod download |
Gemfile |
bundle install |
Skip setup only if no recognizable project file exists.
Step 5: Verify Clean Baseline
Run tests to ensure worktree starts clean:
# Use project-appropriate command
npm test # Node.js
cargo test # Rust
pytest # Python
go test ./... # Go
bundle exec rspec # Ruby
If tests fail: Report failures with details. Ask whether to proceed or investigate.
If tests pass: Report success with test count.
If no test command available: Note this and proceed, but warn that baseline is unverified.
No exceptions:
- Not for "tests are slow, user wants to start"
- Not for "I ran tests recently in the main worktree"
- Not when "this is a simple feature, baseline doesn't matter"
- Not even for "user explicitly asked to skip testing"
Step 6: Report Completion
Worktree ready at <full-path>
Branch: <branch-name>
Tests: <N> passing, 0 failures (or "no test suite detected")
Ready to implement <feature-name>
After implementation is complete, follow the cleanup workflow in the Multi-Worktree Management section.
Quick Reference
| Situation | Action |
|---|---|
.worktrees/ exists |
Use it (verify ignored first) |
worktrees/ exists |
Use it (verify ignored first) |
| Both exist | Use .worktrees/ |
| Neither exists | Check CLAUDE.md, then ask user |
| Directory not ignored | Add to .gitignore, commit, then proceed |
| Tests fail during baseline | Report failures, ask before proceeding |
| No package manager file | Skip dependency install, note it |
| No test suite | Proceed with warning about unverified baseline |
Common Mistakes
| Mistake | Problem | Fix |
|---|---|---|
| Skipping ignore verification | Worktree contents get tracked, pollute git status, potentially committed | Always run git check-ignore for project-local directories |
| Assuming directory location | Creates inconsistency, violates project conventions | Follow priority: existing > CLAUDE.md > ask |
| Proceeding with failing tests | Cannot distinguish new bugs from pre-existing issues | Report failures, get explicit permission |
| Hardcoding setup commands | Breaks on projects using different tools | Auto-detect from project files |
| Skipping user prompt | Creates worktrees where user does not want them | When ambiguous, always ask |
Error Recovery
Worktree Creation Fails
| Error | Cause | Resolution |
|---|---|---|
fatal: '<path>' already exists |
Directory exists from previous attempt | Remove directory: rm -rf <path>, then retry |
fatal: '<branch>' is already checked out |
Branch active in another worktree | Use different branch name or remove existing worktree |
fatal: not a git repository |
Not in a git repo | Navigate to git repository root first |
fatal: invalid reference |
Base branch doesn't exist | Verify branch name, fetch from remote if needed |
Recovery Steps
- Check worktree state:
git worktree list - Identify stuck entries: Look for paths that no longer exist
- Prune stale entries:
git worktree prune - Force remove if needed:
git worktree remove --force <path>
Locked Worktrees
If a worktree shows as locked:
# Check lock status
git worktree list --porcelain | grep -A1 locked
# Unlock (only if certain no process is using it)
git worktree unlock <path>
Multi-Worktree Management
Listing Active Worktrees
git worktree list
# Output:
# /path/to/main abc1234 [main]
# /path/to/.worktrees/feature-a def5678 [feature-a]
# /path/to/.worktrees/feature-b ghi9012 [feature-b]
Switching Between Worktrees
Each worktree is independent. Simply cd to the desired worktree path. No checkout or stash required.
Cleanup Workflow
After branch is merged or abandoned:
# 1. Return to main worktree
cd /path/to/main
# 2. Remove the worktree
git worktree remove .worktrees/feature-name
# 3. Delete the branch (if merged)
git branch -d feature-name
# 4. Prune any stale references
git worktree prune
For comprehensive cleanup after feature completion, follow the steps above.
Disk Space Considerations
Each worktree duplicates working files (not git objects). Monitor disk usage:
# Check worktree sizes
du -sh .worktrees/*
# Remove largest/oldest worktrees first when space constrained
Reference Commands
# List all worktrees
git worktree list
# Create worktree with new branch
git worktree add <path> -b <branch-name>
# Create worktree from existing branch
git worktree add <path> <existing-branch>
# Remove a worktree
git worktree remove <path>
# Force remove (uncommitted changes)
git worktree remove --force <path>
# Prune stale worktree entries
git worktree prune
# Lock worktree (prevent accidental removal)
git worktree lock <path>
# Unlock worktree
git worktree unlock <path>
Example Scripts
Working shell scripts are available in examples/:
- examples/worktree-setup.sh - Complete worktree creation with safety checks
- examples/worktree-cleanup.sh - Safe removal with uncommitted change detection
- examples/worktree-list.sh - Enhanced listing with status and disk usage
Converted and distributed by TomeVault — claim your Tome and manage your conversions.