Writing a plugin — Breezy 3.0.2dev documentation

Table of Contents (3.0.2dev)

# Writing a plugin

## Introduction

Plugins are very similar to brz core functionality. They can import anything in breezy. A plugin may simply override standard functionality, but most plugins supply new commands.

## Creating a new command

To create a command, make a new object that derives from `breezy.commands.Command`, and name it `cmd_foo`, where foo is the name of your command. If you create a command whose name contains an underscore, it will appear in the UI with the underscore turned into a hyphen. For example, cmd_baz_import will appear as baz-import. For examples of how to write commands, please see `builtins.py`.

Once you’ve created a command you must register the command with `breezy.commands.register_command(cmd_foo)`. You must register the command when your file is imported, otherwise brz will not see it.

## Installing a hook

See Using hooks.

## Specifying a plugin version number

Simply define `version_info` to be a tuple defining the current version number of your plugin. eg. `version_info = (0, 9, 0)` `version_info = (0, 9, 0, 'dev', 0)`

## Plugin searching rules

Breezy will scan `~/.config/breezy/plugins` and `breezy/plugins` for plugins by default. You can override this with `BRZ_PLUGIN_PATH` (see User Reference for details).

Plugins may be either modules or packages. If your plugin is a single file, you can structure it as a module. If it has multiple files, or if you want to distribute it as a brz branch, you should structure it as a package, i.e. a directory with an `__init__.py` file.

## More information

Please feel free to contribute your plugin to Breezy, if you think it would be useful to other people.

See the Breezy Developer Guide for details on Breezy’s development guidelines and policies.