using-git-worktrees

使用 Git Worktree

概述

Git worktree 可创建共享同一仓库的隔离工作区，让你能够同时处理多个分支，而无需切换分支。

核心原则： 有条理地选择目录 + 安全验证 = 可靠隔离。

开始时宣布：“我正在使用 using-git-worktrees 技能来设置隔离工作区。”

目录选择流程

1. 确定所需 worktree 的路径："/"
2. 我们已经在目标位置了吗？这里是 Git worktree 吗？如果是，请报告并退出。
3. 如果我们位于错误的 worktree 中，请报告并退出。
4. 按以下优先级确定父 worktree 目录：
   • 现有 worktree 的父目录
   • AGENTS.md 中的偏好设置
   • 用户提示
5. 确保项目本地目录已添加到 .gitignore
6. 创建 worktree、运行设置流程并验证初始状态干净

1. 检查是否存在现有的 worktree 父目录

# Check in priority order
ls -d "../$(git rev-parse --path-format=absolute --git-common-dir | xargs dirname).worktrees" 2>/dev/null      # Alternative

如果找到了： 使用该目录。

2. 检查 AGENTS.md

grep -i "worktree.*director" AGENTS.md 2>/dev/null

如果指定了偏好设置： 直接使用，无需询问。

3. 询问用户

如果目录不存在，且 AGENTS.md 中也没有偏好设置：

No worktree directory found. Where should I create worktrees?

1. ../$(basename "$(git rev-parse --show-toplevel)").worktrees (project-local, hidden)
2. ~/.locals/share/<project-name>.worktrees/ (global location)

Which would you prefer?

创建步骤

1. 检测项目名称

project=$(git rev-parse --path-format=absolute --git-common-dir | xargs dirname)

2. 创建 Worktree

# Create worktree with new branch
path="../${project}.worktrees/${feature_name}"
mkdir -p "$path"
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"

3. 运行项目设置

自动检测并运行相应的设置流程：

# if Justfile
if [ -f Justfile ]; then just setup; fi

# if Mise
if [ -f .mise.toml ]; then mise setup; exit 0; fi

# Node.js (npm)
if [ -f package.json ]; then npm install; fi
# Node.js (yarn)
if [ -f package.json ]; then yarn install; fi
# Node.js (bun)
if [ -f package.json ]; then bun install; fi
# Node.js (pnpm)
if [ -f package.json ]; then pnpm 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

4. 验证初始状态干净

运行测试，确保 worktree 的初始状态干净：

# Examples - use project-appropriate command
# if Justfile
if [ -f Justfile ]; then just test; fi

if [ -f .mise.toml ]; then
  mise check
  exit 0
fi

npm test
cargo test
pytest
go test ./...

如果测试失败： 报告失败情况，并询问是继续还是调查原因。

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

5. 报告位置

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

快速参考

情况	操作
尚无 worktree	使用 ../<projectname>.worktrees/
两者都不存在	检查 AGENTS.md → 询问用户
目录未添加到 .gitignore	立即添加并提交
初始测试期间测试失败	报告失败情况并询问
没有 package.json/Cargo.toml	跳过依赖安装

常见错误

臆断目录位置

• 问题： 导致不一致，违反项目约定
• 解决方法： 按优先级操作：现有目录 > AGENTS.md > 询问

测试失败时仍继续

• 问题： 无法区分新 Bug 和已有问题
• 解决方法： 报告失败情况，并获得明确许可后再继续

硬编码设置命令

• 问题： 在使用不同工具的项目中会出错
• 解决方法： 根据项目文件（package.json 等）自动检测

工作流示例

You: I'm using the using-git-worktrees skill to set up an isolated workspace.

[Check ../<projectname>.worktrees/ - exists]
[Create worktree: git worktree add ../<projectname>.worktrees/auth -b feature/auth]
[Run npm install]
[Run npm test - 47 passing]

Worktree ready at /Users/jesse/myproject.worktrees/auth
Tests passing (47 tests, 0 failures)
Ready to implement auth feature

风险提示

切勿：

• 在现有工作区内创建 worktree
• 跳过初始测试验证
• 未经询问便在测试失败时继续
• 在目录位置不明确时自行臆断
• 跳过 AGENTS.md 检查

务必：

• 遵循目录优先级：现有目录 > AGENTS.md > 询问
• 检查项目本地目录是否已添加到 .gitignore
• 自动检测并运行项目设置流程
• 验证测试初始状态干净

集成

由以下项目调用：

• brainstorming（阶段 4）——设计获批且后续将进行实现时必须调用
• 任何需要隔离工作区的技能

配合使用：

• finishing-a-development-branch——工作完成后必须用于清理
• executing-plans 或 subagent-driven-development——在此 worktree 中开展工作