git-worktree-manager

git-worktree-manager skill 概览

git-worktree-manager 能做什么

git-worktree-manager 是一个面向工程工作的 skill，用来同时管理多个本地 Git worktree，避免分支、端口、环境文件和清理流程互相冲突。它把操作指南和 Python 辅助脚本结合在一起，可以创建已准备好的 worktree、分配确定性的端口、复制本地环境文件、按需安装依赖，并在删除前检查过期的 worktree。

当普通的 git worktree 命令不够用，尤其是每个分支都需要像一个独立可运行应用一样工作时，就适合使用这个 skill。

适合并行 Git 工作流的场景

最适合使用它的人，是需要同时打开两个或更多分支的开发者、技术负责人或 coding-agent 操作者：例如功能开发、hotfix、PR review、迁移测试，或多 agent 并行实现。git-worktree-manager for Git Workflows 尤其适合每个 agent 或终端会话都应该独占一个分支和一套隔离运行环境，而不是共享同一个 checkout 的场景。

如果你只是偶尔切换分支、不运行本地服务，或者团队内部已经有成熟的 worktree 封装工具，那么它的价值会相对有限。

安装前值得关注的差异点

它的实际价值不只是“创建一个 worktree”。这个 skill 提供了一套可重复执行的约定，包括：

• 确定性的 worktree 命名和分支创建
• 不重叠的 app、database 和 Redis 端口分配
• .env、.env.local、.env.development 和 .envrc 同步
• 基于常见 lockfile 的依赖安装检测
• 对过期、dirty 以及已合并分支的清理检查
• 面向每个 worktree 服务隔离的 Docker Compose 模式

因此，git-worktree-manager skill 更偏向可落地的工程操作，而不是一段泛泛介绍 Git worktree 的提示词。

如何使用 git-worktree-manager skill

git-worktree-manager 安装选项

如果你使用 Claude 风格的 skills 配置，并且有可用的 skill manager，可以从仓库安装：

npx skills add alirezarezvani/claude-skills --skill git-worktree-manager

如果手动安装，请从以下位置复制 skill 目录：

engineering/skills/git-worktree-manager

复制到你的本地 skills 文件夹，例如 ~/.claude/skills/git-worktree-manager、~/.codex/skills/git-worktree-manager，或其他兼容的 agent skill 目录。安装后，确认这些文件存在：SKILL.md、README.md、scripts/worktree_manager.py、scripts/worktree_cleanup.py，以及 references/ 下的两个文件。

优先阅读这些文件

为了快速上手，建议按这个顺序阅读：

1. README.md：了解命令形态和工具列表。
2. SKILL.md：了解预期工作流以及适用场景。
3. references/port-allocation-strategy.md：在修改服务端口前先读它。
4. references/docker-compose-patterns.md：如果你的应用使用 Compose，请阅读它。
5. scripts/worktree_manager.py 和 scripts/worktree_cleanup.py：在生产仓库里信任自动化之前，先审阅脚本。

这一步很重要，因为这些脚本会操作真实 checkout、复制 env 文件，并且可能安装依赖。在大型 monorepo 或包含敏感本地配置的仓库中运行之前，务必先检查默认行为。

git-worktree-manager 的实际用法

一个典型的创建并准备 worktree 的流程如下：

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

一个清理前审查流程如下：

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

两个工具都支持通过 --input <json-file> 或 stdin 读取 JSON 输入，适合自动化场景。建议先让 agent 生成命令计划，在你确认 repo path、branch name、base branch、依赖安装行为和清理策略之后，再运行脚本。

让输出更可靠的提示词写法

较弱的提示词：

Set up a worktree for my feature.

更强的提示词：

Use git-worktree-manager to prepare a new worktree for branch feature/billing-webhooks from main in repo /Users/me/app. Name it wt-billing-webhooks. I run app, Postgres, and Redis locally, so allocate non-conflicting ports and write the resulting mapping. Copy env files but do not install dependencies until I approve the command. Show the exact script command and any Docker Compose override I may need.

这样的描述能给 skill 足够的信息来选择分支策略、避免端口冲突、谨慎处理 .env* 文件，并把规划和执行分开。

git-worktree-manager skill 常见问题

git-worktree-manager 只适合 AI agents 吗？

不是。这个 skill 针对 multi-agent 工作做了优化，但其中的脚本和约定对人类开发者同样有用。它的主要收益是可重复性：每个 worktree 都能获得可预测的分支、目录、端口、复制的 env 文件，以及清理前审查，而不是依赖临时的 shell history。

它和普通的 git worktree 有什么区别？

普通的 git worktree add 只是创建另一个 checkout，并不会解决本地应用之间的冲突。git-worktree-manager 补上了外围工作流：端口块、.worktree-ports.json、环境文件复制、可选的依赖安装、Docker Compose 隔离建议，以及针对过期或已合并分支的清理检查。

新手可以安全使用吗？

可以，但应把它当作有引导的工作流，而不是盲目执行命令的工具。新手应该先运行 list/review 类操作，使用 --format text，避免自动删除，并在执行前检查生成的命令。清理脚本会检查 dirty worktree，但你仍然需要理解哪些分支可以安全删除。

什么时候不应该使用这个 skill？

如果你的仓库有特殊的环境处理方式、绝不能复制的 secrets、非标准依赖安装流程，或服务端口由内部平台统一管理，就不要直接原样使用。在这些情况下，可以把 git-worktree-manager guide 当作起点模式，在采用前先定制脚本或提示词。

如何改进 git-worktree-manager skill

给 git-worktree-manager 更完整的仓库上下文

输入越准确，worktree 计划就越安全。建议提供：

• absolute repo path
• target branch and base branch
• desired worktree directory name
• package manager or lockfile expectations
• services that need ports
• whether .env* files may be copied
• whether dependency install is allowed
• cleanup age threshold and base branch for merge checks

这样可以减少猜测，避免 agent 使用并不适合你应用的默认值。

调整端口和 Docker Compose 约定

参考策略使用的默认基准包括 app 3000、Postgres 5432、Redis 6379，并为每个 worktree 使用 10 的 stride。如果你的技术栈有更多服务，请预留更大的连续端口块。如果你在 worktree 外部运行本地基础设施，请偏移 base ports，避免全局冲突。

对于 Docker Compose，优先使用每个 worktree 单独的 overrides、由 .env 驱动的端口，以及唯一的 project names，例如：

docker compose -p myapp_wt_auth up -d

这样可以避免不同分支之间的 container、network、volume 和 database 冲突。

留意常见失败模式

最常见的问题包括复制了 secrets、复用默认 database ports、在不兼容迁移之间共享 Docker volumes、在错误 runtime 中安装依赖，以及删除仍有未提交内容的 worktree。每次运行后，都应要求 agent 报告 dirty status、复制了哪些 env files、选择了哪些 ports，以及执行了哪些 install actions。

清理时，请从仅审查输出开始。只有在确认某个 worktree 已过期、干净，并且已合并到预期 base branch 后，再启用删除。

根据首次输出继续迭代

拿到第一个计划或命令后，不要从头开始，而是要求有针对性地修订：

Revise the git-worktree-manager command to skip dependency installation, use base branch develop, reserve ports for app, Postgres, Redis, and Mailhog, and output JSON for automation.

这样可以让 skill 始终围绕仓库的真实约束进行调整，同时提升安全性和可复现性。