using-git-worktrees

Using Git Worktrees

Why Worktrees

A worktree is a second checkout of the same repo in a separate directory. Each worktree has its own working tree and HEAD, but shares the git object store. This means:

• Subagents work in isolation — no interference with your main session
• You can switch tasks without stashing
• Parallel features develop independently
• Clean rollback: abandon the worktree, nothing pollutes main

When to Use

Use at the START of every feature or bug fix. Do NOT start implementation until a clean worktree exists or you've confirmed you're already in one.

Mandatory before:

• subagent-driven-development skill
• executing-plans skill
• Any work touching more than one file

The Process

Step 1: Detect Existing Isolation

First check — are you already isolated?

# Check if current directory is a worktree (not the main checkout)
git worktree list
pwd

If you're already in a worktree for this feature: proceed to Step 3 (verify clean baseline). If you're in the main checkout: proceed to Step 2.

Step 2: Create the Worktree

# Create worktree + new branch in one command
git worktree add ../worktrees/<feature-name> -b feat/<feature-name>

# Examples:
git worktree add ../worktrees/stripe-billing -b feat/stripe-billing
git worktree add ../worktrees/fix-auth-bug -b fix/auth-token-expiry

The worktree is created at ../worktrees/<feature-name> (sibling of the project root). If the project uses .claude/worktrees/, use that path instead:

git worktree add .claude/worktrees/<feature-name> -b feat/<feature-name>

Step 3: Verify Clean Baseline

Move into the worktree and confirm it starts clean:

cd ../worktrees/<feature-name>   # or .claude/worktrees/<feature-name>
git status                        # Should show: "nothing to commit"
git log --oneline -3              # Confirm you branched from the right point

If status shows unexpected changes: something is wrong — investigate before proceeding.

Step 4: Run Project Setup

Install dependencies and confirm the baseline builds:

npm install          # or pip install -r requirements.txt / go mod download
npm run build        # Confirm baseline build passes BEFORE any changes
npm test             # Confirm baseline tests pass BEFORE any changes

If baseline build or tests fail: STOP. Fix the issue on main first, then recreate the worktree.

Step 5: Proceed with Work

Now development starts. The worktree is isolated, the baseline is confirmed clean.

Cleanup After Work Completes

After the branch is merged or abandoned:

# From the main checkout (not from inside the worktree)
git worktree remove ../worktrees/<feature-name>
git branch -d feat/<feature-name>   # Only after merge

Common Issues

Issue	Fix
"already checked out" error	The branch exists in another worktree — use a different branch name
Worktree has unexpected changes	Run git status to investigate; never force-remove with uncommitted work
Setup script fails in worktree	Check for absolute paths in scripts; worktrees use different working directories
Submodules not initialized	Run git submodule update --init --recursive in the new worktree

Worktree vs Branch Checkout

	git worktree	git checkout -b
Main session disrupted	No	Yes
Parallel work possible	Yes	No
Independent node_modules	Yes (separate dir)	Shared
Subagent isolation	Clean	Risk of contamination

Always use worktrees for subagent work. The isolation is the point.