You are here: Home / Devel Env / Bazaar / Introduction

Introduction to Bazaar (by Yann Pouillon)

WARNING: the description of the Abinit Forge is outdated.
Please consult the Quick Reference for up-to-date info.

Short overview

Bazaar[1] is a distributed Version Control System (VCS) available under the GNU General Public License (GPL) that aids open source development and reduces barriers to participation. Its priorities are to be safe, friendly, free and fast, and to support Windows, GNU/Linux, UNIX and the Mac OS. The main objective is to provide the user with fast and decentralised revision control that "Just Works", supporting renames of files and directories smoothly. Bazaar is designed to maximise the level of community participation in any project. Decentralized revision control systems give people the ability to collaborate more efficiently over the internet using the so-called bazaar development model (see below).

Unlike its predecessors Bazaar depends only on Python 2.4, which is a guarantee of portability, flexibility and ease of installation. Its extremely clever merge algorithms let the package maintainers focus exclusively on relevant and important conflicts and provide an advanced cherrypicking mechanism. Users start to be productive after having learned five commands only, and the information provided by the "bzr help ..." command is very complete. Partial commits and uncommits are fully supported, both for files and subdirectories, and it is possible to transfer uncommitted changes between two branches. Most parameters can be tuned very simply on a per-user or per-branch basis. A lot of plugins are already available, and it is quite easy to extend Bazaar's abilities with the help of Python scripts. Command aliases to ease the migration of former users of CVS and Subversion are even provided.

The documentation available on the Bazaar website is comprehensive and well structured, with a few sections approaching progressively industry-standard levels. Both Bazaar user and developer communities are very active and well organised, and include famous Free Software projects. Moreover the command syntax and their underlying philosophy are quite similar to what existed with the previous version of the VCS. All this will greatly ease, simplify and speed-up the transition, limiting the efforts necessary to prepare the developers of ABINIT as well. And, as a cherry upon the cake, it will not be so difficult to have Bazaar interacting with the upcoming restructured ABINIT website.

A bit of history

One of the ancestors of Bazaar is GNU Arch[2], a distributed, changeset-oriented, peer-to-peer VCS. Started in 2001, the GNU Arch project has been a leader and a contributor in the efforts of free software and open source hackers to develop revolutionary tools to advance their efforts. Its most famous implementation is the one of Tom Lord, codename TLA, which became part of the GNU project in 2003. It was adopted in 2004 by the ABINIT project, which was previously using CVS privately. At that time, distributed versioning had become necessary for us due to the source code reaching a critical size and the rate of contributions increasing more and more steeply. Specific tutorials were written as a step-in procedure for the ABINIT developers.

Despite a very promising future and the support of the Free Software Foundation, the TLA project died abruptly. In 2005, shortly after announcing a new release of his Arch 2.0 project, Tom Lord told Richard Stallman and the GNU Arch users that he was resigning as the maintainer of Arch. He recommended that Canonical Ltd's Bazaar project become the main Arch project. After getting a confirmation that the TLA project was dead, we switched to Bazaar. The existing tutorials were updated accordingly and enhanced.

The GNU Arch project has forked several times along its chaotic history, resulting in several VCS projects. The most common criticism about TLA was the lack of friendliness of its user interface, an issue Bazaar 1 (baz) did its best to address. This in turn induced many portability problems: though baz was indeed more friendly than TLA, its installation on a non-Debian-based system was a long, laborious and painful process. Shortly after the release of Bazaar 1.3, Canonical Ltd decided to put most development efforts on a new project, codename Bazaar-NG or bzr, with a clear emphasis on ease-of-use and portability. In mid-2006, the Bazaar 1 project was abruptly wiped-out from existence, and it became virtually impossible to install it on non-Linux systems. At the same time, bzr started to be used successfully at production-level in huge projects[3].

During the third ABINIT developer workshop held in Liège, Belgium, in January 2007, it was decided to switch to bzr as soon as its version 1.0 would be released and the ABINIT developers adequately prepared. The main part of the process is scheduled to start on May 2007, while the preparation is starting now. The automatic conversion of the existing ABINIT archives to the bzr format using the bzr-provided scripts has already been successfully tested, and several subprojects such as BigDFT and part of the documentation are already managed with bzr. A few ABINIT developers are now managing their other personal projects with bzr as well.

