]>
Commit | Line | Data |
---|---|---|
72e9340c | 1 | Hooks used by git |
6d35cc76 | 2 | ================= |
6d35cc76 JH |
3 | |
4 | Hooks are little scripts you can place in `$GIT_DIR/hooks` | |
5 | directory to trigger action at certain points. When | |
5c94f87e | 6 | `git-init` is run, a handful example hooks are copied in the |
6d35cc76 | 7 | `hooks` directory of the new repository, but by default they are |
45ad9b50 | 8 | all disabled. To enable a hook, make it executable with `chmod +x`. |
6d35cc76 JH |
9 | |
10 | This document describes the currently defined hooks. | |
11 | ||
12 | applypatch-msg | |
13 | -------------- | |
14 | ||
59c8e2cb | 15 | This hook is invoked by `git-am` script. It takes a single |
6d35cc76 | 16 | parameter, the name of the file that holds the proposed commit |
45ad9b50 | 17 | log message. Exiting with non-zero status causes |
59c8e2cb | 18 | `git-am` to abort before applying the patch. |
6d35cc76 JH |
19 | |
20 | The hook is allowed to edit the message file in place, and can | |
21 | be used to normalize the message into some project standard | |
22 | format (if the project has one). It can also be used to refuse | |
23 | the commit after inspecting the message file. | |
24 | ||
45ad9b50 JF |
25 | The default 'applypatch-msg' hook, when enabled, runs the |
26 | 'commit-msg' hook, if the latter is enabled. | |
6d35cc76 JH |
27 | |
28 | pre-applypatch | |
29 | -------------- | |
30 | ||
59c8e2cb | 31 | This hook is invoked by `git-am`. It takes no parameter, |
6d35cc76 JH |
32 | and is invoked after the patch is applied, but before a commit |
33 | is made. Exiting with non-zero status causes the working tree | |
34 | after application of the patch not committed. | |
35 | ||
36 | It can be used to inspect the current working tree and refuse to | |
37 | make a commit if it does not pass certain test. | |
38 | ||
45ad9b50 JF |
39 | The default 'pre-applypatch' hook, when enabled, runs the |
40 | 'pre-commit' hook, if the latter is enabled. | |
6d35cc76 JH |
41 | |
42 | post-applypatch | |
43 | --------------- | |
44 | ||
59c8e2cb | 45 | This hook is invoked by `git-am`. It takes no parameter, |
6d35cc76 JH |
46 | and is invoked after the patch is applied and a commit is made. |
47 | ||
48 | This hook is meant primarily for notification, and cannot affect | |
59c8e2cb | 49 | the outcome of `git-am`. |
6d35cc76 JH |
50 | |
51 | pre-commit | |
52 | ---------- | |
53 | ||
215a7ad1 | 54 | This hook is invoked by `git-commit`, and can be bypassed |
e1ccf53a | 55 | with `\--no-verify` option. It takes no parameter, and is |
6d35cc76 JH |
56 | invoked before obtaining the proposed commit log message and |
57 | making a commit. Exiting with non-zero status from this script | |
215a7ad1 | 58 | causes the `git-commit` to abort. |
6d35cc76 | 59 | |
45ad9b50 | 60 | The default 'pre-commit' hook, when enabled, catches introduction |
6d35cc76 | 61 | of lines with trailing whitespaces and aborts the commit when |
45ad9b50 | 62 | such a line is found. |
6d35cc76 JH |
63 | |
64 | commit-msg | |
65 | ---------- | |
66 | ||
215a7ad1 | 67 | This hook is invoked by `git-commit`, and can be bypassed |
e1ccf53a | 68 | with `\--no-verify` option. It takes a single parameter, the |
6d35cc76 | 69 | name of the file that holds the proposed commit log message. |
215a7ad1 | 70 | Exiting with non-zero status causes the `git-commit` to |
6d35cc76 JH |
71 | abort. |
72 | ||
73 | The hook is allowed to edit the message file in place, and can | |
74 | be used to normalize the message into some project standard | |
75 | format (if the project has one). It can also be used to refuse | |
76 | the commit after inspecting the message file. | |
77 | ||
45ad9b50 JF |
78 | The default 'commit-msg' hook, when enabled, detects duplicate |
79 | "Signed-off-by" lines, and aborts the commit if one is found. | |
6d35cc76 JH |
80 | |
81 | post-commit | |
82 | ----------- | |
83 | ||
215a7ad1 | 84 | This hook is invoked by `git-commit`. It takes no |
6d35cc76 JH |
85 | parameter, and is invoked after a commit is made. |
86 | ||
87 | This hook is meant primarily for notification, and cannot affect | |
215a7ad1 | 88 | the outcome of `git-commit`. |
6d35cc76 | 89 | |
cbb84e5d JH |
90 | [[pre-receive]] |
91 | pre-receive | |
92 | ----------- | |
93 | ||
94 | This hook is invoked by `git-receive-pack` on the remote repository, | |
95 | which happens when a `git push` is done on a local repository. | |
96 | Just before starting to update refs on the remote repository, the | |
97 | pre-receive hook is invoked. Its exit status determines the success | |
98 | or failure of the update. | |
99 | ||
100 | This hook executes once for the receive operation. It takes no | |
101 | arguments, but for each ref to be updated it receives on standard | |
102 | input a line of the format: | |
103 | ||
104 | <old-value> SP <new-value> SP <ref-name> LF | |
105 | ||
106 | where `<old-value>` is the old object name stored in the ref, | |
107 | `<new-value>` is the new object name to be stored in the ref and | |
108 | `<ref-name>` is the full name of the ref. | |
109 | When creating a new ref, `<old-value>` is 40 `0`. | |
110 | ||
111 | If the hook exits with non-zero status, none of the refs will be | |
112 | updated. If the hook exits with zero, updating of individual refs can | |
113 | still be prevented by the <<update,'update'>> hook. | |
114 | ||
24a0d61e JH |
115 | Both standard output and standard error output are forwarded to |
116 | `git-send-pack` on the other end, so you can simply `echo` messages | |
117 | for the user. | |
cbb84e5d JH |
118 | |
119 | [[update]] | |
6d35cc76 JH |
120 | update |
121 | ------ | |
122 | ||
6250ad1e | 123 | This hook is invoked by `git-receive-pack` on the remote repository, |
45ad9b50 | 124 | which happens when a `git push` is done on a local repository. |
6250ad1e | 125 | Just before updating the ref on the remote repository, the update hook |
37425065 | 126 | is invoked. Its exit status determines the success or failure of |
6250ad1e JL |
127 | the ref update. |
128 | ||
129 | The hook executes once for each ref to be updated, and takes | |
130 | three parameters: | |
45ad9b50 JF |
131 | |
132 | - the name of the ref being updated, | |
133 | - the old object name stored in the ref, | |
134 | - and the new objectname to be stored in the ref. | |
6250ad1e JL |
135 | |
136 | A zero exit from the update hook allows the ref to be updated. | |
137 | Exiting with a non-zero status prevents `git-receive-pack` | |
cbb84e5d | 138 | from updating that ref. |
6250ad1e JL |
139 | |
140 | This hook can be used to prevent 'forced' update on certain refs by | |
6d35cc76 JH |
141 | making sure that the object name is a commit object that is a |
142 | descendant of the commit object named by the old object name. | |
6250ad1e JL |
143 | That is, to enforce a "fast forward only" policy. |
144 | ||
145 | It could also be used to log the old..new status. However, it | |
146 | does not know the entire set of branches, so it would end up | |
cbb84e5d JH |
147 | firing one e-mail per ref when used naively, though. The |
148 | <<post-receive,'post-receive'>> hook is more suited to that. | |
6250ad1e | 149 | |
6d35cc76 JH |
150 | Another use suggested on the mailing list is to use this hook to |
151 | implement access control which is finer grained than the one | |
152 | based on filesystem group. | |
153 | ||
24a0d61e JH |
154 | Both standard output and standard error output are forwarded to |
155 | `git-send-pack` on the other end, so you can simply `echo` messages | |
156 | for the user. | |
3aadad1b | 157 | |
cbb84e5d JH |
158 | The default 'update' hook, when enabled--and with |
159 | `hooks.allowunannotated` config option turned on--prevents | |
160 | unannotated tags to be pushed. | |
161 | ||
162 | [[post-receive]] | |
163 | post-receive | |
164 | ------------ | |
6250ad1e | 165 | |
cbb84e5d JH |
166 | This hook is invoked by `git-receive-pack` on the remote repository, |
167 | which happens when a `git push` is done on a local repository. | |
168 | It executes on the remote repository once after all the refs have | |
169 | been updated. | |
170 | ||
171 | This hook executes once for the receive operation. It takes no | |
24a0d61e JH |
172 | arguments, but gets the same information as the |
173 | <<pre-receive,'pre-receive'>> | |
cbb84e5d JH |
174 | hook does on its standard input. |
175 | ||
176 | This hook does not affect the outcome of `git-receive-pack`, as it | |
177 | is called after the real work is done. | |
178 | ||
24a0d61e JH |
179 | This supersedes the <<post-update,'post-update'>> hook in that it get's |
180 | both old and new values of all the refs in addition to their | |
181 | names. | |
cbb84e5d | 182 | |
24a0d61e JH |
183 | Both standard output and standard error output are forwarded to |
184 | `git-send-pack` on the other end, so you can simply `echo` messages | |
185 | for the user. | |
cbb84e5d JH |
186 | |
187 | The default 'post-receive' hook is empty, but there is | |
188 | a sample script `post-receive-email` provided in the `contrib/hooks` | |
189 | directory in git distribution, which implements sending commit | |
190 | emails. | |
191 | ||
192 | [[post-update]] | |
6d35cc76 JH |
193 | post-update |
194 | ----------- | |
195 | ||
6250ad1e | 196 | This hook is invoked by `git-receive-pack` on the remote repository, |
45ad9b50 | 197 | which happens when a `git push` is done on a local repository. |
6250ad1e JL |
198 | It executes on the remote repository once after all the refs have |
199 | been updated. | |
200 | ||
201 | It takes a variable number of parameters, each of which is the | |
202 | name of ref that was actually updated. | |
6d35cc76 JH |
203 | |
204 | This hook is meant primarily for notification, and cannot affect | |
205 | the outcome of `git-receive-pack`. | |
206 | ||
45ad9b50 | 207 | The 'post-update' hook can tell what are the heads that were pushed, |
6250ad1e | 208 | but it does not know what their original and updated values are, |
24a0d61e JH |
209 | so it is a poor place to do log old..new. The |
210 | <<post-receive,'post-receive'>> hook does get both original and | |
211 | updated values of the refs. You might consider it instead if you need | |
212 | them. | |
cbb84e5d | 213 | |
45ad9b50 | 214 | When enabled, the default 'post-update' hook runs |
6d35cc76 | 215 | `git-update-server-info` to keep the information used by dumb |
45ad9b50 JF |
216 | transports (e.g., HTTP) up-to-date. If you are publishing |
217 | a git repository that is accessible via HTTP, you should | |
6250ad1e | 218 | probably enable this hook. |
3aadad1b | 219 | |
cbb84e5d | 220 | Both standard output and standard error output are forwarded to |
24a0d61e JH |
221 | `git-send-pack` on the other end, so you can simply `echo` messages |
222 | for the user. |