使用 Git Worktrees

概述

确保工作在隔离的工作区中进行。优先使用平台的原生工作区工具。仅在无原生工具可用时回退到手动 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_DIR != GIT_COMMON 在 git 子模块内部也为真。在得出“已在工作区中”的结论之前，验证你不在子模块中：

# 如果返回路径，说明你在子模块中，而非工作区——视为普通仓库
git rev-parse --show-superproject-working-tree 2>/dev/null

如果 GIT_DIR != GIT_COMMON（且不是子模块）： 你已经在链接的工作区中。跳到第2步（项目设置）。不要创建另一个工作区。

报告分支状态：

在分支上：“已在隔离工作区 <path> 的分支 <name> 上。”
分离 HEAD：“已在隔离工作区 <path>（分离 HEAD，外部管理）。完成时需要创建分支。”

如果 GIT_DIR == GIT_COMMON（或在子模块中）： 你在普通仓库检出中。

用户是否已经在你的指令中指明了他们的工作区偏好？如果没有，在创建工作区前征求同意：

“您希望我设置一个隔离的工作区吗？它可以保护您当前分支免受更改影响。”

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

第1步：创建隔离工作区

你有两种机制。按此顺序尝试。

1a. 原生工作区工具（首选）

用户已要求隔离工作区（第0步同意）。你是否已经有创建工作区的方法？可能是一个名为 EnterWorktree、WorktreeCreate 的工具，或一个 /worktree 命令，或一个 --worktree 标志。如果有，使用它并跳到第2步。

原生工具会自动处理目录放置、分支创建和清理。当你有原生工具时使用 git worktree add 会创建你的工具链无法看到或管理的幽灵状态。

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

1b. Git Worktree 回退

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

目录选择

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

检查你的指令中是否有声明的工作区目录偏好。 如果用户已经指定了，直接使用，无需询问。
检查是否存在项目本地的工作区目录：
```
ls -d .worktrees 2>/dev/null     # 首选（隐藏）
ls -d worktrees 2>/dev/null      # 备选
```
如果找到，使用它。如果两者都存在，.worktrees 优先。
如果没有其他指导可用，默认使用项目根目录下的 .worktrees/。

安全检查（仅限项目本地目录）

在创建工作区前必须验证目录已被忽略：

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

如果未被忽略： 添加到 .gitignore，提交更改，然后继续。

为什么关键： 防止意外将工作区内容提交到仓库。

创建工作区

# 根据所选位置确定路径
path="$LOCATION/$BRANCH_NAME"

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

沙箱回退： 如果 git worktree add 因权限错误（沙箱拒绝）而失败，告知用户沙箱阻止了工作区创建，你将在当前目录中工作。然后在原地运行设置和基线测试。

第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步：验证干净基线

运行测试以确保工作区从干净状态开始：

# 使用项目适当的命令
npm test / cargo test / pytest / go test ./...

如果测试失败： 报告失败，询问是继续还是调查。

如果测试通过： 报告就绪。

报告

工作区就绪于 <完整路径>
测试通过（<N> 个测试，0 个失败）
准备实现 <功能名称>

快速参考

情况	操作
已在链接工作区中	跳过创建（第0步）
在子模块中	视为普通仓库（第0步防护）
原生工作区工具可用	使用它（第1a步）
无原生工具	Git worktree 回退（第1b步）
`.worktrees/` 存在	使用它（验证已忽略）
`worktrees/` 存在	使用它（验证已忽略）
两者都存在	使用 `.worktrees/`
两者都不存在	检查指令文件，然后默认 `.worktrees/`
目录未被忽略	添加到 .gitignore + 提交
创建时权限错误	沙箱回退，原地工作
基线测试失败	报告失败 + 询问
无 package.json/Cargo.toml	跳过依赖安装

常见错误

与工具链对抗

问题： 当平台已提供隔离时使用 git worktree add
修复： 第0步检测现有隔离。第1a步优先使用原生工具。

跳过检测

问题： 在现有工作区内部创建嵌套工作区
修复： 在创建任何内容前始终运行第0步

跳过忽略验证

问题： 工作区内容被跟踪，污染 git 状态
修复： 在创建项目本地工作区前始终使用 git check-ignore

假设目录位置

问题： 造成不一致，违反项目约定
修复： 遵循优先级：明确指令 > 现有项目本地目录 > 默认

在测试失败时继续

问题： 无法区分新错误和已有问题
修复： 报告失败，获得明确许可后再继续

红旗

永远不要：

在第0步检测到现有隔离时创建工作区
在有原生工作区工具（例如 EnterWorktree）时使用 git worktree add。这是#1错误——如果有，就使用它。
跳过第1a步直接跳到第1b步的 git 命令
未验证目录被忽略（项目本地）就创建工作区
跳过基线测试验证
在测试失败且未询问的情况下继续

始终：

首先运行第0步检测
优先使用原生工具而非 git 回退
遵循目录优先级：明确指令 > 现有项目本地目录 > 默认
验证项目本地目录已被忽略
自动检测并运行项目设置
验证干净的测试基线

using-git-worktrees

相关 Skills