annotate en/hook.tex @ 51:497aa3c9d4ce

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