hgbook

annotate en/hook.tex @ 134:b727a63518d4

find changesets by author, revision, files, or words in the commit message
Minor updates to race description.
author Bryan O'Sullivan <bos@serpentine.com>
date Fri Jul 21 22:42:19 2006 -0700 (2006-07-21)
parents d1a3394f8bcf
children 0707489b90fd
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: