diff --git a/Documentation/config.adoc b/Documentation/config.adoc index dcea3c0c15..a80e7db46d 100644 --- a/Documentation/config.adoc +++ b/Documentation/config.adoc @@ -451,6 +451,8 @@ include::config/guitool.adoc[] include::config/help.adoc[] +include::config/hook.adoc[] + include::config/http.adoc[] include::config/i18n.adoc[] diff --git a/Documentation/config/hook.adoc b/Documentation/config/hook.adoc index a9dc0063c1..083dc60a13 100644 --- a/Documentation/config/hook.adoc +++ b/Documentation/config/hook.adoc @@ -1,10 +1,17 @@ +ifdef::git-hook[] +:see-git-hook: +endif::git-hook[] +ifndef::git-hook[] +:see-git-hook: See linkgit:git-hook[1]. +endif::git-hook[] + hook..command:: The command to execute for `hook.`. `` is a unique name that identifies this hook. The hook events that trigger the command are configured with `hook..event`. The value can be an executable path or a shell oneliner. If more than one value is specified for the same ``, only the last - value parsed is used. See linkgit:git-hook[1]. + value parsed is used. {see-git-hook} hook..event:: The hook events that trigger `hook.`. The value is the @@ -14,7 +21,7 @@ hook..event:: This is a multi-valued key. To run `hook.` on multiple events, specify the key more than once. An empty value resets the list of events, clearing any previously defined events for - `hook.`. See linkgit:git-hook[1]. + `hook.`. {see-git-hook} + The `` must not be the same as a known hook event name (e.g. do not use `hook.pre-commit.event`). Using a known event name as @@ -27,7 +34,7 @@ hook..enabled:: Set to `false` to disable the hook without removing its configuration. This is particularly useful when a hook is defined in a system or global config file and needs to be disabled for a - specific repository. See linkgit:git-hook[1]. + specific repository. {see-git-hook} hook..parallel:: Whether the hook `hook.` may run in parallel with other hooks @@ -37,13 +44,13 @@ hook..parallel:: all hooks for that event run sequentially regardless of `hook.jobs`. Only configured (named) hooks need to declare this. Traditional hooks found in the hooks directory do not need to, and run in parallel when - the effective job count is greater than 1. See linkgit:git-hook[1]. + the effective job count is greater than 1. {see-git-hook} hook..enabled:: Switch to enable or disable all hooks for the `` hook event. When set to `false`, no hooks fire for that event, regardless of any per-hook `hook..enabled` settings. Defaults to `true`. - See linkgit:git-hook[1]. + {see-git-hook} + Note on naming: `` must be the event name (e.g. `pre-commit`), not a hook friendly-name. Since using a known event name as a @@ -60,7 +67,7 @@ hook..jobs:: setting has no effect unless all configured hooks for the event have `hook..parallel` set to `true`. Set to `-1` to use the number of available CPU cores. Must be a positive integer or `-1`; - zero is rejected with a warning. See linkgit:git-hook[1]. + zero is rejected with a warning. {see-git-hook} + Note on naming: although this key resembles `hook..*` (a per-hook setting), `` must be the event name, not a hook diff --git a/Documentation/git-hook.adoc b/Documentation/git-hook.adoc index 46ea52db55..4868852aa0 100644 --- a/Documentation/git-hook.adoc +++ b/Documentation/git-hook.adoc @@ -3,7 +3,7 @@ git-hook(1) NAME ---- -git-hook - Run git hooks +git-hook - Run Git hooks SYNOPSIS -------- @@ -15,8 +15,8 @@ SYNOPSIS DESCRIPTION ----------- -A command interface for running git hooks (see linkgit:githooks[5]), -for use by other scripted git commands. +A command interface for running Git hooks (see linkgit:githooks[5]), +for use by other scripted Git commands. This command parses the default configuration files for sets of configs like so: @@ -41,7 +41,7 @@ spell-checker for your commit messages, you would write a configuration like so: With this config, when you run 'git commit', first `~/bin/linter --cpp20` will have a chance to check your files to be committed (during the `pre-commit` hook -event`), and then `~/bin/spellchecker` will have a chance to check your commit +event), and then `~/bin/spellchecker` will have a chance to check your commit message (during the `commit-msg` hook event). Commands are run in the order Git encounters their associated @@ -161,7 +161,7 @@ setting, allowing all hooks for the event to run concurrently, even if they are not individually marked as parallel. + Some hooks always run sequentially regardless of this flag or the -`hook.jobs` config, because git knows they cannot safely run in parallel: +`hook.jobs` config, because Git knows they cannot safely run in parallel: `applypatch-msg`, `pre-commit`, `prepare-commit-msg`, `commit-msg`, `post-commit`, `post-checkout`, and `push-to-checkout`. @@ -204,6 +204,7 @@ unintended and unsupported ways. CONFIGURATION ------------- +:git-hook: 1 include::config/hook.adoc[] SEE ALSO