Git Worktrees 使用指南：创建隔离工作区，高效管理多分支开发

using-git-worktrees by obra/superpowers

22,800 周安装量

107,700 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/obra/superpowers --skill using-git-worktrees

开发开发运维生产力

🇨🇳中文介绍

使用 Git Worktrees

概述

Git worktrees 创建共享同一仓库的隔离工作区，允许在不切换分支的情况下同时处理多个分支。

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

开始前声明： "我正在使用 using-git-worktrees 技能来设置一个隔离的工作区。"

目录选择流程

遵循以下优先级顺序：

1. 检查现有目录

# 按优先级顺序检查
ls -d .worktrees 2>/dev/null     # 首选（隐藏目录）
ls -d worktrees 2>/dev/null      # 备选

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

2. 检查 CLAUDE.md

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

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

3. 询问用户

如果不存在目录且 CLAUDE.md 中没有偏好设置：

未找到 worktree 目录。我应该在何处创建 worktrees？

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

您倾向于哪个选项？

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

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

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

# 检查目录是否被忽略（尊重本地、全局和系统 gitignore）
git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null

如果未被忽略：

根据 Jesse 的规则"立即修复损坏的东西"：

在 .gitignore 中添加适当的行
提交更改
继续创建 worktree

为何关键： 防止意外将 worktree 内容提交到仓库。

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

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

1. 检测项目名称

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

# 确定完整路径
case $LOCATION in
  .worktrees|worktrees)
    path="$LOCATION/$BRANCH_NAME"
    ;;
  ~/.config/superpowers/worktrees/*)
    path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"
    ;;
esac

# 使用新分支创建 worktree
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"

3. 运行项目设置

自动检测并运行适当的设置：

# 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

4. 验证干净的基线

运行测试以确保 worktree 从干净状态开始：

# 示例 - 使用适合项目的命令
npm test
cargo test
pytest
go test ./...

如果测试失败： 报告失败，询问是继续还是调查。

如果测试通过： 报告准备就绪。

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

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

问题： Worktree 内容被跟踪，污染 git status
修复： 在创建项目本地 worktree 之前始终使用 git check-ignore

问题： 造成不一致，违反项目约定
修复： 遵循优先级：现有 > CLAUDE.md > 询问

在测试失败的情况下继续

问题： 无法区分新 bug 与已存在的问题
修复： 报告失败，获取明确的继续许可

硬编码设置命令

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

You: 我正在使用 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 个失败）
准备实现 auth 功能

创建 worktree 而不验证其是否被忽略（项目本地）
跳过基线测试验证
在测试失败的情况下未经询问就继续
在模糊时假设目录位置
跳过 CLAUDE.md 检查

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

由以下调用：

brainstorming（第 4 阶段）- 当设计被批准并随后进行实现时，必需
subagent-driven-development - 在执行任何任务之前，必需
executing-plans - 在执行任何任务之前，必需
任何需要隔离工作区的技能

与以下配合使用：

finishing-a-development-branch - 工作完成后进行清理时，必需

🇺🇸English

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

Directory Selection Process

Follow this priority order:

1. Check Existing Directories

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

2. Check CLAUDE.md

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

If preference specified: Use it without asking.

3. Ask User

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?

Safety Verification

For Project-Local Directories (.worktrees or worktrees)

MUST verify directory is ignored before creating worktree:

# Check if directory is ignored (respects local, global, and system 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":

Add appropriate line to .gitignore
Commit the change
Proceed with worktree creation

Why critical: Prevents accidentally committing worktree contents to repository.

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

No .gitignore verification needed - outside project entirely.

Creation Steps

1. Detect Project Name

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

2. Create Worktree

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

3. Run Project Setup

Auto-detect and run appropriate setup:

# 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

4. Verify Clean Baseline

Run tests to ensure worktree starts clean:

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

5. Report Location

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

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

Common Mistakes

Skipping ignore verification

Problem: Worktree contents get tracked, pollute git status
Fix: Always use git check-ignore 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.)

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

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

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

Weekly Installs

22.8K

Repository

obra/superpowers

GitHub Stars

107.7K

First Seen

Jan 19, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode19.3K

codex18.6K

gemini-cli18.6K

github-copilot17.6K

cursor16.9K

amp16.2K