Using Version Control

If you are not already, you should be using version control. Perhaps you’re thinking: “I’m a solo developer and do most of my work on a single machine. Why should I bother?” Well, I used to think that too. Then I saw the light.

Advantages of Version Control

Version control brings three very important advantages to the table. First, it allows you to save previous versions of your work. How many times have you played around with some method in Xcode, and then were not entirely sure how to get back? While this might not happen with a great deal of frequency, it does happen over the course of a major project. Now, if you have version control, you just restore the previous version, and you’re golden.

Second, version control allows you to experiment without fear. Suppose you want to add a tab to your application’s preferences window. Simply commit your application before you start adding the tab, add the tab and all the code that is required, and see how you like it. If you decide adding the tab was a bad idea, you could remove the code and the tab. Or, you could simply revert to where you were before you added the tab. The former takes time and care. The latter takes less than a minute.

Third, version control allows you to maintain separate versions of your program. Many developers follow the pattern of allowing free upgrades within the same release, but require an upgrade fee for new releases. So, if you purchase an app at 1.1, you get 1.2, 1.3 and 1.4 for free; but 2.0 is going to cost extra. In order for this model to work, usually the developer is making minor improvements or maintaining 1.4 (or even earlier) while working on getting 2.0 out the door. Now, you could simply have two different Xcode projects. But the trick is this: often fixes made to 1.4 should be applied to 2.0 as well. Thanks to version control, it is possible to do this with a minimum of fuss (though not zero fuss).

Which System?

When I went looking for a version control system, I did so with the idea that I wanted it to be relatively quick and easy. CVS and Subversion (aka “SVN”) are the two granddaddies of the field; but as a solo developer I needed neither their power nor their legacy. A bit more searching, and I turned up two viable options: Git and Mercurial. After some digging, I settled on Mercurial. It just seemed a bit more friendly, and help and documentation seemed a bit easier to find. There are ongoing debates about which is better, but I have no doubt that they are both excellent and useful tools.

Installing Mercurial

Installing Mercurial is easy. Simply go to the download page and download the appropriate package. There are versions for Leopard and Snow Leopard, but to use Mercurial with Tiger, you need Python 2.5.2.

Your First Repository

If you already have an Xcode project, you can create a Mercurial repository for that project by simply typing “hg init “. (“Hg” is the chemical symbol for mercury, and you’re using Mercurial, get it?) This will create a repository for that directory (a hidden .hg directory within ). You can then go into and see what is in your repository by typing “hg status”. You’ll get a list of files with “?” beside them, indicating that Mercurial doesn’t know about them.

In order to start all the version-tracking goodness, you need to add the files to your repository. Do this with “hg add “, or “hg add” if you just want to add all the files. Wildcards may be used when specifying file names. Now Mercurial knows about some of your files. Type “hg status”, and you’ll see “A” next to the files Mercurial has added to the repository.

If you want to roll back to a particular point, you need to commit those changes to your Mercurial database. This is as simple as “hg commit -m ‘Your message in single quotes’”. Your message can be whatever you want; I try to give a brief description of what was most recently changed. Now, when you issue “hg status” only files that have been modified since the last commit will be listed. If you modify a file, you will see an “M” next to it, indicating that there has been a modification, but that modification has not yet been committed. Issue “hg commit -m ‘Another message’” to commit those changes. To see the history of your commits, use “hg log” or “hg -v log” (verbose).

Additional Considerations

You can do a lot with Mercurial. For all the details, you can read Mercurial: The Definitive Guide. My favourite chapter is Mercurial in Daily Use. If you’re brand new to version control, you might want to look at Understanding Mercurial. Finally, have a look at the official Mercurial Tutorial. It covers topics that are not of interest to the solo developer, but there is a lot of good stuff in there.

Two other points, specific to Mac OS X. First, Mercurial does not have a mature GUI for Mac OS X. But there is one available that looks to be shaping up: Murky. Second, once you become comfortable with Mercurial, you’ll want to include an .hgignore file. The .hgignore file as a list of filenames or file patterns that Mercurial will ignore when doing status lists and so on. You want to use this, because you really only want to commit text files to your repository. You can skip the build directory, .DS_Store, and others. Here is my .hgignore file for one of my current projects:

# Allow *. syntax
syntax:glob

# Generated CMake stuff
CMakeFiles
CMakeScripts
CMakeCache.txt
*.cmake
./bin
./build

# CMake generated make stuff
Makefile
config.h

# CMake - Xcode ./Deductions.xcodeproj/@
./build
*.makeDebug
*.makeMinSizeRel
*.makeRelease
*.makeRelWithDebInfo

# Mac temp files .DS_Store@

# Frameworks ./Sparkle.framework/@
./ILCrashReporter.framework/

# Icons and pictures *.jpg@
*.icns

Store the .hgignore file in your project directory, add it to the repository, and boom! every file matching what is described in .hgignore will never bother you again.

There is a bit of a learning curve when it comes to version control. But it will make your life a lot easier in the long run.