GitHook 工具 —— husky介绍及使用

名称

githooks-Git使用的挂钩。(githook在官网的介绍)

描述

挂钩是可以放置在挂钩目录中的程序，可在git执行的某些点触发动作。没有设置可执行位的钩子将被忽略。

默认情况下，hooks目录是$GIT_DIR/hooks，但是可以通过core.hooksPath配置变量来更改（请参见 git-config [1]）。

HOOKS（钩子）的几种情况

1.applypatch-msg(应用程序消息)

这个钩子由git am调用。它只有一个参数，即保存建议的提交日志消息的文件的名称。以非零状态退出会导致git am在应用补丁之前中止。

该挂钩允许在适当位置编辑消息文件，并可用于将消息规范化为某些项目标准格式。检查消息文件后，它也可以用于拒绝提交。

启用后，默认的applypatch-msg挂钩将运行 commit-msg挂钩（如果后者已启用）。

2.pre-applypatch(应用前批处理)

这个钩子由git am调用。它不接受任何参数，并在应用补丁程序之后、提交之前调用。

如果它以非零状态退出，则在应用补丁程序后将不会提交工作树。

它可以用来检查当前的工作树，如果不通过某些测试，则拒绝提交。

默认的pre-applypatch钩子在启用时运行pre-commit钩子（如果后者已启用）。

3.post-applypatch(应用程序批处理后)
这个钩子由git am调用。它不接受任何参数，在应用补丁程序并提交之后调用。

这个钩子主要用于通知，不能影响git am的结果。

4.pre-commit(预先提交)
这个钩子由git commit调用，可以使用--no-verify选项绕过它。它不接受任何参数，并在获取建议的提交日志消息和进行提交之前被调用。从这个脚本中退出非零状态会导致git commit命令在创建提交之前中止。

默认的pre-commit挂钩（如果启用）捕获带有尾随空白的行的引入，并在找到此类行时中止提交。

如果命令不会打开编辑器来修改提交消息，则使用环境变量 GIT_EDITOR=:调用所有git commit挂钩。

当启用hooks.allownonascii配置选项unset或设置为false时，默认的pre-commit挂钩将阻止使用非ASCII文件名。

5.pre-merge-commit(合并前提交)
这个钩子由git merge[1]调用，可以使用--no-verify选项绕过它。它不接受任何参数，并在合并成功执行之后和获取建议的提交日志消息以进行提交之前调用。从这个脚本中退出非零状态会导致Git合并命令在创建提交之前中止。

如果启用了pre-merge-commit挂钩，则默认的预合并提交挂钩将运行pre-commit挂钩。

如果命令不会调出编辑器来修改提交消息，则使用环境变量GIT_EDITOR=:调用此挂钩。

如果无法自动执行合并，则需要解决冲突并单独提交结果（参见git merge）。此时，将不会执行此挂钩，但如果启用了pre-commit挂钩，则会执行它。

6.prepare-commit-msg(准备提交消息)
git commit在准备默认日志消息之后，在启动编辑器之前调用此钩子。

它需要一到三个参数。第一个是包含提交日志消息的文件的名称。第二个是提交消息的来源，可以是：message（如果给出了-m或-F选项）；template（如果给出了-t选项或配置选项commit.template）；merge（如果提交是合并或.git/MERGE_MSG文件）；squash（如果.git/SQUASH_MSG文件存在）；或commit，接着是提交SHA-1（如果是-c，-c）或者--amend 选项）。

如果退出状态为非零，则git commit将中止。

钩子的目的是就地编辑消息文件，而--no-verify选项不禁止它。非零退出意味着钩子失败，并中止提交。它不应该用作预提交挂钩的替换。

Git附带的prepare-commit-msg钩子示例删除了commit模板注释部分中的帮助消息。

7.commit-msg(提交信息)
这个钩子由git commit和git merge调用，可以使用--no-verify选项绕过它。它接受一个参数，即保存建议的提交日志消息的文件的名称。退出非零状态会导致命令中止。

允许钩子就地编辑消息文件，并可用于将消息规范化为某些项目标准格式。它还可用于在检查消息文件后拒绝提交。

默认的commit-msg hook在启用时检测到重复的Signed-off-by行，如果找到一行，则中止提交。

8.post-commit(提交后)
这个钩子由git commit调用。它不接受任何参数，并在提交后调用。

这个钩子主要用于通知，不能影响git commit的结果。

