Back to Details

worktrees

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Using Git Worktrees

使用Git工作树

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工作树可创建共享同一仓库的独立工作区，允许同时处理多个分支而无需切换分支。
核心原则： 系统化目录选择 + 安全验证 = 可靠的隔离。
开始时告知： "我正在使用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 directory is ignored before creating worktree:
bash
undefined
创建工作树前必须验证目录已被忽略：
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. 继续创建工作树

**关键原因：** 防止意外将工作树内容提交到仓库。

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

Node.js

if [ -f package.json ]; then npm install; fi
if [ -f package.json ]; then npm install; fi

Rust

Rust

if [ -f Cargo.toml ]; then cargo build; fi
if [ -f Cargo.toml ]; then cargo build; fi

Python

Python

if [ -f requirements.txt ]; then pip install -r requirements.txt; fi if [ -f pyproject.toml ]; then poetry install; fi
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi if [ -f pyproject.toml ]; then poetry install; fi

Go

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

速查指南

SituationAction
.worktrees/
exists		Use it (verify ignored)
worktrees/
exists		Use it (verify ignored)
Both existUse 
.worktrees/
Neither existsCheck CLAUDE.md → Ask user
Directory not ignoredAdd to .gitignore + commit
Tests fail during baselineReport failures + ask
No package.json/Cargo.tomlSkip 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
  • 问题： 工作树内容被追踪，污染git状态
  • 修复： 创建项目本地工作树前始终使用
    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/已被忽略]
[创建工作树：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 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
绝对禁止：
  • 未验证是否被忽略就创建项目本地工作树
  • 跳过基线测试验证
  • 测试失败未询问就继续
  • 模糊情况下预设目录位置
  • 跳过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——工作完成后清理时必须调用