← 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: Canonical.com Patch Queue Manager
  • Date: 2008-06-20 01:09:18 UTC
  • mfrom: (3505.1.1 ianc-integration)
  • Revision ID: pqm@pqm.ubuntu.com-20080620010918-64z4xylh1ap5hgyf
Accept user names with @s in URLs (Neil Martinsen-Burrell)

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 of each hook is given immediately after each hook type below.
 
16
 
 
17
 
 
18
post_push (Branch)
 
19
------------------
 
20
 
 
21
Run after ``push`` has completed.
 
22
 
 
23
The hook signature is (push_result), containing the members
 
24
 
 
25
  source_branch
 
26
    Where the data is being pushed from (read locked).
 
27
    This should be the lowest latency branch.
 
28
 
 
29
  target_branch
 
30
    The direct location where data is being sent (write locked).
 
31
 
 
32
  master_branch
 
33
    Either target_branch, or if the target is a bound branch, it
 
34
    will be the master location (write locked).
 
35
 
 
36
  local_branch
 
37
    If the target is a bound branch, this will be the target
 
38
    branch, else it will be None.
 
39
 
 
40
  old_revno
 
41
    The revision number (eg 10) of the branch before the push.
 
42
 
 
43
  old_revid
 
44
    The revision id (eg joe@foo.com-1234234-aoeua34) before the push.
 
45
 
 
46
  new_revno
 
47
    The revision number (eg 12) of the branch after the push.
 
48
 
 
49
  new_revid
 
50
    The revision id (eg joe@foo.com-5676566-boa234a) after the push.
 
51
 
 
52
 
 
53
post_pull (Branch)
 
54
------------------
 
55
 
 
56
Run after ``pull`` has completed.
 
57
 
 
58
The hook signature is (push_result) containing the members
 
59
(source, local, master, old_revno, old_revid, new_revno, new_revid)
 
60
where local is the local target branch or None, master is the target 
 
61
master branch, and the rest should be self explanatory. The source
 
62
is read-locked and the target branches are write-locked. Source will
 
63
be the local low-latency branch.
 
64
 
 
65
 
 
66
start_commit (MutableTree)
 
67
--------------------------
 
68
 
 
69
Run on the working tree before ``commit`` starts processing it.
 
70
Unlike the ``pre_commit`` hook (see below), the ``start_commit`` hook
 
71
can safely change the working tree.
 
72
 
 
73
The hook signature is (tree) where tree is a MutableTree object.
 
74
 
 
75
 
 
76
pre_commit (Branch)
 
77
-------------------
 
78
 
 
79
Run before ``commit`` has completed.
 
80
 
 
81
The hook signature is (local, master, old_revno, old_revid, future_revno,
 
82
future_revid, tree_delta, future_tree) where old_revno is NULL_REVISION for
 
83
the first commit to a branch, tree_delta is a TreeDelta object describing
 
84
changes from the basis revision, and future_tree is an in-memory tree
 
85
obtained from CommitBuilder.revision_tree(). Hooks MUST NOT modify tree_delta
 
86
and future_tree.
 
87
 
 
88
 
 
89
post_commit (Branch)
 
90
--------------------
 
91
 
 
92
Run after ``commit`` has completed.
 
93
 
 
94
The hook signature is (local, master, old_revno, old_revid, new_revno,
 
95
new_revid) old_revid is NULL_REVISION for the first commit to a branch.
 
96
 
 
97
 
 
98
post_uncommit (Branch)
 
99
----------------------
 
100
 
 
101
Run after ``uncommit`` has completed.
 
102
 
 
103
The api signature is (local, master, old_revno, old_revid, new_revno,
 
104
new_revid) where local is the local branch or None, master is the target
 
105
branch, and an empty branch receives new_revno of 0, new_revid of None.
 
106
 
 
107
 
 
108
post_change_branch_tip (Branch)
 
109
-------------------------------
 
110
 
 
111
Run after a branch tip has been changed but while the branch is still
 
112
write-locked. Note that push, pull, commit and uncommit all invoke this hook.
 
113
 
 
114
The hook signature is (params), where params is an object containing
 
115
the members
 
116
 
 
117
  branch
 
118
    The branch whose tip has been changed.
 
119
 
 
120
  old_revno
 
121
    The revision number (eg 10) of the branch before the change.
 
122
 
 
123
  old_revid
 
124
    The revision id (eg joe@foo.com-1234234-aoeua34) before the change.
 
125
 
 
126
  new_revno
 
127
    The revision number (eg 12) of the branch after the change.
 
128
 
 
129
  new_revid
 
130
    The revision id (eg joe@foo.com-5676566-boa234a) after the change.
 
131
 
 
132
The old_revno and new_revno members are integers, as the head
 
133
revision is never has a dotted revision number.
 
134
 
 
135
 
 
136
set_rh (Branch)
 
137
---------------
 
138
 
 
139
Note: This hook is now deprecated and will be removed in the near future.
 
140
Please use the ``post_change_branch_tip`` hook instead.
 
141
 
 
142
 
 
143
server_started (SmartTCPServer)
 
144
-------------------------------
 
145
 
 
146
Invoked whenever the server starts serving a directory.
 
147
The hook signature is (backing urls, public url), where:
 
148
 
 
149
  backing_url
 
150
    A list of (string) URLs giving the server-specific directory locations.
 
151
 
 
152
  public_url
 
153
    The public URL for the directory.
 
154
 
 
155
 
 
156
server_stopped (SmartTCPServer)
 
157
-------------------------------
 
158
 
 
159
Invoked whenever the server stops serving a directory.
 
160
The hook signature is the same as ``server_started``.