


Hooks
=====

Introduction
------------

A hook of type *xxx* of class *yyy* needs to be registered using::

  yyy.hooks.install_named_hook("xxx", ...)

See :doc:`Using hooks<../user-guide/hooks>` in the User Guide for examples.

The class that contains each hook is given before the hooks it supplies. For
instance, BranchHooks as the class is the hooks class for
`breezy.branch.Branch.hooks`.

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 all of these is true:

  * 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).

  * The hook is either server specific or part of general infrastructure rather
    than client specific code (such as commit).


BranchHooks
-----------

automatic_tag_name
~~~~~~~~~~~~~~~~~~

Introduced in: 2.2

Called to determine an automatic tag name for a revision.
automatic_tag_name is called with (branch, revision_id) and should
return a tag name or None if no tag name could be determined. The
first non-None tag name returned will be used.

open
~~~~

Introduced in: 1.8

Called with the Branch object that has been opened after a branch is
opened.

post_branch_init
~~~~~~~~~~~~~~~~

Introduced in: 2.2

Called after new branch initialization completes. post_branch_init is
called with a breezy.branch.BranchInitHookParams. Note that init,
branch and checkout (both heavyweight and lightweight) will all
trigger this hook.

post_change_branch_tip
~~~~~~~~~~~~~~~~~~~~~~

Introduced in: 1.4

Called in bzr client and server after a change to the tip of a branch
is made. post_change_branch_tip is called with a
breezy.branch.ChangeBranchTipParams. Note that push, pull, commit,
uncommit will all trigger this hook.

post_commit
~~~~~~~~~~~

Introduced in: 0.15

Called in the bzr client after a commit has completed. post_commit is
called with (local, master, old_revno, old_revid, new_revno,
new_revid). old_revid is NULL_REVISION for the first commit to a
branch.

post_pull
~~~~~~~~~

Introduced in: 0.15

Called after a pull operation completes. post_pull is called with a
breezy.branch.PullResult object and only runs in the bzr client.

post_push
~~~~~~~~~

Introduced in: 0.15

Called after a push operation completes. post_push is called with a
breezy.branch.BranchPushResult object and only runs in the bzr client.

post_switch
~~~~~~~~~~~

Introduced in: 2.2

Called after a checkout switches branch. post_switch is called with a
breezy.branch.SwitchHookParams.

post_uncommit
~~~~~~~~~~~~~

Introduced in: 0.15

