using-git-worktrees

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

使用 Git 工作树

Using Git Worktrees

概述

Overview

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

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

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

Git worktrees create isolated workspaces that share the same repository, allowing you to work on multiple branches simultaneously without switching.

Core Principle: Systematic Directory Selection + Security Validation = Reliable Isolation.

Announce when starting: "I'm using the using-git-worktrees skill to set up an isolated workspace."

目录选择流程

Directory Selection Process

按以下优先顺序执行：

Follow this priority order:

1. 检查现有目录

1. Check Existing Directories

bash

undefined

bash

undefined

按优先顺序检查

Check in priority order

ls -d .worktrees 2>/dev/null # 首选（隐藏目录） ls -d worktrees 2>/dev/null # 备选


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

ls -d .worktrees 2>/dev/null # Preferred (hidden directory) ls -d worktrees 2>/dev/null # Alternative


**If found:** Use that directory. If both exist, `.worktrees` takes precedence.

2. 检查 CLAUDE.md

2. Check CLAUDE.md

bash

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

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

bash

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

If preference is specified: Use it directly without asking.

3. 询问用户

3. Ask the User

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

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

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

你倾向哪个？

If no existing directories and no preference in CLAUDE.md:

No worktree directory found. Where should I create the worktree?

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

Which do you prefer?

安全验证

Security Validation

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

Project-Local Directories (.worktrees or worktrees)

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

bash

undefined

Must verify the directory is ignored before creating worktree:

bash

undefined

检查目录是否被忽略（遵循本地、全局和系统 gitignore）

Check if directory is ignored (follows 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. 继续创建工作树

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

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


**If not ignored:**

Follow Jesse's rule "Fix broken things immediately":
1. Add the corresponding entry to .gitignore
2. Commit the changes
3. Proceed to create the worktree

**Why this is critical:** Prevent accidental commit of worktree content to the repository.

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

Global Directory (~/.config/superpowers/worktrees)

无需 .gitignore 验证——完全在项目之外。

No .gitignore validation needed — completely outside the project.

创建步骤

Creation Steps

1. 检测项目名称

1. Detect Project Name

bash

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

bash

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

2. 创建工作树

2. Create Worktree

bash

undefined

bash

undefined

确定完整路径

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"

undefined

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

undefined

3. 运行项目设置

3. Run Project Setup

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

bash

undefined

Automatically detect and run the corresponding setup commands:

bash

undefined

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

undefined

if [ -f go.mod ]; then go mod download; fi

undefined

4. 验证基线正常

4. Verify Baseline Health

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

bash

undefined

Run tests to ensure the worktree has a clean initial state:

bash

undefined

示例 - 使用项目对应的命令

Example - use project-specific commands

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


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

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

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


**If tests fail:** Report the failure and ask whether to continue or troubleshoot.

**If tests pass:** Report readiness.

5. 报告位置

5. Report Location

工作树已就绪：<full-path>
测试通过（<N> 个测试，0 个失败）
准备实现 <feature-name>

Worktree ready: <full-path>
Tests passed (<N> tests, 0 failures)
Ready to implement <feature-name>

快速参考

Quick Reference

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

Scenario	Action
`.worktrees/` exists	Use it (verify ignored)
`worktrees/` exists	Use it (verify ignored)
Both exist	Use `.worktrees/`
Neither exists	Check CLAUDE.md → Ask user
Directory not ignored	Add to .gitignore + commit
Baseline tests fail	Report failure + ask
No package.json/Cargo.toml	Skip dependency installation

常见错误

Common Mistakes

跳过忽略验证

Skipping Ignore Validation

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

Problem: Worktree content gets tracked, polluting git status
Fix: Always use
```
git check-ignore
```
before creating project-local worktrees

假设目录位置

Assuming Directory Location

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

Problem: Causes inconsistency and violates project conventions
Fix: Follow priority: Existing directories > CLAUDE.md > Ask

带着失败的测试继续

Continuing with Failed Tests

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

Problem: Cannot distinguish new bugs from pre-existing issues
Fix: Report failure and get explicit permission before continuing

硬编码设置命令

Hardcoding Setup Commands

问题： 在使用不同工具的项目上会出错
修复： 从项目文件自动检测（package.json 等）

Problem: Will fail on projects using different tools
Fix: Auto-detect from project files (package.json, etc.)

示例工作流

Example Workflow

你：我正在使用 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 功能

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 passed]

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

红线

Red Lines

绝不：

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

始终：

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

Never:

Create a project-local worktree without verifying it's ignored
Skip baseline test validation
Continue with failed tests without asking
Assume directory location when ambiguous
Skip CLAUDE.md check

Always:

Follow directory priority: Existing directories > CLAUDE.md > Ask
Verify ignore status for project-local directories
Auto-detect and run project setup
Verify clean test baseline

集成

Integration

被以下技能调用：

brainstorming（阶段 4）- 设计通过且需要实现时必需
subagent-driven-development - 执行任何任务前必需
executing-plans - 执行任何任务前必需
任何需要隔离工作区的技能

配合使用：

finishing-a-development-branch - 工作完成后清理时必需

Called by these skills:

brainstorming (Phase 4) - Required when design is approved and implementation is needed
subagent-driven-development - Required before executing any tasks
executing-plans - Required before executing any tasks
Any skill requiring an isolated workspace

Used with:

finishing-a-development-branch - Required for cleanup after work is completed