9.pre-rebase(变基前)
这个钩子由git rebase调用，可用于防止分支重新定位。可以使用一个或两个参数调用钩子。第一个参数是派生序列的上游。第二个参数是正在重设基的分支，重设基当前分支时不设置该参数。

10.post-checkout(结账后)
更新工作树后运行git checkout或git switch时，将调用此挂钩。钩子有三个参数：前一个HEAD的ref，新HEAD的ref（可能已经更改，也可能没有更改）和一个标志，指示签出是分支签出（更改分支，flag=1）还是文件签出（从索引中检索文件，flag=0）。此挂钩不会影响git switch或git checkout的结果。

它也在git clone[1]之后运行，除非使用--no-checkout（-n）选项。给钩子的第一个参数是空ref，第二个参数是新头的ref，标志总是1。同样，对于git worktree add，除非--no-checkout签出。

此钩子可用于执行存储库有效性检查、自动显示与前一个HEAD的差异（如果不同）或设置工作目录元数据属性。

11.post-merge(合并后)
这个钩子由git merge调用，当在本地存储库上完成git pull时就会发生这种情况。钩子接受一个参数，一个状态标志，指定正在进行的合并是否是挤压合并。如果合并由于冲突而失败，则此挂钩不会影响git merge的结果，也不会执行。

此钩子可与相应的预提交钩子结合使用，以保存和还原与工作树相关联的任何形式的元数据（例如：permissions/ownership, ACLS等）。请参阅contrib/hooks/setgitperms.perl，以获取如何执行此操作的示例。

12.pre-push(预推)
这个钩子被git push调用，可以用来防止发生push。使用两个参数调用钩子，这两个参数提供目标远程的名称和位置，如果未使用命名远程，则两个值将相同。

有关要推送的内容的信息在钩子的标准输入中提供，输入行如下：

<local ref> SP <local sha1> SP <remote ref> SP <remote sha1> LF

例如，如果运行git push origin master:foreign命令，钩子将收到如下行：

refs/heads/master 67890 refs/heads/foreign 12345

尽管将提供完整的、40个字符的SHA-1。如果外部参考还不存在，<remote SHA-1> 将是40 0。如果要删除引用，<local ref>将作为（delete）提供，<remote SHA-1>将为40 0。如果本地提交不是由可扩展的名称（如HEAD~或SHA-1）指定的，则将按最初的给定方式提供。

如果这个钩子退出非零状态，git push将中止而不推任何东西。有关拒绝推送的原因的信息可以通过写入标准错误发送给用户。

13.pre-receive(预先接收)
当git-receive-pack对其存储库中的git push和updates引用作出反应时，它将调用此钩子。在开始更新远程存储库上的refs之前，将调用预接收挂钩。它的退出状态决定了更新的成功或失败。

对于接收操作，此钩子执行一次。它不需要参数，但是对于每个要更新的ref，它在标准输入上接收一行格式：

<old-value> SP <new-value> SP <ref-name> LF

其中，<old-value>是存储在ref中的旧对象名，<new-value>是存储在ref中的新对象名，<ref-name>是ref的全名。创建新ref时，<old-value>是40 0。

如果钩子退出非零状态，则不会更新任何参考文件。如果钩子以0退出，则更新钩子仍然可以防止单个引用的更新。

标准输出和标准错误输出都被转发到另一端的git send-pack，因此您可以简单地为用户回显消息。

git push命令行中给定的push选项数--push-option=... 可以从环境变量GIT_PUSH_OPTION_COUNT中读取，选项本身位于GIT_PUSH_OPTION_0，GIT_PUSH_OPTION_1，…中。如果协商不使用PUSH options阶段，则不会设置环境变量。如果客户端选择使用push选项，但不传输任何选项，则count变量将设置为零，GIT_push_OPTION_count=0。

有关一些注意事项，请参阅git-receive-pack中关于“隔离环境”的部分。

14.update(更新)
当git-receive-pack对其存储库中的git push和updates引用作出反应时，它将调用此钩子。就在更新远程存储库上的ref之前，会调用更新挂钩。它的退出状态决定了REF更新的成败。

钩子对每个要更新的ref执行一次，并接受3个参数：

• 正在更新的ref的名称，
• 存储在ref中的旧对象名，
• 以及要存储在ref中的新对象名。

从更新钩子的零出口允许REF被更新。退出非零状态阻止git receive-pack更新REF。

