davila7--claude-code-templates
wehub-resource-sync
1 行
5.7 KiB
JSON
1 行
5.7 KiB
JSON
{"content": "---\nname: using-git-worktrees\ndescription: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification\n---\n\n# Using Git Worktrees\n\n## Overview\n\nGit worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.\n\n**Core principle:** Systematic directory selection + safety verification = reliable isolation.\n\n**Announce at start:** \"I'm using the using-git-worktrees skill to set up an isolated workspace.\"\n\n## Directory Selection Process\n\nFollow this priority order:\n\n### 1. Check Existing Directories\n\n```bash\n# Check in priority order\nls -d .worktrees 2>/dev/null # Preferred (hidden)\nls -d worktrees 2>/dev/null # Alternative\n```\n\n**If found:** Use that directory. If both exist, `.worktrees` wins.\n\n### 2. Check CLAUDE.md\n\n```bash\ngrep -i \"worktree.*director\" CLAUDE.md 2>/dev/null\n```\n\n**If preference specified:** Use it without asking.\n\n### 3. Ask User\n\nIf no directory exists and no CLAUDE.md preference:\n\n```\nNo worktree directory found. Where should I create worktrees?\n\n1. .worktrees/ (project-local, hidden)\n2. ~/.config/superpowers/worktrees/<project-name>/ (global location)\n\nWhich would you prefer?\n```\n\n## Safety Verification\n\n### For Project-Local Directories (.worktrees or worktrees)\n\n**MUST verify directory is ignored before creating worktree:**\n\n```bash\n# Check if directory is ignored (respects local, global, and system gitignore)\ngit check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null\n```\n\n**If NOT ignored:**\n\nPer Jesse's rule \"Fix broken things immediately\":\n1. Add appropriate line to .gitignore\n2. Commit the change\n3. Proceed with worktree creation\n\n**Why critical:** Prevents accidentally committing worktree contents to repository.\n\n### For Global Directory (~/.config/superpowers/worktrees)\n\nNo .gitignore verification needed - outside project entirely.\n\n## Creation Steps\n\n### 1. Detect Project Name\n\n```bash\nproject=$(basename \"$(git rev-parse --show-toplevel)\")\n```\n\n### 2. Create Worktree\n\n```bash\n# Determine full path\ncase $LOCATION in\n .worktrees|worktrees)\n path=\"$LOCATION/$BRANCH_NAME\"\n ;;\n ~/.config/superpowers/worktrees/*)\n path=\"~/.config/superpowers/worktrees/$project/$BRANCH_NAME\"\n ;;\nesac\n\n# Create worktree with new branch\ngit worktree add \"$path\" -b \"$BRANCH_NAME\"\ncd \"$path\"\n```\n\n### 3. Run Project Setup\n\nAuto-detect and run appropriate setup:\n\n```bash\n# Node.js\nif [ -f package.json ]; then npm install; fi\n\n# Rust\nif [ -f Cargo.toml ]; then cargo build; fi\n\n# Python\nif [ -f requirements.txt ]; then pip install -r requirements.txt; fi\nif [ -f pyproject.toml ]; then poetry install; fi\n\n# Go\nif [ -f go.mod ]; then go mod download; fi\n```\n\n### 4. Verify Clean Baseline\n\nRun tests to ensure worktree starts clean:\n\n```bash\n# Examples - use project-appropriate command\nnpm test\ncargo test\npytest\ngo test ./...\n```\n\n**If tests fail:** Report failures, ask whether to proceed or investigate.\n\n**If tests pass:** Report ready.\n\n### 5. Report Location\n\n```\nWorktree ready at <full-path>\nTests passing (<N> tests, 0 failures)\nReady to implement <feature-name>\n```\n\n## Quick Reference\n\n| Situation | Action |\n|-----------|--------|\n| `.worktrees/` exists | Use it (verify ignored) |\n| `worktrees/` exists | Use it (verify ignored) |\n| Both exist | Use `.worktrees/` |\n| Neither exists | Check CLAUDE.md → Ask user |\n| Directory not ignored | Add to .gitignore + commit |\n| Tests fail during baseline | Report failures + ask |\n| No package.json/Cargo.toml | Skip dependency install |\n\n## Common Mistakes\n\n### Skipping ignore verification\n\n- **Problem:** Worktree contents get tracked, pollute git status\n- **Fix:** Always use `git check-ignore` before creating project-local worktree\n\n### Assuming directory location\n\n- **Problem:** Creates inconsistency, violates project conventions\n- **Fix:** Follow priority: existing > CLAUDE.md > ask\n\n### Proceeding with failing tests\n\n- **Problem:** Can't distinguish new bugs from pre-existing issues\n- **Fix:** Report failures, get explicit permission to proceed\n\n### Hardcoding setup commands\n\n- **Problem:** Breaks on projects using different tools\n- **Fix:** Auto-detect from project files (package.json, etc.)\n\n## Example Workflow\n\n```\nYou: I'm using the using-git-worktrees skill to set up an isolated workspace.\n\n[Check .worktrees/ - exists]\n[Verify ignored - git check-ignore confirms .worktrees/ is ignored]\n[Create worktree: git worktree add .worktrees/auth -b feature/auth]\n[Run npm install]\n[Run npm test - 47 passing]\n\nWorktree ready at /Users/jesse/myproject/.worktrees/auth\nTests passing (47 tests, 0 failures)\nReady to implement auth feature\n```\n\n## Red Flags\n\n**Never:**\n- Create worktree without verifying it's ignored (project-local)\n- Skip baseline test verification\n- Proceed with failing tests without asking\n- Assume directory location when ambiguous\n- Skip CLAUDE.md check\n\n**Always:**\n- Follow directory priority: existing > CLAUDE.md > ask\n- Verify directory is ignored for project-local\n- Auto-detect and run project setup\n- Verify clean test baseline\n\n## Integration\n\n**Called by:**\n- **brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows\n- Any skill needing isolated workspace\n\n**Pairs with:**\n- **finishing-a-development-branch** - REQUIRED for cleanup after work complete\n- **executing-plans** or **subagent-driven-development** - Work happens in this worktree\n"} |