Junio C Hamano | 2fbcd21 | 2008-05-14 22:26:07 | [diff] [blame] | 1 | githooks(5) |
| 2 | =========== |
| 3 | |
| 4 | NAME |
| 5 | ---- |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 6 | githooks - Hooks used by Git |
Junio C Hamano | 2fbcd21 | 2008-05-14 22:26:07 | [diff] [blame] | 7 | |
| 8 | SYNOPSIS |
| 9 | -------- |
Junio C Hamano | 198b1f1 | 2016-05-17 22:27:24 | [diff] [blame] | 10 | $GIT_DIR/hooks/* (or \`git config core.hooksPath`/*) |
Junio C Hamano | 2fbcd21 | 2008-05-14 22:26:07 | [diff] [blame] | 11 | |
| 12 | |
| 13 | DESCRIPTION |
| 14 | ----------- |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 15 | |
Junio C Hamano | 198b1f1 | 2016-05-17 22:27:24 | [diff] [blame] | 16 | Hooks are programs you can place in a hooks directory to trigger |
| 17 | actions at certain points in git's execution. Hooks that don't have |
| 18 | the executable bit set are ignored. |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 19 | |
Junio C Hamano | 198b1f1 | 2016-05-17 22:27:24 | [diff] [blame] | 20 | By default the hooks directory is `$GIT_DIR/hooks`, but that can be |
| 21 | changed via the `core.hooksPath` configuration variable (see |
| 22 | linkgit:git-config[1]). |
Junio C Hamano | 8a48fa2 | 2008-12-18 08:44:30 | [diff] [blame] | 23 | |
Junio C Hamano | 198b1f1 | 2016-05-17 22:27:24 | [diff] [blame] | 24 | Before Git invokes a hook, it changes its working directory to either |
Junio C Hamano | 4c60d9a | 2017-05-04 14:36:22 | [diff] [blame] | 25 | $GIT_DIR in a bare repository or the root of the working tree in a non-bare |
| 26 | repository. An exception are hooks triggered during a push ('pre-receive', |
| 27 | 'update', 'post-receive', 'post-update', 'push-to-checkout') which are always |
| 28 | executed in $GIT_DIR. |
Junio C Hamano | 198b1f1 | 2016-05-17 22:27:24 | [diff] [blame] | 29 | |
Junio C Hamano | a75aada | 2023-01-22 01:54:30 | [diff] [blame] | 30 | Environment variables, such as `GIT_DIR`, `GIT_WORK_TREE`, etc., are exported |
| 31 | so that Git commands run by the hook can correctly locate the repository. If |
| 32 | your hook needs to invoke Git commands in a foreign repository or in a |
| 33 | different working tree of the same repository, then it should clear these |
| 34 | environment variables so they do not interfere with Git operations at the |
| 35 | foreign location. For example: |
| 36 | |
| 37 | ------------ |
| 38 | local_desc=$(git describe) |
| 39 | foreign_desc=$(unset $(git rev-parse --local-env-vars); git -C ../foreign-repo describe) |
| 40 | ------------ |
| 41 | |
Junio C Hamano | 198b1f1 | 2016-05-17 22:27:24 | [diff] [blame] | 42 | Hooks can get their arguments via the environment, command-line |
| 43 | arguments, and stdin. See the documentation for each hook below for |
| 44 | details. |
| 45 | |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 46 | `git init` may copy hooks to the new repository, depending on its |
Junio C Hamano | 198b1f1 | 2016-05-17 22:27:24 | [diff] [blame] | 47 | configuration. See the "TEMPLATE DIRECTORY" section in |
| 48 | linkgit:git-init[1] for details. When the rest of this document refers |
| 49 | to "default hooks" it's talking about the default template shipped |
| 50 | with Git. |
| 51 | |
| 52 | The currently supported hooks are described below. |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 53 | |
Junio C Hamano | c28068f | 2009-09-08 00:55:23 | [diff] [blame] | 54 | HOOKS |
| 55 | ----- |
| 56 | |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 57 | applypatch-msg |
Junio C Hamano | c28068f | 2009-09-08 00:55:23 | [diff] [blame] | 58 | ~~~~~~~~~~~~~~ |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 59 | |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 60 | This hook is invoked by linkgit:git-am[1]. It takes a single |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 61 | parameter, the name of the file that holds the proposed commit |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 62 | log message. Exiting with a non-zero status causes `git am` to abort |
Junio C Hamano | 198b1f1 | 2016-05-17 22:27:24 | [diff] [blame] | 63 | before applying the patch. |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 64 | |
| 65 | The hook is allowed to edit the message file in place, and can |
| 66 | be used to normalize the message into some project standard |
Junio C Hamano | 198b1f1 | 2016-05-17 22:27:24 | [diff] [blame] | 67 | format. It can also be used to refuse the commit after inspecting |
| 68 | the message file. |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 69 | |
Junio C Hamano | d578413 | 2006-09-20 21:29:27 | [diff] [blame] | 70 | The default 'applypatch-msg' hook, when enabled, runs the |
| 71 | 'commit-msg' hook, if the latter is enabled. |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 72 | |
| 73 | pre-applypatch |
Junio C Hamano | c28068f | 2009-09-08 00:55:23 | [diff] [blame] | 74 | ~~~~~~~~~~~~~~ |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 75 | |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 76 | This hook is invoked by linkgit:git-am[1]. It takes no parameter, and is |
Junio C Hamano | a31092a | 2008-05-04 06:41:23 | [diff] [blame] | 77 | invoked after the patch is applied, but before a commit is made. |
| 78 | |
| 79 | If it exits with non-zero status, then the working tree will not be |
| 80 | committed after applying the patch. |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 81 | |
| 82 | It can be used to inspect the current working tree and refuse to |
| 83 | make a commit if it does not pass certain test. |
| 84 | |
Junio C Hamano | d578413 | 2006-09-20 21:29:27 | [diff] [blame] | 85 | The default 'pre-applypatch' hook, when enabled, runs the |
| 86 | 'pre-commit' hook, if the latter is enabled. |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 87 | |
| 88 | post-applypatch |
Junio C Hamano | c28068f | 2009-09-08 00:55:23 | [diff] [blame] | 89 | ~~~~~~~~~~~~~~~ |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 90 | |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 91 | This hook is invoked by linkgit:git-am[1]. It takes no parameter, |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 92 | and is invoked after the patch is applied and a commit is made. |
| 93 | |
| 94 | This hook is meant primarily for notification, and cannot affect |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 95 | the outcome of `git am`. |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 96 | |
| 97 | pre-commit |
Junio C Hamano | c28068f | 2009-09-08 00:55:23 | [diff] [blame] | 98 | ~~~~~~~~~~ |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 99 | |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 100 | This hook is invoked by linkgit:git-commit[1], and can be bypassed |
Junio C Hamano | 198b1f1 | 2016-05-17 22:27:24 | [diff] [blame] | 101 | with the `--no-verify` option. It takes no parameters, and is |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 102 | invoked before obtaining the proposed commit log message and |
Junio C Hamano | 198b1f1 | 2016-05-17 22:27:24 | [diff] [blame] | 103 | making a commit. Exiting with a non-zero status from this script |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 104 | causes the `git commit` command to abort before creating a commit. |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 105 | |
Junio C Hamano | d578413 | 2006-09-20 21:29:27 | [diff] [blame] | 106 | The default 'pre-commit' hook, when enabled, catches introduction |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 107 | of lines with trailing whitespaces and aborts the commit when |
Junio C Hamano | d578413 | 2006-09-20 21:29:27 | [diff] [blame] | 108 | such a line is found. |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 109 | |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 110 | All the `git commit` hooks are invoked with the environment |
Junio C Hamano | 26e590a | 2008-02-17 03:53:51 | [diff] [blame] | 111 | variable `GIT_EDITOR=:` if the command will not bring up an editor |
| 112 | to modify the commit message. |
| 113 | |
Junio C Hamano | 11f1537 | 2019-03-07 03:17:00 | [diff] [blame] | 114 | The default 'pre-commit' hook, when enabled--and with the |
| 115 | `hooks.allownonascii` config option unset or set to false--prevents |
| 116 | the use of non-ASCII filenames. |
| 117 | |
Junio C Hamano | cb70539 | 2019-09-18 19:30:01 | [diff] [blame] | 118 | pre-merge-commit |
| 119 | ~~~~~~~~~~~~~~~~ |
| 120 | |
| 121 | This hook is invoked by linkgit:git-merge[1], and can be bypassed |
| 122 | with the `--no-verify` option. It takes no parameters, and is |
| 123 | invoked after the merge has been carried out successfully and before |
| 124 | obtaining the proposed commit log message to |
| 125 | make a commit. Exiting with a non-zero status from this script |
| 126 | causes the `git merge` command to abort before creating a commit. |
| 127 | |
| 128 | The default 'pre-merge-commit' hook, when enabled, runs the |
| 129 | 'pre-commit' hook, if the latter is enabled. |
| 130 | |
| 131 | This hook is invoked with the environment variable |
| 132 | `GIT_EDITOR=:` if the command will not bring up an editor |
| 133 | to modify the commit message. |
| 134 | |
| 135 | If the merge cannot be carried out automatically, the conflicts |
| 136 | need to be resolved and the result committed separately (see |
| 137 | linkgit:git-merge[1]). At that point, this hook will not be executed, |
| 138 | but the 'pre-commit' hook will, if it is enabled. |
| 139 | |
Junio C Hamano | 26e590a | 2008-02-17 03:53:51 | [diff] [blame] | 140 | prepare-commit-msg |
Junio C Hamano | c28068f | 2009-09-08 00:55:23 | [diff] [blame] | 141 | ~~~~~~~~~~~~~~~~~~ |
Junio C Hamano | 26e590a | 2008-02-17 03:53:51 | [diff] [blame] | 142 | |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 143 | This hook is invoked by linkgit:git-commit[1] right after preparing the |
Junio C Hamano | 26e590a | 2008-02-17 03:53:51 | [diff] [blame] | 144 | default log message, and before the editor is started. |
| 145 | |
| 146 | It takes one to three parameters. The first is the name of the file |
Junio C Hamano | bd53dbf | 2009-01-18 18:26:37 | [diff] [blame] | 147 | that contains the commit log message. The second is the source of the commit |
Junio C Hamano | a476efa | 2008-10-10 15:31:42 | [diff] [blame] | 148 | message, and can be: `message` (if a `-m` or `-F` option was |
| 149 | given); `template` (if a `-t` option was given or the |
Junio C Hamano | 26e590a | 2008-02-17 03:53:51 | [diff] [blame] | 150 | configuration option `commit.template` is set); `merge` (if the |
| 151 | commit is a merge or a `.git/MERGE_MSG` file exists); `squash` |
| 152 | (if a `.git/SQUASH_MSG` file exists); or `commit`, followed by |
Junio C Hamano | 458281a | 2021-03-22 21:20:26 | [diff] [blame] | 153 | a commit object name (if a `-c`, `-C` or `--amend` option was given). |
Junio C Hamano | 26e590a | 2008-02-17 03:53:51 | [diff] [blame] | 154 | |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 155 | If the exit status is non-zero, `git commit` will abort. |
Junio C Hamano | 26e590a | 2008-02-17 03:53:51 | [diff] [blame] | 156 | |
| 157 | The purpose of the hook is to edit the message file in place, and |
Junio C Hamano | b76a686 | 2012-05-02 22:02:46 | [diff] [blame] | 158 | it is not suppressed by the `--no-verify` option. A non-zero exit |
Junio C Hamano | 26e590a | 2008-02-17 03:53:51 | [diff] [blame] | 159 | means a failure of the hook and aborts the commit. It should not |
| 160 | be used as replacement for pre-commit hook. |
| 161 | |
Junio C Hamano | 4b2a6c1 | 2017-08-22 18:32:37 | [diff] [blame] | 162 | The sample `prepare-commit-msg` hook that comes with Git removes the |
| 163 | help message found in the commented portion of the commit template. |
Junio C Hamano | 26e590a | 2008-02-17 03:53:51 | [diff] [blame] | 164 | |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 165 | commit-msg |
Junio C Hamano | c28068f | 2009-09-08 00:55:23 | [diff] [blame] | 166 | ~~~~~~~~~~ |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 167 | |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 168 | This hook is invoked by linkgit:git-commit[1] and linkgit:git-merge[1], and can be |
Junio C Hamano | ef75f37 | 2017-09-29 04:22:33 | [diff] [blame] | 169 | bypassed with the `--no-verify` option. It takes a single parameter, |
| 170 | the name of the file that holds the proposed commit log message. |
| 171 | Exiting with a non-zero status causes the command to abort. |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 172 | |
Junio C Hamano | 198b1f1 | 2016-05-17 22:27:24 | [diff] [blame] | 173 | The hook is allowed to edit the message file in place, and can be used |
| 174 | to normalize the message into some project standard format. It |
| 175 | can also be used to refuse the commit after inspecting the message |
| 176 | file. |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 177 | |
Junio C Hamano | d578413 | 2006-09-20 21:29:27 | [diff] [blame] | 178 | The default 'commit-msg' hook, when enabled, detects duplicate |
Junio C Hamano | df3d3cd | 2020-11-02 22:05:05 | [diff] [blame] | 179 | `Signed-off-by` trailers, and aborts the commit if one is found. |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 180 | |
| 181 | post-commit |
Junio C Hamano | c28068f | 2009-09-08 00:55:23 | [diff] [blame] | 182 | ~~~~~~~~~~~ |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 183 | |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 184 | This hook is invoked by linkgit:git-commit[1]. It takes no parameters, and is |
Junio C Hamano | 198b1f1 | 2016-05-17 22:27:24 | [diff] [blame] | 185 | invoked after a commit is made. |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 186 | |
| 187 | This hook is meant primarily for notification, and cannot affect |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 188 | the outcome of `git commit`. |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 189 | |
Junio C Hamano | a476efa | 2008-10-10 15:31:42 | [diff] [blame] | 190 | pre-rebase |
Junio C Hamano | c28068f | 2009-09-08 00:55:23 | [diff] [blame] | 191 | ~~~~~~~~~~ |
Junio C Hamano | a476efa | 2008-10-10 15:31:42 | [diff] [blame] | 192 | |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 193 | This hook is called by linkgit:git-rebase[1] and can be used to prevent a |
Junio C Hamano | 947ab82 | 2013-03-19 23:07:29 | [diff] [blame] | 194 | branch from getting rebased. The hook may be called with one or |
| 195 | two parameters. The first parameter is the upstream from which |
| 196 | the series was forked. The second parameter is the branch being |
| 197 | rebased, and is not set when rebasing the current branch. |
Junio C Hamano | a476efa | 2008-10-10 15:31:42 | [diff] [blame] | 198 | |
Junio C Hamano | 1b50ce9 | 2007-10-03 12:05:53 | [diff] [blame] | 199 | post-checkout |
Junio C Hamano | c28068f | 2009-09-08 00:55:23 | [diff] [blame] | 200 | ~~~~~~~~~~~~~ |
Junio C Hamano | 1b50ce9 | 2007-10-03 12:05:53 | [diff] [blame] | 201 | |
Junio C Hamano | c9f11c2 | 2019-07-10 02:54:04 | [diff] [blame] | 202 | This hook is invoked when a linkgit:git-checkout[1] or |
| 203 | linkgit:git-switch[1] is run after having updated the |
Junio C Hamano | 1b50ce9 | 2007-10-03 12:05:53 | [diff] [blame] | 204 | worktree. The hook is given three parameters: the ref of the previous HEAD, |
| 205 | the ref of the new HEAD (which may or may not have changed), and a flag |
| 206 | indicating whether the checkout was a branch checkout (changing branches, |
| 207 | flag=1) or a file checkout (retrieving a file from the index, flag=0). |
Junio C Hamano | 558abd2 | 2020-09-03 20:22:34 | [diff] [blame] | 208 | This hook cannot affect the outcome of `git switch` or `git checkout`, |
| 209 | other than that the hook's exit status becomes the exit status of |
| 210 | these two commands. |
Junio C Hamano | 1b50ce9 | 2007-10-03 12:05:53 | [diff] [blame] | 211 | |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 212 | It is also run after linkgit:git-clone[1], unless the `--no-checkout` (`-n`) option is |
Junio C Hamano | 36a5672 | 2009-03-28 08:55:34 | [diff] [blame] | 213 | used. The first parameter given to the hook is the null-ref, the second the |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 214 | ref of the new HEAD and the flag is always 1. Likewise for `git worktree add` |
| 215 | unless `--no-checkout` is used. |
Junio C Hamano | 36a5672 | 2009-03-28 08:55:34 | [diff] [blame] | 216 | |
Junio C Hamano | 1b50ce9 | 2007-10-03 12:05:53 | [diff] [blame] | 217 | This hook can be used to perform repository validity checks, auto-display |
| 218 | differences from the previous HEAD if different, or set working dir metadata |
| 219 | properties. |
| 220 | |
Junio C Hamano | 01d8f83 | 2007-09-24 07:37:30 | [diff] [blame] | 221 | post-merge |
Junio C Hamano | c28068f | 2009-09-08 00:55:23 | [diff] [blame] | 222 | ~~~~~~~~~~ |
Junio C Hamano | 01d8f83 | 2007-09-24 07:37:30 | [diff] [blame] | 223 | |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 224 | This hook is invoked by linkgit:git-merge[1], which happens when a `git pull` |
Junio C Hamano | 01d8f83 | 2007-09-24 07:37:30 | [diff] [blame] | 225 | is done on a local repository. The hook takes a single parameter, a status |
| 226 | flag specifying whether or not the merge being done was a squash merge. |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 227 | This hook cannot affect the outcome of `git merge` and is not executed, |
Junio C Hamano | 47d68a5 | 2008-05-06 06:35:40 | [diff] [blame] | 228 | if the merge failed due to conflicts. |
Junio C Hamano | 01d8f83 | 2007-09-24 07:37:30 | [diff] [blame] | 229 | |
| 230 | This hook can be used in conjunction with a corresponding pre-commit hook to |
| 231 | save and restore any form of metadata associated with the working tree |
Junio C Hamano | fb5ffde | 2014-11-04 22:38:56 | [diff] [blame] | 232 | (e.g.: permissions/ownership, ACLS, etc). See contrib/hooks/setgitperms.perl |
Junio C Hamano | 01d8f83 | 2007-09-24 07:37:30 | [diff] [blame] | 233 | for an example of how to do this. |
| 234 | |
Junio C Hamano | 36d5229 | 2013-01-25 21:32:36 | [diff] [blame] | 235 | pre-push |
| 236 | ~~~~~~~~ |
| 237 | |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 238 | This hook is called by linkgit:git-push[1] and can be used to prevent |
| 239 | a push from taking place. The hook is called with two parameters |
| 240 | which provide the name and location of the destination remote, if a |
| 241 | named remote is not being used both values will be the same. |
Junio C Hamano | 36d5229 | 2013-01-25 21:32:36 | [diff] [blame] | 242 | |
| 243 | Information about what is to be pushed is provided on the hook's standard |
| 244 | input with lines of the form: |
| 245 | |
Junio C Hamano | 458281a | 2021-03-22 21:20:26 | [diff] [blame] | 246 | <local ref> SP <local object name> SP <remote ref> SP <remote object name> LF |
Junio C Hamano | 36d5229 | 2013-01-25 21:32:36 | [diff] [blame] | 247 | |
| 248 | For instance, if the command +git push origin master:foreign+ were run the |
| 249 | hook would receive a line like the following: |
| 250 | |
| 251 | refs/heads/master 67890 refs/heads/foreign 12345 |
| 252 | |
Junio C Hamano | 458281a | 2021-03-22 21:20:26 | [diff] [blame] | 253 | although the full object name would be supplied. If the foreign ref does not |
| 254 | yet exist the `<remote object name>` will be the all-zeroes object name. If a |
| 255 | ref is to be deleted, the `<local ref>` will be supplied as `(delete)` and the |
| 256 | `<local object name>` will be the all-zeroes object name. If the local commit |
| 257 | was specified by something other than a name which could be expanded (such as |
| 258 | `HEAD~`, or an object name) it will be supplied as it was originally given. |
Junio C Hamano | 36d5229 | 2013-01-25 21:32:36 | [diff] [blame] | 259 | |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 260 | If this hook exits with a non-zero status, `git push` will abort without |
Junio C Hamano | 36d5229 | 2013-01-25 21:32:36 | [diff] [blame] | 261 | pushing anything. Information about why the push is rejected may be sent |
| 262 | to the user by writing to standard error. |
| 263 | |
Junio C Hamano | 8638c92 | 2007-05-12 20:50:08 | [diff] [blame] | 264 | [[pre-receive]] |
| 265 | pre-receive |
Junio C Hamano | c28068f | 2009-09-08 00:55:23 | [diff] [blame] | 266 | ~~~~~~~~~~~ |
Junio C Hamano | 8638c92 | 2007-05-12 20:50:08 | [diff] [blame] | 267 | |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 268 | This hook is invoked by linkgit:git-receive-pack[1] when it reacts to |
| 269 | `git push` and updates reference(s) in its repository. |
Junio C Hamano | 8638c92 | 2007-05-12 20:50:08 | [diff] [blame] | 270 | Just before starting to update refs on the remote repository, the |
| 271 | pre-receive hook is invoked. Its exit status determines the success |
| 272 | or failure of the update. |
| 273 | |
| 274 | This hook executes once for the receive operation. It takes no |
| 275 | arguments, but for each ref to be updated it receives on standard |
| 276 | input a line of the format: |
| 277 | |
| 278 | <old-value> SP <new-value> SP <ref-name> LF |
| 279 | |
| 280 | where `<old-value>` is the old object name stored in the ref, |
| 281 | `<new-value>` is the new object name to be stored in the ref and |
| 282 | `<ref-name>` is the full name of the ref. |
Junio C Hamano | 458281a | 2021-03-22 21:20:26 | [diff] [blame] | 283 | When creating a new ref, `<old-value>` is the all-zeroes object name. |
Junio C Hamano | 8638c92 | 2007-05-12 20:50:08 | [diff] [blame] | 284 | |
| 285 | If the hook exits with non-zero status, none of the refs will be |
| 286 | updated. If the hook exits with zero, updating of individual refs can |
| 287 | still be prevented by the <<update,'update'>> hook. |
| 288 | |
Junio C Hamano | 323e52d | 2007-05-13 22:19:53 | [diff] [blame] | 289 | Both standard output and standard error output are forwarded to |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 290 | `git send-pack` on the other end, so you can simply `echo` messages |
Junio C Hamano | 323e52d | 2007-05-13 22:19:53 | [diff] [blame] | 291 | for the user. |
Junio C Hamano | 8638c92 | 2007-05-12 20:50:08 | [diff] [blame] | 292 | |
Junio C Hamano | e48a113 | 2016-08-03 22:40:21 | [diff] [blame] | 293 | The number of push options given on the command line of |
| 294 | `git push --push-option=...` can be read from the environment |
| 295 | variable `GIT_PUSH_OPTION_COUNT`, and the options themselves are |
| 296 | found in `GIT_PUSH_OPTION_0`, `GIT_PUSH_OPTION_1`,... |
| 297 | If it is negotiated to not use the push options phase, the |
| 298 | environment variables will not be set. If the client selects |
| 299 | to use push options, but doesn't transmit any, the count variable |
| 300 | will be set to zero, `GIT_PUSH_OPTION_COUNT=0`. |
| 301 | |
Junio C Hamano | e25cc81 | 2017-04-24 06:17:43 | [diff] [blame] | 302 | See the section on "Quarantine Environment" in |
| 303 | linkgit:git-receive-pack[1] for some caveats. |
| 304 | |
Junio C Hamano | 8638c92 | 2007-05-12 20:50:08 | [diff] [blame] | 305 | [[update]] |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 306 | update |
Junio C Hamano | c28068f | 2009-09-08 00:55:23 | [diff] [blame] | 307 | ~~~~~~ |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 308 | |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 309 | This hook is invoked by linkgit:git-receive-pack[1] when it reacts to |
| 310 | `git push` and updates reference(s) in its repository. |
Junio C Hamano | 818f7d6 | 2006-03-26 01:49:30 | [diff] [blame] | 311 | Just before updating the ref on the remote repository, the update hook |
Junio C Hamano | 33db437 | 2006-06-07 19:51:45 | [diff] [blame] | 312 | is invoked. Its exit status determines the success or failure of |
Junio C Hamano | 818f7d6 | 2006-03-26 01:49:30 | [diff] [blame] | 313 | the ref update. |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 314 | |
Junio C Hamano | 818f7d6 | 2006-03-26 01:49:30 | [diff] [blame] | 315 | The hook executes once for each ref to be updated, and takes |
| 316 | three parameters: |
Junio C Hamano | d578413 | 2006-09-20 21:29:27 | [diff] [blame] | 317 | |
| 318 | - the name of the ref being updated, |
| 319 | - the old object name stored in the ref, |
Junio C Hamano | 826f5c4 | 2014-02-07 20:33:30 | [diff] [blame] | 320 | - and the new object name to be stored in the ref. |
Junio C Hamano | 818f7d6 | 2006-03-26 01:49:30 | [diff] [blame] | 321 | |
| 322 | A zero exit from the update hook allows the ref to be updated. |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 323 | Exiting with a non-zero status prevents `git receive-pack` |
Junio C Hamano | 8638c92 | 2007-05-12 20:50:08 | [diff] [blame] | 324 | from updating that ref. |
Junio C Hamano | 818f7d6 | 2006-03-26 01:49:30 | [diff] [blame] | 325 | |
| 326 | This hook can be used to prevent 'forced' update on certain refs by |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 327 | making sure that the object name is a commit object that is a |
| 328 | descendant of the commit object named by the old object name. |
Junio C Hamano | 3f680f3 | 2009-11-16 02:10:54 | [diff] [blame] | 329 | That is, to enforce a "fast-forward only" policy. |
Junio C Hamano | 818f7d6 | 2006-03-26 01:49:30 | [diff] [blame] | 330 | |
| 331 | It could also be used to log the old..new status. However, it |
| 332 | does not know the entire set of branches, so it would end up |
Junio C Hamano | 8638c92 | 2007-05-12 20:50:08 | [diff] [blame] | 333 | firing one e-mail per ref when used naively, though. The |
| 334 | <<post-receive,'post-receive'>> hook is more suited to that. |
Junio C Hamano | 818f7d6 | 2006-03-26 01:49:30 | [diff] [blame] | 335 | |
Junio C Hamano | 198b1f1 | 2016-05-17 22:27:24 | [diff] [blame] | 336 | In an environment that restricts the users' access only to git |
| 337 | commands over the wire, this hook can be used to implement access |
| 338 | control without relying on filesystem ownership and group |
| 339 | membership. See linkgit:git-shell[1] for how you might use the login |
| 340 | shell to restrict the user's access to only git commands. |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 341 | |
Junio C Hamano | 323e52d | 2007-05-13 22:19:53 | [diff] [blame] | 342 | Both standard output and standard error output are forwarded to |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 343 | `git send-pack` on the other end, so you can simply `echo` messages |
Junio C Hamano | 323e52d | 2007-05-13 22:19:53 | [diff] [blame] | 344 | for the user. |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 345 | |
Junio C Hamano | 8638c92 | 2007-05-12 20:50:08 | [diff] [blame] | 346 | The default 'update' hook, when enabled--and with |
Junio C Hamano | d6fff40 | 2009-09-14 09:40:50 | [diff] [blame] | 347 | `hooks.allowunannotated` config option unset or set to false--prevents |
Junio C Hamano | 8638c92 | 2007-05-12 20:50:08 | [diff] [blame] | 348 | unannotated tags to be pushed. |
Junio C Hamano | 818f7d6 | 2006-03-26 01:49:30 | [diff] [blame] | 349 | |
Junio C Hamano | c562f6d | 2020-09-25 22:50:12 | [diff] [blame] | 350 | [[proc-receive]] |
| 351 | proc-receive |
| 352 | ~~~~~~~~~~~~ |
| 353 | |
| 354 | This hook is invoked by linkgit:git-receive-pack[1]. If the server has |
| 355 | set the multi-valued config variable `receive.procReceiveRefs`, and the |
| 356 | commands sent to 'receive-pack' have matching reference names, these |
| 357 | commands will be executed by this hook, instead of by the internal |
| 358 | `execute_commands()` function. This hook is responsible for updating |
| 359 | the relevant references and reporting the results back to 'receive-pack'. |
| 360 | |
| 361 | This hook executes once for the receive operation. It takes no |
| 362 | arguments, but uses a pkt-line format protocol to communicate with |
| 363 | 'receive-pack' to read commands, push-options and send results. In the |
| 364 | following example for the protocol, the letter 'S' stands for |
| 365 | 'receive-pack' and the letter 'H' stands for this hook. |
| 366 | |
| 367 | # Version and features negotiation. |
| 368 | S: PKT-LINE(version=1\0push-options atomic...) |
| 369 | S: flush-pkt |
| 370 | H: PKT-LINE(version=1\0push-options...) |
| 371 | H: flush-pkt |
| 372 | |
| 373 | # Send commands from server to the hook. |
| 374 | S: PKT-LINE(<old-oid> <new-oid> <ref>) |
| 375 | S: ... ... |
| 376 | S: flush-pkt |
| 377 | # Send push-options only if the 'push-options' feature is enabled. |
| 378 | S: PKT-LINE(push-option) |
| 379 | S: ... ... |
| 380 | S: flush-pkt |
| 381 | |
| 382 | # Receive result from the hook. |
| 383 | # OK, run this command successfully. |
| 384 | H: PKT-LINE(ok <ref>) |
| 385 | # NO, I reject it. |
| 386 | H: PKT-LINE(ng <ref> <reason>) |
| 387 | # Fall through, let 'receive-pack' to execute it. |
| 388 | H: PKT-LINE(ok <ref>) |
| 389 | H: PKT-LINE(option fall-through) |
| 390 | # OK, but has an alternate reference. The alternate reference name |
| 391 | # and other status can be given in option directives. |
| 392 | H: PKT-LINE(ok <ref>) |
| 393 | H: PKT-LINE(option refname <refname>) |
| 394 | H: PKT-LINE(option old-oid <old-oid>) |
| 395 | H: PKT-LINE(option new-oid <new-oid>) |
| 396 | H: PKT-LINE(option forced-update) |
| 397 | H: ... ... |
| 398 | H: flush-pkt |
| 399 | |
| 400 | Each command for the 'proc-receive' hook may point to a pseudo-reference |
| 401 | and always has a zero-old as its old-oid, while the 'proc-receive' hook |
| 402 | may update an alternate reference and the alternate reference may exist |
| 403 | already with a non-zero old-oid. For this case, this hook will use |
| 404 | "option" directives to report extended attributes for the reference given |
| 405 | by the leading "ok" directive. |
| 406 | |
| 407 | The report of the commands of this hook should have the same order as |
| 408 | the input. The exit status of the 'proc-receive' hook only determines |
| 409 | the success or failure of the group of commands sent to it, unless |
| 410 | atomic push is in use. |
| 411 | |
Junio C Hamano | 8638c92 | 2007-05-12 20:50:08 | [diff] [blame] | 412 | [[post-receive]] |
| 413 | post-receive |
Junio C Hamano | c28068f | 2009-09-08 00:55:23 | [diff] [blame] | 414 | ~~~~~~~~~~~~ |
Junio C Hamano | 8638c92 | 2007-05-12 20:50:08 | [diff] [blame] | 415 | |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 416 | This hook is invoked by linkgit:git-receive-pack[1] when it reacts to |
| 417 | `git push` and updates reference(s) in its repository. |
Junio C Hamano | 8638c92 | 2007-05-12 20:50:08 | [diff] [blame] | 418 | It executes on the remote repository once after all the refs have |
| 419 | been updated. |
| 420 | |
| 421 | This hook executes once for the receive operation. It takes no |
Junio C Hamano | 323e52d | 2007-05-13 22:19:53 | [diff] [blame] | 422 | arguments, but gets the same information as the |
| 423 | <<pre-receive,'pre-receive'>> |
Junio C Hamano | 8638c92 | 2007-05-12 20:50:08 | [diff] [blame] | 424 | hook does on its standard input. |
| 425 | |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 426 | This hook does not affect the outcome of `git receive-pack`, as it |
Junio C Hamano | 8638c92 | 2007-05-12 20:50:08 | [diff] [blame] | 427 | is called after the real work is done. |
| 428 | |
Junio C Hamano | a638742 | 2007-08-25 03:54:27 | [diff] [blame] | 429 | This supersedes the <<post-update,'post-update'>> hook in that it gets |
Junio C Hamano | 323e52d | 2007-05-13 22:19:53 | [diff] [blame] | 430 | both old and new values of all the refs in addition to their |
| 431 | names. |
Junio C Hamano | 8638c92 | 2007-05-12 20:50:08 | [diff] [blame] | 432 | |
Junio C Hamano | 323e52d | 2007-05-13 22:19:53 | [diff] [blame] | 433 | Both standard output and standard error output are forwarded to |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 434 | `git send-pack` on the other end, so you can simply `echo` messages |
Junio C Hamano | 323e52d | 2007-05-13 22:19:53 | [diff] [blame] | 435 | for the user. |
Junio C Hamano | 8638c92 | 2007-05-12 20:50:08 | [diff] [blame] | 436 | |
| 437 | The default 'post-receive' hook is empty, but there is |
| 438 | a sample script `post-receive-email` provided in the `contrib/hooks` |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 439 | directory in Git distribution, which implements sending commit |
Junio C Hamano | 8638c92 | 2007-05-12 20:50:08 | [diff] [blame] | 440 | emails. |
| 441 | |
Junio C Hamano | e48a113 | 2016-08-03 22:40:21 | [diff] [blame] | 442 | The number of push options given on the command line of |
| 443 | `git push --push-option=...` can be read from the environment |
| 444 | variable `GIT_PUSH_OPTION_COUNT`, and the options themselves are |
| 445 | found in `GIT_PUSH_OPTION_0`, `GIT_PUSH_OPTION_1`,... |
| 446 | If it is negotiated to not use the push options phase, the |
| 447 | environment variables will not be set. If the client selects |
| 448 | to use push options, but doesn't transmit any, the count variable |
| 449 | will be set to zero, `GIT_PUSH_OPTION_COUNT=0`. |
| 450 | |
Junio C Hamano | 8638c92 | 2007-05-12 20:50:08 | [diff] [blame] | 451 | [[post-update]] |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 452 | post-update |
Junio C Hamano | c28068f | 2009-09-08 00:55:23 | [diff] [blame] | 453 | ~~~~~~~~~~~ |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 454 | |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 455 | This hook is invoked by linkgit:git-receive-pack[1] when it reacts to |
| 456 | `git push` and updates reference(s) in its repository. |
Junio C Hamano | 818f7d6 | 2006-03-26 01:49:30 | [diff] [blame] | 457 | It executes on the remote repository once after all the refs have |
| 458 | been updated. |
| 459 | |
| 460 | It takes a variable number of parameters, each of which is the |
| 461 | name of ref that was actually updated. |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 462 | |
| 463 | This hook is meant primarily for notification, and cannot affect |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 464 | the outcome of `git receive-pack`. |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 465 | |
Junio C Hamano | d578413 | 2006-09-20 21:29:27 | [diff] [blame] | 466 | The 'post-update' hook can tell what are the heads that were pushed, |
Junio C Hamano | 818f7d6 | 2006-03-26 01:49:30 | [diff] [blame] | 467 | but it does not know what their original and updated values are, |
Junio C Hamano | 323e52d | 2007-05-13 22:19:53 | [diff] [blame] | 468 | so it is a poor place to do log old..new. The |
| 469 | <<post-receive,'post-receive'>> hook does get both original and |
| 470 | updated values of the refs. You might consider it instead if you need |
| 471 | them. |
Junio C Hamano | 8638c92 | 2007-05-12 20:50:08 | [diff] [blame] | 472 | |
Junio C Hamano | d578413 | 2006-09-20 21:29:27 | [diff] [blame] | 473 | When enabled, the default 'post-update' hook runs |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 474 | `git update-server-info` to keep the information used by dumb |
Junio C Hamano | 88bf571 | 2017-09-10 08:39:23 | [diff] [blame] | 475 | transports (e.g., HTTP) up to date. If you are publishing |
Junio C Hamano | 076ffcc | 2013-02-06 05:13:21 | [diff] [blame] | 476 | a Git repository that is accessible via HTTP, you should |
Junio C Hamano | 818f7d6 | 2006-03-26 01:49:30 | [diff] [blame] | 477 | probably enable this hook. |
Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 478 | |
Junio C Hamano | 8638c92 | 2007-05-12 20:50:08 | [diff] [blame] | 479 | Both standard output and standard error output are forwarded to |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 480 | `git send-pack` on the other end, so you can simply `echo` messages |
Junio C Hamano | 323e52d | 2007-05-13 22:19:53 | [diff] [blame] | 481 | for the user. |
Junio C Hamano | e3ddb5b | 2008-04-21 00:48:07 | [diff] [blame] | 482 | |
Junio C Hamano | c93f321 | 2020-07-24 23:16:19 | [diff] [blame] | 483 | reference-transaction |
| 484 | ~~~~~~~~~~~~~~~~~~~~~ |
Junio C Hamano | a891178 | 2020-07-07 05:35:57 | [diff] [blame] | 485 | |
| 486 | This hook is invoked by any Git command that performs reference |
| 487 | updates. It executes whenever a reference transaction is prepared, |
Junio C Hamano | 458281a | 2021-03-22 21:20:26 | [diff] [blame] | 488 | committed or aborted and may thus get called multiple times. The hook |
| 489 | does not cover symbolic references (but that may change in the future). |
Junio C Hamano | a891178 | 2020-07-07 05:35:57 | [diff] [blame] | 490 | |
| 491 | The hook takes exactly one argument, which is the current state the |
| 492 | given reference transaction is in: |
| 493 | |
| 494 | - "prepared": All reference updates have been queued to the |
| 495 | transaction and references were locked on disk. |
| 496 | |
| 497 | - "committed": The reference transaction was committed and all |
| 498 | references now have their respective new value. |
| 499 | |
| 500 | - "aborted": The reference transaction was aborted, no changes |
| 501 | were performed and the locks have been released. |
| 502 | |
| 503 | For each reference update that was added to the transaction, the hook |
| 504 | receives on standard input a line of the format: |
| 505 | |
| 506 | <old-value> SP <new-value> SP <ref-name> LF |
| 507 | |
Junio C Hamano | 458281a | 2021-03-22 21:20:26 | [diff] [blame] | 508 | where `<old-value>` is the old object name passed into the reference |
| 509 | transaction, `<new-value>` is the new object name to be stored in the |
| 510 | ref and `<ref-name>` is the full name of the ref. When force updating |
| 511 | the reference regardless of its current value or when the reference is |
| 512 | to be created anew, `<old-value>` is the all-zeroes object name. To |
| 513 | distinguish these cases, you can inspect the current value of |
| 514 | `<ref-name>` via `git rev-parse`. |
| 515 | |
Junio C Hamano | a891178 | 2020-07-07 05:35:57 | [diff] [blame] | 516 | The exit status of the hook is ignored for any state except for the |
| 517 | "prepared" state. In the "prepared" state, a non-zero exit status will |
| 518 | cause the transaction to be aborted. The hook will not be called with |
| 519 | "aborted" state in that case. |
| 520 | |
Junio C Hamano | 6bb32e6 | 2015-02-17 22:11:26 | [diff] [blame] | 521 | push-to-checkout |
| 522 | ~~~~~~~~~~~~~~~~ |
| 523 | |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 524 | This hook is invoked by linkgit:git-receive-pack[1] when it reacts to |
| 525 | `git push` and updates reference(s) in its repository, and when |
Junio C Hamano | 6bb32e6 | 2015-02-17 22:11:26 | [diff] [blame] | 526 | the push tries to update the branch that is currently checked out |
| 527 | and the `receive.denyCurrentBranch` configuration variable is set to |
| 528 | `updateInstead`. Such a push by default is refused if the working |
| 529 | tree and the index of the remote repository has any difference from |
| 530 | the currently checked out commit; when both the working tree and the |
| 531 | index match the current commit, they are updated to match the newly |
| 532 | pushed tip of the branch. This hook is to be used to override the |
| 533 | default behaviour. |
| 534 | |
| 535 | The hook receives the commit with which the tip of the current |
| 536 | branch is going to be updated. It can exit with a non-zero status |
| 537 | to refuse the push (when it does so, it must not modify the index or |
| 538 | the working tree). Or it can make any necessary changes to the |
| 539 | working tree and to the index to bring them to the desired state |
| 540 | when the tip of the current branch is updated to the new commit, and |
| 541 | exit with a zero status. |
| 542 | |
| 543 | For example, the hook can simply run `git read-tree -u -m HEAD "$1"` |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 544 | in order to emulate `git fetch` that is run in the reverse direction |
| 545 | with `git push`, as the two-tree form of `git read-tree -u -m` is |
Junio C Hamano | c9f11c2 | 2019-07-10 02:54:04 | [diff] [blame] | 546 | essentially the same as `git switch` or `git checkout` |
| 547 | that switches branches while |
Junio C Hamano | 6bb32e6 | 2015-02-17 22:11:26 | [diff] [blame] | 548 | keeping the local changes in the working tree that do not interfere |
| 549 | with the difference between the branches. |
| 550 | |
| 551 | |
Junio C Hamano | e3ddb5b | 2008-04-21 00:48:07 | [diff] [blame] | 552 | pre-auto-gc |
Junio C Hamano | c28068f | 2009-09-08 00:55:23 | [diff] [blame] | 553 | ~~~~~~~~~~~ |
Junio C Hamano | e3ddb5b | 2008-04-21 00:48:07 | [diff] [blame] | 554 | |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 555 | This hook is invoked by `git gc --auto` (see linkgit:git-gc[1]). It |
| 556 | takes no parameter, and exiting with non-zero status from this script |
| 557 | causes the `git gc --auto` to abort. |
Junio C Hamano | 2fbcd21 | 2008-05-14 22:26:07 | [diff] [blame] | 558 | |
Junio C Hamano | 3166736 | 2010-03-25 00:38:53 | [diff] [blame] | 559 | post-rewrite |
| 560 | ~~~~~~~~~~~~ |
| 561 | |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 562 | This hook is invoked by commands that rewrite commits |
| 563 | (linkgit:git-commit[1] when called with `--amend` and |
Junio C Hamano | a885831 | 2019-09-30 05:07:45 | [diff] [blame] | 564 | linkgit:git-rebase[1]; however, full-history (re)writing tools like |
| 565 | linkgit:git-fast-import[1] or |
| 566 | https://github.com/newren/git-filter-repo[git-filter-repo] typically |
| 567 | do not call it!). Its first argument denotes the command it was |
| 568 | invoked by: currently one of `amend` or `rebase`. Further |
| 569 | command-dependent arguments may be passed in the future. |
Junio C Hamano | 3166736 | 2010-03-25 00:38:53 | [diff] [blame] | 570 | |
| 571 | The hook receives a list of the rewritten commits on stdin, in the |
| 572 | format |
| 573 | |
Junio C Hamano | 458281a | 2021-03-22 21:20:26 | [diff] [blame] | 574 | <old-object-name> SP <new-object-name> [ SP <extra-info> ] LF |
Junio C Hamano | 3166736 | 2010-03-25 00:38:53 | [diff] [blame] | 575 | |
| 576 | The 'extra-info' is again command-dependent. If it is empty, the |
| 577 | preceding SP is also omitted. Currently, no commands pass any |
| 578 | 'extra-info'. |
| 579 | |
| 580 | The hook always runs after the automatic note copying (see |
Junio C Hamano | 96fdfa1 | 2016-03-21 20:52:39 | [diff] [blame] | 581 | "notes.rewrite.<command>" in linkgit:git-config[1]) has happened, and |
Junio C Hamano | 3166736 | 2010-03-25 00:38:53 | [diff] [blame] | 582 | thus has access to these notes. |
| 583 | |
| 584 | The following command-specific comments apply: |
| 585 | |
| 586 | rebase:: |
| 587 | For the 'squash' and 'fixup' operation, all commits that were |
| 588 | squashed are listed as being rewritten to the squashed commit. |
| 589 | This means that there will be several lines sharing the same |
Junio C Hamano | 458281a | 2021-03-22 21:20:26 | [diff] [blame] | 590 | 'new-object-name'. |
Junio C Hamano | 3166736 | 2010-03-25 00:38:53 | [diff] [blame] | 591 | + |
| 592 | The commits are guaranteed to be listed in the order that they were |
| 593 | processed by rebase. |
| 594 | |
Junio C Hamano | d88ba73 | 2017-05-30 04:14:20 | [diff] [blame] | 595 | sendemail-validate |
| 596 | ~~~~~~~~~~~~~~~~~~ |
| 597 | |
Junio C Hamano | 7ab2d20 | 2023-05-10 18:59:24 | [diff] [blame] | 598 | This hook is invoked by linkgit:git-send-email[1]. |
| 599 | |
| 600 | It takes these command line arguments. They are, |
| 601 | 1. the name of the file which holds the contents of the email to be sent. |
| 602 | 2. The name of the file which holds the SMTP headers of the email. |
| 603 | |
| 604 | The SMTP headers are passed in the exact same way as they are passed to the |
| 605 | user's Mail Transport Agent (MTA). In effect, the email given to the user's |
| 606 | MTA, is the contents of $2 followed by the contents of $1. |
| 607 | |
| 608 | An example of a few common headers is shown below. Take notice of the |
| 609 | capitalization and multi-line tab structure. |
| 610 | |
| 611 | From: Example <from@example.com> |
| 612 | To: to@example.com |
| 613 | Cc: cc@example.com, |
| 614 | A <author@example.com>, |
| 615 | One <one@example.com>, |
| 616 | two@example.com |
| 617 | Subject: PATCH-STRING |
| 618 | |
| 619 | Exiting with a non-zero status causes `git send-email` to abort |
| 620 | before sending any e-mails. |
Junio C Hamano | d88ba73 | 2017-05-30 04:14:20 | [diff] [blame] | 621 | |
Junio C Hamano | 9f24e83 | 2023-04-25 21:41:32 | [diff] [blame] | 622 | The following environment variables are set when executing the hook. |
| 623 | |
| 624 | `GIT_SENDEMAIL_FILE_COUNTER`:: |
| 625 | A 1-based counter incremented by one for every file holding an e-mail |
| 626 | to be sent (excluding any FIFOs). This counter does not follow the |
| 627 | patch series counter scheme. It will always start at 1 and will end at |
| 628 | GIT_SENDEMAIL_FILE_TOTAL. |
| 629 | |
| 630 | `GIT_SENDEMAIL_FILE_TOTAL`:: |
| 631 | The total number of files that will be sent (excluding any FIFOs). This |
| 632 | counter does not follow the patch series counter scheme. It will always |
| 633 | be equal to the number of files being sent, whether there is a cover |
| 634 | letter or not. |
| 635 | |
| 636 | These variables may for instance be used to validate patch series. |
| 637 | |
| 638 | The sample `sendemail-validate` hook that comes with Git checks that all sent |
| 639 | patches (excluding the cover letter) can be applied on top of the upstream |
| 640 | repository default branch without conflicts. Some placeholders are left for |
| 641 | additional validation steps to be performed after all patches of a given series |
| 642 | have been applied. |
| 643 | |
Junio C Hamano | d710560 | 2017-11-21 05:32:50 | [diff] [blame] | 644 | fsmonitor-watchman |
| 645 | ~~~~~~~~~~~~~~~~~~ |
| 646 | |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 647 | This hook is invoked when the configuration option `core.fsmonitor` is |
Junio C Hamano | fc6646b | 2020-02-14 23:35:16 | [diff] [blame] | 648 | set to `.git/hooks/fsmonitor-watchman` or `.git/hooks/fsmonitor-watchmanv2` |
| 649 | depending on the version of the hook to use. |
| 650 | |
| 651 | Version 1 takes two arguments, a version (1) and the time in elapsed |
| 652 | nanoseconds since midnight, January 1, 1970. |
| 653 | |
| 654 | Version 2 takes two arguments, a version (2) and a token that is used |
| 655 | for identifying changes since the token. For watchman this would be |
| 656 | a clock id. This version must output to stdout the new token followed |
| 657 | by a NUL before the list of files. |
Junio C Hamano | d710560 | 2017-11-21 05:32:50 | [diff] [blame] | 658 | |
| 659 | The hook should output to stdout the list of all files in the working |
| 660 | directory that may have changed since the requested time. The logic |
| 661 | should be inclusive so that it does not miss any potential changes. |
| 662 | The paths should be relative to the root of the working directory |
| 663 | and be separated by a single NUL. |
| 664 | |
| 665 | It is OK to include files which have not actually changed. All changes |
| 666 | including newly-created and deleted files should be included. When |
| 667 | files are renamed, both the old and the new name should be included. |
| 668 | |
| 669 | Git will limit what files it checks for changes as well as which |
| 670 | directories are checked for untracked files based on the path names |
| 671 | given. |
| 672 | |
| 673 | An optimized way to tell git "all files have changed" is to return |
Junio C Hamano | b9d9d90 | 2018-05-23 07:07:42 | [diff] [blame] | 674 | the filename `/`. |
Junio C Hamano | d710560 | 2017-11-21 05:32:50 | [diff] [blame] | 675 | |
| 676 | The exit status determines whether git will use the data from the |
| 677 | hook to limit its search. On error, it will fall back to verifying |
| 678 | all files and folders. |
Junio C Hamano | 3166736 | 2010-03-25 00:38:53 | [diff] [blame] | 679 | |
Junio C Hamano | 67bf224 | 2020-04-22 21:41:44 | [diff] [blame] | 680 | p4-changelist |
| 681 | ~~~~~~~~~~~~~ |
| 682 | |
| 683 | This hook is invoked by `git-p4 submit`. |
| 684 | |
| 685 | The `p4-changelist` hook is executed after the changelist |
| 686 | message has been edited by the user. It can be bypassed with the |
| 687 | `--no-verify` option. It takes a single parameter, the name |
| 688 | of the file that holds the proposed changelist text. Exiting |
| 689 | with a non-zero status causes the command to abort. |
| 690 | |
| 691 | The hook is allowed to edit the changelist file and can be used |
| 692 | to normalize the text into some project standard format. It can |
| 693 | also be used to refuse the Submit after inspect the message file. |
| 694 | |
| 695 | Run `git-p4 submit --help` for details. |
| 696 | |
| 697 | p4-prepare-changelist |
| 698 | ~~~~~~~~~~~~~~~~~~~~~ |
| 699 | |
| 700 | This hook is invoked by `git-p4 submit`. |
| 701 | |
| 702 | The `p4-prepare-changelist` hook is executed right after preparing |
| 703 | the default changelist message and before the editor is started. |
| 704 | It takes one parameter, the name of the file that contains the |
| 705 | changelist text. Exiting with a non-zero status from the script |
| 706 | will abort the process. |
| 707 | |
| 708 | The purpose of the hook is to edit the message file in place, |
Junio C Hamano | d5cfc8f | 2021-01-16 00:14:51 | [diff] [blame] | 709 | and it is not suppressed by the `--no-verify` option. This hook |
Junio C Hamano | 67bf224 | 2020-04-22 21:41:44 | [diff] [blame] | 710 | is called even if `--prepare-p4-only` is set. |
| 711 | |
| 712 | Run `git-p4 submit --help` for details. |
| 713 | |
| 714 | p4-post-changelist |
| 715 | ~~~~~~~~~~~~~~~~~~ |
| 716 | |
| 717 | This hook is invoked by `git-p4 submit`. |
| 718 | |
| 719 | The `p4-post-changelist` hook is invoked after the submit has |
Junio C Hamano | ee43d18 | 2020-11-11 22:10:41 | [diff] [blame] | 720 | successfully occurred in P4. It takes no parameters and is meant |
Junio C Hamano | 67bf224 | 2020-04-22 21:41:44 | [diff] [blame] | 721 | primarily for notification and cannot affect the outcome of the |
| 722 | git p4 submit action. |
| 723 | |
| 724 | Run `git-p4 submit --help` for details. |
| 725 | |
Junio C Hamano | bfd91f4 | 2018-08-17 22:21:16 | [diff] [blame] | 726 | p4-pre-submit |
| 727 | ~~~~~~~~~~~~~ |
| 728 | |
| 729 | This hook is invoked by `git-p4 submit`. It takes no parameters and nothing |
| 730 | from standard input. Exiting with non-zero status from this script prevent |
Junio C Hamano | 67bf224 | 2020-04-22 21:41:44 | [diff] [blame] | 731 | `git-p4 submit` from launching. It can be bypassed with the `--no-verify` |
| 732 | command line option. Run `git-p4 submit --help` for details. |
| 733 | |
| 734 | |
Junio C Hamano | bfd91f4 | 2018-08-17 22:21:16 | [diff] [blame] | 735 | |
Junio C Hamano | 2ba1471 | 2019-04-25 10:12:27 | [diff] [blame] | 736 | post-index-change |
| 737 | ~~~~~~~~~~~~~~~~~ |
| 738 | |
| 739 | This hook is invoked when the index is written in read-cache.c |
| 740 | do_write_locked_index. |
| 741 | |
| 742 | The first parameter passed to the hook is the indicator for the |
| 743 | working directory being updated. "1" meaning working directory |
| 744 | was updated or "0" when the working directory was not updated. |
| 745 | |
| 746 | The second parameter passed to the hook is the indicator for whether |
| 747 | or not the index was updated and the skip-worktree bit could have |
| 748 | changed. "1" meaning skip-worktree bits could have been updated |
| 749 | and "0" meaning they were not. |
| 750 | |
| 751 | Only one parameter should be set to "1" when the hook runs. The hook |
| 752 | running passing "1", "1" should not be possible. |
| 753 | |
Junio C Hamano | f1fc6ca | 2022-02-17 01:32:33 | [diff] [blame] | 754 | SEE ALSO |
| 755 | -------- |
| 756 | linkgit:git-hook[1] |
| 757 | |
Junio C Hamano | 2fbcd21 | 2008-05-14 22:26:07 | [diff] [blame] | 758 | GIT |
| 759 | --- |
Junio C Hamano | f7c042d | 2008-06-06 22:50:53 | [diff] [blame] | 760 | Part of the linkgit:git[1] suite |