git-worktree-manager

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git Worktree Manager

Git工作树管理器

Tier: POWERFUL
Category: Engineering
Domain: Parallel Development & Branch Isolation

级别：功能强大
分类：工程领域
适用场景：并行开发与分支隔离

Overview

概述

Use this skill to run parallel feature work safely with Git worktrees. It standardizes branch isolation, port allocation, environment sync, and cleanup so each worktree behaves like an independent local app without stepping on another branch.

This skill is optimized for multi-agent workflows where each agent or terminal session owns one worktree.

使用此工具通过Git工作树安全地并行开发功能。它标准化了分支隔离、端口分配、环境同步和清理流程，让每个工作树都像独立的本地应用一样运行，不会互相干扰。

此工具针对多Agent工作流优化，每个Agent或终端会话可拥有一个独立工作树。

Core Capabilities

核心功能

Create worktrees from new or existing branches with deterministic naming
Auto-allocate non-conflicting ports per worktree and persist assignments
Copy local environment files (
```
.env*
```
) from main repo to new worktree
Optionally install dependencies based on lockfile detection
Detect stale worktrees and uncommitted changes before cleanup
Identify merged branches and safely remove outdated worktrees

从新分支或现有分支创建工作树，命名规则统一
为每个工作树自动分配无冲突端口并持久化配置
将主仓库的本地环境文件（
```
.env*
```
）复制到新工作树
根据锁文件检测结果可选安装依赖
清理前检测过时工作树和未提交更改
识别已合并分支并安全移除过时工作树

When to Use

使用场景

You need 2+ concurrent branches open locally
You want isolated dev servers for feature, hotfix, and PR validation
You are working with multiple agents that must not share a branch
Your current branch is blocked but you need to ship a quick fix now
You want repeatable cleanup instead of ad-hoc
```
rm -rf
```
operations

你需要在本地同时打开2个及以上分支
你希望为功能开发、热修复和PR验证提供隔离的开发服务器
你正在使用多个Agent，且它们不能共享分支
当前分支被阻塞，但你需要立即发布快速修复
你希望通过可重复的清理流程替代临时的
```
rm -rf
```
操作

Key Workflows

核心工作流

1. Create a Fully-Prepared Worktree

1. 创建完整配置的工作树

Pick a branch name and worktree name.
Run the manager script (creates branch if missing).
Review generated port map.
Start app using allocated ports.

bash

python scripts/worktree_manager.py \
  --repo . \
  --branch feature/new-auth \
  --name wt-auth \
  --base-branch main \
  --install-deps \
  --format text

If you use JSON automation input:

bash

cat config.json | python scripts/worktree_manager.py --format json

选择分支名称和工作树名称。
运行管理器脚本（若分支不存在则创建）。
查看生成的端口映射。
使用分配的端口启动应用。

bash

python scripts/worktree_manager.py \
  --repo . \
  --branch feature/new-auth \
  --name wt-auth \
  --base-branch main \
  --install-deps \
  --format text

如果使用JSON自动化输入：

bash

cat config.json | python scripts/worktree_manager.py --format json

or

或

python scripts/worktree_manager.py --input config.json --format json

undefined

python scripts/worktree_manager.py --input config.json --format json

undefined

2. Run Parallel Sessions

2. 运行并行会话

Recommended convention:

Main repo: integration branch (
```
main
```
/
```
develop
```
) on default port
Worktree A: feature branch + offset ports
Worktree B: hotfix branch + next offset

Each worktree contains

.worktree-ports.json

with assigned ports.

推荐约定：

主仓库：集成分支（
```
main
```
/
```
develop
```
）使用默认端口
工作树A：功能分支 + 偏移端口
工作树B：热修复分支 + 下一组偏移端口

每个工作树包含

.worktree-ports.json

文件，记录分配的端口。

3. Cleanup with Safety Checks

3. 带安全检查的清理

Scan all worktrees and stale age.
Inspect dirty trees and branch merge status.
Remove only merged + clean worktrees, or force explicitly.

