7
A hook of type *xxx* of class *yyy* needs to be registered using::
9
yyy.hooks.install_named_hook("xxx", ...)
11
See `Using hooks`_ in the User Guide for examples.
13
.. _Using hooks: ../user-guide/index.html#using-hooks
15
The class that contains each hook is given in parentheses immediately
16
after each hook type below.
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.
22
Plugins (including hooks) are run on the server if any of these is true:
24
* The remote branch is on the same machine as the client, and the client
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
36
Called after a Branch object is opened, with the Branch object.
37
Runs on the client and on the server.
43
Run after ``push`` has completed.
46
The hook signature is (push_result), containing the members
49
Where the data is being pushed from (read locked).
50
This should be the lowest latency branch.
53
The direct location where data is being sent (write locked).
56
Either target_branch, or if the target is a bound branch, it
57
will be the master location (write locked).
60
If the target is a bound branch, this will be the target
61
branch, else it will be None.
64
The revision number (eg 10) of the branch before the push.
67
The revision id (eg joe@foo.com-1234234-aoeua34) before the push.
70
The revision number (eg 12) of the branch after the push.
73
The revision id (eg joe@foo.com-5676566-boa234a) after the push.
79
Run after ``pull`` has completed.
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.
90
start_commit (MutableTree)
91
--------------------------
93
Run on the working tree before ``commit`` starts processing it.
96
Unlike the ``pre_commit`` hook (see below), the ``start_commit`` hook
97
can safely change the working tree.
99
The hook signature is (tree) where tree is a MutableTree object.
105
Run before ``commit`` has completed.
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
119
Run after ``commit`` has completed.
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.
126
post_uncommit (Branch)
127
----------------------
129
Run after ``uncommit`` has completed.
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.
137
pre_change_branch_tip (Branch)
138
-------------------------------
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.
144
The hook signature is (params), where params is an object containing
148
The branch whose tip has been changed.
151
The revision number (eg 10) of the branch before the change.
154
The revision id (eg joe@foo.com-1234234-aoeua34) before the change.
157
The revision number (eg 12) of the branch after the change.
160
The revision id (eg joe@foo.com-5676566-boa234a) after the change.
162
The old_revno and new_revno members are integers, as the head
163
revision never has a dotted revision number.
166
post_change_branch_tip (Branch)
167
-------------------------------
169
Run after a branch tip has been changed but while the branch is still
171
Runs on the client and on the server.
172
Note that push, pull, commit and uncommit all invoke this hook.
174
The hook signature is (params), where params is an object containing
178
The branch whose tip has been changed.
181
The revision number (eg 10) of the branch before the change.
184
The revision id (eg joe@foo.com-1234234-aoeua34) before the change.
187
The revision number (eg 12) of the branch after the change.
190
The revision id (eg joe@foo.com-5676566-boa234a) after the change.
192
The old_revno and new_revno members are integers, as the head
193
revision never has a dotted revision number.
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.
203
transform_fallback_location (Branch)
204
------------------------------------
206
Invoked as a stacked branch activates its fallback locations.
208
The hook signature is (branch, url) where:
211
The branch being opened. Note that as it does not yet have its
212
fallback locations activated, the branch should be treated as
216
The URL that the branch specified for its fallback location.
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.
225
server_started (SmartTCPServer)
226
-------------------------------
228
Invoked whenever the server starts serving a directory.
231
The hook signature is (backing urls, public url), where:
234
A list of (string) URLs giving the server-specific directory locations.
237
The public URL for the directory.
240
server_stopped (SmartTCPServer)
241
-------------------------------
243
Invoked whenever the server stops serving a directory.
246
The hook signature is the same as ``server_started``.
249
lock_acquired (LockDir)
250
----------------------------
252
Called with a LockResult object when a lock has been successfully acquired.
253
Runs on the client and on the server.
257
lock_released (LockDir)
258
----------------------------
260
Called with a LockResult object when a lock has been successfully released.
265
commit_message_template (msgeditor)
266
-----------------------------------
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:
273
A commit object, for the commit in progress
276
The original commit message, None initially.
278
The hook should return a new commit message template.
added
removed
bzrlib/help_topics/en/hooks.txt
