Mercurial > hgbook
comparison en/ch09-hook.xml @ 753:1c13ed2130a7
Merge with http://hg.serpentine.com/mercurial/book
author | Dongsheng Song <dongsheng.song@gmail.com> |
---|---|
date | Mon, 30 Mar 2009 16:23:33 +0800 |
parents | 7e7c47481e4f 4ce9d0754af3 |
children | b338f5490029 |
comparison
equal
deleted
inserted
replaced
752:6b1577ef5135 | 753:1c13ed2130a7 |
---|---|
1 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> | 1 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> |
2 | 2 |
3 <chapter id="chap.hook"> | 3 <chapter id="chap:hook"> |
4 <?dbhtml filename="handling-repository-events-with-hooks.html"?> | 4 <?dbhtml filename="handling-repository-events-with-hooks.html"?> |
5 <title>Handling repository events with hooks</title> | 5 <title>Handling repository events with hooks</title> |
6 | 6 |
7 <para>Mercurial offers a powerful mechanism to let you perform | 7 <para id="x_1e6">Mercurial offers a powerful mechanism to let you perform |
8 automated actions in response to events that occur in a | 8 automated actions in response to events that occur in a |
9 repository. In some cases, you can even control Mercurial's | 9 repository. In some cases, you can even control Mercurial's |
10 response to those events.</para> | 10 response to those events.</para> |
11 | 11 |
12 <para>The name Mercurial uses for one of these actions is a | 12 <para id="x_1e7">The name Mercurial uses for one of these actions is a |
13 <emphasis>hook</emphasis>. Hooks are called | 13 <emphasis>hook</emphasis>. Hooks are called |
14 <quote>triggers</quote> in some revision control systems, but the | 14 <quote>triggers</quote> in some revision control systems, but the |
15 two names refer to the same idea.</para> | 15 two names refer to the same idea.</para> |
16 | 16 |
17 <sect1> | 17 <sect1> |
18 <title>An overview of hooks in Mercurial</title> | 18 <title>An overview of hooks in Mercurial</title> |
19 | 19 |
20 <para>Here is a brief list of the hooks that Mercurial supports. | 20 <para id="x_1e8">Here is a brief list of the hooks that Mercurial |
21 We will revisit each of these hooks in more detail later, in | 21 supports. We will revisit each of these hooks in more detail |
22 section <xref linkend="sec.hook.ref"/>.</para> | 22 later, in <xref linkend="sec:hook:ref"/>.</para> |
23 | 23 |
24 <itemizedlist> | 24 <itemizedlist> |
25 <listitem><para><literal role="hook">changegroup</literal>: This | 25 <listitem><para id="x_1e9"><literal role="hook">changegroup</literal>: This |
26 is run after a group of changesets has been brought into the | 26 is run after a group of changesets has been brought into the |
27 repository from elsewhere.</para> | 27 repository from elsewhere.</para> |
28 </listitem> | 28 </listitem> |
29 <listitem><para><literal role="hook">commit</literal>: This is | 29 <listitem><para id="x_1ea"><literal role="hook">commit</literal>: This is |
30 run after a new changeset has been created in the local | 30 run after a new changeset has been created in the local |
31 repository.</para> | 31 repository.</para> |
32 </listitem> | 32 </listitem> |
33 <listitem><para><literal role="hook">incoming</literal>: This is | 33 <listitem><para id="x_1eb"><literal role="hook">incoming</literal>: This is |
34 run once for each new changeset that is brought into the | 34 run once for each new changeset that is brought into the |
35 repository from elsewhere. Notice the difference from | 35 repository from elsewhere. Notice the difference from |
36 <literal role="hook">changegroup</literal>, which is run | 36 <literal role="hook">changegroup</literal>, which is run |
37 once per <emphasis>group</emphasis> of changesets brought | 37 once per <emphasis>group</emphasis> of changesets brought |
38 in.</para> | 38 in.</para> |
39 </listitem> | 39 </listitem> |
40 <listitem><para><literal role="hook">outgoing</literal>: This is | 40 <listitem><para id="x_1ec"><literal role="hook">outgoing</literal>: This is |
41 run after a group of changesets has been transmitted from | 41 run after a group of changesets has been transmitted from |
42 this repository.</para> | 42 this repository.</para> |
43 </listitem> | 43 </listitem> |
44 <listitem><para><literal role="hook">prechangegroup</literal>: | 44 <listitem><para id="x_1ed"><literal role="hook">prechangegroup</literal>: |
45 This is run before starting to bring a group of changesets | 45 This is run before starting to bring a group of changesets |
46 into the repository. | 46 into the repository. |
47 </para> | 47 </para> |
48 </listitem> | 48 </listitem> |
49 <listitem><para><literal role="hook">precommit</literal>: | 49 <listitem><para id="x_1ee"><literal role="hook">precommit</literal>: |
50 Controlling. This is run before starting a commit. | 50 Controlling. This is run before starting a commit. |
51 </para> | 51 </para> |
52 </listitem> | 52 </listitem> |
53 <listitem><para><literal role="hook">preoutgoing</literal>: | 53 <listitem><para id="x_1ef"><literal role="hook">preoutgoing</literal>: |
54 Controlling. This is run before starting to transmit a group | 54 Controlling. This is run before starting to transmit a group |
55 of changesets from this repository. | 55 of changesets from this repository. |
56 </para> | 56 </para> |
57 </listitem> | 57 </listitem> |
58 <listitem><para><literal role="hook">pretag</literal>: | 58 <listitem><para id="x_1f0"><literal role="hook">pretag</literal>: |
59 Controlling. This is run before creating a tag. | 59 Controlling. This is run before creating a tag. |
60 </para> | 60 </para> |
61 </listitem> | 61 </listitem> |
62 <listitem><para><literal | 62 <listitem><para id="x_1f1"><literal |
63 role="hook">pretxnchangegroup</literal>: Controlling. This | 63 role="hook">pretxnchangegroup</literal>: Controlling. This |
64 is run after a group of changesets has been brought into the | 64 is run after a group of changesets has been brought into the |
65 local repository from another, but before the transaction | 65 local repository from another, but before the transaction |
66 completes that will make the changes permanent in the | 66 completes that will make the changes permanent in the |
67 repository. | 67 repository. |
68 </para> | 68 </para> |
69 </listitem> | 69 </listitem> |
70 <listitem><para><literal role="hook">pretxncommit</literal>: | 70 <listitem><para id="x_1f2"><literal role="hook">pretxncommit</literal>: |
71 Controlling. This is run after a new changeset has been | 71 Controlling. This is run after a new changeset has been |
72 created in the local repository, but before the transaction | 72 created in the local repository, but before the transaction |
73 completes that will make it permanent. | 73 completes that will make it permanent. |
74 </para> | 74 </para> |
75 </listitem> | 75 </listitem> |
76 <listitem><para><literal role="hook">preupdate</literal>: | 76 <listitem><para id="x_1f3"><literal role="hook">preupdate</literal>: |
77 Controlling. This is run before starting an update or merge | 77 Controlling. This is run before starting an update or merge |
78 of the working directory. | 78 of the working directory. |
79 </para> | 79 </para> |
80 </listitem> | 80 </listitem> |
81 <listitem><para><literal role="hook">tag</literal>: This is run | 81 <listitem><para id="x_1f4"><literal role="hook">tag</literal>: This is run |
82 after a tag is created. | 82 after a tag is created. |
83 </para> | 83 </para> |
84 </listitem> | 84 </listitem> |
85 <listitem><para><literal role="hook">update</literal>: This is | 85 <listitem><para id="x_1f5"><literal role="hook">update</literal>: This is |
86 run after an update or merge of the working directory has | 86 run after an update or merge of the working directory has |
87 finished. | 87 finished. |
88 </para> | 88 </para> |
89 </listitem></itemizedlist> | 89 </listitem></itemizedlist> |
90 <para>Each of the hooks whose description begins with the word | 90 <para id="x_1f6">Each of the hooks whose description begins with the word |
91 <quote>Controlling</quote> has the ability to determine whether | 91 <quote>Controlling</quote> has the ability to determine whether |
92 an activity can proceed. If the hook succeeds, the activity may | 92 an activity can proceed. If the hook succeeds, the activity may |
93 proceed; if it fails, the activity is either not permitted or | 93 proceed; if it fails, the activity is either not permitted or |
94 undone, depending on the hook. | 94 undone, depending on the hook. |
95 </para> | 95 </para> |
99 <title>Hooks and security</title> | 99 <title>Hooks and security</title> |
100 | 100 |
101 <sect2> | 101 <sect2> |
102 <title>Hooks are run with your privileges</title> | 102 <title>Hooks are run with your privileges</title> |
103 | 103 |
104 <para>When you run a Mercurial command in a repository, and the | 104 <para id="x_1f7">When you run a Mercurial command in a repository, and the |
105 command causes a hook to run, that hook runs on | 105 command causes a hook to run, that hook runs on |
106 <emphasis>your</emphasis> system, under | 106 <emphasis>your</emphasis> system, under |
107 <emphasis>your</emphasis> user account, with | 107 <emphasis>your</emphasis> user account, with |
108 <emphasis>your</emphasis> privilege level. Since hooks are | 108 <emphasis>your</emphasis> privilege level. Since hooks are |
109 arbitrary pieces of executable code, you should treat them | 109 arbitrary pieces of executable code, you should treat them |
110 with an appropriate level of suspicion. Do not install a hook | 110 with an appropriate level of suspicion. Do not install a hook |
111 unless you are confident that you know who created it and what | 111 unless you are confident that you know who created it and what |
112 it does. | 112 it does. |
113 </para> | 113 </para> |
114 | 114 |
115 <para>In some cases, you may be exposed to hooks that you did | 115 <para id="x_1f8">In some cases, you may be exposed to hooks that you did |
116 not install yourself. If you work with Mercurial on an | 116 not install yourself. If you work with Mercurial on an |
117 unfamiliar system, Mercurial will run hooks defined in that | 117 unfamiliar system, Mercurial will run hooks defined in that |
118 system's global <filename role="special">~/.hgrc</filename> | 118 system's global <filename role="special">~/.hgrc</filename> |
119 file. | 119 file. |
120 </para> | 120 </para> |
121 | 121 |
122 <para>If you are working with a repository owned by another | 122 <para id="x_1f9">If you are working with a repository owned by another |
123 user, Mercurial can run hooks defined in that user's | 123 user, Mercurial can run hooks defined in that user's |
124 repository, but it will still run them as <quote>you</quote>. | 124 repository, but it will still run them as <quote>you</quote>. |
125 For example, if you <command role="hg-cmd">hg pull</command> | 125 For example, if you <command role="hg-cmd">hg pull</command> |
126 from that repository, and its <filename | 126 from that repository, and its <filename |
127 role="special">.hg/hgrc</filename> defines a local <literal | 127 role="special">.hg/hgrc</filename> defines a local <literal |
129 under your user account, even though you don't own that | 129 under your user account, even though you don't own that |
130 repository. | 130 repository. |
131 </para> | 131 </para> |
132 | 132 |
133 <note> | 133 <note> |
134 <para> This only applies if you are pulling from a repository | 134 <para id="x_1fa"> This only applies if you are pulling from a repository |
135 on a local or network filesystem. If you're pulling over | 135 on a local or network filesystem. If you're pulling over |
136 http or ssh, any <literal role="hook">outgoing</literal> | 136 http or ssh, any <literal role="hook">outgoing</literal> |
137 hook will run under whatever account is executing the server | 137 hook will run under whatever account is executing the server |
138 process, on the server. | 138 process, on the server. |
139 </para> | 139 </para> |
140 </note> | 140 </note> |
141 | 141 |
142 <para>XXX To see what hooks are defined in a repository, use the | 142 <para id="x_1fb">XXX To see what hooks are defined in a repository, use the |
143 <command role="hg-cmd">hg config hooks</command> command. If | 143 <command role="hg-cmd">hg config hooks</command> command. If |
144 you are working in one repository, but talking to another that | 144 you are working in one repository, but talking to another that |
145 you do not own (e.g. using <command role="hg-cmd">hg | 145 you do not own (e.g. using <command role="hg-cmd">hg |
146 pull</command> or <command role="hg-cmd">hg | 146 pull</command> or <command role="hg-cmd">hg |
147 incoming</command>), remember that it is the other | 147 incoming</command>), remember that it is the other |
150 | 150 |
151 </sect2> | 151 </sect2> |
152 <sect2> | 152 <sect2> |
153 <title>Hooks do not propagate</title> | 153 <title>Hooks do not propagate</title> |
154 | 154 |
155 <para>In Mercurial, hooks are not revision controlled, and do | 155 <para id="x_1fc">In Mercurial, hooks are not revision controlled, and do |
156 not propagate when you clone, or pull from, a repository. The | 156 not propagate when you clone, or pull from, a repository. The |
157 reason for this is simple: a hook is a completely arbitrary | 157 reason for this is simple: a hook is a completely arbitrary |
158 piece of executable code. It runs under your user identity, | 158 piece of executable code. It runs under your user identity, |
159 with your privilege level, on your machine. | 159 with your privilege level, on your machine. |
160 </para> | 160 </para> |
161 | 161 |
162 <para>It would be extremely reckless for any distributed | 162 <para id="x_1fd">It would be extremely reckless for any distributed |
163 revision control system to implement revision-controlled | 163 revision control system to implement revision-controlled |
164 hooks, as this would offer an easily exploitable way to | 164 hooks, as this would offer an easily exploitable way to |
165 subvert the accounts of users of the revision control system. | 165 subvert the accounts of users of the revision control system. |
166 </para> | 166 </para> |
167 | 167 |
168 <para>Since Mercurial does not propagate hooks, if you are | 168 <para id="x_1fe">Since Mercurial does not propagate hooks, if you are |
169 collaborating with other people on a common project, you | 169 collaborating with other people on a common project, you |
170 should not assume that they are using the same Mercurial hooks | 170 should not assume that they are using the same Mercurial hooks |
171 as you are, or that theirs are correctly configured. You | 171 as you are, or that theirs are correctly configured. You |
172 should document the hooks you expect people to use. | 172 should document the hooks you expect people to use. |
173 </para> | 173 </para> |
174 | 174 |
175 <para>In a corporate intranet, this is somewhat easier to | 175 <para id="x_1ff">In a corporate intranet, this is somewhat easier to |
176 control, as you can for example provide a | 176 control, as you can for example provide a |
177 <quote>standard</quote> installation of Mercurial on an NFS | 177 <quote>standard</quote> installation of Mercurial on an NFS |
178 filesystem, and use a site-wide <filename role="special">~/.hgrc</filename> file to define hooks that all users will | 178 filesystem, and use a site-wide <filename role="special">~/.hgrc</filename> file to define hooks that all users will |
179 see. However, this too has its limits; see below. | 179 see. However, this too has its limits; see below. |
180 </para> | 180 </para> |
181 | 181 |
182 </sect2> | 182 </sect2> |
183 <sect2> | 183 <sect2> |
184 <title>Hooks can be overridden</title> | 184 <title>Hooks can be overridden</title> |
185 | 185 |
186 <para>Mercurial allows you to override a hook definition by | 186 <para id="x_200">Mercurial allows you to override a hook definition by |
187 redefining the hook. You can disable it by setting its value | 187 redefining the hook. You can disable it by setting its value |
188 to the empty string, or change its behaviour as you wish. | 188 to the empty string, or change its behaviour as you wish. |
189 </para> | 189 </para> |
190 | 190 |
191 <para>If you deploy a system- or site-wide <filename | 191 <para id="x_201">If you deploy a system- or site-wide <filename |
192 role="special">~/.hgrc</filename> file that defines some | 192 role="special">~/.hgrc</filename> file that defines some |
193 hooks, you should thus understand that your users can disable | 193 hooks, you should thus understand that your users can disable |
194 or override those hooks. | 194 or override those hooks. |
195 </para> | 195 </para> |
196 | 196 |
197 </sect2> | 197 </sect2> |
198 <sect2> | 198 <sect2> |
199 <title>Ensuring that critical hooks are run</title> | 199 <title>Ensuring that critical hooks are run</title> |
200 | 200 |
201 <para>Sometimes you may want to enforce a policy that you do not | 201 <para id="x_202">Sometimes you may want to enforce a policy that you do not |
202 want others to be able to work around. For example, you may | 202 want others to be able to work around. For example, you may |
203 have a requirement that every changeset must pass a rigorous | 203 have a requirement that every changeset must pass a rigorous |
204 set of tests. Defining this requirement via a hook in a | 204 set of tests. Defining this requirement via a hook in a |
205 site-wide <filename role="special">~/.hgrc</filename> won't | 205 site-wide <filename role="special">~/.hgrc</filename> won't |
206 work for remote users on laptops, and of course local users | 206 work for remote users on laptops, and of course local users |
207 can subvert it at will by overriding the hook. | 207 can subvert it at will by overriding the hook. |
208 </para> | 208 </para> |
209 | 209 |
210 <para>Instead, you can set up your policies for use of Mercurial | 210 <para id="x_203">Instead, you can set up your policies for use of Mercurial |
211 so that people are expected to propagate changes through a | 211 so that people are expected to propagate changes through a |
212 well-known <quote>canonical</quote> server that you have | 212 well-known <quote>canonical</quote> server that you have |
213 locked down and configured appropriately. | 213 locked down and configured appropriately. |
214 </para> | 214 </para> |
215 | 215 |
216 <para>One way to do this is via a combination of social | 216 <para id="x_204">One way to do this is via a combination of social |
217 engineering and technology. Set up a restricted-access | 217 engineering and technology. Set up a restricted-access |
218 account; users can push changes over the network to | 218 account; users can push changes over the network to |
219 repositories managed by this account, but they cannot log into | 219 repositories managed by this account, but they cannot log into |
220 the account and run normal shell commands. In this scenario, | 220 the account and run normal shell commands. In this scenario, |
221 a user can commit a changeset that contains any old garbage | 221 a user can commit a changeset that contains any old garbage |
222 they want. | 222 they want. |
223 </para> | 223 </para> |
224 | 224 |
225 <para>When someone pushes a changeset to the server that | 225 <para id="x_205">When someone pushes a changeset to the server that |
226 everyone pulls from, the server will test the changeset before | 226 everyone pulls from, the server will test the changeset before |
227 it accepts it as permanent, and reject it if it fails to pass | 227 it accepts it as permanent, and reject it if it fails to pass |
228 the test suite. If people only pull changes from this | 228 the test suite. If people only pull changes from this |
229 filtering server, it will serve to ensure that all changes | 229 filtering server, it will serve to ensure that all changes |
230 that people pull have been automatically vetted. | 230 that people pull have been automatically vetted. |
234 </sect1> | 234 </sect1> |
235 <sect1> | 235 <sect1> |
236 <title>Care with <literal>pretxn</literal> hooks in a | 236 <title>Care with <literal>pretxn</literal> hooks in a |
237 shared-access repository</title> | 237 shared-access repository</title> |
238 | 238 |
239 <para>If you want to use hooks to do some automated work in a | 239 <para id="x_206">If you want to use hooks to do some automated work in a |
240 repository that a number of people have shared access to, you | 240 repository that a number of people have shared access to, you |
241 need to be careful in how you do this. | 241 need to be careful in how you do this. |
242 </para> | 242 </para> |
243 | 243 |
244 <para>Mercurial only locks a repository when it is writing to the | 244 <para id="x_207">Mercurial only locks a repository when it is writing to the |
245 repository, and only the parts of Mercurial that write to the | 245 repository, and only the parts of Mercurial that write to the |
246 repository pay attention to locks. Write locks are necessary to | 246 repository pay attention to locks. Write locks are necessary to |
247 prevent multiple simultaneous writers from scribbling on each | 247 prevent multiple simultaneous writers from scribbling on each |
248 other's work, corrupting the repository. | 248 other's work, corrupting the repository. |
249 </para> | 249 </para> |
250 | 250 |
251 <para>Because Mercurial is careful with the order in which it | 251 <para id="x_208">Because Mercurial is careful with the order in which it |
252 reads and writes data, it does not need to acquire a lock when | 252 reads and writes data, it does not need to acquire a lock when |
253 it wants to read data from the repository. The parts of | 253 it wants to read data from the repository. The parts of |
254 Mercurial that read from the repository never pay attention to | 254 Mercurial that read from the repository never pay attention to |
255 locks. This lockless reading scheme greatly increases | 255 locks. This lockless reading scheme greatly increases |
256 performance and concurrency. | 256 performance and concurrency. |
257 </para> | 257 </para> |
258 | 258 |
259 <para>With great performance comes a trade-off, though, one which | 259 <para id="x_209">With great performance comes a trade-off, though, one which |
260 has the potential to cause you trouble unless you're aware of | 260 has the potential to cause you trouble unless you're aware of |
261 it. To describe this requires a little detail about how | 261 it. To describe this requires a little detail about how |
262 Mercurial adds changesets to a repository and reads those | 262 Mercurial adds changesets to a repository and reads those |
263 changes. | 263 changes. |
264 </para> | 264 </para> |
265 | 265 |
266 <para>When Mercurial <emphasis>writes</emphasis> metadata, it | 266 <para id="x_20a">When Mercurial <emphasis>writes</emphasis> metadata, it |
267 writes it straight into the destination file. It writes file | 267 writes it straight into the destination file. It writes file |
268 data first, then manifest data (which contains pointers to the | 268 data first, then manifest data (which contains pointers to the |
269 new file data), then changelog data (which contains pointers to | 269 new file data), then changelog data (which contains pointers to |
270 the new manifest data). Before the first write to each file, it | 270 the new manifest data). Before the first write to each file, it |
271 stores a record of where the end of the file was in its | 271 stores a record of where the end of the file was in its |
272 transaction log. If the transaction must be rolled back, | 272 transaction log. If the transaction must be rolled back, |
273 Mercurial simply truncates each file back to the size it was | 273 Mercurial simply truncates each file back to the size it was |
274 before the transaction began. | 274 before the transaction began. |
275 </para> | 275 </para> |
276 | 276 |
277 <para>When Mercurial <emphasis>reads</emphasis> metadata, it reads | 277 <para id="x_20b">When Mercurial <emphasis>reads</emphasis> metadata, it reads |
278 the changelog first, then everything else. Since a reader will | 278 the changelog first, then everything else. Since a reader will |
279 only access parts of the manifest or file metadata that it can | 279 only access parts of the manifest or file metadata that it can |
280 see in the changelog, it can never see partially written data. | 280 see in the changelog, it can never see partially written data. |
281 </para> | 281 </para> |
282 | 282 |
283 <para>Some controlling hooks (<literal | 283 <para id="x_20c">Some controlling hooks (<literal |
284 role="hook">pretxncommit</literal> and <literal | 284 role="hook">pretxncommit</literal> and <literal |
285 role="hook">pretxnchangegroup</literal>) run when a | 285 role="hook">pretxnchangegroup</literal>) run when a |
286 transaction is almost complete. All of the metadata has been | 286 transaction is almost complete. All of the metadata has been |
287 written, but Mercurial can still roll the transaction back and | 287 written, but Mercurial can still roll the transaction back and |
288 cause the newly-written data to disappear. | 288 cause the newly-written data to disappear. |
289 </para> | 289 </para> |
290 | 290 |
291 <para>If one of these hooks runs for long, it opens a window of | 291 <para id="x_20d">If one of these hooks runs for long, it opens a window of |
292 time during which a reader can see the metadata for changesets | 292 time during which a reader can see the metadata for changesets |
293 that are not yet permanent, and should not be thought of as | 293 that are not yet permanent, and should not be thought of as |
294 <quote>really there</quote>. The longer the hook runs, the | 294 <quote>really there</quote>. The longer the hook runs, the |
295 longer that window is open. | 295 longer that window is open. |
296 </para> | 296 </para> |
297 | 297 |
298 <sect2> | 298 <sect2> |
299 <title>The problem illustrated</title> | 299 <title>The problem illustrated</title> |
300 | 300 |
301 <para>In principle, a good use for the <literal | 301 <para id="x_20e">In principle, a good use for the <literal |
302 role="hook">pretxnchangegroup</literal> hook would be to | 302 role="hook">pretxnchangegroup</literal> hook would be to |
303 automatically build and test incoming changes before they are | 303 automatically build and test incoming changes before they are |
304 accepted into a central repository. This could let you | 304 accepted into a central repository. This could let you |
305 guarantee that nobody can push changes to this repository that | 305 guarantee that nobody can push changes to this repository that |
306 <quote>break the build</quote>. But if a client can pull | 306 <quote>break the build</quote>. But if a client can pull |
307 changes while they're being tested, the usefulness of the test | 307 changes while they're being tested, the usefulness of the test |
308 is zero; an unsuspecting someone can pull untested changes, | 308 is zero; an unsuspecting someone can pull untested changes, |
309 potentially breaking their build. | 309 potentially breaking their build. |
310 </para> | 310 </para> |
311 | 311 |
312 <para>The safest technological answer to this challenge is to | 312 <para id="x_20f">The safest technological answer to this challenge is to |
313 set up such a <quote>gatekeeper</quote> repository as | 313 set up such a <quote>gatekeeper</quote> repository as |
314 <emphasis>unidirectional</emphasis>. Let it take changes | 314 <emphasis>unidirectional</emphasis>. Let it take changes |
315 pushed in from the outside, but do not allow anyone to pull | 315 pushed in from the outside, but do not allow anyone to pull |
316 changes from it (use the <literal | 316 changes from it (use the <literal |
317 role="hook">preoutgoing</literal> hook to lock it down). | 317 role="hook">preoutgoing</literal> hook to lock it down). |
319 that if a build or test succeeds, the hook will push the new | 319 that if a build or test succeeds, the hook will push the new |
320 changes out to another repository that people | 320 changes out to another repository that people |
321 <emphasis>can</emphasis> pull from. | 321 <emphasis>can</emphasis> pull from. |
322 </para> | 322 </para> |
323 | 323 |
324 <para>In practice, putting a centralised bottleneck like this in | 324 <para id="x_210">In practice, putting a centralised bottleneck like this in |
325 place is not often a good idea, and transaction visibility has | 325 place is not often a good idea, and transaction visibility has |
326 nothing to do with the problem. As the size of a | 326 nothing to do with the problem. As the size of a |
327 project&emdash;and the time it takes to build and | 327 project&emdash;and the time it takes to build and |
328 test&emdash;grows, you rapidly run into a wall with this | 328 test&emdash;grows, you rapidly run into a wall with this |
329 <quote>try before you buy</quote> approach, where you have | 329 <quote>try before you buy</quote> approach, where you have |
330 more changesets to test than time in which to deal with them. | 330 more changesets to test than time in which to deal with them. |
331 The inevitable result is frustration on the part of all | 331 The inevitable result is frustration on the part of all |
332 involved. | 332 involved. |
333 </para> | 333 </para> |
334 | 334 |
335 <para>An approach that scales better is to get people to build | 335 <para id="x_211">An approach that scales better is to get people to build |
336 and test before they push, then run automated builds and tests | 336 and test before they push, then run automated builds and tests |
337 centrally <emphasis>after</emphasis> a push, to be sure all is | 337 centrally <emphasis>after</emphasis> a push, to be sure all is |
338 well. The advantage of this approach is that it does not | 338 well. The advantage of this approach is that it does not |
339 impose a limit on the rate at which the repository can accept | 339 impose a limit on the rate at which the repository can accept |
340 changes. | 340 changes. |
341 </para> | 341 </para> |
342 | 342 |
343 </sect2> | 343 </sect2> |
344 </sect1> | 344 </sect1> |
345 <sect1 id="sec.hook.simple"> | 345 <sect1 id="sec:hook:simple"> |
346 <title>A short tutorial on using hooks</title> | 346 <title>A short tutorial on using hooks</title> |
347 | 347 |
348 <para>It is easy to write a Mercurial hook. Let's start with a | 348 <para id="x_212">It is easy to write a Mercurial hook. Let's start with a |
349 hook that runs when you finish a <command role="hg-cmd">hg | 349 hook that runs when you finish a <command role="hg-cmd">hg |
350 commit</command>, and simply prints the hash of the changeset | 350 commit</command>, and simply prints the hash of the changeset |
351 you just created. The hook is called <literal | 351 you just created. The hook is called <literal |
352 role="hook">commit</literal>. | 352 role="hook">commit</literal>. |
353 </para> | 353 </para> |
354 | 354 |
355 <para>All hooks follow the pattern in this example.</para> | 355 <para id="x_213">All hooks follow the pattern in this example.</para> |
356 | 356 |
357 &interaction.hook.simple.init; | 357 &interaction.hook.simple.init; |
358 | 358 |
359 <para>You add an entry to the <literal | 359 <para id="x_214">You add an entry to the <literal |
360 role="rc-hooks">hooks</literal> section of your <filename | 360 role="rc-hooks">hooks</literal> section of your <filename |
361 role="special">~/.hgrc</filename>. On the left is the name of | 361 role="special">~/.hgrc</filename>. On the left is the name of |
362 the event to trigger on; on the right is the action to take. As | 362 the event to trigger on; on the right is the action to take. As |
363 you can see, you can run an arbitrary shell command in a hook. | 363 you can see, you can run an arbitrary shell command in a hook. |
364 Mercurial passes extra information to the hook using environment | 364 Mercurial passes extra information to the hook using environment |
366 </para> | 366 </para> |
367 | 367 |
368 <sect2> | 368 <sect2> |
369 <title>Performing multiple actions per event</title> | 369 <title>Performing multiple actions per event</title> |
370 | 370 |
371 <para>Quite often, you will want to define more than one hook | 371 <para id="x_215">Quite often, you will want to define more than one hook |
372 for a particular kind of event, as shown below.</para> | 372 for a particular kind of event, as shown below.</para> |
373 | 373 |
374 &interaction.hook.simple.ext; | 374 &interaction.hook.simple.ext; |
375 | 375 |
376 <para>Mercurial lets you do this by adding an | 376 <para id="x_216">Mercurial lets you do this by adding an |
377 <emphasis>extension</emphasis> to the end of a hook's name. | 377 <emphasis>extension</emphasis> to the end of a hook's name. |
378 You extend a hook's name by giving the name of the hook, | 378 You extend a hook's name by giving the name of the hook, |
379 followed by a full stop (the | 379 followed by a full stop (the |
380 <quote><literal>.</literal></quote> character), followed by | 380 <quote><literal>.</literal></quote> character), followed by |
381 some more text of your choosing. For example, Mercurial will | 381 some more text of your choosing. For example, Mercurial will |
382 run both <literal>commit.foo</literal> and | 382 run both <literal>commit.foo</literal> and |
383 <literal>commit.bar</literal> when the | 383 <literal>commit.bar</literal> when the |
384 <literal>commit</literal> event occurs. | 384 <literal>commit</literal> event occurs. |
385 </para> | 385 </para> |
386 | 386 |
387 <para>To give a well-defined order of execution when there are | 387 <para id="x_217">To give a well-defined order of execution when there are |
388 multiple hooks defined for an event, Mercurial sorts hooks by | 388 multiple hooks defined for an event, Mercurial sorts hooks by |
389 extension, and executes the hook commands in this sorted | 389 extension, and executes the hook commands in this sorted |
390 order. In the above example, it will execute | 390 order. In the above example, it will execute |
391 <literal>commit.bar</literal> before | 391 <literal>commit.bar</literal> before |
392 <literal>commit.foo</literal>, and <literal>commit</literal> | 392 <literal>commit.foo</literal>, and <literal>commit</literal> |
393 before both. | 393 before both. |
394 </para> | 394 </para> |
395 | 395 |
396 <para>It is a good idea to use a somewhat descriptive extension | 396 <para id="x_218">It is a good idea to use a somewhat descriptive |
397 when you define a new hook. This will help you to remember | 397 extension when you define a new hook. This will help you to |
398 what the hook was for. If the hook fails, you'll get an error | 398 remember what the hook was for. If the hook fails, you'll get |
399 message that contains the hook name and extension, so using a | 399 an error message that contains the hook name and extension, so |
400 descriptive extension could give you an immediate hint as to | 400 using a descriptive extension could give you an immediate hint |
401 why the hook failed (see section <xref | 401 as to why the hook failed (see <xref |
402 linkend="sec.hook.perm"/> for an example). | 402 linkend="sec:hook:perm"/> for an example). |
403 </para> | 403 </para> |
404 | 404 |
405 </sect2> | 405 </sect2> |
406 <sect2 id="sec.hook.perm"> | 406 <sect2 id="sec:hook:perm"> |
407 <title>Controlling whether an activity can proceed</title> | 407 <title>Controlling whether an activity can proceed</title> |
408 | 408 |
409 <para>In our earlier examples, we used the <literal | 409 <para id="x_219">In our earlier examples, we used the <literal |
410 role="hook">commit</literal> hook, which is run after a | 410 role="hook">commit</literal> hook, which is run after a |
411 commit has completed. This is one of several Mercurial hooks | 411 commit has completed. This is one of several Mercurial hooks |
412 that run after an activity finishes. Such hooks have no way | 412 that run after an activity finishes. Such hooks have no way |
413 of influencing the activity itself. | 413 of influencing the activity itself. |
414 </para> | 414 </para> |
415 | 415 |
416 <para>Mercurial defines a number of events that occur before an | 416 <para id="x_21a">Mercurial defines a number of events that occur before an |
417 activity starts; or after it starts, but before it finishes. | 417 activity starts; or after it starts, but before it finishes. |
418 Hooks that trigger on these events have the added ability to | 418 Hooks that trigger on these events have the added ability to |
419 choose whether the activity can continue, or will abort. | 419 choose whether the activity can continue, or will abort. |
420 </para> | 420 </para> |
421 | 421 |
422 <para>The <literal role="hook">pretxncommit</literal> hook runs | 422 <para id="x_21b">The <literal role="hook">pretxncommit</literal> hook runs |
423 after a commit has all but completed. In other words, the | 423 after a commit has all but completed. In other words, the |
424 metadata representing the changeset has been written out to | 424 metadata representing the changeset has been written out to |
425 disk, but the transaction has not yet been allowed to | 425 disk, but the transaction has not yet been allowed to |
426 complete. The <literal role="hook">pretxncommit</literal> | 426 complete. The <literal role="hook">pretxncommit</literal> |
427 hook has the ability to decide whether the transaction can | 427 hook has the ability to decide whether the transaction can |
428 complete, or must be rolled back. | 428 complete, or must be rolled back. |
429 </para> | 429 </para> |
430 | 430 |
431 <para>If the <literal role="hook">pretxncommit</literal> hook | 431 <para id="x_21c">If the <literal role="hook">pretxncommit</literal> hook |
432 exits with a status code of zero, the transaction is allowed | 432 exits with a status code of zero, the transaction is allowed |
433 to complete; the commit finishes; and the <literal | 433 to complete; the commit finishes; and the <literal |
434 role="hook">commit</literal> hook is run. If the <literal | 434 role="hook">commit</literal> hook is run. If the <literal |
435 role="hook">pretxncommit</literal> hook exits with a | 435 role="hook">pretxncommit</literal> hook exits with a |
436 non-zero status code, the transaction is rolled back; the | 436 non-zero status code, the transaction is rolled back; the |
438 <literal role="hook">commit</literal> hook is not run. | 438 <literal role="hook">commit</literal> hook is not run. |
439 </para> | 439 </para> |
440 | 440 |
441 &interaction.hook.simple.pretxncommit; | 441 &interaction.hook.simple.pretxncommit; |
442 | 442 |
443 <para>The hook in the example above checks that a commit comment | 443 <para id="x_21d">The hook in the example above checks that a commit comment |
444 contains a bug ID. If it does, the commit can complete. If | 444 contains a bug ID. If it does, the commit can complete. If |
445 not, the commit is rolled back. | 445 not, the commit is rolled back. |
446 </para> | 446 </para> |
447 | 447 |
448 </sect2> | 448 </sect2> |
449 </sect1> | 449 </sect1> |
450 <sect1> | 450 <sect1> |
451 <title>Writing your own hooks</title> | 451 <title>Writing your own hooks</title> |
452 | 452 |
453 <para>When you are writing a hook, you might find it useful to run | 453 <para id="x_21e">When you are writing a hook, you might find it useful to run |
454 Mercurial either with the <option | 454 Mercurial either with the <option |
455 role="hg-opt-global">-v</option> option, or the <envar | 455 role="hg-opt-global">-v</option> option, or the <envar |
456 role="rc-item-ui">verbose</envar> config item set to | 456 role="rc-item-ui">verbose</envar> config item set to |
457 <quote>true</quote>. When you do so, Mercurial will print a | 457 <quote>true</quote>. When you do so, Mercurial will print a |
458 message before it calls each hook. | 458 message before it calls each hook. |
459 </para> | 459 </para> |
460 | 460 |
461 <sect2 id="sec.hook.lang"> | 461 <sect2 id="sec:hook:lang"> |
462 <title>Choosing how your hook should run</title> | 462 <title>Choosing how your hook should run</title> |
463 | 463 |
464 <para>You can write a hook either as a normal | 464 <para id="x_21f">You can write a hook either as a normal |
465 program&emdash;typically a shell script&emdash;or as a Python | 465 program&emdash;typically a shell script&emdash;or as a Python |
466 function that is executed within the Mercurial process. | 466 function that is executed within the Mercurial process. |
467 </para> | 467 </para> |
468 | 468 |
469 <para>Writing a hook as an external program has the advantage | 469 <para id="x_220">Writing a hook as an external program has the advantage |
470 that it requires no knowledge of Mercurial's internals. You | 470 that it requires no knowledge of Mercurial's internals. You |
471 can call normal Mercurial commands to get any added | 471 can call normal Mercurial commands to get any added |
472 information you need. The trade-off is that external hooks | 472 information you need. The trade-off is that external hooks |
473 are slower than in-process hooks. | 473 are slower than in-process hooks. |
474 </para> | 474 </para> |
475 | 475 |
476 <para>An in-process Python hook has complete access to the | 476 <para id="x_221">An in-process Python hook has complete access to the |
477 Mercurial API, and does not <quote>shell out</quote> to | 477 Mercurial API, and does not <quote>shell out</quote> to |
478 another process, so it is inherently faster than an external | 478 another process, so it is inherently faster than an external |
479 hook. It is also easier to obtain much of the information | 479 hook. It is also easier to obtain much of the information |
480 that a hook requires by using the Mercurial API than by | 480 that a hook requires by using the Mercurial API than by |
481 running Mercurial commands. | 481 running Mercurial commands. |
482 </para> | 482 </para> |
483 | 483 |
484 <para>If you are comfortable with Python, or require high | 484 <para id="x_222">If you are comfortable with Python, or require high |
485 performance, writing your hooks in Python may be a good | 485 performance, writing your hooks in Python may be a good |
486 choice. However, when you have a straightforward hook to | 486 choice. However, when you have a straightforward hook to |
487 write and you don't need to care about performance (probably | 487 write and you don't need to care about performance (probably |
488 the majority of hooks), a shell script is perfectly fine. | 488 the majority of hooks), a shell script is perfectly fine. |
489 </para> | 489 </para> |
490 | 490 |
491 </sect2> | 491 </sect2> |
492 <sect2 id="sec.hook.param"> | 492 <sect2 id="sec:hook:param"> |
493 <title>Hook parameters</title> | 493 <title>Hook parameters</title> |
494 | 494 |
495 <para>Mercurial calls each hook with a set of well-defined | 495 <para id="x_223">Mercurial calls each hook with a set of well-defined |
496 parameters. In Python, a parameter is passed as a keyword | 496 parameters. In Python, a parameter is passed as a keyword |
497 argument to your hook function. For an external program, a | 497 argument to your hook function. For an external program, a |
498 parameter is passed as an environment variable. | 498 parameter is passed as an environment variable. |
499 </para> | 499 </para> |
500 | 500 |
501 <para>Whether your hook is written in Python or as a shell | 501 <para id="x_224">Whether your hook is written in Python or as a shell |
502 script, the hook-specific parameter names and values will be | 502 script, the hook-specific parameter names and values will be |
503 the same. A boolean parameter will be represented as a | 503 the same. A boolean parameter will be represented as a |
504 boolean value in Python, but as the number 1 (for | 504 boolean value in Python, but as the number 1 (for |
505 <quote>true</quote>) or 0 (for <quote>false</quote>) as an | 505 <quote>true</quote>) or 0 (for <quote>false</quote>) as an |
506 environment variable for an external hook. If a hook | 506 environment variable for an external hook. If a hook |
512 | 512 |
513 </sect2> | 513 </sect2> |
514 <sect2> | 514 <sect2> |
515 <title>Hook return values and activity control</title> | 515 <title>Hook return values and activity control</title> |
516 | 516 |
517 <para>A hook that executes successfully must exit with a status | 517 <para id="x_225">A hook that executes successfully must exit with a status |
518 of zero if external, or return boolean <quote>false</quote> if | 518 of zero if external, or return boolean <quote>false</quote> if |
519 in-process. Failure is indicated with a non-zero exit status | 519 in-process. Failure is indicated with a non-zero exit status |
520 from an external hook, or an in-process hook returning boolean | 520 from an external hook, or an in-process hook returning boolean |
521 <quote>true</quote>. If an in-process hook raises an | 521 <quote>true</quote>. If an in-process hook raises an |
522 exception, the hook is considered to have failed. | 522 exception, the hook is considered to have failed. |
523 </para> | 523 </para> |
524 | 524 |
525 <para>For a hook that controls whether an activity can proceed, | 525 <para id="x_226">For a hook that controls whether an activity can proceed, |
526 zero/false means <quote>allow</quote>, while | 526 zero/false means <quote>allow</quote>, while |
527 non-zero/true/exception means <quote>deny</quote>. | 527 non-zero/true/exception means <quote>deny</quote>. |
528 </para> | 528 </para> |
529 | 529 |
530 </sect2> | 530 </sect2> |
531 <sect2> | 531 <sect2> |
532 <title>Writing an external hook</title> | 532 <title>Writing an external hook</title> |
533 | 533 |
534 <para>When you define an external hook in your <filename | 534 <para id="x_227">When you define an external hook in your <filename |
535 role="special">~/.hgrc</filename> and the hook is run, its | 535 role="special">~/.hgrc</filename> and the hook is run, its |
536 value is passed to your shell, which interprets it. This | 536 value is passed to your shell, which interprets it. This |
537 means that you can use normal shell constructs in the body of | 537 means that you can use normal shell constructs in the body of |
538 the hook. | 538 the hook. |
539 </para> | 539 </para> |
540 | 540 |
541 <para>An executable hook is always run with its current | 541 <para id="x_228">An executable hook is always run with its current |
542 directory set to a repository's root directory. | 542 directory set to a repository's root directory. |
543 </para> | 543 </para> |
544 | 544 |
545 <para>Each hook parameter is passed in as an environment | 545 <para id="x_229">Each hook parameter is passed in as an environment |
546 variable; the name is upper-cased, and prefixed with the | 546 variable; the name is upper-cased, and prefixed with the |
547 string <quote><literal>HG_</literal></quote>. | 547 string <quote><literal>HG_</literal></quote>. |
548 </para> | 548 </para> |
549 | 549 |
550 <para>With the exception of hook parameters, Mercurial does not | 550 <para id="x_22a">With the exception of hook parameters, Mercurial does not |
551 set or modify any environment variables when running a hook. | 551 set or modify any environment variables when running a hook. |
552 This is useful to remember if you are writing a site-wide hook | 552 This is useful to remember if you are writing a site-wide hook |
553 that may be run by a number of different users with differing | 553 that may be run by a number of different users with differing |
554 environment variables set. In multi-user situations, you | 554 environment variables set. In multi-user situations, you |
555 should not rely on environment variables being set to the | 555 should not rely on environment variables being set to the |
558 | 558 |
559 </sect2> | 559 </sect2> |
560 <sect2> | 560 <sect2> |
561 <title>Telling Mercurial to use an in-process hook</title> | 561 <title>Telling Mercurial to use an in-process hook</title> |
562 | 562 |
563 <para>The <filename role="special">~/.hgrc</filename> syntax | 563 <para id="x_22b">The <filename role="special">~/.hgrc</filename> syntax |
564 for defining an in-process hook is slightly different than for | 564 for defining an in-process hook is slightly different than for |
565 an executable hook. The value of the hook must start with the | 565 an executable hook. The value of the hook must start with the |
566 text <quote><literal>python:</literal></quote>, and continue | 566 text <quote><literal>python:</literal></quote>, and continue |
567 with the fully-qualified name of a callable object to use as | 567 with the fully-qualified name of a callable object to use as |
568 the hook's value. | 568 the hook's value. |
569 </para> | 569 </para> |
570 | 570 |
571 <para>The module in which a hook lives is automatically imported | 571 <para id="x_22c">The module in which a hook lives is automatically imported |
572 when a hook is run. So long as you have the module name and | 572 when a hook is run. So long as you have the module name and |
573 <envar>PYTHONPATH</envar> right, it should <quote>just | 573 <envar>PYTHONPATH</envar> right, it should <quote>just |
574 work</quote>. | 574 work</quote>. |
575 </para> | 575 </para> |
576 | 576 |
577 <para>The following <filename role="special">~/.hgrc</filename> | 577 <para id="x_22d">The following <filename role="special">~/.hgrc</filename> |
578 example snippet illustrates the syntax and meaning of the | 578 example snippet illustrates the syntax and meaning of the |
579 notions we just described. | 579 notions we just described. |
580 </para> | 580 </para> |
581 <programlisting>[hooks] | 581 <programlisting>[hooks] |
582 commit.example = python:mymodule.submodule.myhook</programlisting> | 582 commit.example = python:mymodule.submodule.myhook</programlisting> |
583 <para>When Mercurial runs the <literal>commit.example</literal> | 583 <para id="x_22e">When Mercurial runs the <literal>commit.example</literal> |
584 hook, it imports <literal>mymodule.submodule</literal>, looks | 584 hook, it imports <literal>mymodule.submodule</literal>, looks |
585 for the callable object named <literal>myhook</literal>, and | 585 for the callable object named <literal>myhook</literal>, and |
586 calls it. | 586 calls it. |
587 </para> | 587 </para> |
588 | 588 |
589 </sect2> | 589 </sect2> |
590 <sect2> | 590 <sect2> |
591 <title>Writing an in-process hook</title> | 591 <title>Writing an in-process hook</title> |
592 | 592 |
593 <para>The simplest in-process hook does nothing, but illustrates | 593 <para id="x_22f">The simplest in-process hook does nothing, but illustrates |
594 the basic shape of the hook API: | 594 the basic shape of the hook API: |
595 </para> | 595 </para> |
596 <programlisting>def myhook(ui, repo, **kwargs): | 596 <programlisting>def myhook(ui, repo, **kwargs): |
597 pass</programlisting> | 597 pass</programlisting> |
598 <para>The first argument to a Python hook is always a <literal | 598 <para id="x_230">The first argument to a Python hook is always a <literal |
599 role="py-mod-mercurial.ui">ui</literal> object. The second | 599 role="py-mod-mercurial.ui">ui</literal> object. The second |
600 is a repository object; at the moment, it is always an | 600 is a repository object; at the moment, it is always an |
601 instance of <literal | 601 instance of <literal |
602 role="py-mod-mercurial.localrepo">localrepository</literal>. | 602 role="py-mod-mercurial.localrepo">localrepository</literal>. |
603 Following these two arguments are other keyword arguments. | 603 Following these two arguments are other keyword arguments. |
613 <title>Some hook examples</title> | 613 <title>Some hook examples</title> |
614 | 614 |
615 <sect2> | 615 <sect2> |
616 <title>Writing meaningful commit messages</title> | 616 <title>Writing meaningful commit messages</title> |
617 | 617 |
618 <para>It's hard to imagine a useful commit message being very | 618 <para id="x_231">It's hard to imagine a useful commit message being very |
619 short. The simple <literal role="hook">pretxncommit</literal> | 619 short. The simple <literal role="hook">pretxncommit</literal> |
620 hook of the example below will prevent you from committing a | 620 hook of the example below will prevent you from committing a |
621 changeset with a message that is less than ten bytes long. | 621 changeset with a message that is less than ten bytes long. |
622 </para> | 622 </para> |
623 | 623 |
625 | 625 |
626 </sect2> | 626 </sect2> |
627 <sect2> | 627 <sect2> |
628 <title>Checking for trailing whitespace</title> | 628 <title>Checking for trailing whitespace</title> |
629 | 629 |
630 <para>An interesting use of a commit-related hook is to help you | 630 <para id="x_232">An interesting use of a commit-related hook is to help you |
631 to write cleaner code. A simple example of <quote>cleaner | 631 to write cleaner code. A simple example of <quote>cleaner |
632 code</quote> is the dictum that a change should not add any | 632 code</quote> is the dictum that a change should not add any |
633 new lines of text that contain <quote>trailing | 633 new lines of text that contain <quote>trailing |
634 whitespace</quote>. Trailing whitespace is a series of | 634 whitespace</quote>. Trailing whitespace is a series of |
635 space and tab characters at the end of a line of text. In | 635 space and tab characters at the end of a line of text. In |
636 most cases, trailing whitespace is unnecessary, invisible | 636 most cases, trailing whitespace is unnecessary, invisible |
637 noise, but it is occasionally problematic, and people often | 637 noise, but it is occasionally problematic, and people often |
638 prefer to get rid of it. | 638 prefer to get rid of it. |
639 </para> | 639 </para> |
640 | 640 |
641 <para>You can use either the <literal | 641 <para id="x_233">You can use either the <literal |
642 role="hook">precommit</literal> or <literal | 642 role="hook">precommit</literal> or <literal |
643 role="hook">pretxncommit</literal> hook to tell whether you | 643 role="hook">pretxncommit</literal> hook to tell whether you |
644 have a trailing whitespace problem. If you use the <literal | 644 have a trailing whitespace problem. If you use the <literal |
645 role="hook">precommit</literal> hook, the hook will not know | 645 role="hook">precommit</literal> hook, the hook will not know |
646 which files you are committing, so it will have to check every | 646 which files you are committing, so it will have to check every |
652 will prevent you from committing <filename>foo</filename> due | 652 will prevent you from committing <filename>foo</filename> due |
653 to the problem with <filename>bar</filename>. This doesn't | 653 to the problem with <filename>bar</filename>. This doesn't |
654 seem right. | 654 seem right. |
655 </para> | 655 </para> |
656 | 656 |
657 <para>Should you choose the <literal | 657 <para id="x_234">Should you choose the <literal |
658 role="hook">pretxncommit</literal> hook, the check won't | 658 role="hook">pretxncommit</literal> hook, the check won't |
659 occur until just before the transaction for the commit | 659 occur until just before the transaction for the commit |
660 completes. This will allow you to check for problems only the | 660 completes. This will allow you to check for problems only the |
661 exact files that are being committed. However, if you entered | 661 exact files that are being committed. However, if you entered |
662 the commit message interactively and the hook fails, the | 662 the commit message interactively and the hook fails, the |
665 role="hg-cmd">hg commit</command> again. | 665 role="hg-cmd">hg commit</command> again. |
666 </para> | 666 </para> |
667 | 667 |
668 &interaction.hook.ws.simple; | 668 &interaction.hook.ws.simple; |
669 | 669 |
670 <para>In this example, we introduce a simple <literal | 670 <para id="x_235">In this example, we introduce a simple <literal |
671 role="hook">pretxncommit</literal> hook that checks for | 671 role="hook">pretxncommit</literal> hook that checks for |
672 trailing whitespace. This hook is short, but not very | 672 trailing whitespace. This hook is short, but not very |
673 helpful. It exits with an error status if a change adds a | 673 helpful. It exits with an error status if a change adds a |
674 line with trailing whitespace to any file, but does not print | 674 line with trailing whitespace to any file, but does not print |
675 any information that might help us to identify the offending | 675 any information that might help us to identify the offending |
676 file or line. It also has the nice property of not paying | 676 file or line. It also has the nice property of not paying |
677 attention to unmodified lines; only lines that introduce new | 677 attention to unmodified lines; only lines that introduce new |
678 trailing whitespace cause problems. | 678 trailing whitespace cause problems. |
679 </para> | 679 </para> |
680 | 680 |
681 <para>The above version is much more complex, but also more | 681 <para id="x_236">The above version is much more complex, but also more |
682 useful. It parses a unified diff to see if any lines add | 682 useful. It parses a unified diff to see if any lines add |
683 trailing whitespace, and prints the name of the file and the | 683 trailing whitespace, and prints the name of the file and the |
684 line number of each such occurrence. Even better, if the | 684 line number of each such occurrence. Even better, if the |
685 change adds trailing whitespace, this hook saves the commit | 685 change adds trailing whitespace, this hook saves the commit |
686 comment and prints the name of the save file before exiting | 686 comment and prints the name of the save file before exiting |
690 the saved commit message once you've corrected the problem. | 690 the saved commit message once you've corrected the problem. |
691 </para> | 691 </para> |
692 | 692 |
693 &interaction.hook.ws.better; | 693 &interaction.hook.ws.better; |
694 | 694 |
695 <para>As a final aside, note in the example above the use of | 695 <para id="x_237">As a final aside, note in the example above the use of |
696 <command>perl</command>'s in-place editing feature to get rid | 696 <command>perl</command>'s in-place editing feature to get rid |
697 of trailing whitespace from a file. This is concise and | 697 of trailing whitespace from a file. This is concise and |
698 useful enough that I will reproduce it here. | 698 useful enough that I will reproduce it here. |
699 </para> | 699 </para> |
700 <programlisting>perl -pi -e 's,\s+$,,' filename</programlisting> | 700 <programlisting>perl -pi -e 's,\s+$,,' filename</programlisting> |
702 </sect2> | 702 </sect2> |
703 </sect1> | 703 </sect1> |
704 <sect1> | 704 <sect1> |
705 <title>Bundled hooks</title> | 705 <title>Bundled hooks</title> |
706 | 706 |
707 <para>Mercurial ships with several bundled hooks. You can find | 707 <para id="x_238">Mercurial ships with several bundled hooks. You can find |
708 them in the <filename class="directory">hgext</filename> | 708 them in the <filename class="directory">hgext</filename> |
709 directory of a Mercurial source tree. If you are using a | 709 directory of a Mercurial source tree. If you are using a |
710 Mercurial binary package, the hooks will be located in the | 710 Mercurial binary package, the hooks will be located in the |
711 <filename class="directory">hgext</filename> directory of | 711 <filename class="directory">hgext</filename> directory of |
712 wherever your package installer put Mercurial. | 712 wherever your package installer put Mercurial. |
714 | 714 |
715 <sect2> | 715 <sect2> |
716 <title><literal role="hg-ext">acl</literal>&emdash;access | 716 <title><literal role="hg-ext">acl</literal>&emdash;access |
717 control for parts of a repository</title> | 717 control for parts of a repository</title> |
718 | 718 |
719 <para>The <literal role="hg-ext">acl</literal> extension lets | 719 <para id="x_239">The <literal role="hg-ext">acl</literal> extension lets |
720 you control which remote users are allowed to push changesets | 720 you control which remote users are allowed to push changesets |
721 to a networked server. You can protect any portion of a | 721 to a networked server. You can protect any portion of a |
722 repository (including the entire repo), so that a specific | 722 repository (including the entire repo), so that a specific |
723 remote user can push changes that do not affect the protected | 723 remote user can push changes that do not affect the protected |
724 portion. | 724 portion. |
725 </para> | 725 </para> |
726 | 726 |
727 <para>This extension implements access control based on the | 727 <para id="x_23a">This extension implements access control based on the |
728 identity of the user performing a push, | 728 identity of the user performing a push, |
729 <emphasis>not</emphasis> on who committed the changesets | 729 <emphasis>not</emphasis> on who committed the changesets |
730 they're pushing. It makes sense to use this hook only if you | 730 they're pushing. It makes sense to use this hook only if you |
731 have a locked-down server environment that authenticates | 731 have a locked-down server environment that authenticates |
732 remote users, and you want to be sure that only specific users | 732 remote users, and you want to be sure that only specific users |
735 | 735 |
736 <sect3> | 736 <sect3> |
737 <title>Configuring the <literal role="hook">acl</literal> | 737 <title>Configuring the <literal role="hook">acl</literal> |
738 hook</title> | 738 hook</title> |
739 | 739 |
740 <para>In order to manage incoming changesets, the <literal | 740 <para id="x_23b">In order to manage incoming changesets, the <literal |
741 role="hg-ext">acl</literal> hook must be used as a | 741 role="hg-ext">acl</literal> hook must be used as a |
742 <literal role="hook">pretxnchangegroup</literal> hook. This | 742 <literal role="hook">pretxnchangegroup</literal> hook. This |
743 lets it see which files are modified by each incoming | 743 lets it see which files are modified by each incoming |
744 changeset, and roll back a group of changesets if they | 744 changeset, and roll back a group of changesets if they |
745 modify <quote>forbidden</quote> files. Example: | 745 modify <quote>forbidden</quote> files. Example: |
746 </para> | 746 </para> |
747 <programlisting>[hooks] | 747 <programlisting>[hooks] |
748 pretxnchangegroup.acl = python:hgext.acl.hook</programlisting> | 748 pretxnchangegroup.acl = python:hgext.acl.hook</programlisting> |
749 | 749 |
750 <para>The <literal role="hg-ext">acl</literal> extension is | 750 <para id="x_23c">The <literal role="hg-ext">acl</literal> extension is |
751 configured using three sections. | 751 configured using three sections. |
752 </para> | 752 </para> |
753 | 753 |
754 <para>The <literal role="rc-acl">acl</literal> section has | 754 <para id="x_23d">The <literal role="rc-acl">acl</literal> section has |
755 only one entry, <envar role="rc-item-acl">sources</envar>, | 755 only one entry, <envar role="rc-item-acl">sources</envar>, |
756 which lists the sources of incoming changesets that the hook | 756 which lists the sources of incoming changesets that the hook |
757 should pay attention to. You don't normally need to | 757 should pay attention to. You don't normally need to |
758 configure this section. | 758 configure this section. |
759 </para> | 759 </para> |
760 <itemizedlist> | 760 <itemizedlist> |
761 <listitem><para><envar role="rc-item-acl">serve</envar>: | 761 <listitem><para id="x_23e"><envar role="rc-item-acl">serve</envar>: |
762 Control incoming changesets that are arriving from a | 762 Control incoming changesets that are arriving from a |
763 remote repository over http or ssh. This is the default | 763 remote repository over http or ssh. This is the default |
764 value of <envar role="rc-item-acl">sources</envar>, and | 764 value of <envar role="rc-item-acl">sources</envar>, and |
765 usually the only setting you'll need for this | 765 usually the only setting you'll need for this |
766 configuration item. | 766 configuration item. |
767 </para> | 767 </para> |
768 </listitem> | 768 </listitem> |
769 <listitem><para><envar role="rc-item-acl">pull</envar>: | 769 <listitem><para id="x_23f"><envar role="rc-item-acl">pull</envar>: |
770 Control incoming changesets that are arriving via a pull | 770 Control incoming changesets that are arriving via a pull |
771 from a local repository. | 771 from a local repository. |
772 </para> | 772 </para> |
773 </listitem> | 773 </listitem> |
774 <listitem><para><envar role="rc-item-acl">push</envar>: | 774 <listitem><para id="x_240"><envar role="rc-item-acl">push</envar>: |
775 Control incoming changesets that are arriving via a push | 775 Control incoming changesets that are arriving via a push |
776 from a local repository. | 776 from a local repository. |
777 </para> | 777 </para> |
778 </listitem> | 778 </listitem> |
779 <listitem><para><envar role="rc-item-acl">bundle</envar>: | 779 <listitem><para id="x_241"><envar role="rc-item-acl">bundle</envar>: |
780 Control incoming changesets that are arriving from | 780 Control incoming changesets that are arriving from |
781 another repository via a bundle. | 781 another repository via a bundle. |
782 </para> | 782 </para> |
783 </listitem></itemizedlist> | 783 </listitem></itemizedlist> |
784 | 784 |
785 <para>The <literal role="rc-acl.allow">acl.allow</literal> | 785 <para id="x_242">The <literal role="rc-acl.allow">acl.allow</literal> |
786 section controls the users that are allowed to add | 786 section controls the users that are allowed to add |
787 changesets to the repository. If this section is not | 787 changesets to the repository. If this section is not |
788 present, all users that are not explicitly denied are | 788 present, all users that are not explicitly denied are |
789 allowed. If this section is present, all users that are not | 789 allowed. If this section is present, all users that are not |
790 explicitly allowed are denied (so an empty section means | 790 explicitly allowed are denied (so an empty section means |
791 that all users are denied). | 791 that all users are denied). |
792 </para> | 792 </para> |
793 | 793 |
794 <para>The <literal role="rc-acl.deny">acl.deny</literal> | 794 <para id="x_243">The <literal role="rc-acl.deny">acl.deny</literal> |
795 section determines which users are denied from adding | 795 section determines which users are denied from adding |
796 changesets to the repository. If this section is not | 796 changesets to the repository. If this section is not |
797 present or is empty, no users are denied. | 797 present or is empty, no users are denied. |
798 </para> | 798 </para> |
799 | 799 |
800 <para>The syntaxes for the <literal | 800 <para id="x_244">The syntaxes for the <literal |
801 role="rc-acl.allow">acl.allow</literal> and <literal | 801 role="rc-acl.allow">acl.allow</literal> and <literal |
802 role="rc-acl.deny">acl.deny</literal> sections are | 802 role="rc-acl.deny">acl.deny</literal> sections are |
803 identical. On the left of each entry is a glob pattern that | 803 identical. On the left of each entry is a glob pattern that |
804 matches files or directories, relative to the root of the | 804 matches files or directories, relative to the root of the |
805 repository; on the right, a user name. | 805 repository; on the right, a user name. |
806 </para> | 806 </para> |
807 | 807 |
808 <para>In the following example, the user | 808 <para id="x_245">In the following example, the user |
809 <literal>docwriter</literal> can only push changes to the | 809 <literal>docwriter</literal> can only push changes to the |
810 <filename class="directory">docs</filename> subtree of the | 810 <filename class="directory">docs</filename> subtree of the |
811 repository, while <literal>intern</literal> can push changes | 811 repository, while <literal>intern</literal> can push changes |
812 to any file or directory except <filename | 812 to any file or directory except <filename |
813 class="directory">source/sensitive</filename>. | 813 class="directory">source/sensitive</filename>. |
819 | 819 |
820 </sect3> | 820 </sect3> |
821 <sect3> | 821 <sect3> |
822 <title>Testing and troubleshooting</title> | 822 <title>Testing and troubleshooting</title> |
823 | 823 |
824 <para>If you want to test the <literal | 824 <para id="x_246">If you want to test the <literal |
825 role="hg-ext">acl</literal> hook, run it with Mercurial's | 825 role="hg-ext">acl</literal> hook, run it with Mercurial's |
826 debugging output enabled. Since you'll probably be running | 826 debugging output enabled. Since you'll probably be running |
827 it on a server where it's not convenient (or sometimes | 827 it on a server where it's not convenient (or sometimes |
828 possible) to pass in the <option | 828 possible) to pass in the <option |
829 role="hg-opt-global">--debug</option> option, don't forget | 829 role="hg-opt-global">--debug</option> option, don't forget |
830 that you can enable debugging output in your <filename | 830 that you can enable debugging output in your <filename |
831 role="special">~/.hgrc</filename>: | 831 role="special">~/.hgrc</filename>: |
832 </para> | 832 </para> |
833 <programlisting>[ui] | 833 <programlisting>[ui] |
834 debug = true</programlisting> | 834 debug = true</programlisting> |
835 <para>With this enabled, the <literal | 835 <para id="x_247">With this enabled, the <literal |
836 role="hg-ext">acl</literal> hook will print enough | 836 role="hg-ext">acl</literal> hook will print enough |
837 information to let you figure out why it is allowing or | 837 information to let you figure out why it is allowing or |
838 forbidding pushes from specific users. | 838 forbidding pushes from specific users. |
839 </para> | 839 </para> |
840 | 840 |
843 <sect2> | 843 <sect2> |
844 <title><literal | 844 <title><literal |
845 role="hg-ext">bugzilla</literal>&emdash;integration with | 845 role="hg-ext">bugzilla</literal>&emdash;integration with |
846 Bugzilla</title> | 846 Bugzilla</title> |
847 | 847 |
848 <para>The <literal role="hg-ext">bugzilla</literal> extension | 848 <para id="x_248">The <literal role="hg-ext">bugzilla</literal> extension |
849 adds a comment to a Bugzilla bug whenever it finds a reference | 849 adds a comment to a Bugzilla bug whenever it finds a reference |
850 to that bug ID in a commit comment. You can install this hook | 850 to that bug ID in a commit comment. You can install this hook |
851 on a shared server, so that any time a remote user pushes | 851 on a shared server, so that any time a remote user pushes |
852 changes to this server, the hook gets run. | 852 changes to this server, the hook gets run. |
853 </para> | 853 </para> |
854 | 854 |
855 <para>It adds a comment to the bug that looks like this (you can | 855 <para id="x_249">It adds a comment to the bug that looks like this (you can |
856 configure the contents of the comment&emdash;see below): | 856 configure the contents of the comment&emdash;see below): |
857 </para> | 857 </para> |
858 <programlisting>Changeset aad8b264143a, made by Joe User | 858 <programlisting>Changeset aad8b264143a, made by Joe User |
859 <joe.user@domain.com> in the frobnitz repository, refers | 859 <joe.user@domain.com> in the frobnitz repository, refers |
860 to this bug. For complete details, see | 860 to this bug. For complete details, see |
861 http://hg.domain.com/frobnitz?cmd=changeset;node=aad8b264143a | 861 http://hg.domain.com/frobnitz?cmd=changeset;node=aad8b264143a |
862 Changeset description: Fix bug 10483 by guarding against some | 862 Changeset description: Fix bug 10483 by guarding against some |
863 NULL pointers</programlisting> | 863 NULL pointers</programlisting> |
864 <para>The value of this hook is that it automates the process of | 864 <para id="x_24a">The value of this hook is that it automates the process of |
865 updating a bug any time a changeset refers to it. If you | 865 updating a bug any time a changeset refers to it. If you |
866 configure the hook properly, it makes it easy for people to | 866 configure the hook properly, it makes it easy for people to |
867 browse straight from a Bugzilla bug to a changeset that refers | 867 browse straight from a Bugzilla bug to a changeset that refers |
868 to that bug. | 868 to that bug. |
869 </para> | 869 </para> |
870 | 870 |
871 <para>You can use the code in this hook as a starting point for | 871 <para id="x_24b">You can use the code in this hook as a starting point for |
872 some more exotic Bugzilla integration recipes. Here are a few | 872 some more exotic Bugzilla integration recipes. Here are a few |
873 possibilities: | 873 possibilities: |
874 </para> | 874 </para> |
875 <itemizedlist> | 875 <itemizedlist> |
876 <listitem><para>Require that every changeset pushed to the | 876 <listitem><para id="x_24c">Require that every changeset pushed to the |
877 server have a valid bug ID in its commit comment. In this | 877 server have a valid bug ID in its commit comment. In this |
878 case, you'd want to configure the hook as a <literal | 878 case, you'd want to configure the hook as a <literal |
879 role="hook">pretxncommit</literal> hook. This would | 879 role="hook">pretxncommit</literal> hook. This would |
880 allow the hook to reject changes that didn't contain bug | 880 allow the hook to reject changes that didn't contain bug |
881 IDs. | 881 IDs. |
882 </para> | 882 </para> |
883 </listitem> | 883 </listitem> |
884 <listitem><para>Allow incoming changesets to automatically | 884 <listitem><para id="x_24d">Allow incoming changesets to automatically |
885 modify the <emphasis>state</emphasis> of a bug, as well as | 885 modify the <emphasis>state</emphasis> of a bug, as well as |
886 simply adding a comment. For example, the hook could | 886 simply adding a comment. For example, the hook could |
887 recognise the string <quote>fixed bug 31337</quote> as | 887 recognise the string <quote>fixed bug 31337</quote> as |
888 indicating that it should update the state of bug 31337 to | 888 indicating that it should update the state of bug 31337 to |
889 <quote>requires testing</quote>. | 889 <quote>requires testing</quote>. |
890 </para> | 890 </para> |
891 </listitem></itemizedlist> | 891 </listitem></itemizedlist> |
892 | 892 |
893 <sect3 id="sec.hook.bugzilla.config"> | 893 <sect3 id="sec:hook:bugzilla:config"> |
894 <title>Configuring the <literal role="hook">bugzilla</literal> | 894 <title>Configuring the <literal role="hook">bugzilla</literal> |
895 hook</title> | 895 hook</title> |
896 | 896 |
897 <para>You should configure this hook in your server's | 897 <para id="x_24e">You should configure this hook in your server's |
898 <filename role="special">~/.hgrc</filename> as an <literal | 898 <filename role="special">~/.hgrc</filename> as an <literal |
899 role="hook">incoming</literal> hook, for example as | 899 role="hook">incoming</literal> hook, for example as |
900 follows: | 900 follows: |
901 </para> | 901 </para> |
902 <programlisting>[hooks] | 902 <programlisting>[hooks] |
903 incoming.bugzilla = python:hgext.bugzilla.hook</programlisting> | 903 incoming.bugzilla = python:hgext.bugzilla.hook</programlisting> |
904 | 904 |
905 <para>Because of the specialised nature of this hook, and | 905 <para id="x_24f">Because of the specialised nature of this hook, and |
906 because Bugzilla was not written with this kind of | 906 because Bugzilla was not written with this kind of |
907 integration in mind, configuring this hook is a somewhat | 907 integration in mind, configuring this hook is a somewhat |
908 involved process. | 908 involved process. |
909 </para> | 909 </para> |
910 | 910 |
911 <para>Before you begin, you must install the MySQL bindings | 911 <para id="x_250">Before you begin, you must install the MySQL bindings |
912 for Python on the host(s) where you'll be running the hook. | 912 for Python on the host(s) where you'll be running the hook. |
913 If this is not available as a binary package for your | 913 If this is not available as a binary package for your |
914 system, you can download it from | 914 system, you can download it from |
915 <citation>web:mysql-python</citation>. | 915 <citation>web:mysql-python</citation>. |
916 </para> | 916 </para> |
917 | 917 |
918 <para>Configuration information for this hook lives in the | 918 <para id="x_251">Configuration information for this hook lives in the |
919 <literal role="rc-bugzilla">bugzilla</literal> section of | 919 <literal role="rc-bugzilla">bugzilla</literal> section of |
920 your <filename role="special">~/.hgrc</filename>. | 920 your <filename role="special">~/.hgrc</filename>. |
921 </para> | 921 </para> |
922 <itemizedlist> | 922 <itemizedlist> |
923 <listitem><para><envar | 923 <listitem><para id="x_252"><envar |
924 role="rc-item-bugzilla">version</envar>: The version | 924 role="rc-item-bugzilla">version</envar>: The version |
925 of Bugzilla installed on the server. The database | 925 of Bugzilla installed on the server. The database |
926 schema that Bugzilla uses changes occasionally, so this | 926 schema that Bugzilla uses changes occasionally, so this |
927 hook has to know exactly which schema to use. At the | 927 hook has to know exactly which schema to use. At the |
928 moment, the only version supported is | 928 moment, the only version supported is |
929 <literal>2.16</literal>. | 929 <literal>2.16</literal>. |
930 </para> | 930 </para> |
931 </listitem> | 931 </listitem> |
932 <listitem><para><envar role="rc-item-bugzilla">host</envar>: | 932 <listitem><para id="x_253"><envar role="rc-item-bugzilla">host</envar>: |
933 The hostname of the MySQL server that stores your | 933 The hostname of the MySQL server that stores your |
934 Bugzilla data. The database must be configured to allow | 934 Bugzilla data. The database must be configured to allow |
935 connections from whatever host you are running the | 935 connections from whatever host you are running the |
936 <literal role="hook">bugzilla</literal> hook on. | 936 <literal role="hook">bugzilla</literal> hook on. |
937 </para> | 937 </para> |
938 </listitem> | 938 </listitem> |
939 <listitem><para><envar role="rc-item-bugzilla">user</envar>: | 939 <listitem><para id="x_254"><envar role="rc-item-bugzilla">user</envar>: |
940 The username with which to connect to the MySQL server. | 940 The username with which to connect to the MySQL server. |
941 The database must be configured to allow this user to | 941 The database must be configured to allow this user to |
942 connect from whatever host you are running the <literal | 942 connect from whatever host you are running the <literal |
943 role="hook">bugzilla</literal> hook on. This user | 943 role="hook">bugzilla</literal> hook on. This user |
944 must be able to access and modify Bugzilla tables. The | 944 must be able to access and modify Bugzilla tables. The |
945 default value of this item is <literal>bugs</literal>, | 945 default value of this item is <literal>bugs</literal>, |
946 which is the standard name of the Bugzilla user in a | 946 which is the standard name of the Bugzilla user in a |
947 MySQL database. | 947 MySQL database. |
948 </para> | 948 </para> |
949 </listitem> | 949 </listitem> |
950 <listitem><para><envar | 950 <listitem><para id="x_255"><envar |
951 role="rc-item-bugzilla">password</envar>: The MySQL | 951 role="rc-item-bugzilla">password</envar>: The MySQL |
952 password for the user you configured above. This is | 952 password for the user you configured above. This is |
953 stored as plain text, so you should make sure that | 953 stored as plain text, so you should make sure that |
954 unauthorised users cannot read the <filename | 954 unauthorised users cannot read the <filename |
955 role="special">~/.hgrc</filename> file where you | 955 role="special">~/.hgrc</filename> file where you |
956 store this information. | 956 store this information. |
957 </para> | 957 </para> |
958 </listitem> | 958 </listitem> |
959 <listitem><para><envar role="rc-item-bugzilla">db</envar>: | 959 <listitem><para id="x_256"><envar role="rc-item-bugzilla">db</envar>: |
960 The name of the Bugzilla database on the MySQL server. | 960 The name of the Bugzilla database on the MySQL server. |
961 The default value of this item is | 961 The default value of this item is |
962 <literal>bugs</literal>, which is the standard name of | 962 <literal>bugs</literal>, which is the standard name of |
963 the MySQL database where Bugzilla stores its data. | 963 the MySQL database where Bugzilla stores its data. |
964 </para> | 964 </para> |
965 </listitem> | 965 </listitem> |
966 <listitem><para><envar | 966 <listitem><para id="x_257"><envar |
967 role="rc-item-bugzilla">notify</envar>: If you want | 967 role="rc-item-bugzilla">notify</envar>: If you want |
968 Bugzilla to send out a notification email to subscribers | 968 Bugzilla to send out a notification email to subscribers |
969 after this hook has added a comment to a bug, you will | 969 after this hook has added a comment to a bug, you will |
970 need this hook to run a command whenever it updates the | 970 need this hook to run a command whenever it updates the |
971 database. The command to run depends on where you have | 971 database. The command to run depends on where you have |
974 class="directory">/var/www/html/bugzilla</filename>: | 974 class="directory">/var/www/html/bugzilla</filename>: |
975 </para> | 975 </para> |
976 <programlisting>cd /var/www/html/bugzilla && | 976 <programlisting>cd /var/www/html/bugzilla && |
977 ./processmail %s nobody@nowhere.com</programlisting> | 977 ./processmail %s nobody@nowhere.com</programlisting> |
978 </listitem> | 978 </listitem> |
979 <listitem><para> The Bugzilla | 979 <listitem><para id="x_258"> The Bugzilla |
980 <literal>processmail</literal> program expects to be | 980 <literal>processmail</literal> program expects to be |
981 given a bug ID (the hook replaces | 981 given a bug ID (the hook replaces |
982 <quote><literal>%s</literal></quote> with the bug ID) | 982 <quote><literal>%s</literal></quote> with the bug ID) |
983 and an email address. It also expects to be able to | 983 and an email address. It also expects to be able to |
984 write to some files in the directory that it runs in. | 984 write to some files in the directory that it runs in. |
991 | 991 |
992 </sect3> | 992 </sect3> |
993 <sect3> | 993 <sect3> |
994 <title>Mapping committer names to Bugzilla user names</title> | 994 <title>Mapping committer names to Bugzilla user names</title> |
995 | 995 |
996 <para>By default, the <literal | 996 <para id="x_259">By default, the <literal |
997 role="hg-ext">bugzilla</literal> hook tries to use the | 997 role="hg-ext">bugzilla</literal> hook tries to use the |
998 email address of a changeset's committer as the Bugzilla | 998 email address of a changeset's committer as the Bugzilla |
999 user name with which to update a bug. If this does not suit | 999 user name with which to update a bug. If this does not suit |
1000 your needs, you can map committer email addresses to | 1000 your needs, you can map committer email addresses to |
1001 Bugzilla user names using a <literal | 1001 Bugzilla user names using a <literal |
1002 role="rc-usermap">usermap</literal> section. | 1002 role="rc-usermap">usermap</literal> section. |
1003 </para> | 1003 </para> |
1004 | 1004 |
1005 <para>Each item in the <literal | 1005 <para id="x_25a">Each item in the <literal |
1006 role="rc-usermap">usermap</literal> section contains an | 1006 role="rc-usermap">usermap</literal> section contains an |
1007 email address on the left, and a Bugzilla user name on the | 1007 email address on the left, and a Bugzilla user name on the |
1008 right. | 1008 right. |
1009 </para> | 1009 </para> |
1010 <programlisting>[usermap] | 1010 <programlisting>[usermap] |
1011 jane.user@example.com = jane</programlisting> | 1011 jane.user@example.com = jane</programlisting> |
1012 <para>You can either keep the <literal | 1012 <para id="x_25b">You can either keep the <literal |
1013 role="rc-usermap">usermap</literal> data in a normal | 1013 role="rc-usermap">usermap</literal> data in a normal |
1014 <filename role="special">~/.hgrc</filename>, or tell the | 1014 <filename role="special">~/.hgrc</filename>, or tell the |
1015 <literal role="hg-ext">bugzilla</literal> hook to read the | 1015 <literal role="hg-ext">bugzilla</literal> hook to read the |
1016 information from an external <filename>usermap</filename> | 1016 information from an external <filename>usermap</filename> |
1017 file. In the latter case, you can store | 1017 file. In the latter case, you can store |
1023 like this: | 1023 like this: |
1024 </para> | 1024 </para> |
1025 <programlisting># regular hgrc file refers to external usermap file | 1025 <programlisting># regular hgrc file refers to external usermap file |
1026 [bugzilla] | 1026 [bugzilla] |
1027 usermap = /home/hg/repos/userdata/bugzilla-usermap.conf</programlisting> | 1027 usermap = /home/hg/repos/userdata/bugzilla-usermap.conf</programlisting> |
1028 <para>While the <filename>usermap</filename> file that it | 1028 <para id="x_25c">While the <filename>usermap</filename> file that it |
1029 refers to might look like this: | 1029 refers to might look like this: |
1030 </para> | 1030 </para> |
1031 <programlisting># bugzilla-usermap.conf - inside a hg repository | 1031 <programlisting># bugzilla-usermap.conf - inside a hg repository |
1032 [usermap] stephanie@example.com = steph</programlisting> | 1032 [usermap] stephanie@example.com = steph</programlisting> |
1033 | 1033 |
1034 </sect3> | 1034 </sect3> |
1035 <sect3> | 1035 <sect3> |
1036 <title>Configuring the text that gets added to a bug</title> | 1036 <title>Configuring the text that gets added to a bug</title> |
1037 | 1037 |
1038 <para>You can configure the text that this hook adds as a | 1038 <para id="x_25d">You can configure the text that this hook adds as a |
1039 comment; you specify it in the form of a Mercurial template. | 1039 comment; you specify it in the form of a Mercurial template. |
1040 Several <filename role="special">~/.hgrc</filename> entries | 1040 Several <filename role="special">~/.hgrc</filename> entries |
1041 (still in the <literal role="rc-bugzilla">bugzilla</literal> | 1041 (still in the <literal role="rc-bugzilla">bugzilla</literal> |
1042 section) control this behaviour. | 1042 section) control this behaviour. |
1043 </para> | 1043 </para> |
1044 <itemizedlist> | 1044 <itemizedlist> |
1045 <listitem><para><literal>strip</literal>: The number of | 1045 <listitem><para id="x_25e"><literal>strip</literal>: The number of |
1046 leading path elements to strip from a repository's path | 1046 leading path elements to strip from a repository's path |
1047 name to construct a partial path for a URL. For example, | 1047 name to construct a partial path for a URL. For example, |
1048 if the repositories on your server live under <filename | 1048 if the repositories on your server live under <filename |
1049 class="directory">/home/hg/repos</filename>, and you | 1049 class="directory">/home/hg/repos</filename>, and you |
1050 have a repository whose path is <filename | 1050 have a repository whose path is <filename |
1054 <filename class="directory">app/tests</filename>. The | 1054 <filename class="directory">app/tests</filename>. The |
1055 hook will make this partial path available when | 1055 hook will make this partial path available when |
1056 expanding a template, as <literal>webroot</literal>. | 1056 expanding a template, as <literal>webroot</literal>. |
1057 </para> | 1057 </para> |
1058 </listitem> | 1058 </listitem> |
1059 <listitem><para><literal>template</literal>: The text of the | 1059 <listitem><para id="x_25f"><literal>template</literal>: The text of the |
1060 template to use. In addition to the usual | 1060 template to use. In addition to the usual |
1061 changeset-related variables, this template can use | 1061 changeset-related variables, this template can use |
1062 <literal>hgweb</literal> (the value of the | 1062 <literal>hgweb</literal> (the value of the |
1063 <literal>hgweb</literal> configuration item above) and | 1063 <literal>hgweb</literal> configuration item above) and |
1064 <literal>webroot</literal> (the path constructed using | 1064 <literal>webroot</literal> (the path constructed using |
1065 <literal>strip</literal> above). | 1065 <literal>strip</literal> above). |
1066 </para> | 1066 </para> |
1067 </listitem></itemizedlist> | 1067 </listitem></itemizedlist> |
1068 | 1068 |
1069 <para>In addition, you can add a <envar | 1069 <para id="x_260">In addition, you can add a <envar |
1070 role="rc-item-web">baseurl</envar> item to the <literal | 1070 role="rc-item-web">baseurl</envar> item to the <literal |
1071 role="rc-web">web</literal> section of your <filename | 1071 role="rc-web">web</literal> section of your <filename |
1072 role="special">~/.hgrc</filename>. The <literal | 1072 role="special">~/.hgrc</filename>. The <literal |
1073 role="hg-ext">bugzilla</literal> hook will make this | 1073 role="hg-ext">bugzilla</literal> hook will make this |
1074 available when expanding a template, as the base string to | 1074 available when expanding a template, as the base string to |
1076 a Bugzilla comment to view a changeset. Example: | 1076 a Bugzilla comment to view a changeset. Example: |
1077 </para> | 1077 </para> |
1078 <programlisting>[web] | 1078 <programlisting>[web] |
1079 baseurl = http://hg.domain.com/</programlisting> | 1079 baseurl = http://hg.domain.com/</programlisting> |
1080 | 1080 |
1081 <para>Here is an example set of <literal | 1081 <para id="x_261">Here is an example set of <literal |
1082 role="hg-ext">bugzilla</literal> hook config information. | 1082 role="hg-ext">bugzilla</literal> hook config information. |
1083 </para> | 1083 </para> |
1084 | 1084 |
1085 <programlisting>&ch10-bugzilla-config.lst;</programlisting> | 1085 &ch10-bugzilla-config.lst; |
1086 | 1086 |
1087 </sect3> | 1087 </sect3> |
1088 <sect3> | 1088 <sect3> |
1089 <title>Testing and troubleshooting</title> | 1089 <title>Testing and troubleshooting</title> |
1090 | 1090 |
1091 <para>The most common problems with configuring the <literal | 1091 <para id="x_262">The most common problems with configuring the <literal |
1092 role="hg-ext">bugzilla</literal> hook relate to running | 1092 role="hg-ext">bugzilla</literal> hook relate to running |
1093 Bugzilla's <filename>processmail</filename> script and | 1093 Bugzilla's <filename>processmail</filename> script and |
1094 mapping committer names to user names. | 1094 mapping committer names to user names. |
1095 </para> | 1095 </para> |
1096 | 1096 |
1097 <para>Recall from section <xref | 1097 <para id="x_263">Recall from <xref |
1098 linkend="sec.hook.bugzilla.config"/> above that the user | 1098 linkend="sec:hook:bugzilla:config"/> above that the user |
1099 that runs the Mercurial process on the server is also the | 1099 that runs the Mercurial process on the server is also the |
1100 one that will run the <filename>processmail</filename> | 1100 one that will run the <filename>processmail</filename> |
1101 script. The <filename>processmail</filename> script | 1101 script. The <filename>processmail</filename> script |
1102 sometimes causes Bugzilla to write to files in its | 1102 sometimes causes Bugzilla to write to files in its |
1103 configuration directory, and Bugzilla's configuration files | 1103 configuration directory, and Bugzilla's configuration files |
1104 are usually owned by the user that your web server runs | 1104 are usually owned by the user that your web server runs |
1105 under. | 1105 under. |
1106 </para> | 1106 </para> |
1107 | 1107 |
1108 <para>You can cause <filename>processmail</filename> to be run | 1108 <para id="x_264">You can cause <filename>processmail</filename> to be run |
1109 with the suitable user's identity using the | 1109 with the suitable user's identity using the |
1110 <command>sudo</command> command. Here is an example entry | 1110 <command>sudo</command> command. Here is an example entry |
1111 for a <filename>sudoers</filename> file. | 1111 for a <filename>sudoers</filename> file. |
1112 </para> | 1112 </para> |
1113 <programlisting>hg_user = (httpd_user) | 1113 <programlisting>hg_user = (httpd_user) |
1114 NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s</programlisting> | 1114 NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s</programlisting> |
1115 <para>This allows the <literal>hg_user</literal> user to run a | 1115 <para id="x_265">This allows the <literal>hg_user</literal> user to run a |
1116 <filename>processmail-wrapper</filename> program under the | 1116 <filename>processmail-wrapper</filename> program under the |
1117 identity of <literal>httpd_user</literal>. | 1117 identity of <literal>httpd_user</literal>. |
1118 </para> | 1118 </para> |
1119 | 1119 |
1120 <para>This indirection through a wrapper script is necessary, | 1120 <para id="x_266">This indirection through a wrapper script is necessary, |
1121 because <filename>processmail</filename> expects to be run | 1121 because <filename>processmail</filename> expects to be run |
1122 with its current directory set to wherever you installed | 1122 with its current directory set to wherever you installed |
1123 Bugzilla; you can't specify that kind of constraint in a | 1123 Bugzilla; you can't specify that kind of constraint in a |
1124 <filename>sudoers</filename> file. The contents of the | 1124 <filename>sudoers</filename> file. The contents of the |
1125 wrapper script are simple: | 1125 wrapper script are simple: |
1126 </para> | 1126 </para> |
1127 <programlisting>#!/bin/sh | 1127 <programlisting>#!/bin/sh |
1128 cd `dirname $0` && ./processmail "$1" nobody@example.com</programlisting> | 1128 cd `dirname $0` && ./processmail "$1" nobody@example.com</programlisting> |
1129 <para>It doesn't seem to matter what email address you pass to | 1129 <para id="x_267">It doesn't seem to matter what email address you pass to |
1130 <filename>processmail</filename>. | 1130 <filename>processmail</filename>. |
1131 </para> | 1131 </para> |
1132 | 1132 |
1133 <para>If your <literal role="rc-usermap">usermap</literal> is | 1133 <para id="x_268">If your <literal role="rc-usermap">usermap</literal> is |
1134 not set up correctly, users will see an error message from | 1134 not set up correctly, users will see an error message from |
1135 the <literal role="hg-ext">bugzilla</literal> hook when they | 1135 the <literal role="hg-ext">bugzilla</literal> hook when they |
1136 push changes to the server. The error message will look | 1136 push changes to the server. The error message will look |
1137 like this: | 1137 like this: |
1138 </para> | 1138 </para> |
1139 <programlisting>cannot find bugzilla user id for john.q.public@example.com</programlisting> | 1139 <programlisting>cannot find bugzilla user id for john.q.public@example.com</programlisting> |
1140 <para>What this means is that the committer's address, | 1140 <para id="x_269">What this means is that the committer's address, |
1141 <literal>john.q.public@example.com</literal>, is not a valid | 1141 <literal>john.q.public@example.com</literal>, is not a valid |
1142 Bugzilla user name, nor does it have an entry in your | 1142 Bugzilla user name, nor does it have an entry in your |
1143 <literal role="rc-usermap">usermap</literal> that maps it to | 1143 <literal role="rc-usermap">usermap</literal> that maps it to |
1144 a valid Bugzilla user name. | 1144 a valid Bugzilla user name. |
1145 </para> | 1145 </para> |
1148 </sect2> | 1148 </sect2> |
1149 <sect2> | 1149 <sect2> |
1150 <title><literal role="hg-ext">notify</literal>&emdash;send email | 1150 <title><literal role="hg-ext">notify</literal>&emdash;send email |
1151 notifications</title> | 1151 notifications</title> |
1152 | 1152 |
1153 <para>Although Mercurial's built-in web server provides RSS | 1153 <para id="x_26a">Although Mercurial's built-in web server provides RSS |
1154 feeds of changes in every repository, many people prefer to | 1154 feeds of changes in every repository, many people prefer to |
1155 receive change notifications via email. The <literal | 1155 receive change notifications via email. The <literal |
1156 role="hg-ext">notify</literal> hook lets you send out | 1156 role="hg-ext">notify</literal> hook lets you send out |
1157 notifications to a set of email addresses whenever changesets | 1157 notifications to a set of email addresses whenever changesets |
1158 arrive that those subscribers are interested in. | 1158 arrive that those subscribers are interested in. |
1159 </para> | 1159 </para> |
1160 | 1160 |
1161 <para>As with the <literal role="hg-ext">bugzilla</literal> | 1161 <para id="x_26b">As with the <literal role="hg-ext">bugzilla</literal> |
1162 hook, the <literal role="hg-ext">notify</literal> hook is | 1162 hook, the <literal role="hg-ext">notify</literal> hook is |
1163 template-driven, so you can customise the contents of the | 1163 template-driven, so you can customise the contents of the |
1164 notification messages that it sends. | 1164 notification messages that it sends. |
1165 </para> | 1165 </para> |
1166 | 1166 |
1167 <para>By default, the <literal role="hg-ext">notify</literal> | 1167 <para id="x_26c">By default, the <literal role="hg-ext">notify</literal> |
1168 hook includes a diff of every changeset that it sends out; you | 1168 hook includes a diff of every changeset that it sends out; you |
1169 can limit the size of the diff, or turn this feature off | 1169 can limit the size of the diff, or turn this feature off |
1170 entirely. It is useful for letting subscribers review changes | 1170 entirely. It is useful for letting subscribers review changes |
1171 immediately, rather than clicking to follow a URL. | 1171 immediately, rather than clicking to follow a URL. |
1172 </para> | 1172 </para> |
1173 | 1173 |
1174 <sect3> | 1174 <sect3> |
1175 <title>Configuring the <literal role="hg-ext">notify</literal> | 1175 <title>Configuring the <literal role="hg-ext">notify</literal> |
1176 hook</title> | 1176 hook</title> |
1177 | 1177 |
1178 <para>You can set up the <literal | 1178 <para id="x_26d">You can set up the <literal |
1179 role="hg-ext">notify</literal> hook to send one email | 1179 role="hg-ext">notify</literal> hook to send one email |
1180 message per incoming changeset, or one per incoming group of | 1180 message per incoming changeset, or one per incoming group of |
1181 changesets (all those that arrived in a single pull or | 1181 changesets (all those that arrived in a single pull or |
1182 push). | 1182 push). |
1183 </para> | 1183 </para> |
1185 # send one email per group of changes | 1185 # send one email per group of changes |
1186 changegroup.notify = python:hgext.notify.hook | 1186 changegroup.notify = python:hgext.notify.hook |
1187 # send one email per change | 1187 # send one email per change |
1188 incoming.notify = python:hgext.notify.hook</programlisting> | 1188 incoming.notify = python:hgext.notify.hook</programlisting> |
1189 | 1189 |
1190 <para>Configuration information for this hook lives in the | 1190 <para id="x_26e">Configuration information for this hook lives in the |
1191 <literal role="rc-notify">notify</literal> section of a | 1191 <literal role="rc-notify">notify</literal> section of a |
1192 <filename role="special">~/.hgrc</filename> file. | 1192 <filename role="special">~/.hgrc</filename> file. |
1193 </para> | 1193 </para> |
1194 <itemizedlist> | 1194 <itemizedlist> |
1195 <listitem><para><envar role="rc-item-notify">test</envar>: | 1195 <listitem><para id="x_26f"><envar role="rc-item-notify">test</envar>: |
1196 By default, this hook does not send out email at all; | 1196 By default, this hook does not send out email at all; |
1197 instead, it prints the message that it | 1197 instead, it prints the message that it |
1198 <emphasis>would</emphasis> send. Set this item to | 1198 <emphasis>would</emphasis> send. Set this item to |
1199 <literal>false</literal> to allow email to be sent. The | 1199 <literal>false</literal> to allow email to be sent. The |
1200 reason that sending of email is turned off by default is | 1200 reason that sending of email is turned off by default is |
1202 exactly as you would like, and it would be bad form to | 1202 exactly as you would like, and it would be bad form to |
1203 spam subscribers with a number of <quote>broken</quote> | 1203 spam subscribers with a number of <quote>broken</quote> |
1204 notifications while you debug your configuration. | 1204 notifications while you debug your configuration. |
1205 </para> | 1205 </para> |
1206 </listitem> | 1206 </listitem> |
1207 <listitem><para><envar role="rc-item-notify">config</envar>: | 1207 <listitem><para id="x_270"><envar role="rc-item-notify">config</envar>: |
1208 The path to a configuration file that contains | 1208 The path to a configuration file that contains |
1209 subscription information. This is kept separate from | 1209 subscription information. This is kept separate from |
1210 the main <filename role="special">~/.hgrc</filename> so | 1210 the main <filename role="special">~/.hgrc</filename> so |
1211 that you can maintain it in a repository of its own. | 1211 that you can maintain it in a repository of its own. |
1212 People can then clone that repository, update their | 1212 People can then clone that repository, update their |
1213 subscriptions, and push the changes back to your server. | 1213 subscriptions, and push the changes back to your server. |
1214 </para> | 1214 </para> |
1215 </listitem> | 1215 </listitem> |
1216 <listitem><para><envar role="rc-item-notify">strip</envar>: | 1216 <listitem><para id="x_271"><envar role="rc-item-notify">strip</envar>: |
1217 The number of leading path separator characters to strip | 1217 The number of leading path separator characters to strip |
1218 from a repository's path, when deciding whether a | 1218 from a repository's path, when deciding whether a |
1219 repository has subscribers. For example, if the | 1219 repository has subscribers. For example, if the |
1220 repositories on your server live in <filename | 1220 repositories on your server live in <filename |
1221 class="directory">/home/hg/repos</filename>, and | 1221 class="directory">/home/hg/repos</filename>, and |
1228 considers down to <filename | 1228 considers down to <filename |
1229 class="directory">shared/test</filename>, and it will | 1229 class="directory">shared/test</filename>, and it will |
1230 match subscribers against that. | 1230 match subscribers against that. |
1231 </para> | 1231 </para> |
1232 </listitem> | 1232 </listitem> |
1233 <listitem><para><envar | 1233 <listitem><para id="x_272"><envar |
1234 role="rc-item-notify">template</envar>: The template | 1234 role="rc-item-notify">template</envar>: The template |
1235 text to use when sending messages. This specifies both | 1235 text to use when sending messages. This specifies both |
1236 the contents of the message header and its body. | 1236 the contents of the message header and its body. |
1237 </para> | 1237 </para> |
1238 </listitem> | 1238 </listitem> |
1239 <listitem><para><envar | 1239 <listitem><para id="x_273"><envar |
1240 role="rc-item-notify">maxdiff</envar>: The maximum | 1240 role="rc-item-notify">maxdiff</envar>: The maximum |
1241 number of lines of diff data to append to the end of a | 1241 number of lines of diff data to append to the end of a |
1242 message. If a diff is longer than this, it is | 1242 message. If a diff is longer than this, it is |
1243 truncated. By default, this is set to 300. Set this to | 1243 truncated. By default, this is set to 300. Set this to |
1244 <literal>0</literal> to omit diffs from notification | 1244 <literal>0</literal> to omit diffs from notification |
1245 emails. | 1245 emails. |
1246 </para> | 1246 </para> |
1247 </listitem> | 1247 </listitem> |
1248 <listitem><para><envar | 1248 <listitem><para id="x_274"><envar |
1249 role="rc-item-notify">sources</envar>: A list of | 1249 role="rc-item-notify">sources</envar>: A list of |
1250 sources of changesets to consider. This lets you limit | 1250 sources of changesets to consider. This lets you limit |
1251 <literal role="hg-ext">notify</literal> to only sending | 1251 <literal role="hg-ext">notify</literal> to only sending |
1252 out email about changes that remote users pushed into | 1252 out email about changes that remote users pushed into |
1253 this repository via a server, for example. See section | 1253 this repository via a server, for example. See |
1254 <xref | 1254 <xref linkend="sec:hook:sources"/> for the sources you |
1255 linkend="sec.hook.sources"/> for the sources you can | 1255 can specify here. |
1256 specify here. | |
1257 </para> | 1256 </para> |
1258 </listitem></itemizedlist> | 1257 </listitem></itemizedlist> |
1259 | 1258 |
1260 <para>If you set the <envar role="rc-item-web">baseurl</envar> | 1259 <para id="x_275">If you set the <envar role="rc-item-web">baseurl</envar> |
1261 item in the <literal role="rc-web">web</literal> section, | 1260 item in the <literal role="rc-web">web</literal> section, |
1262 you can use it in a template; it will be available as | 1261 you can use it in a template; it will be available as |
1263 <literal>webroot</literal>. | 1262 <literal>webroot</literal>. |
1264 </para> | 1263 </para> |
1265 | 1264 |
1266 <para>Here is an example set of <literal | 1265 <para id="x_276">Here is an example set of <literal |
1267 role="hg-ext">notify</literal> configuration information. | 1266 role="hg-ext">notify</literal> configuration information. |
1268 </para> | 1267 </para> |
1269 | 1268 |
1270 <programlisting>&ch10-notify-config.lst;</programlisting> | 1269 &ch10-notify-config.lst; |
1271 | 1270 |
1272 <para>This will produce a message that looks like the | 1271 <para id="x_277">This will produce a message that looks like the |
1273 following: | 1272 following: |
1274 </para> | 1273 </para> |
1275 | 1274 |
1276 <programlisting>&ch10-notify-config-mail.lst;</programlisting> | 1275 &ch10-notify-config-mail.lst; |
1277 | 1276 |
1278 </sect3> | 1277 </sect3> |
1279 <sect3> | 1278 <sect3> |
1280 <title>Testing and troubleshooting</title> | 1279 <title>Testing and troubleshooting</title> |
1281 | 1280 |
1282 <para>Do not forget that by default, the <literal | 1281 <para id="x_278">Do not forget that by default, the <literal |
1283 role="hg-ext">notify</literal> extension <emphasis>will not | 1282 role="hg-ext">notify</literal> extension <emphasis>will not |
1284 send any mail</emphasis> until you explicitly configure it to do so, | 1283 send any mail</emphasis> until you explicitly configure it to do so, |
1285 by setting <envar role="rc-item-notify">test</envar> to | 1284 by setting <envar role="rc-item-notify">test</envar> to |
1286 <literal>false</literal>. Until you do that, it simply | 1285 <literal>false</literal>. Until you do that, it simply |
1287 prints the message it <emphasis>would</emphasis> send. | 1286 prints the message it <emphasis>would</emphasis> send. |
1288 </para> | 1287 </para> |
1289 | 1288 |
1290 </sect3> | 1289 </sect3> |
1291 </sect2> | 1290 </sect2> |
1292 </sect1> | 1291 </sect1> |
1293 <sect1 id="sec.hook.ref"> | 1292 <sect1 id="sec:hook:ref"> |
1294 <title>Information for writers of hooks</title> | 1293 <title>Information for writers of hooks</title> |
1295 | 1294 |
1296 <sect2> | 1295 <sect2> |
1297 <title>In-process hook execution</title> | 1296 <title>In-process hook execution</title> |
1298 | 1297 |
1299 <para>An in-process hook is called with arguments of the | 1298 <para id="x_279">An in-process hook is called with arguments of the |
1300 following form: | 1299 following form: |
1301 </para> | 1300 </para> |
1302 <programlisting>def myhook(ui, repo, **kwargs): pass</programlisting> | 1301 <programlisting>def myhook(ui, repo, **kwargs): pass</programlisting> |
1303 <para>The <literal>ui</literal> parameter is a <literal | 1302 <para id="x_27a">The <literal>ui</literal> parameter is a <literal |
1304 role="py-mod-mercurial.ui">ui</literal> object. The | 1303 role="py-mod-mercurial.ui">ui</literal> object. The |
1305 <literal>repo</literal> parameter is a <literal | 1304 <literal>repo</literal> parameter is a <literal |
1306 role="py-mod-mercurial.localrepo">localrepository</literal> | 1305 role="py-mod-mercurial.localrepo">localrepository</literal> |
1307 object. The names and values of the | 1306 object. The names and values of the |
1308 <literal>**kwargs</literal> parameters depend on the hook | 1307 <literal>**kwargs</literal> parameters depend on the hook |
1309 being invoked, with the following common features: | 1308 being invoked, with the following common features: |
1310 </para> | 1309 </para> |
1311 <itemizedlist> | 1310 <itemizedlist> |
1312 <listitem><para>If a parameter is named | 1311 <listitem><para id="x_27b">If a parameter is named |
1313 <literal>node</literal> or <literal>parentN</literal>, it | 1312 <literal>node</literal> or <literal>parentN</literal>, it |
1314 will contain a hexadecimal changeset ID. The empty string | 1313 will contain a hexadecimal changeset ID. The empty string |
1315 is used to represent <quote>null changeset ID</quote> | 1314 is used to represent <quote>null changeset ID</quote> |
1316 instead of a string of zeroes. | 1315 instead of a string of zeroes. |
1317 </para> | 1316 </para> |
1318 </listitem> | 1317 </listitem> |
1319 <listitem><para>If a parameter is named | 1318 <listitem><para id="x_27c">If a parameter is named |
1320 <literal>url</literal>, it will contain the URL of a | 1319 <literal>url</literal>, it will contain the URL of a |
1321 remote repository, if that can be determined. | 1320 remote repository, if that can be determined. |
1322 </para> | 1321 </para> |
1323 </listitem> | 1322 </listitem> |
1324 <listitem><para>Boolean-valued parameters are represented as | 1323 <listitem><para id="x_27d">Boolean-valued parameters are represented as |
1325 Python <literal>bool</literal> objects. | 1324 Python <literal>bool</literal> objects. |
1326 </para> | 1325 </para> |
1327 </listitem></itemizedlist> | 1326 </listitem></itemizedlist> |
1328 | 1327 |
1329 <para>An in-process hook is called without a change to the | 1328 <para id="x_27e">An in-process hook is called without a change to the |
1330 process's working directory (unlike external hooks, which are | 1329 process's working directory (unlike external hooks, which are |
1331 run in the root of the repository). It must not change the | 1330 run in the root of the repository). It must not change the |
1332 process's working directory, or it will cause any calls it | 1331 process's working directory, or it will cause any calls it |
1333 makes into the Mercurial API to fail. | 1332 makes into the Mercurial API to fail. |
1334 </para> | 1333 </para> |
1335 | 1334 |
1336 <para>If a hook returns a boolean <quote>false</quote> value, it | 1335 <para id="x_27f">If a hook returns a boolean <quote>false</quote> value, it |
1337 is considered to have succeeded. If it returns a boolean | 1336 is considered to have succeeded. If it returns a boolean |
1338 <quote>true</quote> value or raises an exception, it is | 1337 <quote>true</quote> value or raises an exception, it is |
1339 considered to have failed. A useful way to think of the | 1338 considered to have failed. A useful way to think of the |
1340 calling convention is <quote>tell me if you fail</quote>. | 1339 calling convention is <quote>tell me if you fail</quote>. |
1341 </para> | 1340 </para> |
1342 | 1341 |
1343 <para>Note that changeset IDs are passed into Python hooks as | 1342 <para id="x_280">Note that changeset IDs are passed into Python hooks as |
1344 hexadecimal strings, not the binary hashes that Mercurial's | 1343 hexadecimal strings, not the binary hashes that Mercurial's |
1345 APIs normally use. To convert a hash from hex to binary, use | 1344 APIs normally use. To convert a hash from hex to binary, use |
1346 the <literal>bin</literal> function. | 1345 the <literal>bin</literal> function. |
1347 </para> | 1346 </para> |
1348 | 1347 |
1349 </sect2> | 1348 </sect2> |
1350 <sect2> | 1349 <sect2> |
1351 <title>External hook execution</title> | 1350 <title>External hook execution</title> |
1352 | 1351 |
1353 <para>An external hook is passed to the shell of the user | 1352 <para id="x_281">An external hook is passed to the shell of the user |
1354 running Mercurial. Features of that shell, such as variable | 1353 running Mercurial. Features of that shell, such as variable |
1355 substitution and command redirection, are available. The hook | 1354 substitution and command redirection, are available. The hook |
1356 is run in the root directory of the repository (unlike | 1355 is run in the root directory of the repository (unlike |
1357 in-process hooks, which are run in the same directory that | 1356 in-process hooks, which are run in the same directory that |
1358 Mercurial was run in). | 1357 Mercurial was run in). |
1359 </para> | 1358 </para> |
1360 | 1359 |
1361 <para>Hook parameters are passed to the hook as environment | 1360 <para id="x_282">Hook parameters are passed to the hook as environment |
1362 variables. Each environment variable's name is converted in | 1361 variables. Each environment variable's name is converted in |
1363 upper case and prefixed with the string | 1362 upper case and prefixed with the string |
1364 <quote><literal>HG_</literal></quote>. For example, if the | 1363 <quote><literal>HG_</literal></quote>. For example, if the |
1365 name of a parameter is <quote><literal>node</literal></quote>, | 1364 name of a parameter is <quote><literal>node</literal></quote>, |
1366 the name of the environment variable representing that | 1365 the name of the environment variable representing that |
1367 parameter will be <quote><literal>HG_NODE</literal></quote>. | 1366 parameter will be <quote><literal>HG_NODE</literal></quote>. |
1368 </para> | 1367 </para> |
1369 | 1368 |
1370 <para>A boolean parameter is represented as the string | 1369 <para id="x_283">A boolean parameter is represented as the string |
1371 <quote><literal>1</literal></quote> for <quote>true</quote>, | 1370 <quote><literal>1</literal></quote> for <quote>true</quote>, |
1372 <quote><literal>0</literal></quote> for <quote>false</quote>. | 1371 <quote><literal>0</literal></quote> for <quote>false</quote>. |
1373 If an environment variable is named <envar>HG_NODE</envar>, | 1372 If an environment variable is named <envar>HG_NODE</envar>, |
1374 <envar>HG_PARENT1</envar> or <envar>HG_PARENT2</envar>, it | 1373 <envar>HG_PARENT1</envar> or <envar>HG_PARENT2</envar>, it |
1375 contains a changeset ID represented as a hexadecimal string. | 1374 contains a changeset ID represented as a hexadecimal string. |
1377 ID</quote> instead of a string of zeroes. If an environment | 1376 ID</quote> instead of a string of zeroes. If an environment |
1378 variable is named <envar>HG_URL</envar>, it will contain the | 1377 variable is named <envar>HG_URL</envar>, it will contain the |
1379 URL of a remote repository, if that can be determined. | 1378 URL of a remote repository, if that can be determined. |
1380 </para> | 1379 </para> |
1381 | 1380 |
1382 <para>If a hook exits with a status of zero, it is considered to | 1381 <para id="x_284">If a hook exits with a status of zero, it is considered to |
1383 have succeeded. If it exits with a non-zero status, it is | 1382 have succeeded. If it exits with a non-zero status, it is |
1384 considered to have failed. | 1383 considered to have failed. |
1385 </para> | 1384 </para> |
1386 | 1385 |
1387 </sect2> | 1386 </sect2> |
1388 <sect2> | 1387 <sect2> |
1389 <title>Finding out where changesets come from</title> | 1388 <title>Finding out where changesets come from</title> |
1390 | 1389 |
1391 <para>A hook that involves the transfer of changesets between a | 1390 <para id="x_285">A hook that involves the transfer of changesets between a |
1392 local repository and another may be able to find out | 1391 local repository and another may be able to find out |
1393 information about the <quote>far side</quote>. Mercurial | 1392 information about the <quote>far side</quote>. Mercurial |
1394 knows <emphasis>how</emphasis> changes are being transferred, | 1393 knows <emphasis>how</emphasis> changes are being transferred, |
1395 and in many cases <emphasis>where</emphasis> they are being | 1394 and in many cases <emphasis>where</emphasis> they are being |
1396 transferred to or from. | 1395 transferred to or from. |
1397 </para> | 1396 </para> |
1398 | 1397 |
1399 <sect3 id="sec.hook.sources"> | 1398 <sect3 id="sec:hook:sources"> |
1400 <title>Sources of changesets</title> | 1399 <title>Sources of changesets</title> |
1401 | 1400 |
1402 <para>Mercurial will tell a hook what means are, or were, used | 1401 <para id="x_286">Mercurial will tell a hook what means are, or were, used |
1403 to transfer changesets between repositories. This is | 1402 to transfer changesets between repositories. This is |
1404 provided by Mercurial in a Python parameter named | 1403 provided by Mercurial in a Python parameter named |
1405 <literal>source</literal>, or an environment variable named | 1404 <literal>source</literal>, or an environment variable named |
1406 <envar>HG_SOURCE</envar>. | 1405 <envar>HG_SOURCE</envar>. |
1407 </para> | 1406 </para> |
1408 | 1407 |
1409 <itemizedlist> | 1408 <itemizedlist> |
1410 <listitem><para><literal>serve</literal>: Changesets are | 1409 <listitem><para id="x_287"><literal>serve</literal>: Changesets are |
1411 transferred to or from a remote repository over http or | 1410 transferred to or from a remote repository over http or |
1412 ssh. | 1411 ssh. |
1413 </para> | 1412 </para> |
1414 </listitem> | 1413 </listitem> |
1415 <listitem><para><literal>pull</literal>: Changesets are | 1414 <listitem><para id="x_288"><literal>pull</literal>: Changesets are |
1416 being transferred via a pull from one repository into | 1415 being transferred via a pull from one repository into |
1417 another. | 1416 another. |
1418 </para> | 1417 </para> |
1419 </listitem> | 1418 </listitem> |
1420 <listitem><para><literal>push</literal>: Changesets are | 1419 <listitem><para id="x_289"><literal>push</literal>: Changesets are |
1421 being transferred via a push from one repository into | 1420 being transferred via a push from one repository into |
1422 another. | 1421 another. |
1423 </para> | 1422 </para> |
1424 </listitem> | 1423 </listitem> |
1425 <listitem><para><literal>bundle</literal>: Changesets are | 1424 <listitem><para id="x_28a"><literal>bundle</literal>: Changesets are |
1426 being transferred to or from a bundle. | 1425 being transferred to or from a bundle. |
1427 </para> | 1426 </para> |
1428 </listitem></itemizedlist> | 1427 </listitem></itemizedlist> |
1429 | 1428 |
1430 </sect3> | 1429 </sect3> |
1431 <sect3 id="sec.hook.url"> | 1430 <sect3 id="sec:hook:url"> |
1432 <title>Where changes are going&emdash;remote repository | 1431 <title>Where changes are going&emdash;remote repository |
1433 URLs</title> | 1432 URLs</title> |
1434 | 1433 |
1435 <para>When possible, Mercurial will tell a hook the location | 1434 <para id="x_28b">When possible, Mercurial will tell a hook the location |
1436 of the <quote>far side</quote> of an activity that transfers | 1435 of the <quote>far side</quote> of an activity that transfers |
1437 changeset data between repositories. This is provided by | 1436 changeset data between repositories. This is provided by |
1438 Mercurial in a Python parameter named | 1437 Mercurial in a Python parameter named |
1439 <literal>url</literal>, or an environment variable named | 1438 <literal>url</literal>, or an environment variable named |
1440 <envar>HG_URL</envar>. | 1439 <envar>HG_URL</envar>. |
1441 </para> | 1440 </para> |
1442 | 1441 |
1443 <para>This information is not always known. If a hook is | 1442 <para id="x_28c">This information is not always known. If a hook is |
1444 invoked in a repository that is being served via http or | 1443 invoked in a repository that is being served via http or |
1445 ssh, Mercurial cannot tell where the remote repository is, | 1444 ssh, Mercurial cannot tell where the remote repository is, |
1446 but it may know where the client is connecting from. In | 1445 but it may know where the client is connecting from. In |
1447 such cases, the URL will take one of the following forms: | 1446 such cases, the URL will take one of the following forms: |
1448 </para> | 1447 </para> |
1449 <itemizedlist> | 1448 <itemizedlist> |
1450 <listitem><para><literal>remote:ssh:1.2.3.4</literal>&emdash;remote | 1449 <listitem><para id="x_28d"><literal>remote:ssh:1.2.3.4</literal>&emdash;remote |
1451 ssh client, at the IP address | 1450 ssh client, at the IP address |
1452 <literal>1.2.3.4</literal>. | 1451 <literal>1.2.3.4</literal>. |
1453 </para> | 1452 </para> |
1454 </listitem> | 1453 </listitem> |
1455 <listitem><para><literal>remote:http:1.2.3.4</literal>&emdash;remote | 1454 <listitem><para id="x_28e"><literal>remote:http:1.2.3.4</literal>&emdash;remote |
1456 http client, at the IP address | 1455 http client, at the IP address |
1457 <literal>1.2.3.4</literal>. If the client is using SSL, | 1456 <literal>1.2.3.4</literal>. If the client is using SSL, |
1458 this will be of the form | 1457 this will be of the form |
1459 <literal>remote:https:1.2.3.4</literal>. | 1458 <literal>remote:https:1.2.3.4</literal>. |
1460 </para> | 1459 </para> |
1461 </listitem> | 1460 </listitem> |
1462 <listitem><para>Empty&emdash;no information could be | 1461 <listitem><para id="x_28f">Empty&emdash;no information could be |
1463 discovered about the remote client. | 1462 discovered about the remote client. |
1464 </para> | 1463 </para> |
1465 </listitem></itemizedlist> | 1464 </listitem></itemizedlist> |
1466 | 1465 |
1467 </sect3> | 1466 </sect3> |
1468 </sect2> | 1467 </sect2> |
1469 </sect1> | 1468 </sect1> |
1470 <sect1> | 1469 <sect1> |
1471 <title>Hook reference</title> | 1470 <title>Hook reference</title> |
1472 | 1471 |
1473 <sect2 id="sec.hook.changegroup"> | 1472 <sect2 id="sec:hook:changegroup"> |
1474 <title><literal role="hook">changegroup</literal>&emdash;after | 1473 <title><literal role="hook">changegroup</literal>&emdash;after |
1475 remote changesets added</title> | 1474 remote changesets added</title> |
1476 | 1475 |
1477 <para>This hook is run after a group of pre-existing changesets | 1476 <para id="x_290">This hook is run after a group of pre-existing changesets |
1478 has been added to the repository, for example via a <command | 1477 has been added to the repository, for example via a <command |
1479 role="hg-cmd">hg pull</command> or <command role="hg-cmd">hg | 1478 role="hg-cmd">hg pull</command> or <command role="hg-cmd">hg |
1480 unbundle</command>. This hook is run once per operation | 1479 unbundle</command>. This hook is run once per operation |
1481 that added one or more changesets. This is in contrast to the | 1480 that added one or more changesets. This is in contrast to the |
1482 <literal role="hook">incoming</literal> hook, which is run | 1481 <literal role="hook">incoming</literal> hook, which is run |
1483 once per changeset, regardless of whether the changesets | 1482 once per changeset, regardless of whether the changesets |
1484 arrive in a group. | 1483 arrive in a group. |
1485 </para> | 1484 </para> |
1486 | 1485 |
1487 <para>Some possible uses for this hook include kicking off an | 1486 <para id="x_291">Some possible uses for this hook include kicking off an |
1488 automated build or test of the added changesets, updating a | 1487 automated build or test of the added changesets, updating a |
1489 bug database, or notifying subscribers that a repository | 1488 bug database, or notifying subscribers that a repository |
1490 contains new changes. | 1489 contains new changes. |
1491 </para> | 1490 </para> |
1492 | 1491 |
1493 <para>Parameters to this hook: | 1492 <para id="x_292">Parameters to this hook: |
1494 </para> | 1493 </para> |
1495 <itemizedlist> | 1494 <itemizedlist> |
1496 <listitem><para><literal>node</literal>: A changeset ID. The | 1495 <listitem><para id="x_293"><literal>node</literal>: A changeset ID. The |
1497 changeset ID of the first changeset in the group that was | 1496 changeset ID of the first changeset in the group that was |
1498 added. All changesets between this and | 1497 added. All changesets between this and |
1499 <literal role="tag">tip</literal>, inclusive, were added by a single | 1498 <literal role="tag">tip</literal>, inclusive, were added by a single |
1500 <command role="hg-cmd">hg pull</command>, <command | 1499 <command role="hg-cmd">hg pull</command>, <command |
1501 role="hg-cmd">hg push</command> or <command | 1500 role="hg-cmd">hg push</command> or <command |
1502 role="hg-cmd">hg unbundle</command>. | 1501 role="hg-cmd">hg unbundle</command>. |
1503 </para> | 1502 </para> |
1504 </listitem> | 1503 </listitem> |
1505 <listitem><para><literal>source</literal>: A string. The | 1504 <listitem><para id="x_294"><literal>source</literal>: A |
1506 source of these changes. See section <xref | 1505 string. The source of these changes. See <xref |
1507 linkend="sec.hook.sources"/> for details. | 1506 linkend="sec:hook:sources"/> for details. |
1508 </para> | 1507 </para> |
1509 </listitem> | 1508 </listitem> |
1510 <listitem><para><literal>url</literal>: A URL. The location | 1509 <listitem><para id="x_295"><literal>url</literal>: A URL. The |
1511 of the remote repository, if known. See section <xref | 1510 location of the remote repository, if known. See <xref |
1512 linkend="sec.hook.url"/> for more | 1511 linkend="sec:hook:url"/> for more information. |
1513 information. | |
1514 </para> | 1512 </para> |
1515 </listitem></itemizedlist> | 1513 </listitem></itemizedlist> |
1516 | 1514 |
1517 <para>See also: <literal role="hook">incoming</literal> (section | 1515 <para id="x_296">See also: <literal |
1518 <xref linkend="sec.hook.incoming"/>), <literal | 1516 role="hook">incoming</literal> (<xref |
1519 role="hook">prechangegroup</literal> (section <xref | 1517 linkend="sec:hook:incoming"/>), <literal |
1520 linkend="sec.hook.prechangegroup"/>), <literal | 1518 role="hook">prechangegroup</literal> (<xref |
1521 role="hook">pretxnchangegroup</literal> (section <xref | 1519 linkend="sec:hook:prechangegroup"/>), <literal |
1522 linkend="sec.hook.pretxnchangegroup"/>) | 1520 role="hook">pretxnchangegroup</literal> (<xref |
1523 </para> | 1521 linkend="sec:hook:pretxnchangegroup"/>) |
1524 | 1522 </para> |
1525 </sect2> | 1523 |
1526 <sect2 id="sec.hook.commit"> | 1524 </sect2> |
1525 <sect2 id="sec:hook:commit"> | |
1527 <title><literal role="hook">commit</literal>&emdash;after a new | 1526 <title><literal role="hook">commit</literal>&emdash;after a new |
1528 changeset is created</title> | 1527 changeset is created</title> |
1529 | 1528 |
1530 <para>This hook is run after a new changeset has been created. | 1529 <para id="x_297">This hook is run after a new changeset has been created. |
1531 </para> | 1530 </para> |
1532 | 1531 |
1533 <para>Parameters to this hook: | 1532 <para id="x_298">Parameters to this hook: |
1534 </para> | 1533 </para> |
1535 <itemizedlist> | 1534 <itemizedlist> |
1536 <listitem><para><literal>node</literal>: A changeset ID. The | 1535 <listitem><para id="x_299"><literal>node</literal>: A changeset ID. The |
1537 changeset ID of the newly committed changeset. | 1536 changeset ID of the newly committed changeset. |
1538 </para> | 1537 </para> |
1539 </listitem> | 1538 </listitem> |
1540 <listitem><para><literal>parent1</literal>: A changeset ID. | 1539 <listitem><para id="x_29a"><literal>parent1</literal>: A changeset ID. |
1541 The changeset ID of the first parent of the newly | 1540 The changeset ID of the first parent of the newly |
1542 committed changeset. | 1541 committed changeset. |
1543 </para> | 1542 </para> |
1544 </listitem> | 1543 </listitem> |
1545 <listitem><para><literal>parent2</literal>: A changeset ID. | 1544 <listitem><para id="x_29b"><literal>parent2</literal>: A changeset ID. |
1546 The changeset ID of the second parent of the newly | 1545 The changeset ID of the second parent of the newly |
1547 committed changeset. | 1546 committed changeset. |
1548 </para> | 1547 </para> |
1549 </listitem></itemizedlist> | 1548 </listitem></itemizedlist> |
1550 | 1549 |
1551 <para>See also: <literal role="hook">precommit</literal> | 1550 <para id="x_29c">See also: <literal |
1552 (section <xref linkend="sec.hook.precommit"/>), <literal | 1551 role="hook">precommit</literal> (<xref |
1553 role="hook">pretxncommit</literal> (section <xref | 1552 linkend="sec:hook:precommit"/>), <literal |
1554 linkend="sec.hook.pretxncommit"/>) | 1553 role="hook">pretxncommit</literal> (<xref |
1555 </para> | 1554 linkend="sec:hook:pretxncommit"/>) |
1556 | 1555 </para> |
1557 </sect2> | 1556 |
1558 <sect2 id="sec.hook.incoming"> | 1557 </sect2> |
1558 <sect2 id="sec:hook:incoming"> | |
1559 <title><literal role="hook">incoming</literal>&emdash;after one | 1559 <title><literal role="hook">incoming</literal>&emdash;after one |
1560 remote changeset is added</title> | 1560 remote changeset is added</title> |
1561 | 1561 |
1562 <para>This hook is run after a pre-existing changeset has been | 1562 <para id="x_29d">This hook is run after a pre-existing changeset has been |
1563 added to the repository, for example via a <command | 1563 added to the repository, for example via a <command |
1564 role="hg-cmd">hg push</command>. If a group of changesets | 1564 role="hg-cmd">hg push</command>. If a group of changesets |
1565 was added in a single operation, this hook is called once for | 1565 was added in a single operation, this hook is called once for |
1566 each added changeset. | 1566 each added changeset. |
1567 </para> | 1567 </para> |
1568 | 1568 |
1569 <para>You can use this hook for the same purposes as the | 1569 <para id="x_29e">You can use this hook for the same purposes as |
1570 <literal role="hook">changegroup</literal> hook (section <xref | 1570 the <literal role="hook">changegroup</literal> hook (<xref |
1571 linkend="sec.hook.changegroup"/>); it's simply | 1571 linkend="sec:hook:changegroup"/>); it's simply more |
1572 more convenient sometimes to run a hook once per group of | 1572 convenient sometimes to run a hook once per group of |
1573 changesets, while other times it's handier once per changeset. | 1573 changesets, while other times it's handier once per changeset. |
1574 </para> | 1574 </para> |
1575 | 1575 |
1576 <para>Parameters to this hook: | 1576 <para id="x_29f">Parameters to this hook: |
1577 </para> | 1577 </para> |
1578 <itemizedlist> | 1578 <itemizedlist> |
1579 <listitem><para><literal>node</literal>: A changeset ID. The | 1579 <listitem><para id="x_2a0"><literal>node</literal>: A changeset ID. The |
1580 ID of the newly added changeset. | 1580 ID of the newly added changeset. |
1581 </para> | 1581 </para> |
1582 </listitem> | 1582 </listitem> |
1583 <listitem><para><literal>source</literal>: A string. The | 1583 <listitem><para id="x_2a1"><literal>source</literal>: A |
1584 source of these changes. See section <xref | 1584 string. The source of these changes. See <xref |
1585 linkend="sec.hook.sources"/> for details. | 1585 linkend="sec:hook:sources"/> for details. |
1586 </para> | 1586 </para> |
1587 </listitem> | 1587 </listitem> |
1588 <listitem><para><literal>url</literal>: A URL. The location | 1588 <listitem><para id="x_2a2"><literal>url</literal>: A URL. The |
1589 of the remote repository, if known. See section <xref | 1589 location of the remote repository, if known. See <xref |
1590 linkend="sec.hook.url"/> for more | 1590 linkend="sec:hook:url"/> for more information. |
1591 information. | |
1592 </para> | 1591 </para> |
1593 </listitem></itemizedlist> | 1592 </listitem></itemizedlist> |
1594 | 1593 |
1595 <para>See also: <literal role="hook">changegroup</literal> | 1594 <para id="x_2a3">See also: <literal |
1596 (section <xref linkend="sec.hook.changegroup"/>) <literal | 1595 role="hook">changegroup</literal> (<xref |
1597 role="hook">prechangegroup</literal> (section <xref | 1596 linkend="sec:hook:changegroup"/>) <literal |
1598 linkend="sec.hook.prechangegroup"/>), <literal | 1597 role="hook">prechangegroup</literal> (<xref |
1599 role="hook">pretxnchangegroup</literal> (section <xref | 1598 linkend="sec:hook:prechangegroup"/>), <literal |
1600 linkend="sec.hook.pretxnchangegroup"/>) | 1599 role="hook">pretxnchangegroup</literal> (<xref |
1601 </para> | 1600 linkend="sec:hook:pretxnchangegroup"/>) |
1602 | 1601 </para> |
1603 </sect2> | 1602 |
1604 <sect2 id="sec.hook.outgoing"> | 1603 </sect2> |
1604 <sect2 id="sec:hook:outgoing"> | |
1605 <title><literal role="hook">outgoing</literal>&emdash;after | 1605 <title><literal role="hook">outgoing</literal>&emdash;after |
1606 changesets are propagated</title> | 1606 changesets are propagated</title> |
1607 | 1607 |
1608 <para>This hook is run after a group of changesets has been | 1608 <para id="x_2a4">This hook is run after a group of changesets has been |
1609 propagated out of this repository, for example by a <command | 1609 propagated out of this repository, for example by a <command |
1610 role="hg-cmd">hg push</command> or <command role="hg-cmd">hg | 1610 role="hg-cmd">hg push</command> or <command role="hg-cmd">hg |
1611 bundle</command> command. | 1611 bundle</command> command. |
1612 </para> | 1612 </para> |
1613 | 1613 |
1614 <para>One possible use for this hook is to notify administrators | 1614 <para id="x_2a5">One possible use for this hook is to notify administrators |
1615 that changes have been pulled. | 1615 that changes have been pulled. |
1616 </para> | 1616 </para> |
1617 | 1617 |
1618 <para>Parameters to this hook: | 1618 <para id="x_2a6">Parameters to this hook: |
1619 </para> | 1619 </para> |
1620 <itemizedlist> | 1620 <itemizedlist> |
1621 <listitem><para><literal>node</literal>: A changeset ID. The | 1621 <listitem><para id="x_2a7"><literal>node</literal>: A changeset ID. The |
1622 changeset ID of the first changeset of the group that was | 1622 changeset ID of the first changeset of the group that was |
1623 sent. | 1623 sent. |
1624 </para> | 1624 </para> |
1625 </listitem> | 1625 </listitem> |
1626 <listitem><para><literal>source</literal>: A string. The | 1626 <listitem><para id="x_2a8"><literal>source</literal>: A string. The |
1627 source of the of the operation (see section <xref | 1627 source of the of the operation (see <xref |
1628 linkend="sec.hook.sources"/>). If a remote | 1628 linkend="sec:hook:sources"/>). If a remote |
1629 client pulled changes from this repository, | 1629 client pulled changes from this repository, |
1630 <literal>source</literal> will be | 1630 <literal>source</literal> will be |
1631 <literal>serve</literal>. If the client that obtained | 1631 <literal>serve</literal>. If the client that obtained |
1632 changes from this repository was local, | 1632 changes from this repository was local, |
1633 <literal>source</literal> will be | 1633 <literal>source</literal> will be |
1634 <literal>bundle</literal>, <literal>pull</literal>, or | 1634 <literal>bundle</literal>, <literal>pull</literal>, or |
1635 <literal>push</literal>, depending on the operation the | 1635 <literal>push</literal>, depending on the operation the |
1636 client performed. | 1636 client performed. |
1637 </para> | 1637 </para> |
1638 </listitem> | 1638 </listitem> |
1639 <listitem><para><literal>url</literal>: A URL. The location | 1639 <listitem><para id="x_2a9"><literal>url</literal>: A URL. The |
1640 of the remote repository, if known. See section <xref | 1640 location of the remote repository, if known. See <xref |
1641 linkend="sec.hook.url"/> for more | 1641 linkend="sec:hook:url"/> for more information. |
1642 information. | |
1643 </para> | 1642 </para> |
1644 </listitem></itemizedlist> | 1643 </listitem></itemizedlist> |
1645 | 1644 |
1646 <para>See also: <literal role="hook">preoutgoing</literal> | 1645 <para id="x_2aa">See also: <literal |
1647 (section <xref linkend="sec.hook.preoutgoing"/>) | 1646 role="hook">preoutgoing</literal> (<xref |
1648 </para> | 1647 linkend="sec:hook:preoutgoing"/>) |
1649 | 1648 </para> |
1650 </sect2> | 1649 |
1651 <sect2 id="sec.hook.prechangegroup"> | 1650 </sect2> |
1651 <sect2 id="sec:hook:prechangegroup"> | |
1652 <title><literal | 1652 <title><literal |
1653 role="hook">prechangegroup</literal>&emdash;before starting | 1653 role="hook">prechangegroup</literal>&emdash;before starting |
1654 to add remote changesets</title> | 1654 to add remote changesets</title> |
1655 | 1655 |
1656 <para>This controlling hook is run before Mercurial begins to | 1656 <para id="x_2ab">This controlling hook is run before Mercurial begins to |
1657 add a group of changesets from another repository. | 1657 add a group of changesets from another repository. |
1658 </para> | 1658 </para> |
1659 | 1659 |
1660 <para>This hook does not have any information about the | 1660 <para id="x_2ac">This hook does not have any information about the |
1661 changesets to be added, because it is run before transmission | 1661 changesets to be added, because it is run before transmission |
1662 of those changesets is allowed to begin. If this hook fails, | 1662 of those changesets is allowed to begin. If this hook fails, |
1663 the changesets will not be transmitted. | 1663 the changesets will not be transmitted. |
1664 </para> | 1664 </para> |
1665 | 1665 |
1666 <para>One use for this hook is to prevent external changes from | 1666 <para id="x_2ad">One use for this hook is to prevent external changes from |
1667 being added to a repository. For example, you could use this | 1667 being added to a repository. For example, you could use this |
1668 to <quote>freeze</quote> a server-hosted branch temporarily or | 1668 to <quote>freeze</quote> a server-hosted branch temporarily or |
1669 permanently so that users cannot push to it, while still | 1669 permanently so that users cannot push to it, while still |
1670 allowing a local administrator to modify the repository. | 1670 allowing a local administrator to modify the repository. |
1671 </para> | 1671 </para> |
1672 | 1672 |
1673 <para>Parameters to this hook: | 1673 <para id="x_2ae">Parameters to this hook: |
1674 </para> | 1674 </para> |
1675 <itemizedlist> | 1675 <itemizedlist> |
1676 <listitem><para><literal>source</literal>: A string. The | 1676 <listitem><para id="x_2af"><literal>source</literal>: A string. The |
1677 source of these changes. See section <xref | 1677 source of these changes. See <xref |
1678 linkend="sec.hook.sources"/> for details. | 1678 linkend="sec:hook:sources"/> for details. |
1679 </para> | 1679 </para> |
1680 </listitem> | 1680 </listitem> |
1681 <listitem><para><literal>url</literal>: A URL. The location | 1681 <listitem><para id="x_2b0"><literal>url</literal>: A URL. The |
1682 of the remote repository, if known. See section <xref | 1682 location of the remote repository, if known. See <xref |
1683 linkend="sec.hook.url"/> for more | 1683 linkend="sec:hook:url"/> for more information. |
1684 information. | |
1685 </para> | 1684 </para> |
1686 </listitem></itemizedlist> | 1685 </listitem></itemizedlist> |
1687 | 1686 |
1688 <para>See also: <literal role="hook">changegroup</literal> | 1687 <para id="x_2b1">See also: <literal |
1689 (section <xref linkend="sec.hook.changegroup"/>), <literal | 1688 role="hook">changegroup</literal> (<xref |
1690 role="hook">incoming</literal> (section <xref | 1689 linkend="sec:hook:changegroup"/>), <literal |
1691 linkend="sec.hook.incoming"/>), , <literal | 1690 role="hook">incoming</literal> (<xref |
1692 role="hook">pretxnchangegroup</literal> (section <xref | 1691 linkend="sec:hook:incoming"/>), <literal |
1693 linkend="sec.hook.pretxnchangegroup"/>) | 1692 role="hook">pretxnchangegroup</literal> (<xref |
1694 </para> | 1693 linkend="sec:hook:pretxnchangegroup"/>) |
1695 | 1694 </para> |
1696 </sect2> | 1695 |
1697 <sect2 id="sec.hook.precommit"> | 1696 </sect2> |
1697 <sect2 id="sec:hook:precommit"> | |
1698 <title><literal role="hook">precommit</literal>&emdash;before | 1698 <title><literal role="hook">precommit</literal>&emdash;before |
1699 starting to commit a changeset</title> | 1699 starting to commit a changeset</title> |
1700 | 1700 |
1701 <para>This hook is run before Mercurial begins to commit a new | 1701 <para id="x_2b2">This hook is run before Mercurial begins to commit a new |
1702 changeset. It is run before Mercurial has any of the metadata | 1702 changeset. It is run before Mercurial has any of the metadata |
1703 for the commit, such as the files to be committed, the commit | 1703 for the commit, such as the files to be committed, the commit |
1704 message, or the commit date. | 1704 message, or the commit date. |
1705 </para> | 1705 </para> |
1706 | 1706 |
1707 <para>One use for this hook is to disable the ability to commit | 1707 <para id="x_2b3">One use for this hook is to disable the ability to commit |
1708 new changesets, while still allowing incoming changesets. | 1708 new changesets, while still allowing incoming changesets. |
1709 Another is to run a build or test, and only allow the commit | 1709 Another is to run a build or test, and only allow the commit |
1710 to begin if the build or test succeeds. | 1710 to begin if the build or test succeeds. |
1711 </para> | 1711 </para> |
1712 | 1712 |
1713 <para>Parameters to this hook: | 1713 <para id="x_2b4">Parameters to this hook: |
1714 </para> | 1714 </para> |
1715 <itemizedlist> | 1715 <itemizedlist> |
1716 <listitem><para><literal>parent1</literal>: A changeset ID. | 1716 <listitem><para id="x_2b5"><literal>parent1</literal>: A changeset ID. |
1717 The changeset ID of the first parent of the working | 1717 The changeset ID of the first parent of the working |
1718 directory. | 1718 directory. |
1719 </para> | 1719 </para> |
1720 </listitem> | 1720 </listitem> |
1721 <listitem><para><literal>parent2</literal>: A changeset ID. | 1721 <listitem><para id="x_2b6"><literal>parent2</literal>: A changeset ID. |
1722 The changeset ID of the second parent of the working | 1722 The changeset ID of the second parent of the working |
1723 directory. | 1723 directory. |
1724 </para> | 1724 </para> |
1725 </listitem></itemizedlist> | 1725 </listitem></itemizedlist> |
1726 <para>If the commit proceeds, the parents of the working | 1726 <para id="x_2b7">If the commit proceeds, the parents of the working |
1727 directory will become the parents of the new changeset. | 1727 directory will become the parents of the new changeset. |
1728 </para> | 1728 </para> |
1729 | 1729 |
1730 <para>See also: <literal role="hook">commit</literal> (section | 1730 <para id="x_2b8">See also: <literal role="hook">commit</literal> |
1731 <xref linkend="sec.hook.commit"/>), <literal | 1731 (<xref linkend="sec:hook:commit"/>), <literal |
1732 role="hook">pretxncommit</literal> (section <xref | 1732 role="hook">pretxncommit</literal> (<xref |
1733 linkend="sec.hook.pretxncommit"/>) | 1733 linkend="sec:hook:pretxncommit"/>) |
1734 </para> | 1734 </para> |
1735 | 1735 |
1736 </sect2> | 1736 </sect2> |
1737 <sect2 id="sec.hook.preoutgoing"> | 1737 <sect2 id="sec:hook:preoutgoing"> |
1738 <title><literal role="hook">preoutgoing</literal>&emdash;before | 1738 <title><literal role="hook">preoutgoing</literal>&emdash;before |
1739 starting to propagate changesets</title> | 1739 starting to propagate changesets</title> |
1740 | 1740 |
1741 <para>This hook is invoked before Mercurial knows the identities | 1741 <para id="x_2b9">This hook is invoked before Mercurial knows the identities |
1742 of the changesets to be transmitted. | 1742 of the changesets to be transmitted. |
1743 </para> | 1743 </para> |
1744 | 1744 |
1745 <para>One use for this hook is to prevent changes from being | 1745 <para id="x_2ba">One use for this hook is to prevent changes from being |
1746 transmitted to another repository. | 1746 transmitted to another repository. |
1747 </para> | 1747 </para> |
1748 | 1748 |
1749 <para>Parameters to this hook: | 1749 <para id="x_2bb">Parameters to this hook: |
1750 </para> | 1750 </para> |
1751 <itemizedlist> | 1751 <itemizedlist> |
1752 <listitem><para><literal>source</literal>: A string. The | 1752 <listitem><para id="x_2bc"><literal>source</literal>: A |
1753 source of the operation that is attempting to obtain | 1753 string. The source of the operation that is attempting to |
1754 changes from this repository (see section <xref | 1754 obtain changes from this repository (see <xref |
1755 linkend="sec.hook.sources"/>). See the documentation | 1755 linkend="sec:hook:sources"/>). See the documentation |
1756 for the <literal>source</literal> parameter to the | 1756 for the <literal>source</literal> parameter to the |
1757 <literal role="hook">outgoing</literal> hook, in section | 1757 <literal role="hook">outgoing</literal> hook, in |
1758 <xref linkend="sec.hook.outgoing"/>, for possible values | 1758 <xref linkend="sec:hook:outgoing"/>, for possible values |
1759 of | 1759 of this parameter. |
1760 this parameter. | 1760 </para> |
1761 </para> | 1761 </listitem> |
1762 </listitem> | 1762 <listitem><para id="x_2bd"><literal>url</literal>: A URL. The |
1763 <listitem><para><literal>url</literal>: A URL. The location | 1763 location of the remote repository, if known. See <xref |
1764 of the remote repository, if known. See section <xref | 1764 linkend="sec:hook:url"/> for more information. |
1765 linkend="sec.hook.url"/> for more | |
1766 information. | |
1767 </para> | 1765 </para> |
1768 </listitem></itemizedlist> | 1766 </listitem></itemizedlist> |
1769 | 1767 |
1770 <para>See also: <literal role="hook">outgoing</literal> (section | 1768 <para id="x_2be">See also: <literal |
1771 <xref linkend="sec.hook.outgoing"/>) | 1769 role="hook">outgoing</literal> (<xref |
1772 </para> | 1770 linkend="sec:hook:outgoing"/>) |
1773 | 1771 </para> |
1774 </sect2> | 1772 |
1775 <sect2 id="sec.hook.pretag"> | 1773 </sect2> |
1774 <sect2 id="sec:hook:pretag"> | |
1776 <title><literal role="hook">pretag</literal>&emdash;before | 1775 <title><literal role="hook">pretag</literal>&emdash;before |
1777 tagging a changeset</title> | 1776 tagging a changeset</title> |
1778 | 1777 |
1779 <para>This controlling hook is run before a tag is created. If | 1778 <para id="x_2bf">This controlling hook is run before a tag is created. If |
1780 the hook succeeds, creation of the tag proceeds. If the hook | 1779 the hook succeeds, creation of the tag proceeds. If the hook |
1781 fails, the tag is not created. | 1780 fails, the tag is not created. |
1782 </para> | 1781 </para> |
1783 | 1782 |
1784 <para>Parameters to this hook: | 1783 <para id="x_2c0">Parameters to this hook: |
1785 </para> | 1784 </para> |
1786 <itemizedlist> | 1785 <itemizedlist> |
1787 <listitem><para><literal>local</literal>: A boolean. Whether | 1786 <listitem><para id="x_2c1"><literal>local</literal>: A boolean. Whether |
1788 the tag is local to this repository instance (i.e. stored | 1787 the tag is local to this repository instance (i.e. stored |
1789 in <filename role="special">.hg/localtags</filename>) or | 1788 in <filename role="special">.hg/localtags</filename>) or |
1790 managed by Mercurial (stored in <filename | 1789 managed by Mercurial (stored in <filename |
1791 role="special">.hgtags</filename>). | 1790 role="special">.hgtags</filename>). |
1792 </para> | 1791 </para> |
1793 </listitem> | 1792 </listitem> |
1794 <listitem><para><literal>node</literal>: A changeset ID. The | 1793 <listitem><para id="x_2c2"><literal>node</literal>: A changeset ID. The |
1795 ID of the changeset to be tagged. | 1794 ID of the changeset to be tagged. |
1796 </para> | 1795 </para> |
1797 </listitem> | 1796 </listitem> |
1798 <listitem><para><literal>tag</literal>: A string. The name of | 1797 <listitem><para id="x_2c3"><literal>tag</literal>: A string. The name of |
1799 the tag to be created. | 1798 the tag to be created. |
1800 </para> | 1799 </para> |
1801 </listitem></itemizedlist> | 1800 </listitem></itemizedlist> |
1802 | 1801 |
1803 <para>If the tag to be created is revision-controlled, the | 1802 <para id="x_2c4">If the tag to be created is |
1804 <literal role="hook">precommit</literal> and <literal | 1803 revision-controlled, the <literal |
1805 role="hook">pretxncommit</literal> hooks (sections <xref | 1804 role="hook">precommit</literal> and <literal |
1806 linkend="sec.hook.commit"/> and <xref | 1805 role="hook">pretxncommit</literal> hooks (<xref |
1807 linkend="sec.hook.pretxncommit"/>) will also be run. | 1806 linkend="sec:hook:commit"/> and <xref |
1808 </para> | 1807 linkend="sec:hook:pretxncommit"/>) will also be run. |
1809 | 1808 </para> |
1810 <para>See also: <literal role="hook">tag</literal> (section | 1809 |
1811 <xref linkend="sec.hook.tag"/>) | 1810 <para id="x_2c5">See also: <literal role="hook">tag</literal> |
1812 </para> | 1811 (<xref linkend="sec:hook:tag"/>) |
1813 </sect2> | 1812 </para> |
1814 <sect2 id="sec.hook.pretxnchangegroup"> | 1813 </sect2> |
1814 <sect2 id="sec:hook:pretxnchangegroup"> | |
1815 <title><literal | 1815 <title><literal |
1816 role="hook">pretxnchangegroup</literal>&emdash;before | 1816 role="hook">pretxnchangegroup</literal>&emdash;before |
1817 completing addition of remote changesets</title> | 1817 completing addition of remote changesets</title> |
1818 | 1818 |
1819 <para>This controlling hook is run before a | 1819 <para id="x_2c6">This controlling hook is run before a |
1820 transaction&emdash;that manages the addition of a group of new | 1820 transaction&emdash;that manages the addition of a group of new |
1821 changesets from outside the repository&emdash;completes. If | 1821 changesets from outside the repository&emdash;completes. If |
1822 the hook succeeds, the transaction completes, and all of the | 1822 the hook succeeds, the transaction completes, and all of the |
1823 changesets become permanent within this repository. If the | 1823 changesets become permanent within this repository. If the |
1824 hook fails, the transaction is rolled back, and the data for | 1824 hook fails, the transaction is rolled back, and the data for |
1825 the changesets is erased. | 1825 the changesets is erased. |
1826 </para> | 1826 </para> |
1827 | 1827 |
1828 <para>This hook can access the metadata associated with the | 1828 <para id="x_2c7">This hook can access the metadata associated with the |
1829 almost-added changesets, but it should not do anything | 1829 almost-added changesets, but it should not do anything |
1830 permanent with this data. It must also not modify the working | 1830 permanent with this data. It must also not modify the working |
1831 directory. | 1831 directory. |
1832 </para> | 1832 </para> |
1833 | 1833 |
1834 <para>While this hook is running, if other Mercurial processes | 1834 <para id="x_2c8">While this hook is running, if other Mercurial processes |
1835 access this repository, they will be able to see the | 1835 access this repository, they will be able to see the |
1836 almost-added changesets as if they are permanent. This may | 1836 almost-added changesets as if they are permanent. This may |
1837 lead to race conditions if you do not take steps to avoid | 1837 lead to race conditions if you do not take steps to avoid |
1838 them. | 1838 them. |
1839 </para> | 1839 </para> |
1840 | 1840 |
1841 <para>This hook can be used to automatically vet a group of | 1841 <para id="x_2c9">This hook can be used to automatically vet a group of |
1842 changesets. If the hook fails, all of the changesets are | 1842 changesets. If the hook fails, all of the changesets are |
1843 <quote>rejected</quote> when the transaction rolls back. | 1843 <quote>rejected</quote> when the transaction rolls back. |
1844 </para> | 1844 </para> |
1845 | 1845 |
1846 <para>Parameters to this hook: | 1846 <para id="x_2ca">Parameters to this hook: |
1847 </para> | 1847 </para> |
1848 <itemizedlist> | 1848 <itemizedlist> |
1849 <listitem><para><literal>node</literal>: A changeset ID. The | 1849 <listitem><para id="x_2cb"><literal>node</literal>: A changeset ID. The |
1850 changeset ID of the first changeset in the group that was | 1850 changeset ID of the first changeset in the group that was |
1851 added. All changesets between this and | 1851 added. All changesets between this and |
1852 <literal role="tag">tip</literal>, | 1852 <literal role="tag">tip</literal>, |
1853 inclusive, were added by a single <command | 1853 inclusive, were added by a single <command |
1854 role="hg-cmd">hg pull</command>, <command | 1854 role="hg-cmd">hg pull</command>, <command |
1855 role="hg-cmd">hg push</command> or <command | 1855 role="hg-cmd">hg push</command> or <command |
1856 role="hg-cmd">hg unbundle</command>. | 1856 role="hg-cmd">hg unbundle</command>. |
1857 </para> | 1857 </para> |
1858 </listitem> | 1858 </listitem> |
1859 <listitem><para><literal>source</literal>: A string. The | 1859 <listitem><para id="x_2cc"><literal>source</literal>: A |
1860 source of these changes. See section <xref | 1860 string. The source of these changes. See <xref |
1861 linkend="sec.hook.sources"/> for details. | 1861 linkend="sec:hook:sources"/> for details. |
1862 </para> | 1862 </para> |
1863 </listitem> | 1863 </listitem> |
1864 <listitem><para><literal>url</literal>: A URL. The location | 1864 <listitem><para id="x_2cd"><literal>url</literal>: A URL. The |
1865 of the remote repository, if known. See section <xref | 1865 location of the remote repository, if known. See <xref |
1866 linkend="sec.hook.url"/> for more | 1866 linkend="sec:hook:url"/> for more information. |
1867 information. | |
1868 </para> | 1867 </para> |
1869 </listitem></itemizedlist> | 1868 </listitem></itemizedlist> |
1870 | 1869 |
1871 <para>See also: <literal role="hook">changegroup</literal> | 1870 <para id="x_2ce">See also: <literal |
1872 (section <xref linkend="sec.hook.changegroup"/>), <literal | 1871 role="hook">changegroup</literal> (<xref |
1873 role="hook">incoming</literal> (section <xref | 1872 linkend="sec:hook:changegroup"/>), <literal |
1874 linkend="sec.hook.incoming"/>), <literal | 1873 role="hook">incoming</literal> (<xref |
1875 role="hook">prechangegroup</literal> (section <xref | 1874 linkend="sec:hook:incoming"/>), <literal |
1876 linkend="sec.hook.prechangegroup"/>) | 1875 role="hook">prechangegroup</literal> (<xref |
1877 </para> | 1876 linkend="sec:hook:prechangegroup"/>) |
1878 | 1877 </para> |
1879 </sect2> | 1878 |
1880 <sect2 id="sec.hook.pretxncommit"> | 1879 </sect2> |
1880 <sect2 id="sec:hook:pretxncommit"> | |
1881 <title><literal role="hook">pretxncommit</literal>&emdash;before | 1881 <title><literal role="hook">pretxncommit</literal>&emdash;before |
1882 completing commit of new changeset</title> | 1882 completing commit of new changeset</title> |
1883 | 1883 |
1884 <para>This controlling hook is run before a | 1884 <para id="x_2cf">This controlling hook is run before a |
1885 transaction&emdash;that manages a new commit&emdash;completes. | 1885 transaction&emdash;that manages a new commit&emdash;completes. |
1886 If the hook succeeds, the transaction completes and the | 1886 If the hook succeeds, the transaction completes and the |
1887 changeset becomes permanent within this repository. If the | 1887 changeset becomes permanent within this repository. If the |
1888 hook fails, the transaction is rolled back, and the commit | 1888 hook fails, the transaction is rolled back, and the commit |
1889 data is erased. | 1889 data is erased. |
1890 </para> | 1890 </para> |
1891 | 1891 |
1892 <para>This hook can access the metadata associated with the | 1892 <para id="x_2d0">This hook can access the metadata associated with the |
1893 almost-new changeset, but it should not do anything permanent | 1893 almost-new changeset, but it should not do anything permanent |
1894 with this data. It must also not modify the working | 1894 with this data. It must also not modify the working |
1895 directory. | 1895 directory. |
1896 </para> | 1896 </para> |
1897 | 1897 |
1898 <para>While this hook is running, if other Mercurial processes | 1898 <para id="x_2d1">While this hook is running, if other Mercurial processes |
1899 access this repository, they will be able to see the | 1899 access this repository, they will be able to see the |
1900 almost-new changeset as if it is permanent. This may lead to | 1900 almost-new changeset as if it is permanent. This may lead to |
1901 race conditions if you do not take steps to avoid them. | 1901 race conditions if you do not take steps to avoid them. |
1902 </para> | 1902 </para> |
1903 | 1903 |
1904 <para>Parameters to this hook: | 1904 <para id="x_2d2">Parameters to this hook: |
1905 </para> | 1905 </para> |
1906 <itemizedlist> | 1906 <itemizedlist> |
1907 <listitem><para><literal>node</literal>: A changeset ID. The | 1907 <listitem><para id="x_2d3"><literal>node</literal>: A changeset ID. The |
1908 changeset ID of the newly committed changeset. | 1908 changeset ID of the newly committed changeset. |
1909 </para> | 1909 </para> |
1910 </listitem> | 1910 </listitem> |
1911 <listitem><para><literal>parent1</literal>: A changeset ID. | 1911 <listitem><para id="x_2d4"><literal>parent1</literal>: A changeset ID. |
1912 The changeset ID of the first parent of the newly | 1912 The changeset ID of the first parent of the newly |
1913 committed changeset. | 1913 committed changeset. |
1914 </para> | 1914 </para> |
1915 </listitem> | 1915 </listitem> |
1916 <listitem><para><literal>parent2</literal>: A changeset ID. | 1916 <listitem><para id="x_2d5"><literal>parent2</literal>: A changeset ID. |
1917 The changeset ID of the second parent of the newly | 1917 The changeset ID of the second parent of the newly |
1918 committed changeset. | 1918 committed changeset. |
1919 </para> | 1919 </para> |
1920 </listitem></itemizedlist> | 1920 </listitem></itemizedlist> |
1921 | 1921 |
1922 <para>See also: <literal role="hook">precommit</literal> | 1922 <para id="x_2d6">See also: <literal |
1923 (section <xref linkend="sec.hook.precommit"/>) | 1923 role="hook">precommit</literal> (<xref |
1924 </para> | 1924 linkend="sec:hook:precommit"/>) |
1925 | 1925 </para> |
1926 </sect2> | 1926 |
1927 <sect2 id="sec.hook.preupdate"> | 1927 </sect2> |
1928 <sect2 id="sec:hook:preupdate"> | |
1928 <title><literal role="hook">preupdate</literal>&emdash;before | 1929 <title><literal role="hook">preupdate</literal>&emdash;before |
1929 updating or merging working directory</title> | 1930 updating or merging working directory</title> |
1930 | 1931 |
1931 <para>This controlling hook is run before an update or merge of | 1932 <para id="x_2d7">This controlling hook is run before an update |
1932 the working directory begins. It is run only if Mercurial's | 1933 or merge of the working directory begins. It is run only if |
1933 normal pre-update checks determine that the update or merge | 1934 Mercurial's normal pre-update checks determine that the update |
1934 can proceed. If the hook succeeds, the update or merge may | 1935 or merge can proceed. If the hook succeeds, the update or |
1935 proceed; if it fails, the update or merge does not start. | 1936 merge may proceed; if it fails, the update or merge does not |
1936 </para> | 1937 start. |
1937 | 1938 </para> |
1938 <para>Parameters to this hook: | 1939 |
1940 <para id="x_2d8">Parameters to this hook: | |
1939 </para> | 1941 </para> |
1940 <itemizedlist> | 1942 <itemizedlist> |
1941 <listitem><para><literal>parent1</literal>: A changeset ID. | 1943 <listitem><para id="x_2d9"><literal>parent1</literal>: A |
1942 The ID of the parent that the working directory is to be | 1944 changeset ID. The ID of the parent that the working |
1943 updated to. If the working directory is being merged, it | 1945 directory is to be updated to. If the working directory |
1944 will not change this parent. | 1946 is being merged, it will not change this parent. |
1945 </para> | 1947 </para> |
1946 </listitem> | 1948 </listitem> |
1947 <listitem><para><literal>parent2</literal>: A changeset ID. | 1949 <listitem><para id="x_2da"><literal>parent2</literal>: A |
1948 Only set if the working directory is being merged. The ID | 1950 changeset ID. Only set if the working directory is being |
1949 of the revision that the working directory is being merged | 1951 merged. The ID of the revision that the working directory |
1950 with. | 1952 is being merged with. |
1951 </para> | 1953 </para> |
1952 </listitem></itemizedlist> | 1954 </listitem></itemizedlist> |
1953 | 1955 |
1954 <para>See also: <literal role="hook">update</literal> (section | 1956 <para id="x_2db">See also: <literal role="hook">update</literal> |
1955 <xref linkend="sec.hook.update"/>) | 1957 (<xref linkend="sec:hook:update"/>)</para> |
1956 </para> | 1958 |
1957 | 1959 </sect2> |
1958 </sect2> | 1960 <sect2 id="sec:hook:tag"> |
1959 <sect2 id="sec.hook.tag"> | |
1960 <title><literal role="hook">tag</literal>&emdash;after tagging a | 1961 <title><literal role="hook">tag</literal>&emdash;after tagging a |
1961 changeset</title> | 1962 changeset</title> |
1962 | 1963 |
1963 <para>This hook is run after a tag has been created. | 1964 <para id="x_2dc">This hook is run after a tag has been created. |
1964 </para> | 1965 </para> |
1965 | 1966 |
1966 <para>Parameters to this hook: | 1967 <para id="x_2dd">Parameters to this hook: |
1967 </para> | 1968 </para> |
1968 <itemizedlist> | 1969 <itemizedlist> |
1969 <listitem><para><literal>local</literal>: A boolean. Whether | 1970 <listitem><para id="x_2de"><literal>local</literal>: A boolean. Whether |
1970 the new tag is local to this repository instance (i.e. | 1971 the new tag is local to this repository instance (i.e. |
1971 stored in <filename | 1972 stored in <filename |
1972 role="special">.hg/localtags</filename>) or managed by | 1973 role="special">.hg/localtags</filename>) or managed by |
1973 Mercurial (stored in <filename | 1974 Mercurial (stored in <filename |
1974 role="special">.hgtags</filename>). | 1975 role="special">.hgtags</filename>). |
1975 </para> | 1976 </para> |
1976 </listitem> | 1977 </listitem> |
1977 <listitem><para><literal>node</literal>: A changeset ID. The | 1978 <listitem><para id="x_2df"><literal>node</literal>: A changeset ID. The |
1978 ID of the changeset that was tagged. | 1979 ID of the changeset that was tagged. |
1979 </para> | 1980 </para> |
1980 </listitem> | 1981 </listitem> |
1981 <listitem><para><literal>tag</literal>: A string. The name of | 1982 <listitem><para id="x_2e0"><literal>tag</literal>: A string. The name of |
1982 the tag that was created. | 1983 the tag that was created. |
1983 </para> | 1984 </para> |
1984 </listitem></itemizedlist> | 1985 </listitem></itemizedlist> |
1985 | 1986 |
1986 <para>If the created tag is revision-controlled, the <literal | 1987 <para id="x_2e1">If the created tag is revision-controlled, the <literal |
1987 role="hook">commit</literal> hook (section <xref | 1988 role="hook">commit</literal> hook (section <xref |
1988 linkend="sec.hook.commit"/>) is run before this hook. | 1989 linkend="sec:hook:commit"/>) is run before this hook. |
1989 </para> | 1990 </para> |
1990 | 1991 |
1991 <para>See also: <literal role="hook">pretag</literal> (section | 1992 <para id="x_2e2">See also: <literal role="hook">pretag</literal> |
1992 <xref linkend="sec.hook.pretag"/>) | 1993 (<xref linkend="sec:hook:pretag"/>) |
1993 </para> | 1994 </para> |
1994 | 1995 |
1995 </sect2> | 1996 </sect2> |
1996 <sect2 id="sec.hook.update"> | 1997 <sect2 id="sec:hook:update"> |
1997 <title><literal role="hook">update</literal>&emdash;after | 1998 <title><literal role="hook">update</literal>&emdash;after |
1998 updating or merging working directory</title> | 1999 updating or merging working directory</title> |
1999 | 2000 |
2000 <para>This hook is run after an update or merge of the working | 2001 <para id="x_2e3">This hook is run after an update or merge of the working |
2001 directory completes. Since a merge can fail (if the external | 2002 directory completes. Since a merge can fail (if the external |
2002 <command>hgmerge</command> command fails to resolve conflicts | 2003 <command>hgmerge</command> command fails to resolve conflicts |
2003 in a file), this hook communicates whether the update or merge | 2004 in a file), this hook communicates whether the update or merge |
2004 completed cleanly. | 2005 completed cleanly. |
2005 </para> | 2006 </para> |
2006 | 2007 |
2007 <itemizedlist> | 2008 <itemizedlist> |
2008 <listitem><para><literal>error</literal>: A boolean. | 2009 <listitem><para id="x_2e4"><literal>error</literal>: A boolean. |
2009 Indicates whether the update or merge completed | 2010 Indicates whether the update or merge completed |
2010 successfully. | 2011 successfully. |
2011 </para> | 2012 </para> |
2012 </listitem> | 2013 </listitem> |
2013 <listitem><para><literal>parent1</literal>: A changeset ID. | 2014 <listitem><para id="x_2e5"><literal>parent1</literal>: A changeset ID. |
2014 The ID of the parent that the working directory was | 2015 The ID of the parent that the working directory was |
2015 updated to. If the working directory was merged, it will | 2016 updated to. If the working directory was merged, it will |
2016 not have changed this parent. | 2017 not have changed this parent. |
2017 </para> | 2018 </para> |
2018 </listitem> | 2019 </listitem> |
2019 <listitem><para><literal>parent2</literal>: A changeset ID. | 2020 <listitem><para id="x_2e6"><literal>parent2</literal>: A changeset ID. |
2020 Only set if the working directory was merged. The ID of | 2021 Only set if the working directory was merged. The ID of |
2021 the revision that the working directory was merged with. | 2022 the revision that the working directory was merged with. |
2022 </para> | 2023 </para> |
2023 </listitem></itemizedlist> | 2024 </listitem></itemizedlist> |
2024 | 2025 |
2025 <para>See also: <literal role="hook">preupdate</literal> | 2026 <para id="x_2e7">See also: <literal role="hook">preupdate</literal> |
2026 (section <xref linkend="sec.hook.preupdate"/>) | 2027 (<xref linkend="sec:hook:preupdate"/>) |
2027 </para> | 2028 </para> |
2028 | 2029 |
2029 </sect2> | 2030 </sect2> |
2030 </sect1> | 2031 </sect1> |
2031 </chapter> | 2032 </chapter> |