通过确保对象名是commit对象（commit对象是由旧对象名命名的commit对象的后代），此钩子可用于防止强制更新某些ref。也就是说，执行“仅限快进”政策。

它还可以用来记录旧的..新的状态。但是，它不知道整个分支集，因此在天真地使用时，它最终会为每个ref触发一封电子邮件。post-receive钩子更适合这种情况。

在一个仅限制用户通过网络访问git命令的环境中，此钩子可用于实现访问控制，而不依赖文件系统所有权和组成员资格。请参阅git shell了解如何使用登录shell限制用户仅访问git命令。

标准输出和标准错误输出都被转发到另一端的git send-pack，因此您可以简单地为用户回显消息。

默认的update hook在启用时，如果hooks.allowunannotated config选项未设置或设置为false，则会阻止推送未注释的标记。

15.post-receive(接收后)
当git-receive-pack对其存储库中的git push和updates引用作出反应时，它将调用此钩子。在更新所有ref之后，它在远程存储库上执行一次。

对于接收操作，此钩子执行一次。它不接受参数，但获取的信息与pre-receive钩子在其标准输入上所做的相同。

这个钩子不会影响git receive-pack的结果，因为它是在实际工作完成后调用的。

这将取代post-update挂钩，因为它除了获取所有ref的名称外，还获取它们的旧值和新值。

标准输出和标准错误输出都被转发到另一端的git send-pack，因此您可以简单地为用户回显消息。

默认的post-receive钩子是空的，但是Git发行版的contrib/hooks目录中提供了一个示例脚本post-receive email，它实现了发送提交电子邮件。

git push命令行中给定的push选项数--push-option=...可以从环境变量GIT_PUSH_OPTION_COUNT中读取，选项本身位于GIT_PUSH_OPTION_0，GIT_PUSH_OPTION_1，…中。如果协商不使用PUSH options阶段，则不会设置环境变量。如果客户端选择使用push选项，但不传输任何选项，则count变量将设置为零，GIT_push_OPTION_count=0。

16.post-update(更新后)
当git-receive-pack对其存储库中的git push和updates引用作出反应时，它将调用此钩子。在更新所有ref之后，它在远程存储库上执行一次。

它接受可变数量的参数，每个参数都是实际更新的ref的名称。

此钩子主要用于通知，不能影响git receive-pack的结果。

post-update钩子可以告诉推送的头是什么，但是它不知道它们的原始值和更新值是什么，所以它是一个很糟糕的地方来记录旧的..新的。post-receive钩子获取refs的原始值和更新值。如果你需要的话，你可以考虑一下。

启用后，默认的post-update挂钩运行git update-server-info以保持dumb transports（例如HTTP）使用的信息是最新的。如果您要发布一个可以通过HTTP访问的Git存储库，那么您可能应该启用这个钩子。

标准输出和标准错误输出都被转发到另一端的git send-pack，因此您可以简单地为用户回显消息。

17.push-to-checkout(推送至结帐)
当git-receive-pack对其存储库中的git push和update s引用作出反应，并且当push尝试更新当前签出的分支并且receive.denyCurrentBranch配置变量设置为updateInstead时，它将调用此钩子。如果工作树和远程存储库的索引与当前签出的提交有任何差异，则默认情况下拒绝此类推送；当工作树和索引都与当前提交匹配时，它们将更新以匹配分支的新推送提示。此钩子将用于重写默认行为。

钩子接收当前分支的提示将被更新的提交。它可以以非零状态退出拒绝推送（当它这样做时，它不必修改索引或工作树）。或者，当当前分支的尖端被更新为新的提交，并以零状态退出时，它可以对工作树和索引进行任何必要的更改，以使它们达到所希望的状态。

例如，钩子可以简单地运行git read-tree -u -m HEAD "$1"，以模拟git push反向运行的git fetch，因为git read tree -u -m的两种树形式本质上与git switch或git checkout相同，后者切换分支，同时保持工作树中不干扰的本地更改树枝之间的差别。

18.pre-auto-gc(前自动gc)
这个钩子由git gc --auto调用（参见git gc）。它不需要任何参数，并且从这个脚本中退出非零状态，导致git gc --auto中止。

19.post-rewrite(重写后)
此钩子由重写提交的命令调用（使用--amend和git rebase调用git commit；但是，git fast-import或git filter-repo之类的完整历史（重新）编写工具通常不会调用它！）。它的第一个参数表示它被调用的命令：当前是amend或rebase之一。将来可能会传递更多依赖命令的参数。