Why Bazaar?

The Bazaar project is named after Eric S. Raymond's essay, The Cathedral and the Bazaar[4], which describes and compares two software development models:

  • the Cathedral model, in which source code is available with each software release, but code developed between releases is restricted to an exclusive group of developers; GNU Emacs and GCC are presented as examples;
  • the Bazaar model, in which the code is developed over the Internet in view of the public.

Eric Raymond credits Linus Torvalds, leader of the Linux kernel project, as the inventor of the latter. He also provides anecdotal accounts of his own implementation of this model for the fetchmail project.

One of the main advantages of the Bazaar VCS is that it allows these two development models to be mixed seamlessly within the same project. Such a possibility brings forth extreme flexibility for a constantly-growing project like ABINIT, allowing dynamical restructuring of the development teams and subprojects. It is also easy to mix topic-based branches with per-developer ones.

What now?

The next part will deal with the efficient workflows matching Bazaar's philosophy usable within the ABINIT project, as well as the restructuring of the archive.

In the meantime, if you have a taste for adventure, you may already try to install Bazaar and play with it a little bit.

Those who would not have Python[5] 2.4 support available yet are kindly invited to do the necessary. If you have to request it officially and encounter some difficulty, you may argue that Python 2.4 is available since March 30th, 2005, has been thoroughly tested and bugfixed since then, and is in bugfix-only mode since October 18th, 2006.

If it is materially impossible for you to get Python 2.4 installed, please report to Yann Pouillon so that we can try to find a solution for you.

Introducing repositories, branches, and checkouts

From now on, the development of ABINIT will be managed through an ensemble of Bazaar repositories. Each repository stores a group of related branches, allowing optimisation of the management of their history. There is exactly one repository per developer, corresponding to each minor version of ABINIT. For example, when ABINIT 5.4.2 is out, new repositories will be created for the 5.5 version and developers will be invited to use them for their new developments. Another example: according to the development policy of ABINIT, when the 5.7.3 version is released, the maintainers will be able to prune history by just removing all 5.4 repositories.

The structure of a repository is basically a collection of directories containing the whole history of particular development efforts. Each of these directories is called a branch. The choice of creating branches is up to the developer and is totally free, though it is recommended to minimise their number and to organise them topically. When a branch contains a directly-usable version of the source code, it is called a working tree. With such branches it would be in principle possible to work directly within the repository, but this is not the case for ABINIT. The developers have to create working trees on their own computers either by branching or checking out, which are two ways of cloning the repository branches. It is also possible to incorporate the developments contained in one branch into another, by merging.

The difference between a Bazaar branch and a Bazaar checkout is that, in the case of a branch the history is kept locally within the working tree, while for a checkout the history is kept remotely in a repository. Please note that the remote location need not be the central ABINIT archive, but might be a repository owned by a developer. In other terms, a branch is completely autonomous, whereas a checkout still depends on a network connection. Nonetheless, if a developer needs to work off-line with a checkout, an option of bzr permits local commits, and the history will be transferred on commit when the network is available again. It is even possible to unbind a checkout temporarily from its repository in order to work locally for a longer amount of time.

The commit operation is critical, since it corresponds to the moments when history is saved, and thus to the available snapshots - aka revisions - of a development. A valuable piece of advice for any Version Control System (VCS) is: commit early, commit often! The more you commit, the easier it will be to go backwards if a problem occurs. The longer you wait before commiting your changes, the more probable it is that someone else modifies the code in such a way that a conflict occurs. If you're developing a new feature, it's probably best to land the feature as soon as it is relatively stable. This allows other developers to see what you've done, comment on it, and above all test it.


Note: this section is greatly inspired from the *Workflows* document found on the Bazaar website, at:

Bazaar supports many different kinds of workflow, ranging from centralised lock-step development to totally free-form. These are mostly separate from data-storage concerns. The workflow used by ABINIT is to be presented at the end of the section. You might skip the description of the other workflows, although they are kept for completeness.

Centralised / Lock-step

This is essentially the same as the CVS and SVN workflow. All developers work on the same branch (or branches). They run "bzr update" to get their checkout up-to-date, then "bzr commit" to commit.

Advantage over CVS and SVN: much better branching and merging.

