using-git-worktrees

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Using Git Worktrees

使用Git Worktrees

Overview

概述

Ensure 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.

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

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

确保工作在隔离的工作区中进行。优先使用平台的原生工作区工具。仅在没有原生工具可用时，才退而使用手动git worktree。

核心原则： 先检测是否已存在隔离环境。然后使用原生工具。最后才使用git作为备选。绝不与现有工具框架冲突。

开始时告知： "我正在使用using-git-worktrees技能来设置隔离工作区。"

Step 0: Detect Existing Isolation

步骤0：检测现有隔离状态

Before creating anything, check if you are already in an isolated 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 guard:

GIT_DIR != GIT_COMMON

is also true inside git submodules. Before concluding "already in a worktree," verify you are not in a submodule:

bash

undefined

在创建任何内容之前，先检查是否已处于隔离工作区中。

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

同样成立。在判定“已处于工作区”之前，需验证你不在子模块中：

bash

undefined

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


**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.

Report with branch state:
- On a 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."

**If `GIT_DIR == GIT_COMMON` (or in a submodule):** You are in a normal repo checkout.

Has the user already indicated their 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."

Honor any existing declared preference without asking. If the user declines consent, work in place and skip to Step 2.

git rev-parse --show-superproject-working-tree 2>/dev/null


**如果`GIT_DIR != GIT_COMMON`（且不在子模块中）：** 你已处于关联工作区。跳至步骤2（项目设置）。请勿创建另一个工作区。

根据分支状态报告：
- 处于分支上："已在`<path>`路径的隔离工作区中，当前分支为`<name>`。"
- 分离HEAD状态："已在`<path>`路径的隔离工作区中（分离HEAD状态，外部管理）。完成时需创建分支。"

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

用户是否已在指令中表明其工作区偏好？如果没有，在创建工作区前需征得同意：

> "是否需要我设置一个隔离工作区？它可以保护你当前的分支不被修改。"

无需询问，直接遵循已声明的偏好。如果用户拒绝同意，则在当前目录工作并跳至步骤2。

Step 1: Create Isolated Workspace

步骤1：创建隔离工作区

You have two mechanisms. Try them in this order.

有两种实现方式。按以下顺序尝试。

1a. Native Worktree Tools (preferred)

1a. 原生工作区工具（优先选择）

The 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.

Native 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.

Only proceed to Step 1b if you have no native worktree tool available.

用户已要求设置隔离工作区（步骤0已同意）。你是否已有创建工作区的方法？可能是名为

EnterWorktree

、

WorktreeCreate

的工具，

/worktree

命令，或

--worktree

参数。如果有，请使用它并跳至步骤2。

原生工具会自动处理目录放置、分支创建和清理工作。当有原生工具可用时使用

git worktree add

会创建工具框架无法查看或管理的幻影状态。

仅在没有原生工作区工具可用时，才继续步骤1b。

1b. Git Worktree Fallback

1b. Git Worktree备选方案

Only use this if Step 1a does not apply — you have no native worktree tool available. Create a worktree manually using git.

仅在步骤1a不适用时使用——即没有原生工作区工具可用。使用git手动创建工作区。

Directory Selection

目录选择

Follow this priority order. Explicit user preference always beats observed filesystem state.

Check your instructions for a declared worktree directory preference. If the user has already specified one, use it without asking.

Check for an existing project-local worktree directory:

bash

ls -d .worktrees 2>/dev/null     # Preferred (hidden)
ls -d worktrees 2>/dev/null      # Alternative

If found, use it. If both exist,

.worktrees

wins.

If there is no other guidance available, default to
```
.worktrees/
```
at the project root.

遵循以下优先级顺序。用户明确的偏好始终优先于已观察到的文件系统状态。

检查指令中是否已声明工作区目录偏好。 如果用户已指定，则直接使用无需询问。
检查是否存在项目本地的工作区目录：
bash
```
ls -d .worktrees 2>/dev/null     # 首选（隐藏目录）
ls -d worktrees 2>/dev/null      # 备选
```
如果找到，则使用该目录。如果两者都存在，优先选择
```
.worktrees
```
。
如果没有其他指导，默认使用项目根目录下的
```
.worktrees/
```
。

Safety Verification (project-local directories only)