钩子接收stdin上重写的提交列表，格式如下

<old-sha1> SP <new-sha1> [ SP <extra-info> ] LF

extra-info同样依赖于命令。如果为空，则前面的SP也将被忽略。目前，没有命令传递任何extra-info。

钩子总是在自动复制便笺之后运行（参见git config中的“notes.rewrite.<command>”），因此可以访问这些便笺。

以下命令特定注释适用：
rebase
对于squash和fixup操作，所有挤压的提交都将被列为被重写为挤压的提交。这意味着将有多条线路共享同一个new-sha1。
保证提交按rebase处理的顺序列出。

20.sendemail-validate(发送电子邮件验证)
此钩子由git send-email[1]调用。它只接受一个参数，即保存要发送的电子邮件的文件的名称。退出非零状态导致git send-email在发送任何电子邮件之前中止。

21.fsmonitor-watchman(监听看守者)
当配置选项core.fsmonitor设置为.git/hooks/fsmonitor-watchman时，将调用此钩子。它需要两个参数，一个版本（当前为1）和自1970年1月1日午夜以来以纳秒为单位的时间。

钩子应该输出到stdout工作目录中自请求时间以来可能已更改的所有文件的列表。逻辑应该是包含的，这样就不会遗漏任何潜在的更改。这些路径应该相对于工作目录的根目录，并由单个NUL分隔。

可以包含没有实际更改的文件。应包括所有更改，包括新创建和删除的文件。重命名文件时，应同时包含旧名称和新名称。

Git将根据给定的路径名限制它检查哪些文件进行更改，以及检查哪些目录以查找未跟踪的文件。

告诉git“所有文件都已更改”的一种优化方法是返回filename/。

退出状态决定Git是否使用钩子中的数据来限制其搜索。出错时，它将返回到验证所有文件和文件夹。

22.p4-pre-submit(p4预先提交)
此钩子由git-p4 submit调用。它不接受任何参数，也不接受标准输入。从脚本中退出非零状态，防止git-p4 submit从启动提交。运行git-p4 submit --help获取详细信息。

23.post-index-change(索引后变化)
当索引写入读缓存时调用此挂钩。c do_write_locked_index。

传递给钩子的第一个参数是正在更新的工作目录的指示符。“1”表示工作目录已更新，或“0”表示工作目录未更新。

传递给钩子的第二个参数是指示索引是否已更新以及跳过工作树位是否已更改的指示器。”“1”表示跳过工作树位可能已更新，“0”表示它们未更新。

钩子运行时，只有一个参数应设置为“1”。吊钩不应通过“1”、“1”。

husky是什么？

husky 是一个 Git Hook 工具。husky 其实就是一个为 git 客户端增加 hook 的工具。将其安装到所在仓库的过程中它会自动在.git/目录下增加相应的钩子实现在pre-commit阶段就执行一系列流程保证每一个commit 的正确性。部分 cd在 commit stage执行的命令可以挪动到本地执行，比如 lint 检查、比如单元测试。当然，pre-commit阶段执行的命令当然要保证其速度不要太慢，每次 commit 都等很久也不是什么好的体验。

husky安装

npm install husky --save-dev

// package.json
{
  "husky": {
    "hooks": {
      "pre-commit": "npm test",
      "pre-push": "npm test",
      "...": "..."
    }
  }
}

git commit -m 'Keep calm and commit'

保留现有的挂钩。需要Node >= 10和Git >= 2.13.0。

从0.14升级

运行husky-upgrade以自动升级您的配置：

npx --no-install husky-upgrade

您也可以手动执行。将现有的钩子移至husky.hooks字段并使用原始Git钩子名称。另外，如果您使用的是GIT_PARAMS env 变量，请将其重命名为HUSKY_GIT_PARAMS。

{
  "scripts": {
-   "precommit": "npm test",
-   "commitmsg": "commitlint -E GIT_PARAMS"
  },
+ "husky": {
+   "hooks": {
+     "pre-commit": "npm test",
+     "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
+   }
+ }
}

从1.0.0开始，husky 可以使用配置.huskyrc，.huskyrc.json，.huskyrc.js或husky.config.js文件。

// .huskyrc
{
  "hooks": {
    "pre-commit": "npm test"
  }
}

支持的挂钩

