Git Worktrees

Guidance for isolated Git worktree workflows and parallel branch development.

SKILL.md

GitHub

Git Worktrees

Isolated development environments. Parallel work without branch switching. Clean separation.

Triggers

  • Need to work on multiple features simultaneously
  • Subagent work that modifies overlapping files
  • Experimental changes that should not touch the main working directory
  • Running tests on one branch while developing on another
  • Agent isolation via EnterWorktree / ExitWorktree tools

When to Use Worktrees vs Branches

Scenario Use
Sequential feature work Branch (simpler)
Parallel feature work Worktree (isolated)
Quick hotfix while mid-feature Worktree (no stash needed)
Subagent isolation Worktree (via isolation: "worktree" on Agent tool)
Spike/experiment alongside main work Worktree (disposable)
Code review while developing Worktree (separate checkout)

Worktree Workflow

Creating a Worktree

# Create a worktree for a new branch
git worktree add ../project-feature-name -b feature/feature-name

# Create a worktree for an existing branch
git worktree add ../project-hotfix hotfix/urgent-fix

# List active worktrees
git worktree list

Directory naming: Use ../<project>-<purpose> to keep worktrees adjacent to the main repo.

Working in a Worktree

# Each worktree is a full checkout — cd into it and work normally
cd ../project-feature-name
# Run tests, edit files, commit — all isolated from main worktree

# Install dependencies if needed (they're NOT shared)
npm install  # or pip install -r requirements.txt, etc.

Cleaning Up

# When done with a worktree
cd /path/to/main/repo
git worktree remove ../project-feature-name

# Prune stale worktree references
git worktree prune

Agent Tool Integration

When spawning subagents, use isolation: "worktree" to give each agent its own copy:

Agent tool parameters:
  isolation: "worktree"
  prompt: "Implement feature X in the isolated worktree..."

The worktree is automatically cleaned up if the agent makes no changes. If changes are made, the worktree path and branch are returned in the result.

Baseline Verification

After creating a worktree, always verify the baseline:

# Ensure tests pass in the clean worktree before making changes
cd ../project-worktree
# Run the project's test suite
# If tests fail here, the problem is pre-existing — do not mask it

Dependency Detection

Some worktrees need dependency installation:

Project Type Check For Install Command
Node.js package.json npm install or bun install
Python requirements.txt / pyproject.toml pip install -r requirements.txt or uv sync
Rust Cargo.toml cargo build
Go go.mod go mod download

Rules

  1. Never delete worktrees with uncommitted changes — commit or stash first
  2. Never checkout the same branch in multiple worktrees
  3. Always clean up worktrees when done to avoid disk bloat
  4. Always verify baseline tests pass before starting work