Software Version Control With Subversion

Subversion doesn't refer to the early stages of the robot uprising. Subversion is an open source package for source code version control. It also works for version control on hardware designs. There's too much to cover in one post, so I'll hit the basics to get you started..

Why Version Control?
Why might the roboticist care about version control, you may inquire? Simple. It's like a giant undo button when you screw up the project (notice I didn't say if). It also helps you experiment with changes. And it's useful to coordinate various hardware, firmware, and software changes together.

For example... the client and server code I wrote for capturing images off the Game Boy Camera is very persnickety. I tweak one thing in firmware or client software and it all goes to heck. So if I want to make changes, I save the working version of the code and try the changes. If they fail miserably I can revert back. If they work I can commit those changes to the server.

Ok, great, let's get started...

Version Control Software Tools

I chose Subversion for no other reason than some folks at work use it and they are smart, so it must be pretty good. :) To get started, you'll need a client and a server.

Subversion Server

You need a place to store the checked in files. I originally installed VisualSVN Server for Windows but they started requiring VisualStudio integration.

Instead, use the command line Subversion and create a file-based repository. Light, simple, fast. First, install win32svn from Sourceforge, or install the appropriate binaries for your system.

To create a new repository (windows) use the following command.

svnadmin create c:\svnrepos

I prefer to create a single repository on the local system and use folders under it for each project. Once you have the repository created, you can do everything else with your IDE and/or GUI-based client.

Subversion Client

If your development environment doesn't support Subversion directly (like Arduino IDE or Eagle CAD), you'll need client software. I wanted something cross-platform, GUI based, and free. I chose RapidSVN which offers Windows MSI and Mac OS X dmg installers.

With it, I can develop on the Mac or PC and check in code to my Windows server (or Google Code). I could expose my PC the internet if I need to access it remotely. Neat.

The RapidSVN documentation is pretty helpful.

And here's a comparison of Subversion Clients in case it is helpful.

Putting Your Project Under Version Control

Adding an Existing Arduino Project

You've got an existing Arduino project and now you want to add it into the repository you created above. Here's how.

Over in the RapidSVN client, select Add Existing Repository... from the Bookmarks menu and type in the path to your repository. This bookmarks the main code repository. For the example above, I used file:///c:/svnrepos/

Now click on the new bookmark. The right panel will display the list of folders in that repository. Well, there aren't any yet, are there? So let's create one. Right click in the right pane and select Make directory.... Type in the name of your project (e.g., ARM) and the folder will be created.

Next, right click on the new folder  and select Checkout New Working Copy... Then click the [...] button next to the Destination Directory text field and select the folder where your Arduino code lives. Click OK in the Checkout dialog. (in the screen capture below, notice the URL is actually a network server not a file; you'd see file:///c:/svnrepos/ for the example above).

After the screen refreshes, in the right hand pane you should see a list of the files in that directory labeled "unversioned" with a question mark icon.

Select the files you want under source code version control, right click, and select Add from the contextual menu. They're added to version control but not yet uploaded to the server.

After adding, notice the orange icon next to the file. That indicates the local version is newer than the server version or that the local version isn't present on the server.

Select the files you just added, right click and select Commit to check these files in, uploading them to the server. Enter some notes about each change you commit.

You'll notice the icon next to the files is now a white document. That means the server and local version are identical. Yay!

Now you can get started using version control while you work.

Version Control Tutorial

Check In Changes

You make some changes in the code, test it out, make sure it's working (best to try to check in only working code). Now it's time to check in. If your IDE supports Subversion, check the documentation on how to check in documents.

Otherwise, open RapidSVN and assuming you've already done the steps above, browse to the working copy bookmark corresponding to your project. Drill down to find the files you've changed. They will have orange icons next to the filenames.

Use CTRL+left-click to select all the files you changed and click the commit button on the button bar (see picture to the right)

Now type in what you changed into the dialog box and click the OK button and the files will be updated on the server..

Revert Changes

If you goof up your code, you can restore to the most recent version using the revert button (see the picture to the right). Find the file, click the revert button. A dialog will appear to confirm the decision. Click OK.

Updating

Perhaps you made some edits on your laptop while traveling and you come home and want to update your main development desktop system. If the version on the server is newer than your local version, you can update the local version with the Update button (see picture to the right).

Find the file in RapidSVN, click it, and click the update button. Leave the Use latest checkbox selected and click ok.

You may need to have a diff tool installed to do this, so you can resolve changes between the two versions. Configure the diff tool by selecting Preferences out of the View menu, and then clicking the Programs tab and then the Diff Tool sub tab.

Browse for your diff tool. There isn't really a diff tool for some non-text type file formats. But for text formats, what should you use?  Here are some hints. I use WinMerge on the PC but honestly I hardly ever need it since I'm a one person development shop and I rarely update code in two different places.

Releasing Your Next Version

When you've made all the changes and want to mark it as a release, or when you just want a snapshot in time of a working project, it's time for tags.

The idea is simple. You copy the current versions of all the files residing in trunk (the main code base) into a new folder. That folder happens to be under the tags directory.

Just drag and drop (hold down CTRL to copy) within your RapidSVN client. A dialog will appear to confirm the choice. Click OK.

Experimenting

If you want to experiment with some changes to your code, but don't want to hork up the current working version that resides in the trunk directory, you copy the current files into a new directory under the directory branches.

Just drag and drop (hold down CTRL to copy) within your RapidSVN client. A dialog will appear to confirm the choice. Click OK.

You can then check out the branch version to a new directory on your PC and work on it. Right click on the folder you just copied into branches, and select Checkout new working copy...

Merging Changes

If you've made successful experimental changes and want those in the main code, the trunk, you have to merge them back in.

Doing so requires a diff program if one exists for the file type. Otherwise, manually merge in changes if you've been working on trunk updates and branch updates at the same time. If the branch isn't missing any trunk updates/changes, you can just overwrite the file.

File Structures

I now like to keep all my working folders under a Projects folder. Some projects are simple, just a bit of code, for example. Others include firmware, client side software, and electronics design. So I create subdirectories: firmware, where I store various firmware (like Arduino sketches), software, where I place the client side code, maybe NetBeans or python scripts or whatnot, and hardware, where I store all the Eagle CAD files and the like.

I like to name tags with either a version number or date, or both. I then copy the software, firmware, and hardware directories from trunk over. Branches I try to name descriptively or with version number and then copy over the relevant parts, maybe just firmware.

That's All

So, that's it, hopefully it's enough to get you started and save you some hassle next time some code breaks.