A version control system is a must-have for every software developer. Read about our preliminary considerations, our experience with Bazaar and take your first steps with a small tutorial.

As we started to develop software products in a team years ago, we realized the necessity to track changes in our work over time and to easily collaborate with colleagues. There are different tools available, such as Git or Mercurial. And, of course, the old good Subversion. We considered different systems from our point of view.

Some of our developers work on Macs, while some others use Windows machines. It is necessary, since we offer the majority of our software products for both operating systems. So one of the requirements for a system that should manage the version control was its flawless integration in multiple plattforms. One of the best things (if not the very best one) about distributed version control systems is the ability to work offline without any connection to some server. Every local branch (a folder under revision control) is fully functional, and the work on your laptop can be done  virtually from anywhere (consider hours of boredom at an airport or tuning your software on a customer's location). You can commit your changes step by step, and when you are back in the office or have a VPN connection established, merge your changes into the main branch. For different projects we have had developers spread over various locations, who were able to collaborate without any drawbacks, pushing into the main branch and pulling the colleagues' changes now and then. Even those, who prefer the centralized workflow, will not be disappointed by Bazaar, since it is also provided.

But enough theory – how can you do this in practice? First of all, grab the free latest version from Canonical's site (http://bazaar.canonical.com). By the way, Canonical developed Bazaar for they own needs of working on one of the most popular Linux distributions – Ubuntu. They provide packages and installation instructions for many operating systems. If you are not afraid of working with command line, you can use a very intuitive command set (such as "bzr branch", "bzr log" or "bzr commit"). My personal favorite is Bazaar Explorer – an excellent GUI client that is very helpful to get familiar with the system.

bazaar explorer

Create a Bazaar user, so that your colleagues can see, who made the changes. Go to Setting|Configuration|User Configuration, or type in your command window:

C:\> bzr whoami "John Doe <>"

Create a repository that will contain a main branch (and maybe other branches later), accessible by all developers, and initialize it. The following command will create a new folder at the specified location and initialize the repository in a single step :

C:\> bzr init-repo S:\TestRepository

Shared repository with trees (format: 2a)
shared repository: S:/TestRepository

Initialize a trunk ("trunk" is a common name for the main branch) inside your repository. Here, you also don't have to create the foler on your own. Bazaar will do this for you:

C:\> bzr init S:\TestRepository\trunk

Created a repository tree (format: 2a)
Using shared repository: S:/TestRepository/

Now get a branch of your server trunk in your local project folder. Obviously, there is no content inside, but Bazaar will recognize it as a branch. It keeps a folder .bzr, which stores the knowledge about the revisions and branch relationships.

C:\> bzr branch S:\TestRepository\trunk C:\MyProject\trunk

Branched 0 revision(s).

Now put your first files into your local trunk, add them to revision control and make an initial commit (I will create an empty file myFirstFile.txt).

C:\>cd C:\MyProject\trunk

C:\MyProject\trunk>bzr add
adding myFirstFile.txt

C:\MyProject\trunk>bzr commit -m "Initial commit"
Committing to: C:/MyProject/trunk/
added myFirstFile.txt
Committed revision 1.

Push your local trunk's contents to the server trunk, so your colleagues can benefit from your work. Use the --remember option to avoid selecting the target every time:

C:\MyProject\trunk>bzr push --remember S:\TestRepository\trunk
All changes applied successfully.
Pushed up to revision 1.

You will see that your server trunk folder now also contains your file. From this point, any other developer could get a branch from the server trunk and work locally. It is a good idea to make a couple more local branches where you can develop features and fix bugs independently. Often, a hotfix is something that can't wait, while the feature you work on is still under construction. We will create a branch "working", where we will conduct all our work. If you wish, you could make one more branch for a bugfix and merge the changes back, without putting your uncomplete work into the trunk. As you see, branching in Bazaar is pretty straight-forward:

C:\MyProject\trunk>cd ..

C:\MyProject>bzr branch trunk working
Branched 1 revision(s).

Your working branch is now a copy of your local trunk. Now, change the contents of the text file in your work branch and merge your work back into the local trunk.

C:\MyProject>cd working

C:\MyProject\working>bzr commit -m "Changes applied"
Committing to: C:/MyProject/working/
modified myFirstFile.txt
Committed revision 2.
C:\MyProject\working>cd ../trunk

C:\MyProject\trunk>bzr merge ../working
M  myFirstFile.txt
All changes applied successfully.

You could do this a couple of times, but we assume, that your work is done for first. You have to commit your merged changes in your local trunk:

C:\MyProject\trunk>bzr commit -m "Feature A done"
Committing to: C:/MyProject/trunk/
modified myFirstFile.txt
Committed revision 2.

And now, you can push your changes to the server again, to make your work available for others:

C:\MyProject\trunk>bzr push
Using saved push location: S:/TestRepository/trunk/
All changes applied successfully.
Pushed up to revision 2.

Let's see, how does the log of your server trunk look now.

C:\MyProject\trunk>bzr log S:\TestRepository\trunk
revno: 2 [merge]
committer: Borys Golik <>
branch nick: trunk
timestamp: Fri 2012-02-17 16:05:00 +0100
Feature A done
revno: 1
committer: Borys Golik <>
branch nick: trunk
timestamp: Fri 2012-02-17 15:21:19 +0100
Initial commit
Use --include-merges or -n0 to see merged revisions.

Or, a more convenient way, see the log from Bazaar Explorer:

bazaar explorer

Play around with the log window and try the "Diff" button on the different revisions – you will like it! And don't forget to pull the changes, that your colleagues may have made, into your local trunk every now and then, propagating the changes into your working branch if necessary.

During the work with your colleagues, Bazaar will help you to merge different branches. If there is a conflict, e.g. you and your colleague have changed the same line in a file, you will get a conflict which you have to solve manually. Bazaar is great, but it still doesn't know, which piece of code is the right one. Since you take any files under revision control, you should consider the pitfall concerning binary (not text based) files. If two users change the contents of such a file, it will be impossible to merge both changes. You will still have a chance to take one version, or another, but not the one containing both changes. We used to live with this handicap, so whenever a change on a binary file is necessary, it can be pushed back to the server trunk and all colleagues pull the changed version, before applying their own modifications.