The developers of ABINIT typically use this workflow to manage the synchronisation of their efforts between two computers, e.g. between their laptops and workstations.

Lock-step with local commits

This is essentially the same as the above, except that when developers are making a series of changes, they do "commit --local" or unbind their checkout, then commit their work to the shared mainline when it is complete.

Advantage over lock-step: less chance for a bad commit to interfere with everyone else's work.

It can profit to groups of developers involved in the same effort and who have to constantly keep up-to-date with the others. This workflow may also be used for highly experimental developments, by developers unable to refrent for committing, or when the connection to the central ABINIT archive is not permanent.

Decentralised with shared mainline

In this workflow, each developer has their own branch or branches, plus commit rights to the main branch. They do their work in their personal branch, then merge it into the mainline when it is ready.

Advantages over lock-step w/ local commits: easier organisation of work; developers can merge one another's personal branches when working on something together.

This can be typically used by a group of developers working at the same place on the same development through a local repository. When they are satisfied with the status of their code, they can push their mainline into the central ABINIT archive.

Decentralised with automatic gatekeeper

In this workflow, each developer has their own branch or branches, plus read-only access to the mainline. A software gatekeeper (e.g. a Patch Queue Manager) has commit rights to the main branch. When a developer wants their work merged, they request the gatekeeper to merge it. The gatekeeper does a merge, a compile, and runs the test suite. If the code passes, it is merged into the mainline.

Advantage over decentralised with shared mainline: code is always tested before it enters the mainline.

This is what we propose to develop in order to relieve the human gatekeeper of a substantial part of his task.

Decentralised with human gatekeeper

In this workflow, each developer has their own branch or branches, plus read-only access to the main branch. One developer (the gatekeeper) has commit rights to the main branch. When a developer wants their work merged, they ask the gatekeeper to merge it. The gatekeeper does code review, and merges the work into if it meets standards.

Advantage over decentralised with automatic gatekeeper: code is always reviewed before it enters the mainline.

This is the development model of ABINIT from 2004, and will continue to be the main way of integrating new contributions. What changes now is that the other development models can be used concurrently with no interference. As you can see, Bazaar provides a lot of freedom and flexibility.

What now?

We will speak about writing usable changelogs, give advice for merging and dealing with conflicts, and raise your awareness about some basic precautions which have to be taken in order to have everything going smoothly.

In the meantime, those who don't have Bazaar installed yet are kindly invited to do so and to report their success or failure to the GNU Arch mailing list.

Completing the Bazaar tutorials is also strongly recommended, as the next part will suppose familiarity with bzr. A list of useful commands is gathered in the next section.


Useful commands

You will need to know a few commands only to be able to unleash the great potential of Bazaar. Here is a list of the commands you will likely use most of the time:

Type ...To ...
bzr help Get help
bzr info Get detailed information about a bzr-managed directory
bzr status Get a status report about a working tree
bzr init Start a new branch from scratch
bzr branch Start a new branch from an existing one
bzr push Publish a branch to a remote location
bzr pull Synchronise a branch with a remote location
bzr checkout Create a new working tree for a remote branch
bzr update Synchronise a checkout with its parent branch
bzr commit Save a revision of a working tree
bzr merge Import the contents of another branch
bzr resolved Mark a merge conflict as resolved

You should use bzr help to know a little bit about them before using them intensely.

Branches and checkouts

The bzr branch command creates an autonomous working tree from the Forge (or from another branch). This copies down the complete history of the branch, and all operations can be performed locally. You may keep in sync with the parent branch by typing bzr pull, and publish your changes by means of bzr push.

A checkout is much like a branch, except that the history is kept on the Forge. The remote branch is thus updated each time you commit, unless you specify the "--local" option to bzr. To keep a local copy in sync with the Forge, you just need to type bzr update.

Depending on the way you work and your development environment, you may prefer one of these two methods, or use some clever combinations. The only limit is fixed by your imagination, and a little bit of thinking before starting will help you greatly.


If the working tree is empty just after having downloaded a branch, type bzr checkout to unfold it.

Moving files and directories

Bazaar handles moving and renaming files very nicely, provided that you take a few precautions. You should always issue a bzr status before moving files / directories, and check that either all or none of the involved files / directories are versioned. If not so, their history might be lost.

