worktree

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Worktree

Default to linked-worktree isolation. Multiple sessions often run concurrently. Setup costs ~30 seconds and prevents hours of merge pain.

默认使用 linked-worktree 隔离机制。 多个会话通常会并发运行。设置耗时约30秒，可省去数小时的合并冲突处理工作。

Valid Workspace Definition

有效工作区定义

Valid for significant or autonomous work: linked checkout created via Skill(worktree)
```
create
```
(typically
```
.worktrees/<name>
```
)
Not valid by default: primary checkout at repo root
Allowed exception: interactive, single-agent, small changes can run in primary checkout when that is the deliberate choice

All operations use

noodle worktree

— it enforces CWD safety, correct sequencing, stash/rebase handling, and dep reinstall.

适用于重要或自主型工作：通过 Skill(worktree) 的
```
create
```
命令创建的关联检出（通常位于
```
.worktrees/<name>
```
）
默认无效：仓库根目录的主检出
允许的例外情况：交互式、单Agent的小型变更，若经过刻意选择，可在主检出中运行

所有操作均使用

noodle worktree

—— 它会确保 CWD 安全、执行顺序正确，处理 stash/rebase 逻辑，以及重新安装依赖。

Commands

命令

Preflight

前置检查

bash

noodle worktree list

Shows all worktrees with merge status. Run at session start to spot stale worktrees from crashed sessions.

bash

noodle worktree list

显示所有 worktree 及其合并状态。在会话开始时运行，可识别因会话崩溃遗留的过期 worktree。

Create

创建

bash

noodle worktree create <name>

Creates worktree + branch at

.worktrees/<name>

, symlinks

.claude/settings.local.json

, auto-detects package manager, installs deps.

bash

noodle worktree create <name>

在

.worktrees/<name>

路径创建 worktree 和对应分支，创建

.claude/settings.local.json

的符号链接，自动检测包管理器并安装依赖。

Run commands inside a worktree

在 worktree 内运行命令

bash

noodle worktree exec <name> <command...>

Runs the command inside the worktree via

cmd.Dir

. The parent shell's CWD never changes — this is the safe way to run builds, tests, or any tool that needs the worktree as CWD.

bash

undefined

bash

noodle worktree exec <name> <command...>

通过

cmd.Dir

在 worktree 内运行命令。父 shell 的 CWD 始终保持不变 —— 这是运行构建、测试或任何需要以 worktree 作为 CWD 的工具的安全方式。

bash

undefined

Examples

示例

noodle worktree exec my-feature go test ./... noodle worktree exec my-feature go build ./...


For git operations, `git -C` also works and doesn't need `exec`:

```bash
git -C <project-root>/.worktrees/<name> status
git -C <project-root>/.worktrees/<name> add -A
git -C <project-root>/.worktrees/<name> commit -m "message"

File reads/edits use absolute paths directly — no

exec

needed.

noodle worktree exec my-feature go test ./... noodle worktree exec my-feature go build ./...


对于 Git 操作，`git -C` 也可以使用，无需 `exec`：

```bash
git -C <project-root>/.worktrees/<name> status
git -C <project-root>/.worktrees/<name> add -A
git -C <project-root>/.worktrees/<name> commit -m "message"

文件读取/编辑可直接使用绝对路径 —— 无需

exec

。

Merge

合并

bash

noodle worktree merge <name>
noodle worktree merge <name> --into <branch>

Single command does: CWD safety check -> stash worktree noise -> rebase onto target branch -> merge -> remove worktree -> delete branch -> prune -> reinstall deps. Refuses to run if CWD is inside the worktree or if root checkout is not on the target branch.

By default, the target is the integration branch, auto-detected from

origin/HEAD

(falls back to

main

if detection fails). Use

--into

to merge into any branch — the root checkout must be on that branch when you run the command.

If there are no commits to merge, it exits early and leaves the worktree/branch in place so you can decide whether to continue work or run cleanup.

Merges are serialized via lockfile (

.worktrees/.merge-lock

). If another merge is in progress, the command waits with short retry intervals (default timeout: 5 minutes) and then proceeds automatically. Stale locks from crashed processes are detected and cleaned up automatically.

bash

noodle worktree merge <name>
noodle worktree merge <name> --into <branch>

单条命令完成以下操作：CWD 安全检查 → stash worktree 中的临时改动 → rebase 到目标分支 → 合并 → 删除 worktree → 删除分支 → 清理 → 重新安装依赖。如果 CWD 位于 worktree 内，或根检出不在目标分支上，命令将拒绝执行。

默认情况下，目标分支为集成分支，会从

origin/HEAD

自动检测（检测失败则回退到

main

）。使用

--into

可合并到任意分支 —— 运行命令时根检出必须位于该分支上。

如果没有需要合并的提交，命令会提前退出，并保留 worktree/分支，以便你决定是继续工作还是执行清理。

合并操作通过锁文件（

.worktrees/.merge-lock

）串行执行。如果有另一个合并正在进行，命令会以较短的重试间隔等待（默认超时时间：5分钟），然后自动继续。会自动检测并清理因进程崩溃遗留的过期锁。

Prune merged/patch-equivalent worktrees

清理已合并/补丁等价的 worktree

bash

noodle worktree prune

Auto-cleans safe worktrees:

no commits ahead of integration branch, or patch-equivalent commits only
clean working tree (no uncommitted changes)
removes stale
```
.worktrees/<name>
```
directories that are no longer real worktrees

