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