bash

python scripts/worktree_cleanup.py --repo . --stale-days 14 --format text
python scripts/worktree_cleanup.py --repo . --remove-merged --format text

扫描所有工作树及其过时时长。
检查未提交更改的工作树和分支合并状态。
仅移除已合并且无未提交更改的工作树，或显式强制移除。

bash

python scripts/worktree_cleanup.py --repo . --stale-days 14 --format text
python scripts/worktree_cleanup.py --repo . --remove-merged --format text

4. Docker Compose Pattern

4. Docker Compose 模式

Use per-worktree override files mapped from allocated ports. The script outputs a deterministic port map; apply it to

docker-compose.worktree.yml

See docker-compose-patterns.md for concrete templates.

使用每个工作树的覆盖文件映射分配的端口。脚本会输出确定的端口映射，将其应用到

docker-compose.worktree.yml

。

具体模板请查看docker-compose-patterns.md。

5. Port Allocation Strategy

5. 端口分配策略

Default strategy is

base + (index * stride)

with collision checks:

App:
```
3000
```
Postgres:
```
5432
```
Redis:
```
6379
```
Stride:
```
10
```

See port-allocation-strategy.md for the full strategy and edge cases.

默认策略是

基准端口 + （索引 * 步长）

，并包含冲突检测：

应用：
```
3000
```
Postgres：
```
5432
```
Redis：
```
6379
```
步长：
```
10
```

完整策略和边缘情况请查看port-allocation-strategy.md。

Script Interfaces

脚本接口

```
python scripts/worktree_manager.py --help
```
- Create/list worktrees
- Allocate/persist ports
- Copy
```
.env*
```
  files
- Optional dependency installation
```
python scripts/worktree_cleanup.py --help
```
- Stale detection by age
- Dirty-state detection
- Merged-branch detection
- Optional safe removal

Both tools support stdin JSON and

--input

file mode for automation pipelines.

```
python scripts/worktree_manager.py --help
```
- 创建/列出工作树
- 分配/持久化端口
- 复制
```
.env*
```
  文件
- 可选依赖安装
```
python scripts/worktree_cleanup.py --help
```
- 根据时长检测过时工作树
- 检测未提交更改状态
- 检测已合并分支
- 可选安全移除

这两个工具都支持标准输入JSON和

--input

文件模式，适用于自动化流水线。

Common Pitfalls

常见误区

Creating worktrees inside the main repo directory
Reusing
```
localhost:3000
```
across all branches
Sharing one database URL across isolated feature branches
Removing a worktree with uncommitted changes
Forgetting to prune old metadata after branch deletion
Assuming merged status without checking against the target branch

在主仓库目录内创建工作树
在所有分支中重复使用
```
localhost:3000
```
在隔离的功能分支之间共享同一个数据库URL
移除包含未提交更改的工作树
分支删除后忘记清理旧元数据
未与目标分支核对就假设分支已合并

Best Practices

最佳实践

One branch per worktree, one agent per worktree.
Keep worktrees short-lived; remove after merge.
Use a deterministic naming pattern (
```
wt-<topic>
```
).
Persist port mappings in file, not memory or terminal notes.
Run cleanup scan weekly in active repos.
Use
```
--format json
```
for machine flows and
```
--format text
```
for human review.
Never force-remove dirty worktrees unless changes are intentionally discarded.

一个工作树对应一个分支，一个Agent对应一个工作树。
工作树生命周期尽量短，合并后立即移除。
使用统一的命名规则（
```
wt-<主题>
```
）。
将端口映射持久化到文件，而非内存或终端笔记。
在活跃仓库中每周运行一次清理扫描。
机器流程使用
```
--format json
```
格式，人工审核使用
```
--format text
```
格式。
除非有意丢弃更改，否则切勿强制移除包含未提交更改的工作树。

Validation Checklist

验证清单

Before claiming setup complete:

