setup-worktree

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Setup worktree

设置 worktree

Treat workspace creation as a transaction: preflight every repository first, then apply, checkpoint, and report the exact state left behind.

Resolve this skill's directory as

SKILL_DIR

; all commands below use files from that directory.

将工作区创建视为一项事务：先对每个仓库进行预检，然后应用更改、保存检查点，并报告最终留下的确切状态。

将此 skill 的目录确定为

SKILL_DIR

；以下所有命令都使用该目录中的文件。

1. Resolve the task

1. 确定任务

From the selected repository, resolve the root with:

git rev-parse --show-toplevel

Get the task slug from the user's invocation or the established conversation. Require a matching

.agent-work/tasks/<TASKSLUG>/

directory. Read

ticket.md

task.md

, then every outline Markdown file present there, before deriving a slug from context. If more than one task remains plausible, ask for the slug.

This step is complete when the repository root, task slug, and task directory are unambiguous and the available task brief and outline have been read.

从选定仓库中确定根目录：

git rev-parse --show-toplevel

从用户调用请求或已确立的对话上下文中获取任务 slug。必须存在匹配的

.agent-work/tasks/<TASKSLUG>/

目录。读取

ticket.md

或

task.md

，然后读取该目录中存在的每个大纲 Markdown 文件，在此之后才可根据上下文推导 slug。如果仍有多个合理候选，请询问用户以确定 slug。

此步骤完成的条件是：仓库根目录、任务 slug 和任务目录均明确无歧义，并且已读取可用的任务简报和大纲。

2. Resolve the early-exit branch

2. 确定提前退出分支

Read both config files when present:

```
.agent-work/workspace.json
```
```
.agent-work/workspace.local.json
```

The local file overrides shared scalar fields. If effective

disabled

true

, preflight and check out the task branch in the current repository:

python3 "$SKILL_DIR/scripts/setup_worktree.py" branch --repo-root "$REPO_ROOT" --task-slug "$TASKSLUG"
python3 "$SKILL_DIR/scripts/setup_worktree.py" branch --repo-root "$REPO_ROOT" --task-slug "$TASKSLUG" --apply

The first command must report the intended create/reuse/switch action without an error before the second runs. Then read the

disabled

outcome, report it, and stop. A checkout failure is a partial failure, not a disabled success.

When workspace setup is enabled, run:

git rev-parse --git-dir
git rev-parse --git-common-dir

If the two Git directories resolve to different paths, this checkout is already a linked worktree. Read the

already-in-worktree

outcome, report it, and stop unless the user explicitly asks for another worktree.

This step is complete when exactly one branch is selected: continue, stop in the current linked worktree, or stop on the checked-out disabled-workspace branch.

存在以下配置文件时，读取它们：

```
.agent-work/workspace.json
```
```
.agent-work/workspace.local.json
```

本地文件中的标量字段覆盖共享文件中的对应值。如果合并后的有效配置中

disabled

为

true

，请先预检，再在当前仓库中检出任务分支：

python3 "$SKILL_DIR/scripts/setup_worktree.py" branch --repo-root "$REPO_ROOT" --task-slug "$TASKSLUG"
python3 "$SKILL_DIR/scripts/setup_worktree.py" branch --repo-root "$REPO_ROOT" --task-slug "$TASKSLUG" --apply

运行第二条命令前，第一条命令必须无错误地报告计划执行的

create

、

reuse

或

switch

操作。然后读取

disabled

结果，报告结果并停止。检出失败属于部分失败，不能视为

disabled

成功。

启用工作区设置时，运行：

git rev-parse --git-dir
git rev-parse --git-common-dir

如果两个 Git 目录解析为不同路径，则此检出已经位于一个链接 worktree 中。读取

already-in-worktree

结果，报告结果并停止，除非用户明确要求创建另一个 worktree。

此步骤完成的条件是只能确定以下一种处理路径：继续、在当前链接 worktree 中停止，或在已检出的禁用工作区分支上停止。

3. Establish configuration

3. 建立配置

When either config exists, use it. When neither exists:

Inspect
```
scripts/create_worktree.sh
```
in the repository root if it exists.
If it exists, read configuration and legacy migration, translate every behavior into
```
.agent-work/workspace.json
```
. If a behavior has no exact representation or more than one plausible mapping, show that ambiguity and obtain the user's choice before writing.

Otherwise write the preserved single-repository default with:

python3 "$SKILL_DIR/scripts/setup_worktree.py" init --repo-root "$REPO_ROOT" --write

Read configuration whenever translating a legacy script, diagnosing a config error, or explaining merge behavior. Existing config is user-owned; report an invalid field with its JSON path instead of silently repairing it.

This step is complete when at least one valid config file exists and every legacy behavior is mapped or explicitly resolved by the user.

只要任一配置文件存在，就使用现有配置。如果两个配置均不存在：

