Rev 3806: (mbp) updated hooks docs from Michael Ernst in file:///home/pqm/archives/thelove/bzr/%2Btrunk/
Canonical.com Patch Queue Manager
pqm at pqm.ubuntu.com
Wed Oct 29 07:01:50 GMT 2008
At file:///home/pqm/archives/thelove/bzr/%2Btrunk/
------------------------------------------------------------
revno: 3806
revision-id: pqm at pqm.ubuntu.com-20081029070146-p1cqjt23zctbpg51
parent: pqm at pqm.ubuntu.com-20081028202057-u3csau9zvf0hapya
parent: mbp at sourcefrog.net-20081029061935-wbhez2qzb2bd13n6
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Wed 2008-10-29 07:01:46 +0000
message:
(mbp) updated hooks docs from Michael Ernst
modified:
NEWS NEWS-20050323055033-4e00b5db738777ff
bzrlib/help_topics/en/hooks.txt hooks.txt-20070830033044-xxu2rced13f72dka-1
doc/en/user-guide/hooks.txt hooks.txt-20070829200551-7nr6e5a1io6x78uf-1
------------------------------------------------------------
revno: 3805.1.2
revision-id: mbp at sourcefrog.net-20081029061935-wbhez2qzb2bd13n6
parent: mbp at sourcefrog.net-20081029061045-q8fpbt0v1bdag0mt
committer: Martin Pool <mbp at sourcefrog.net>
branch nick: doc
timestamp: Wed 2008-10-29 17:19:35 +1100
message:
Update news
modified:
NEWS NEWS-20050323055033-4e00b5db738777ff
------------------------------------------------------------
revno: 3805.1.1
revision-id: mbp at sourcefrog.net-20081029061045-q8fpbt0v1bdag0mt
parent: pqm at pqm.ubuntu.com-20081028202057-u3csau9zvf0hapya
parent: mernst at csail.mit.edu-20081020092603-1rujv34uamb0gza8
committer: Martin Pool <mbp at sourcefrog.net>
branch nick: doc
timestamp: Wed 2008-10-29 17:10:45 +1100
message:
Merge and tweak hook documentation
modified:
bzrlib/help_topics/en/hooks.txt hooks.txt-20070830033044-xxu2rced13f72dka-1
doc/en/user-guide/hooks.txt hooks.txt-20070829200551-7nr6e5a1io6x78uf-1
------------------------------------------------------------
revno: 3786.1.2
revision-id: mernst at csail.mit.edu-20081020092603-1rujv34uamb0gza8
parent: mernst at csail.mit.edu-20081020065324-8oz1mxqa5p0zkdss
committer: mernst at csail.mit.edu
branch nick: doc-hooks
timestamp: Mon 2008-10-20 11:26:03 +0200
message:
Improvements suggested by Andrew Bennetts.
modified:
bzrlib/help_topics/en/hooks.txt hooks.txt-20070830033044-xxu2rced13f72dka-1
doc/en/user-guide/hooks.txt hooks.txt-20070829200551-7nr6e5a1io6x78uf-1
doc/en/user-guide/http_smart_server.txt fastcgi.txt-20061005091552-rz8pva0olkxv0sd8-3
------------------------------------------------------------
revno: 3786.1.1
revision-id: mernst at csail.mit.edu-20081020065324-8oz1mxqa5p0zkdss
parent: pqm at pqm.ubuntu.com-20081020020359-7f8c4hviijt1m5vq
committer: mernst at csail.mit.edu
branch nick: doc-hooks
timestamp: Mon 2008-10-20 08:53:24 +0200
message:
This patch improves the User Guide's documentation of hooks.
The text no longer intersperses discussion of what a user does with a
descripton of the code. Nor does it confusingly use first person to
describe what the code does. It puts two lists of hooks together in one
place. It fixes bugs in hook examples (per
https://lists.ubuntu.com/archives/bazaar/2008q3/047498.html). It clarifies
where each hook is run (on the client, the server, or both).
modified:
bzrlib/help_topics/en/hooks.txt hooks.txt-20070830033044-xxu2rced13f72dka-1
doc/en/user-guide/hooks.txt hooks.txt-20070829200551-7nr6e5a1io6x78uf-1
doc/en/user-guide/http_smart_server.txt fastcgi.txt-20061005091552-rz8pva0olkxv0sd8-3
=== modified file 'NEWS'
--- a/NEWS 2008-10-28 19:43:42 +0000
+++ b/NEWS 2008-10-29 06:19:35 +0000
@@ -78,6 +78,8 @@
DOCUMENTATION:
+ * Improved hook documentation. (Michael Ernst)
+
API CHANGES:
* commands.plugins_cmds is now a CommandRegistry, not a dict.
=== modified file 'bzrlib/help_topics/en/hooks.txt'
--- a/bzrlib/help_topics/en/hooks.txt 2008-10-22 19:05:22 +0000
+++ b/bzrlib/help_topics/en/hooks.txt 2008-10-29 06:10:45 +0000
@@ -12,19 +12,36 @@
.. _Using hooks: ../user-guide/index.html#using-hooks
-The class of each hook is given immediately after each hook type below.
+The class that contains each hook is given in parentheses immediately
+after each hook type below.
+
+Each description also indicates whether the hook runs on the client (the
+machine where bzr was invoked) or the server (the machine addressed by
+the branch URL). These may be, but are not necessarily, the same machine.
+
+Plugins (including hooks) are run on the server if any of these is true:
+
+ * The remote branch is on the same machine as the client, and the client
+ has plugins enabled.
+
+ * The connection is via a smart server (accessed with a URL starting with
+ "bzr://", "bzr+ssh://" or "bzr+http://", or accessed via a "http://"
+ URL when a smart server is available via HTTP), and that server has
+ plugins enabled.
open (Branch)
-------------
Called after a Branch object is opened, with the Branch object.
+Runs on the client and on the server.
post_push (Branch)
------------------
Run after ``push`` has completed.
+Runs on the client.
The hook signature is (push_result), containing the members
@@ -60,6 +77,7 @@
------------------
Run after ``pull`` has completed.
+Runs on the client.
The hook signature is (push_result) containing the members
(source, local, master, old_revno, old_revid, new_revno, new_revid)
@@ -73,6 +91,8 @@
--------------------------
Run on the working tree before ``commit`` starts processing it.
+Runs on the client.
+
Unlike the ``pre_commit`` hook (see below), the ``start_commit`` hook
can safely change the working tree.
@@ -83,6 +103,7 @@
-------------------
Run before ``commit`` has completed.
+Runs on the client.
The hook signature is (local, master, old_revno, old_revid, future_revno,
future_revid, tree_delta, future_tree) where old_revno is NULL_REVISION for
@@ -96,6 +117,7 @@
--------------------
Run after ``commit`` has completed.
+Runs on the client.
The hook signature is (local, master, old_revno, old_revid, new_revno,
new_revid) old_revid is NULL_REVISION for the first commit to a branch.
@@ -105,6 +127,7 @@
----------------------
Run after ``uncommit`` has completed.
+Runs on the client.
The api signature is (local, master, old_revno, old_revid, new_revno,
new_revid) where local is the local branch or None, master is the target
@@ -115,6 +138,7 @@
-------------------------------
Run before a branch tip has been changed, while the branch is write-locked.
+Runs on the client and on the server.
Note that push, pull, commit and uncommit all invoke this hook.
The hook signature is (params), where params is an object containing
@@ -143,7 +167,9 @@
-------------------------------
Run after a branch tip has been changed but while the branch is still
-write-locked. Note that push, pull, commit and uncommit all invoke this hook.
+write-locked.
+Runs on the client and on the server.
+Note that push, pull, commit and uncommit all invoke this hook.
The hook signature is (params), where params is an object containing
the members
@@ -200,6 +226,8 @@
-------------------------------
Invoked whenever the server starts serving a directory.
+Runs on the server.
+
The hook signature is (backing urls, public url), where:
backing_url
@@ -213,6 +241,8 @@
-------------------------------
Invoked whenever the server stops serving a directory.
+Runs on the server.
+
The hook signature is the same as ``server_started``.
@@ -220,10 +250,14 @@
----------------------------
Called with a LockResult object when a lock has been successfully acquired.
+Runs on the client and on the server.
+
(New in 1.8.)
lock_released (LockDir)
----------------------------
Called with a LockResult object when a lock has been successfully released.
+Runs on the client.
+
(New in 1.8.)
=== modified file 'doc/en/user-guide/hooks.txt'
--- a/doc/en/user-guide/hooks.txt 2008-05-07 06:49:50 +0000
+++ b/doc/en/user-guide/hooks.txt 2008-10-29 06:10:45 +0000
@@ -7,6 +7,14 @@
One way to customize Bazaar's behaviour is with *hooks*. Hooks allow you to
perform actions before or after certain Bazaar operations. The operations
include ``commit``, ``push``, ``pull``, and ``uncommit``.
+For a complete list of hooks and their parameters, see `Hooks
+<../user-reference/bzr_man.html#hooks>`_ in the User Reference.
+
+Most hooks are run on the client, but a few are run on the server. (Also
+see the `bzr-push-and-update`_ plugin that handles one special case of
+server-side operations.)
+
+.. _bzr-push-and-update: https://launchpad.net/bzr-push-and-update/
Using hooks
-----------
@@ -29,25 +37,20 @@
``plugins`` subdirectory of your configuration directory. (If you have never
installed any plugins, you may need to create the ``plugins`` directory).
-First, we define a function that will be run after ``push`` completes. We
-could also use an instance method or a callable object. All push hooks take a
-single argument, the ``push_result``.
-
-Next, we install the hook. ``'post_push'`` identifies where we want to install
-the hook, and the second parameter is the hook itself. We also give the hook a
-name 'My post_push hook', which can be used in progress messages and error
-messages.
-
That's it! The next time you push, it should show "The new revno is...".
Of course, hooks can be much more elaborate than this, because you have the
full power of Python at your disposal. Now that you know how to use hooks,
what you do with them is up to you.
-Standard hooks
---------------
+The plugin code does two things. First, it defines a function that will be
+run after ``push`` completes. (It could instead use an instance method or
+a callable object.) All push hooks take a single argument, the
+``push_result``.
-For a complete list of hooks and their parameters, see `Hooks
-<../user-reference/bzr_man.html#hooks>`_ in the User Reference.
+Second, the plugin installs the hook. The first argument ``'post_push'``
+identifies where to install the hook. The second argument is the hook
+itself. The third argument is a name ``'My post_push hook'``, which can be
+used in progress messages and error messages.
Debugging hooks
---------------
More information about the bazaar-commits
mailing list