Agent skill
using-git-worktrees
Use when developing multiple features in parallel. Isolated workspaces prevent conflicts and enable concurrent branches.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/using-git-worktrees-changoo89-claude-pilot
SKILL.md
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
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?