using-git-worktrees

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Using Git Worktrees

使用Git Worktrees

Overview

概述

Create isolated working directories for parallel development tasks using

git worktree

, allowing multiple branches to be checked out simultaneously without conflicts. This skill enforces a deterministic, multi-phase process from directory selection through setup verification, ensuring every worktree is production-ready before any work begins.

通过

git worktree

为并行开发任务创建隔离的工作目录，支持同时检出多个分支且无冲突。本技能遵循确定性的多阶段流程，从目录选择到设置校验全链路覆盖，确保所有worktree在开始工作前均达到生产可用标准。

When to Use

适用场景

Starting a new feature branch that should not interfere with current work
Working on multiple tasks simultaneously (bug fix + feature)
Creating a clean environment for testing or code review
Running long processes (tests, builds) while continuing development

开启不会影响当前工作的新功能分支
同时处理多项任务（比如修复Bug+开发新功能）
为测试或代码评审创建干净环境
运行长时间流程（测试、构建）的同时继续开发工作

Phase 1: Select Worktree Directory

阶段1：选择Worktree目录

[HARD-GATE] Do NOT skip directory selection. Do NOT assume a default path without checking priorities.

Follow this priority order exactly:

[强制门槛] 不得跳过目录选择步骤，未确认优先级前不得假设默认路径。

严格遵循以下优先级顺序：

Priority 1: Existing Worktree Matching Task

优先级1：匹配当前任务的已有Worktree

Check if a worktree already exists for the task:

bash

git worktree list

If a matching worktree exists, use it. Do NOT create a duplicate.

检查当前任务是否已存在对应worktree：

bash

git worktree list

如果存在匹配的worktree，直接复用即可，不得创建重复实例。

Priority 2: CLAUDE.md Worktree Directory Hint

优先级2：CLAUDE.md中的Worktree目录配置提示

Check the project's CLAUDE.md for a configured worktree directory:

undefined

检查项目CLAUDE.md文件中是否配置了worktree存储目录：

undefined

Example CLAUDE.md entry

CLAUDE.md配置示例

worktree-directory: ../worktrees


If specified, create worktrees under that directory.

worktree-directory: ../worktrees


如果有指定配置，在该目录下创建worktree。

Priority 3: Ask the User

优先级3：询问用户

If no hint is configured and no convention is obvious, ask the user where worktrees should be created. Suggest a sensible default:

../worktrees/<project-name>/<branch-name>

STOP — Confirm the worktree directory with the user before proceeding.

如果没有配置提示且没有明确的使用惯例，询问用户希望将worktree创建在哪个位置，可提供合理的默认路径建议：

../worktrees/<项目名称>/<分支名称>

暂停 — 继续操作前需先和用户确认worktree存储目录。

Directory Selection Decision Table

目录选择决策表

Condition	Action
Worktree for this branch already exists	Navigate to existing worktree
CLAUDE.md has `worktree-directory`	Use configured path
Project has existing worktrees	Use same parent directory pattern
No convention found	Ask user, suggest `../worktrees/<project>/<branch>`
User specifies path inside repo root	Warn — must add to `.gitignore`

条件	操作
目标分支对应的worktree已存在	直接进入已有worktree
CLAUDE.md中配置了 `worktree-directory`	使用配置的路径
项目已有现存的worktree	沿用相同的父目录规则
未找到使用惯例	询问用户，建议路径为 `../worktrees/<项目名>/<分支名>`
用户指定的路径在仓库根目录内	发出警告 — 必须将该路径添加到 `.gitignore` 中

Phase 2: Safety Verification

阶段2：安全校验

[HARD-GATE] Do NOT create any worktree until all safety checks pass.

[强制门槛] 所有安全检查通过前，不得创建任何worktree。

Check .gitignore Coverage

校验.gitignore覆盖情况

If the worktree directory is inside the repository root, ensure it is in

.gitignore

bash

undefined

如果worktree目录在仓库根目录内，确保该路径已被加入

.gitignore

：

bash

undefined

Check if the worktree path would be tracked

检查worktree路径是否会被Git追踪

git check-ignore <worktree-path>


If not ignored, warn the user and suggest adding it to `.gitignore`.

git check-ignore <worktree-path>


如果未被忽略，向用户发出警告并建议将其添加到`.gitignore`中。

Verify Clean Working Tree

校验工作树状态干净

Check for uncommitted changes that could cause issues:

bash

git status --porcelain

If the working tree is dirty, inform the user and ask how to proceed:

Commit changes first
Stash changes
Proceed anyway (worktree creation itself is safe)

检查是否存在可能引发问题的未提交变更：

bash

git status --porcelain

如果工作树状态为脏，告知用户并询问后续处理方式：

先提交变更
暂存变更
继续操作（worktree创建本身是安全的）

Verify Branch Does Not Exist in Another Worktree

校验分支未在其他Worktree中检出

bash

