用途
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)。
限制与未提供信息
资料未提供独立安装方法、收费与价格、支持平台或效果指标。