mcpField
U
using-git-worktrees

using-git-worktrees

github.com/mavscui开发19361 次安装34 周前更新
代码仓库

关于 using-git-worktrees

using-git-worktrees 是一项指导编码 Agent 建立 Git worktree 隔离工作区的技能，适用于需要并行处理多个分支的开发流程。它按仓库现状和 CLAUDE.md 选择目录，并要求检查忽略规则与测试基线。

主要功能

  1. 01按优先级选择 worktree 目录
  2. 02检查项目目录是否被 Git 忽略
  3. 03根据项目文件运行依赖安装
  4. 04运行测试验证干净基线
  5. 05失败时先报告并征求继续许可

适用场景

  1. 01同时处理多个分支而不切换工作区
  2. 02为新功能建立隔离的开发目录
  3. 03在实现前确认项目测试基线

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/mavscui/agent-skills-hunter --skill using-git-worktrees

安装后在 Claude Code 中输入/using-git-worktrees确认已加载。

详细介绍

使用 Git 工作树

概述

Git 工作树会创建共享同一仓库的隔离工作区，让你能够同时在多个分支上工作，而无需切换分支。

核心原则： 系统化的目录选择 + 安全验证 = 可靠隔离。

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

目录选择流程

按以下优先级顺序执行：

1. 检查现有目录
# Check in priority order
ls -d .worktrees 2>/dev/null     # Preferred (hidden)
ls -d worktrees 2>/dev/null      # Alternative

**如果找到：**使用该目录。如果两个目录都存在，则优先使用 .worktrees。

2. 检查 CLAUDE.md
grep -i "worktree.*director" CLAUDE.md 2>/dev/null

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

3. 询问用户

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

No worktree directory found. Where should I create worktrees?

1. .worktrees/ (project-local, hidden)
2. ~/.config/superpowers/worktrees/<project-name>/ (global location)

Which would you prefer?

安全验证

对于项目本地目录（.worktrees 或 worktrees）

创建工作树前，必须验证该目录已被忽略：

# Check if directory is ignored (respects local, global, and system gitignore)
git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null

如果未被忽略：

根据 Jesse 的规则“立即修复损坏的内容”：

  1. 在 .gitignore 中添加适当的行
  2. 提交更改
  3. 继续创建工作树

**为什么至关重要：**防止意外将工作树内容提交到仓库。

对于全局目录（~/.config/superpowers/worktrees）

无需验证 .gitignore——该目录完全位于项目之外。

创建步骤

1. 检测项目名称
project=$(basename "$(git rev-parse --show-toplevel)")
2. 创建工作树
# Determine full path
case $LOCATION in
  .worktrees|worktrees)
    path="$LOCATION/$BRANCH_NAME"
    ;;
  ~/.config/superpowers/worktrees/*)
    path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"
    ;;
esac

# Create worktree with new branch
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"
3. 运行项目设置

自动检测并运行适当的设置命令：

# 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
4. 验证干净基线

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

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

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

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

5. 报告位置
Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>

快速参考

情况操作
.worktrees/ 存在使用它（验证是否已忽略）
worktrees/ 存在使用它（验证是否已忽略）
两者都存在使用 .worktrees/
两者都不存在检查 CLAUDE.md → 询问用户
目录未被忽略添加到 .gitignore 并提交
基线测试失败报告失败并询问
没有 package.json/Cargo.toml跳过依赖安装

常见错误

跳过忽略状态验证
  • **问题：**工作树内容会被跟踪，污染 git status
  • **修复：**创建项目本地工作树前，务必使用 git check-ignore
想当然地确定目录位置
  • **问题：**导致不一致，违反项目约定
  • **修复：**遵循优先级：现有目录 > CLAUDE.md > 询问
测试失败仍继续
  • **问题：**无法区分新 Bug 和既有问题
  • **修复：**报告失败情况，获得明确许可后再继续
硬编码设置命令
  • **问题：**在使用不同工具的项目中会失效
  • **修复：**根据项目文件（package.json 等）自动检测

示例工作流

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

[Check .worktrees/ - exists]
[Verify ignored - git check-ignore confirms .worktrees/ is ignored]
[Create worktree: git worktree add .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

危险信号

绝不：

  • 未验证目录已被忽略就创建工作树（项目本地）
  • 跳过基线测试验证
  • 未经询问就在测试失败时继续
  • 在目录位置不明确时自行假设
  • 跳过 CLAUDE.md 检查

始终：

  • 遵循目录优先级：现有目录 > CLAUDE.md > 询问
  • 验证项目本地目录已被忽略
  • 自动检测并运行项目设置
  • 验证测试基线干净

集成

由以下内容调用：

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

配合使用：

  • finishing-a-development-branch——工作完成后必须使用，以进行清理
  • executing-plans 或 subagent-driven-development——工作在此工作树中进行

评论

支持 Markdown