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