Rev 2769: Add documentation for hooks in file:///home/pqm/archives/thelove/bzr/%2Btrunk/

Thu Aug 30 05:44:53 BST 2007

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

------------------------------------------------------------
revno: 2769
revision-id: pqm at pqm.ubuntu.com-20070830044451-flsqsh6qsc4j4h75
parent: pqm at pqm.ubuntu.com-20070829235511-o6ftd800xa245p9h
parent: aaron.bentley at utoronto.ca-20070830033601-bykwk4l5t6x78d65
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Thu 2007-08-30 05:44:51 +0100
message:
  Add documentation for hooks
added:
  doc/en/user-guide/hooks.txt    hooks.txt-20070829200551-7nr6e5a1io6x78uf-1
  doc/en/user-reference/hooks.txt hooks.txt-20070830033044-xxu2rced13f72dka-1
  doc/en/user-reference/index.txt index.txt-20070830033353-ud9e03xsh24053oo-1
modified:
  doc/en/user-guide/index.txt    index.txt-20060622101119-tgwtdci8z769bjb9-2
    ------------------------------------------------------------
    revno: 2767.2.2
    merged: aaron.bentley at utoronto.ca-20070830033601-bykwk4l5t6x78d65
    parent: abentley at panoramicfeedback.com-20070829200609-62b03g4cib5s4rkz
    committer: Aaron Bentley <aaron.bentley at utoronto.ca>
    branch nick: bzr.docs
    timestamp: Wed 2007-08-29 23:36:01 -0400
    message:
      Split hooks doc into guide and reference
    ------------------------------------------------------------
    revno: 2767.2.1
    merged: abentley at panoramicfeedback.com-20070829200609-62b03g4cib5s4rkz
    parent: pqm at pqm.ubuntu.com-20070829161516-le0ppkanxngkjg69
    committer: Aaron Bentley <abentley at panoramicfeedback.com>
    branch nick: bzr.docs
    timestamp: Wed 2007-08-29 16:06:09 -0400
    message:
      Add documentation for hooks
=== added file 'doc/en/user-guide/hooks.txt'

--- a/doc/en/user-guide/hooks.txt	1970-01-01 00:00:00 +0000
+++ b/doc/en/user-guide/hooks.txt	2007-08-30 03:36:01 +0000
@@ -0,0 +1,45 @@
+###########
+Using hooks
+###########
+
+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``.
+
+Using Hooks
+###########
+To use a hook, you should write a `plugin <plugins.html>`_.  Instead of
+creating a new command, this plugin will define and install the hook.  Here's
+an example::
+
+    from bzrlib import branch
+
+
+    def post_push_hook(push_result):
+        print "The new revno is %d" % push_result.new_revno
+
+
+    branch.Branch.hooks.install_hook('post_push', post_push_hook)
+    branch.Branch.hooks.name_hook(post_push_hook, 'My post_push hook')
+
+To use this example, create a file named ``push_hook.py``, and stick it in
+``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 intance 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.
+
+Finally, we name the hook.  This is optional, but it means the hook name 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.
+
+For a complete list of hooks and their parameters, see the `Hooks Reference
+<../user-reference/hooks.html>`_.

=== added file 'doc/en/user-reference/hooks.txt'
--- a/doc/en/user-reference/hooks.txt	1970-01-01 00:00:00 +0000
+++ b/doc/en/user-reference/hooks.txt	2007-08-30 03:36:01 +0000
@@ -0,0 +1,52 @@
+###############
+Hooks Reference 
+###############
+
+post_push
+#########
+
+Run after ``push`` has completed.
+
+The hook signature is (push_result), containing the members
+(source, local, master, old_revno, old_revid, new_revno, new_revid)
+where local is the local target branch or None, master is the target 
+master branch, and the rest should be self-explanatory. The source
+is read-locked and the target branches are write-locked. Source will
+be the local low-latency branch.
+
+
+post_pull
+#########
+Run after ``pull`` has completed.
+
+The hook signature is (push_result) containing the members
+(source, local, master, old_revno, old_revid, new_revno, new_revid)
+where local is the local target branch or None, master is the target 
+master branch, and the rest should be self explanatory. The source
+is read-locked and the target branches are write-locked. Source will
+be the local low-latency branch.
+
+post_commit
+###########
+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
+#############
+Run after ``uncommit`` has completed.
+
+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
+branch, and an empty branch recieves new_revno of 0, new_revid of None.
+
+set_rh
+######
+Run after the branch's revision history has been modified (push, pull, commit
+and uncommit can all modify the revision history).
+
+The hook signature is (branch, revision_history), and the branch will be
+write-locked.
+
+See also `Using Hooks <../user-guide/hooks.html>`_.

=== added file 'doc/en/user-reference/index.txt'
--- a/doc/en/user-reference/index.txt	1970-01-01 00:00:00 +0000
+++ b/doc/en/user-reference/index.txt	2007-08-30 03:36:01 +0000
@@ -0,0 +1,8 @@
+#####################
+Bazaar User Reference
+#####################
+
+* `Hooks Reference <hooks.html>`_ |--| The various operations that Bazaar
+  lets you hook into
+
+.. |--| unicode:: U+2014

=== modified file 'doc/en/user-guide/index.txt'
--- a/doc/en/user-guide/index.txt	2007-08-10 08:11:57 +0000
+++ b/doc/en/user-guide/index.txt	2007-08-29 20:06:09 +0000
@@ -78,6 +78,9 @@
 
 * `Plugins <plugins.html>`_ |--| Information on how to use plugins in Bazaar.
 
+* `Hooks <hooks.html>`_ |--| How to set up hooks that are executed on certain
+  Bazaar operations.
+
 * `Using aliases <using_aliases.html>`_ |--| How to set up 
   and use command aliases.
 


