SuperAPI AI 工具集

nv-worktree-commands

编程与开发

查看项目

更新于 11-06 03:07

技能介绍

用途

nv-worktree-commands 是 Novu 仓库内的一份 Git worktree 命令参考,主要供实现或调试 worktree 工作流的智能体使用。资料说明,端到端流程应优先使用 nv-worktree-create,本参考侧重具体命令与规则。

路径命名

  • REPO_ROOT 由 git rev-parse --show-toplevel 得到。
  • REPO_PARENT 为 REPO_ROOT 的父目录。
  • BRANCH 为用户提供的名称,用作 Git 分支名。
  • DIR_NAME 为 BRANCH 清洗后的结果:小写化,并将 / 替换为 -。
  • WORKTREE 为 $REPO_PARENT/$DIR_NAME。

示例:仓库位于 /Users/me/work/novu 时,分支 more-dcr-oauths 对应路径 /Users/me/work/more-dcr-oauths;分支 nv-1234/foo-bar 对应 /Users/me/work/nv-1234-foo-bar。若 WORKTREE 已存在于磁盘或出现在 git worktree list 中,应中止。

创建

从当前 HEAD 创建新分支:

git worktree add -b <branch> <worktree-path>

从指定基准创建:

git worktree add -b <branch> <worktree-path> <base-ref>

其中 <base-ref> 可以是 HEAD、main、origin/main、标签或提交 SHA。

检查

git worktree list
git -C <worktree-path> status -sb
git -C <worktree-path> rev-parse HEAD

复制本地环境文件

git worktree add 不会带入被 gitignore 的文件。资料指出,在 Novu 中只有普通 .env 文件被 gitignore,.env.development、.env.agent、.env.test 等已被跟踪,会出现在 worktree 中。

默认方式:向 git 查询被忽略的 .env 文件,使用 --directory 避免进入 node_modules、.nx、dist 等目录:

cd <main-repo-root>
git ls-files -z -o -i --exclude-standard --directory \
| grep -zE '(^|/)\.env$' \
| rsync -a --from0 --files-from=- ./ "<worktree-path>/"

lite 方式仅覆盖核心应用,不做搜索:

cd <main-repo-root>
for f in apps/api/src/.env apps/worker/src/.env apps/ws/src/.env apps/dashboard/.env; do
  [ -f "$f" ] && echo "$f"
done | rsync -a --files-from=- ./ "<worktree-path>/"

资料提醒,不要对整个仓库使用 rsync --include='*/',因为会进入 node_modules 和 .nx,实测约 11 秒,而上述方式约 0.1 秒。复制后应报告实际发送的文件列表,上述命令约复制 8 个文件。

Novu 相关注意事项

  • 应从父检出复制,而不是运行 node scripts/setup-env-files.js。该脚本在缺少 .env 时会生成新的 STORE_ENCRYPTION_KEY,导致 worktree 与父检出及共享的本地 Mongo/Redis 不一致。
  • 典型复制的文件包括 apps/api/src/.env、apps/dashboard/.env、apps/worker/src/.env、apps/ws/src/.env,以及 apps/inbound-mail、libs/agent-evals 下的文件。
  • 除非任务需要,跳过 playground 的环境文件。

安装与构建

创建 worktree 时不要执行安装或构建(pnpm install、pnpm build、pnpm setup:agent)。如用户需要,会自行提出。

删除

git worktree remove <worktree-path>
git worktree prune

应先移除 worktree 中未提交的工作;仅在用户明确要求时使用 --force。若要审计已合并或过期的 worktree 并批量清理,可参考 nv-worktree-cleanup。

反模式

  • 目标是具名功能分支时使用 git worktree add --detach,应改用 -b。
  • 用 cp -r 复制整个仓库,而不是 git worktree add。
  • 兄弟目录 ../<name> worktree 已足够时,复用 ~/.cursor/worktrees/… 下的分离路径。
  • 父级已执行安装脚本时,在 Cursor Cloud 子 worktree 中重复运行完整安装脚本(pnpm setup:agent)。

限制与未提供信息

资料未提供独立安装方法、收费与价格、支持平台或效果指标。