git-worktree - SKILL.md Agent Skill

name: git-worktree description: Manage Git worktrees for isolated parallel development without branch switching

Git Worktree Skill

Manage isolated development environments using Git worktrees.

When to Use

Working on multiple features simultaneously
Need to review a PR while working on something else
Testing changes without affecting your main workspace
Running long builds while continuing development

Quick Commands

Create worktree for a new branch

git worktree add ../feature-xyz -b feature/xyz

Create worktree for existing branch

git worktree add ../pr-review origin/pr-branch

List all worktrees

git worktree list

Remove worktree

git worktree remove ../feature-xyz

Clean up stale worktrees

git worktree prune

Workflow Patterns

Pattern 1: Feature Development

# Create isolated workspace for new feature
git worktree add ../my-feature -b feature/new-thing

# Work in the new worktree
cd ../my-feature

# When done, merge and cleanup
git checkout main
git merge feature/new-thing
git worktree remove ../my-feature
git branch -d feature/new-thing

Pattern 2: PR Review

# Create worktree for PR review without switching branches
git fetch origin pull/123/head:pr-123
git worktree add ../pr-123-review pr-123

# Review in separate directory
cd ../pr-123-review
go test ./...

# Cleanup after review
git worktree remove ../pr-123-review
git branch -D pr-123

Pattern 3: Hotfix While Working

# You're working on feature, need to fix prod bug
git worktree add ../hotfix -b hotfix/urgent-fix origin/main

# Fix bug in hotfix worktree
cd ../hotfix
# ... make fixes ...
git commit -am "fix: urgent bug"
git push origin hotfix/urgent-fix

# Return to feature work
cd ../my-feature

Directory Convention

~/code/
├── celestia-app/           # Main worktree (main branch)
├── celestia-app-feature/   # Feature worktree
├── celestia-app-hotfix/    # Hotfix worktree
└── celestia-app-review/    # PR review worktree

Best Practices

Naming: Use descriptive directory names matching the branch
Location: Keep worktrees as siblings to main repo
Cleanup: Remove worktrees when done to avoid clutter
Prune: Run git worktree prune periodically

Common Issues

"fatal: is already checked out"

The branch is already checked out in another worktree. Use a different branch or remove the existing worktree.

Stale worktrees after deletion

Run git worktree prune to clean up references to deleted worktree directories.

Submodules not initialized

Run git submodule update --init in the new worktree.