workspace-isolation

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 (Phase 4) - REQUIRED when design is approved and implementation follows
Any skill needing isolated workspace

Pairs with:

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

被以下技能调用：

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

搭配技能：

finishing-a-development-branch - 工作完成后清理时必须调用
executing-plans 或 subagent-driven-development - 在该工作区中执行开发任务