rev |
line source |
bos@34
|
1 \chapter{Handling repository events with hooks}
|
bos@34
|
2 \label{chap:hook}
|
bos@34
|
3
|
bos@34
|
4 Mercurial offers a powerful mechanism to let you perform automated
|
bos@34
|
5 actions in response to events that occur in a repository. In some
|
bos@34
|
6 cases, you can even control Mercurial's response to those events.
|
bos@34
|
7
|
bos@34
|
8 The name Mercurial uses for one of these actions is a \emph{hook}.
|
bos@34
|
9 Hooks are called ``triggers'' in some revision control systems, but
|
bos@34
|
10 the two names refer to the same idea.
|
bos@34
|
11
|
bos@38
|
12 \section{An overview of hooks in Mercurial}
|
bos@38
|
13
|
bos@41
|
14 Here is a brief list of the hooks that Mercurial supports. We will
|
bos@41
|
15 revisit each of these hooks in more detail later, in
|
bos@41
|
16 section~\ref{sec:hook:ref}.
|
bos@41
|
17
|
bos@38
|
18 \begin{itemize}
|
bos@38
|
19 \item[\small\hook{changegroup}] This is run after a group of
|
bos@41
|
20 changesets has been brought into the repository from elsewhere.
|
bos@38
|
21 \item[\small\hook{commit}] This is run after a new changeset has been
|
bos@41
|
22 created in the local repository.
|
bos@38
|
23 \item[\small\hook{incoming}] This is run once for each new changeset
|
bos@38
|
24 that is brought into the repository from elsewhere. Notice the
|
bos@38
|
25 difference from \hook{changegroup}, which is run once per
|
bos@41
|
26 \emph{group} of changesets brought in.
|
bos@38
|
27 \item[\small\hook{outgoing}] This is run after a group of changesets
|
bos@41
|
28 has been transmitted from this repository.
|
bos@38
|
29 \item[\small\hook{prechangegroup}] This is run before starting to
|
bos@41
|
30 bring a group of changesets into the repository.
|
bos@41
|
31 \item[\small\hook{precommit}] Controlling. This is run before starting
|
bos@41
|
32 a commit.
|
bos@41
|
33 \item[\small\hook{preoutgoing}] Controlling. This is run before
|
bos@41
|
34 starting to transmit a group of changesets from this repository.
|
bos@41
|
35 \item[\small\hook{pretag}] Controlling. This is run before creating a tag.
|
bos@41
|
36 \item[\small\hook{pretxnchangegroup}] Controlling. This is run after a
|
bos@41
|
37 group of changesets has been brought into the local repository from
|
bos@41
|
38 another, but before the transaction completes that will make the
|
bos@41
|
39 changes permanent in the repository.
|
bos@41
|
40 \item[\small\hook{pretxncommit}] Controlling. This is run after a new
|
bos@41
|
41 changeset has been created in the local repository, but before the
|
bos@41
|
42 transaction completes that will make it permanent.
|
bos@41
|
43 \item[\small\hook{preupdate}] Controlling. This is run before starting
|
bos@41
|
44 an update or merge of the working directory.
|
bos@38
|
45 \item[\small\hook{tag}] This is run after a tag is created.
|
bos@38
|
46 \item[\small\hook{update}] This is run after an update or merge of the
|
bos@38
|
47 working directory has finished.
|
bos@38
|
48 \end{itemize}
|
bos@41
|
49 Each of the hooks whose description begins with the word
|
bos@41
|
50 ``Controlling'' has the ability to determine whether an activity can
|
bos@41
|
51 proceed. If the hook succeeds, the activity may proceed; if it fails,
|
bos@41
|
52 the activity is either not permitted or undone, depending on the hook.
|
bos@38
|
53
|
bos@38
|
54 \section{Hooks and security}
|
bos@38
|
55
|
bos@38
|
56 \subsection{Hooks are run with your privileges}
|
bos@38
|
57
|
bos@38
|
58 When you run a Mercurial command in a repository, and the command
|
bos@41
|
59 causes a hook to run, that hook runs on \emph{your} system, under
|
bos@41
|
60 \emph{your} user account, with \emph{your} privilege level. Since
|
bos@41
|
61 hooks are arbitrary pieces of executable code, you should treat them
|
bos@41
|
62 with an appropriate level of suspicion. Do not install a hook unless
|
bos@41
|
63 you are confident that you know who created it and what it does.
|
bos@38
|
64
|
bos@38
|
65 In some cases, you may be exposed to hooks that you did not install
|
bos@38
|
66 yourself. If you work with Mercurial on an unfamiliar system,
|
bos@38
|
67 Mercurial will run hooks defined in that system's global \hgrc\ file.
|
bos@38
|
68
|
bos@38
|
69 If you are working with a repository owned by another user, Mercurial
|
bos@41
|
70 can run hooks defined in that user's repository, but it will still run
|
bos@41
|
71 them as ``you''. For example, if you \hgcmd{pull} from that
|
bos@41
|
72 repository, and its \sfilename{.hg/hgrc} defines a local
|
bos@41
|
73 \hook{outgoing} hook, that hook will run under your user account, even
|
bos@41
|
74 though you don't own that repository.
|
bos@38
|
75
|
bos@38
|
76 \begin{note}
|
bos@38
|
77 This only applies if you are pulling from a repository on a local or
|
bos@38
|
78 network filesystem. If you're pulling over http or ssh, any
|
bos@41
|
79 \hook{outgoing} hook will run under whatever account is executing
|
bos@41
|
80 the server process, on the server.
|
bos@38
|
81 \end{note}
|
bos@38
|
82
|
bos@38
|
83 XXX To see what hooks are defined in a repository, use the
|
bos@38
|
84 \hgcmdargs{config}{hooks} command. If you are working in one
|
bos@38
|
85 repository, but talking to another that you do not own (e.g.~using
|
bos@38
|
86 \hgcmd{pull} or \hgcmd{incoming}), remember that it is the other
|
bos@38
|
87 repository's hooks you should be checking, not your own.
|
bos@38
|
88
|
bos@38
|
89 \subsection{Hooks do not propagate}
|
bos@38
|
90
|
bos@38
|
91 In Mercurial, hooks are not revision controlled, and do not propagate
|
bos@38
|
92 when you clone, or pull from, a repository. The reason for this is
|
bos@38
|
93 simple: a hook is a completely arbitrary piece of executable code. It
|
bos@38
|
94 runs under your user identity, with your privilege level, on your
|
bos@38
|
95 machine.
|
bos@38
|
96
|
bos@38
|
97 It would be extremely reckless for any distributed revision control
|
bos@38
|
98 system to implement revision-controlled hooks, as this would offer an
|
bos@38
|
99 easily exploitable way to subvert the accounts of users of the
|
bos@38
|
100 revision control system.
|
bos@38
|
101
|
bos@38
|
102 Since Mercurial does not propagate hooks, if you are collaborating
|
bos@38
|
103 with other people on a common project, you should not assume that they
|
bos@38
|
104 are using the same Mercurial hooks as you are, or that theirs are
|
bos@38
|
105 correctly configured. You should document the hooks you expect people
|
bos@38
|
106 to use.
|
bos@38
|
107
|
bos@38
|
108 In a corporate intranet, this is somewhat easier to control, as you
|
bos@38
|
109 can for example provide a ``standard'' installation of Mercurial on an
|
bos@38
|
110 NFS filesystem, and use a site-wide \hgrc\ file to define hooks that
|
bos@38
|
111 all users will see. However, this too has its limits; see below.
|
bos@38
|
112
|
bos@38
|
113 \subsection{Hooks can be overridden}
|
bos@38
|
114
|
bos@38
|
115 Mercurial allows you to override a hook definition by redefining the
|
bos@38
|
116 hook. You can disable it by setting its value to the empty string, or
|
bos@38
|
117 change its behaviour as you wish.
|
bos@38
|
118
|
bos@38
|
119 If you deploy a system-~or site-wide \hgrc\ file that defines some
|
bos@38
|
120 hooks, you should thus understand that your users can disable or
|
bos@38
|
121 override those hooks.
|
bos@38
|
122
|
bos@38
|
123 \subsection{Ensuring that critical hooks are run}
|
bos@38
|
124
|
bos@38
|
125 Sometimes you may want to enforce a policy that you do not want others
|
bos@38
|
126 to be able to work around. For example, you may have a requirement
|
bos@38
|
127 that every changeset must pass a rigorous set of tests. Defining this
|
bos@38
|
128 requirement via a hook in a site-wide \hgrc\ won't work for remote
|
bos@38
|
129 users on laptops, and of course local users can subvert it at will by
|
bos@38
|
130 overriding the hook.
|
bos@38
|
131
|
bos@38
|
132 Instead, you can set up your policies for use of Mercurial so that
|
bos@38
|
133 people are expected to propagate changes through a well-known
|
bos@38
|
134 ``canonical'' server that you have locked down and configured
|
bos@38
|
135 appropriately.
|
bos@38
|
136
|
bos@38
|
137 One way to do this is via a combination of social engineering and
|
bos@38
|
138 technology. Set up a restricted-access account; users can push
|
bos@38
|
139 changes over the network to repositories managed by this account, but
|
bos@38
|
140 they cannot log into the account and run normal shell commands. In
|
bos@38
|
141 this scenario, a user can commit a changeset that contains any old
|
bos@38
|
142 garbage they want.
|
bos@38
|
143
|
bos@38
|
144 When someone pushes a changeset to the server that everyone pulls
|
bos@38
|
145 from, the server will test the changeset before it accepts it as
|
bos@38
|
146 permanent, and reject it if it fails to pass the test suite. If
|
bos@38
|
147 people only pull changes from this filtering server, it will serve to
|
bos@38
|
148 ensure that all changes that people pull have been automatically
|
bos@38
|
149 vetted.
|
bos@38
|
150
|
bos@134
|
151 \section{Care with \texttt{pretxn} hooks in a shared-access repository}
|
bos@41
|
152
|
bos@41
|
153 If you want to use hooks to so some automated work in a repository
|
bos@134
|
154 that a number of people have shared access to, you need to be careful
|
bos@41
|
155 in how you do this.
|
bos@41
|
156
|
bos@41
|
157 Mercurial only locks a repository when it is writing to the
|
bos@41
|
158 repository, and only the parts of Mercurial that write to the
|
bos@41
|
159 repository pay attention to locks. Write locks are necessary to
|
bos@41
|
160 prevent multiple simultaneous writers from scribbling on each other's
|
bos@41
|
161 work, corrupting the repository.
|
bos@41
|
162
|
bos@41
|
163 Because Mercurial is careful with the order in which it reads and
|
bos@41
|
164 writes data, it does not need to acquire a lock when it wants to read
|
bos@41
|
165 data from the repository. The parts of Mercurial that read from the
|
bos@41
|
166 repository never pay attention to locks. This lockless reading scheme
|
bos@41
|
167 greatly increases performance and concurrency.
|
bos@41
|
168
|
bos@41
|
169 With great performance comes a trade-off, though, one which has the
|
bos@41
|
170 potential to cause you trouble unless you're aware of it. To describe
|
bos@41
|
171 this requires a little detail about how Mercurial adds changesets to a
|
bos@41
|
172 repository and reads those changes.
|
bos@41
|
173
|
bos@41
|
174 When Mercurial \emph{writes} metadata, it writes it straight into the
|
bos@41
|
175 destination file. It writes file data first, then manifest data
|
bos@41
|
176 (which contains pointers to the new file data), then changelog data
|
bos@41
|
177 (which contains pointers to the new manifest data). Before the first
|
bos@41
|
178 write to each file, it stores a record of where the end of the file
|
bos@41
|
179 was in its transaction log. If the transaction must be rolled back,
|
bos@41
|
180 Mercurial simply truncates each file back to te size it was before the
|
bos@41
|
181 transaction began.
|
bos@41
|
182
|
bos@41
|
183 When Mercurial \emph{reads} metadata, it reads the changelog first,
|
bos@41
|
184 then everything else. Since a reader will only access parts of the
|
bos@41
|
185 manifest or file metadata that it can see in the changelog, it can
|
bos@41
|
186 never see partially written data.
|
bos@41
|
187
|
bos@41
|
188 Some controlling hooks (\hook{pretxncommit} and
|
bos@41
|
189 \hook{pretxnchangegroup}) run when a transaction is almost complete.
|
bos@41
|
190 All of the metadata has been written, but Mercurial can still roll the
|
bos@41
|
191 transaction back and cause the newly-written data to disappear.
|
bos@41
|
192
|
bos@134
|
193 If one of these hooks runs for long, it opens a window of time during
|
bos@134
|
194 which a reader can see the metadata for changesets that are not yet
|
bos@134
|
195 permanent, and should not be thought of as ``really there''. The
|
bos@134
|
196 longer the hook runs, the longer that window is open.
|
bos@134
|
197
|
bos@134
|
198 \subsection{The problem illustrated}
|
bos@134
|
199
|
bos@134
|
200 In principle, a good use for the \hook{pretxnchangegroup} hook would
|
bos@134
|
201 be to automatically build and test incoming changes before they are
|
bos@134
|
202 accepted into a central repository. This could let you guarantee that
|
bos@134
|
203 nobody can push changes to this repository that ``break the build''.
|
bos@134
|
204 But if a client can pull changes while they're being tested, the
|
bos@134
|
205 usefulness of the test is zero; an unsuspecting someone can pull
|
bos@134
|
206 untested changes, potentially breaking their build.
|
bos@134
|
207
|
bos@134
|
208 The safest technological answer to this challenge is to set up such a
|
bos@134
|
209 ``gatekeeper'' repository as \emph{unidirectional}. Let it take
|
bos@134
|
210 changes pushed in from the outside, but do not allow anyone to pull
|
bos@134
|
211 changes from it (use the \hook{preoutgoing} hook to lock it down).
|
bos@134
|
212 Configure a \hook{changegroup} hook so that if a build or test
|
bos@134
|
213 succeeds, the hook will push the new changes out to another repository
|
bos@134
|
214 that people \emph{can} pull from.
|
bos@134
|
215
|
bos@134
|
216 In practice, putting a centralised bottleneck like this in place is
|
bos@134
|
217 not often a good idea, and transaction visibility has nothing to do
|
bos@134
|
218 with the problem. As the size of a project---and the time it takes to
|
bos@134
|
219 build and test---grows, you rapidly run into a wall with this ``try
|
bos@134
|
220 before you buy'' approach, where you have more changesets to test than
|
bos@134
|
221 time in which to deal with them. The inevitable result is frustration
|
bos@134
|
222 on the part of all involved.
|
bos@134
|
223
|
bos@134
|
224 An approach that scales better is to get people to build and test
|
bos@134
|
225 before they push, then run automated builds and tests centrally
|
bos@134
|
226 \emph{after} a push, to be sure all is well. The advantage of this
|
bos@134
|
227 approach is that it does not impose a limit on the rate at which the
|
bos@134
|
228 repository can accept changes.
|
bos@41
|
229
|
bos@34
|
230 \section{A short tutorial on using hooks}
|
bos@34
|
231 \label{sec:hook:simple}
|
bos@34
|
232
|
bos@34
|
233 It is easy to write a Mercurial hook. Let's start with a hook that
|
bos@34
|
234 runs when you finish a \hgcmd{commit}, and simply prints the hash of
|
bos@34
|
235 the changeset you just created. The hook is called \hook{commit}.
|
bos@34
|
236
|
bos@34
|
237 \begin{figure}[ht]
|
bos@34
|
238 \interaction{hook.simple.init}
|
bos@34
|
239 \caption{A simple hook that runs when a changeset is committed}
|
bos@34
|
240 \label{ex:hook:init}
|
bos@34
|
241 \end{figure}
|
bos@34
|
242
|
bos@34
|
243 All hooks follow the pattern in example~\ref{ex:hook:init}. You add
|
bos@34
|
244 an entry to the \rcsection{hooks} section of your \hgrc\. On the left
|
bos@34
|
245 is the name of the event to trigger on; on the right is the action to
|
bos@34
|
246 take. As you can see, you can run an arbitrary shell command in a
|
bos@34
|
247 hook. Mercurial passes extra information to the hook using
|
bos@34
|
248 environment variables (look for \envar{HG\_NODE} in the example).
|
bos@34
|
249
|
bos@34
|
250 \subsection{Performing multiple actions per event}
|
bos@34
|
251
|
bos@34
|
252 Quite often, you will want to define more than one hook for a
|
bos@34
|
253 particular kind of event, as shown in example~\ref{ex:hook:ext}.
|
bos@34
|
254 Mercurial lets you do this by adding an \emph{extension} to the end of
|
bos@34
|
255 a hook's name. You extend a hook's name by giving the name of the
|
bos@34
|
256 hook, followed by a full stop (the ``\texttt{.}'' character), followed
|
bos@34
|
257 by some more text of your choosing. For example, Mercurial will run
|
bos@34
|
258 both \texttt{commit.foo} and \texttt{commit.bar} when the
|
bos@34
|
259 \texttt{commit} event occurs.
|
bos@34
|
260
|
bos@34
|
261 \begin{figure}[ht]
|
bos@34
|
262 \interaction{hook.simple.ext}
|
bos@34
|
263 \caption{Defining a second \hook{commit} hook}
|
bos@34
|
264 \label{ex:hook:ext}
|
bos@34
|
265 \end{figure}
|
bos@34
|
266
|
bos@34
|
267 To give a well-defined order of execution when there are multiple
|
bos@34
|
268 hooks defined for an event, Mercurial sorts hooks by extension, and
|
bos@34
|
269 executes the hook commands in this sorted order. In the above
|
bos@34
|
270 example, it will execute \texttt{commit.bar} before
|
bos@34
|
271 \texttt{commit.foo}, and \texttt{commit} before both.
|
bos@34
|
272
|
bos@34
|
273 It is a good idea to use a somewhat descriptive extension when you
|
bos@34
|
274 define a new hook. This will help you to remember what the hook was
|
bos@34
|
275 for. If the hook fails, you'll get an error message that contains the
|
bos@34
|
276 hook name and extension, so using a descriptive extension could give
|
bos@34
|
277 you an immediate hint as to why the hook failed (see
|
bos@34
|
278 section~\ref{sec:hook:perm} for an example).
|
bos@34
|
279
|
bos@34
|
280 \subsection{Controlling whether an activity can proceed}
|
bos@34
|
281 \label{sec:hook:perm}
|
bos@34
|
282
|
bos@34
|
283 In our earlier examples, we used the \hook{commit} hook, which is
|
bos@34
|
284 run after a commit has completed. This is one of several Mercurial
|
bos@34
|
285 hooks that run after an activity finishes. Such hooks have no way of
|
bos@34
|
286 influencing the activity itself.
|
bos@34
|
287
|
bos@34
|
288 Mercurial defines a number of events that occur before an activity
|
bos@34
|
289 starts; or after it starts, but before it finishes. Hooks that
|
bos@34
|
290 trigger on these events have the added ability to choose whether the
|
bos@34
|
291 activity can continue, or will abort.
|
bos@34
|
292
|
bos@34
|
293 The \hook{pretxncommit} hook runs after a commit has all but
|
bos@34
|
294 completed. In other words, the metadata representing the changeset
|
bos@34
|
295 has been written out to disk, but the transaction has not yet been
|
bos@34
|
296 allowed to complete. The \hook{pretxncommit} hook has the ability to
|
bos@34
|
297 decide whether the transaction can complete, or must be rolled back.
|
bos@34
|
298
|
bos@34
|
299 If the \hook{pretxncommit} hook exits with a status code of zero, the
|
bos@34
|
300 transaction is allowed to complete; the commit finishes; and the
|
bos@34
|
301 \hook{commit} hook is run. If the \hook{pretxncommit} hook exits with
|
bos@34
|
302 a non-zero status code, the transaction is rolled back; the metadata
|
bos@34
|
303 representing the changeset is erased; and the \hook{commit} hook is
|
bos@34
|
304 not run.
|
bos@34
|
305
|
bos@34
|
306 \begin{figure}[ht]
|
bos@34
|
307 \interaction{hook.simple.pretxncommit}
|
bos@34
|
308 \caption{Using the \hook{pretxncommit} hook to control commits}
|
bos@34
|
309 \label{ex:hook:pretxncommit}
|
bos@34
|
310 \end{figure}
|
bos@34
|
311
|
bos@34
|
312 The hook in example~\ref{ex:hook:pretxncommit} checks that a commit
|
bos@34
|
313 comment contains a bug ID. If it does, the commit can complete. If
|
bos@34
|
314 not, the commit is rolled back.
|
bos@34
|
315
|
bos@37
|
316 \section{Writing your own hooks}
|
bos@37
|
317
|
bos@37
|
318 When you are writing a hook, you might find it useful to run Mercurial
|
bos@37
|
319 either with the \hggopt{-v} option, or the \rcitem{ui}{verbose} config
|
bos@37
|
320 item set to ``true''. When you do so, Mercurial will print a message
|
bos@37
|
321 before it calls each hook.
|
bos@37
|
322
|
bos@37
|
323 \subsection{Choosing how your hook should run}
|
bos@37
|
324 \label{sec:hook:lang}
|
bos@34
|
325
|
bos@34
|
326 You can write a hook either as a normal program---typically a shell
|
bos@37
|
327 script---or as a Python function that is executed within the Mercurial
|
bos@34
|
328 process.
|
bos@34
|
329
|
bos@34
|
330 Writing a hook as an external program has the advantage that it
|
bos@34
|
331 requires no knowledge of Mercurial's internals. You can call normal
|
bos@34
|
332 Mercurial commands to get any added information you need. The
|
bos@34
|
333 trade-off is that external hooks are slower than in-process hooks.
|
bos@34
|
334
|
bos@34
|
335 An in-process Python hook has complete access to the Mercurial API,
|
bos@34
|
336 and does not ``shell out'' to another process, so it is inherently
|
bos@34
|
337 faster than an external hook. It is also easier to obtain much of the
|
bos@34
|
338 information that a hook requires by using the Mercurial API than by
|
bos@34
|
339 running Mercurial commands.
|
bos@34
|
340
|
bos@34
|
341 If you are comfortable with Python, or require high performance,
|
bos@34
|
342 writing your hooks in Python may be a good choice. However, when you
|
bos@34
|
343 have a straightforward hook to write and you don't need to care about
|
bos@34
|
344 performance (probably the majority of hooks), a shell script is
|
bos@34
|
345 perfectly fine.
|
bos@34
|
346
|
bos@37
|
347 \subsection{Hook parameters}
|
bos@34
|
348 \label{sec:hook:param}
|
bos@34
|
349
|
bos@34
|
350 Mercurial calls each hook with a set of well-defined parameters. In
|
bos@34
|
351 Python, a parameter is passed as a keyword argument to your hook
|
bos@34
|
352 function. For an external program, a parameter is passed as an
|
bos@34
|
353 environment variable.
|
bos@34
|
354
|
bos@34
|
355 Whether your hook is written in Python or as a shell script, the
|
bos@37
|
356 hook-specific parameter names and values will be the same. A boolean
|
bos@37
|
357 parameter will be represented as a boolean value in Python, but as the
|
bos@37
|
358 number 1 (for ``true'') or 0 (for ``false'') as an environment
|
bos@37
|
359 variable for an external hook. If a hook parameter is named
|
bos@37
|
360 \texttt{foo}, the keyword argument for a Python hook will also be
|
bos@37
|
361 named \texttt{foo} Python, while the environment variable for an
|
bos@37
|
362 external hook will be named \texttt{HG\_FOO}.
|
bos@37
|
363
|
bos@37
|
364 \subsection{Hook return values and activity control}
|
bos@37
|
365
|
bos@37
|
366 A hook that executes successfully must exit with a status of zero if
|
bos@37
|
367 external, or return boolean ``false'' if in-process. Failure is
|
bos@37
|
368 indicated with a non-zero exit status from an external hook, or an
|
bos@37
|
369 in-process hook returning boolean ``true''. If an in-process hook
|
bos@37
|
370 raises an exception, the hook is considered to have failed.
|
bos@37
|
371
|
bos@37
|
372 For a hook that controls whether an activity can proceed, zero/false
|
bos@37
|
373 means ``allow'', while non-zero/true/exception means ``deny''.
|
bos@37
|
374
|
bos@37
|
375 \subsection{Writing an external hook}
|
bos@37
|
376
|
bos@37
|
377 When you define an external hook in your \hgrc\ and the hook is run,
|
bos@37
|
378 its value is passed to your shell, which interprets it. This means
|
bos@37
|
379 that you can use normal shell constructs in the body of the hook.
|
bos@37
|
380
|
bos@37
|
381 An executable hook is always run with its current directory set to a
|
bos@37
|
382 repository's root directory.
|
bos@37
|
383
|
bos@37
|
384 Each hook parameter is passed in as an environment variable; the name
|
bos@37
|
385 is upper-cased, and prefixed with the string ``\texttt{HG\_}''.
|
bos@37
|
386
|
bos@37
|
387 With the exception of hook parameters, Mercurial does not set or
|
bos@37
|
388 modify any environment variables when running a hook. This is useful
|
bos@37
|
389 to remember if you are writing a site-wide hook that may be run by a
|
bos@37
|
390 number of different users with differing environment variables set.
|
bos@37
|
391 In multi-user situations, you should not rely on environment variables
|
bos@37
|
392 being set to the values you have in your environment when testing the
|
bos@37
|
393 hook.
|
bos@37
|
394
|
bos@37
|
395 \subsection{Telling Mercurial to use an in-process hook}
|
bos@37
|
396
|
bos@37
|
397 The \hgrc\ syntax for defining an in-process hook is slightly
|
bos@37
|
398 different than for an executable hook. The value of the hook must
|
bos@37
|
399 start with the text ``\texttt{python:}'', and continue with the
|
bos@37
|
400 fully-qualified name of a callable object to use as the hook's value.
|
bos@37
|
401
|
bos@37
|
402 The module in which a hook lives is automatically imported when a hook
|
bos@37
|
403 is run. So long as you have the module name and \envar{PYTHONPATH}
|
bos@37
|
404 right, it should ``just work''.
|
bos@37
|
405
|
bos@37
|
406 The following \hgrc\ example snippet illustrates the syntax and
|
bos@37
|
407 meaning of the notions we just described.
|
bos@37
|
408 \begin{codesample2}
|
bos@37
|
409 [hooks]
|
bos@37
|
410 commit.example = python:mymodule.submodule.myhook
|
bos@37
|
411 \end{codesample2}
|
bos@37
|
412 When Mercurial runs the \texttt{commit.example} hook, it imports
|
bos@37
|
413 \texttt{mymodule.submodule}, looks for the callable object named
|
bos@37
|
414 \texttt{myhook}, and calls it.
|
bos@37
|
415
|
bos@37
|
416 \subsection{Writing an in-process hook}
|
bos@37
|
417
|
bos@37
|
418 The simplest in-process hook does nothing, but illustrates the basic
|
bos@37
|
419 shape of the hook API:
|
bos@37
|
420 \begin{codesample2}
|
bos@37
|
421 def myhook(ui, repo, **kwargs):
|
bos@37
|
422 pass
|
bos@37
|
423 \end{codesample2}
|
bos@37
|
424 The first argument to a Python hook is always a
|
bos@37
|
425 \pymodclass{mercurial.ui}{ui} object. The second is a repository object;
|
bos@37
|
426 at the moment, it is always an instance of
|
bos@37
|
427 \pymodclass{mercurial.localrepo}{localrepository}. Following these two
|
bos@37
|
428 arguments are other keyword arguments. Which ones are passed in
|
bos@37
|
429 depends on the hook being called, but a hook can ignore arguments it
|
bos@37
|
430 doesn't care about by dropping them into a keyword argument dict, as
|
bos@37
|
431 with \texttt{**kwargs} above.
|
bos@34
|
432
|
bos@39
|
433 \section{Hook reference}
|
bos@41
|
434 \label{sec:hook:ref}
|
bos@39
|
435
|
bos@39
|
436 \subsection{In-process hook execution}
|
bos@39
|
437
|
bos@39
|
438 An in-process hook is called with arguments of the following form:
|
bos@39
|
439 \begin{codesample2}
|
bos@39
|
440 def myhook(ui, repo, **kwargs):
|
bos@39
|
441 pass
|
bos@39
|
442 \end{codesample2}
|
bos@39
|
443 The \texttt{ui} parameter is a \pymodclass{mercurial.ui}{ui} object.
|
bos@39
|
444 The \texttt{repo} parameter is a
|
bos@39
|
445 \pymodclass{mercurial.localrepo}{localrepository} object. The
|
bos@39
|
446 names and values of the \texttt{**kwargs} parameters depend on the
|
bos@39
|
447 hook being invoked, with the following common features:
|
bos@39
|
448 \begin{itemize}
|
bos@39
|
449 \item If a parameter is named \texttt{node} or
|
bos@39
|
450 \texttt{parent\emph{N}}, it will contain a hexadecimal changeset ID.
|
bos@39
|
451 The empty string is used to represent ``null changeset ID'' instead
|
bos@39
|
452 of a string of zeroes.
|
bos@39
|
453 \item Boolean-valued parameters are represented as Python
|
bos@39
|
454 \texttt{bool} objects.
|
bos@39
|
455 \end{itemize}
|
bos@39
|
456
|
bos@39
|
457 An in-process hook is called without a change to the process's working
|
bos@39
|
458 directory (unlike external hooks, which are run in the root of the
|
bos@39
|
459 repository). It must not change the process's working directory. If
|
bos@39
|
460 it were to do so, it would probably cause calls to the Mercurial API,
|
bos@39
|
461 or operations after the hook finishes, to fail.
|
bos@39
|
462
|
bos@39
|
463 If a hook returns a boolean ``false'' value, it is considered to
|
bos@39
|
464 have succeeded. If it returns a boolean ``true'' value or raises an
|
bos@39
|
465 exception, it is considered to have failed.
|
bos@39
|
466
|
bos@39
|
467 \subsection{External hook execution}
|
bos@39
|
468
|
bos@39
|
469 An external hook is passed to the user's shell for execution, so
|
bos@39
|
470 features of that shell, such as variable substitution and command
|
bos@39
|
471 redirection, are available. The hook is run in the root directory of
|
bos@39
|
472 the repository.
|
bos@39
|
473
|
bos@39
|
474 Hook parameters are passed to the hook as environment variables. Each
|
bos@39
|
475 environment variable's name is converted in upper case and prefixed
|
bos@39
|
476 with the string ``\texttt{HG\_}''. For example, if the name of a
|
bos@39
|
477 parameter is ``\texttt{node}'', the name of the environment variable
|
bos@39
|
478 representing that parameter will be ``\texttt{HG\_NODE}''.
|
bos@39
|
479
|
bos@39
|
480 A boolean parameter is represented as the string ``\texttt{1}'' for
|
bos@39
|
481 ``true'', ``\texttt{0}'' for ``false''. If an environment variable is
|
bos@39
|
482 named \envar{HG\_NODE}, \envar{HG\_PARENT1} or \envar{HG\_PARENT2}, it
|
bos@39
|
483 contains a changeset ID represented as a hexadecimal string. The
|
bos@39
|
484 empty string is used to represent ``null changeset ID'' instead of a
|
bos@39
|
485 string of zeroes.
|
bos@39
|
486
|
bos@39
|
487 If a hook exits with a status of zero, it is considered to have
|
bos@39
|
488 succeeded. If it exits with a non-zero status, it is considered to
|
bos@39
|
489 have failed.
|
bos@39
|
490
|
bos@39
|
491 \subsection{The \hook{changegroup} hook}
|
bos@39
|
492 \label{sec:hook:changegroup}
|
bos@39
|
493
|
bos@40
|
494 This hook is run after a group of pre-existing changesets has been
|
bos@40
|
495 added to the repository, for example via a \hgcmd{pull} or
|
bos@40
|
496 \hgcmd{unbundle}. This hook is run once per operation that added one
|
bos@41
|
497 or more changesets. This is in contrast to the \hook{incoming} hook,
|
bos@41
|
498 which is run once per changeset, regardless of whether the changesets
|
bos@41
|
499 arrive in a group.
|
bos@41
|
500
|
bos@41
|
501 Some possible uses for this hook include kicking off an automated
|
bos@41
|
502 build or test of the added changesets, updating a bug database, or
|
bos@41
|
503 notifying subscribers that a repository contains new changes.
|
bos@40
|
504
|
bos@40
|
505 Parameters to this hook:
|
bos@40
|
506 \begin{itemize}
|
bos@40
|
507 \item[\texttt{node}] A changeset ID. The changeset ID of the first
|
bos@40
|
508 changeset in the group that was added. All changesets between this
|
bos@40
|
509 and \index{tags!\texttt{tip}}\texttt{tip}, inclusive, were added by
|
bos@40
|
510 a single \hgcmd{pull}, \hgcmd{push} or \hgcmd{unbundle}.
|
bos@40
|
511 \end{itemize}
|
bos@40
|
512
|
bos@40
|
513 See also: \hook{incoming} (section~\ref{sec:hook:incoming}),
|
bos@40
|
514 \hook{prechangegroup} (section~\ref{sec:hook:prechangegroup}),
|
bos@40
|
515 \hook{pretxnchangegroup} (section~\ref{sec:hook:pretxnchangegroup})
|
bos@39
|
516
|
bos@39
|
517 \subsection{The \hook{commit} hook}
|
bos@39
|
518 \label{sec:hook:commit}
|
bos@39
|
519
|
bos@40
|
520 This hook is run after a new changeset has been created.
|
bos@40
|
521
|
bos@40
|
522 Parameters to this hook:
|
bos@40
|
523 \begin{itemize}
|
bos@40
|
524 \item[\texttt{node}] A changeset ID. The changeset ID of the newly
|
bos@40
|
525 committed changeset.
|
bos@40
|
526 \item[\texttt{parent1}] A changeset ID. The changeset ID of the first
|
bos@40
|
527 parent of the newly committed changeset.
|
bos@40
|
528 \item[\texttt{parent2}] A changeset ID. The changeset ID of the second
|
bos@40
|
529 parent of the newly committed changeset.
|
bos@40
|
530 \end{itemize}
|
bos@40
|
531
|
bos@40
|
532 See also: \hook{precommit} (section~\ref{sec:hook:precommit}),
|
bos@40
|
533 \hook{pretxncommit} (section~\ref{sec:hook:pretxncommit})
|
bos@40
|
534
|
bos@40
|
535 \subsection{The \hook{incoming} hook}
|
bos@40
|
536 \label{sec:hook:incoming}
|
bos@40
|
537
|
bos@40
|
538 This hook is run after a pre-existing changeset has been added to the
|
bos@40
|
539 repository, for example via a \hgcmd{push}. If a group of changesets
|
bos@40
|
540 was added in a single operation, this hook is called once for each
|
bos@40
|
541 added changeset.
|
bos@40
|
542
|
bos@41
|
543 You can use this hook for the same purposes as the \hook{changegroup}
|
bos@41
|
544 hook (section~\ref{sec:hook:changegroup}); it's simply more convenient
|
bos@41
|
545 sometimes to run a hook once per group of changesets, while othher
|
bos@41
|
546 times it's handier once per changeset.
|
bos@41
|
547
|
bos@40
|
548 Parameters to this hook:
|
bos@40
|
549 \begin{itemize}
|
bos@40
|
550 \item[\texttt{node}] A changeset ID. The ID of the newly added
|
bos@39
|
551 changeset.
|
bos@40
|
552 \end{itemize}
|
bos@40
|
553
|
bos@40
|
554 See also: \hook{changegroup} (section~\ref{sec:hook:changegroup}) \hook{prechangegroup} (section~\ref{sec:hook:prechangegroup}), \hook{pretxnchangegroup} (section~\ref{sec:hook:pretxnchangegroup})
|
bos@40
|
555
|
bos@40
|
556 \subsection{The \hook{outgoing} hook}
|
bos@40
|
557 \label{sec:hook:outgoing}
|
bos@40
|
558
|
bos@40
|
559 This hook is run after a group of changesets has been propagated out
|
bos@40
|
560 of this repository, for example by a \hgcmd{push} or \hgcmd{bundle}
|
bos@40
|
561 command.
|
bos@40
|
562
|
bos@41
|
563 One possible use for this hook is to notify administrators that
|
bos@41
|
564 changes have been pulled.
|
bos@41
|
565
|
bos@40
|
566 Parameters to this hook:
|
bos@40
|
567 \begin{itemize}
|
bos@40
|
568 \item[\texttt{node}] A changeset ID. The changeset ID of the first
|
bos@40
|
569 changeset of the group that was sent.
|
bos@40
|
570 \item[\texttt{source}] A string. The source of the of the operation.
|
bos@40
|
571 If a remote client pulled changes from this repository,
|
bos@40
|
572 \texttt{source} will be \texttt{serve}. If the client that obtained
|
bos@40
|
573 changes from this repository was local, \texttt{source} will be
|
bos@40
|
574 \texttt{bundle}, \texttt{pull}, or \texttt{push}, depending on the
|
bos@40
|
575 operation the client performed.
|
bos@40
|
576 \end{itemize}
|
bos@40
|
577
|
bos@40
|
578 See also: \hook{preoutgoing} (section~\ref{sec:hook:preoutgoing})
|
bos@40
|
579
|
bos@40
|
580 \subsection{The \hook{prechangegroup} hook}
|
bos@40
|
581 \label{sec:hook:prechangegroup}
|
bos@40
|
582
|
bos@41
|
583 This controlling hook is run before Mercurial begins to add a group of
|
bos@41
|
584 changesets from another repository.
|
bos@41
|
585
|
bos@41
|
586 This hook does not have any information about the changesets to be
|
bos@41
|
587 added, because it is run before transmission of those changesets is
|
bos@41
|
588 allowed to begin. If this hook fails, the changesets will not be
|
bos@41
|
589 transmitted.
|
bos@41
|
590
|
bos@41
|
591 One use for this hook is to prevent external changes from being added
|
bos@41
|
592 to a repository, for example to ``freeze'' a server-hosted branch
|
bos@41
|
593 temporarily or permanently.
|
bos@41
|
594
|
bos@40
|
595 This hook is not passed any parameters.
|
bos@40
|
596
|
bos@40
|
597 See also: \hook{changegroup} (section~\ref{sec:hook:changegroup}),
|
bos@40
|
598 \hook{incoming} (section~\ref{sec:hook:incoming}), ,
|
bos@40
|
599 \hook{pretxnchangegroup} (section~\ref{sec:hook:pretxnchangegroup})
|
bos@40
|
600
|
bos@40
|
601 \subsection{The \hook{precommit} hook}
|
bos@40
|
602 \label{sec:hook:precommit}
|
bos@40
|
603
|
bos@41
|
604 This hook is run before Mercurial begins to commit a new changeset.
|
bos@41
|
605 It is run before Mercurial has any of the metadata for the commit,
|
bos@41
|
606 such as the files to be committed, the commit message, or the commit
|
bos@41
|
607 date.
|
bos@41
|
608
|
bos@41
|
609 One use for this hook is to disable the ability to commit new
|
bos@41
|
610 changesets, while still allowing incoming changesets. Another is to
|
bos@41
|
611 run a build or test, and only allow the commit to begin if the build
|
bos@41
|
612 or test succeeds.
|
bos@40
|
613
|
bos@40
|
614 Parameters to this hook:
|
bos@40
|
615 \begin{itemize}
|
bos@40
|
616 \item[\texttt{parent1}] A changeset ID. The changeset ID of the first
|
bos@40
|
617 parent of the working directory.
|
bos@40
|
618 \item[\texttt{parent2}] A changeset ID. The changeset ID of the second
|
bos@40
|
619 parent of the working directory.
|
bos@40
|
620 \end{itemize}
|
bos@40
|
621 If the commit proceeds, the parents of the working directory will
|
bos@40
|
622 become the parents of the new changeset.
|
bos@40
|
623
|
bos@40
|
624 See also: \hook{commit} (section~\ref{sec:hook:commit}),
|
bos@40
|
625 \hook{pretxncommit} (section~\ref{sec:hook:pretxncommit})
|
bos@40
|
626
|
bos@40
|
627 \subsection{The \hook{preoutgoing} hook}
|
bos@40
|
628 \label{sec:hook:preoutgoing}
|
bos@40
|
629
|
bos@40
|
630 This hook is invoked before Mercurial knows the identities of the
|
bos@40
|
631 changesets to be transmitted.
|
bos@40
|
632
|
bos@41
|
633 One use for this hook is to prevent changes from being transmitted to
|
bos@41
|
634 another repository.
|
bos@41
|
635
|
bos@40
|
636 Parameters to this hook:
|
bos@40
|
637 \begin{itemize}
|
bos@40
|
638 \item[\texttt{source}] A string. The source of the operation that is
|
bos@40
|
639 attempting to obtain changes from this repository. See the
|
bos@40
|
640 documentation for the \texttt{source} parameter to the
|
bos@40
|
641 \hook{outgoing} hook, in section~\ref{sec:hook:outgoing}, for
|
bos@40
|
642 possible values of this parameter..
|
bos@40
|
643 \end{itemize}
|
bos@40
|
644
|
bos@40
|
645 See also: \hook{outgoing} (section~\ref{sec:hook:outgoing})
|
bos@40
|
646
|
bos@40
|
647 \subsection{The \hook{pretag} hook}
|
bos@40
|
648 \label{sec:hook:pretag}
|
bos@40
|
649
|
bos@41
|
650 This controlling hook is run before a tag is created. If the hook
|
bos@41
|
651 succeeds, creation of the tag proceeds. If the hook fails, the tag is
|
bos@41
|
652 not created.
|
bos@41
|
653
|
bos@40
|
654 Parameters to this hook:
|
bos@40
|
655 \begin{itemize}
|
bos@40
|
656 \item[\texttt{local}] A boolean. Whether the tag is local to this
|
bos@40
|
657 repository instance (i.e.~stored in \sfilename{.hg/tags}) or managed
|
bos@40
|
658 by Mercurial (stored in \sfilename{.hgtags}).
|
bos@40
|
659 \item[\texttt{node}] A changeset ID. The ID of the changeset to be tagged.
|
bos@40
|
660 \item[\texttt{tag}] A string. The name of the tag to be created.
|
bos@40
|
661 \end{itemize}
|
bos@40
|
662
|
bos@40
|
663 If the tag to be created is revision-controlled, the \hook{precommit}
|
bos@40
|
664 and \hook{pretxncommit} hooks (sections~\ref{sec:hook:commit}
|
bos@40
|
665 and~\ref{sec:hook:pretxncommit}) will also be run.
|
bos@40
|
666
|
bos@40
|
667 See also: \hook{tag} (section~\ref{sec:hook:tag})
|
bos@40
|
668
|
bos@40
|
669 \subsection{The \hook{pretxnchangegroup} hook}
|
bos@40
|
670 \label{sec:hook:pretxnchangegroup}
|
bos@40
|
671
|
bos@41
|
672 This controlling hook is run before a transaction---that manages the
|
bos@41
|
673 addition of a group of new changesets from outside the
|
bos@41
|
674 repository---completes. If the hook succeeds, the transaction
|
bos@41
|
675 completes, and all of the changesets become permanent within this
|
bos@41
|
676 repository. If the hook fails, the transaction is rolled back, and
|
bos@41
|
677 the data for the changesets is erased.
|
bos@41
|
678
|
bos@41
|
679 This hook can access the metadata associated with the almost-added
|
bos@41
|
680 changesets, but it should not do anything permanent with this data.
|
bos@41
|
681 It must also not modify the working directory.
|
bos@41
|
682
|
bos@41
|
683 While this hook is running, if other Mercurial processes access this
|
bos@41
|
684 repository, they will be able to see the almost-added changesets as if
|
bos@41
|
685 they are permanent. This may lead to race conditions if you do not
|
bos@41
|
686 take steps to avoid them.
|
bos@41
|
687
|
bos@41
|
688 This hook can be used to automatically vet a group of changesets. If
|
bos@41
|
689 the hook fails, all of the changesets are ``rejected'' when the
|
bos@41
|
690 transaction rolls back.
|
bos@41
|
691
|
bos@40
|
692 Parameters to this hook are the same as for the \hook{changegroup}
|
bos@40
|
693 hook; see section~\ref{sec:hook:changegroup} for details.
|
bos@40
|
694
|
bos@40
|
695 See also: \hook{changegroup} (section~\ref{sec:hook:changegroup}),
|
bos@40
|
696 \hook{incoming} (section~\ref{sec:hook:incoming}),
|
bos@40
|
697 \hook{prechangegroup} (section~\ref{sec:hook:prechangegroup})
|
bos@40
|
698
|
bos@40
|
699 \subsection{The \hook{pretxncommit} hook}
|
bos@40
|
700 \label{sec:hook:pretxncommit}
|
bos@40
|
701
|
bos@41
|
702 This controlling hook is run before a transaction---that manages a new
|
bos@41
|
703 commit---completes. If the hook succeeds, the transaction completes
|
bos@41
|
704 and the changeset becomes permanent within this repository. If the
|
bos@41
|
705 hook fails, the transaction is rolled back, and the commit data is
|
bos@41
|
706 erased.
|
bos@41
|
707
|
bos@41
|
708 This hook can access the metadata associated with the almost-new
|
bos@41
|
709 changeset, but it should not do anything permanent with this data. It
|
bos@41
|
710 must also not modify the working directory.
|
bos@41
|
711
|
bos@41
|
712 While this hook is running, if other Mercurial processes access this
|
bos@41
|
713 repository, they will be able to see the almost-new changeset as if it
|
bos@41
|
714 is permanent. This may lead to race conditions if you do not take
|
bos@41
|
715 steps to avoid them.
|
bos@41
|
716
|
bos@40
|
717 Parameters to this hook are the same as for the \hook{commit} hook;
|
bos@40
|
718 see section~\ref{sec:hook:commit} for details.
|
bos@40
|
719
|
bos@40
|
720 See also: \hook{precommit} (section~\ref{sec:hook:precommit})
|
bos@40
|
721
|
bos@40
|
722 \subsection{The \hook{preupdate} hook}
|
bos@40
|
723 \label{sec:hook:preupdate}
|
bos@40
|
724
|
bos@41
|
725 This controlling hook is run before an update or merge of the working
|
bos@41
|
726 directory begins. It is run only if Mercurial's normal pre-update
|
bos@41
|
727 checks determine that the update or merge can proceed. If the hook
|
bos@41
|
728 succeeds, the update or merge may proceed; if it fails, the update or
|
bos@41
|
729 merge does not start.
|
bos@41
|
730
|
bos@40
|
731 Parameters to this hook:
|
bos@40
|
732 \begin{itemize}
|
bos@40
|
733 \item[\texttt{parent1}] A changeset ID. The ID of the parent that the
|
bos@40
|
734 working directory is to be updated to. If the working directory is
|
bos@40
|
735 being merged, it will not change this parent.
|
bos@40
|
736 \item[\texttt{parent2}] A changeset ID. Only set if the working
|
bos@40
|
737 directory is being merged. The ID of the revision that the working
|
bos@40
|
738 directory is being merged with.
|
bos@40
|
739 \end{itemize}
|
bos@40
|
740
|
bos@40
|
741 See also: \hook{update} (section~\ref{sec:hook:update})
|
bos@40
|
742
|
bos@40
|
743 \subsection{The \hook{tag} hook}
|
bos@40
|
744 \label{sec:hook:tag}
|
bos@40
|
745
|
bos@41
|
746 This hook is run after a tag has been created.
|
bos@41
|
747
|
bos@40
|
748 Parameters to this hook are the same as for the \hook{pretag} hook;
|
bos@40
|
749 see section~\ref{sec:hook:pretag} for details.
|
bos@40
|
750
|
bos@40
|
751 If the created tag is revision-controlled, the \hook{commit} hook
|
bos@41
|
752 (section~\ref{sec:hook:commit}) is run before this hook.
|
bos@40
|
753
|
bos@40
|
754 See also: \hook{pretag} (section~\ref{sec:hook:pretag})
|
bos@40
|
755
|
bos@40
|
756 \subsection{The \hook{update} hook}
|
bos@40
|
757 \label{sec:hook:update}
|
bos@40
|
758
|
bos@41
|
759 This hook is run after an update or merge of the working directory
|
bos@41
|
760 completes. Since a merge can fail (if the external \command{hgmerge}
|
bos@41
|
761 command fails to resolve conflicts in a file), this hook communicates
|
bos@41
|
762 whether the update or merge completed cleanly.
|
bos@41
|
763
|
bos@40
|
764 \begin{itemize}
|
bos@40
|
765 \item[\texttt{error}] A boolean. Indicates whether the update or
|
bos@40
|
766 merge completed successfully.
|
bos@40
|
767 \item[\texttt{parent1}] A changeset ID. The ID of the parent that the
|
bos@40
|
768 working directory was updated to. If the working directory was
|
bos@40
|
769 merged, it will not have changed this parent.
|
bos@40
|
770 \item[\texttt{parent2}] A changeset ID. Only set if the working
|
bos@40
|
771 directory was merged. The ID of the revision that the working
|
bos@40
|
772 directory was merged with.
|
bos@40
|
773 \end{itemize}
|
bos@40
|
774
|
bos@40
|
775 See also: \hook{preupdate} (section~\ref{sec:hook:preupdate})
|
bos@34
|
776
|
bos@34
|
777 %%% Local Variables:
|
bos@34
|
778 %%% mode: latex
|
bos@34
|
779 %%% TeX-master: "00book"
|
bos@34
|
780 %%% End:
|