← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/help_topics/en/hooks.txt

  • Committer: Mark Hammond
  • Date: 2009-01-12 01:55:34 UTC
  • mto: (3995.8.2 prepare-1.12)
  • mto: This revision was merged to the branch mainline in revision 4007.
  • Revision ID: mhammond@skippinet.com.au-20090112015534-yfxg50p7mpds9j4v
Include all .html files from the tortoise doc directory.

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/help_topics/en/hooks.txt
 
1
Hooks
 
2
=====
 
3
 
 
4
Introduction
 
5
------------
 
6
 
 
7
A hook of type *xxx* of class *yyy* needs to be registered using::
 
8
 
 
9
  yyy.hooks.install_named_hook("xxx", ...)
 
10
 
 
11
See `Using hooks`_ in the User Guide for examples.
 
12
 
 
13
.. _Using hooks: ../user-guide/index.html#using-hooks
 
14
 
 
15
The class that contains each hook is given in parentheses immediately
 
16
after each hook type below.
 
17
 
 
18
Each description also indicates whether the hook runs on the client (the
 
19
machine where bzr was invoked) or the server (the machine addressed by
 
20
the branch URL).  These may be, but are not necessarily, the same machine.
 
21
 
 
22
Plugins (including hooks) are run on the server if any of these is true:
 
23
 
 
24
  * The remote branch is on the same machine as the client, and the client
 
25
    has plugins enabled.
 
26
 
 
27
  * The connection is via a smart server (accessed with a URL starting with
 
28
    "bzr://", "bzr+ssh://" or "bzr+http://", or accessed via a "http://"
 
29
    URL when a smart server is available via HTTP), and that server has
 
30
    plugins enabled.
 
31
 
 
32
 
 
33
open (Branch)
 
34
-------------
 
35
 
 
36
Called after a Branch object is opened, with the Branch object.
 
37
Runs on the client and on the server.
 
38
 
 
39
 
 
40
post_push (Branch)
 
41
------------------
 
42
 
 
43
Run after ``push`` has completed.
 
44
Runs on the client.
 
45
 
 
46
The hook signature is (push_result), containing the members
 
47
 
 
48
  source_branch
 
49
    Where the data is being pushed from (read locked).
 
50
    This should be the lowest latency branch.
 
51
 
 
52
  target_branch
 
53
    The direct location where data is being sent (write locked).
 
54
 
 
55
  master_branch
 
56
    Either target_branch, or if the target is a bound branch, it
 
57
    will be the master location (write locked).
 
58
 
 
59
  local_branch
 
60
    If the target is a bound branch, this will be the target
 
61
    branch, else it will be None.
 
62
 
 
63
  old_revno
 
64
    The revision number (eg 10) of the branch before the push.
 
65
 
 
66
  old_revid
 
67
    The revision id (eg joe@foo.com-1234234-aoeua34) before the push.
 
68
 
 
69
  new_revno
 
70
    The revision number (eg 12) of the branch after the push.
 
71
 
 
72
  new_revid
 
73
    The revision id (eg joe@foo.com-5676566-boa234a) after the push.
 
74
 
 
75
 
 
76
post_pull (Branch)
 
77
------------------
 
78
 
 
79
Run after ``pull`` has completed.
 
80
Runs on the client.
 
81
 
 
82
The hook signature is (push_result) containing the members
 
83
(source, local, master, old_revno, old_revid, new_revno, new_revid)
 
84
where local is the local target branch or None, master is the target 
 
85
master branch, and the rest should be self explanatory. The source
 
86
is read-locked and the target branches are write-locked. Source will
 
87
be the local low-latency branch.
 
88
 
 
89
 
 
90
start_commit (MutableTree)
 
91
--------------------------
 
92
 
 
93
Run on the working tree before ``commit`` starts processing it.
 
94
Runs on the client.
 
95
 
 
96
Unlike the ``pre_commit`` hook (see below), the ``start_commit`` hook
 
97
can safely change the working tree.
 
98
 
 
99
The hook signature is (tree) where tree is a MutableTree object.
 
100
 
 
101
 
 
102
pre_commit (Branch)
 
103
-------------------
 
104
 
 
105
Run before ``commit`` has completed.
 
106
Runs on the client.
 
107
 
 
108
The hook signature is (local, master, old_revno, old_revid, future_revno,
 
109
future_revid, tree_delta, future_tree) where old_revno is NULL_REVISION for
 
110
the first commit to a branch, tree_delta is a TreeDelta object describing
 
111
changes from the basis revision, and future_tree is an in-memory tree
 
112
obtained from CommitBuilder.revision_tree(). Hooks MUST NOT modify tree_delta
 
113
and future_tree.
 
114
 
 
115
 
 
116
post_commit (Branch)
 
117
--------------------
 
118
 
 
119
Run after ``commit`` has completed.
 
120
Runs on the client.
 
121
 
 
122
The hook signature is (local, master, old_revno, old_revid, new_revno,
 
123
new_revid) old_revid is NULL_REVISION for the first commit to a branch.
 
124
 
 
125
 
 
126
post_uncommit (Branch)
 
127
----------------------
 