git worktree list

A branch cannot be checked out in two worktrees simultaneously. If the branch is already checked out, navigate to that existing worktree instead.

bash

git worktree list

同一个分支不能同时在两个worktree中检出，如果分支已经被其他worktree检出，直接进入该已有worktree即可。

Safety Check Decision Table

安全检查决策表

Check	Result	Action
Path inside repo, not in `.gitignore`	FAIL	Add to `.gitignore` first
Branch already in another worktree	FAIL	Use existing worktree
Working tree dirty	WARN	Inform user, ask preference
Path already exists (not worktree)	FAIL	Choose different path
All checks pass	PASS	Proceed to Phase 3

检查项	结果	操作
路径在仓库内，且未加入 `.gitignore`	不通过	先将路径添加到 `.gitignore`
分支已在其他worktree中检出	不通过	使用已有worktree
工作树状态为脏	警告	告知用户，询问处理偏好
路径已存在（非worktree）	不通过	选择其他路径
所有检查通过	通过	进入阶段3

Phase 3: Create the Worktree

阶段3：创建Worktree

bash

undefined

bash

undefined

For a new branch

用于创建新分支的场景

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

For an existing branch

用于已有分支的场景

git worktree add <path> <existing-branch>


Always tell the user the full path where the worktree was created:

Worktree created at: /absolute/path/to/worktree Branch: feature/my-feature Base: main


**STOP — Confirm the worktree was created successfully before proceeding to setup.**

git worktree add <path> <existing-branch>


必须告知用户worktree创建的完整路径：

Worktree创建路径：/absolute/path/to/worktree 分支：feature/my-feature 基分支：main


**暂停 — 继续后续设置前需先确认worktree创建成功。**

Phase 4: Project Setup and Auto-Detection

阶段4：项目设置与自动检测

After creating the worktree, detect and run the project's setup commands.

创建worktree后，检测并运行项目的初始化设置命令。

Setup Detection Decision Table

初始化检测决策表

Indicator File	Ecosystem	Setup Command
`pnpm-lock.yaml`	Node.js (pnpm)	`pnpm install`
`yarn.lock`	Node.js (yarn)	`yarn install`
`package-lock.json`	Node.js (npm)	`npm install`
`package.json` (no lock)	Node.js (npm)	`npm install`
`pyproject.toml` + `tool.poetry`	Python (poetry)	`poetry install`
`pyproject.toml` (no poetry)	Python (pip)	`pip install -e .`
`setup.py`	Python (pip)	`pip install -e .`
`requirements.txt`	Python (pip)	`pip install -r requirements.txt`
`go.mod`	Go	`go mod download`
`Cargo.toml`	Rust	`cargo build`
`Gemfile`	Ruby	`bundle install`
`composer.json`	PHP	`composer install`

标识文件	技术栈	初始化命令
`pnpm-lock.yaml`	Node.js (pnpm)	`pnpm install`
`yarn.lock`	Node.js (yarn)	`yarn install`
`package-lock.json`	Node.js (npm)	`npm install`
`package.json` (无锁文件)	Node.js (npm)	`npm install`
`pyproject.toml` + `tool.poetry`	Python (poetry)	`poetry install`
`pyproject.toml` (无poetry配置)	Python (pip)	`pip install -e .`
`setup.py`	Python (pip)	`pip install -e .`
`requirements.txt`	Python (pip)	`pip install -r requirements.txt`
`go.mod`	Go	`go mod download`
`Cargo.toml`	Rust	`cargo build`
`Gemfile`	Ruby	`bundle install`
`composer.json`	PHP	`composer install`

Multiple Ecosystems

多技术栈场景

If the project uses multiple ecosystems (e.g., a Go backend with a Node.js frontend), run setup for each detected ecosystem in the appropriate subdirectories.

如果项目使用多技术栈（比如Go后端搭配Node.js前端），在对应的子目录下为每个检测到的技术栈分别运行初始化命令。

Environment Files

环境变量文件

If the project has

.env.example

.env.template

bash

undefined

如果项目存在

.env.example

或

.env.template

：

bash

undefined

Copy environment template if .env does not exist in worktree

如果worktree中不存在.env文件，复制环境变量模板

cp .env.example .env # then inform user to update values

undefined

cp .env.example .env # 之后告知用户更新配置值

undefined

Phase 5: Clean Baseline Test Verification

阶段5：干净基准测试校验

[HARD-GATE] Do NOT proceed with any work until baseline tests pass or failures are acknowledged.

Run the project's test suite to establish a clean baseline BEFORE starting any work:

bash

undefined

[强制门槛] 基准测试通过或失败原因确认前，不得开展任何开发工作。

开始工作前先运行项目测试套件，确认基准环境正常：

bash

undefined

Use the project's test command

使用项目对应的测试命令

Node.js: npm test / yarn test / pnpm test

Python: pytest / python -m pytest

Go: go test ./...