If none of the files is versioned, just do as if bzr didn't exist. If all files are already versioned, you should move them using the bzr mv command.

Writing usable changelogs

Supposing that you modify strongly ABINIT, your changes need to be understandable by the gatekeeper as well as by other developers.

You should write "changelogs" (this is not required for small modifications, or if you make a large number of commits, each properly described with a one line comment). Your changelogs have to follow a set of minimal rules, in particular regarding their structure. To further optimise their management, we are following the GNU changelog format. Here is a template:

One short summary line (no trailing dot)

* dir1/sub1/file1: Some changes. Make full sentences.

* dir2/sub2/file2,dir3/sub3/file3: Some other changes.
* dir4/sub4/file4: Related changes (no blank line before).

* Additional notes and issues.

Please make sure that all lines contain less than 80 characters and start at the first column (the best is to make sure that automatic wrapping is enabled in your preferred editor). This will allow automatic global changelog generation when needed.

The best practice is to write your changelogs along as you develop. It is much more efficient than waiting for commit-time, because you will remember what you have just done much more precisely than you would two or three weeks later. In the long run this will help everybody - including yourself - save a lot of time, for your changelogs will gain a lot in clarity.

For a complete reference on the topic, we refer you to the corresponding Free Software Foundation document. Reading the "Change Logs" section entirely once is highly recommended.


As ABINIT is a collective effort, committing your changes properly is a little bit more than typing bzr commit. We highly recommend that you complete the following check-list for each commit:

  1. Check the working tree with bzr status.
  2. Process files marked as unknown. Go back to step 1 until no file is marked as unknown.
  3. Write a changelog if it does not already exists.
  4. bzr commit --strict [-F logfile] (use the -F option only if your changelog is in a file).

Partial commits are possible by adding files and directories at the end of the command-line (use with care).


Make sure that the EDITOR environment variable is set before committing.

Merging branches

When you want to import the contents of a branch into another one, you will type bzr merge branch_url and let Bazaar do the job for you. Merge will automatically calculate the changes that exist in the branch you're merging from and which are not in yours, then attempt to apply them to your branch.

If you are careful enough and merge the branches you need into yours regularly, most of your merges will be straightforward. However, sooner or later, you will run into a conflict with someone else's contributions. Though solving conflicts is rarely a delicate matter, it has to be done manually and methodically.

If you want things to go smoothly in all cases, you do have to take a systematic precaution: always commit your latest changes before merging. If something goes wrong, or if it takes a lot of time to solve the conflicts, you will still be able to continue to develop in parallel within the unmerged branch. The same applies once you are satisfied: always commit immediately after a successful merge. Then, and only then, you may continue safely your developments.

Solving conflicts

In case of conflict, 3 files with the same basename are created. The filename of the common base (i.e. before divergence) is appended with .BASE, the filename of the file containing your changes is appended with .THIS, and the filename with the changes from the other tree is appended with .OTHER.

Using a program such as kdiff3 or xxdiff, you can comfortably merge them into one file and save the result as the orginal filename. With kdiff3 the command-line will look like:

kdiff3 myfile.BASE myfile.OTHER myfile.THIS

and the resulting file should be saved as myfile.

Before committing you must use the bzr resolve myfile command, which will remove the .OTHER, .THIS and .BASE files. Always use it with great care, and keep in mind that, if myfile does not exist when you call bzr resolve, it will just be considered as removed by bzr.

Moving changes between trees

When you make changes in the wrong tree, or when the changes turn out to be bigger than expected, you may want to start a new branch. To move your changes from one tree (OLDDIR) to another (NEWDIR), just type:

bzr merge --uncommitted OLDDIR

This will apply all of the uncommitted changes you made in OLDDIR to NEWDIR. It will not apply committed changes, even if they would be applied to NEWDIR with a regular merge. The changes will remain in OLDDIR, but you can use bzr revert OLDDIR to remove them, once you're satisfied with NEWDIR.

Note: NEWDIR does not have to be a copy of OLDDIR, but they should be related. The more different they are, the greater the chance of conflicts.


This little tour in "Bazaarland" is now finished. You should now be able to use bzr efficiently in the context of ABINIT, provided that you do your part of the deal, which is: PRACTICE!