```
git worktree list
```
shows expected path + branch.
```
.worktree-ports.json
```
exists and contains unique ports.
```
.env
```
files copied successfully (if present in source repo).
Dependency install command exits with code
```
0
```
(if enabled).
Cleanup scan reports no unintended stale dirty trees.

在确认设置完成前，请检查以下内容：

```
git worktree list
```
显示预期的路径和分支。
```
.worktree-ports.json
```
存在且包含唯一端口。
```
.env
```
文件已成功复制（若源仓库存在）。
依赖安装命令返回码为
```
0
```
（若启用）。
清理扫描未报告意外的过时未提交工作树。

References

参考文档

port-allocation-strategy.md
docker-compose-patterns.md
README.md for quick start and installation details

port-allocation-strategy.md
docker-compose-patterns.md
README.md 快速开始和安装详情

Decision Matrix

决策矩阵

Use this quick selector before creating a new worktree:

Need isolated dependencies and server ports -> create a new worktree
Need only a quick local diff review -> stay on current tree
Need hotfix while feature branch is dirty -> create dedicated hotfix worktree
Need ephemeral reproduction branch for bug triage -> create temporary worktree and cleanup same day

创建新工作树前，请使用以下快速选择指南：

需要隔离的依赖和服务器端口 -> 创建新工作树
仅需要快速本地差异审查 -> 保留当前工作树
当前功能分支有未提交更改但需要热修复 -> 创建专用热修复工作树
需要临时分支用于bug排查 -> 创建临时工作树并在当天清理

Operational Checklist

操作清单

Before Creation

创建前

Confirm main repo has clean baseline or intentional WIP commits.
Confirm target branch naming convention.
Confirm required base branch exists (
```
main
```
/
```
develop
```
).
Confirm no reserved local ports are already occupied by non-repo services.

确认主仓库有干净的基线或有意保留的未提交更改。
确认目标分支符合命名规范。
确认所需的基准分支存在（
```
main
```
/
```
develop
```
）。
确认没有预留的本地端口被非仓库服务占用。

After Creation

创建后

Verify
```
git status
```
branch matches expected branch.
Verify
```
.worktree-ports.json
```
exists.
Verify app boots on allocated app port.
Verify DB and cache endpoints target isolated ports.

验证
```
git status
```
显示的分支与预期一致。
验证
```
.worktree-ports.json
```
存在。
验证应用能在分配的端口启动。
验证数据库和缓存端点指向隔离的端口。

Before Removal

移除前

Verify branch has upstream and is merged when intended.
Verify no uncommitted files remain.
Verify no running containers/processes depend on this worktree path.

验证分支已关联上游且按预期合并。
验证没有未提交文件残留。
验证没有运行中的容器/进程依赖此工作树路径。

CI and Team Integration

CI与团队集成

Use worktree path naming that maps to task ID (
```
wt-1234-auth
```
).
Include the worktree path in terminal title to avoid wrong-window commits.
In automated setups, persist creation metadata in CI artifacts/logs.
Trigger cleanup report in scheduled jobs and post summary to team channel.

使用与任务ID对应的工作树路径命名（
```
wt-1234-auth
```
）。
在终端标题中包含工作树路径，避免在错误窗口提交。
在自动化设置中，将创建元数据持久化到CI制品/日志中。
在定时任务中触发清理报告，并将摘要发布到团队频道。

Failure Recovery

故障恢复

If
```
git worktree add
```
fails due to existing path: inspect path, do not overwrite.
If dependency install fails: keep worktree created, mark status and continue manual recovery.
If env copy fails: continue with warning and explicit missing file list.
If port allocation collides with external service: rerun with adjusted base ports.

若
```
git worktree add
```
因路径已存在失败：检查路径，不要覆盖。
若依赖安装失败：保留已创建的工作树，标记状态并手动恢复。
若环境文件复制失败：继续执行并显示警告和缺失文件列表。
若端口分配与外部服务冲突：调整基准端口后重新运行。