Document the semantics and behavior of multiple hooks, including the configuration options and requirements for them to be run. Signed-off-by: brian m. carlson <sandals@xxxxxxxxxxxxxxxxxxxx> --- Documentation/config.txt | 2 ++ Documentation/config/hook.txt | 19 +++++++++++++++++++ Documentation/githooks.txt | 9 +++++++++ 3 files changed, 30 insertions(+) create mode 100644 Documentation/config/hook.txt diff --git a/Documentation/config.txt b/Documentation/config.txt index d87846faa6..f62b8ce494 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -350,6 +350,8 @@ include::config/guitool.txt[] include::config/help.txt[] +include::config/hook.txt[] + include::config/http.txt[] include::config/i18n.txt[] diff --git a/Documentation/config/hook.txt b/Documentation/config/hook.txt new file mode 100644 index 0000000000..4585cc7f55 --- /dev/null +++ b/Documentation/config/hook.txt @@ -0,0 +1,19 @@ +hook.<name>.errorBehavior:: + Control the error behavior when using multiple hooks. ++ +-- +* `stop-on-first` - If a hook fails, do not execute further hooks, even if the + command normally ignores whether hooks succeed or fail, and return its exit + code as the exit code of the hook set. If all hooks succeed, the exit code is 0. + This is the default. +* `report-any-error` - Always execute all hooks, but return the exit code of the + first failing hook as the exit code of the hook set. If all hooks succeed, the + exit code of the hook set is 0. +* `report-any-success` - Always execute all hooks, and if any hook succeeds, + return 0 as the exit code of the hook set. If all hooks fail, the exit code of + the hook set is 1. +-- ++ +If the exit code of the hook set is zero, then the hooks are considered to have +succeeded; otherwise, they are considered to have failed. Note that the success +or failure of some hooks is ignored (see linkgit:githooks[5] for more). diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index 786e778ab8..c680e575b3 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -31,6 +31,15 @@ Hooks can get their arguments via the environment, command-line arguments, and stdin. See the documentation for each hook below for details. +It is possible to provide multiple hooks for a single function. If the +main hook file is absent, hooks are additionally looked for in a +directory with the name of the main hook file with a `.d` appended. +(That is, if `post-receive` is missing, `post-receive.d` is inspected +for any hooks that might be present.) Each of these hooks is executed in order, +sorted by file name. By default, if a hook fails, additional hooks are not +executed, but this can be controlled with the `hook.*.errorBehavior` setting +(see linkgit:git-config[1]). + `git init` may copy hooks to the new repository, depending on its configuration. See the "TEMPLATE DIRECTORY" section in linkgit:git-init[1] for details. When the rest of this document refers
