SuperAPI AI 工具集

git-worktree

编程与开发

查看项目

更新于 11-12 22:25

技能介绍

用途

git-worktree 是一个管理 Git worktree 的技能,用于隔离的并行开发。它提供统一接口,处理代码评审隔离、多特性并行开发以及完成后的清理等场景。资料强调:始终通过 worktree-manager.sh 脚本操作,不要直接调用 git worktree add,因为脚本会完成原始命令不具备的关键初始化。

主要能力

  • 从 main 分支创建带清晰分支名的 worktree;
  • 列出所有 worktree 及其当前状态;
  • 在 worktree 之间切换以进行并行工作;
  • 自动清理已完成的 worktree;
  • 每个步骤提供交互式确认;
  • 自动管理 .worktrees 目录的 .gitignore;
  • 自动从主仓库向新 worktree 复制 .env 文件(如 .env、.env.local、.env.test 等)。

使用方式

脚本路径为 ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh。正确示例:

bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-name

资料明确禁止直接执行:

git worktree add .worktrees/feature-name -b feature-name main

命令

  • create <branch-name> [from-branch]:创建新 worktree 与分支。branch-name 必填,from-branch 可选(默认 main)。流程包括:检查是否已存在、从远程更新基础分支、创建 worktree 和分支、复制所有 .env 文件、显示路径。
  • list 或 ls:列出可用 worktree、分支、当前所在项(以 ✓ 标记)以及主仓库状态。
  • switch <name> 或 go <name>:切换到已有 worktree 并进入该目录;未提供名称时列出可选 worktree 并提示选择。
  • cleanup 或 clean:交互式清理不活跃的 worktree,先列出、再确认、然后删除并清理空目录。
  • copy-env <name>:向已存在但缺少 .env 文件的 worktree 复制环境文件。

在 Claude Code 工作流中

  • /workflows:review:若当前不在 PR 分支,会询问是否使用 worktree 做隔离评审;已在 PR 分支则直接留在当前分支。
  • /workflows:work:总是询问选择“在当前 worktree 上新建分支(实时工作)”还是“使用 worktree(并行工作)”。

手动调用示例

bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh list
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh switch feature-login
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh copy-env feature-login
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup

适用场景

  • 代码评审:不在 PR 分支时创建隔离 worktree 进行评审;
  • 并行特性开发:同时开发多个功能并在其间切换;
  • 完成工作后的清理。

设计原则与限制

  • KISS:一个管理脚本处理全部操作,命令简单、默认合理、交互确认防止误操作;
  • 约定默认:worktree 默认从 main 创建并存放于 .worktrees/ 目录,分支名即 worktree 名,.gitignore 自动管理;
  • 安全:创建与清理前确认,不会删除当前所在 worktree;
  • 目录结构示例:.worktrees/feature-login/、.worktrees/feature-notifications/;
  • 实现基于 git worktree add,各 worktree 有独立分支、共享 Git 历史与对象,可从任一 worktree 推送;
  • 性能:worktree 是轻量文件系统链接,不复制仓库,比克隆或 stash/切换更快;
  • 故障处理:worktree 已存在时会询问是否切换;无法删除当前 worktree 时需先回到主仓库再清理;缺少 .env 时用 copy-env 补充;可用 list 查看当前位置,用 cd $(git rev-parse --show-toplevel) 返回主仓库。

资料未提供收费、价格、平台支持范围等具体信息,暂未提供。