Called in the bzr client after an uncommit completes. post_uncommit is
called with (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 receives new_revno of 0, new_revid
of None.

pre_change_branch_tip
~~~~~~~~~~~~~~~~~~~~~

Introduced in: 1.6

Called in bzr client and server before a change to the tip of a branch
is made. pre_change_branch_tip is called with a
breezy.branch.ChangeBranchTipParams. Note that push, pull, commit,
uncommit will all trigger this hook.

pre_commit
~~~~~~~~~~

Introduced in: 0.91

Called after a commit is calculated but before it is completed.
pre_commit is called with (local, master, old_revno, old_revid,
future_revno, future_revid, tree_delta, future_tree). old_revid is
NULL_REVISION for the first commit to a branch, tree_delta is a
TreeDelta object describing changes from the basis revision. hooks
MUST NOT modify this delta.  future_tree is an in-memory tree obtained
from CommitBuilder.revision_tree() and hooks MUST NOT modify this
tree.

transform_fallback_location
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Introduced in: 1.9

Called when a stacked branch is activating its fallback locations.
transform_fallback_location is called with (branch, url), and should
return a new url. Returning the same url allows it to be used as-is,
returning a different one can be used to cause the branch to stack on
a closer copy of that fallback_location. Note that the branch cannot
have history accessing methods called on it during this hook because
the fallback locations have not been activated. When there are
multiple hooks installed for transform_fallback_location, all are
called with the url returned from the previous hook.The order is
however undefined.

SmartClientHooks
----------------

call
~~~~

Introduced in: unknown

Called when the smart client is submitting a request to the smart
server. Called with a breezy.bzr.smart.client.CallHookParams object.
Streaming request bodies, and responses, are not accessible.

SmartServerHooks
----------------

server_exception
~~~~~~~~~~~~~~~~

Introduced in: 2.4

Called by the bzr server when an exception occurs. server_exception is
called with the sys.exc_info() tuple return true for the hook if the
exception has been handled, in which case the server will exit
normally.

server_started
~~~~~~~~~~~~~~

Introduced in: 0.16

Called by the bzr server when it starts serving a directory.
server_started is called with (backing urls, public url), where
backing_url is a list of URLs giving the server-specific directory
locations, and public_url is the public URL for the directory being
served.

server_started_ex
~~~~~~~~~~~~~~~~~

Introduced in: 1.17

Called by the bzr server when it starts serving a directory.
server_started is called with (backing_urls, server_obj).

server_stopped
~~~~~~~~~~~~~~

Introduced in: 0.16

Called by the bzr server when it stops serving a directory.
server_stopped is called with the same parameters as the
server_started hook: (backing_urls, public_url).

CommandHooks
------------

extend_command
~~~~~~~~~~~~~~

Introduced in: 1.13

Called after creating a command object to allow modifications such as
adding or removing options, docs etc. Called with the new
breezy.commands.Command object.

get_command
~~~~~~~~~~~

Introduced in: 1.17

Called when creating a single command. Called with (cmd_or_none,
command_name). get_command should either return the cmd_or_none
parameter, or a replacement Command object that should be used for the
command. Note that the Command.hooks hooks are core infrastructure.
Many users will prefer to use breezy.commands.register_command or
plugin_cmds.register_lazy.

get_missing_command
~~~~~~~~~~~~~~~~~~~

Introduced in: 1.17

Called when creating a single command if no command could be found.
Called with (command_name). get_missing_command should either return
None, or a Command object to be used for the command.

list_commands
~~~~~~~~~~~~~

Introduced in: 1.17

Called when enumerating commands. Called with a set of cmd_name
strings for all the commands found so far. This set  is safe to mutate
- e.g. to remove a command. list_commands should return the updated
set of command names.

post_command
~~~~~~~~~~~~

Introduced in: 2.6

Called after executing a command. Called with the command object.

pre_command
~~~~~~~~~~~

Introduced in: 2.6

Called prior to executing a command. Called with the command object.

_ConfigHooks
------------

get
~~~

Introduced in: 2.4

Invoked when a config option is read. The signature is (stack, name,
value).

load
~~~~

Introduced in: 2.4

Invoked when a config store is loaded. The signature is (store).

remove
~~~~~~

Introduced in: 2.4

Invoked when a config option is removed. The signature is (stack,
name).

save
~~~~

Introduced in: 2.4

Invoked when a config store is saved. The signature is (store).

set
~~~

Introduced in: 2.4

Invoked when a config option is set. The signature is (stack, name,
value).

ControlDirHooks
---------------

post_repo_init
~~~~~~~~~~~~~~

Introduced in: 2.2

Invoked after a repository has been initialized. post_repo_init is
called with a breezy.controldir.RepoInitHookParams.

pre_open
~~~~~~~~

Introduced in: 1.14

Invoked before attempting to open a ControlDir with the transport that
the open will use.

InfoHooks
---------

repository
~~~~~~~~~~

Introduced in: 1.15

Invoked when displaying the statistics for a repository. repository is
called with a statistics dictionary as returned by the repository and
a file-like object to write to.

LockHooks
---------

lock_acquired
~~~~~~~~~~~~~

Introduced in: 1.8

Called with a breezy.lock.LockResult when a physical lock is acquired.

lock_broken
~~~~~~~~~~~

Introduced in: 1.15

Called with a breezy.lock.LockResult when a physical lock is broken.

lock_released
~~~~~~~~~~~~~

Introduced in: 1.8

Called with a breezy.lock.LockResult when a physical lock is released.

MergeHooks
----------

merge_file_content
~~~~~~~~~~~~~~~~~~

Introduced in: 2.1

Called with a breezy.merge.Merger object to create a per file merge
object when starting a merge. Should return either None or a subclass
of ``breezy.merge.AbstractPerFileMerger``. Such objects will then be
called per file that needs to be merged (including when one side has
deleted the file and the other has changed it). See the
AbstractPerFileMerger API docs for details on how it is used by merge.

post_merge
~~~~~~~~~~

Introduced in: 2.5

Called after a merge. Receives a Merger object as the single argument.
The return value is ignored.

pre_merge
~~~~~~~~~

Introduced in: 2.5

Called before a merge. Receives a Merger object as the single
argument.

MergeDirectiveHooks
-------------------

merge_request_body
~~~~~~~~~~~~~~~~~~

Introduced in: 1.15.0

Called with a MergeRequestBodyParams when a body is needed for a merge
request.  Callbacks must return a body.  If more than one callback is
registered, the output of one callback is provided to the next.

MessageEditorHooks
------------------

commit_message_template
~~~~~~~~~~~~~~~~~~~~~~~

Introduced in: 1.10

Called when a commit message is being generated.
commit_message_template is called with the breezy.commit.Commit object
and the message that is known so far. commit_message_template must
return a new message to use (which could be the same as it was given).
When there are multiple hooks registered for commit_message_template,
they are chained with the result from the first passed into the
second, and so on.

set_commit_message
~~~~~~~~~~~~~~~~~~

Introduced in: 2.4

Set a fixed commit message. set_commit_message is called with the
breezy.commit.Commit object (so you can also change e.g. revision
properties by editing commit.builder._revprops) and the message so
far. set_commit_message must return the message to use or None if it
should use the message editor as normal.

MutableTreeHooks
----------------

post_build_tree
~~~~~~~~~~~~~~~

Introduced in: 2.5

Called after a completely new tree is built. The hook is called with
the tree as its only argument.

post_commit
~~~~~~~~~~~

Introduced in: 2.0

Called after a commit is performed on a tree. The hook is called with
a breezy.mutabletree.PostCommitHookParams object. The mutable tree the
commit was performed on is available via the mutable_tree attribute of
that object.

post_transform
~~~~~~~~~~~~~~

Introduced in: 2.5

Called after a tree transform has been performed on a tree. The hook
is called with the tree that is being transformed and the transform.

pre_transform
~~~~~~~~~~~~~

Introduced in: 2.5

Called before a tree transform on this tree. The hook is called with
the tree that is being transformed and the transform.

start_commit
~~~~~~~~~~~~

Introduced in: 1.4

Called before a commit is performed on a tree. The start commit hook
is able to change the tree before the commit takes place. start_commit
is called with the breezy.mutabletree.MutableTree that the commit is
being performed on.

StatusHooks
-----------

post_status
~~~~~~~~~~~

Introduced in: 2.3

Called with argument StatusHookParams after Breezy has displayed the
status. StatusHookParams has the attributes (old_tree, new_tree,
to_file, versioned, show_ids, short, verbose). The last four arguments
correspond to the command line options specified by the user for the
status command. to_file is the output stream for writing.

pre_status
~~~~~~~~~~

Introduced in: 2.3

Called with argument StatusHookParams before Breezy displays the
status. StatusHookParams has the attributes (old_tree, new_tree,
to_file, versioned, show_ids, short, verbose). The last four arguments
correspond to the command line options specified by the user for the
status command. to_file is the output stream for writing.

TransportHooks
--------------

post_connect
~~~~~~~~~~~~

Introduced in: 2.5

Called after a new connection is established or a reconnect occurs.
The sole argument passed is either the connected transport or smart
medium instance.

RioVersionInfoBuilderHooks
--------------------------

revision
~~~~~~~~

Introduced in: 1.15

Invoked when adding information about a revision to the RIO stanza
that is printed. revision is called with a revision object and a RIO
stanza.


