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中无偏好设置：

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

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

您偏好哪一个？

Safety Verification

安全验证

For Project-Local Directories (.worktrees or worktrees)

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

MUST verify .gitignore before creating worktree:

bash

undefined

创建工作树前必须验证.gitignore：

bash

undefined

Check if directory pattern in .gitignore

检查目录规则是否在.gitignore中

grep -q "^.worktrees/$" .gitignore || grep -q "^worktrees/$" .gitignore


**If NOT in .gitignore:**

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.

grep -q "^.worktrees/$" .gitignore || grep -q "^worktrees/$" .gitignore


**如果不在.gitignore中：**

遵循Jesse的规则“立即修复问题”：
1. 向.gitignore中添加合适的规则
2. 提交该变更
3. 继续创建工作树

**为何至关重要：** 避免意外将工作树内容提交到仓库中。

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. 创建工作树

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. 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

运行测试确保工作树初始状态正常：

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>

工作树已就绪，路径：<完整路径>
测试通过（共<N>个测试，0个失败）
已准备好开发<功能名称>

Quick Reference

快速参考

Situation	Action
`.worktrees/` exists	Use it (verify .gitignore)
`worktrees/` exists	Use it (verify .gitignore)
Both exist	Use `.worktrees/`
Neither exists	Check CLAUDE.md → Ask user
Directory not in .gitignore	Add it immediately + commit
Tests fail during baseline	Report failures + ask
No package.json/Cargo.toml	Skip dependency install

场景	操作
`.worktrees/` 已存在	使用该目录（需验证.gitignore）
`worktrees/` 已存在	使用该目录（需验证.gitignore）
两者都存在	使用 `.worktrees/`
两者都不存在	检查CLAUDE.md → 询问用户
目录未在.gitignore中	立即添加规则 + 提交变更
基线测试失败	报告失败 + 询问用户
无package.json/Cargo.toml	跳过依赖安装

Common Mistakes

常见错误

Skipping .gitignore verification

Problem: Worktree contents get tracked, pollute git status
Fix: Always grep .gitignore before creating project-local worktree

Assuming directory location

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

Proceeding with failing tests

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

Hardcoding setup commands

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

跳过.gitignore验证

问题： 工作树内容被追踪，污染git状态
解决： 创建项目本地工作树前，务必检查.gitignore

默认目录位置

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

测试失败仍继续

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

硬编码搭建命令

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

Example Workflow

示例工作流

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

[Check .worktrees/ - exists]
[Verify .gitignore - contains .worktrees/]
[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/ - 已存在]
[验证.gitignore - 已包含.worktrees/]
[创建工作树：git worktree add .worktrees/auth -b feature/auth]
[运行npm install]
[运行npm test - 47项测试通过]

工作树已就绪，路径：/Users/jesse/myproject/.worktrees/auth
测试通过（共47个测试，0个失败）
已准备好开发认证功能

Red Flags

注意事项

Never:

Create worktree without .gitignore verification (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 .gitignore for project-local
Auto-detect and run project setup
Verify clean test baseline

绝对禁止：

不验证.gitignore就创建项目本地工作树
跳过基线测试验证
测试失败未询问用户就继续
目录位置不明确时默认选择
跳过CLAUDE.md检查

必须执行：

遵循目录优先级：现有目录 > CLAUDE.md设置 > 询问用户
对项目本地目录验证.gitignore
自动检测并运行项目搭建命令
验证干净的测试基线

Integration

集成

Called by:

brainstorming Skillc(Phase 4) - REQUIRED when design is approved and implementation follows
Any skill needing isolated workspace

Pairs with:

finishing-a-development-branch Skill - REQUIRED for cleanup after work complete
executing-plans or subagent-driven-development Skill - Work happens in this worktree

调用方：

brainstorming Skill（第4阶段）- 设计通过后开展实现时必须调用
任何需要隔离工作区的技能

搭配使用：

finishing-a-development-branch Skill - 工作完成后清理时必须调用
executing-plans 或 subagent-driven-development Skill - 在该工作树中开展工作