/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to doc/en/user-guide/plugins.txt

  • Committer: Ian Clatworthy
  • Date: 2007-11-21 07:39:16 UTC
  • mto: (3054.1.1 ianc-integration)
  • mto: This revision was merged to the branch mainline in revision 3055.
  • Revision ID: ian.clatworthy@internode.on.net-20071121073916-qlpp5gvcf0639r38
1st cut at the 'Personal version control' chapter

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/user-guide/plugins.txt
 
1
Using plugins
 
2
=============
 
3
 
 
4
.. Information on how to use plugins in Bazaar.
 
5
 
 
6
What is a plugin?
 
7
-----------------
 
8
 
 
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
 
15
overriding commands, adding new commands, providing additional network
 
16
transports, or customizing log output. The sky is the limit for the
 
17
customization that can be done through plugins.
 
18
 
 
19
Where to find plugins 
 
20
---------------------
 
21
 
 
22
We keep our list of plugins on the http://bazaar-vcs.org/BzrPlugins page.
 
23
 
 
24
How to install a plugin 
 
25
-----------------------
 
26
 
 
27
Installing a plugin is very easy! One can either install a plugin
 
28
system-wide or on a per user basis. Both methods involve creating a
 
29
``plugins`` directory. Within this directory one can place plugins in
 
30
subdirectories. For example, ``plugins/bzrtools/``.
 
31
 
 
32
Two locations are currently checked:  the bzrlib/plugins directory
 
33
(typically found in ``/usr/lib/python2.4/site-packages/bzrlib/plugins/``) and
 
34
``$HOME/.bazaar/plugins/``.
 
35
 
 
36
One can additionally override the home plugins by setting the environment
 
37
variable ``BZR_PLUGIN_PATH`` to a directory that contains plugins. The
 
38
installation of a plugin can be checked by running ``bzr plugins`` at
 
39
any time. New commands can be seen by running ``bzr help commands``.
 
40
The commands provided by a plugin are shown followed by the name of the
 
41
plugin in brackets.
 
42
 
 
43
Plugins work particularly well with Bazaar branches. For example, to
 
44
install the bzrtools plugins for your main user account, one can perform
 
45
the following:: 
 
46
 
 
47
    bzr branch http://panoramicfeedback.com/opensource/bzr/bzrtools
 
48
    ~/.bazaar/plugins/bzrtools
 
49
 
 
50
When installing plugins the directories that you install them in must
 
51
be valid python identifiers. This means that they can only contain
 
52
certain characters, notably they cannot contain hyphens (``-``). Rather
 
53
than installing ``bzr-gtk`` to ``~/.bazaar/plugins/bzr-gtk``, install it
 
54
to ``~/.bazaar/plugins/gtk``.
 
55
 
 
56
Listing the installed plugins
 
57
-----------------------------
 
58
 
 
59
To do this, use the plugins command like this::
 
60
 
 
61
    bzr plugins
 
62
 
 
63
The name, location and version of each plugin installed will be displayed.
 
64
 
 
65
Popular plugins
 
66
---------------
 
67
 
 
68
Here is a sample of some of the more popular plugins:
 
69
 
 
70
* TODO ...
 
71
 
 
72
If you wish to write your own plugins, it is not difficult to do.
 
73
See `Writing a plugin`_ in the appendices to get started.