SuperAPI AI 工具集

git-worktree

编程与开发

查看项目

更新于 10-15 12:37

技能介绍

Git Worktree Manager 是一项用于在开发流程中统一管理 Git 工作树的技能。无论是要隔离地评审 PR,还是并行开发多个功能,它都尝试把相关复杂度交由一个管理脚本来处理。

用途

该技能面向需要隔离环境或并行开发的场景,包括代码评审(/ce:review)、功能开发(/ce:work)、同时推进多个功能,以及完成工作后的清理。在 /ce:review 中,如果当前不在目标分支(PR 分支或指定分支),会提供使用工作树进行隔离评审的选项;在 /ce:work 中,则始终询问用户希望并行工作树还是实时分支工作。

主要能力

据资料,该技能可以:从 main 分支创建带有清晰分支名的工作树;列出工作树及当前状态;在工作树之间切换以进行并行工作;自动清理已完成的工作树;每一步提供交互式确认;自动管理 worktree 目录的 .gitignore;自动从主仓库向新工作树复制 .env 文件;自动信任 mise 和 direnv 配置,并带有评审安全的防护规则。

其强调的关键点:不要直接调用 git worktree add,而应始终使用 worktree-manager.sh 脚本。因为脚本会处理原始 git 命令不做的关键设置,包括:复制 .env、.env.local、.env.test 等文件;按分支感知的安全规则信任开发工具配置(mise 仅在相对于受信任基线分支未变更时自动信任,direnv 仅对受信任基础分支自动允许,评审工作树保持手动);确保 .worktrees 被加入 .gitignore;创建一致的目录结构。

使用方式

在 Claude Code 工作流中,该技能会被 /ce:review 和 /ce:work 命令自动调用。也可从 bash 手动调用,命令形式如下:

创建新工作树(自动复制 .env 文件): bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-login

列出全部工作树: 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

向已有工作树复制 .env 文件: 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

各命令说明:

  • create <branch-name> [from-branch]:创建带指定分支名的新工作树。branch-name 必填,from-branch 可选(默认 main)。执行时会检查工作树是否已存在、从远程更新基础分支、创建工作树与分支、复制主仓库的 .env 文件、按分支安全规则信任开发工具配置,并显示可 cd 进入的路径。
  • list 或 ls:列出所有可用工作树及其分支和当前状态,输出包括工作树名称、分支名、当前所处位置(以 ✓ 标记)、主仓库状态。
  • switch <name> 或 go <name>:切换到已有工作树并 cd 进入;若未提供名称,则列出可用工作树并提示选择。
  • cleanup 或 clean:以交互确认方式清理非活动工作树,列出非活动工作树、请求确认、移除所选工作树、清理空目录。

适用场景

资料给出的典型流程包括:代码评审时若不在 PR 分支,可选择以工作树隔离评审,完成后返回主目录并清理;并行功能开发时,可分别创建多个功能工作树,按需切换,完成后回到主目录清理。该技能也被设计为与 /ce:review 和 /ce:work 集成:评审时先检查当前分支,若已在目标分支则无需工作树,若不同则询问是否使用工作树;工作时始终提供“在当前工作树新建分支(实时工作)”或“工作树(并行工作)”两种选择。

设计原则与限制

其设计原则包括:KISS(一个管理脚本处理全部操作、命令简单且默认合理、交互提示防止误操作、直接用分支名命名);有主张的默认值(除非指定否则始终从 main 创建、存放在 .worktrees/ 目录、分支名即工作树名、自动管理 .gitignore);安全优先(创建与清理前确认、不删除当前所在工作树、给出清晰错误信息)。

技术细节方面,目录结构为 .worktrees/ 下按功能命名的工作树目录,.gitignore 会被更新以包含 .worktrees。它基于 git worktree add 提供隔离环境,每个工作树拥有自己的分支,各工作树之间的改动互不影响,并与主仓库共享 git 历史,可从任意工作树推送。性能上,工作树是轻量的文件系统链接,不复制仓库,共享 git 对象,比克隆或 stash/切换更快。

故障排查包括:若提示工作树已存在,脚本会询问是否切换过去;若提示无法移除当前工作树,需先切回主仓库再清理;找不到位置时用 list 查看;若工作树缺少 .env 文件(例如通过原始 git worktree add 创建),可用 copy-env 复制;返回主目录可使用 cd $(git rev-parse --show-toplevel)。

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