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>

第 4 步：退出工作树（完成后）

功能开发完成后，请使用原生的 ExitWorktree 工具（与 EnterWorktree 配套）进行清理。它可以移除工作树，也可以保留或丢弃更改，并能妥善恢复运行环境的状态。

优先使用它，而不是 git worktree remove。在这里直接使用 Git，会留下与你创建工作树时设法避免的相同幽灵状态，而运行环境无法感知或管理这种状态。

只有在没有可用的原生退出工具时，才使用 git worktree remove。

快速参考

情况	操作
已处于关联工作树中	跳过创建（第 0 步）
位于子模块中	按普通仓库处理（第 0 步检查）
有可用的原生工作树工具	使用它（第 1a 步）
没有原生工具	使用 Git 工作树作为后备方案（第 1b 步）
存在 .worktrees/	使用它（确认已忽略）
存在 worktrees/	使用它（确认已忽略）
两者都存在	使用 .worktrees/
两者都不存在	检查说明文件，然后默认使用 .worktrees/
目录未被忽略	将其添加到 .gitignore 并提交
创建时遇到权限错误	使用沙盒后备方案，在原位置工作
基线测试失败	报告失败并询问
没有 package.json/Cargo.toml	跳过依赖安装
功能开发完成，正在清理	使用原生 ExitWorktree（第 4 步）

常见的自我开脱

借口	事实
“我显然不在工作树中，没必要检查”	执行第 0 步。运行环境创建的隔离环境和子模块都容易让人误判；检测命令能给出确切答案。
“git worktree add 比寻找原生工具快”	原生工具（例如 EnterWorktree）负责管理位置、分支和清理。绕过它是头号错误，会产生运行环境无法感知或管理的幽灵状态。
“工作树目录肯定已经被忽略了”	执行 git check-ignore。未被忽略的工作树目录会将整个目录树提交到仓库中。
“目录名随便取都行”	明确指示优先于项目中已有的目录，后者又优先于默认的 .worktrees/。
“工作区是全新的，基线测试可以稍后再跑”	基线测试不干净，会导致之后的每次失败都难以判断。现在就运行测试；是否在失败后继续，由与你协作的人决定。