using-git-worktrees

使用 Git 工作树

概述

工作树只是同时检出另一段 Git 历史记录的特殊情况，并非通用的安全标志。优先使用当前工作区，并复用现有的合适工作树。分支决策和工作树决策彼此独立。

核心原则： 只有在有必要且有归属证据时才创建；每个创建的工作树都必须配有清理方案。

开始时说明： 解释需要工作树来解决的具体检出冲突。

步骤 0：环境检测

进行任何修改之前，记录仓库根目录、HEAD、分支或分离状态、已暂存／未暂存／未跟踪的路径、正在进行的 Git 操作，以及：

git worktree list --porcelain

将当前宿主环境的任务／对话绑定托管工作区语义归类为 managed、non-managed 或 unknown。使用可信的宿主／会话上下文、明确的宿主契约或宿主原生生命周期结果；不要根据产品名称、目录前缀、命令级 workdir、缺失的工具或缺少的元数据来推断分类。non-managed 必须有明确证据，证明当前环境不具备任务绑定的托管语义。当宿主提供工作区字段时，记录任务工作区和未指定单命令目录覆盖时命令的默认 cwd。

若存在尚未解决的冲突、正在进行的合并／变基／拣选提交／还原／二分查找，或无法解释的分离式 HEAD，则停止。只有可信的宿主绑定证据表明分离式 HEAD 是当前托管工作树的预期状态时，才可以接受；例如，Codex 托管的工作树默认以分离式状态启动。保留用户状态：不要自动暂存、重置、清理、大范围暂存或提交。

在决定是否有必要创建以及选择放置位置之前，阅读最相关的最小范围项目 AGENTS.md、CLAUDE.md、当前权威规范和现有工作树约定。仓库策略可能要求或禁止隔离，并决定任何获准的仓库内位置；不要在创建检出后才查明该策略。

步骤 1：必要性决策

只有满足以下任一条件时，才创建至多一个由任务负责的工作树：

• 任务进行期间必须让另一个分支保持检出状态；
• 无关的脏状态妨碍在当前工作区安全检出；
• 用户或当前仓库权威规范明确要求创建。

任务复杂度、规划、TDD、使用子 Agent，或分支名称为 main／master，都不足以构成理由。同一任务的子 Agent 共用一个工作区；不要为每个子 Agent 创建工作树，也不要创建嵌套工作树。如果不需要独立历史记录，也不要创建分支。

记录：原因、分支、确切路径、创建工作的协调者，以及预期的清理事件。如果负责人或清理条件不明确，则在创建前停止。

步骤 2：安全放置

仅当目标目录已被忽略（git check-ignore）时，才使用现有的仓库约定。切勿仅为容纳工作树而编辑或提交 .gitignore。如果没有安全的仓库内约定，则使用任务专属、位于仓库外的用户级临时目录。解析并验证确切路径后再创建；不要将宽泛的主目录、工作区或仓库根目录作为目标。

步骤 3：创建最小检出

优先复用已有的、承载相同目标的分支。只有在获准的 Git 生命周期要求独立历史记录时，才创建分支。

托管宿主绑定门槛

当宿主界面声明工作区受任务／聊天绑定管理时，请使用其原生 Worktree/Handoff 生命周期，而不是通过 Shell 创建工作区。只有在可信的宿主证据表明当前任务已绑定到目标工作区时，才重用当前任务。如果原生操作在另一个任务中创建工作或将工作移至另一个任务，则只能在该绑定任务中继续。

执行原生生命周期操作后，或在进入／重用已绑定的托管工作区时立即，并且在首次写入任务内容或 Git 历史记录之前，读取以下联合后置条件：

• 可信的任务工作区；
• 不带命令级目录覆盖的默认命令 cwd；
• 目标 Git worktree 根目录；
• 目标 HEAD 和分支／分离状态。

这四项必须描述同一个执行环境。git worktree list、看起来像托管工作区的路径，或单个命令的 workdir，都只能证明该后置条件的一部分。如果原生创建／交接不可用、只能通过 UI 操作，或无法验证，请在通过 Shell 创建 worktree 或写入任务内容／历史记录之前停止，并告知用户应执行的宿主原生重新进入操作。不得悄悄回退到 git worktree add。 应依据宿主环境适用的语义比较解析后的路径标识，而非比较原始路径字符串。默认 cwd 可以等于 worktree 根目录，也可以位于其内部；从该默认 cwd 运行 Git 时，必须解析到目标 worktree 根目录。 目标宿主托管的分离 HEAD 符合 Git 状态要求；不得仅为使该状态看起来像普通检出而创建分支。

如果已存在未绑定的手动 worktree，请保留它，并报告其确切路径、HEAD、分支、状态和所有权证据。不得自动迁移、删除、暂存、重置或覆盖有未提交更改、未跟踪文件或所有权未知的状态。后续提交／补丁转移须遵循正常的 Git 授权流程，并且必须在提供清理选项之前，于新的绑定任务中验证。

通用 Git 回退方案

只有在可信证据明确将当前宿主／CLI 界面判定为 non-managed 时，才使用以下 Shell 路径。若判定为 unknown，则应采取默认拒绝策略；缺少原生工具或绑定元数据并不能作为通用回退的依据。

# Existing branch
git worktree add <exact-path> <branch>

# New independently justified branch
git worktree add -b <branch> <exact-path> <start-point>

读取回显的 git worktree list --porcelain、新 worktree 的 HEAD／分支及其状态。不要使用强制标志。在通用宿主上，可以通过命令级 workdir 指定此检出目录，但这绝不能证明任务已绑定到托管工作区。

步骤 4：以权威文档为准的设置与基线验证

阅读项目的安装文档、锁文件和现有设置脚本。只运行项目明确要求的设置步骤。不得仅因清单文件存在，就推断需要运行 npm install、cargo build、pip install、poetry install，或下载依赖项。

运行范围最小且相关的基线验证。如果设置或测试失败，请报告确切错误并保留 worktree；不要通过修改无关文件来掩盖问题。

步骤 5：交接与清理责任

报告确切路径、分支、起始 HEAD、基线结果、负责人和清理触发条件。创建者协调方须持续负责，直到证明已完成清理或明确移交责任。

在任务提交或集成决策后，使用 finishing-a-development-branch。通常可以移除 worktree，同时保留尚未合并的分支；开放的 PR 不要求永久保留检出目录。

危险信号

绝不要：

• 仅因任务会修改代码就创建 worktree；
• 仅为使 worktree 能够创建而修改 .gitignore；
• 盲目安装依赖项；
• 为每个子 Agent 创建一个 worktree；
• 将 Git 回显、路径前缀或命令级 workdir 当作任务已绑定到托管工作区的证明；
• 仅因宿主原生功能尚未开放、只能通过 UI 操作或未出现在初始工具列表中，就通过 Shell 创建 worktree；
• 将全局 prune 或强制清理作为例行维护；
• 移除有未提交更改、未跟踪文件、已锁定、属于用户所有或所有权未知的资源。

集成

仅在必要性判断之后，由规划／执行工作流有条件地调用。与 finishing-a-development-branch 配合，用于基于证据的清理。