# Using Git Worktrees

> 当开始需要与当前工作区隔离的功能开发，或执行实现方案之前，必须使用本 skill；通过原生工具或 git worktree 回退机制确保独立工作空间已存在

- **Type:** Skill
- **Install:** `agentstack add skill-jnlk-cn-superpowers-cn-using-git-worktrees`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jnlk-cn](https://agentstack.voostack.com/s/jnlk-cn)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jnlk-cn](https://github.com/jnlk-cn)
- **Source:** https://github.com/jnlk-cn/superpowers-cn/tree/main/skills/using-git-worktrees
- **Website:** https://github.com/jnlk-cn/superpowers-cn

## Install

```sh
agentstack add skill-jnlk-cn-superpowers-cn-using-git-worktrees
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 使用 Git Worktrees

## 概述

确保工作在独立工作空间中进行。优先使用平台原生的 worktree 工具。仅当没有原生工具可用时，才回退到手动 git worktree。

**核心原则：** 先检测现有隔离。再使用原生工具。最后回退到 git。切勿与 harness 对抗。

**开始时声明：** "我正在使用 using-git-worktrees skill 来设置独立工作空间。"

## 第 0 步：检测现有隔离

**在创建任何内容之前，先检查你是否已经处于独立工作空间中。**

```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)
```

**子模块防护：** 在 git 子模块内部，`GIT_DIR != GIT_COMMON` 同样成立。在得出"已经在 worktree 中"的结论前，先确认自己不在子模块里：

```bash
# 如果返回路径，说明你在子模块中，而不是 worktree 中——按普通仓库处理
git rev-parse --show-superproject-working-tree 2>/dev/null
```

**如果 `GIT_DIR != GIT_COMMON`（且不是子模块）：** 你已经位于一个 linked worktree 中。直接跳到第 2 步（项目设置）。不要创建另一个 worktree。

按分支状态报告：
- 在分支上："已在 `` 的独立工作空间中，位于分支 ``。"
- 分离 HEAD："已在 `` 的独立工作空间中（分离 HEAD，由外部管理）。需要在收尾时创建分支。"

**如果 `GIT_DIR == GIT_COMMON`（或在子模块中）：** 你处于普通的仓库检出状态。

用户是否已经在你的指令中表明了 worktree 偏好？如果没有，在创建 worktree 前先征求同意：

> "是否要我设置一个独立的 worktree？这样可以保护当前分支不被修改。"

如果已有明确偏好，直接按偏好执行，无需再问。如果用户拒绝同意，就在原地工作并跳到第 2 步。

## 第 1 步：创建独立工作空间

**你有两种机制，按以下顺序尝试。**

### 1a. 原生 Worktree 工具（优先）

用户已经同意创建独立工作空间（第 0 步）。你是否有现成的创建 worktree 的方式？它可能是名为 `EnterWorktree`、`WorktreeCreate` 的工具，`/worktree` 命令，或 `--worktree` 标志。如果有，使用它并跳到第 2 步。

原生工具会自动处理目录放置、分支创建和清理。当你已有原生工具时使用 `git worktree add`，会生成 harness 无法看见或管理的幽灵状态。

只有在没有原生 worktree 工具可用时，才进入第 1b 步。

### 1b. Git Worktree 回退

**仅在第 1a 步不适用时使用**——即你没有原生 worktree 工具可用。使用 git 手动创建 worktree。

#### 目录选择

遵循以下优先级顺序。用户明确指定的目录始终优先于文件系统当前状态。

1. **检查指令中是否声明了 worktree 目录偏好。** 如果用户已指定，直接使用，无需询问。

2. **检查是否已存在项目本地 worktree 目录：**
   ```bash
   ls -d .worktrees 2>/dev/null     # 优先（隐藏目录）
   ls -d worktrees 2>/dev/null      # 备选
   ```
   如果存在，则使用。如果两者都存在，`.worktrees` 优先。

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

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

**必须确认目录已被忽略，然后才能创建 worktree：**

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

**如果未被忽略：** 先添加到 `.gitignore`，提交更改，然后再继续。

**重要性：** 防止意外将 worktree 内容提交到仓库。

#### 创建 Worktree

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

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

**Sandbox 回退：** 如果 `git worktree add` 因权限错误失败（sandbox 拒绝），告知用户 sandbox 阻止了 worktree 创建，你将在当前目录中工作。然后在原地运行设置和基线测试。

## 第 2 步：项目设置

自动检测并运行相应的设置：

```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
```

## 第 3 步：验证干净基线

运行测试，确保工作空间以干净状态开始：

```bash
# 使用适合项目的命令
npm test / cargo test / pytest / go test ./...
```

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

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

### 报告

```
Worktree 已就绪：
测试通过（ 个测试，0 个失败）
准备实现：
```

## 快速参考

| 情况 | 操作 |
|-----------|--------|
| 已在 linked worktree 中 | 跳过创建（第 0 步） |
| 在子模块中 | 按普通仓库处理（第 0 步防护） |
| 有原生 worktree 工具可用 | 使用它（第 1a 步） |
| 无原生工具 | Git worktree 回退（第 1b 步） |
| `.worktrees/` 已存在 | 使用它（确认已忽略） |
| `worktrees/` 已存在 | 使用它（确认已忽略） |
| 两者都存在 | 使用 `.worktrees/` |
| 两者都不存在 | 先检查指令文件，再默认使用 `.worktrees/` |
| 目录未被忽略 | 添加到 `.gitignore` 并提交 |
| 创建时权限错误 | Sandbox 回退，原地工作 |
| 基线测试失败 | 报告失败并询问 |
| 无 package.json/Cargo.toml 等 | 跳过依赖安装 |

## 常见错误

### 与 harness 对抗

- **问题：** 在平台已提供隔离的情况下仍使用 `git worktree add`
- **修复：** 第 0 步检测现有隔离。第 1a 步优先使用原生工具。

### 跳过检测

- **问题：** 在现有 worktree 内部创建嵌套 worktree
- **修复：** 创建任何东西前都要先执行第 0 步

### 跳过忽略校验

- **问题：** worktree 内容被跟踪，污染 git 状态
- **修复：** 创建项目本地 worktree 前始终使用 `git check-ignore`

### 假定目录位置

- **问题：** 造成不一致，违反项目约定
- **修复：** 遵循优先级：明确指令 > 现有项目本地目录 > 默认值

### 在测试失败时继续

- **问题：** 无法区分新 bug 与既有问题
- **修复：** 报告失败，获得明确同意后再继续

## 红线

**绝不能：**
- 第 0 步已检测到现有隔离时仍创建 worktree
- 有原生 worktree 工具（例如 `EnterWorktree`）时使用 `git worktree add`。这是头号错误——如果有，就用它。
- 跳过第 1a 步直接执行第 1b 步的 git 命令
- 未确认已忽略就创建项目本地 worktree
- 跳过基线测试验证
- 未询问就在测试失败时继续

**必须始终：**
- 先执行第 0 步检测
- 优先使用原生工具而非 git 回退
- 遵循目录优先级：明确指令 > 现有项目本地目录 > 默认值
- 对项目本地目录确认已被忽略
- 自动检测并运行项目设置
- 验证干净测试基线

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jnlk-cn](https://github.com/jnlk-cn)
- **Source:** [jnlk-cn/superpowers-cn](https://github.com/jnlk-cn/superpowers-cn)
- **License:** MIT
- **Homepage:** https://github.com/jnlk-cn/superpowers-cn

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jnlk-cn-superpowers-cn-using-git-worktrees
- Seller: https://agentstack.voostack.com/s/jnlk-cn
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.