SuperAPI AI 工具集

using-git-worktrees

编程与开发

查看项目

更新于 11-13 10:12

技能介绍

用途

该技能用于在开始需要与当前工作区隔离的功能开发,或执行实现计划之前,创建独立的 Git worktree。Git worktree 可以在共享同一仓库的前提下提供多个隔离工作区,从而同时处理多个分支而无需切换。

核心原则是:系统化的目录选择加安全校验,等于可靠的隔离。

主要能力

  • 目录选择:按优先级检查已有目录,先查 .worktrees(隐藏、首选),再查 worktrees(备选);若两者都存在则用 .worktrees;若都不存在则询问用户选择项目内的 .worktrees/ 或 worktrees/。
  • 安全校验:对项目本地目录,创建前必须用 git check-ignore -q .worktrees 确认该目录已被忽略;若未被忽略,则向 .gitignore 添加对应行并提交,防止工作树内容被误提交进仓库。
  • 创建与初始化:检测项目名,用 git worktree add ".worktrees/$BRANCH_NAME" -b "$BRANCH_NAME" 创建带新分支的工作树并进入。
  • 自动项目设置:根据项目文件自动运行安装命令,例如存在 package.json 时执行 npm install;存在 requirements.txt 时执行 pip install -r requirements.txt;存在 pyproject.toml 时执行 poetry install。
  • 基线验证:运行测试确保工作树从干净状态开始;测试失败时报告失败并询问是继续还是排查,测试通过则报告就绪。
  • 结果报告:输出工作树的完整路径、通过的测试数量与失败数、准备实现的功能名称。

使用方式

技能开始时需声明:“I'm using the using-git-worktrees skill to set up an isolated workspace.” 随后依次执行:检查并选择目录、验证目录被忽略、创建 worktree、按检测结果安装依赖、运行测试、报告位置。技能内提供了 PowerShell 示例命令(如 Test-Path、Split-Path -Leaf)用于目录检测和项目名获取。

适用场景

  • 需要与当前工作区隔离的功能开发。
  • 执行实现计划或子代理驱动开发时作为工作区准备步骤。
  • 与 brainstorming 衔接(设计批准后进入实现),与 finishing-a-development-branch 配合完成工作后清理。

限制与注意事项

  • 对项目本地目录,必须校验其已被忽略,否则工作树内容会污染 git status。
  • 不得在目录位置不明确时自行假设,应遵循“已有优先,否则询问”的顺序。
  • 基线测试失败时不得未经询问直接继续,以免无法区分新缺陷与既有问题。
  • 不应硬编码安装命令,应根据项目文件自动检测;无 package.json 等文件时跳过依赖安装。
  • 资料中的 setup 与测试命令为示例,具体项目可能不同。