Git 工作树管理器

git-worktree-manager
分类编程
作者Alireza Rezvani
许可MIT
评分4.40/5
使用5.8K

Git Worktree Manager

等级： POWERFUL
类别： Engineering
领域： Parallel Development & Branch Isolation

概述

使用此技能通过 Git worktrees 安全地运行并行功能开发。它标准化了分支隔离、端口分配、环境同步和清理流程，使每个 worktree 表现得像一个独立的本地应用，而不会干扰其他分支。

该技能针对多智能体工作流进行了优化，每个智能体或终端会话拥有一个独立的 worktree。

核心能力

  • 从新分支或现有分支创建具有确定性命名的 worktree
  • 为每个 worktree 自动分配不冲突的端口并持久化记录
  • 将本地环境文件 (.env*) 从主仓库复制到新 worktree
  • 根据 lockfile 检测结果可选地安装依赖
  • 在清理前检测过期 worktree 和未提交的更改
  • 识别已合并的分支并安全地删除过时的 worktree

使用场景

  • 需要在本地同时打开 2 个或更多并发分支
  • 需要为功能开发、热修复（hotfix）和 PR 验证提供隔离的开发服务器
  • 与多个不能共享分支的智能体协作
  • 当前分支被阻塞，但需要立即发布快速修复
  • 需要可重复的清理流程，而非随机执行 rm -rf 操作

关键工作流

1. 创建完全就绪的 Worktree

1. 选择分支名称和 worktree 名称。
2. 运行管理脚本（如果分支不存在则创建）。
3. 查看生成的端口映射表。
4. 使用分配的端口启动应用。

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

或

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

2. 运行并行会话

推荐约定：

  • 主仓库：集成分支 (main/develop) 使用默认端口
  • Worktree A：功能分支 + 偏移端口
  • Worktree B：热修复分支 + 下一个偏移端口

每个 worktree 包含一个记录分配端口的 .worktree-ports.json 文件。

3. 带安全检查的清理

1. 扫描所有 worktree 及其过期时长。
2. 检查脏树（dirty trees）和分支合并状态。
3. 仅删除已合并且干净的 worktree，或显式强制删除。

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 模式

使用基于分配端口映射的每个 worktree 的覆盖文件。脚本会输出一个确定性的端口映射表；请将其应用于 docker-compose.worktree.yml。

具体模板请参阅 docker-compose-patterns.md。

5. 端口分配策略

默认策略为 base + (index * stride) 并包含冲突检查：

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

完整策略和边界情况请参阅 port-allocation-strategy.md。
案例。

脚本接口

  • python scripts/worktree_manager.py --help
- 创建/列出 worktree - 分配/持久化端口 - 复制 .env* 文件 - 可选的依赖安装
  • python scripts/worktree_cleanup.py --help
- 基于时间的过期检测 - 脏状态（Dirty-state）检测 - 已合并分支检测 - 可选的安全删除

两种工具均支持 stdin JSON 和 --input 文件模式，以便集成到自动化流水线中。

常见陷阱

1. 在主仓库目录内部创建 worktree
2. 在所有分支中重复使用 localhost:3000
3. 在隔离的功能分支之间共享同一个数据库 URL
4. 删除包含未提交更改的 worktree
5. 分支删除后忘记清理旧的元数据
6. 在未对比目标分支的情况下直接假设已合并状态

最佳实践

1. 每个 worktree 对应一个分支，每个 worktree 对应一个 Agent。
2. 保持 worktree 的短生命周期；合并后立即删除。
3. 使用确定性的命名模式（wt-<topic>）。
4. 将端口映射持久化到文件中，而非内存或终端笔记中。
5. 在活跃仓库中每周运行一次清理扫描。
6. 机器流使用 --format json，人工审查使用 --format text。
7. 除非有意丢弃更改，否则绝不要强制删除脏 worktree。

验证清单

在确认设置完成前，请检查：

1. git worktree list 显示预期的路径和分支。
2. .worktree-ports.json 存在且包含唯一端口。
3. .env 文件已成功复制（如果源仓库中存在）。
4. 依赖安装命令退出码为 0（如果已启用）。
5. 清理扫描报告中没有意外的过期脏树。

参考资料

决策矩阵

在创建新 worktree 前，请参考此快速选择指南：

  • 需要隔离的依赖和服务器端口 $\rightarrow$ 创建新 worktree
  • 仅需快速进行本地 diff 审查 $\rightarrow$ 留在当前 tree
  • 功能分支处于脏状态但需要紧急修复 $\rightarrow$ 创建专用 hotfix worktree
  • 需要临时分支进行 Bug 分类 $\rightarrow$ 创建临时 worktree 并在当天清理

操作清单

创建前

1. 确认主仓库具有干净的基线或是有意为之的 WIP 提交。
2. 确认目标分支的命名规范。
3. 确认所需的基础分支存在（main/develop）。
4. 确认没有预留的本地端口被非仓库服务占用。

创建后

1. 验证 git status 分支与预期分支一致。
2. 验证 .worktree-ports.json 存在。
3. 验证应用在分配的端口上能正常启动。
4. 验证数据库和缓存端点指向隔离的端口。

删除前

1. 验证分支具有上游且已按预期合并。
2. 验证没有遗留未提交的文件。
3. 验证没有运行中的容器/进程依赖于此 worktree 路径。

CI 与团队集成

  • 使用与任务 ID 映射的 worktree 路径命名（如 wt-1234-auth）。
  • 在终端标题中包含 worktree 路径，避免在错误的窗口提交。
  • 在自动化设置中，将创建元数据持久化到 CI 产物/日志中。
  • 在定时任务中触发清理报告，并将摘要发送至团队频道。

故障恢复

  • 如果 git worktree add 因路径已存在而失败：检查路径，不要直接覆盖。
  • 如果依赖安装失败：保留已创建的 worktree，标记状态并进行手动恢复。
  • 如果环境文件复制失败：发出警告并列出缺失文件，然后继续执行。
  • 如果端口分配与外部服务冲突：请调整基础端口后重新运行。