uTools-Manuals/docs/git/githooks.html

<div class="c-markdown doc-markdown"><div class="doc-postil"><div class="c-markdown"><h2>命名</h2></div></div><div class="doc-postil"><div class="c-markdown"><p>githooks  -  Git 使用的挂钩</p></div></div><div class="doc-postil"><div class="c-markdown"><h2>概要</h2></div></div><div class="doc-postil"><div class="c-markdown"><p>$GIT_DIR/hooks/* (or <code>git config core.hooksPath</code>/*)</p></div></div><div class="doc-postil"><div class="c-markdown"><h2>描述</h2></div></div><div class="doc-postil"><div class="c-markdown"><p>Hook 是你可以放在钩子目录中的程序，以触发 git 执行中某些点的动作。没有可执行位设置的 Hook 将被忽略。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>默认情况下，Hook 目录是<code>$GIT_DIR/hooks</code>，但可以通过<code>core.hooksPath</code>配置变量来更改（参见 git-config [1]）。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>在 Git 调用 hook 之前，它将其工作目录更改为裸仓库中的 $ GIT_DIR 或非裸仓库中工作树的根。一个例外是推（内触发挂钩<code>pre-receive</code>，<code>update</code>，<code>post-receive</code>，<code>post-update</code>，<code>push-to-checkout</code>它们总是在 $ GIT_DIR 执行）。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>Hook 可以通过环境，命令行参数和 stdin 获得它们的参数。有关详细信息，请参阅下面每个挂钩的文档。</p></div></div><div class="doc-postil"><div class="c-markdown"><p><code>git init</code> 可能会将钩子复制到新的存储库，具体取决于其配置。有关详细信息，请参阅 git-init [1] 中的 “TEMPLATE DIRECTORY” 部分。当本文档的其余部分提到“default hooks”时，它将讨论 Git 附带的默认模板。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>下面介绍当前支持的 hook 。</p></div></div><div class="doc-postil"><div class="c-markdown"><h2>Hooks</h2></div></div><div class="doc-postil"><div class="c-markdown"><h3>applypatch-msg</h3></div></div><div class="doc-postil"><div class="c-markdown"><p>这个 hook 被调用<code>git am</code>。它采用一个参数，即包含提议的提交日志消息的文件的名称。以非零状态退出导致<code>git am</code>在应用修补程序之前中止。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>允许 hook 编辑消息文件，并可用于将消息标准化为某种项目标准格式。在检查消息文件之后，它也可以用来拒绝提交。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>默认<code>applypatch-msg</code>挂钩在启用时运行<code>commit-msg</code> hook（如果后者已启用）。</p></div></div><div class="doc-postil"><div class="c-markdown"><h3>pre-applypatch</h3></div></div><div class="doc-postil"><div class="c-markdown"><p>这个 hook 被调用<code>git am</code>。它不接受任何参数，并在应用修补程序后调用，但在提交之前调用。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>如果它以非零状态退出，则在应用修补程序后，工作树不会被提交。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>它可以用来检查当前的工作树，如果它没有通过某些测试，就拒绝提交。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>默认<code>pre-applypatch</code> hook 在启用时运行<code>pre-commit</code> hook（如果后者已启用）。</p></div></div><div class="doc-postil"><div class="c-markdown"><h3>post-applypatch</h3></div></div><div class="doc-postil"><div class="c-markdown"><p>这个 hook 被调用<code>git am</code>。它不接受任何参数，并在应用修补程序并进行提交后调用。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>这个 hook 主要是为了通知，并不能影响结果<code>git am</code>。</p></div></div><div class="doc-postil"><div class="c-markdown"><h3>pre-commit</h3></div></div><div class="doc-postil"><div class="c-markdown"><p>该 hook 由<code>git commit</code>该<code>--no-verify</code>选项调用，并且可以绕过该选项。它不接受任何参数，并在获取建议的提交日志消息并进行提交之前调用它。从该脚本中退出非零状态会导致该<code>git commit</code>命令在创建提交之前中止。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>默认<code>pre-commit</code> hook 启用后，会捕获带有尾随空白的行的介绍，并在找到这样的行时中止提交。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>如果该命令不会<code>git commit</code>调用<code>GIT_EDITOR=:</code>编辑器来修改提交消息，则所有钩子都将使用环境变量进行调用。</p></div></div><div class="doc-postil"><div class="c-markdown"><h3>prepare-commit-msg</h3></div></div><div class="doc-postil"><div class="c-markdown"><p><code>git commit</code>在编写默认日志消息之后，在编辑器启动之前，该 hook 被调用。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>它需要一到三个参数。第一个是包含提交日志消息的文件的名称。第二个是提交消息的来源，可以是：（<code>message</code>如果给出了a <code>-m</code>或<code>-F</code>选项）; <code>template</code>（如果<code>-t</code>给出选项或<code>commit.template</code>设置了配置选项）; <code>merge</code>（如果提交是合并或<code>.git/MERGE_MSG</code>文件存在）; <code>squash</code>（如果<code>.git/SQUASH_MSG</code>存在文件）; 或者<code>commit</code>，后跟提交 SHA-1（如果是<code>-c</code>，<code>-C</code>或<code>--amend</code>给予选项）。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>如果退出状态不为零，<code>git commit</code>则会中止。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>Hook 的目的是编辑邮件文件，并且不会被该<code>--no-verify</code>选项抑制。非零的退出意味着挂钩失败并放弃提交。它不应该被用作预提交 hook 的替换。</p></div></div><div class="doc-postil"><div class="c-markdown"><p><code>prepare-commit-msg</code> Git 附带的示例钩子会注释<code>Conflicts:</code>合并的提交消息的一部分。</p></div></div><div class="doc-postil"><div class="c-markdown"><h3>commit-msg</h3></div></div><div class="doc-postil"><div class="c-markdown"><p>该 hook 由<code>git commit</code>选项调用，并且可以绕过<code>--no-verify</code>选项。它采用一个参数，即包含提议的提交日志消息的文件的名称。以非零状态退出会导致<code>git commit</code>中止。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>允许 hook 编辑消息文件，并可用于将消息标准化为某种项目标准格式。在检查消息文件之后，它也可以用来拒绝提交。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>默认<code>commit-msg</code> hook 启用时检测到重复的 “Signed-off-by” 行，如果找到，则终止提交。</p></div></div><div class="doc-postil"><div class="c-markdown"><h3>post-commit</h3></div></div><div class="doc-postil"><div class="c-markdown"><p>这个 hook 被<code>git commit</code>调用。它不接受任何参数，并在提交完成后调用。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>这个 hook 主要是为了通知，并不能影响<code>git commit的</code>结果。</p></div></div><div class="doc-postil"><div class="c-markdown"><h3>pre-rebase</h3></div></div><div class="doc-postil"><div class="c-markdown"><p>此 hook 被调用<code>git rebase</code>并且可以用来防止分支得到重建。挂钩可以用一个或两个参数调用。第一个参数是系列分叉的上游。第二个参数是重新分支的分支，并在重新绑定当前分支时未设置。</p></div></div><div class="doc-postil"><div class="c-markdown"><h3>post-checkout</h3></div></div><div class="doc-postil"><div class="c-markdown"><p>当<code>git checkout</code>更新工作树后运行a时会调用此钩子。这个钩子有三个参数：前一个 HEAD 的 ref ，新 HEAD 的 ref（可能或者可能没有改变）以及一个标志，指示结帐是否是分支结账（改变分支，标志= 1）或者一个文件签出（从索引中检索一个文件，flag = 0）。这个钩子不能影响结果<code>git checkout</code>。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>它也在之后运行<code>git clone</code>，除非使用 --no-checkout（-n）选项。给 hook 的第一个参数是 null-ref ，是新 HEAD 的 ref 的第二个参数，并且该标志始终为1。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>该 hook 可用于执行存储库有效性检查，自动显示与以前 HEAD 不同的区别，或设置工作目录元数据属性。</p></div></div><div class="doc-postil"><div class="c-markdown"><h3>post-merge</h3></div></div><div class="doc-postil"><div class="c-markdown"><p>这个 hook 被调用<code>git merge</code>，当<code>git pull</code>在本地仓库上完成时发生。挂钩采用一个参数，一个状态标志指定是否合并完成是一个壁球合并。<code>git merge</code>如果合并因冲突而失败，则此挂接不会影响结果并且不会执行。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>该 hook 可以与相应的预提交钩子结合使用，以保存和恢复任何形式的与工作树关联的元数据（例如：权限/所有权，ACLS 等）。有关如何执行此操作的示例，请参阅 contrib / hooks / setgitperms.perl 。</p></div></div><div class="doc-postil"><div class="c-markdown"><h3>pre-push</h3></div></div><div class="doc-postil"><div class="c-markdown"><p>这个 hook 被调用<code>git push</code>，可以用来防止发生推送。该钩子被调用时提供了两个参数，它们提供目标远程的名称和位置，如果没有使用一个命名的远程，那么这两个值都是相同的。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>有关要推送什么的信息通过以下格式的线条在 hook 的标准输入上提供：</p></div></div><div class="doc-postil"><div class="c-markdown"><pre class="prism-token token language-javascript">&lt;local ref&gt; SP &lt;local sha1&gt; SP &lt;remote ref&gt; SP &lt;remote sha1&gt; LF</pre></div></div><div class="doc-postil"><div class="c-markdown"><p>例如，如果<code>git push origin master:foreign</code>运行该命令， hook 将收到如下所示的行：</p></div></div><div class="doc-postil"><div class="c-markdown"><pre class="prism-token token language-javascript">refs/heads/master 67890 refs/heads/foreign 12345</pre></div></div><div class="doc-postil"><div class="c-markdown"><p>尽管将提供完整的40个字符的 SHA-1 。如果国外裁判不存在，<code>&lt;remote SHA-1&gt;</code>将是40 <code>0</code>。如果一个裁判将被删除，<code>&lt;local ref&gt;</code>将提供作为<code>(delete)</code>和<code>&lt;local SHA-1&gt;</code>将是40 <code>0</code>。如果本地提交是由可扩展的名称以外的其他名称指定的（例如<code>HEAD~</code>，或 SHA-1 ），则它将按原来的形式提供。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>如果此 hook 以非零状态退出，<code>git push</code>将不中断任何操作而中止。有关推送被拒绝的原因可通过写入标准错误发送给用户。</p></div></div><div class="doc-postil"><div class="c-markdown"><h3>pre-receive</h3></div></div><div class="doc-postil"><div class="c-markdown"><p>这个 hook 是<code>git-receive-pack</code>在远程仓库上调用的，当<code>git push</code>在本地仓库上完成时会发生这种情况。在开始更新远程仓库中的 refs 之前，调用预接收 hook 。其退出状态决定了更新的成败。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>该 hook 为接收操作执行一次。它不需要任何参数，但是对于每个要更新的引用，它都会在标准输入中接收格式的一行：</p></div></div><div class="doc-postil"><div class="c-markdown"><pre class="prism-token token language-javascript">&lt;old-value&gt; SP &lt;new-value&gt; SP &lt;ref-name&gt; LF</pre></div></div><div class="doc-postil"><div class="c-markdown"><p>在<code>&lt;old-value&gt;</code> ref 中存储的旧对象名称是在 ref 中存储<code>&lt;new-value&gt;</code>的新对象名称，并且<code>&lt;ref-name&gt;</code>是 ref 的全名。当创建一个新的参考，<code>&lt;old-value&gt;</code>是40 <code>0</code>。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>如果 hook 以非零状态退出，则没有任何参数会被更新。如果钩子具有零退出，从个人参更新仍可以通过防止<em style="font-style: italic;">更新</em>钩。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>标准输出和标准错误输出都被转发到<code>git send-pack</code>另一端，因此您可以简单地<code>echo</code>向用户发送消息。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>命令行定推送选项的数量<code>git push --push-option=...</code>可以从环境变量中读取<code>GIT_PUSH_OPTION_COUNT</code>本身中找到的选项，并且<code>GIT_PUSH_OPTION_0</code>，<code>GIT_PUSH_OPTION_1</code>......如果协商不使用推送选项阶段，环境变量将不会被设置。如果客户选择使用推送选项，但不传送任何数据，则计数变量将被设置为零<code>GIT_PUSH_OPTION_COUNT=0</code>。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>有关注意事项，请参阅 git-receive-pack [1] 中的“隔离环境”部分。</p></div></div><div class="doc-postil"><div class="c-markdown"><h3>update</h3></div></div><div class="doc-postil"><div class="c-markdown"><p>这个 hook 是<code>git-receive-pack</code>在远程仓库上调用的，当<code>git push</code>在本地仓库上完成时会发生这种情况。在更新远程存储库中的 ref 之前，会调用更新挂钩。它的退出状态决定了 ref 更新的成败。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>该 hook 为每个要更新的引用执行一次，并且需要三个参数：</p></div></div><div class="doc-postil"><div class="c-markdown"><ul class="ul-level-0 list-paddingleft-2" style="margin: 10px 0px 10px 20px;"><li><p>正在更新的参考名称，</p></li></ul></div></div><div class="doc-postil"><div class="c-markdown"><ul class="ul-level-0 list-paddingleft-2" style="margin: 10px 0px 10px 20px;"><li><p>旧的对象名称存储在 ref 中，</p></li></ul></div></div><div class="doc-postil"><div class="c-markdown"><ul class="ul-level-0 list-paddingleft-2" style="margin: 10px 0px 10px 20px;"><li><p>并将新的对象名称存储在 ref 中。</p></li></ul></div></div><div class="doc-postil"><div class="c-markdown"><p>从更新挂钩零退出允许 ref 被更新。以非零状态退出可防止<code>git-receive-pack</code>更新该引用。</p></div></div><div class="doc-postil"><div class="c-markdown"><p><code>forced</code>通过确保对象名称是一个提交对象，该对象是旧对象名称所指定的提交对象的后代，该 hook 可用于防止更新某些引用。也就是说，强制执行“仅快进”策略。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>它也可以用来记录旧的......新状态。但是，它并不知道整套分支，所以最终会在天真地使用时为每个参考文献发送一封电子邮件。在<em style="font-style: italic;">后收到</em>钩更适合一点。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>在一个限制用户仅通过线路访问 git 命令的环境中，该 hook 可用于实现访问控制，而不依赖文件系统所有权和组成员身份。有关如何使用登录 shell 来限制用户对 git 命令的访问，请参阅 git-shell [1]。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>标准输出和标准错误输出都被转发到<code>git send-pack</code>另一端，因此您可以简单地<code>echo</code>向用户发送消息。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>默认<code>update</code> hook <code>hooks.allowunannotated</code>启用时（且配置选项未设置或设置为false）可防止未注释的标签被推送。</p></div></div><div class="doc-postil"><div class="c-markdown"><h3>post-receive</h3></div></div><div class="doc-postil"><div class="c-markdown"><p>这个 hook 是<code>git-receive-pack</code>在远程仓库上调用的，当<code>git push</code>在本地仓库上完成时会发生这种情况。它在更新所有 ref 后立即在远程存储库上执行。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>该 hook 为接收操作执行一次。它不需要任何参数，但会获得与<em style="font-style: italic;">预接收</em>钩子在其标准输入上相同的信息。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>这个 hook 并不影响结果<code>git-receive-pack</code>，因为它是在真正的工作完成后调用的。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>这取代了<em style="font-style: italic;">更新后的</em> hook ，它除了获得所有参考名称之外，还获得了所有参考的新旧值。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>标准输出和标准错误输出都被转发到<code>git send-pack</code>另一端，因此您可以简单地<code>echo</code>向用户发送消息。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>默认<code>post-receive</code> hook 为空，但在 Git 分配<code>post-receive-email</code>的<code>contrib/hooks</code>目录中提供了一个示例脚本，该脚本实现了发送提交邮件。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>命令行定推送选项的数量<code>git push --push-option=...</code>可以从环境变量中读取<code>GIT_PUSH_OPTION_COUNT</code>本身中找到的选项，并且<code>GIT_PUSH_OPTION_0</code>，<code>GIT_PUSH_OPTION_1</code>......如果协商不使用推送选项阶段，环境变量将不会被设置。如果客户选择使用推送选项，但不传送任何数据，则计数变量将被设置为零<code>GIT_PUSH_OPTION_COUNT=0</code>。</p></div></div><div class="doc-postil"><div class="c-markdown"><h3>post-update</h3></div></div><div class="doc-postil"><div class="c-markdown"><p>这个 hook 是<code>git-receive-pack</code>在远程仓库上调用的，当<code>git push</code>在本地仓库上完成时会发生这种情况。它在更新所有 ref 后立即在远程存储库上执行。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>它需要可变数量的参数，每个参数都是实际更新的 ref 的名称。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>这个 hook 主要是为了通知，并不能影响结果<code>git-receive-pack</code>。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>该<code>post-update</code>能告诉什么是推送的头，但它不知道他们原来的和更新的值，所以它是做记录 old..new 一个穷地方。在<em style="font-style: italic;">后收到</em> hook 并得到裁判的原件和更新的值。如果你需要它们，你可以考虑它。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>启用后，默认<code>post-update</code>将运行<code>git update-server-info</code>以保持传输（例如，HTTP）使用的信息最新。如果您正在发布可通过HTTP访问的Git存储库，则应该启用此挂接。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>标准输出和标准错误输出都被转发到<code>git send-pack</code>另一端，因此您可以简单地<code>echo</code>向用户发送消息。</p></div></div><div class="doc-postil"><div class="c-markdown"><h3>push-to-checkout</h3></div></div><div class="doc-postil"><div class="c-markdown"><p>该钩子由<code>git-receive-pack</code>远程存储库调用<code>git push</code>，当在本地存储库上完成a操作时，当推送尝试更新当前检出的分支并将<code>receive.denyCurrentBranch</code>配置变量设置为<code>updateInstead</code>。如果远程存储库的工作树和索引与当前检出的提交有任何不同，则默认情况下会拒绝这种推送; 当工作树和索引都与当前提交匹配时，它们会更新以匹配分支的新推入的提示。该钩子将用于覆盖默认行为。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>钩子接收当前分支的尖端将被更新的提交。它可以以非零状态退出以拒绝推送（当它这样做时，它不能修改索引或工作树）。或者，它可以对工作树和索引进行任何必要的更改，以在当前分支的提示更新为新提交时将其带到期望的状态，并以零状态退出。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>例如，钩子可以简单地运行<code>git read-tree -u -m HEAD "$1"</code>，以模拟<code>git fetch</code>与反向运行的钩子<code>git push</code>，因为双树形式<code>read-tree -u -m</code>基本上与<code>git checkout</code>开关分支相同，同时保持工作树中不会干扰的局部变化分支之间的差异。</p></div></div><div class="doc-postil"><div class="c-markdown"><h3>pre-auto-gc</h3></div></div><div class="doc-postil"><div class="c-markdown"><p>这个钩子被调用<code>git gc --auto</code>。它不接受任何参数，并从此脚本中<code>git gc --auto</code>以非零状态退出导致中止。</p></div></div><div class="doc-postil"><div class="c-markdown"><h3>post-rewrite</h3></div></div><div class="doc-postil"><div class="c-markdown"><p>这个钩子被重写提交的命令调用（<code>git commit --amend</code>，<code>git-rebase</code>;目前<code>git-filter-branch</code>确实<code>not</code>叫它！）。它的第一个参数表示它被调用的命令：当前是<code>amend</code>or的一个<code>rebase</code>。更多的依赖于命令的参数可能会在未来传递。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>该钩子以格式接收stdin上重写的提交列表</p></div></div><div class="doc-postil"><div class="c-markdown"><pre class="prism-token token language-javascript">&lt;old-sha1&gt; SP &lt;new-sha1&gt; [ SP &lt;extra-info&gt; ] LF</pre></div></div><div class="doc-postil"><div class="c-markdown"><p>这又<code>extra-info</code>是依赖于命令的。如果它是空的，则前面的SP也被省略。目前，没有命令通过任何<code>extra-info</code>。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>钩子总是在自动音符复制之后运行（请参阅git-config [1]中的“notes.rewrite。&lt;command&gt;”），因此可以访问这些音符。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>以下特定于命令的注释适用于：</p></div></div><div class="doc-postil"><div class="c-markdown"><p>rebase</p></div></div><div class="doc-postil"><div class="c-markdown"><p>对于<code>squash</code>和<code>fixup</code>操作，被压扁，所有提交被列为被改写成压扁的承诺。这意味着将会有几条线路共享相同的信息<code>new-sha1</code>。</p></div></div><div class="doc-postil"><div class="c-markdown"><p>提交将保证按照他们通过rebase处理的顺序列出。</p></div></div><div class="doc-postil"><div class="c-markdown"><h3>sendemail-validate</h3></div></div><div class="doc-postil"><div class="c-markdown"><p>这个钩子被调用<code>git send-email</code>。它需要一个参数，即保存要发送的电子邮件的文件的名称。以非零状态退出导致<code>git send-email</code>在发送任何电子邮件之前中止。</p></div></div></div>