~bzr-pqm/bzr/bzr.dev : contents of doc/en/user-guide/writing_a

~bzr-pqm/bzr/bzr.dev : (revision 5409.4.1)

Writing a plugin
================

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

Plugins are very similar to bzr core functionality.  They can import
anything in bzrlib.  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
``bzrlib.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
``bzrlib.commands.register_command(cmd_foo)``.  You must register the
command when your file is imported, otherwise bzr will not see it.

Installing a hook
-----------------

See `Using hooks`_.

 .. _Using hooks: hooks.txt


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
----------------------

Bzr will scan ``~/.bazaar/plugins``  and ``bzrlib/plugins`` for plugins
by default.  You can override this with  ``BZR_PLUGIN_PATH``
(see `User Reference <../user-reference/bzr_man.html#bzr-plugin-path>`_
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 bzr 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 BzrTools, if you think it
would be useful to other people.

See the `Bazaar Developer Guide`_ for details on Bazaar's development
guidelines and policies.

.. _Bazaar Developer Guide: ../developer-guide/HACKING.html

2977.1.1 by Ian Clatworthy First cut at new look User Guide including chapters 1 and 2	1	Writing a plugin
	2	================
	3
	4	Introduction
	5	------------
	6
	7	Plugins are very similar to bzr core functionality. They can import
	8	anything in bzrlib. A plugin may simply override standard functionality,
	9	but most plugins supply new commands.
	10
	11	Creating a new command
	12	----------------------
	13
	14	To create a command, make a new object that derives from
	15	``bzrlib.commands.Command``, and name it ``cmd_foo``, where foo is the name of
	16	your command. If you create a command whose name contains an underscore,
	17	it will appear in the UI with the underscore turned into a hyphen. For
	18	example, `cmd_baz_import` will appear as `baz-import`. For examples of how
	19	to write commands, please see ``builtins.py``.
	20
	21	Once you've created a command you must register the command with
	22	``bzrlib.commands.register_command(cmd_foo)``. You must register the
	23	command when your file is imported, otherwise bzr will not see it.
	24
5168.2.1 by Andrew Bennetts Add example merge_file_content hook based on my answer to <https://answers.edge.launchpad.net/bzr/+question/103163>.	25	Installing a hook
	26	-----------------
	27
	28	See `Using hooks`_.
	29
	30	.. _Using hooks: hooks.txt
	31
	32
3777.6.2 by Marius Kruger Give an indication of how to specify a plugin version number	33	Specifying a plugin version number
	34	----------------------------------
	35	Simply define ``version_info`` to be a tuple defining the current version
	36	number of your plugin. eg.
	37	``version_info = (0, 9, 0)``
	38	``version_info = (0, 9, 0, 'dev', 0)``
	39
2977.1.1 by Ian Clatworthy First cut at new look User Guide including chapters 1 and 2	40	Plugin searching rules
	41	----------------------
	42
4628.2.3 by Vincent Ladeuil Update doc and add NEWS entry.	43	Bzr will scan ``~/.bazaar/plugins`` and ``bzrlib/plugins`` for plugins
	44	by default. You can override this with ``BZR_PLUGIN_PATH``
	45	(see `User Reference <../user-reference/bzr_man.html#bzr-plugin-path>`_
	46	for details).
	47
	48	Plugins may be either modules or packages. If your plugin is a single
	49	file, you can structure it as a module. If it has multiple files, or if
	50	you want to distribute it as a bzr branch, you should structure it as a
2977.1.1 by Ian Clatworthy First cut at new look User Guide including chapters 1 and 2	51	package, i.e. a directory with an ``__init__.py`` file.
	52
	53	More information
	54	----------------
	55
	56	Please feel free to contribute your plugin to BzrTools, if you think it
	57	would be useful to other people.
	58
	59	See the `Bazaar Developer Guide`_ for details on Bazaar's development
	60	guidelines and policies.
	61
	62	.. _Bazaar Developer Guide: ../developer-guide/HACKING.html