using-git-worktrees

使用 Git Worktree

概述

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

核心原则: 先检测是否已有隔离环境,再使用原生工具,最后才回退到 git。不要与运行环境对抗。

开始时声明: "我正在使用 using-git-worktrees 技能来设置隔离的工作区。"

第 0 步:检测现有隔离环境

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

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 中"之前,请先确认你不在子模块中:

# 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

如果 GIT_DIR != GIT_COMMON(且不在子模块中): 你已经处于一个关联的 worktree 中。跳至第 2 步(项目设置)。不要再创建另一个 worktree。

报告时附带分支状态:

• 在分支上:"已处于隔离工作区 <path>,当前分支为 <name>。"
• 分离的 HEAD:"已处于隔离工作区 <path>(分离的 HEAD,由外部管理)。完成时需要创建分支。"

如果 GIT_DIR == GIT_COMMON(或处于子模块中): 你处于普通的仓库检出中。

你的指令中是否已经表明了 worktree 偏好?如果没有,在创建 worktree 之前请先征得同意:

"是否需要我设置一个隔离的 worktree?这样可以保护你当前的分支不受改动影响。"

如果已有明确声明的偏好,则直接遵循,无需再问。如果用户拒绝同意,则在原地工作,并跳至第 2 步。

第 1 步:创建隔离工作区

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

1a. 原生 Worktree 工具(优先)

用户已要求隔离工作区(第 0 步中已获得同意)。你是否已有创建 worktree 的方式?它可能是名为 EnterWorktree、WorktreeCreate 的工具,也可能是 /worktree 命令或 --worktree 参数。如果有,请使用它,然后跳至第 2 步。

原生工具会自动处理目录位置、分支创建和清理。在有原生工具的情况下使用 git worktree add,会产生运行环境无法看到或管理的"幽灵状态"。

只有在没有可用的原生 worktree 工具时,才继续执行第 1b 步。

1b. Git Worktree 回退方案

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

目录选择

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

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

2. 检查项目内是否已存在 worktree 目录:

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

   如果找到,则使用它。如果两者都存在,.worktrees 优先。

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

安全验证(仅限项目内目录)

在创建 worktree 之前,必须验证该目录已被忽略:

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

如果未被忽略: 将其添加到 .gitignore,提交该更改,然后继续。

为何至关重要: 防止误将 worktree 内容提交到仓库中。

创建 Worktree

# Determine path based on chosen location
path="$LOCATION/$BRANCH_NAME"

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

沙箱回退: 如果 git worktree add 因权限错误(沙箱拒绝)而失败,请告知用户沙箱阻止了 worktree 的创建,并说明你将改为在当前目录中工作。然后直接在原地执行环境设置和基线测试。

第 2 步:项目设置

自动检测并运行合适的设置:

# 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 步:验证干净的基线

运行测试,确保工作区起始状态干净:

# Use project-appropriate command
npm test / cargo test / pytest / go test ./...

如果测试失败: 报告失败项,并询问是继续还是先排查问题。

如果测试通过: 报告工作区已就绪。

报告

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

快速参考

场景	操作
已处于关联的 worktree 中	跳过创建（步骤 0）
位于子模块中	按普通仓库处理（步骤 0 的防护检查）
有原生 worktree 工具可用	使用该工具（步骤 1a）
没有原生工具	回退到 Git worktree（步骤 1b）
存在 .worktrees/	使用它（需验证已被忽略）
存在 worktrees/	使用它（需验证已被忽略）
两者都存在	使用 .worktrees/
两者都不存在	先检查说明文件，然后默认使用 .worktrees/
目录未被忽略	添加到 .gitignore 并提交
创建时出现权限错误	沙箱回退，就地工作
基线测试失败	报告失败并询问
没有 package.json/Cargo.toml	跳过依赖安装

常见的自我合理化借口

借口	事实
“我显然不在 worktree 中，没必要检查”	运行步骤 0。harness 创建的隔离和子模块都会骗过肉眼判断，检测命令才能给出定论。
“git worktree add 比找原生工具快”	原生工具（如 EnterWorktree）负责放置、分支和清理。绕过它是头号错误，会产生 harness 无法看到或管理的幻影状态。
“worktree 目录肯定已经被忽略了”	运行 git check-ignore。未被忽略的 worktree 目录会把整个目录树提交进仓库。
“任何目录名都可以”	明确的指令优先于已存在的项目本地目录，而项目本地目录又优先于 .worktrees/ 默认值。
“工作区是全新的，基线测试可以等等”	不干净的基线会让之后的每个失败都难以判断。现在就运行测试；越过失败继续，是你的人类合作伙伴的决定。