| 1 | ifdef::git-hook[] |
| 2 | :see-git-hook: |
| 3 | endif::git-hook[] |
| 4 | ifndef::git-hook[] |
| 5 | :see-git-hook: See linkgit:git-hook[1]. |
| 6 | endif::git-hook[] |
| 7 | |
| 8 | hook.<friendly-name>.command:: |
| 9 | The command to execute for `hook.<friendly-name>`. `<friendly-name>` |
| 10 | is a unique name that identifies this hook. The hook events that |
| 11 | trigger the command are configured with `hook.<friendly-name>.event`. |
| 12 | The value can be an executable path or a shell oneliner. If more than |
| 13 | one value is specified for the same `<friendly-name>`, only the last |
| 14 | value parsed is used. {see-git-hook} |
| 15 | |
| 16 | hook.<friendly-name>.event:: |
| 17 | The hook events that trigger `hook.<friendly-name>`. The value is the |
| 18 | name of a hook event, like "pre-commit" or "update". (See |
| 19 | linkgit:githooks[5] for a complete list of hook events.) On the |
| 20 | specified event, the associated `hook.<friendly-name>.command` is executed. |
| 21 | This is a multi-valued key. To run `hook.<friendly-name>` on multiple |
| 22 | events, specify the key more than once. An empty value resets |
| 23 | the list of events, clearing any previously defined events for |
| 24 | `hook.<friendly-name>`. {see-git-hook} |
| 25 | + |
| 26 | The `<friendly-name>` must not be the same as a known hook event name |
| 27 | (e.g. do not use `hook.pre-commit.event`). Using a known event name as |
| 28 | a friendly-name is a fatal error because it creates an ambiguity with |
| 29 | `hook.<event>.enabled` and `hook.<event>.jobs`. For unknown event names, |
| 30 | a warning is issued when `<friendly-name>` matches the event value. |
| 31 | |
| 32 | hook.<friendly-name>.enabled:: |
| 33 | Whether the hook `hook.<friendly-name>` is enabled. Defaults to `true`. |
| 34 | Set to `false` to disable the hook without removing its |
| 35 | configuration. This is particularly useful when a hook is defined |
| 36 | in a system or global config file and needs to be disabled for a |
| 37 | specific repository. {see-git-hook} |
| 38 | |
| 39 | hook.<friendly-name>.parallel:: |
| 40 | Whether the hook `hook.<friendly-name>` may run in parallel with other hooks |
| 41 | for the same event. Defaults to `false`. Set to `true` only when the |
| 42 | hook script is safe to run concurrently with other hooks for the same |
| 43 | event. If any hook for an event does not have this set to `true`, |
| 44 | all hooks for that event run sequentially regardless of `hook.jobs`. |
| 45 | Only configured (named) hooks need to declare this. Traditional hooks |
| 46 | found in the hooks directory do not need to, and run in parallel when |
| 47 | the effective job count is greater than 1. {see-git-hook} |
| 48 | |
| 49 | hook.<event>.enabled:: |
| 50 | Switch to enable or disable all hooks for the `<event>` hook event. |
| 51 | When set to `false`, no hooks fire for that event, regardless of any |
| 52 | per-hook `hook.<friendly-name>.enabled` settings. Defaults to `true`. |
| 53 | {see-git-hook} |
| 54 | + |
| 55 | Note on naming: `<event>` must be the event name (e.g. `pre-commit`), |
| 56 | not a hook friendly-name. Since using a known event name as a |
| 57 | friendly-name is disallowed (see `hook.<friendly-name>.event` above), |
| 58 | there is no ambiguity between event-level and per-hook `.enabled` |
| 59 | settings for known events. For unknown events, if a friendly-name |
| 60 | matches the event name despite the warning, `.enabled` is treated |
| 61 | as per-hook only. |
| 62 | |
| 63 | hook.<event>.jobs:: |
| 64 | Specifies how many hooks can be run simultaneously for the `<event>` |
| 65 | hook event (e.g. `hook.post-receive.jobs = 4`). Overrides `hook.jobs` |
| 66 | for this specific event. The same parallelism restrictions apply: this |
| 67 | setting has no effect unless all configured hooks for the event have |
| 68 | `hook.<friendly-name>.parallel` set to `true`. Set to `-1` to use the |
| 69 | number of available CPU cores. Must be a positive integer or `-1`; |
| 70 | zero is rejected with a warning. {see-git-hook} |
| 71 | + |
| 72 | Note on naming: although this key resembles `hook.<friendly-name>.*` |
| 73 | (a per-hook setting), `<event>` must be the event name, not a hook |
| 74 | friendly name. The key component is stored literally and looked up by |
| 75 | event name at runtime with no translation between the two namespaces. |
| 76 | A key like `hook.my-hook.jobs` is stored under `"my-hook"` but the |
| 77 | lookup at runtime uses the event name (e.g. `"post-receive"`), so |
| 78 | `hook.my-hook.jobs` is silently ignored even when `my-hook` is |
| 79 | registered for that event. Use `hook.post-receive.jobs` or any other |
| 80 | valid event name when setting `hook.<event>.jobs`. |
| 81 | |
| 82 | hook.jobs:: |
| 83 | Specifies how many hooks can be run simultaneously during parallelized |
| 84 | hook execution. If unspecified, defaults to 1 (serial execution). |
| 85 | Set to `-1` to use the number of available CPU cores. |
| 86 | Can be overridden on a per-event basis with `hook.<event>.jobs`. |
| 87 | Some hooks always run sequentially regardless of this setting because |
| 88 | they operate on shared data and cannot safely be parallelized: |
| 89 | + |
| 90 | -- |
| 91 | `applypatch-msg`;; |
| 92 | `prepare-commit-msg`;; |
| 93 | `commit-msg`;; |
| 94 | Receive a commit message file and may rewrite it in place. |
| 95 | `pre-commit`;; |
| 96 | `post-checkout`;; |
| 97 | `push-to-checkout`;; |
| 98 | `post-commit`;; |
| 99 | Access the working tree, index, or repository state. |
| 100 | -- |
| 101 | + |
| 102 | This setting has no effect unless all configured hooks for the event have |
| 103 | `hook.<friendly-name>.parallel` set to `true`. |
| 104 | + |
| 105 | For `pre-push` hooks, which normally keep stdout and stderr separate, |
| 106 | setting this to a value greater than 1 (or passing `-j`) will merge stdout |
| 107 | into stderr to allow correct de-interleaving of parallel output. |