tomevault-io SKILL: Using Git Worktrees
Purpose: Parallel development using isolated workspaces for concurrent feature branches Target: Developers working on multiple features simultaneously
Quick Start
When to Use This Skill
- Developing multiple features concurrently
- Running long-running tests on one branch while working on another
- Isolating experimental changes without stash/commit dance
- Hotfix production while continuing feature work
Quick Reference
# Create new worktree
git worktree add ../project-feature-1 feature-1
git worktree add ../project-feature-2 feature-2
# List worktrees
git worktree list
# Remove worktree after merge
git worktree remove ../project-feature-1
Core Concepts
Worktree Creation
Basic Syntax:
git worktree add <path> <branch> [<start-point>]
Examples:
# Create worktree for existing branch
git worktree add ../myproject-feature feature-x
# Create worktree for new branch
git worktree add ../myproject-experiment -b experiment-branch
# Create worktree at specific commit
git worktree add ../myproject-v1.0 -b v1.0-fixes a1b2c3d
Worktree Management
List worktrees:
git worktree list
# Output:
# /path/to/main abc1234 [main]
# /path/to/feature-1 def5678 [feature-1]
# /path/to/hotfix ghi9012 [hotfix/security-fix]
Remove worktree:
# Prune after deleting directory manually
rm -rf ../myproject-feature
git worktree prune
# Remove directly
git worktree remove ../myproject-feature
Lock worktree (prevent cleanup):
git worktree lock ../myproject-critical
git worktree unlock ../myproject-critical
Workflow Integration
Parallel Development Pattern:
# Main workspace: feature work
cd ~/project-main
git checkout -b feature-auth
# Worktree 1: Hotfix
git worktree add ../project-hotfix -b hotfix-login
cd ../project-hotfix
# Fix hotfix, test, commit, push
# Worktree 2: Experiment
git worktree add ../project-experiment -b experiment-ui
cd ../project-experiment
# Try new UI approach, discard if fails
# Return to main workspace
cd ~/project-main
# Continue feature work, merge hotfix when ready
Cleanup
After Feature Merge
# 1. Merge feature branch to main
git checkout main
git merge feature-1
# 2. Remove worktree
git worktree remove ../project-feature-1
# 3. Delete branch (optional)
git branch -d feature-1
# 4. Prune stale worktrees
git worktree prune
Automated Cleanup
# Remove all worktrees for merged branches
git worktree list | while read path commit branch; do
if git merge-base --is-ancestor "${branch:0:-1}" main 2>/dev/null; then
git worktree remove "$path"
fi
done
Verification
Test Worktree Operations
# Create test worktree
git worktree add /tmp/test-worktree -b test-worktree-branch
# Verify it exists
git worktree list | grep test-worktree-branch
# Verify isolation
cd /tmp/test-worktree
git status # Should show test-worktree-branch, not main
# Cleanup
git worktree remove /tmp/test-worktree
Troubleshooting
Worktree Already Registered
Error: working tree '.claude' already exists
Solution: Remove existing worktree first
git worktree list # Find the worktree
git worktree remove <path> # Remove it
Detached HEAD in Worktree
Issue: Worktree showing commit hash instead of branch
Fix: Create local branch
cd ../project-worktree
git checkout -b local-branch-name
Related Skills
- git-operations: Push/pull/merge operations across worktrees
- parallel-subagents: Coordinate work across multiple worktrees
- git-master: Git workflow mastery including worktrees
Version: claude-pilot 4.3.0
Converted and distributed by TomeVault — claim your Tome and manage your conversions.