bash

noodle worktree prune

自动清理符合安全条件的 worktree：

没有领先于集成分支的提交，或仅包含补丁等价的提交
工作区干净（无未提交的变更）
移除已不再是有效 worktree 的过期
```
.worktrees/<name>
```
目录

Clean up without merging

不合并直接清理

bash

noodle worktree cleanup <name>

Warns if there are unmerged commits. Use

--force

to discard them.

bash

noodle worktree cleanup <name>

如果存在未合并的提交会发出警告。使用

--force

可直接丢弃这些提交。

Critical Safety Rules

关键安全规则

NEVER
cd
into
.worktrees/
— if the shell CWD is inside a worktree when it gets removed, the shell dies permanently (exit code 1, no recovery, session over). This applies to:

Direct
```
cd /path/to/worktree && ...
```
in Bash tool calls
Any command that changes CWD as a side effect

The Bash tool maintains a persistent shell —

cd

in one call persists to ALL future calls. A later

rm -rf

git worktree remove

on that path kills the shell instantly.

Always use one of these instead:

```
noodle worktree exec <name> <cmd>
```
— CWD-safe by design
Subshells:
```
(cd /path && cmd)
```
— CWD resets when subshell exits
Absolute paths:
```
go build /path/to/pkg/...
```
Tool flags:
```
git -C <path>
```
,
```
go -C <path>
```

绝对不要
cd
到
.worktrees/
目录 —— 如果 shell 的 CWD 位于某个 worktree 内，而该 worktree 被删除，shell 会永久终止（退出码1，无法恢复，会话结束）。这适用于以下情况：

在 Bash 工具调用中直接执行
```
cd /path/to/worktree && ...
```
任何会副作用式改变 CWD 的命令

Bash 工具会维护一个持久化 shell —— 一次调用中的

cd

会对所有后续调用生效。之后对该路径执行

rm -rf

或

git worktree remove

会立即终止 shell。

请始终使用以下替代方式：

```
noodle worktree exec <name> <cmd>
```
—— 设计上保证 CWD 安全
子 shell：
```
(cd /path && cmd)
```
—— 子 shell 退出时 CWD 会重置
绝对路径：
```
go build /path/to/pkg/...
```
工具参数：
```
git -C <path>
```
、
```
go -C <path>
```

Parallel Agent Teams

并行 Agent 团队

Lead creates one worktree per teammate:
```
noodle worktree create phase-1
```
Spawn each with
```
mode: "acceptEdits"
```
— worktrees are isolated scratch space
Each teammate commits on its own branch
Lead merges each:
```
noodle worktree merge phase-1
```

Sub-agent hierarchies: A lead agent working in its own worktree (branch

lead-work

) can spawn sub-agents with their own worktrees. Sub-agents merge back into the lead's branch, not main:

bash

undefined

负责人为每个团队成员创建一个 worktree：
```
noodle worktree create phase-1
```
以
```
mode: "acceptEdits"
```
模式生成每个 Agent —— worktree 是隔离的临时工作空间
每个团队成员在自己的分支上提交代码
负责人合并每个 worktree：
```
noodle worktree merge phase-1
```

子 Agent 层级：在自身 worktree（分支

lead-work

）中工作的负责人 Agent 可以生成拥有各自 worktree 的子 Agent。子 Agent 合并回负责人的分支，而非 main 分支：

bash

undefined

Root checkout must be on the target branch

根检出必须位于目标分支上

git checkout lead-work noodle worktree merge sub-work --into lead-work


**Foundational changes**: If Phase 1 is a foundation later phases need, do it on main first, commit, then create parallel worktrees. Branches start from the commit they were created at.

**When not to use**: sequential tasks, read-only research, single-agent work with no concurrency risk.

git checkout lead-work noodle worktree merge sub-work --into lead-work


**基础变更**：如果第1阶段是后续阶段需要的基础，先在 main 分支上完成并提交，再创建并行 worktree。分支从其创建时的提交点开始。

**不适用场景**：串行任务、只读研究、无并发风险的单 Agent 工作。

Conventions

约定规范

Directory:
```
.worktrees/
```
at project root (gitignored)
Naming:
```
.worktrees/<branch-name>
```
Branches are ephemeral — merge back to main and delete when done
Brain vault is shared state — never branch it. Teammates send results back to the lead.

目录：项目根目录下的
```
.worktrees/
```
（已加入 gitignore）
命名规则：
```
.worktrees/<branch-name>
```
分支是临时的 —— 完成后合并回 main 并删除
Brain vault 是共享状态 —— 绝对不要为其创建分支。团队成员将结果返回给负责人。

Stale Worktree Triage

过期 worktree 排查处理

Use

noodle worktree list

to check status, then:

Merged (shows "safe to clean up") ->
```
noodle worktree cleanup <name>
```
Unmerged with commits -> report to user, let them decide merge vs discard
No commits -> crashed session artifact ->
```
noodle worktree cleanup <name>
```

使用

noodle worktree list

检查状态，然后按以下方式处理：

已合并（显示“safe to clean up”）→ 执行
```
noodle worktree cleanup <name>
```
有未合并提交 → 告知用户，由他们决定合并还是丢弃
无提交 → 会话崩溃的遗留产物 → 执行
```
noodle worktree cleanup <name>
```