「Git」- 钩子

钩子是什么?

和其它版本控制系统一样,在特定的动作发生时,Git能触发自定义的脚本,以此来完成Git无法完成的某些工作。这些脚本就是“钩子”。

钩子分为两种:
1)运行于客户端的钩子。在进行诸如提交、合并这样的操作时,会触发客户端钩子。
2)运行于服务端的钩子。在诸如接收到推送的提交这样的操作时,则会触发服务端钩子。

我们能够根据自己的需要使用这些钩子。

如何设置钩子?

在客户端中,钩子被存储在项目中的.git/hooks目录中。在远程仓库中,钩子存储在仓库的hooks目录下。当发生特定的Git动作时,Git会调用该目录中特定名字的脚本。这些脚本就是“钩子”。

当我们用git init初始化一个新仓库时,Git默认会在这个目录中放置一些示例钩子。这些脚本除了本身可以被调用外,它们还透露了被触发时所传入的参数。所有的示例钩子都是Shell脚本,其中一些还混杂了Perl代码,不过,任何正确命名的可执行脚本都可以正常使用,我们可以用Ruby或Python,或其它语言编写它们。这些示例钩子的名字都是以.sample结尾,如果我们想启用它们,得先移除这个后缀。

把一个正确命名且可执行的钩子文件放入.git/hooks目录中,即可激活该钩子脚本。这样一来,它就能在发生特定动作时被Git调用。接下来,我们会讲解常用的钩子脚本类型。

客户端中的钩子

客户端钩子主要存在于本地仓库中,通常在.git/hooks目录中,分为很多种。下面把它们分为三类进行介绍,分别是:提交工作流钩子、电子邮件工作流钩子、其它钩子。

提交工作流中的钩子

pre-commit,在输入提交信息前运行。它用于检查即将提交的快照,例如,检查是否有所遗漏、确保测试运行、以及核查代码。 如果该钩子以非零值退出,Git将放弃此次提交,不过我们可以用git commit --no-verify来绕过这个环节。我们可以利用该钩子,来检查代码风格是否一致(运行类似lint的程序)、尾随空白字符是否存在(自带的钩子就是这么做的)、或新方法的文档是否适当。

有的人可能不理解“在输入提交信息前运行”这句话什么意思,大概是我们用了太多的git commit -m "New Commit"的缘故,该命令将提交和提交的输入信息一步化,淡化了二者中间的一个过程。实际情况是执行提交命令git commit后会启动一个编辑器。

prepare-commit-msg,该钩子在启动提交信息编辑器之前,默认信息被创建之后运行。它允许我们编辑提交者所看到的默认信息。该钩子会接收一些参上:存有当前提交信息的文件的路径、提交类型、修补提交的提交SHA-1校验。它对一般的提交来说并没有什么用;然而对那些会自动产生默认信息的提交非常有用,如提交信息模板、合并提交、压缩提交、修订提交等。 我们可以结合提交模板来使用它,动态地插入信息。

commit-msg,此钩子接收一个参数,此参数即上文提到的,保存由当前提交信息的临时文件的路径。如果该钩子脚本以非零值退出,Git将放弃提交。因此,可以用来在提交通过前,先进行项目状态或提交信息的验证。 在本章的最后一节,我们将展示如何使用该钩子来核对提交信息是否遵循指定的模板。

post-commit,该钩子在整个提交过程完成后运行。它不接收任何参数,但我们可以很容易地通过运行git log -1 HEAD来获得最后一次的提交信息。该钩子一般用于进行通知类的事情。

电子邮件工作流中的钩子

我们可以给电子邮件工作流设置三个客户端钩子。它们都是由git am命令调用的。因此如果我们的工作流中没有用到这个命令,可以直接跳到下一节。如果我们需要通过电子邮件接收由git format-patch产生的补丁,这些钩子也许用得上。

applypatch-msg,它是第一个运行的钩子。它接收一个参数:包含提议提交信息的临时文件的名字。如果脚本返回非零值,Git 将放弃该补丁。 我们可以用该脚本来确保提交信息符合格式,或直接用脚本修正格式错误。

pre-applypatch,它是下一个在git am运行期间被调用的钩子。有些难以理解的是,它正好运行于应用补丁之后,产生提交之前,所以我们可以用它在提交前检查快照。我们可以用这个钩子运行测试或检查工作区。如果有什么遗漏,或测试未能通过,脚本会以非零值退出,并中断git am 的运行,这样补丁就不会被提交。

