git-worktree
Git Worktree - Parallel Development
Overview
Git worktrees enable multiple working directories from a single repository. Each worktree has its own branch while sharing the same Git object database.
Core principle: Check worktree status, create worktree for parallel work, reference cleanup commands as needed.
When to Use
Use worktrees when:
- Working on multiple branches simultaneously
- Emergency hotfix needed without disrupting current work
- Reviewing PRs in isolation
- Testing across branches without stashing
Avoid when:
- Quick branch switch (use
git switchinstead) - Single feature, single branch workflow
The Workflow
Step 1: Check Worktree Status
Before creating a worktree, check what already exists:
# List all worktrees
git worktree list
# Verbose output with branch info
git worktree list --verbose
Step 2: Create Worktree
Basic creation:
# Create worktree with new branch from HEAD
git worktree add ../project-feature-name -b feature-name
# Create from specific base branch
git worktree add ../project-hotfix -b hotfix-critical origin/main
# Create from existing remote branch
git worktree add ../project-review pr-123
Tip: Place worktrees outside the repo directory (e.g., ../project-feature-name) so they aren't tracked by Git.
Recommended configuration (run once):
git config worktree.guessRemote true
git config worktree.useRelativePaths true # Requires Git 2.45+
Step 3: Work in Worktree
Navigate to the worktree and work normally:
cd ../project-feature-name
# Install dependencies, run tests, start Claude, etc.
Worktree Management Reference
These commands are available for managing worktrees. Surface these to the user when relevant:
List worktrees:
# List all worktrees
git worktree list
# Verbose output with branch and commit info
git worktree list --verbose
Remove worktrees:
# Remove a worktree (must have no uncommitted changes)
git worktree remove ../project-feature-name
# Force remove (discards uncommitted changes)
git worktree remove -f ../project-feature-name
Prune stale worktrees:
# Clean up metadata for manually deleted worktrees
git worktree prune
# Dry run to see what would be pruned
git worktree prune -n
# Repair a disconnected worktree
git worktree repair ../project-feature-name
Troubleshooting
"Another worktree already uses this branch"
Cause: Can't checkout same branch in multiple worktrees.
Solution:
# Check which worktree has it
git worktree list | grep branch-name
# Create new branch from same base instead
git worktree add ../new-path -b branch-copy origin/branch-name
"Worktree contains modified or untracked files"
Cause: Can't remove worktree with uncommitted changes.
Solution:
# Commit or stash changes first
cd ../project-feature-name
git add . && git commit -m "Final changes"
# Or force remove (discards changes)
git worktree remove -f ../project-feature-name
Stale Worktree References
Cause: Manually deleted worktree directory without git worktree remove.
Solution:
# List worktrees (shows "prunable" entries)
git worktree list --verbose
# Clean up stale metadata
git worktree prune
Examples
Example 1: Create worktree for new feature
Create worktree with descriptive branch name
git worktree add ../myproject-auth -b feature/auth cd ../myproject-auth
Install dependencies and verify setup
npm install npm test
**Why this is good:** Checks existing worktrees, uses descriptive naming, verifies setup before work.
</Good>
<Bad>
```bash
# Create worktree without checking existing ones
git worktree add ../temp -b temp
cd ../temp
Why this is bad: No verification of existing worktrees, vague naming makes tracking difficult, no setup verification.
Example 2: Emergency hotfix pattern
Fix bug, test, commit
npm test git add . git commit -m "Fix payment processor race condition" git push -u origin hotfix/payment-bug
Return to original work
cd ../myproject git worktree remove ../myproject-hotfix
**Why this is good:** Branches from correct base (main), tests before committing, cleans up after.
</Good>
<Bad>
```bash
# Create hotfix from current feature branch
git worktree add ../fix -b fix
cd ../fix
# Make changes, forget to clean up
Why this is bad: Wrong base branch (includes feature work), vague naming, no cleanup.
Example 3: Review PR without switching
Review and test
npm install npm test
Leave comments, then clean up
cd ../myproject git worktree remove ../myproject-pr-123
**Why this is good:** Fetches PR properly, uses PR number in path, cleans up after review.
</Good>
<Bad>
```bash
# Try to checkout PR in main worktree
git checkout pr-123 # Loses current work
Why this is bad: Switches branch in main worktree, loses current state, forces stashing.
Integration
This skill enables:
- Working on multiple branches simultaneously without context switching
- Running parallel Claude Code sessions (one per worktree)
- Emergency hotfixes without disrupting feature work
- Safe PR review in isolated environments
Pairs with:
- track-session - Create separate SESSION_PROGRESS.md in each worktree to track independent progress
- commit workflows - Each worktree has its own staging area and commits independently
- Parallel Claude sessions - Name each Claude session after its worktree branch for clarity
Integration pattern with track-session:
# Create worktree
git worktree add ../myproject-feature -b feature/new-api
cd ../myproject-feature
# Create independent progress tracking
echo "# Session Progress - New API Feature" > SESSION_PROGRESS.md
# Start Claude session named "myproject - New API Feature"
# Work proceeds with independent progress tracking
Multi-worktree workflow:
# Terminal 1: Feature work in main worktree
cd ~/myproject
# Claude session: "myproject - main"
# Terminal 2: Hotfix in separate worktree
cd ~/myproject-hotfix
# Claude session: "myproject - hotfix"
# Terminal 3: PR review in separate worktree
cd ~/myproject-pr-123
# Claude session: "myproject - PR review"
Best practices:
- Name Claude sessions to match worktree purpose
- Each worktree tracks progress independently
- Use
git worktree listto see all active work - Clean up worktrees when branches are merged