128
 
 
129
Run after ``uncommit`` has completed.
 
130
Runs on the client.
 
131
 
 
132
The api signature is (local, master, old_revno, old_revid, new_revno,
 
133
new_revid) where local is the local branch or None, master is the target
 
134
branch, and an empty branch receives new_revno of 0, new_revid of None.
 
135
 
 
136
 
 
137
pre_change_branch_tip (Branch)
 
138
-------------------------------
 
139
 
 
140
Run before a branch tip has been changed, while the branch is write-locked.
 
141
Runs on the client and on the server.
 
142
Note that push, pull, commit and uncommit all invoke this hook.
 
143
 
 
144
The hook signature is (params), where params is an object containing
 
145
the members
 
146
 
 
147
  branch
 
148
    The branch whose tip has been changed.
 
149
 
 
150
  old_revno
 
151
    The revision number (eg 10) of the branch before the change.
 
152
 
 
153
  old_revid
 
154
    The revision id (eg joe@foo.com-1234234-aoeua34) before the change.
 
155
 
 
156
  new_revno
 
157
    The revision number (eg 12) of the branch after the change.
 
158
 
 
159
  new_revid
 
160
    The revision id (eg joe@foo.com-5676566-boa234a) after the change.
 
161
 
 
162
The old_revno and new_revno members are integers, as the head
 
163
revision never has a dotted revision number.
 
164
 
 
165
 
 
166
post_change_branch_tip (Branch)
 
167
-------------------------------
 
168
 
 
169
Run after a branch tip has been changed but while the branch is still
 
170
write-locked.
 
171
Runs on the client and on the server.
 
172
Note that push, pull, commit and uncommit all invoke this hook.
 
173
 
 
174
The hook signature is (params), where params is an object containing
 
175
the members
 
176
 
 
177
  branch
 
178
    The branch whose tip has been changed.
 
179
 
 
180
  old_revno
 
181
    The revision number (eg 10) of the branch before the change.
 
182
 
 
183
  old_revid
 
184
    The revision id (eg joe@foo.com-1234234-aoeua34) before the change.
 
185
 
 
186
  new_revno
 
187
    The revision number (eg 12) of the branch after the change.
 
188
 
 
189
  new_revid
 
190
    The revision id (eg joe@foo.com-5676566-boa234a) after the change.
 
191
 
 
192
The old_revno and new_revno members are integers, as the head
 
193
revision never has a dotted revision number.
 
194
 
 
195
 
 
196
set_rh (Branch)
 
197
---------------
 
198
 
 
199
Note: This hook is now deprecated and will be removed in the near future.
 
200
Please use the ``post_change_branch_tip`` hook instead.
 
201
 
 
202
 
 
203
transform_fallback_location (Branch)
 
204
------------------------------------
 
205
 
 
206
Invoked as a stacked branch activates its fallback locations.
 
207
 
 
208
The hook signature is (branch, url) where:
 
209
 
 
210
  branch
 
211
    The branch being opened.  Note that as it does not yet have its
 
212
    fallback locations activated, the branch should be treated as
 
213
    half-built.
 
214
 
 
215
  url
 
216
    The URL that the branch specified for its fallback location.
 
217
 
 
218
The hook must return a URL for the branch containing the fallback
 
219
location. If multiple hooks are registered, the order in which they 
 
220
will be called is undefined and subject to change.
 
221
 
 
222
(New in 1.9)
 
223
 
 
224
 
 
225
server_started (SmartTCPServer)
 
226
-------------------------------
 
227
 
 
228
Invoked whenever the server starts serving a directory.
 
229
Runs on the server.
 
230
 
 
231
The hook signature is (backing urls, public url), where:
 
232
 
 
233
  backing_url
 
234
    A list of (string) URLs giving the server-specific directory locations.
 
235
 
 
236
  public_url
 
237
    The public URL for the directory.
 
238
 
 
239
 
 
240
server_stopped (SmartTCPServer)
 
241
-------------------------------
 
242
 
 
243
Invoked whenever the server stops serving a directory.
 
244
Runs on the server.
 
245
 
 
246
The hook signature is the same as ``server_started``.
 
247
 
 
248
 
 
249
lock_acquired (LockDir)
 
250
----------------------------
 
251
 
 
252
Called with a LockResult object when a lock has been successfully acquired.
 
253
Runs on the client and on the server.
 
254
 
 
255
(New in 1.8.)
 
256
 
 
257
lock_released (LockDir)
 
258
----------------------------
 
259
 
 
260
Called with a LockResult object when a lock has been successfully released.
 
261
Runs on the client.
 
262
 
 
263
(New in 1.8.)
 
264
 
 
265
commit_message_template (msgeditor)
 
266
-----------------------------------
 
267
 
 
268
Invoked by commit to generate a commit message template.
 
269
Each hook can modify the commit message template.
 
270
The hook signature is (commit, start_message), where:
 
271
 
 
272
  commit
 
273
    A commit object, for the commit in progress
 
274
 
 
275
  start_message
 
276
    The original commit message, None initially.
 
277
 
 
278
The hook should return a new commit message template.
 
279
 
 
280
(New in 1.10.)