AgentAlley

Skills · Coding

Using Git Worktrees

Unverified●29/40

Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback

Originally by obra · MIT

Claude Code◐PartialHas SKILL.md but declares no allowed-tools — Claude Code will ask for permission each time
Cursor·UnknownWe have not crawled the repo tree, so we will not guess
Codex·UnknownWe have not crawled the repo tree, so we will not guess
Gemini CLI·UnknownThe spec defines no detection rule for Gemini
Copilot·UnknownWe have not crawled the repo tree, so we will not guess
npx agentalley add using-git-worktrees

This command does not work yet — the CLI is still being built. Until then, use Raw in the reader below to take the file.

Who is stuck, and on what

Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback

The whole source

No sign-in, no blur, nothing truncated
using-git-worktrees/SKILL.md168 lines6.7 KBRawView on GitHub
Frontmatter — 2 properties
nameusing-git-worktrees
descriptionUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
1---
2name: using-git-worktrees
3description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
4---A5 — No allowed-tools declared — no way to tell what this skill may touch
5 
6# Using Git Worktrees
7 
8## Overview
9 
10Ensure work happens in an isolated workspace. Prefer your platform's native worktree tools. Fall back to manual git worktrees only when no native tool is available.
11 
12**Core principle:** Detect existing isolation first. Then use native tools. Then fall back to git. Never fight the harness.
13 
14**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
15 
16## Step 0: Detect Existing Isolation
17 
18**Before creating anything, check if you are already in an isolated workspace.**
19 
20```bash
21GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
22GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
23BRANCH=$(git branch --show-current)
24```
25 
26**Submodule guard:** `GIT_DIR != GIT_COMMON` is also true inside git submodules. Before concluding "already in a worktree," verify you are not in a submodule:
27 
28```bash
29# If this returns a path, you're in a submodule, not a worktree — treat as normal repo
30git rev-parse --show-superproject-working-tree 2>/dev/null
31```
32 
33**If `GIT_DIR != GIT_COMMON` (and not a submodule):** You are already in a linked worktree. Skip to Step 2 (Project Setup). Do NOT create another worktree.
34 
35Report with branch state:
36- On a branch: "Already in isolated workspace at `<path>` on branch `<name>`."
37- Detached HEAD: "Already in isolated workspace at `<path>` (detached HEAD, externally managed). Branch creation needed at finish time."
38 
39**If `GIT_DIR == GIT_COMMON` (or in a submodule):** You are in a normal repo checkout.
40 
41Has the user already indicated their worktree preference in your instructions? If not, ask for consent before creating a worktree:
42 
43> "Would you like me to set up an isolated worktree? It protects your current branch from changes."
44 
45Honor any existing declared preference without asking. If the user declines consent, work in place and skip to Step 2.
46 
47## Step 1: Create Isolated Workspace
48 
49**You have two mechanisms. Try them in this order.**
50 
51### 1a. Native Worktree Tools (preferred)
52 
53The user has asked for an isolated workspace (Step 0 consent). Do you already have a way to create a worktree? It might be a tool with a name like `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag. If you do, use it and skip to Step 2.
54 
55Native tools handle directory placement, branch creation, and cleanup automatically. Using `git worktree add` when you have a native tool creates phantom state your harness can't see or manage.
56 
57Only proceed to Step 1b if you have no native worktree tool available.
58 
59### 1b. Git Worktree Fallback
60 
61**Only use this if Step 1a does not apply** — you have no native worktree tool available. Create a worktree manually using git.
62 
63#### Directory Selection
64 
65Follow this priority order. Explicit user preference always beats observed filesystem state.
66 
671. **Check your instructions for a declared worktree directory preference.** If the user has already specified one, use it without asking.
68 
692. **Check for an existing project-local worktree directory:**
70 ```bash
71 ls -d .worktrees 2>/dev/null # Preferred (hidden)
72 ls -d worktrees 2>/dev/null # Alternative
73 ```
74 If found, use it. If both exist, `.worktrees` wins.
75 
763. **If there is no other guidance available**, default to `.worktrees/` at the project root.
77 
78#### Safety Verification (project-local directories only)
79 
80**MUST verify directory is ignored before creating worktree:**
81 
82```bash
83git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
84```
85 
86**If NOT ignored:** Add to .gitignore, commit the change, then proceed.
87 
88**Why critical:** Prevents accidentally committing worktree contents to repository.
89 
90#### Create the Worktree
91 
92```bash
93# Determine path based on chosen location
94path="$LOCATION/$BRANCH_NAME"
95 
96git worktree add "$path" -b "$BRANCH_NAME"
97cd "$path"
98```
99 
100**Sandbox fallback:** If `git worktree add` fails with a permission error (sandbox denial), tell the user the sandbox blocked worktree creation and you're working in the current directory instead. Then run setup and baseline tests in place.
101 
102## Step 2: Project Setup
103 
104Auto-detect and run appropriate setup:
105 
106```bash
107# Node.js
108if [ -f package.json ]; then npm install; fi
109 
110# Rust
111if [ -f Cargo.toml ]; then cargo build; fi
112 
113# Python
114if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
115if [ -f pyproject.toml ]; then poetry install; fi
116 
117# Go
118if [ -f go.mod ]; then go mod download; fiA4 — This skill pulls in web or user content but never says to treat that content as data. A signal, not proof.
119```
120 
121## Step 3: Verify Clean Baseline
122 
123Run tests to ensure workspace starts clean:
124 
125```bash
126# Use project-appropriate command
127npm test / cargo test / pytest / go test ./...
128```
129 
130**If tests fail:** Report failures, ask whether to proceed or investigate.
131 
132**If tests pass:** Report ready.
133 
134### Report
135 
136```
137Worktree ready at <full-path>
138Tests passing (<N> tests, 0 failures)
139Ready to implement <feature-name>
140```
141 
142## Quick Reference
143 
144| Situation | Action |
145|-----------|--------|
146| Already in linked worktree | Skip creation (Step 0) |
147| In a submodule | Treat as normal repo (Step 0 guard) |
148| Native worktree tool available | Use it (Step 1a) |
149| No native tool | Git worktree fallback (Step 1b) |
150| `.worktrees/` exists | Use it (verify ignored) |
151| `worktrees/` exists | Use it (verify ignored) |
152| Both exist | Use `.worktrees/` |
153| Neither exists | Check instruction file, then default `.worktrees/` |
154| Directory not ignored | Add to .gitignore + commit |
155| Permission error on create | Sandbox fallback, work in place |
156| Tests fail during baseline | Report failures + ask |
157| No package.json/Cargo.toml | Skip dependency install |
158 
159## Common Rationalizations
160 
161| Excuse | Reality |
162|--------|---------|
163| "I'm obviously not in a worktree — no need to check" | Run Step 0. Harness-created isolation and submodules both fool eyeballing; the detection commands settle it. |
164| "`git worktree add` is quicker than hunting for a native tool" | A native tool (e.g. `EnterWorktree`) owns placement, branching, and cleanup. Bypassing it is the #1 mistake — it creates phantom state your harness can't see or manage. |
165| "The worktree directory is surely ignored already" | Run `git check-ignore`. An unignored worktree directory commits the whole tree into the repo. |
166| "Any directory name works" | Explicit instructions beat an existing project-local directory, which beats the `.worktrees/` default. |
167| "The workspace is fresh — baseline tests can wait" | A dirty baseline makes every later failure ambiguous. Run the tests now; proceeding past failures is your human partner's call. |
168 

Reviews

Installed this one?Write the first review and take the Trailblazer badge.

Reviews only open after a real install, so this is empty — and we leave it empty rather than invent one.

Alternatives

Also in Coding
Subagent Driven DevelopmentUse when executing implementation plans with independent tasks in the current sessionCoding · MIT◐◐◐◐◐●36/40Python Code Style & DocumentationPython code style, linting, formatting, naming conventions, and documentation standards. Use when writing new code, reviewing style, configuring linters, writing docstrings, or establishing project standards.Coding · MIT◐····●35/40Competitor Price Analysis 💲Competitor pricing strategy analysis and market positioning. Price mapping, pricing gaps identification, elasticity signals evaluation, and strategic pricing optimization. Use when the user asks about competitor pricing, price analysis, pricing strategy, or coCoding · MIT◐····●34/40Competitor Price Tracker 📊Set up competitor price tracking and monitoring workflows. Track price changes, detect promotions, analyze pricing patterns, and get alerts for competitive price movements.Coding · MIT◐····●34/40