Rust: cargo test


Purpose:
- Confirms the worktree is set up correctly
- Establishes that all tests pass before changes are made
- Any test failures after this point are caused by your changes, not pre-existing issues

If baseline tests fail:
- Report the failures to the user
- Do NOT proceed with work until the baseline is understood
- The base branch may have broken tests that need addressing first


目的：
- 确认worktree配置正确
- 确认修改前所有测试均能通过
- 后续出现的测试失败均由你的修改导致，而非预存问题

如果基准测试失败：
- 向用户上报失败情况
- 基准问题确认前不得继续开发
- 可能是基分支本身存在损坏的测试，需要先修复

Phase 6: Location Reporting

阶段6：位置上报

Always report the worktree location clearly to the user:

Worktree ready:
  Path:    /Users/dev/worktrees/myproject/feature-auth
  Branch:  feature/auth-refactor
  Base:    main
  Setup:   npm install (completed)
  Tests:   24 passed, 0 failed

必须清晰向用户告知worktree的位置信息：

Worktree已就绪:
  路径:    /Users/dev/worktrees/myproject/feature-auth
  分支:  feature/auth-refactor
  基分支:    main
  初始化:   npm install (已完成)
  测试:   24 passed, 0 failed

Cleanup Patterns

清理规则

After Merging or Completing Work

合并或完成工作后

bash

undefined

bash

undefined

Remove the worktree

移除worktree

git worktree remove <path>

If files remain (dirty worktree), force removal

如果有残留文件（脏worktree），强制移除

git worktree remove --force <path>

Prune stale worktree references

清理失效的worktree引用

git worktree prune

undefined

git worktree prune

undefined

List All Worktrees

列出所有Worktree

bash

git worktree list

bash

git worktree list

Handling Locked Worktrees

处理被锁定的Worktree

If a worktree is locked (to prevent accidental removal):

bash

undefined

如果worktree被锁定（防止误删）：

bash

undefined

Unlock before removing

移除前先解锁

git worktree unlock <path> git worktree remove <path>

undefined

git worktree unlock <path> git worktree remove <path>

undefined

Anti-Patterns / Common Mistakes

反模式/常见错误

Anti-Pattern	Why It Is Wrong	What to Do Instead
Creating duplicate worktree for same branch	Git does not allow it; wastes time	Check `git worktree list` first
Worktree inside repo without `.gitignore`	Worktree files show as untracked	Add path to `.gitignore`
Skipping dependency install in worktree	Build/test failures from missing deps	Always run project setup
Skipping baseline test run	Cannot distinguish pre-existing vs new failures	Run tests before starting work
Assuming worktree has same env vars	`.env` files are not shared between worktrees	Copy and configure `.env`
Leaving stale worktrees after merge	Disk waste, confusing `git worktree list`	Remove worktrees after branch completion
Force-removing worktree with uncommitted work	Permanent data loss	Commit or stash first

反模式	错误原因	正确做法
为同一个分支创建重复的worktree	Git不支持该操作，浪费时间	先执行 `git worktree list` 检查
Worktree在仓库内但未加入 `.gitignore`	Worktree文件会被识别为未追踪文件	将路径添加到 `.gitignore`
跳过worktree的依赖安装步骤	缺少依赖会引发构建/测试失败	始终运行项目初始化命令
跳过基准测试运行	无法区分是预存问题还是新修改导致的失败	开始工作前先运行测试
假设worktree共享相同的环境变量	`.env` 文件不会在worktree之间共享	复制并配置 `.env` 文件
合并后残留过时的worktree	浪费磁盘空间， `git worktree list` 输出混乱	分支处理完成后移除对应worktree
强制移除存在未提交工作的worktree	永久丢失数据	先提交或暂存修改

Integration Points

集成点

Skill	Integration
`finishing-a-development-branch`	After completing work in a worktree, use this to merge or create a PR
`dispatching-parallel-agents`	Run agents in separate worktrees for true isolation
`verification-before-completion`	Validate work before leaving the worktree
`self-learning`	Check CLAUDE.md for worktree directory preferences
`planning`	Worktree creation is often the first step of plan execution

技能	集成逻辑
`finishing-a-development-branch`	完成worktree内的工作后，使用该技能合并代码或创建PR
`dispatching-parallel-agents`	在独立的worktree中运行Agent实现真正的隔离
`verification-before-completion`	退出worktree前校验工作成果
`self-learning`	检查CLAUDE.md获取worktree目录偏好配置
`planning`	创建worktree通常是计划执行的第一步

Skill Type

技能类型

RIGID — Follow this process exactly. Every phase must be completed in order. Do NOT skip safety checks. Do NOT skip baseline test verification. Do NOT create worktrees without confirming the directory.

严格执行型 — 必须严格遵循本流程，所有阶段必须按顺序完成。不得跳过安全检查，不得跳过基准测试校验，未确认目录前不得创建worktree。