Bazaar Explorer - Version Control for Human Beings
Bazaar Explorer - Version Control for Human Beings
Home | Note
Many of the customization features outlined below were introduced in 1.0beta. Please upgrade if you wish to use a feature not available in earlier versions.
It’s easy to customise Bazaar Explorer so that the commands you need and web sites you use are available at your fingertips. Many extension types are supported including:
More generally, Bazaar Explorer can be extended with Accessories. Your personal extensions are stored in your Wallet. To see all of the configurable objects supported, use the File ‣ Accessories dialog.
Your wallet contains a file for each extension type. Click on the links under the Wallet tab in the Accessories dialog for basic instructions. Additional help is provided below.
Items in the Working Tree browser may be either opened or edited. Opening a file runs the application configured at the operating system level to open files of that type. For a HTML file, this is usually a web browser like Firefox. When developing content though, you often want to edit a web page or image instead of viewing them. To support this, Bazaar Explorer lets you configure custom editor applications.
Note
By default, clicking an item in the status report edits it and double-clicking an item in the Working Tree browser opens it. To launch an editor on double-click instead, change the relevant preference under the Behavior tab in your preferences.
Editors are configured in a file called editors.conf. General instructions are provided at the top of the file with that name stored in your wallet. In a nutshell, editors.conf is a file in INI format where keys are file extensions and values are editor application names. For example:
[DEFAULT]
png, gif = gimp
Editors can be configured globally or per desktop environment. Browse the predefined editors using the Accessories dialog for examples.
Toolbars are stored in a file called toolbars.xml. To extend an existing toolbar, simply add a folder with a title matching an existing toolbar name. Your new toolbar items will be appended to the existing toolbar.
If you want to add an action to all toolbars, add items to folders called toolset:prefix and toolset:suffix. These items are prepended and appended to all toolbars respectively.
If you want to completely replace the contents of an existing folder (rather than append items to that folder), add the existing="replace" parameter to the folder. For example, if your want Open to be the only action appended to every toolbar, add this into your toolbars.xml file:
<folder title="toolset:suffix" existing="replace" >
<action name="Open" />
</folder>
These are stored in folders called kind:xxx. The supported kind names are given below.
| Kind | Description |
|---|---|
| welcome | The welcome page |
| repository | A shared repository |
| virtual-repository | A directory searched for nested bzr locations |
| branch | A normal branch |
| bound-branch | A branch bound to another (heavyweight checkout) |
| checkout | A working tree linked to a separate branch |
Most toolbars simply reference existing menu actions. Here are the action names you can use in toolbars.
| Menu | Action names |
|---|---|
| File | Open, Open_Location, Accessories, Close, Quit |
| Edit | Preferences |
| View | Refresh |
| Bazaar | Add, Diff, Commit, All_Commands, Plugins |
| Bazaar/Start | Initialize, Branch, Checkout |
| Bazaar/Collaborate | Pull, Merge, Update, Push, Send, Tag, Export |
| Bazaar/Explore | Log, Browse, Info, System_Info, System_Log |
| Bazaar/Work | Conflicts, Switch, Bind, Unbind, Revert, Uncommit |
| Bookmarks | Add_Bookmark, Edit_Bookmarks, Refresh_Bookmarks |
| Tools | Add_Tool, Edit_Tools, Refresh_Tools |
| Settings | Rules, Locations, Credentials |
| Settings/Configuration | Configuration, Branch_Configuration |
| Settings/Ignores | Ignores, Working_Tree_Ignores |
| Help | Help_Contents, Welcome, Get_Help_Online, Translate_This_Application, Report_a_Problem |
There are also 4 special actions for the submenus within the Bazaar menu: Start, Collaborate, Explore, Work.
To create a completely new toolbar, simply add a folder with the name of the toolbar you want as the title. After restarting Explorer, your new toolbar will be available for selection in the Preferences dialog (or Tools dialog on Windows).
You may also create your own tools and add them to toolbars. The suggested way to do this is to configure a tool in your toolbox and copy-and-paste from one file (tools.xml) into another (toolbars.xml). See below for details.
Use the Tools ‣ Add Tool dialog to add Tools. These can be accessed from either:
Each tool has a:
The following tool categories are supported:
Within the action (labelled Command on the dialog), placeholders are permitted:
Placeholders are included using the format %(name)s. To include a real % in an action, use %%.
Note
Placeholder values containing spaces ought to be quoted for you so there is no need to surround placeholders with double quotes.
If a bzr command you use isn’t already on the menus, add a tool to access it. If the command you specify looks like a QBzr or Bzr-Gtk command, it will be run directly. Otherwise, the command is run via the qrun dialog. Here are some examples.
| Command | Actual command |
|---|---|
| heads | bzr qrun –uimode heads |
| log -r-10.. | bzr qrun –umode log -r10.. |
| qlog . :parent | bzr qlog . :parent |
| qrun –category loom | bzr qrun –category loom |
| gmissing | bzr gmissing |
Note
If you specify a qbzr command, remember to use the --uimode option to keep the dialog open.
These can be really useful for accessing bug trackers, Continuous Integration tool status pages, documentation, etc.
These can be good for launching helper applications like profilers, IDEs, modelling tools, etc.
Note
It would be nice to support make, ant, etc. here. That may work via launching a shell each time. Patches welcome.
Having added tools, you can edit tools.xml (via Tools ‣ Manage Tools ‣ Edit My Tools) and organize them into folders, re-order them, etc.
Bazaar Explorer comes with the Tango icon set which provides many icons for your tools. If you want to add a custom icon for a tool or folder, create a logos directory within your wallet and put 16x16 png files in there. An icon called foo.png is available via the logical name logos/foo.
You can define extensions that only apply to selected projects by putting them into a “hat”. A hat is simply a folder under .bazaar/explorer/hats (or the equivalent location on Windows) titled xxx and containing the various configuration files for each extension type, e.g. tools.xml.
Numerous sample hats are provided out-of-the-box. You can browse these using the Hats tab on the Accessories dialog.
If you want to give your hat a custom icon, add a file called icon.png at the top level within your hat’s folder.
If your customizations may be useful to others, it’s easy to package them up and share them. There are 3 ways you can do this:
To package as a plugin, simply put your extensions within an explorer directory within a normal Bazaar plugin. Don’t forget to ensure bzr will find the plugin by also creating an __init__.py file in the top level of your plugin. See http://doc.bazaar.canonical.com/plugins/en/plugin-development.html for more general details on creating a Bazaar plugin.
Home |