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