git-worktree

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.*directory" CLAUDE.md 2>/dev/null

If preference specified: Use it without asking.

bash

grep -i "worktree.*directory" 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中未指定偏好：

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

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

创建worktree前必须验证.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. 继续创建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="$HOME/.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 pnpm 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

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

pnpm test cargo test pytest go test ./...


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

**If tests pass:** Report ready.

pnpm 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个失败）
已准备好开发<feature-name>

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验证

问题： Worktree内容被追踪，污染git状态
修复： 创建项目本地worktree前务必检查.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/]
[创建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 .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

绝对禁止：

创建项目本地worktree时跳过.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

被以下技能调用：

brainstorming（第4阶段）——当设计通过并即将开始实现时必须调用
任何需要隔离工作区的技能