--- name: git-worktrees-c9d890f8c0fb description: 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 --- # 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 ls -d .worktrees 2>/dev/null # Preferred (hidden) ls -d worktrees 2>/dev/null # Alternative ``` **If found:** Use that directory. If both exist, `.worktrees` wins. ### 2. Check CLAUDE.md ```bash grep -i "worktree.*director" CLAUDE.md 2>/dev/null ``` **If preference specified:** Use it without asking. ### 3. Ask User If no directory exists and no CLAUDE.md preference: ``` No worktree directory found. Where should I create worktrees? 1. .worktrees/ (project-local, hidden) 2. ~/.config/superpowers/worktrees// (global location) Which would you prefer? ``` ## Safety Verification ### For Project-Local Directories (.worktrees or worktrees) **MUST verify .gitignore before creating worktree:** ```bash # Check if directory pattern in .gitignore grep -q "^\.worktrees/$" .gitignore || grep -q "^worktrees/$" .gitignore ``` **If NOT in .gitignore:** Per Jesse's rule "Fix broken things immediately": 1. Add appropriate line to .gitignore 2. Commit the change 3. Proceed with worktree creation **Why critical:** Prevents accidentally committing worktree contents to repository. ### For Global Directory (~/.config/superpowers/worktrees) No .gitignore verification needed - outside project entirely. ## Creation Steps ### 1. Detect Project Name ```bash project=$(basename "$(git rev-parse --show-toplevel)") ``` ### 2. Create Worktree ```bash # Determine full path case $LOCATION in .worktrees|worktrees) path="$LOCATION/$BRANCH_NAME" ;; ~/.config/superpowers/worktrees/*) path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME" ;; esac # Create worktree with new branch git worktree add "$path" -b "$BRANCH_NAME" cd "$path" ``` ### 3. Run Project Setup Auto-detect and run appropriate setup: ```bash # Node.js if [ -f package.json ]; then npm install; fi # Rust if [ -f Cargo.toml ]; then cargo build; fi # Python if [ -f requirements.txt ]; then pip install -r requirements.txt; fi if [ -f pyproject.toml ]; then poetry install; fi # Go if [ -f go.mod ]; then go mod download; fi ``` ### 4. Verify Clean Baseline Run tests to ensure worktree starts clean: ```bash # Examples - use project-appropriate command npm test cargo test pytest go test ./... ``` **If tests fail:** Report failures, ask whether to proceed or investigate. **If tests pass:** Report ready. ### 5. Report Location ``` Worktree ready at Tests passing ( tests, 0 failures) Ready to implement ``` ## Quick Reference | Situation | Action | |-----------|--------| | `.worktrees/` exists | Use it (verify .gitignore) | | `worktrees/` exists | Use it (verify .gitignore) | | Both exist | Use `.worktrees/` | | Neither exists | Check CLAUDE.md → Ask user | | Directory not in .gitignore | Add it immediately + commit | | Tests fail during baseline | Report failures + ask | | No package.json/Cargo.toml | Skip dependency install | ## Common Mistakes **Skipping .gitignore verification** - **Problem:** Worktree contents get tracked, pollute git status - **Fix:** Always grep .gitignore before creating project-local worktree **Assuming directory location** - **Problem:** Creates inconsistency, violates project conventions - **Fix:** Follow priority: existing > CLAUDE.md > 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 .gitignore - contains .worktrees/] [Create worktree: git worktree add .worktrees/auth -b feature/auth] [Run npm install] [Run npm test - 47 passing] Worktree ready at /Users/jesse/myproject/.worktrees/auth Tests passing (47 tests, 0 failures) Ready to implement auth feature ``` ## Red Flags **Never:** - Create worktree without .gitignore verification (project-local) - Skip baseline test verification - Proceed with failing tests without asking - Assume directory location when ambiguous - Skip CLAUDE.md check **Always:** - Follow directory priority: existing > CLAUDE.md > ask - Verify .gitignore for project-local - Auto-detect and run project setup - Verify clean test baseline ## Integration **Called by:** - **brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows - Any skill needing isolated workspace **Pairs with:** - **finishing-a-development-branch** - REQUIRED for cleanup after work complete - **executing-plans** or **subagent-driven-development** - Work happens in this worktree --- Source attribution: zach-source Original project: https://github.com/zach-source/claude-plugins/blob/61adbbc283466a1755a493153bfe79e7df2bdf77/plugins/git-tools/skills/git-worktrees/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2025 Zach Taylor Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: zach-source Original project: https://github.com/zach-source/claude-plugins/blob/61adbbc283466a1755a493153bfe79e7df2bdf77/plugins/git-tools/skills/git-worktrees/SKILL.md Attribution basis: Source repository record Fields of work: Content & Media, Development & Engineering Roles: Backend Developer, DevOps / SRE, Frontend Developer, Full-Stack Developer, Technical Writer Specialties: Git Tools: Tool not specified Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: a35dd31a3831f2f9ca6e1beef6902cf8e3720ac89e4ff7714bb1052b766959aa