Rev 3416: Better hooks doc (Ian Clatworthy) in file:///home/pqm/archives/thelove/bzr/%2Btrunk/

Canonical.com Patch Queue Manager pqm at pqm.ubuntu.com
Thu May 8 09:22:50 BST 2008


At file:///home/pqm/archives/thelove/bzr/%2Btrunk/

------------------------------------------------------------
revno: 3416
revision-id:pqm at pqm.ubuntu.com-20080508082241-zyx68bbzrgnlhw9m
parent: pqm at pqm.ubuntu.com-20080508070500-9zyyvsk0eev20t4w
parent: ian.clatworthy at canonical.com-20080508064759-9riwekf33mrnadtj
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Thu 2008-05-08 09:22:41 +0100
message:
  Better hooks doc (Ian Clatworthy)
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: 3414.1.1
    revision-id:ian.clatworthy at canonical.com-20080508064759-9riwekf33mrnadtj
    parent: pqm at pqm.ubuntu.com-20080508003116-ps46dreqbprfr166
    parent: ian.clatworthy at canonical.com-20080507090507-4sramfa2vknpx89x
    committer: Ian Clatworthy <ian.clatworthy at canonical.com>
    branch nick: ianc-integration
    timestamp: Thu 2008-05-08 16:47:59 +1000
    message:
      Better hooks doc (Ian Clatworthy)
    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: 3408.5.5
    revision-id:ian.clatworthy at canonical.com-20080507090507-4sramfa2vknpx89x
    parent: ian.clatworthy at canonical.com-20080507075003-490c9l2ojchqu2eu
    committer: Ian Clatworthy <ian.clatworthy at canonical.com>
    branch nick: bzr.hooks-doc
    timestamp: Wed 2008-05-07 19:05:07 +1000
    message:
      added smart server hooks doc
    modified:
      bzrlib/help_topics/en/hooks.txt hooks.txt-20070830033044-xxu2rced13f72dka-1
    ------------------------------------------------------------
    revno: 3408.5.4
    revision-id:ian.clatworthy at canonical.com-20080507075003-490c9l2ojchqu2eu
    parent: ian.clatworthy at canonical.com-20080507074908-yxj4g7fl573oip20
    committer: Ian Clatworthy <ian.clatworthy at canonical.com>
    branch nick: bzr.hooks-doc
    timestamp: Wed 2008-05-07 17:50:03 +1000
    message:
      added NEWS item
    modified:
      NEWS                           NEWS-20050323055033-4e00b5db738777ff
    ------------------------------------------------------------
    revno: 3408.5.3
    revision-id:ian.clatworthy at canonical.com-20080507074908-yxj4g7fl573oip20
    parent: ian.clatworthy at canonical.com-20080507071822-1kvfdqg6kt8l70a3
    committer: Ian Clatworthy <ian.clatworthy at canonical.com>
    branch nick: bzr.hooks-doc
    timestamp: Wed 2008-05-07 17:49:08 +1000
    message:
      add classes to the Hooks User Reference doc
    modified:
      bzrlib/help_topics/en/hooks.txt hooks.txt-20070830033044-xxu2rced13f72dka-1
    ------------------------------------------------------------
    revno: 3408.5.2
    revision-id:ian.clatworthy at canonical.com-20080507071822-1kvfdqg6kt8l70a3
    parent: ian.clatworthy at canonical.com-20080507064950-k03qeflkaen81f35
    committer: Ian Clatworthy <ian.clatworthy at canonical.com>
    branch nick: bzr.hooks-doc
    timestamp: Wed 2008-05-07 17:18:22 +1000
    message:
      add start_commit doc
    modified:
      bzrlib/help_topics/en/hooks.txt hooks.txt-20070830033044-xxu2rced13f72dka-1
    ------------------------------------------------------------
    revno: 3408.5.1
    revision-id:ian.clatworthy at canonical.com-20080507064950-k03qeflkaen81f35
    parent: pqm at pqm.ubuntu.com-20080506114010-jwclr2qtiekvawjg
    committer: Ian Clatworthy <ian.clatworthy at canonical.com>
    branch nick: bzr.hooks-doc
    timestamp: Wed 2008-05-07 16:49:50 +1000
    message:
      fix User Guide example
    modified:
      doc/en/user-guide/hooks.txt    hooks.txt-20070829200551-7nr6e5a1io6x78uf-1
