用途:用一个全局 Git pre-commit 钩子,在整台机器上统一执行“main/master 分支禁止提交、智能体必须在 worktree 中工作”的策略,避免在每个仓库重复复制钩子代码。
主要能力与策略:任何人向 main 或 master 提交都会被阻止;当环境变量 CLAUDECODE=1(在 Claude Code 的 Bash 会话中被设置)时,如果智能体在主检出目录的任意分支上提交,也会被阻止并提示改用 worktree;智能体在关联 worktree 的功能分支上提交、人类在主检出目录的功能分支上提交则允许;人类可用 ALLOW_MAIN_COMMIT=1 git commit 或 --no-verify 作为逃生通道。
作用范围自动识别:保护仅在带有已提交的 .envrc 且包含 export DEV_HOST= 的仓库中生效,这是 worktree-devproxy 已接入仓库的标志;其他仓库会被静默跳过,将来新接入的仓库无需额外步骤即可覆盖。
安装(每台机器一次): cp scripts/pre-commit ~/.githooks/pre-commit chmod +x ~/.githooks/pre-commit git config --global core.hooksPath ~/.githooks
设计说明:使用全局 core.hooksPath 而非每仓库钩子,保证策略只有一份,更新只需改一个文件;全局钩子结尾会 exec 仓库自身的 .githooks/pre-commit(若存在),以保留仓库特定钩子,因此仓库不应设置本地 core.hooksPath,否则会覆盖全局并静默失效。智能体检测依据是 CLAUDECODE=1。主检出目录的检测方式是 git rev-parse --git-dir 与 --git-common-dir 相等,在关联 worktree 中二者不同。错误信息中直接给出补救命令 wt new <branch>,智能体可自行纠正。
验证:在已接入仓库的 main 分支执行 git commit --allow-empty -m test 预期被阻止;智能体在主检出功能分支上预期被阻止;在 wt new 创建的 worktree 中提交应成功;没有 .envrc/DEV_HOST 的仓库提交应成功(跳过保护)。
限制:仅本地有效,无法阻止已存在的 main 提交被 push 或 force-push,需配合 GitHub 分支保护(仅允许 squash PR)覆盖远端;逃生通道基于自觉设计,目标是引导智能体,而非防篡改。