3
A plugin is an external component for Bazaar-NG that is typically made by
4
third parties. A plugin is capable of augmenting Bazaar-NG by adding or
5
replacing new or current functionality in Bazaar-NG. Plugins often work as
6
a way for developers to test new features for Bazaar-NG prior to inclusion
7
in the official codebase. Plugins can do a variety of things, including
8
overriding commands, adding new commands, providing additional network
9
transports, customizing log output. The sky is the limit for the
10
customization that can be done through plugins.
14
We keep our list of plugins on the http://bazaar-vcs.org/PluginRegistry page.
18
Plugins are very similar to bzr core functionality. They can import
19
anything in bzrlib. A plugin may simply override standard functionality,
20
but most plugins supply new commands.
22
To create a command, make a new object that derives from
23
`bzrlib.commands.Command`, and name it cmd_foo, where foo is the name of
24
your command. If you create a command whose name contains an underscore,
25
it will appear in the UI with the underscore turned into a hyphen. For
26
example, "cmd_baz_import" will appear as "baz-import". For examples of how
27
to write commands, please see builtins.py.
29
Once you've created a command you must register the command with
30
`bzrlib.commands.register_command(cmd_foo)`. You must register the command
31
when your file is imported, otherwise bzr will not see it.
33
Bzr will scan **bzrlib/plugins** and **~/.bazaar/plugins** for plugins by
34
default. You can override this with **BZR_PLUGIN_PATH**. Plugins may be
35
either modules or packages. If your plugin is a single file, you can
36
structure it as a module. If it has multiple files, or if you want to
37
distribute it as a bzr branch, you should structure it as a package, i.e. a
38
directory with an **__init__.py** file.
40
Please feel free to contribute your plugin to BzrTools, if you think it
41
would be useful to other people.
43
How to Install a plugin
44
=======================
45
Installing a plugin is very easy! One can either install a plugin
46
systemwide or on a user by user basis. Both methods involve create a
47
"plugins" directory. Within this directory one can place plugins in
48
subdirectories. For example, "plugins/bzrtools/".
50
Two locations are currently checked; the bzrlib/plugins directory
51
(typically found in /usr/lib/python2.4/site-packages/bzrlib/plugins/) and
52
$HOME/.bazaar/plugins/.
54
One can additionally override the home plugins by setting the environment
55
variable BZR_PLUGIN_PATH to a directory that contains plugins. The
56
installation of a plugin can be checked by running **bzr plugins** at
57
any time. New commands can be seen by running **bzr help commands**.
59
Plugins work particularly well with Bazaar-NG branches. For example, to
60
install the bzrtools plugins for your main user account, one can perform
63
bzr branch http://panoramicfeedback.com/opensource/bzr/bzrtools
64
~/.bazaar/plugins/bzrtools
added
removed
doc/plugins.txt
