Tutorial: Bazaar Version Control

Semi-inspired by this thread Why you should care about version control, and why I suggest git - Programming - Chief Delphi (would recommend reading that thread as well) I find Bazaar is an easy to use source code revision tool that should leave teams with a warm productive feeling during the build season.

Here’s what you might be using right now to go back to earlier versions of your teams code:

The problem with organizing dated code like this:

  • Annoying
  • Really, it’s unorganized
  • Directories pile up
  • Disk space piles up
  • Inefficient
  • Not very good for exporting

There’s a way to avoid this, and just have your original code structure, no repetitions. Imagine this:

  • One single directory for code
  • Every revision can be tagged
  • A detailed log of every revision
  • Easy exports
  • Easily push and pull from a server or another computer
  • Way easier to restore and keep track of the current working
    code

You can have the same features as the picture above (plus more), and have it looking like this:

That one folder hierarchy, stores all your previous revisions/dates of code. Liking this concept? Now to show you how.

Note: Bazaar is my personal favourite decentralized SRCS out there. If you have an enterprise of teams that want to share code among themselves (hey! anybody want to host a source code server for FIRST teams?) then an alternative such as git/svn might be better.****

Anyhow, Bazaar is available at their website for Windows, Mac, Ubuntu and a whole boatload of other platforms. In Ubuntu it’s available under Synaptic as “bzr”

It comes by default as a command-line interface but each platform has many GUI’s for it (most bundled with the Bazaar binaries/source code).

I’ll let you figure out how to install it for yourself, it’s quick and easy but writing here on how for each platform might take a while :wink:

Anyways once you’ve got it up and running the first thing we have to do is identify yourself - you should do this for all new users. This solves the great question of “Who made the code stop working?” :wink:

In the CLI:


bzr whoami "Andrew H. [email protected]"

Of course enter your own name and email address. If you commit a revision without running this command you will get an identifier based on the computer’s current session, i.e. “user@programminglaptop”

In the CLI:


cd ~/RobotCode09
bzr init

Running the bzr application with the argument “init” will create a branch from the current directory. You can now manipulate the directory.

Currently, the branch is entirely blank - files need to be added. Everytime you want to send off a new revision, you’ll need to add the files you’ve created since the last revision.

When first initializing a branch in a directory, you’ll want to commit the initial data. Start by adding the files using the “add” argument.

In the CLI:


cd ~/RobotCode09
bzr add

This adds every file in the directory to the branch, and finally, the very point to source code revision control, submitting a revision. Everytime you wish to create a “savepoint” in your code, simply add the news files (if any) and commit the revision. We can use the “commit” argument to send a new revision, but we’ll also want to add a message for the logs. For this we use…

In the CLI:


cd ~/RobotCode09
bzr commit -m "All of our initial code and docs, yay!"

We now have created a brand spanking new branch and added the original files. Let’s put it all together now.


cd ~/RobotCode09
bzr init
bzr add
bzr commit -m "All of our initial code and docs, yay!"
# We now have a branch.  Revision #1

Now whenever you make changes to your code…


bzr add
bzr commit -m "New revision..."
# Revision x

Unless you only want to make a revision based on edited files, you’ll need to add the files. However you can always merge the two commands together with the pipe.


# We've edited some code, and added a new library!
bzr add | bzr commit -m "New revision..."
# Added all files and commited revision.

Now you’re all setup, those are the absolute basics - Bazaar has so much to offer besides that.

The next step is to be able to view your logs, and revert back to an old revision if the worst happens. You can view the entire revision log with the “log” argument.


bzr log
# Displays log.

Sometimes the log will be a very large buffer and will need to be placed in a text file so you can read the whole thing. We can do this very simply.


bzr log > "Log01_01_2010.txt"

You can then open the logfile up in your favourite text editor/viewer.

Unfortunately the log only provides so much information using the bare minimum commands as we did above. What you’ll find so far:

  • The revision number
  • The committer - who sent the commit command, based off the above “whoami” argument.
  • Branch nickname (directory name)
  • Time of commitment
  • Message provided at the time.
  • Tags (see below)

Especially in the world of robotics you’re definitely looking for more information than that. Luckily the “log” argument has even more sub-arguments to it. Such as the -v option; this allows makes the log display details on which files were edited, added and removed.


bzr log -v > "Log01_01_2010__Detailed.txt"

Yet still, there’s something missing that can help quite dearly. TAGS! Wouldn’t you love to mark all revisions with completely working code - you know the ones that made the robot loop around the field and not nearly run over a mentor? Luckily we can do this :slight_smile:

Tagging a revision is simple enough with the “tag” argument. By default running this command will tag the current revision but you can also use the -r to tag older revisions. For example…


bzr tag "works, epic, didnotfail, autonomous" # Tags current revision with "works", "epic", "didnotfail", and "autonomous"
bzr tag -r 5 "old" # Tags revision number 5 with "old"

Perfect eh? Now to find revisions based on their tags…

You can list all tags with their revision number associated beside it…


bzr tags # List all tags

or, get the log of revisions by a tag…


bzr log -r tag:works

Finally the greatest part of them all - restoring a revision. This is as simple as “revert”


bzr log # Find the revision
bzr revert -r 5 # Revert to Revision Number 5.

Let’s put it all together shall we.


# We have some code in a directory that we want to put under revision control.
cd ~/RobotCode09
bzr whoami "Andrew H. <[email protected]>"
bzr init
bzr add | commit -m "Initial initialization"
bzr tag "works"
# <we edit some code>
bzr add | commit -m "Changed code, edited autonomous."
# ~~~Days later upon many revisions we find that we added some code in an earlier revision that caused a malfunction in the robot.
bzr log # Where was that revision that worked?
bzr log -r tag:works
# <Returns Revision 1>
bzr revert -r 1
# Yay everything works, hurry for Bazaar!

It’s actually that simple really. There’s one more really great thing you can do however. Let’s say you have autonomous.c and rc.c and we want to restore only autonomous.c to an earlier revision. We can do that :slight_smile: The “cat” argument grabs a file from a previous revision (using -r )


bzr cat -r 1 autonomous.c > autonomous.c
bzr commit -m "Restored autonomous back to a working point."
bzr tag "works"

And the big finish, pushing and pulling to/from a server. Let’s say that we have one main coding computer and the team’s programmers all have their own laptop. They want to commit there changes to a server. So we use the push and checkout commands!


mkdir RobotCode09 # Create a directory for the code
bzr checkout G:/CurrentRobotCode # Get all the code from the shared folder
# Make changes
bzr whoami "Team Coder. <[email protected]>"
bzr commit -m "My changes to autonomous."
bzr tag "works"
bzr push G:/CurrentRobotCode
# The rest of the team can now view and edit my code.

So there we have it, let’s have all of our teams using source code revision control!

~Happy coding!~

Thanks for this wonderful tutorial. I have heard the concept of version control before but this is my first time using it so bare with me.

What is the best way to handle two people doing a checkout, changing files, committing and pushing. If I’m not mistaken the second person will get an error when they try to push saying there local branch is out of date. If you follow the suggestion of updating then you end up with conflicts. When you use resolve you end up with a file with lines like these.

<<<<<<< TREE

>>>>>>> MERGE-SOURCE

You are then able to push but then you have those added lines to break the compiler.