=== modified file 'NEWS'
--- a/NEWS	2008-05-08 04:33:38 +0000
+++ b/NEWS	2008-05-08 08:22:41 +0000
@@ -84,6 +84,8 @@
 
     * Document outlining strategies for TortoiseBzr. (Mark Hammond)
 
+    * Improved the documentation on hooks. (Ian Clatworthy)
+
   TESTING:
 
     * Add ``thread_name_suffix`` parameter to SmartTCPServer_for_testing, to

=== modified file 'bzrlib/help_topics/en/hooks.txt'
--- a/bzrlib/help_topics/en/hooks.txt	2008-04-09 06:41:44 +0000
+++ b/bzrlib/help_topics/en/hooks.txt	2008-05-08 06:47:59 +0000
@@ -1,8 +1,22 @@
 Hooks
 =====
 
-post_push
----------
+Introduction
+------------
+
+A hook of type *xxx* of class *yyy* needs to be registered using::
+
+  yyy.hooks.install_named_hook("xxx", ...)
+
+See `Using hooks`_ in the User Guide for examples.
+
+.. _Using hooks: ../user-guide/index.html#using-hooks
+
+The class of each hook is given immediately after each hook type below.
+
+
+post_push (Branch)
+------------------
 
 Run after ``push`` has completed.
 
@@ -35,8 +49,9 @@
   new_revid
     The revision id (eg joe at foo.com-5676566-boa234a) after the push.
 
-post_pull
----------
+
+post_pull (Branch)
+------------------
 
 Run after ``pull`` has completed.
 
@@ -47,10 +62,21 @@
 is read-locked and the target branches are write-locked. Source will
 be the local low-latency branch.
 
-pre_commit
-----------
-
-Run prefore ``commit`` has completed.
+
+start_commit (MutableTree)
+--------------------------
+
+Run on the working tree before ``commit`` starts processing it.
+Unlike the ``pre_commit`` hook (see below), the ``start_commit`` hook
+can safely change the working tree.
+
+The hook signature is (tree) where tree is a MutableTree object.
+
+
+pre_commit (Branch)
+-------------------
+
+Run before ``commit`` has completed.
 
 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
@@ -59,16 +85,18 @@
 obtained from CommitBuilder.revision_tree(). Hooks MUST NOT modify tree_delta
 and future_tree.
 
-post_commit
------------
+
+post_commit (Branch)
+--------------------
 
 Run after ``commit`` has completed.
 
 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.
 
-post_uncommit
--------------
+
+post_uncommit (Branch)
+----------------------
 
 Run after ``uncommit`` has completed.
 
@@ -76,8 +104,9 @@
 new_revid) where local is the local branch or None, master is the target
 branch, and an empty branch receives new_revno of 0, new_revid of None.
 
-post_change_branch_tip
-----------------------
+
+post_change_branch_tip (Branch)
+-------------------------------
 
 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.
@@ -103,12 +132,29 @@
 The old_revno and new_revno members are integers, as the head
 revision is never has a dotted revision number.
 
-set_rh
-------
+
+set_rh (Branch)
+---------------
 
 Note: This hook is now deprecated and will be removed in the near future.
 Please use the ``post_change_branch_tip`` hook instead.
 
-See also `Using hooks`_ in the User Guide.
-
-.. _Using hooks: ../user-guide/index.html#using-hooks
+
+server_started (SmartTCPServer)
+-------------------------------
+
+Invoked whenever the server starts serving a directory.
+The hook signature is (backing urls, public url), where:
+
+  backing_url
+    A list of (string) URLs giving the server-specific directory locations.
+
+  public_url
+    The public URL for the directory.
+
+
+server_stopped (SmartTCPServer)
+-------------------------------
+
+Invoked whenever the server stops serving a directory.
+The hook signature is the same as ``server_started``.

=== modified file 'doc/en/user-guide/hooks.txt'
--- a/doc/en/user-guide/hooks.txt	2008-03-15 00:51:43 +0000
+++ b/doc/en/user-guide/hooks.txt	2008-05-07 06:49:50 +0000
@@ -22,7 +22,7 @@
         print "The new revno is %d" % push_result.new_revno
 
 
-    branch.Branch.hooks.install_hook('post_push', post_push_hook,
+    branch.Branch.hooks.install_named_hook('post_push', post_push_hook,
                                      'My post_push hook')
 
 To use this example, create a file named ``push_hook.py``, and stick it in




More information about the bazaar-commits mailing list