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