SuperAPI AI Directory

using-git-worktrees

Coding & development

View repository

Updated 10-16 07:26

About this skill

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.