git-worktree-manager

Git Worktree 管理器

等级: POWERFUL
类别: Engineering
领域: 并行开发与分支隔离

概述

使用此 Skill 可借助 Git worktree 安全地并行推进功能开发。它将分支隔离、端口分配、环境同步和清理标准化,使每个 worktree 都像一个独立的本地应用,而不会干扰其他分支。

此 Skill 针对多 Agent 工作流进行了优化,即每个 Agent 或终端会话各自管理一个 worktree。

核心能力

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

适用场景

• 你需要在本地同时打开 2 个及以上的并发分支
• 你希望为功能开发、热修复和 PR 验证分别运行隔离的开发服务器
• 你正在与多个 Agent 协作,且它们不能共享同一分支
• 当前分支被阻塞,但你需要立即发布一个快速修复
• 你希望进行可重复的清理,而不是临时执行 rm -rf 操作

关键工作流

1. 创建已完成准备的 worktree

1. 选择分支名和 worktree 名。
2. 运行管理器脚本(若分支不存在则自动创建)。
3. 查看生成的端口映射。
4. 使用分配的端口启动应用。

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

如果你使用 JSON 格式的自动化输入:

cat config.json | python scripts/worktree_manager.py --format json
# or
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. 检查有未提交更改的工作区以及分支的合并状态。
3. 仅移除已合并且干净的 worktree,或明确使用强制选项移除。

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),并进行冲突检查:

• 应用: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
  • 按时间检测过期 worktree
  • 检测脏状态
  • 检测已合并分支
  • 可选的安全移除

两个工具均支持 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. 清理扫描未报告任何非预期的过期脏工作树。

参考资料

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

决策矩阵

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

• 需要隔离的依赖和服务端口 -> 创建新工作树
• 只需快速查看本地差异 -> 留在当前工作树
• 功能分支有未提交改动时需要热修复 -> 创建专用的热修复工作树
• 需要为缺陷分诊创建临时复现分支 -> 创建临时工作树，并在当天清理

操作检查清单

创建之前

1. 确认主仓库处于干净的基线状态，或有有意提交的 WIP 提交。
2. 确认目标分支的命名约定。
3. 确认所需的基础分支存在（main/develop）。
4. 确认保留的本地端口没有被非本仓库的服务占用。

创建之后

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

删除之前

1. 在预期合并的情况下，验证分支已设置上游并已合并。
2. 验证没有未提交的文件残留。
3. 验证没有正在运行的容器或进程依赖此工作树路径。

CI 与团队集成

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

故障恢复

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