安全验证（仅针对项目本地目录）

MUST verify directory is ignored before creating worktree:

bash

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

If NOT ignored: Add to .gitignore, commit the change, then proceed.

Why critical: Prevents accidentally committing worktree contents to repository.

必须在创建工作区前验证目录已被忽略：

bash

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

如果未被忽略： 将目录添加到.gitignore，提交更改，然后继续。

为什么至关重要： 防止意外将工作区内容提交到仓库。

Create the Worktree

创建工作区

bash

undefined

bash

undefined

Determine path based on chosen location

根据所选位置确定路径

path="$LOCATION/$BRANCH_NAME"

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


**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.

path="$LOCATION/$BRANCH_NAME"

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


**沙箱备选方案：** 如果`git worktree add`因权限错误（沙箱拒绝）而失败，告知用户沙箱阻止了工作区创建，你将改为在当前目录工作。然后在当前目录运行设置和基线测试。

Step 2: Project Setup

步骤2：项目设置

Auto-detect and run appropriate setup:

bash

undefined

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

bash

undefined

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

undefined

if [ -f go.mod ]; then go mod download; fi

undefined

Step 3: Verify Clean Baseline

步骤3：验证干净基线

Run tests to ensure workspace starts clean:

bash

undefined

运行测试以确保工作区初始状态正常：

bash

undefined

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.

npm test / cargo test / pytest / go test ./...


**如果测试失败：** 报告失败情况，询问是否继续或进行排查。

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

Report

报告内容

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

工作区已在<full-path>路径就绪
测试通过（共<N>个测试，0个失败）
已准备好实现<feature-name>

Quick Reference

快速参考

Situation	Action
Already in linked worktree	Skip creation (Step 0)
In a submodule	Treat as normal repo (Step 0 guard)
Native worktree tool available	Use it (Step 1a)
No native tool	Git worktree fallback (Step 1b)
`.worktrees/` exists	Use it (verify ignored)
`worktrees/` exists	Use it (verify ignored)
Both exist	Use `.worktrees/`
Neither exists	Check instruction file, then default `.worktrees/`
Directory not ignored	Add to .gitignore + commit
Permission error on create	Sandbox fallback, work in place
Tests fail during baseline	Report failures + ask
No package.json/Cargo.toml	Skip dependency install

场景	操作
已处于关联工作区	跳过创建步骤（步骤0）
处于子模块中	按普通仓库处理（步骤0防护）
有原生工作区工具可用	使用原生工具（步骤1a）
无原生工具	使用Git Worktree备选方案（步骤1b）
`.worktrees/` 已存在	使用该目录（验证已被忽略）
`worktrees/` 已存在	使用该目录（验证已被忽略）
两者都存在	使用 `.worktrees/`
两者都不存在	检查指令文件，然后默认使用 `.worktrees/`
目录未被忽略	添加到.gitignore并提交
创建时出现权限错误	沙箱备选方案，在当前目录工作
基线测试失败	报告失败情况并询问
无package.json/Cargo.toml	跳过依赖安装

Common Rationalizations

常见误区解释

Excuse	Reality
"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.
" `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.
"The worktree directory is surely ignored already"	Run `git check-ignore` . An unignored worktree directory commits the whole tree into the repo.
"Any directory name works"	Explicit instructions beat an existing project-local directory, which beats the `.worktrees/` default.
"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.

借口	实际情况
"我显然不在工作区里——没必要检查"	执行步骤0。工具框架创建的隔离环境和子模块都会误导肉眼判断；检测命令可以准确判定状态。
" `git worktree add` 比寻找原生工具更快"	原生工具（如 `EnterWorktree` ）负责目录放置、分支管理和清理工作。绕过它是最常见的错误——会创建工具框架无法查看或管理的幻影状态。
"工作区目录肯定已经被忽略了"	执行 `git check-ignore` 。未被忽略的工作区目录会将整个目录树提交到仓库。
"任何目录名称都可以"	明确的指令优先于已存在的项目本地目录，后者优先于 `.worktrees/` 默认目录。
"工作区是全新的——基线测试可以稍后再做"	不干净的基线会导致后续所有失败都难以定位。现在就运行测试；是否跳过失败继续执行由你的人工伙伴决定。