git hooks 简介与使用

1 简介

git hooks，即git 钩子，定义为能在特定的重要动作发生时触发自定义脚本。
git 的hook分为两种，客户端hooks和服务端hooks。
客户端钩子由诸如提交和合并这样的操作所调用，而服务器端钩子作用于诸如接收被推送的提交这样的联网操作。

官方文档：

https://git-scm.com/docs/githooks

2 说明

• 结构说明

git hooks在git项目中的位置在 /.git/hooks 目录下，初始化时由以下sample组成：

applypatch-msg.sample*
commit-msg.sample*
post-update.sample*
pre-applypatch.sample*
pre-commit.sample*
prepare-commit-msg.sample*
pre-push.sample*
pre-rebase.sample*
pre-receive.sample*
update.sample*

• hook说明

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

  把一个正确命名（不带扩展名）且可执行的文件放入 .git 目录下的 hooks 子目录中，即可激活该钩子脚本。 这样一来，它就能被 Git 调用。

  
  
  初始化时的 pre-commit.sample

• hook类型

  1. applypatch-msg
     它接收单个参数：包含请求合并信息的临时文件的名字。 如果脚本返回非零值，Git 将放弃该补丁。 你可以用该脚本来确保提交信息符合格式，或直接用脚本修正格式错误。

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

  3. post-update
     仅在所有的ref被push之后执行一次。它与post-receive很像，但是不接收旧值与新值。主要用于通知。每个被push的repo都会生成一个参数，参数内容是ref的名称。

  4. pre-applypatch
     实际上的调用时机是应用补丁之后、变更commit之前。如果以非0的状态退出，会导致变更成为uncommitted状态。可用于在实际进行commit之前检查代码树的状态或用它在提交前检查快照。 你可以用这个脚本运行测试或检查工作区。 如果有什么遗漏，或测试未能通过，脚本会以非零值退出，中断 git am 的运行，这样补丁就不会被提交。

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

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

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

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

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

  10. update（服务器端）
      update 脚本和 pre-receive 脚本十分类似，不同之处在于它会为每一个准备更新的分支各运行一次。 假如推送者同时向多个分支推送内容，pre-receive 只运行一次，相比之下 update 则会为每一个被推送的分支各运行一次。 它不会从标准输入读取内容，而是接受三个参数：引用的名字（分支），推送前的引用指向的内容的 SHA-1 值，以及用户准备推送的内容的 SHA-1 值。 如果 update 脚本以非零值退出，只有相应的那一个引用会被拒绝；其余的依然会被更新。

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

  12. post-checkout
      更新工作树后调用checkout时调用，或者执行 git clone后调用。主要用于验证环境、显示变更、配置环境。在 git checkout 成功运行后，post-checkout 钩子会被调用。你可以根据你的项目环境用它调整你的工作目录。 其中包括放入大的二进制文件、自动生成文档或进行其他类似这样的操作。

  13. post-rewrite
      本hook在git命令重写（rewrite）已经被commit的数据时调用。除了其携带的参数之外，本hook还从stdin接收信息，信息格式为” ”。post-rewrite 钩子被那些会替换提交记录的命令调用，比如 git commit --amend 和 git rebase（不过不包括 git filter-branch）。 它唯一的参数是触发重写的命令名，同时从标准输入中接受一系列重写的提交记录。 这个钩子的用途很大程度上跟 post-checkout 和 post-merge 差不多。

完整说明详见官方文档：

https://git-scm.com/docs/githooks

3 demo（git commit代码检查）

• 先说思路，思路是使用pre-commit
  官方说明：

This hook is invoked by git-commit[1], and can be bypassed with the --no-verify option. It takes no parameters, and is invoked before obtaining the proposed commit log message and making a commit. Exiting with a non-zero status from this script causes the git commit command to abort before creating a commit.
The default pre-commit hook, when enabled, catches introduction of lines with trailing whitespaces and aborts the commit when such a line is found.
All the git commit hooks are invoked with the environment variable GIT_EDITOR=: if the command will not bring up an editor to modify the commit message.
The default pre-commit hook, when enabled—and with the hooks.allownonascii config option unset or set to false—prevents the use of non-ASCII filenames.

• 初始化并一个git仓库，这里随便用一个go文件仓库作为demo，代码输出 hello world!!

package main

import "fmt"

var str =  "hello world!!"

func main()  {
    fmt.Println(str)
}

• 尝试推送一下，此时可以看到，添加hook前能够正常提交

  
  
  添加hook前正常提交

• 进入.git/hooks目录下：

  .git/hooks目录结构

• 拷贝一个 pre-commit.sample并命名为 pre-commit，编辑pre-commit

cp .git/hooks/pre-commit.sample .git/hooks/pre-commit && vi .git/hooks/pre-commit

• 使用bash随手写一个方法，校验代码中的 “hello”字段，如果存在则输出一个异常信息

#!/bin/bash

echo  "code check running..."

for FILE in `git diff --name-only --cached`; do

    grep 'hello' $FILE 2>&1 >/dev/null
    if [ $? -eq 0 ]; then
        echo $FILE '包含hello，退出commit'
        exit 1
    fi
    
done

• 尝试运行一下commit，果然报错了

git commit 报错

• 去除代码中的 hello，再次运行一下commit试试
  
  验证通过

• 校验通过，可以正常push。

4 小结

• 根据所需要的需求选用不同的hook类型，然后使用bash shell/Ruby/Python等编写脚本，在git生命周期中添加你需要的逻辑。
• git hooks分为客户端和服务端，需要注意所增加配置的影响范围。
• 使用时需要去除文件.sample后缀名，否则文件不生效。