112 lines
2.8 KiB
Markdown
112 lines
2.8 KiB
Markdown
---
|
|
name: using-git-worktrees
|
|
description: 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
|
|
|
|
```bash
|
|
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:**
|
|
|
|
```bash
|
|
git check-ignore -q .worktrees 2>/dev/null
|
|
```
|
|
|
|
**If NOT ignored:** Add to `.gitignore` and commit before proceeding.
|
|
|
|
### 3. Create Worktree
|
|
|
|
```bash
|
|
project=$(basename "$(git rev-parse --show-toplevel)")
|
|
git worktree add .worktrees/$BRANCH_NAME -b $BRANCH_NAME
|
|
cd .worktrees/$BRANCH_NAME
|
|
```
|
|
|
|
### 4. Run Project Setup
|
|
|
|
```bash
|
|
# This is a Node.js project
|
|
if [ -f package.json ]; then
|
|
npm install
|
|
fi
|
|
```
|
|
|
|
### 5. Verify Clean Baseline
|
|
|
|
```bash
|
|
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
|