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