Version control: What system should I use?

in

Part of an occasional series of posts discussing the potentially baffling intersection between sound and music research work and software development

A version control system remembers the history of changes to your files, so you can review what you have changed and when; and it helps you to share your changes and work with colleagues more easily. We discussed the concepts behind version control in a previous article.

Here we talk about which system or service to use. This is a fairly long post intended for readers who are interested in the reasons why they might do things a particular way, not a quick-start tutorial.

As of 2011, there are three free version control systems that are common enough and capable enough to be good first choices: git, Mercurial, and Subversion. Subversion is a “centralised” system, the other two are “distributed” (see our earlier article for an explanation).

These systems are software programs which you use to manage your code; in each case you will also need to decide where your code will be stored, and for each system you have a number of good options for storing your code outside your own computer. So there are many possibilities here.

Which system to use really depends on three things:

  • what system (if any) other people you work with are using;
  • where it is that you want to keep your code;
  • the tools, user interfaces, and documentation available.

Let's look at those in turn.

What are other people using?

This should be the easiest question to answer.

If other people around you are using a particular system or hosting service, that's a good reason to do the same. If you're working on the same project, of course you'll want to use the same system — but even if you aren't, at least you can sort out any problems together.

Where do you want to keep your code?

Here are some possibilities.

— on your institution's servers

If your institution provides a central version-control server, you should at the very least consider using it. That way your institution has the reassurance of knowing that your work won't become completely inaccessible when you leave and, if you're lucky, you'll get backups and support as you work. And indeed, you might be required to use your institution's own systems.

If you don't know whether your institution has a standard version-control server, ask! Send an email to your systems support address; ask your supervisor; go and talk to the systems people.

There are some potential disadvantages to using servers internal to your institution, most notably that it may make collaboration with researchers elsewhere more difficult than if you used a shared service. Many systems groups are willing to find ways to provide access for individual collaborators, so it's worth asking, but it isn't always straightforward. Still, it's always better than no version control at all.

Best system for this scenario: Whatever your institution provides!

— on the SoundSoftware hosting service: code.soundsoftware.ac.uk

We provide a hosting facility for projects using version control: the SoundSoftware hosting service at code.soundsoftware.ac.uk. This is specifically designed for researchers in the UK working in the audio and music fields.

The SoundSoftware hosting service uses Mercurial, and we also publish a user interface called EasyMercurial to help get started with it (or with any other Mercurial hosting service). Read more about why you might want to use our service in this article.

Best system for this scenario: Mercurial, perhaps with EasyMercurial.

— on an external code hosting service

There are lots and lots of public services for hosting version control repositories. These first appeared as hosts for “open source” software only – that is, software that is published under a free licence that permits redistribution – but several of them will now accept personal projects without open source licences as well.

You should think a little bit before using public hosting services. We actively encourage the publication of academic work as open source software and we believe it is often beneficial to research work to do software development as openly as possible, but your institution might not feel so warmly about it. And a private repository on a general hosting service offers none of the advantages (for the institution in particular) of an internal server in terms of enabling ongoing access to your work. Nonetheless, our usual refrain applies: it's always better than no version control at all!

Some notable services are:

  • GitHub, a hosting service for git repositories. GitHub has a very “social” design, aimed at making it simple to copy and maintain your own version of (or “fork”) someone's existing work: this makes it very productive for somewhat speculative, loosely collaborative endeavours. GitHub charges for private repository hosting, but offer free educational accounts.
  • BitBucket, a hosting service originally only for Mercurial repositories but which now hosts git repositories as well. BitBucket allows private repositories with up to five users for free, which could be handy for small research teams.
  • Google Code, Google's hosting service for Subversion and Mercurial repositories. Google Code only accepts open source software, repositories are always public, and you have to pick your open-source licence when you register a project.
  • CodePlex, Microsoft's hosting service for Mercurial and Team Foundation Server repositories. CodePlex also only accepts open source software, and its repositories are always public.
  • SourceForge, the “original” code hosting facility for Git, Mercurial, and Subversion repositories. Like the previous two, SourceForge also only accepts open source software and hosts public repositories.

Best system for this: Mercurial or git with BitBucket if shared private repositories are important to you; git with GitHub if you know other people who use it and you're keen to work with or learn from them; Subversion with Google Code or SourceForge if you've developed a preference for Subversion or wish to build a large project with many public-facing facilities.

If you do use an external service, please consider also using the SoundSoftware project service. You can set up a project on there even if your code is hosted elsewhere, to increase visibility of your code.

— on your own computer

You can use version control for your own project files very easily, without having to ask anybody's permission or store anything on a server.

It's particularly easy to do this using a distributed version control system like Mercurial or git, in which the repository is stored in hidden files inside your working copy. Just tell your version control system to initialise a repository in your project folder, and you're off. (This three-minute video shows an example.) If you want to switch to using a hosting service later on, you can push your entire project history to a new remote repository with a single command.

There are still problems with working only on your own computer: you don't get free backups as you do with an offsite server, and you can't share your code so readily with other researchers, or even with yourself if you switch to a different computer (lab machine, laptop etc). These are potentially serious disadvantages, and you should usually try to use some sort of shared or centralised service if you can. Still, all together now: it's better than no version control at all!

Best system for this scenario: Mercurial with EasyMercurial if you are not particularly technically inclined; git if you are.

What are the tools, user interfaces, and documentation like?

All of these systems are easy to use if you are familiar with a command-line, particularly on a Linux or Mac OS/X machine. Some other considerations that may matter to you include:

  • Our own Mercurial user interface, EasyMercurial, is a nice way to get started and is unusual in being essentially the same across Windows, OS/X and Linux.
  • Windows users will find that Subversion has the most comprehensive client support, through TortoiseSVN or SmartSVN.
    There are nice Mercurial interfaces for Windows (including TortoiseHg and our own EasyMercurial), though Mercurial currently has some limitations in how it handles non-Western filenames on Windows which may be an issue.
    Git has historically lagged in support for Windows, though there is a TortoiseGit available.
  • Mac users will find attractive client applications for all of these version control systems, but it may be of interest that support for Git is now integrated directly into Xcode 4.

Here are some starter tutorial links for each of these systems: