Skip to content
Skills Library
Programming · Automation

using-git-worktrees

/using-git-worktrees

当需要开始与当前工作区隔离的功能开发或执行实现计划之前使用——创建具有智能目录选择和安全验证的隔离 git 工作树

Licence
MIT
Last repository change
14.10.2026

Assessment and security

96/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability21 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 14.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

当需要开始与当前工作区隔离的功能开发或执行实现计划之前使用——创建具有智能目录选择和安全验证的隔离 git 工作树

Original author description

当需要开始与当前工作区隔离的功能开发或执行实现计划之前使用——创建具有智能目录选择和安全验证的隔离 git 工作树

How it works

  1. 概述
  2. 目录选择流程
  3. 安全验证
  4. 创建步骤
  5. 快速参考
  6. 常见错误
  7. 示例工作流
  8. 红线
  9. 集成
Original SKILL.md headings · 215 lines, 435 words
SKILL.md preview
---
name: using-git-worktrees
description: 当需要开始与当前工作区隔离的功能开发或执行实现计划之前使用——创建具有智能目录选择和安全验证的隔离 git 工作树
---

# 使用 Git 工作树

## 概述

Git 工作树创建共享同一仓库的隔离工作区,允许同时在多个分支上工作而无需切换。

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

**开始时宣布:** "我正在使用 using-git-worktrees 技能来建立一个隔离的工作区。"

## 目录选择流程

按以下优先顺序执行:

### 1. 检查现有目录

```bash
# 按优先顺序检查
ls -d .worktrees 2>/dev/null     # 首选(隐藏目录)
ls -d worktrees 2>/dev/null      # 备选
```

**如果找到:** 使用该目录。如果两者都存在,`.worktrees` 优先。

### 2. 检查 CLAUDE.md

```bash
grep -i "worktree.*director" CLAUDE.md 2>/dev/null
```

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

### 3. 询问用户

如果没有现有目录且 CLAUDE.md 中无偏好设置:

```
未找到工作树目录。我应该在哪里创建工作树?

1. .worktrees/(项目本地,隐藏目录)
2. ~/.config/superpowers/worktrees/<project-name>/(全局位置)

你倾向哪个?
```

## 安全验证

### 项目本地目录(.worktrees 或 worktrees)

**创建工作树前必须验证目录已被忽略:**

```bash
# 检查目录是否被忽略(遵循本地、全局和系统 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. 检测项目名称

```bash
project=$(basename "$(git rev-parse --show-toplevel)")
```

### 2. 创建工作树

```bash
# 确定完整路径
case $LOCATION in
  .worktrees|worktrees)
    path="$LOCATION/$BRANCH_NAME"
    ;;
  ~/.config/superpowers/worktrees/*)
    path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"
    ;;
esac

# 创建带有新分支的工作树
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"
```

### 3. 运行项目设置

自动检测并运行相应的设置命令:

```bash
# 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. 验证基线正常

运行测试确保工作树初始状态干净:

```bash
# 示例 - 使用项目对应的命令
npm test
cargo test
pytest
go test ./...
```

**如果测试失败:** 报告失败情况,询问是否继续或排查。

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

### 5. 报告位置

```
工作树已就绪:<full-path>
测试通过(<N> 个测试,0 个失败)
准备实现 <feature-name>
```

## 快速参考

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

## 常见错误

### 跳过忽略验证

- **问题:** 工作树内容被跟踪,污染 git status
- **修复:** 创建项目本地工作树前始终使用 `git check-ignore`

### 假设目录位置

- **问题:** 造成不一致,违反项目约定
- **修复:** 遵循优先级:现有目录 > CLAUDE.md > 询问

### 带着失败的测试继续

- **问题:** 无法区分新 bug 和已有问题
- **修复:** 报告失败,获得明确许可后再继续

### 硬编码设置命令

- **问题:** 在使用不同工具的项目上会出错
- **修复:** 从项目文件自动检测(package.json 等)

## 示例工作流

```
你:我正在使用 using-git-worktrees 技能来建立一个隔离的工作区。

[检查 .worktrees/ - 存在]
[验证已忽略 - git check-ignore 确认 .worktrees/ 已被忽略]
[创建工作树:git worktree add .worktrees/auth -b feature/auth]
[运行 npm install]
[运行 npm test - 47 个通过]

工作树已就绪:/Users/jesse/myproject/.worktrees/auth
测试通过(47 个测试,0 个失败)
准备实现 auth 功能
```

## 红线

**绝不:**
- 创建项目本地工作树时不验证是否已忽略
- 跳过基线测试验证
- 不询问就带着失败的测试继续
- 在有歧义时假设目录位置
- 跳过 CLAUDE.md 检查

**始终:**
- 遵循目录优先级:现有目录 > CLAUDE.md > 询问
- 对项目本地目录验证是否已忽略
- 自动检测并运行项目设置
- 验证测试基线干净

## 集成

**被以下技能调用:**
- **brainstorming**(阶段 4)- 设计通过且需要实现时必需
- **subagent-driven-development** - 执行任何任务前必需
- **executing-plans** - 执行任何任务前必需
- 任何需要隔离工作区的技能

**配合使用:**
- **finishing-a-development-branch** - 工作完成后清理时必需

Versions

RepositoryScoreLicence
This page · leodorareluctant259/superpowers-zh96MIT
jjuraszek/pi-gauntlet100MIT
event4u-app/agent-config100MIT
yusixian/anjian100MIT
GanyuanRan/Aegis100MIT
sitien173/refract100MIT
innei/ryugi100MIT
rootcastleco/rei-skills100MIT
davila7/claude-code-templates100MIT

Database snapshot: 13.11.2026 · package version a77122c8c1fa (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 84using_git_worktrees
    Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification
  • 100git-worktrees
    Use when starting feature work that needs isolation from current workspace, before executing implementation plans, or when MORE THAN ONE SESSION is working on one checkout - creates isolated git worktrees with smart directory selection and safety verification
  • 100isolate
    Use when starting feature work that needs isolation from current workspace or before executing implementation plans — creates isolated git worktrees with smart directory selection and safety verification
  • 100use-git-worktree
    This skill should be used when starting feature work that needs isolation from current workspace - creates isolated git worktrees with smart directory selection and safety verification
  • 100worktree
    Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification
  • 100codex-git-worktrees
    Use when implementation needs isolation from the current workspace; creates git worktrees with safe directory selection and baseline verification.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.