Agent skill
git-worktrees
Master Git worktrees for parallel development, PR reviews, and experiments. Create isolated working directories for multiple branches simultaneously. Use when working on multiple branches at once, reviewing PRs, or running experiments without affecting main work. Triggers on worktree, parallel development, multiple branches, PR review isolation, experiment branch, feature isolation.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/git-worktrees
SKILL.md
Git Worktrees
Work on multiple branches simultaneously without stashing or switching.
Quick Reference
Core Commands
| Action | Command |
|---|---|
| List worktrees | git worktree list |
| Add worktree | git worktree add ../path branch |
| Add new branch | git worktree add -b new-branch ../path |
| Remove worktree | git worktree remove ../path |
| Prune stale | git worktree prune |
| Lock worktree | git worktree lock ../path |
Key Concepts
What is a Worktree?
main-repo/ # Main worktree (default)
+-- .git/ # Shared Git database
+-- src/
+-- ...
../main-repo-feature-auth/ # Linked worktree
+-- .git --> main-repo/.git # Points to main .git
+-- src/ # Independent working files
+-- ...
Benefits
| Benefit | Description |
|---|---|
| No stashing | Keep uncommitted work while switching context |
| Parallel work | Work on multiple features simultaneously |
| Clean reviews | Review PRs in isolated directories |
| Experiments | Try things without affecting main work |
| Fast switching | Just cd to another directory |
Common Workflows
1. Parallel Feature Development
# You're working on feature A
cd ~/repos/my-project
git checkout feature-a
# ... making changes ...
# Urgent: Need to work on feature B
git worktree add ../my-project-feature-b feature-b
# Work on feature B in the new directory
cd ../my-project-feature-b
# ... make changes, commit ...
# Go back to feature A - your work is still there!
cd ../my-project
2. PR Review in Isolation
# Fetch the PR
git fetch origin pull/123/head:pr-123
# Create worktree for review
git worktree add ../project-pr-123 pr-123
# Review in the isolated worktree
cd ../project-pr-123
npm install && npm test
# Back to your work
cd ../project
# Clean up after review
git worktree remove ../project-pr-123
git branch -d pr-123
3. Long-running Experiments
# Create experiment worktree
git worktree add -b experiment/new-architecture ../project-experiment
# Work on experiment over days/weeks
cd ../project-experiment
# Lock it to prevent accidental deletion
git worktree lock ../project-experiment
# Continue normal work in main repo
cd ../project
4. Hotfix While Mid-Feature
# Mid-feature, need to hotfix
git worktree add ../project-hotfix main
cd ../project-hotfix
git checkout -b hotfix/critical-bug
# Fix, test, push
git add . && git commit -m "fix: critical bug"
git push origin hotfix/critical-bug
# Clean up and return
cd ../project
git worktree remove ../project-hotfix
Naming Convention
Recommended worktree directory naming:
{repo-name}-{purpose}/
Examples:
my-app-feature-auth/- Feature workmy-app-pr-123/- PR reviewmy-app-experiment-v2/- Experimental workmy-app-hotfix/- Hotfix branch
Best Practices
DO
- Use descriptive directory names
- Clean up worktrees after use
- Lock long-running worktrees
- Run
git worktree pruneperiodically - Keep worktrees in sibling directories
DON'T
- Create worktrees inside the main repo
- Delete worktree directories manually (use
git worktree remove) - Forget to install dependencies in each worktree
- Have too many worktrees (they take disk space)
- Share node_modules between worktrees
IDE Integration
VS Code
Open each worktree as a separate window:
cd ../project-feature-b
code .
Or use Multi-root Workspaces to see all worktrees.
Troubleshooting
| Issue | Solution |
|---|---|
| "branch already checked out" | That branch is in another worktree |
| "not a git repository" | Worktree was moved/deleted incorrectly |
| Stale worktree entries | Run git worktree prune |
| Can't delete worktree | git worktree unlock first if locked |
| Missing dependencies | Run install in each worktree |
When to Use This Skill
- Working on multiple features simultaneously
- Reviewing pull requests without disrupting work
- Running long-term experiments
- Handling urgent hotfixes mid-feature
- Testing different branches side by side
- Comparing code across branches
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?