2.8 KiB

Raw Blame History

name	description
using-git-worktrees	Use when starting feature work that needs isolation from current workspace or before executing implementation plans

Using Git Worktrees

Overview

Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.

Core principle: Systematic directory selection + safety verification = reliable isolation.

Announce at start: "I'm using the using-git-worktrees skill to set up an isolated workspace."

Directory Selection Process

Follow this priority order:

1. Check Existing Directories

ls -d .worktrees 2>/dev/null  # Preferred (hidden)
ls -d worktrees 2>/dev/null    # Alternative

This project already has a .worktrees/ directory — use it.

2. Safety Verification

MUST verify directory is ignored before creating worktree:

git check-ignore -q .worktrees 2>/dev/null

If NOT ignored: Add to .gitignore and commit before proceeding.

3. Create Worktree

project=$(basename "$(git rev-parse --show-toplevel)")
git worktree add .worktrees/$BRANCH_NAME -b $BRANCH_NAME
cd .worktrees/$BRANCH_NAME

4. Run Project Setup

# This is a Node.js project
if [ -f package.json ]; then
  npm install
fi

5. Verify Clean Baseline

npm run test

If tests fail: Report failures, ask whether to proceed or investigate. If tests pass: Report ready.

6. Report Location

Worktree ready at .worktrees/$BRANCH_NAME
Tests passing (X tests, 0 failures)
Ready to implement.

Quick Reference

Situation	Action
`.worktrees/` exists	Use it (verify ignored)
`.worktrees/` not ignored	Add to `.gitignore` + commit first
Tests fail during baseline	Report failures + ask
No package.json	Skip dependency install

Common Mistakes

Skipping ignore verification

Problem: Worktree contents get tracked, pollute git status
Fix: Always use git check-ignore before creating worktree

Proceeding with failing tests

Problem: Can't distinguish new bugs from pre-existing issues
Fix: Report failures, get explicit permission to proceed

Red Flags

Never:

Create worktree without verifying it's ignored
Skip baseline test verification
Proceed with failing tests without asking

Always:

Verify directory is ignored
Auto-detect and run project setup (npm install)
Verify clean test baseline

Integration

Called by:

brainstorming — REQUIRED when design is approved and implementation follows
subagent-driven-development — REQUIRED before executing any tasks
executing-plans — REQUIRED before executing any tasks

Pairs with:

finishing-a-development-branch — REQUIRED for cleanup after work complete

2.8 KiB Raw Blame History