using-git-worktrees

Use Git worktrees

Overview

Ensure work happens in an isolated workspace. Prefer your platform's native worktree tooling. Only fall back to manual git worktree when no native tooling is available.

Core principle: Detect existing isolation first. Then use native tooling. Then fall back to git. Never fight the harness.

Announce at the start: "I'm using the using-git-worktrees skill to set up an isolated workspace."

Step 0: Detect existing isolation

Before creating anything, check whether you're already in an isolated workspace.

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
BRANCH=$(git branch --show-current)

Submodule guard: Inside a git submodule GIT_DIR != GIT_COMMON is also true. Before concluding "already inside a worktree", first confirm you're not in a submodule:

# 如果这条命令返回路径，说明你在 submodule 里，不是 worktree —— 按普通仓库处理
git rev-parse --show-superproject-working-tree 2>/dev/null

If GIT_DIR != GIT_COMMON(and not a submodule): You're already inside a linked worktree. Skip to Step 2 (project setup).Do notcreate another worktree.

Report by branch state:

• On a branch: "Already in isolated workspace <path>, branch <name>。"
• Detached HEAD: "Already in isolated workspace <path>(detached HEAD, externally managed). A branch will need to be created on completion."

If GIT_DIR == GIT_COMMON(or inside a submodule): You're in a normal repository checkout.

Has the user already stated a worktree preference in your instructions? If not, ask for consent before creating a worktree:

"Would you like me to set up an isolated worktree? It protects your current branch from changes."

If the user has already stated a preference, follow it directly and don't ask again. If the user declines consent, work in place and skip to Step 2.

Step 1: Create the isolated workspace

You have two mechanisms. Try them in this order.

1a. Native Worktree tooling (preferred)

The user has already requested an isolated workspace (consent obtained in Step 0). Do you already have a way to create a worktree? It might be a tool named EnterWorktree、WorktreeCreate , a/worktree command, or a --worktree flag. If so, use it, then skip to Step 2.

Native tooling automatically handles directory placement, branch creation, and cleanup. Using git worktree addwhen you already have native tooling creates "phantom state" that your harness can't see or manage.

Only proceed to Step 1b when no native worktree tooling is available.

1b. Git Worktree fallback

Use only when Step 1a doesn't apply — you have no native worktree tooling available. Create the worktree manually with git.

Directory selection

Follow this priority order. An explicit user preference always takes precedence over observed filesystem state.

1. Check whether a worktree directory preference is declared in your instructions. If the user has specified one, use it directly without asking.

2. Check whether a project-local worktree directory exists:

   ls -d .worktrees 2>/dev/null     # 首选（隐藏目录）
   ls -d worktrees 2>/dev/null      # 备选
   

   Use it if found. If both exist,.worktrees Priority.

3. If there is no other information to reference, by default use the .worktrees/。

Security verification (project-local directory only)

Before creating a worktree, you must verify that the directory is ignored:

git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null

If it is not ignored: Add it to .gitignore, commit the change, then continue.

Why it is critical: Prevents worktree contents from being accidentally committed to the repository.

Create the worktree

# 根据选定位置确定路径
path="$LOCATION/$BRANCH_NAME"

git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"

Sandbox fallback: If git worktree add fails due to a permission error (sandbox denial), tell the user that the sandbox blocked worktree creation, and you will work in place in the current directory. Then run setup and baseline tests in place.

Step 2: Project setup

Automatically detect and run the corresponding setup command:

# 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

Step 3: Verify the baseline is clean

Run the tests to ensure the workspace is initially clean:

# 使用项目对应的命令
npm test / cargo test / pytest / go test ./...

If the tests fail: Report the failure and ask whether to continue or investigate.

If the tests pass: Report ready.

Report

工作树已就绪：<full-path>
测试通过（<N> 个测试，0 个失败）
准备实现 <feature-name>

Quick reference

Situation	Action
Already inside a linked worktree	Skip creation (Step 0)
Inside a submodule	Treat as a normal repository (Step 0 guard)
Has a native worktree tool	Use it (Step 1a)
No native tool	git worktree fallback (Step 1b)
.worktrees/ exists	Use it (verify it is ignored)
worktrees/ exists	Use it (verify it is ignored)
Both exist	Use .worktrees/
Neither exists	Check the instructions file, then default to .worktrees/
Directory is not ignored	Add to .gitignore + commit
Permission error on creation	Sandbox fallback, work in place
Baseline tests fail	Report failure + ask
No package.json/Cargo.toml	Skip dependency installation

Common mistakes

Fighting the harness

• Problem: Still using git worktree add
• Fix: Step 0 detects existing isolation. Step 1a yields to the native tool.

Skipping detection

• Problem: Creating another worktree nested inside an existing worktree
• Fix: Always run Step 0 before creating anything

Skipping ignore verification

• Problem: Worktree contents are tracked, polluting git status
• Fix: Always use before creating a project-local worktree git check-ignore

Assuming the directory location

• Problem: Causes inconsistency and violates project conventions
• Fix: Follow the priority: explicit instructions > existing project-local directory > default

Continuing with failing tests

• Problem: Cannot distinguish new bugs from pre-existing issues
• Fix: report the failure, obtain explicit permission before continuing

Red lines

Never:

• Create a worktree when existing isolation is already detected in Step 0
• Use EnterWorktreewhen a native worktree tool (such as git worktree add) already exists. This is mistake #1—if it exists, use it.
• Skip Step 1a and jump straight to the git commands of Step 1b
• Create a project-local worktree without verifying it is already ignored
• Skip baseline test verification
• Continue with failing tests without asking

Always:

• Run the Step 0 detection first
• Prefer native tools, then fall back to git
• Follow directory priority: explicit instructions > existing project-local directory > default
• Verify that the project-local directory is already ignored
• Auto-detect and run project setup
• Verify the test baseline is clean

Integration

Called by the following skills:

• brainstorming(Phase 4) - required when the design passes and implementation is needed
• subagent-driven-development - required before executing any task
• executing-plans - required before executing any task
• Any skill that needs an isolated workspace

Used with:

• finishing-a-development-branch - required when cleaning up after work is complete