using-git-worktrees · diff
git:20260723.88b8ec9 to git:20260731.818d42f
65 added, 175 removed. Audit A to A.
---
name: using-git-worktrees
- description: "Use when starting feature work that needs isolation from the current workspace, or when an implementation plan should run outside the active working tree."
+ description: "Use when a coding task needs a concurrent checkout, unrelated dirty state blocks safe branch switching, or the user or repository explicitly requires a worktree."
---
# 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/aegis/worktrees/<project-name>/ (global location)
-
- 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 (respects local, global, and system gitignore)
- git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
- ```
-
- **If NOT ignored:**
-
- 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.
+ A worktree is an exception for simultaneously checking out another Git history,
+ not a general safety badge. Prefer the current workspace and reuse an existing
+ suitable worktree. A branch decision and a worktree decision are separate.
- ### For Global Directory (~/.config/aegis/worktrees)
+ **Core principle:** create only with necessity and ownership evidence; pair every
+ created worktree with a cleanup path.
- No .gitignore verification needed - outside project entirely.
+ **Announce at start:** explain which concrete checkout conflict requires a
+ worktree.
- ## Creation Steps
+ ## Step 0: Environment Detection
- ### 1. Detect Project Name
+ Before mutation, record the repository root, `HEAD`, branch/detached state,
+ staged/unstaged/untracked paths, active Git operations, and:
```bash
- project=$(basename "$(git rev-parse --show-toplevel)")
+ git worktree list --porcelain
```
- ### 2. Create Worktree
-
- ```bash
- # Determine full path
- case $LOCATION in
- .worktrees|worktrees)
- path="$LOCATION/$BRANCH_NAME"
- ;;
- ~/.config/aegis/worktrees/*)
- path="~/.config/aegis/worktrees/$project/$BRANCH_NAME"
- ;;
- esac
+ Stop on detached HEAD, unresolved conflicts, or an active merge/rebase/
+ cherry-pick/revert/bisect. Preserve user state: no automatic stash, reset,
+ clean, broad staging, or commit.
- # Create worktree with new branch
- git worktree add "$path" -b "$BRANCH_NAME"
- cd "$path"
- ```
+ ## Step 1: Necessity Decision
- ### 3. Run Project Setup
+ Create at most one task-owned worktree only when one of these is true:
- Auto-detect and run appropriate setup:
+ - another branch must remain checked out while this task proceeds;
+ - unrelated dirty state prevents a safe checkout in the current workspace;
+ - explicit user or current repository authority requires it.
- ```bash
- # Node.js
- if [ -f package.json ]; then npm install; fi
+ Task complexity, planning, TDD, use of subagents, or a `main`/`master` branch
+ name is not sufficient. Same-task subagents share one workspace; do not create
+ per-subagent or nested worktrees. If independent history is unnecessary, do not
+ create a branch either.
- # Rust
- if [ -f Cargo.toml ]; then cargo build; fi
+ Record: reason, branch, exact path, creating coordinator, and expected cleanup
+ event. If the owner or cleanup condition is unknown, stop before creation.
- # Python
- if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
- if [ -f pyproject.toml ]; then poetry install; fi
+ ## Step 2: Safe Placement
- # Go
- if [ -f go.mod ]; then go mod download; fi
- ```
+ Use an existing repository convention only when the target directory is already
+ ignored (`git check-ignore`). Never edit or commit `.gitignore` solely to host a
+ worktree. If no safe in-repo convention exists, use a task-specific external
+ user-level temporary directory outside the repository. Resolve and verify the
+ exact path before creation; do not target a broad home, workspace, or repo root.
- ### 4. Verify Clean Baseline
+ ## Step 3: Create the Minimum Checkout
- Run tests to ensure worktree starts clean:
+ Prefer reusing an existing branch carrying the same goal. Create a branch only
+ when the approved Git lifecycle requires independent history.
```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
+ # Existing branch
+ git worktree add <exact-path> <branch>
- ```
- Worktree ready at <full-path>
- Tests passing (<N> tests, 0 failures)
- Ready to implement <feature-name>
+ # New independently justified branch
+ git worktree add -b <branch> <exact-path> <start-point>
```
- ## Quick Reference
-
- | Situation | Action |
- |-----------|--------|
- | `.worktrees/` exists | Use it (verify ignored) |
- | `worktrees/` exists | Use it (verify ignored) |
- | Both exist | Use `.worktrees/` |
- | Neither exists | Check CLAUDE.md → Ask user |
- | Directory not ignored | Add to .gitignore + commit |
- | Tests fail during baseline | Report failures + ask |
- | No package.json/Cargo.toml | 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 > 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
+ Read back `git worktree list --porcelain`, the new worktree's `HEAD`/branch, and
+ its status. Do not use force flags.
- ### Hardcoding setup commands
+ ## Step 4: Authority-Led Setup and Baseline
- - **Problem:** Breaks on projects using different tools
- - **Fix:** Auto-detect from project files (package.json, etc.)
+ Read the project's agent guide, install docs, lockfiles, and existing scripts.
+ Run only setup the project explicitly requires. Do not infer `npm install`,
+ `cargo build`, `pip install`, `poetry install`, or dependency downloads merely
+ from manifest presence.
- ## Example Workflow
+ Run the smallest relevant baseline verification. If setup or tests fail, report
+ the exact failure and preserve the worktree; do not hide it by mutating unrelated
+ files.
- ```
- You: I'm using the using-git-worktrees skill to set up an isolated workspace.
+ ## Step 5: Handoff and Cleanup Ownership
- [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]
+ Report the exact path, branch, start `HEAD`, baseline result, owner, and cleanup
+ trigger. The creating coordinator remains responsible until it proves cleanup
+ or explicitly hands ownership off.
- Worktree ready at /Users/jesse/myproject/.worktrees/auth
- Tests passing (47 tests, 0 failures)
- Ready to implement auth feature
- ```
+ Use `finishing-a-development-branch` after the task commit or integration
+ decision. A worktree may usually be removed while its unmerged branch remains;
+ an open PR does not require a permanent checkout.
## 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 CLAUDE.md check
+ Never:
- **Always:**
- - Follow directory priority: existing > CLAUDE.md > ask
- - Verify directory is ignored for project-local
- - Auto-detect and run project setup
- - Verify clean test baseline
+ - create a worktree only because a task modifies code;
+ - modify `.gitignore` merely to make worktree creation possible;
+ - install dependencies blindly;
+ - create one worktree per subagent;
+ - run global prune or force cleanup as routine hygiene;
+ - remove dirty, untracked, locked, user-owned, or ownership-unknown resources.
## Integration
- **Called by:**
- - **brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows
- - **subagent-driven-development** - REQUIRED before executing any tasks
- - **executing-plans** - REQUIRED before executing any tasks
- - Any skill needing isolated workspace
-
- **Pairs with:**
- - **finishing-a-development-branch** - REQUIRED for cleanup after work complete
+ Called conditionally by planning/execution workflows only after the necessity
+ decision. Pairs with `finishing-a-development-branch` for evidence-led cleanup.