Husky支持此处定义的所有Git钩子。服务器端挂钩（pre-receive，update和post-receive）不被支持。

访问Git参数和标准输入

Git挂钩可以通过命令行参数和stdin获取参数。husky 使它们可以通过HUSKY_GIT_PARAMS和HUSKY_GIT_STDIN环境变量来访问。

可以简单测试一下，你就能看到这些参数其实获取到的就是你输入的message信息

"commit-msg": "echo $HUSKY_GIT_PARAMS"

跳过所有挂钩（重新定位）

在重新定位期间，您可能希望跳过所有挂钩，可以使用HUSKY_SKIP_HOOKS环境变量。

HUSKY_SKIP_HOOKS = 1 git rebase ...

禁用自动安装

如果您不希望husky自动安装Git挂钩，只需设置HUSKY_SKIP_INSTALL环境变量即可。

HUSKY_SKIP_INSTALL=1 npm install

CI服务器

默认情况下，Husky不会安装在CI服务器上。

Monorepos

如果您有一个多程序包存储库，建议使用lerna之类的工具，并且仅将husky安装在根目录中package.json以充当真理的来源。

一般来说，应该避免在多个中定义huskypackage.json，因为每个软件包都会覆盖以前的husky安装。

.
└── root
    ├── .git
    ├── package.json ?? # Add husky here
    └── packages
        ├── A
        │   └── package.json
        ├── B
        │   └── package.json
        └── C
            └── package.json

// root/package.json
{
  "private": true,
  "devDependencies": {
    "husky": "..."
  },
  "husky": {
    "hooks": {
      "pre-commit": "lerna run test"
    }
  }
}

节点版本管理器

如果您使用Windows，那么husky只会使用系统上全局安装的版本。

对于macOS和Linux用户：

• 如果您git在终端中运行命令，那么husky将使用shell中定义的版本PATH。换句话说，如果您是nvm用户，那么husky将使用您设置的版本nvm。
• 如果您使用的是GUI客户端和nvm，则它可能具有不同的PATH而不是未加载nvm，在这种情况下，通常会选择node安装的最高版本nvm。您还可以检查~/.node_path以查看GUI使用哪个版本，如果要使用其他版本，也可以进行编辑。

本地命令（?/.huskyrc）

~/.huskyrc如果在运行钩子脚本之前存在该文件，则Husky将提供源文件。您可以使用它来例如加载节点版本管理器或shell在挂接前运行一些命令。

# ~/.huskyrc
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

多个命令

根据设计，就像scripts在中定义的一样package.json，husky将钩子脚本作为单个命令运行。

"pre-commit": "cmd && cmd"

也就是说，如果您更喜欢使用数组，建议的方法是在中定义它们.huskyrc.js。

const tasks = arr => arr.join(' && ')

module.exports = {
  'hooks': {
    'pre-commit': tasks([
      'cmd',
      'cmd'
    ])
  }
}

npm-run-all之类的工具也可以提供帮助。

疑难排解

调试信息

HUSKY_DEBUG=1在运行命令时可以提供其他信息。

HUSKY_DEBUG=1 npm install husky --save-dev
HUSKY_DEBUG=1 git commit ...

挂钩没有运行

检查是否安装了挂钩。确认.git/hooks/pre-commit存在并且具有沙哑的代码。它应该以以下内容开头：

#!/bin/sh
# husky...

如果没有，您可能在package.json覆盖沙哑的钩子中定义了另一个Git钩子管理器。在安装过程中还要检查输出，您应该看到：

husky > Setting up git hooks
husky > Done

提交不被阻止

为了阻止提交，pre-commit脚本必须以非零的退出代码退出。如果您的提交未被阻止，请检查脚本退出代码。

提交很慢

Husky速度很快，而且提交的时间仅增加了十分之几秒（~0.3s在低端PC上）。因此，这很可能与期间完成了多少操作有关pre-commit。您通常可以通过在工具（babel，eslint等）上使用缓存并使用lint-staged来改善此问题。

在新仓库中测试husky

为了找出问题，您还可以创建一个新的仓库：

mkdir foo && cd foo
git init && npm init -y
npm install husky --save-dev

# Add a failing pre-commit hook to your package.json:
# "pre-commit": "echo \"this should fail\" && exit 1"

# Make a commit

ENOENT错误‘node_modules / husky / .git / hooks‘

验证您的Git版本是>=2.13.0。