检查仓库根目录下是否存在
```
scripts/create_worktree.sh
```
。
如果存在，读取配置与旧版迁移，并将脚本中的每项行为都映射到
```
.agent-work/workspace.json
```
。如果某项行为没有完全对应的表示，或存在多个合理映射，请先展示这种歧义并获得用户选择，然后再写入配置。

否则，通过以下命令写入保留的单仓库默认配置：

python3 "$SKILL_DIR/scripts/setup_worktree.py" init --repo-root "$REPO_ROOT" --write

迁移旧版脚本、诊断配置错误或说明合并行为时，都要读取配置。现有配置归用户所有；遇到无效字段时，应报告该字段及其 JSON 路径，而不是静默修复。

此步骤完成的条件是：至少存在一个有效配置文件，并且每项旧版行为都已映射或已由用户明确解决。

4. Preflight the whole workspace

4. 预检整个工作区

Run the planner and retain its JSON output:

python3 "$SKILL_DIR/scripts/setup_worktree.py" plan --repo-root "$REPO_ROOT" --task-slug "$TASKSLUG"

Inspect every repository record. The planner must account for all configured repositories and prove, before mutation:

the repository exists, and the source commit exists when branch creation needs it;
the rendered branch is a valid Git branch;
the destination is either absent or the same registered worktree on that branch;
no branch is checked out at a conflicting path;
every copy match stays below its source repository and excludes Git metadata;
exactly one primary working directory can be selected;
every setup command is shown verbatim.

The effective config is the setup contract. Ask only when a command needs credentials, elevated privileges, or an external mutation beyond local dependency/project setup.

This step is complete only when every record has action

create

attach

, or

reuse

, with no planner error and no unresolved authorization.

运行规划器并保留其 JSON 输出：

python3 "$SKILL_DIR/scripts/setup_worktree.py" plan --repo-root "$REPO_ROOT" --task-slug "$TASKSLUG"

检查每个仓库记录。规划器必须涵盖所有已配置仓库，并在进行任何变更前证明：

仓库存在；如果创建分支需要源提交，则该源提交存在；
渲染后的分支名是有效的 Git 分支；
目标路径不存在，或者对应于该分支上同一个已注册的 worktree；
没有分支在冲突路径中被检出；
每个复制匹配项都位于源仓库之下，并排除 Git 元数据；
可以且只能选定一个主要工作目录；
每条设置命令均逐字展示。

有效配置就是设置契约。仅当某条命令需要凭据、提升权限，或需要执行超出本地依赖/项目设置范围的外部变更时，才向用户询问。

此步骤只有在每条记录的操作均为

create

、

attach

或

reuse

，且不存在规划器错误和未解决的授权问题时才算完成。

5. Apply and checkpoint

5. 应用并保存检查点

Run:

python3 "$SKILL_DIR/scripts/setup_worktree.py" apply --repo-root "$REPO_ROOT" --task-slug "$TASKSLUG"

The helper creates or attaches each worktree, copies configured local files while preserving relative paths, runs each configured setup command in its worktree, and verifies repository identity and branch.

reuse

completes the same copy, setup, and verification checkpoint so an interrupted run is resumable.

If any record fails, preserve the worktrees already created. Read partial failure and recovery, report the successful checkpoints and the exact failing operation, and work from that state. Cleanup is a separate, explicitly approved action.

This step is complete when every configured repository has status

ready

, or the partial state and one reproducible recovery command have been reported.

运行：

python3 "$SKILL_DIR/scripts/setup_worktree.py" apply --repo-root "$REPO_ROOT" --task-slug "$TASKSLUG"

辅助脚本会创建或附加每个 worktree，在保留相对路径的同时复制已配置的本地文件，在各自的 worktree 中运行每条已配置的设置命令，并验证仓库身份和分支。

reuse

同样会完成复制、设置和验证检查点，以便恢复中断的运行。

如果任何记录失败，请保留已经创建的 worktree。读取部分失败与恢复，报告成功的检查点和确切失败的操作，并基于该状态继续工作。清理是另一项需要明确批准的操作。

此步骤完成的条件是：每个已配置仓库的状态均为

ready

，或者已报告部分失败状态及一条可复现的恢复命令。

6. Report the result

6. 报告结果

Cross-check the helper result against

git worktree list --porcelain

for every repository. Then read the success outcome and report the task slug, primary worktree, every repository's path and branch, whether it was created/attached/reused, copied-file counts, and setup results.

The skill is complete only when all configured repositories are verified or an honest partial-failure report names every retained worktree and its recovery path.

针对每个仓库，将辅助脚本的结果与

git worktree list --porcelain

进行交叉核对。然后读取成功结果，报告任务 slug、主要 worktree、每个仓库的路径和分支、其状态为创建/附加/复用、复制文件数量以及设置结果。

只有当所有已配置仓库均验证通过，或如实报告部分失败并列明每个保留的 worktree 及其恢复路径时，此 skill 才算完成。