| name | using-git-worktrees |
| description | 当需要开始与当前工作区隔离的功能开发或执行实现计划之前使用——创建具有智能目录选择和安全验证的隔离 git 工作树 |
使用 Git 工作树
概述
Git 工作树创建共享同一仓库的隔离工作区,允许同时在多个分支上工作而无需切换。
核心原则: 系统化的目录选择 + 安全验证 = 可靠的隔离。
开始时宣布: "我正在使用 using-git-worktrees 技能来建立一个隔离的工作区。"
目录选择流程
按以下优先顺序执行:
1. 检查现有目录
run_command(command="ls -d .worktrees 2>/dev/null")
run_command(command="ls -d worktrees 2>/dev/null")
如果找到: 使用该目录。如果两者都存在,.worktrees 优先。
2. 检查 AGENTS.md
run_command(command="grep -i \"worktree.*director\" AGENTS.md 2>/dev/null")
如果指定了偏好: 直接使用,无需询问。
3. 询问用户
如果无现有目录且 AGENTS.md 中无偏好:
未找到工作树目录。我应该在哪里创建工作树?
1. .worktrees/(项目本地,隐藏目录)
2. ~/.config/reasonix/worktrees/<project-name>/(全局位置)
你倾向哪个?
安全验证
项目本地目录
创建工作树前必须验证目录已被忽略:
run_command(command="git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null")
如果未被忽略: 根据"立即修复坏掉的东西"原则,在 .gitignore 中添加相应条目并提交,然后继续。
全局目录
无需 .gitignore 验证——完全在项目之外。
创建步骤
1. 检测项目名称
run_command(command="git rev-parse --show-toplevel") # 获取仓库根目录,提取项目名
2. 创建工作树
# 根据目录类型构造路径,然后创建工作树
run_command(command="git worktree add <path> -b <branch-name>")
# 注意:cd 在 run_command 中不持久,后续命令使用完整路径或 cwd 参数
3. 运行项目设置
自动检测并运行相应的设置命令(耗时较长,使用后台运行):
# 检测项目类型并后台运行对应设置命令
run_command(command="ls package.json Cargo.toml requirements.txt pyproject.toml go.mod 2>/dev/null")
# 根据存在的文件选择对应的设置命令:
# run_background(command="npm install") # Node.js
# run_background(command="cargo build") # Rust
# run_background(command="pip install -r requirements.txt") # Python
# run_background(command="poetry install") # Python (poetry)
# run_background(command="go mod download") # Go
4. 验证基线正常
运行测试确保工作树初始状态干净(耗时较长,使用后台运行):
run_background(command="npm test")
如果测试失败: 报告失败情况,询问是否继续或排查。
如果测试通过: 报告就绪。
5. 报告位置
工作树已就绪:<full-path>
测试通过(<N> 个测试,0 个失败)
准备实现 <feature-name>
快速参考
| 情况 | 操作 |
|---|
.worktrees/ 存在 | 使用它(验证已忽略) |
worktrees/ 存在 | 使用它(验证已忽略) |
| 两者都存在 | 使用 .worktrees/ |
| 都不存在 | 检查 AGENTS.md → 询问用户 |
| 目录未被忽略 | 添加到 .gitignore + 提交 |
| 基线测试失败 | 报告失败 + 询问 |
| 无 package.json/Cargo.toml | 跳过依赖安装 |
常见错误
- 跳过忽略验证 → 工作树内容被跟踪,污染 git status。修复:创建项目本地工作树前始终使用
run_command(command="git check-ignore -q <dir>")。
- 假设目录位置 → 造成不一致。修复:遵循优先级:现有目录 > AGENTS.md > 询问。
- 带着失败的测试继续 → 无法区分新 bug 和已有问题。修复:报告失败,获得明确许可后再继续。
- 硬编码设置命令 → 在使用不同工具的项目上会出错。修复:从项目文件自动检测。
示例工作流
你:我正在使用 using-git-worktrees 技能来建立一个隔离的工作区。
[检查 .worktrees/ - run_command(command="ls -d .worktrees 2>/dev/null") 存在]
[验证已忽略 - run_command(command="git check-ignore -q .worktrees 2>/dev/null") 确认 .worktrees/ 已被忽略]
[创建工作树:run_command(command="git worktree add .worktrees/auth -b feature/auth")]
[运行项目设置:run_background(command="npm install")]
[运行测试:run_background(command="npm test") - 47 个通过]
工作树已就绪:/Users/jesse/myproject/.worktrees/auth
测试通过(47 个测试,0 个失败)
准备实现 auth 功能
红线
绝不:
- 创建项目本地工作树时不验证是否已忽略
- 跳过基线测试验证
- 不询问就带着失败的测试继续
- 在有歧义时假设目录位置
始终:
- 遵循目录优先级:现有目录 > AGENTS.md > 询问
- 对项目本地目录验证是否已忽略
- 自动检测并运行项目设置
- 验证测试基线干净
集成
被以下技能调用: brainstorming(阶段 4)、subagent-driven-development、executing-plans,以及任何需要隔离工作区的技能。
配合使用: finishing-a-development-branch - 工作完成后清理时必需。