Introduction

bzrlib has a very flexible internal structure allowing plugins for many operations. Plugins can add commands, new storage formats, diff and merge features and more. This document provides an overview of the API and conventions for plugin authors.

If you’re writing a plugin and have questions not addressed by this document, please ask us.

Structure of a plugin

Plugins are Python modules under bzrlib.plugins. They can be installed either into the PYTHONPATH in that location, or in ~/.bazaar/plugins.

Plugins should have a setup.py.

As for other Python modules, the name of the directory must match the expected name of the plugin.

Plugin metadata before installation

Plugins can export a summary of what they provide, and what versions of bzrlib they are compatible with. This allows tools to be written to work with plugins, such as to generate a directory of plugins, or install them via a symlink/checkout to ~/.bazaar/plugins.

This interface allows bzr to interrogate a plugin without actually loading it. This is useful because loading a plugin may have side effects such as registering or overriding commands, or the plugin may raise an error, if for example a prerequisite is not present.

if __name__ == 'main':
    setup(...)

# (look for a .hg directory)
bzr_control_formats = {"Mercurial":{'.hg/': None}}

# (look for a file called .svn/format with contents 4\n).
bzr_control_formats = {"Subversion":{'.svn/format': '4\n'}}

#!/usr/bin/env python2.4
from distutils.core import setup

bzr_plugin_name = 'demo'
bzr_commands = [
    'new-command',
    ]

bzr_branch_formats = {
    "Branch label on disk\n":"demo branch",
    }

bzr_control_formats = {"Subversion":{'.svn/format': '4\n'}}

bzr_transports = ["hg+ssh://"]

bzr_plugin_version = (1, 3, 0, 'dev', 0)
bzr_minimum_version = (1, 0, 0)

if __name__ == 'main':
    setup(name="Demo",
          version="1.3.0dev0",
          description="Demo plugin for plugin metadata.",
          author="Canonical Ltd",
          author_email="[email protected]",
          license = "GNU GPL v2",
          url="https://launchpad.net/bzr-demo",
          packages=['bzrlib.plugins.demo',
                    'bzrlib.plugins.demo.tests',
                    ],
          package_dir={'bzrlib.plugins.demo': '.'})

Plugin metadata after installation

After a plugin has been installed, metadata can be more easily obtained by looking inside the module object – in other words, for variables defined in the plugin’s __init__.py.

from bzrlib.api import require_api

require_api(bzrlib, (1, 11, 0))

version_info = (1, 10, 0)

if __name__ == 'bzrlib.plugins.loggerhead':
    # register with bzrlib...

Plugin performance

Plugins should avoid doing work or loading code from the plugin or external libraries, if they’re just installed but not actually active, because this slows down every invocation of bzr. The bzrlib APIs generally allow the plugin to ‘lazily’ register methods to invoke if a particular disk format or seen or a particular command is run.

Plugin registrations

The plugin __init__.py runs when the plugin is loaded during bzr startup. Generally the plugin won’t want to actually do anything at this time other than register or override functions to be called later.

The plugin can import bzrlib and call any function. Some interesting APIs are described in Bazaar Plugins Guide.

Publishing your plugin

When your plugin is basically working you might like to share it with other people. Here are some steps to consider:

• make a project on Launchpad.net like <https://launchpad.net/bzr-fastimport> and publish the branches or tarballs there
• include the plugin in <http://wiki.bazaar.canonical.com/BzrPlugins>
• post about it to the bazaar-announce list at lists.canonical.com