| 1 | git-hook(1) |
| 2 | =========== |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | git-hook - Run Git hooks |
| 7 | |
| 8 | SYNOPSIS |
| 9 | -------- |
| 10 | [verse] |
| 11 | 'git hook' run [--allow-unknown-hook-name] [--ignore-missing] [--to-stdin=<path>] [(-j|--jobs) <n>] |
| 12 | <hook-name> [-- <hook-args>] |
| 13 | 'git hook' list [--allow-unknown-hook-name] [-z] [--show-scope] <hook-name> |
| 14 | |
| 15 | DESCRIPTION |
| 16 | ----------- |
| 17 | |
| 18 | A command interface for running Git hooks (see linkgit:githooks[5]), |
| 19 | for use by other scripted Git commands. |
| 20 | |
| 21 | This command parses the default configuration files for sets of configs like |
| 22 | so: |
| 23 | |
| 24 | [hook "linter"] |
| 25 | event = pre-commit |
| 26 | command = ~/bin/linter --cpp20 |
| 27 | |
| 28 | In this example, `[hook "linter"]` represents one script - `~/bin/linter |
| 29 | --cpp20` - which can be shared by many repos, and even by many hook events, if |
| 30 | appropriate. |
| 31 | |
| 32 | To add an unrelated hook which runs on a different event, for example a |
| 33 | spell-checker for your commit messages, you would write a configuration like so: |
| 34 | |
| 35 | [hook "linter"] |
| 36 | event = pre-commit |
| 37 | command = ~/bin/linter --cpp20 |
| 38 | [hook "spellcheck"] |
| 39 | event = commit-msg |
| 40 | command = ~/bin/spellchecker |
| 41 | |
| 42 | With this config, when you run 'git commit', first `~/bin/linter --cpp20` will |
| 43 | have a chance to check your files to be committed (during the `pre-commit` hook |
| 44 | event), and then `~/bin/spellchecker` will have a chance to check your commit |
| 45 | message (during the `commit-msg` hook event). |
| 46 | |
| 47 | Commands are run in the order Git encounters their associated |
| 48 | `hook.<friendly-name>.event` configs during the configuration parse (see |
| 49 | linkgit:git-config[1]). Although multiple `hook.linter.event` configs can be |
| 50 | added, only one `hook.linter.command` event is valid - Git uses "last-one-wins" |
| 51 | to determine which command to run. |
| 52 | |
| 53 | So if you wanted your linter to run when you commit as well as when you push, |
| 54 | you would configure it like so: |
| 55 | |
| 56 | [hook "linter"] |
| 57 | event = pre-commit |
| 58 | event = pre-push |
| 59 | command = ~/bin/linter --cpp20 |
| 60 | |
| 61 | With this config, `~/bin/linter --cpp20` would be run by Git before a commit is |
| 62 | generated (during `pre-commit`) as well as before a push is performed (during |
| 63 | `pre-push`). |
| 64 | |
| 65 | And if you wanted to run your linter as well as a secret-leak detector during |
| 66 | only the "pre-commit" hook event, you would configure it instead like so: |
| 67 | |
| 68 | [hook "linter"] |
| 69 | event = pre-commit |
| 70 | command = ~/bin/linter --cpp20 |
| 71 | [hook "no-leaks"] |
| 72 | event = pre-commit |
| 73 | command = ~/bin/leak-detector |
| 74 | |
| 75 | With this config, before a commit is generated (during `pre-commit`), Git would |
| 76 | first start `~/bin/linter --cpp20` and second start `~/bin/leak-detector`. It |
| 77 | would evaluate the output of each when deciding whether to proceed with the |
| 78 | commit. |
| 79 | |
| 80 | For a full list of hook events which you can set your `hook.<friendly-name>.event` to, |
| 81 | and how hooks are invoked during those events, see linkgit:githooks[5]. |
| 82 | |
| 83 | Git will ignore any `hook.<friendly-name>.event` that specifies an event it doesn't |
| 84 | recognize. This is intended so that tools which wrap Git can use the hook |
| 85 | infrastructure to run their own hooks; see "WRAPPERS" for more guidance. |
| 86 | |
| 87 | In general, when instructions suggest adding a script to |
| 88 | `.git/hooks/<hook-event>`, you can specify it in the config instead by running: |
| 89 | |
| 90 | ---- |
| 91 | git config set hook.<some-name>.command <path-to-script> |
| 92 | git config set --append hook.<some-name>.event <hook-event> |
| 93 | ---- |
| 94 | |
| 95 | This way you can share the script between multiple repos. That is, `cp |
| 96 | ~/my-script.sh ~/project/.git/hooks/pre-commit` would become: |
| 97 | |
| 98 | ---- |
| 99 | git config set hook.my-script.command ~/my-script.sh |
| 100 | git config set --append hook.my-script.event pre-commit |
| 101 | ---- |
| 102 | |
| 103 | SUBCOMMANDS |
| 104 | ----------- |
| 105 | |
| 106 | run:: |
| 107 | Runs hooks configured for `<hook-name>`, in the order they are |
| 108 | discovered during the config parse. The default `<hook-name>` from |
| 109 | the hookdir is run last. See linkgit:githooks[5] for supported |
| 110 | hook names. |
| 111 | + |
| 112 | |
| 113 | Any positional arguments to the hook should be passed after a |
| 114 | mandatory `--` (or `--end-of-options`, see linkgit:gitcli[7]). See |
| 115 | linkgit:githooks[5] for arguments hooks might expect (if any). |
| 116 | |
| 117 | list [-z] [--show-scope]:: |
| 118 | Print a list of hooks which will be run on `<hook-name>` event. If no |
| 119 | hooks are configured for that event, print a warning and return 1. |
| 120 | Use `-z` to terminate output lines with NUL instead of newlines. |
| 121 | |
| 122 | OPTIONS |
| 123 | ------- |
| 124 | |
| 125 | --allow-unknown-hook-name:: |
| 126 | By default `git hook run` and `git hook list` will bail out when |
| 127 | `<hook-name>` is not a hook event known to Git (see linkgit:githooks[5] |
| 128 | for the list of known hooks). This is meant to help catch typos |
| 129 | such as `prereceive` when `pre-receive` was intended. Pass this |
| 130 | flag to allow unknown hook names. |
| 131 | |
| 132 | --to-stdin:: |
| 133 | For "run"; specify a file which will be streamed into the |
| 134 | hook's stdin. The hook will receive the entire file from |
| 135 | beginning to EOF. |
| 136 | |
| 137 | --ignore-missing:: |
| 138 | Ignore any missing hook by quietly returning zero. Used for |
| 139 | tools that want to do a blind one-shot run of a hook that may |
| 140 | or may not be present. |
| 141 | |
| 142 | -z:: |
| 143 | Terminate "list" output lines with NUL instead of newlines. |
| 144 | |
| 145 | --show-scope:: |
| 146 | For "list"; prefix each configured hook's friendly name with a |
| 147 | tab-separated config scope (e.g. `local`, `global`, `system`), |
| 148 | mirroring the output style of `git config --show-scope`. Traditional |
| 149 | hooks from the hookdir are unaffected. |
| 150 | |
| 151 | -j:: |
| 152 | --jobs:: |
| 153 | Only valid for `run`. |
| 154 | + |
| 155 | Specify how many hooks to run simultaneously. If this flag is not specified, |
| 156 | the value of the `hook.jobs` config is used, see linkgit:git-config[1]. If |
| 157 | neither is specified, defaults to 1 (serial execution). |
| 158 | + |
| 159 | When greater than 1, it overrides the per-hook `hook.<friendly-name>.parallel` |
| 160 | setting, allowing all hooks for the event to run concurrently, even if they |
| 161 | are not individually marked as parallel. |
| 162 | + |
| 163 | Some hooks always run sequentially regardless of this flag or the |
| 164 | `hook.jobs` config, because Git knows they cannot safely run in parallel: |
| 165 | `applypatch-msg`, `pre-commit`, `prepare-commit-msg`, `commit-msg`, |
| 166 | `post-commit`, `post-checkout`, and `push-to-checkout`. |
| 167 | |
| 168 | WRAPPERS |
| 169 | -------- |
| 170 | |
| 171 | `git hook run` has been designed to make it easy for tools which wrap Git to |
| 172 | configure and execute hooks using the Git hook infrastructure. It is possible to |
| 173 | provide arguments and stdin via the command line, as well as specifying parallel |
| 174 | or series execution if the user has provided multiple hooks. |
| 175 | |
| 176 | Assuming your wrapper wants to support a hook named "mywrapper-start-tests", you |
| 177 | can have your users specify their hooks like so: |
| 178 | |
| 179 | [hook "setup-test-dashboard"] |
| 180 | event = mywrapper-start-tests |
| 181 | command = ~/mywrapper/setup-dashboard.py --tap |
| 182 | |
| 183 | Then, in your 'mywrapper' tool, you can invoke any users' configured hooks by |
| 184 | running: |
| 185 | |
| 186 | ---- |
| 187 | git hook run --allow-unknown-hook-name mywrapper-start-tests \ |
| 188 | # providing something to stdin |
| 189 | --stdin some-tempfile-123 \ |
| 190 | # execute multiple hooks in parallel |
| 191 | --jobs 3 \ |
| 192 | # plus some arguments of your own... |
| 193 | -- \ |
| 194 | --testname bar \ |
| 195 | baz |
| 196 | ---- |
| 197 | |
| 198 | Take care to name your wrapper's hook events in a way which is unlikely to |
| 199 | overlap with Git's native hooks (see linkgit:githooks[5]) - a hook event named |
| 200 | `mywrappertool-validate-commit` is much less likely to be added to native Git |
| 201 | than a hook event named `validate-commit`. If Git begins to use a hook event |
| 202 | named the same thing as your wrapper hook, it may invoke your users' hooks in |
| 203 | unintended and unsupported ways. |
| 204 | |
| 205 | CONFIGURATION |
| 206 | ------------- |
| 207 | :git-hook: 1 |
| 208 | include::config/hook.adoc[] |
| 209 | |
| 210 | SEE ALSO |
| 211 | -------- |
| 212 | linkgit:githooks[5] |
| 213 | |
| 214 | GIT |
| 215 | --- |
| 216 | Part of the linkgit:git[1] suite |