Pro Git 中文版

Appearance

git-hook ​

运行 git 钩子

概要 ​

'git hook' run [--allow-unknown-hook-name] [--ignore-missing] [--to-stdin=<path>] [(-j|--jobs) <n>]
	<hook-name> [-- <hook-args>]
'git hook' list [--allow-unknown-hook-name] [-z] [--show-scope] <hook-name>

描述 ​

用于运行 git 钩子（参见 githooks(5)）的命令接口，供其他脚本化 git 命令使用。

此命令解析默认配置文件以获取如下配置集：

[hook "linter"]
  event = pre-commit
  command = ~/bin/linter --cpp20

在此示例中，[hook "linter"] 表示一个脚本——~/bin/linter --cpp20——可以由多个仓库共享，甚至可以由多个钩子事件共享（如果合适）。

要添加在不同事件上运行的无关钩子（例如提交消息的拼写检查器），您可以编写如下配置：

[hook "linter"]
  event = pre-commit
  command = ~/bin/linter --cpp20
[hook "spellcheck"]
  event = commit-msg
  command = ~/bin/spellchecker

使用此配置，当您运行 'git commit' 时，首先 ~/bin/linter --cpp20 将有机会检查您要提交的文件（在 pre-commit 钩子事件期间），然后 ~/bin/spellchecker 将有机会检查您的提交消息（在 commit-msg 钩子事件期间）。

命令按 Git 在配置解析期间遇到其关联的 hook.<friendly-name>.event 配置的顺序运行（参见 git-config(1)）。虽然可以添加多个 hook.linter.event 配置，但只有一个 hook.linter.command 事件有效——Git 使用"最后一个获胜"来确定运行哪个命令。

子命令 ​

  • run - 运行为 <hook-name> 配置的钩子，按配置解析期间发现的顺序运行。钩子目录中的默认 <hook-name> 最后运行。有关支持的钩子名称，请参阅 githooks(5)。 钩子的任何位置参数应在强制性的 --（或 --end-of-options，参见 gitcli(7)）之后传递。

  • list [-z] [--show-scope] - 打印将在 <hook-name> 事件上运行的钩子列表。如果未为该事件配置钩子，打印警告并返回 1。使用 -z 以 NUL 而不是换行符终止输出行。

选项 ​

  • --allow-unknown-hook-name - 默认情况下，git hook run 和 git hook list 会在 <hook-name> 不是 Git 已知的钩子事件时中止（有关已知钩子的列表，请参阅 githooks(5)）。这是为了帮助捕获拼写错误。传递此标志以允许未知的钩子名称。

  • --to-stdin - 对于 "run"；指定将流式传输到钩子 stdin 的文件。钩子将从头到 EOF 接收整个文件。

  • --ignore-missing - 通过静默返回零来忽略任何缺失的钩子。用于想要对可能存在也可能不存在的钩子进行一次性盲目运行的工具。

  • -z - 以 NUL 而不是换行符终止 "list" 输出行。

  • --show-scope - 对于 "list"；在每个配置的钩子的友好名称前加上制表符分隔的配置范围（例如 local、global、system），镜像 git config --show-scope 的输出样式。来自钩子目录的传统钩子不受影响。

  • -j, --jobs - 仅对 run 有效。 指定同时运行多少个钩子。如果未指定此标志，使用 hook.jobs 配置的值。如果都未指定，默认为 1（串行执行）。 当大于 1 时，它覆盖每钩子的 hook.<friendly-name>.parallel 设置，允许事件的所有钩子并发运行，即使它们未单独标记为并行。 无论此标志或 hook.jobs 配置如何，某些钩子始终串行运行，因为 git 知道它们无法安全地并行运行：applypatch-msg、pre-commit、prepare-commit-msg、commit-msg、post-commit、post-checkout 和 push-to-checkout。

包装器 ​

git hook run 旨在使包装 Git 的工具可以轻松使用 Git 钩子基础设施配置和执行钩子。可以通过命令行提供参数和 stdin，以及指定并行或串行执行（如果用户提供了多个钩子）。

假设您的包装器想要支持名为 "mywrapper-start-tests" 的钩子，您可以如下配置：

[hook "setup-test-dashboard"]
  event = mywrapper-start-tests
  command = ~/mywrapper/setup-dashboard.py --tap

然后，在您的 'mywrapper' 工具中，您可以通过运行以下命令调用任何用户配置的钩子：

git hook run --allow-unknown-hook-name mywrapper-start-tests \
  --stdin some-tempfile-123 \
  --jobs 3 \
  -- \
  --testname bar \
  baz

配置 ​

  • hook.<friendly-name>.command - 要为 hook.<friendly-name> 执行的命令。<friendly-name> 是标识此钩子的唯一名称。触发命令的钩子事件通过 hook.<friendly-name>.event 配置。该值可以是可执行路径或 shell 单行命令。

  • hook.<friendly-name>.event - 触发 hook.<friendly-name> 的钩子事件。该值是钩子事件的名称，如 "pre-commit" 或 "update"。这是一个多值键。要在多个事件上运行 hook.<friendly-name>，请多次指定该键。空值会重置事件列表。

  • hook.<friendly-name>.enabled - 钩子 hook.<friendly-name> 是否启用。默认为 true。设置为 false 以在不删除其配置的情况下禁用钩子。

  • hook.<friendly-name>.parallel - 钩子 hook.<friendly-name> 是否可以与其他钩子并行运行。默认为 false。仅当钩子脚本可以安全地与同一事件的其他钩子并发运行时才设置为 true。

  • hook.<event>.enabled - 启用或禁用 <event> 钩子事件的所有钩子的开关。设置为 false 时，该事件不会触发任何钩子。默认为 true。

  • hook.<event>.jobs - 指定可以为 <event> 钩子事件同时运行多少个钩子。覆盖此特定事件的 hook.jobs。设置为 -1 以使用可用 CPU 核心数。

  • hook.jobs - 指定在并行化钩子执行期间可以同时运行多少个钩子。如果未指定，默认为 1（串行执行）。设置为 -1 以使用可用 CPU 核心数。可以通过 hook.<event>.jobs 按事件覆盖。

另请参阅 ​

githooks(5)

Git ​

git(1) 套件的一部分

基于 CC BY-NC-SA 3.0 许可发布

Pro Git 中文版