# Using Git Worktrees

> 在开始需要与当前 workspace 隔离的 feature work 时，或在执行 implementation plans 之前使用 - 通过原生工具或 git worktree fallback 确保存在隔离 workspace

- Skill: `vinvcn/using-git-worktrees` (Agent Skill)
- Install (CLI): `npx skillmds@latest add vinvcn/using-git-worktrees`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vinvcn/using-git-worktrees/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: vinvcn (https://skillmd.com/u/vinvcn)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vinvcn/using-git-worktrees

---


# 使用 Git Worktrees

## 概览

确保工作发生在隔离 workspace 中。优先使用你所在平台的原生 worktree 工具。只有在没有原生工具可用时，才 fallback 到手动 git worktrees。

**核心原则：** 先检测现有隔离。然后使用原生工具。然后 fallback 到 git。绝不对抗 harness。

**开始时宣布：** "I'm using the using-git-worktrees skill to set up an isolated workspace."

## Step 0: 检测现有隔离

**创建任何东西之前，检查你是否已经在隔离 workspace 中。**

```bash
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 防护：** `GIT_DIR != GIT_COMMON` 在 git submodules 内部也为 true。得出“already in a worktree”结论之前，先验证你不在 submodule 中：

```bash
# If this returns a path, you're in a submodule, not a worktree — treat as normal repo
git rev-parse --show-superproject-working-tree 2>/dev/null
```

**如果 `GIT_DIR != GIT_COMMON`（且不是 submodule）：** 你已经在 linked worktree 中。跳到 Step 3（Project Setup）。不要再创建另一个 worktree。

报告 branch 状态：
- 在 branch 上："Already in isolated workspace at `<path>` on branch `<name>`."
- Detached HEAD："Already in isolated workspace at `<path>` (detached HEAD, externally managed). Branch creation needed at finish time."

**如果 `GIT_DIR == GIT_COMMON`（或在 submodule 中）：** 你在普通 repo checkout 中。

用户是否已经在你的说明中表明了他们的 worktree 偏好？如果没有，在创建 worktree 前征得同意：

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

遵循任何已有的明确偏好，不要再询问。如果用户拒绝同意，就在原地工作并跳到 Step 3。

## Step 1: 创建隔离 Workspace

**你有两种机制。按此顺序尝试。**

### 1a. 原生 Worktree 工具（首选）

用户已经要求使用隔离 workspace（Step 0 consent）。你是否已经有创建 worktree 的方式？它可能是名为 `EnterWorktree`、`WorktreeCreate` 的工具、`/worktree` 命令，或 `--worktree` flag。如果有，使用它并跳到 Step 3。

原生工具会自动处理目录位置、branch 创建和清理。在你有原生工具时使用 `git worktree add`，会创建 harness 无法看到或管理的 phantom state。

只有在没有原生 worktree 工具可用时，才继续 Step 1b。

### 1b. Git Worktree Fallback

**只有在 Step 1a 不适用时才使用这个** —— 你没有可用的原生 worktree 工具。用 git 手动创建 worktree。

#### 目录选择

遵循此优先级顺序。明确的用户偏好始终优先于观察到的 filesystem state。

1. **检查你的说明中是否声明了 worktree 目录偏好。** 如果用户已经指定了一个，不询问直接使用它。

2. **检查是否存在项目本地 worktree 目录：**
   ```bash
   ls -d .worktrees 2>/dev/null     # Preferred (hidden)
   ls -d worktrees 2>/dev/null      # Alternative
   ```
   如果找到，就使用它。如果两者都存在，`.worktrees` 优先。

3. **检查是否存在全局目录：**
   ```bash
   project=$(basename "$(git rev-parse --show-toplevel)")
   ls -d ~/.config/superpowers/worktrees/$project 2>/dev/null
   ```
   如果找到，就使用它（与旧版全局路径保持 backward compatibility）。

4. **如果没有其他可用 guidance**，默认使用项目根目录下的 `.worktrees/`。

#### 安全验证（仅限项目本地目录）

**创建 worktree 前必须验证目录已被 ignored：**

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

**如果没有被 ignored：** 添加到 .gitignore，提交该更改，然后继续。

**为什么关键：** 防止意外把 worktree contents commit 到 repository。

全局目录（`~/.config/superpowers/worktrees/`）无需验证。

#### 创建 Worktree

```bash
project=$(basename "$(git rev-parse --show-toplevel)")

# Determine path based on chosen location
# For project-local: path="$LOCATION/$BRANCH_NAME"
# For global: path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"

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

**Sandbox fallback：** 如果 `git worktree add` 因 permission error（sandbox denial）失败，告诉用户 sandbox 阻止了 worktree 创建，你将改在当前目录工作。然后在原地运行 setup 和 baseline tests。

## Step 3: Project Setup

自动检测并运行适当 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
```

## Step 4: 验证干净 Baseline

运行测试，确保 workspace 起始状态干净：

```bash
# Use project-appropriate command
npm test / cargo test / pytest / go test ./...
```

**如果测试失败：** 报告失败，询问是继续还是调查。

**如果测试通过：** 报告已就绪。

### 报告

```
Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>
```

## 快速参考

| 情况 | 操作 |
|-----------|--------|
| 已经在 linked worktree 中 | 跳过创建（Step 0） |
| 在 submodule 中 | 视为普通 repo（Step 0 guard） |
| 原生 worktree 工具可用 | 使用它（Step 1a） |
| 没有原生工具 | Git worktree fallback（Step 1b） |
| `.worktrees/` 存在 | 使用它（验证 ignored） |
| `worktrees/` 存在 | 使用它（验证 ignored） |
| 两者都存在 | 使用 `.worktrees/` |
| 两者都不存在 | 检查 instruction file，然后默认 `.worktrees/` |
| 全局路径存在 | 使用它（backward compat） |
| 目录未 ignored | 添加到 .gitignore + commit |
| 创建时 permission error | Sandbox fallback，原地工作 |
| baseline 期间测试失败 | 报告失败 + 询问 |
| 没有 package.json/Cargo.toml | 跳过 dependency install |

## 常见错误

### 对抗 harness

- **问题：** 在平台已经提供隔离时使用 `git worktree add`
- **修复：** Step 0 检测现有隔离。Step 1a 交给原生工具。

### 跳过检测

- **问题：** 在现有 worktree 内部创建嵌套 worktree
- **修复：** 创建任何东西之前始终运行 Step 0

### 跳过 ignore 验证

- **问题：** Worktree contents 被 tracked，污染 git status
- **修复：** 创建项目本地 worktree 前始终使用 `git check-ignore`

### 假设目录位置

- **问题：** 制造不一致，违反项目约定
- **修复：** 遵循优先级：existing > global legacy > instruction file > default

### 在测试失败时继续

- **问题：** 无法区分新 bug 和已有问题
- **修复：** 报告失败，获得明确许可后再继续

## Red Flags

**绝不：**
- 在 Step 0 检测到现有隔离时创建 worktree
- 在你有原生 worktree 工具（例如 `EnterWorktree`）时使用 `git worktree add`。这是 #1 mistake —— 如果你有它，就使用它。
- 跳过 Step 1a，直接跳到 Step 1b 的 git commands
- 不验证它已被 ignored（项目本地）就创建 worktree
- 跳过 baseline test verification
- 不询问就在测试失败时继续

**始终：**
- 先运行 Step 0 detection
- 优先使用原生工具，而不是 git fallback
- 遵循目录优先级：existing > global legacy > instruction file > default
- 对项目本地目录验证 directory is ignored
- 自动检测并运行 project setup
- 验证 clean test baseline