全局 Git 钩子整体设置流程
一、目标与行为摘要
- 在 /Your/work/dir 及其子目录下的 Git 仓库中，执行 git commit 时，若未设置 NO_XXX，则在提交说明第一行末尾自动追加 [xxx]。
- 不在上述路径下的仓库：不追加；仍会尝试执行该仓库 .git/hooks/prepare-commit-msg（若存在）。
- 使用环境变量 NO_XXX（无需赋值）可跳过本次追加。
- 全局通过 core.hooksPath 指向固定目录；Husky 仓库需在项目内增加转发脚本（见第五节）。
二、目录与 Git 配置
1. 创建钩子目录
|
1 |
mkdir -p "$HOME/.config/git/hooks" |
2. 指向该目录（全局）
|
1 |
git config --global core.hooksPath "$HOME/.config/git/hooks" |
查看：
|
1 |
git config --global --get core.hooksPath |
应输出：/Users/macadmin/.config/git/hooks（或 $HOME 展开后的等价路径）。
3. 为何需要单独目录
设置 core.hooksPath 后，Git 只使用该目录下的钩子文件，不再自动读取各仓库 .git/hooks 下的同名文件。因此需要：
- 在 prepare-commit-msg 中实现追加逻辑，并在适当时先调用 .git/hooks/prepare-commit-msg；
- 为 pre-commit、commit-msg、pre-push 等常用钩子提供转发脚本，内部执行 .git/hooks/<同名>（若存在），以尽量保持与未配置全局 hooksPath 时一致的行为。
三、prepare-commit-msg 逻辑要点
脚本建议包含：
- 解析仓库根目录：git rev-parse –show-toplevel，并用 cd “$ROOT” && pwd -P 规范化路径。
- 前缀判断：仅当根目录为 /Your/work/dir 或以其为前缀的子路径时，才执行追加。
- NO_XXX 判断：若 [ “${NO_XXX+x}” = “x” ]，则不再追加（变量已设置即可，不要求有值）。
- 链式旧钩子：若 $GIT_DIR/hooks/prepare-commit-msg 存在且可执行，先执行（避免与历史安装方式冲突）。
- 追加前检查：首行非空、且不以 [xxx] 结尾；使用 sed 修改首行（注意 macOS 与 GNU sed 对 -i 的差异，可用 sed -i.bak … && rm -f *.bak）。
具体实现以当前目录下 prepare-commit-msg 文件为准。
四、转发类钩子（pre-commit、commit-msg 等）
在全局 hooksPath 目录中为每个需要的钩子名建立可执行脚本，内容模式为：
|
1 2 3 4 5 |
#!/usr/bin/env sh GIT_DIR=$(git rev-parse --git-dir 2>/dev/null) || exit 0 LEGACY="$GIT_DIR/hooks/<钩子名>" [ -x "$LEGACY" ] && exec sh "$LEGACY" "$@" exit 0 |
将 <钩子名> 替换为 pre-commit、commit-msg 等。这样未使用 Husky、仅依赖 .git/hooks 的仓库仍能跑原有检查。
五、Husky 仓库额外步骤
若仓库执行：
|
1 |
git config core.hooksPath |
得到 .husky/_（或任意非全局路径），则 Git 不会调用 $HOME/.config/git/hooks/prepare-commit-msg。
在该仓库 /.husky/prepare-commit-msg 中写入转发（需可执行）：
|
1 2 3 |
#!/usr/bin/env sh [ -x "${HOME}/.config/git/hooks/prepare-commit-msg" ] || exit 0 exec sh "${HOME}/.config/git/hooks/prepare-commit-msg" "$@" |
保存后：
|
1 |
chmod +x .husky/prepare-commit-msg |
之后在该仓库提交时，会由 Husky 调用上述文件，再进入全局 prepare-commit-msg 逻辑。
六、验证步骤
- 无 Husky、在 Work/code 下的测试仓库：
123cd /Your/work/dir/某测试仓库git commit --allow-empty -m "chore: 钩子测试"git log -1 --pretty=%B
首行应类似：chore: 钩子测试 [xxx]。 - 跳过追加：
1NO_XXX git commit --allow-empty -m "chore: 无 AI 标"
首行应无 [xxx]。 - Husky 仓库：确认已存在 .husky/prepare-commit-msg 转发且可执行后，重复步骤 1。
七、撤销与排错
撤销全局 hooksPath
|
1 |
git config --global --unset core.hooksPath |
撤销后，各仓库恢复默认使用 .git/hooks（以仓库内是否另有 core.hooksPath 为准）。
未追加时的检查清单
| 检查项 | 说明 |
|---|---|
| 是否在 Work/code 下 | 根目录须匹配 /Your/work/dir 前缀 |
| 是否设置了 NO_XXX | env | grep NO_XXX |
| 首行是否已有 [xxx] | 已有则不再追加 |
| 仓库是否使用 Husky | 是则需 .husky/prepare-commit-msg 转发 |
| 全局 core.hooksPath | git config –global –get core.hooksPath |
全局 Git 钩子使用说明
git config –global core.hooksPath 指向的钩子目录，用于在提交说明首行末尾追加 [xxx]（见 prepare-commit-msg），并转发其它钩子到各仓库的 .git/hooks。
追加 [xxx] 何时生效
同时满足以下条件时，会在**提交说明第一行（标题）**末尾追加空格 + [xxx]：
- 仓库根目录（git rev-parse –show-toplevel 规范化后）位于 /Your/work/dir 或其子目录下。
- 环境变量 NO_XXX 未设置（见下文「如何跳过」）。
- 首行非空，且尚未以 [xxx] 结尾（避免 git commit –amend 重复追加）。
不满足第 1 条时：仍会执行 .git/hooks/prepare-commit-msg（若存在），但不会改说明、不追加。
如何跳过追加
只要 NO_XXX 已被设置（无需赋值），本次提交不会追加 [xxx]：
|
1 |
NO_XXX git commit -m "feat: 某功能" |
|
1 2 |
export NO_XXX git commit -m "feat: 另一功能" |
|
1 |
NO_XXX= git commit -m "feat: 空值也算已设置" |
取消跳过：unset NO_XXX。
Husky 仓库为何还要在项目里加钩子
若某仓库在本地配置了 core.hooksPath（例如 Husky 的 .husky/_），Git 只会执行该路径下的钩子，不会自动执行 prepare-commit-msg。
此类仓库需在 .husky/prepare-commit-msg 中转发到本机脚本，例如：
|
1 2 3 |
#!/usr/bin/env sh [ -x "${HOME}/.config/git/hooks/prepare-commit-msg" ] || exit 0 exec sh "${HOME}/.config/git/hooks/prepare-commit-msg" "$@" |
并赋予可执行权限：chmod +x .husky/prepare-commit-msg。
其它钩子（pre-commit、commit-msg 等）
pre-commit、commit-msg、pre-push 等为薄转发：若存在 .git/hooks/<同名> 且可执行，则执行之；否则直接退出。用于在设置了全局 core.hooksPath 后，仍能使用各仓库原先放在 .git/hooks 里的逻辑。
与 commitlint 等
prepare-commit-msg 在打开编辑器或写入 -m 说明之后、commit-msg 校验之前执行。追加后首行形如：feat: 描述 [xxx]。若与 commitlint 规则冲突，需在 commitlint.config.js 中放宽对 subject 的规则。
