Back to Details

using-git-worktrees

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Using Git Worktrees

使用Git Worktrees

Core Principle

核心原则

Isolate feature work. Keep main clean.
Git worktrees let you work on multiple branches simultaneously in separate directories.
隔离功能开发，保持主分支干净。
Git worktrees允许你在不同目录中同时处理多个分支。

When to Use

适用场景

  • Starting a new feature
  • Working on a bugfix while main development continues
  • Need to context-switch without stashing
  • Want clean separation between work streams
  • 开始开发新功能
  • 在主分支持续开发的同时处理bug修复
  • 需要切换上下文但不想暂存代码
  • 希望不同工作流之间完全隔离

Setup Process

设置流程

Step 1: Check for Existing Worktree Directory

步骤1：检查是否存在Worktree目录

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

Step 2: Check CLAUDE.md for Preferences

步骤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
如果指定了偏好：直接使用该设置，无需询问。

Step 3: If No Directory Exists

步骤3：如果没有找到目录

Ask the user:
No worktree directory found. Where should I create worktrees?
1. .worktrees/ (project-local, hidden)
2. worktrees/ (project-local, visible)
3. ~/.config/superpowers/worktrees/<project-name>/ (global location)

Which would you prefer?
询问用户：
未找到worktree目录。我应该在哪里创建worktrees？
1. .worktrees/（项目本地，隐藏）
2. worktrees/（项目本地，可见）
3. ~/.config/superpowers/worktrees/<project-name>/（全局位置）

你偏好哪一个？

Step 4: Verify .gitignore

步骤4：验证.gitignore配置

bash
undefined
bash
undefined

Check if directory pattern in .gitignore

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

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

If not present, add it:
```bash
echo ".worktrees/" >> .gitignore
grep -q "^.worktrees/$" .gitignore || grep -q "^worktrees/$" .gitignore

如果不存在，添加规则：
```bash
echo ".worktrees/" >> .gitignore

or

或

echo "worktrees/" >> .gitignore
undefined
echo "worktrees/" >> .gitignore
undefined

Creating a Worktree

创建Worktree

Standard Creation

标准创建方式

bash
undefined
bash
undefined

Determine branch name from feature

根据功能确定分支名称

BRANCH_NAME="feature/descriptive-name"
BRANCH_NAME="feature/descriptive-name"

Create worktree with new branch

创建带新分支的worktree

git worktree add ".worktrees/$BRANCH_NAME" -b "$BRANCH_NAME"
git worktree add ".worktrees/$BRANCH_NAME" -b "$BRANCH_NAME"

Navigate to worktree

进入worktree目录

cd ".worktrees/$BRANCH_NAME"
undefined
cd ".worktrees/$BRANCH_NAME"
undefined

From Existing Branch

基于已有分支创建

bash
git worktree add ".worktrees/$BRANCH_NAME" "$BRANCH_NAME"
bash
git worktree add ".worktrees/$BRANCH_NAME" "$BRANCH_NAME"

Post-Creation Setup

创建后的设置

Install Dependencies

安装依赖

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

Run Initial Tests

运行初始测试

bash
undefined
bash
undefined

Run test suite

运行测试套件

npm test # or appropriate command
npm test # 或对应命令

Report status

报告状态


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

如果测试失败：报告失败情况，询问是否继续或排查问题。
如果测试通过：报告准备就绪。

Worktree Management

Worktree管理

List Worktrees

列出所有Worktree

bash
git worktree list
bash
git worktree list

Remove Worktree

删除Worktree

bash
undefined
bash
undefined

After merging feature branch

合并功能分支后

git worktree remove ".worktrees/feature/branch-name"
git worktree remove ".worktrees/feature/branch-name"

Force remove (if needed)

强制删除（如有需要）

git worktree remove --force ".worktrees/feature/branch-name"
undefined
git worktree remove --force ".worktrees/feature/branch-name"
undefined

Prune Stale Worktrees

清理过期Worktree

bash
git worktree prune
bash
git worktree prune

Best Practices

最佳实践

Naming Convention

命名规范

  • feature/descriptive-name
    for features
  • bugfix/issue-number-description
    for bugs
  • hotfix/critical-issue
    for urgent fixes
  • 功能分支使用
    feature/descriptive-name
  • Bug修复分支使用
    bugfix/issue-number-description
  • 紧急修复分支使用
    hotfix/critical-issue

Keep Worktrees Focused

保持Worktree聚焦

  • One feature per worktree
  • Merge and remove when done
  • Don't let worktrees accumulate
  • 每个Worktree对应一个功能
  • 完成后合并并删除Worktree
  • 不要让Worktree堆积

Sync Regularly

定期同步

bash
undefined
bash
undefined

In worktree, get latest from main

在Worktree中获取main分支最新代码

git fetch origin git rebase origin/main
undefined
git fetch origin git rebase origin/main
undefined

Completion Checklist

完成清单

When feature is complete:
  1. All tests pass
  2. Code reviewed
  3. Merged to main
  4. Worktree removed
  5. Branch deleted (if desired)
bash
undefined
功能开发完成时：
  1. 所有测试通过
  2. 代码已评审
  3. 已合并到main分支
  4. Worktree已删除
  5. 分支已删除（如有需要）
bash
undefined

Full cleanup

完整清理流程

git checkout main git pull git worktree remove ".worktrees/feature/name" git branch -d feature/name
undefined
git checkout main git pull git worktree remove ".worktrees/feature/name" git branch -d feature/name
undefined

Announcement Template

通知模板

At start of worktree creation:
"I'm using the using-git-worktrees skill to set up an isolated workspace for [feature name]."
On completion:
"Worktree ready at [full-path]
Tests passing ([N] tests, 0 failures)
Ready to implement [feature-name]"
创建Worktree开始时：
"我正在使用using-git-worktrees技能为[功能名称]设置独立工作区。"
创建完成时：
"Worktree已准备就绪，路径为[完整路径]
测试通过（共[N]个测试，0个失败）
已准备好开发[功能名称]"