# Lerianstudio Ring Using Git Worktrees > Using Git Worktrees - Skill: `tomevault-io/lerianstudio-ring-using-git-worktrees` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/lerianstudio-ring-using-git-worktrees` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/lerianstudio-ring-using-git-worktrees/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/lerianstudio-ring-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 ring:using-git-worktrees skill to set up an isolated workspace." ## Directory Selection Process **Priority order:** (1) Existing `.worktrees/` or `worktrees/` (2) CLAUDE.md preference (3) Ask user ```bash ls -d .worktrees worktrees 2>/dev/null # Check existing (prefer .worktrees) grep -i "worktree.*director" CLAUDE.md # Check project preference ``` **If none found, ask:** `.worktrees/` (project-local, hidden) OR `~/.config/ring/worktrees//` (global) ## Safety Verification **Project-local directories:** MUST verify .gitignore before creating: `grep -q "^\.worktrees/$\|^worktrees/$" .gitignore` - If NOT in .gitignore: Add it → commit → proceed (fix broken things immediately) - **Why critical:** Prevents accidentally committing worktree contents **Global directory (~/.config/ring/worktrees):** No verification needed - outside project. ## Creation Steps ```bash # 1. Detect project project=$(basename "$(git rev-parse --show-toplevel)") # 2. Create worktree (path = $LOCATION/$BRANCH or ~/.config/ring/worktrees/$project/$BRANCH) git worktree add "$path" -b "$BRANCH_NAME" && cd "$path" # 3. Auto-detect and run setup [ -f package.json ] && npm install [ -f Cargo.toml ] && cargo build [ -f requirements.txt ] && pip install -r requirements.txt [ -f pyproject.toml ] && poetry install [ -f go.mod ] && go mod download # 4. Verify clean baseline (npm test / cargo test / pytest / go test ./...) ``` **If tests fail:** Report failures, ask whether to proceed or investigate. **If tests pass:** Report: `Worktree ready at | Tests passing ( tests) | 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 | Mistake | Problem | Fix | |---------|---------|-----| | Skip .gitignore verification | Worktree contents tracked, pollute git status | Always grep .gitignore first | | Assuming directory location | Inconsistency, violates conventions | Follow priority: existing > CLAUDE.md > ask | | Proceeding with failing tests | Can't distinguish new vs pre-existing bugs | Report failures, get permission | | Hardcoding setup commands | Breaks on different tools | Auto-detect from project files | ## Example Workflow Announce → Check `.worktrees/` exists → Verify .gitignore → `git worktree add .worktrees/auth -b feature/auth` → `npm install` → `npm test` (47 passing) → Report ready ## 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 - **ring:executing-plans** or **ring:subagent-driven-development** - Work happens in this worktree ## Blocker Criteria STOP and report if: | Decision Type | Blocker Condition | Required Action | |---|---|---| | .gitignore Safety | Project-local worktree directory not in .gitignore | STOP and report | | Baseline Tests | Tests fail during worktree setup | STOP and report | | Directory Ambiguity | Multiple conflicting worktree locations exist | STOP and report | | Permission Issues | Cannot create worktree in target directory | STOP and report | ### Cannot Be Overridden The following requirements CANNOT be waived: - Project-local worktree directories MUST be in .gitignore before creation - Baseline test verification is REQUIRED before proceeding with work - Directory selection MUST follow priority order: existing > CLAUDE.md > ask user - Worktree creation MUST include dependency installation and test verification ## Severity Calibration | Severity | Condition | Required Action | |---|---|---| | CRITICAL | Worktree directory not in .gitignore (project-local) | MUST add to .gitignore immediately | | CRITICAL | Proceeding with failing baseline tests | MUST report failures and get permission | | HIGH | Skipping dependency installation step | MUST run appropriate package manager | | HIGH | Assuming directory location when ambiguous | MUST follow priority order or ask user | | MEDIUM | Missing CLAUDE.md check in priority order | Should check CLAUDE.md preferences | | LOW | Not auto-detecting project type | Fix in next iteration | ## Pressure Resistance | User Says | Your Response | |---|---| | "Skip .gitignore check, just create the worktree" | "CANNOT skip .gitignore verification for project-local directories. Worktree contents would pollute git status." | | "Tests are failing but proceed anyway" | "CANNOT proceed with failing baseline tests. I need to report failures so we can distinguish pre-existing bugs from new ones." | | "Put the worktree in this custom location" | "I'll verify that location doesn't conflict with existing conventions and check .gitignore requirements first." | | "Skip dependency installation, it takes too long" | "CANNOT skip dependency installation. Tests won't run correctly without dependencies, invalidating baseline verification." | ## Anti-Rationalization Table | Rationalization | Why It's WRONG | Required Action | |---|---|---| | ".gitignore check is paranoia" | Without it, worktree contents get tracked, polluting every git status. | **MUST verify .gitignore first** | | "I know where worktrees go in this project" | Assumption conflicts with existing directories or CLAUDE.md preferences. | **MUST follow directory priority order** | | "Failing tests are probably unrelated" | You cannot distinguish new vs pre-existing bugs without clean baseline. | **MUST report failures and ask before proceeding** | | "Setup is straightforward, skip auto-detection" | Different projects use different tools. Manual setup misses dependencies. | **MUST auto-detect from project files** | | "Global directory doesn't need verification" | Global directories don't need .gitignore verification - this is correct. Only project-local needs it. | **MUST distinguish global vs project-local** | --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/lerianstudio) — claim your Tome and manage your conversions.