Git Hooks 可以在运行各个动作的前后自动去触发某个脚本来做前置处理或是后置处理,这个功能很常被用来在 commit 前自动检查代码的排版或是写法上的问题,确保 commit 过的代码排版和风格是一致的。Git Hooks 有分为在客户端(client-side)触发的 Hook,以及在服务器端(server-side)触发的 Hook,这篇文章只会介绍在客户端触发的 Hook。

当我们运行 git init 指令替项目加入 Git 版本控制后,项目目录底下会多出一个 .git 目录,这个目录用来存放 Git 设置与版本控制所需的文件,它并不能被 add 进 Git 仓库中。在 .git/hooks 目录中可以放置这个项目要使用的 Git Hooks 脚本,这些脚本会有特定的文件名,用来决定它是在 Git 运行哪个动作时会被触发。

客户端的 Hook 触发时机和文件名称的关系如下表(非全部):

触发时机 文件名称(按触发的先后顺序排列)
git am 运行之前 applypatch-msg、pre-applypatch
git am 运行之后 post-applypatch
git commit 运行之前 pre-commit、prepare-commit-msg(commit 消息的编辑器打开前)、commit-msg
git commit 运行之后 post-commit
git merge 运行之前 pre-merge-commit
git rebase 运行之前 pre-rebase
git push 运行之前 pre-push

每个脚本在被触发运行时,各自会有不同的参数传入。在 .git/hooks 目录中,会有以 .sample 结尾的 Shell 脚本文件,会说明该 Git Hooks 脚本应会被传入什么样的参数,以及它该根据什么样的状况回传什么 exit status,您也可以查阅官方文档获得更详细的说明。虽然 .sample 文件是 sh 脚本,但要用 Bash 脚本,甚至是任意可执行文件也都是可以的。要被用作 Git Hooks 脚本的文件必须具有可运行权限才可以被触发运行。

撰写 Shell 脚本的时候可以用 ShellCheck 来检查 Shell 脚本的问题。

Git Hooks 的基本应用

commit 前自动检查项目

可以加入 pre-commit 脚本来实现 commit 前自动检查项目。如果在加入脚本后,临时在 commit 时不需要检查的话,可以在使用 git commit 指令时加上 --no-verify 参数来略过脚本。

Node.js 项目
#!/bin/bash

npm run lint

通常 Node.js 项目会在 package.json 的 scripts 字段下设置 lint 脚本,来调用 lint 工具去检查 JavaScript 等代码的语法。所以在 pre-commit 脚本中去运行 npm run lint。

Cargo 项目
#!/bin/bash

set -e

cargo +nightly fmt -- --check
cargo clippy --all-targets -- -D warnings

set -e 指令可以让 Bash 在运行一系列指令的过程中,如果其中一行指令出现问题,就立刻回传它的 exit status,而不再运行下去。

保存与共享 Git Hooks

由于 Git Hooks 脚本预设存放在无法被 git add 的 .git 目录下,因此如果要能使它被 push 到远程的 Git 仓库上,就需要换个位置放,而不是放在 .git/hooks。

笔者自己是习惯在项目目录底下再创建一个 .githooks 目录,并把 Git Hooks 脚本都放在这个目录下。

当然,我们还是要让 Git 知道 Git Hooks 脚本放在哪才行,可以运行如下的指令:

git config core.hooksPath .githooks

用如上的指令将 Git 的 core.hooksPath 字段设置为 Git Hooks 脚本所在的目录即可。注意这个设置也只会在目前的这个本地端项目有效,并不会被 push 到远程的 Git 仓库上。

我们可以在 CONTRIBUTING.md 或 README.md 中撰写说明,让刚 clone 这个 Git 项目的开发者主动去运行这个指令。也可以把这个指令写在程序项目自动化脚本的某个位置。像是 Node.js 项目,可以在 package.json 的 scripts 字段下设置 prepare 脚本,来调用这个指令。prepare 脚本会在 npm ci 或是 npm i 的时候被运行。当我们 clone 一个 Node.js 项目后,通常首先要做的事情就是 npm ci 或是 npm i,所以利用 prepare 脚本来设置 Git Hooks 的目录。

不过别的环境里可能会没有 git 指令工具,此时 git config 指令会运行失败,而导致后续原本要跑的流程中止了。将指令改成以下这样,再加进程式项目里应该会比较好一点:

git config core.hooksPath .githooks || exit 0