Chief Delphi - Tutorial: Bazaar Version Control

Semi-inspired by this thread http://www.chiefdelphi.com/forums/sh...ad.php?t=79446 (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:
http://i50.tinypic.com/wwkkr8.jpg

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:
http://i50.tinypic.com/wu2v7m.jpg

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 ;)

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?" ;)

In the CLI:

Code:

bzr whoami "Andrew H. minirobotics@gmail.com"

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:

Code:

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:

Code:

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:

Code:

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.

Code:

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...

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.

Code:

# 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.

Code:

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.

Code:

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.

Code:

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 :)

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...

Code:

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...

Code:

bzr tags # List all tags

or, get the log of revisions by a tag...

Code:

bzr log -r tag:works

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

Code:

bzr log # Find the revision

bzr revert -r 5 # Revert to Revision Number 5.

Let's put it all together shall we.

Code:

# We have some code in a directory that we want to put under revision control.

cd ~/RobotCode09

bzr whoami "Andrew H. <minirobotics@gmail.com>"

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 :) The "cat" argument grabs a file from a previous revision (using -r <revision number>)

Code:

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!

Code:

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. <coder778@frc9999.net>"

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!~