Posted by s.hettrick on 30 September 2013 - 11:42am 

By Daniel Jones, Postdoctoral Researcher in the Department of Materials at The University of Oxford and Software Developer working on the CASTEP density functional theory code.

Once your software development goes beyond simple hacking, your productivity will be improved by using a version control system (VCS). A VCS allows you to keep track of all the changes to your software during its development. It enables you to roll back the clock to see how something worked at any point in the software’s history. Simply put, I could not work without the peace of mind that the version control system gives me. And if you ever want to involve others in the development of your software (and you probably will), version control becomes all but essential.

Here are five tips to get you started using version control:

1. Use it!

Your first step is to choose a version control system. If there is a wealth of knowledge about a particular system where you work, then go with that. If not, I would recommend choosing a distributed VCS (either git or mercurial) as these more modern tools facilitate collaboration more effectively, and you will probably have to learn to use them sooner or later. While the number of commands available can seem somewhat overwhelming, there is a simple set of commands to get you going:

• init - initialise a repository
• commit - save the current set of changes to the repository
• diff - what’s the difference between what I’ve got now and the last committed version.

You can learn more controls as you need them.

2. Tools, GUIs and plug-ins can help

Many people are happiest working on the command line (including me). If that’s not you, there are many GUI front ends for the various VCSs. A quick search on the web returns many examples. I particularly like TortoiseHg for viewing the history of my projects. Using a visual diff tool like meld or kdiff3 can help when you start to use branching and merging in your workflow.

3. Commit often

The power of VCS (especially when working alone on a project) is the ability to go back to a previous version of your software either to exactly reproduce earlier work, or to find out why something used to work but doesn’t any more. Since you can revisit any revision, you don’t need to make sure every committed version is fully functional. The more often you commit your code, the more fine-grained is the history you create, which will help when you try to discover when a bug was inserted into your code.

4. Trust it!

A VCS coupled with some well thought out tests allows you to take leaps of faith with your development knowing that you have all your safety nets in place. You can try the new library that you’ve found, or the new algorithm that you have read about, knowing that if it doesn’t work, you can backtrack to a previous working version.

5. Your log is your friend, be careful with it

Each time you commit your changes to your VCS you are asked to include a message to describe the change you've made. Make sure you spend a little time thinking about this message. I recommend a short one liner, like an email subject, followed by a clear description of all the changes made, and a note to tell you whether you have added functionality, fixed a bug, or whatever. Life is made much easier if you follow point three above and commit often, because you will not need to stretch your memory to work out what you have changed. In six months, when you have forgotten what you did and why, you will thank your past self for leaving you a clear description of what happened.

This short post just brushes the surface of version control. Soon you will be interested in branching and merging for managing concurrent developments. If you have been diligent enough to manage a good test suite for your code, the bisect command is a fantastic way to help track down trouble. The web is full of tutorials covering the full breadth of options that the VCS tools give you. For starters, a handful of links are copied below.

Further reading

1. Mercurial tutorial
2. Git tutorial
3. SVN tutorial