using-git-worktrees

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Using Git Worktrees

使用Git Worktrees

Overview

概述

Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.

Core principle: Systematic directory selection + safety verification = reliable isolation.

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

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

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

开始时告知： “我正在使用using-git-worktrees技能来设置独立工作区。”

Directory Selection Process

目录选择流程

Follow this priority order:

请遵循以下优先级顺序：

1. Check Existing Directories

1. 检查现有目录

bash

undefined

bash

undefined

Check in priority order

按优先级检查

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


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

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


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

2. Check CLAUDE.md

2. 检查CLAUDE.md

bash

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

If preference specified: Use it without asking.

bash

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

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

3. Ask User

3. 询问用户

If no directory exists and no CLAUDE.md preference:

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?

如果不存在任何目录且CLAUDE.md中未指定偏好：

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

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

您偏好哪一个？

Safety Verification

安全验证

For Project-Local Directories (.worktrees or worktrees)

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

MUST verify directory is ignored before creating worktree:

bash

undefined

创建worktree前必须验证目录是否被忽略：

bash

undefined

Check if directory is ignored (respects local, global, and system gitignore)

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

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


**If NOT ignored:**

Per Jesse's rule "Fix broken things immediately":
1. Add appropriate line to .gitignore
2. Commit the change
3. Proceed with worktree creation

**Why critical:** Prevents accidentally committing worktree contents to repository.

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


**如果未被忽略：**

遵循Jesse的规则“立即修复问题”：
1. 向.gitignore添加相应的行
2. 提交该更改
3. 继续创建worktree

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

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

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

No .gitignore verification needed - outside project entirely.

无需验证.gitignore - 完全位于项目外部。

Creation Steps

创建步骤

1. Detect Project Name

1. 检测项目名称

bash

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

bash

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

2. Create Worktree

2. 创建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

创建带新分支的worktree

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

undefined

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

undefined

3. Run Project Setup

3. 运行项目设置

Auto-detect and run appropriate setup:

bash

undefined

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

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. Verify Clean Baseline

4. 验证干净基线

Run tests to ensure worktree starts clean:

bash

undefined

运行测试以确保worktree初始状态正常：

bash

undefined

Examples - use project-appropriate command

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

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


**If tests fail:** Report failures, ask whether to proceed or investigate.

**If tests pass:** Report ready.

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


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

**如果测试通过：** 报告工作区已准备就绪。

5. Report Location

5. 报告位置

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

Worktree已在<完整路径>准备就绪
测试通过（共<N>个测试，0个失败）
已准备好实现<功能名称>

Quick Reference

快速参考

Situation	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
Tests fail during baseline	Report failures + ask
No package.json/Cargo.toml	Skip dependency install

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

Common Mistakes

常见错误

Skipping ignore verification

跳过忽略验证

Problem: Worktree contents get tracked, pollute git status
Fix: Always use
```
git check-ignore
```
before creating project-local worktree

问题： Worktree内容被追踪，污染git状态
解决方法： 创建项目本地worktree前始终使用
```
git check-ignore
```
验证

Assuming directory location

假设目录位置

Problem: Creates inconsistency, violates project conventions
Fix: Follow priority: existing > CLAUDE.md > ask

问题： 导致不一致，违反项目约定
解决方法： 遵循优先级：现有目录 > CLAUDE.md配置 > 询问用户

Proceeding with failing tests

测试失败仍继续

Problem: Can't distinguish new bugs from pre-existing issues
Fix: Report failures, get explicit permission to proceed

问题： 无法区分新bug与原有问题
解决方法： 报告失败情况，获取明确的继续许可

Hardcoding setup commands

硬编码设置命令

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

问题： 在使用不同工具的项目上会失效
解决方法： 从项目文件（如package.json）自动检测

Example Workflow

示例工作流

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

您：我正在使用using-git-worktrees技能来设置独立工作区。

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

Worktree已在/Users/jesse/myproject/.worktrees/auth准备就绪
测试通过（共47个测试，0个失败）
已准备好实现认证功能

Red Flags

注意事项

Never:

Create worktree without verifying it's ignored (project-local)
Skip baseline test verification
Proceed with failing tests without asking
Assume directory location when ambiguous
Skip CLAUDE.md check

Always:

Follow directory priority: existing > CLAUDE.md > ask
Verify directory is ignored for project-local
Auto-detect and run project setup
Verify clean test baseline

绝对不要：

未验证是否被忽略就创建项目本地worktree
跳过基线测试验证
测试失败未询问就继续
存在歧义时假设目录位置
跳过CLAUDE.md检查

始终要：

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

Integration

集成

Called by:

brainstorming (Phase 4) - REQUIRED when design is approved and implementation follows
subagent-driven-development - REQUIRED before executing any tasks
executing-plans - REQUIRED before executing any tasks
Any skill needing isolated workspace

Pairs with:

finishing-a-development-branch - REQUIRED for cleanup after work complete

被以下技能调用：

brainstorming（第4阶段）- 设计获批且即将实施时必须调用
subagent-driven-development - 执行任何任务前必须调用
executing-plans - 执行任何任务前必须调用
任何需要独立工作区的技能

搭配使用：

finishing-a-development-branch - 工作完成后清理时必须调用