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