post-applypatch,运行于提交产生之后,是在git am运行期间最后被调用的钩子。我们可以用它把结果通知给一个小组或我们所拉取的补丁的作者。但我们没办法用它停止打补丁的过程。

其它钩子

pre-rebase,该钩子运行于变基之前,以非零值退出可以中止变基的过程。我们可以使用这个钩子来禁止对已经推送的提交变基。 Git自带的pre-rebase钩子示例就是这么做的,不过它所做的一些假设可能与我们的工作流程不匹配。

post-rewrite,该钩子被那些会替换提交记录的命令调用,比如git commit --amendgit rebase(但不包括git filter-branch)。它收到的唯一参数是触发重写的命令,并从标准输入中接受重写列表。这个钩子的用途很大程度上跟post-checkout和post-merge差不多。

post-checkout,在git checkout成功运行后,该钩子会被调用。我们可以根据我们的项目环境合理地调整我们的工作目录。 其中包括移入大的二进制文件、自动生成文档、进行其他类似这样的操作。

post-merge,在git merge成功运行后,该钩子会被调用。我们可以用它恢复Git无法跟踪的工作区数据,比如权限数据。这个钩子也可以用来验证某些在Git控制之外的文件是否存在,这样我们就能在工作区改变时,把这些文件复制进来。

pre-push,在git push运行期间,更新了远程引用,但尚未传送对象时,该钩子会被调用。它接受的参数为远程分支的名字和位置,同时从标准输入中读取一系列待更新的引用。我们可以在推送开始之前,用它验证对引用的更新操作。一个非零的退出码将终止推送过程。

在Git的一些日常操作运行时,偶尔会调用git gc --auto进行垃圾回收。pre-auto-gc钩子会在垃圾回收开始之前被调用,可以用它来提醒我们现在要回收垃圾了,或者依情形判断是否要中断回收。

服务端中的钩子

除了客户端钩子,作为系统管理员,我们还可以使用若干服务端的钩子对仓库强制执行各种类型的策略。 这些钩子脚本在推送到服务器之前和之后运行。推送到服务器前运行的钩子可以在任何时候以非零值退出,拒绝推送并给客户端返回错误消息,还可以依我们所想设置足够复杂的推送策略。

pre-receive,处理来自客户端的推送操作时,最先被调用的脚本是pre-receive。 它从标准输入获取一系列被推送的引用。如果它以非零值退出,所有的推送内容都不会被接受。 我们可以用这个钩子阻止对引用进行非快进(non-fast-forward)的更新,或者对该推送所修改的所有引用以及文件进行访问控制。

update,该钩子与pre-receive十分类似,不同之处在于它会为每一个准备更新的分支各运行一次。假如推送者同时向多个分支推送内容,pre-receive只运行一次,相比之下update则会为每一个被推送的分支各运行一次。它不会从标准输入读取内容,但是它接受三个参数:引用的名字(分支)、推送前的引用指向的内容的SHA-1值、用户准备推送的内容的SHA-1值。如果update脚本以非零值退出,只有相应的那一个引用会被拒绝;其余的依然会被更新。

post-receive,该钩子在整个过程完结以后运行,可以用来更新其他系统服务或者通知用户。它接受与pre-receive相同的标准输入数据。 它的用途包括给某个邮件列表发信,通知持续集成(continous integration)的服务器,或者更新问题追踪系统(ticket-tracking system),甚至可以通过分析提交信息来决定某个问题(ticket)是否应该被开启、修改、关闭。该脚本无法终止推送进程,不过客户端在它结束运行之前将保持连接状态,所以如果我们想做其他操作需谨慎使用它,因为它将耗费我们很长的一段时间。

注意事项

需要注意的是,克隆某个版本库时,它的客户端钩子并不会被复制。如果需要靠这些脚本来强制维持某种策略,建议我们在服务端实现这一功能。(请参照「使用强制策略的一个例子」中的例子。)

常见问题处理

fatal: cannot run .git/hooks/pre-commit: No such file or directory

问题描述:

# git commit -m 'pre-commit hook testing'                                                                                                                                                                                                                             
fatal: cannot run .git/hooks/pre-commit: No such file or directory 

原因分析:
在我们的场景(Ubuntu 20.04 TLS)中,由于 pre-commit 脚本为 CRLF 结尾,导致无法执行。

解决方案:
通过 dos2unix 命令,dos2unix .git/hooks/pre-commit 转换为 Unix 结尾文件。

参考文献

Git Doc/8.3 Customizing Git – Git Hooks