worktree

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git Worktree Management

Git Worktree 管理

Iron Law

铁律

NEVER MODIFY FILES IN A WORKTREE YOU DID NOT CREATE

切勿修改非你创建的worktree中的文件

Operations

操作指南

1. Create

1. 创建

Create a new worktree for isolated parallel development.

bash

git worktree add <path> -b <branch-name>

Always use a descriptive branch name matching the worktree purpose
Place worktrees in a consistent location (e.g.,
```
/tmp/<repo>-worktrees/<name>
```
)
Verify the worktree was created successfully before proceeding
Initialize any required workspace files (progress.txt, CLAUDE.md, prd.json)

为独立的并行开发创建新的worktree。

bash

git worktree add <path> -b <branch-name>

始终使用与worktree用途匹配的描述性分支名称
将worktree放置在统一的位置（例如：
```
/tmp/<repo>-worktrees/<name>
```
）
在继续操作前验证worktree是否创建成功
初始化所有必要的工作区文件（progress.txt、CLAUDE.md、prd.json）

2. List

2. 列出

Show all active worktrees and their branches.

bash

git worktree list

Check for stale or orphaned worktrees
Verify each worktree points to a valid path
Note which branches are checked out where

显示所有活跃的worktree及其对应的分支。

bash

git worktree list

检查是否存在过期或孤立的worktree
验证每个worktree是否指向有效的路径
记录哪些分支在哪个位置被检出

3. Switch

3. 切换

Navigate between worktrees safely.

Always verify your current working directory before making changes
Use absolute paths to avoid confusion
Check
```
git status
```
in the target worktree before starting work
Never assume you are in the correct worktree — verify with
```
pwd
```
and
```
git branch
```

安全地在不同worktree之间切换。

在进行更改前始终验证当前工作目录
使用绝对路径避免混淆
在开始工作前检查目标worktree的
```
git status
```
永远不要假设你处于正确的worktree中——务必用
```
pwd
```
和
```
git branch
```
验证

4. Sync

4. 同步

Keep worktrees up to date with upstream changes.

bash

undefined

保持worktree与上游更改同步。

bash

undefined

From within the worktree:

在worktree内执行：

git fetch origin git rebase origin/main # or merge, depending on strategy

- Resolve conflicts in the worktree where they occur
- Do not sync during active implementation — finish the current story first
- After syncing, re-run quality checks to catch integration issues

git fetch origin git rebase origin/main # 或使用merge，取决于策略

- 在冲突所在的worktree中解决冲突
- 不要在活跃开发期间同步——先完成当前任务
- 同步后重新运行质量检查，发现集成问题

5. Cleanup

5. 清理

Remove worktrees that are no longer needed.

bash

git worktree remove <path>
git worktree prune

Verify all changes are committed and pushed before removing
Never force-remove a worktree with uncommitted changes
Prune stale references after removal
Delete the associated branch only after confirming the merge

移除不再需要的worktree。

bash

git worktree remove <path>
git worktree prune

在移除前验证所有更改已提交并推送
切勿强制移除包含未提交更改的worktree
移除后清理过期的引用
仅在确认合并完成后删除关联分支

Red Flags — If You Catch Yourself Thinking:

警示信号——如果你有以下想法：

Thought	Reality
"I'll just edit files in this other worktree quickly"	Each worktree is an isolated workspace. Switch properly or create a new one.
"I don't need to check which worktree I'm in"	Wrong worktree = wrong branch = wrong commits. ALWAYS verify with pwd and git branch.
"I'll force-remove this worktree to save time"	Force-remove destroys uncommitted work. Check git status first.
"Pruning is optional, I'll do it later"	Stale worktree references cause confusing errors. Prune after every removal.

想法	实际情况
"我就快速编辑一下这个其他worktree里的文件"	每个worktree都是独立的工作区。请正确切换或创建新的worktree。
"我不需要检查自己在哪个worktree里"	错误的worktree = 错误的分支 = 错误的提交。务必用pwd和git branch验证。
"我要强制移除这个worktree来节省时间"	强制移除会销毁未提交的工作内容。先检查git status。
"清理是可选的，我之后再做"	过期的worktree引用会导致令人困惑的错误。每次移除后都要清理。

Rules

规则

Always verify your working directory before making any changes
Never force-remove a worktree without checking for uncommitted changes
Prune stale worktree references after every removal
Use absolute paths for all worktree operations
One branch per worktree — never checkout a branch that is active in another worktree

在进行任何更改前始终验证当前工作目录
切勿在未检查未提交更改的情况下强制移除worktree
每次移除后清理过期的worktree引用
所有worktree操作都使用绝对路径
一个worktree对应一个分支——永远不要检出在另一个worktree中活跃的分支