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