using-git-worktrees

# 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 # Check in priority order (PowerShell) Test-Path .worktrees # Preferred (hidden) Test-Path worktrees # Alternative ``` **If found:** Use that directory. If both exist, `.worktrees` wins. ### 2. Ask User If no directory exists: ``` No worktree directory found. Where should I create worktrees? 1. .worktrees/ (project-local, hidden) 2. worktrees/ (project-local, visible) Which would you prefer? ``` ## Safety Verification ### For Project-Local Directories (.worktrees or worktrees) **MUST verify directory is ignored before creating worktree:** ```bash # Check if directory is ignored git check-ignore -q .worktrees ``` **If NOT ignored:** 1. Add appropriate line to .gitignore 2. Commit the change 3. Proceed with worktree creation **Why critical:** Prevents accidentally committing worktree contents to repository. ## Creation Steps ### 1. Detect Project Name ```bash $project = Split-Path -Leaf (git rev-parse --show-toplevel) ``` ### 2. Create Worktree ```bash # Create worktree with new branch git worktree add ".worktrees/$BRANCH_NAME" -b "$BRANCH_NAME" cd ".worktrees/$BRANCH_NAME" ``` ### 3. Run Project Setup Auto-detect and run appropriate setup: ```bash # Node.js if (Test-Path package.json) { npm install } # Python if (Test-Path requirements.txt) { pip install -r requirements.txt } if (Test-Path pyproject.toml) { poetry install } ``` ### 4. Verify Clean Baseline Run tests to ensure worktree starts clean: ```bash npm test ``` **If tests fail:** Report failures, ask whether to proceed or investigate. **If tests pass:** Report ready. ### 5. Report Location ``` Worktree ready at <full-path> Tests passing (<N> tests, 0 failures) Ready to implement <feature-name> ``` ## Quick Reference | Situation | Action | |-----------|--------| | `.worktrees/` exists | Use it (verify ignored) | | `worktrees/` exists | Use it (verify ignored) | | Both exist | Use `.worktrees/` | | Neither exists | Ask user | | Directory not ignored | Add to .gitignore + commit | | 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 project-local worktree ### Assuming directory location - **Problem:** Creates inconsistency, violates project conventions - **Fix:** Follow priority: existing > ask ### Proceeding with failing tests - **Problem:** Can't distinguish new bugs from pre-existing issues - **Fix:** Report failures, get explicit permission to proceed ### Hardcoding setup commands - **Problem:** Breaks on projects using different tools - **Fix:** Auto-detect from project files (package.json, etc.) ## Example Workflow ``` You: I'm using the using-git-worktrees skill to set up an isolated workspace. [Check .worktrees/ - exists] [Verify ignored - git check-ignore confirms .worktrees/ is ignored] [Create worktree: git worktree add .worktrees/auth -b feature/auth] [Run npm install] [Run npm test - 47 passing] Worktree ready at C:\project\.worktrees\auth Tests passing (47 tests, 0 failures) Ready to implement auth feature ``` ## Red Flags **Never:** - Create worktree without verifying it's ignored (project-local) - Skip baseline test verification - Proceed with failing tests without asking - Assume directory location when ambiguous - Skip ignore verification **Always:** - Follow directory priority: existing > ask - Verify directory is ignored for project-local - Auto-detect and run project setup - Verify clean test baseline ## Integration **Called by:** - **brainstorming** - When design is approved and implementation follows **Pairs with:** - **finishing-a-development-branch** - Cleanup after work complete - **executing-plans** or **subagent-driven-development** - Work happens in this worktree