Tips and tutorials for GIS and Remote Sensing…

Tag Archives: Version Control

I’ve been quite enthusiastically advocating version control software (specifically mercurial) recently amongst some colleagues for managing code. Whilst the principles of version control are pretty familiar to most people, there are better ways than creating multiple copies with different names such as _final_final_verson2!

Version control software provides a better way of not only retaining different versions of files but allowing you to compare changes between them so you can easily find the lines that have been changed, particularly useful if you’ve just broken something! Mercurial and Git are two popular examples of version controls software. What’s nice about these (compared to other version control software such as subversion) is that all the changes are kept locally so you just need the software installed on your computer to have a folder under version control. For small projects, with only a couple of files, I just have local mercurial repositories set up.

When multiple people are working on the same code, these software work best when combined with hosting such as that provided by Bitbucket or github. My personal preference is Bitbucket as it offers mercurial (whereas github uses only git), allows private repositories for free (with unlimited users if you’re in academia) and I think it has a nicer interface. A lot of the software we’re developing / using is on Bitbucket (see bitbucket.org/petebunting/ and bitbucket.org/chchrsc/).

The command line interface for mercurial can be downloaded for Windows and OS X from http://mercurial.selenic.com, or can be installed from the package manager if you’re using linux:

sudo apt-get install mercurial

If you’d rather use a GUI than the command line TortoiseHG is a good option for Windows or sourcetree for Windows or OS X.

There are loads of good resources for learning mercurial on the internet, hginit.com is a particularly well written one and a good place to start. I’ve also put together a quick ‘cheat sheet’ with the commands I use most frequently.

Mercurial Cheat Sheet

hg clone REMOTE LOCAL # Create local copy.
hg pull -u # Pull changes from remote server (bitbucket) and update local copy.
hg merge # Merge changes from remote server with local changes (sometimes required after pulling).
hg commit # Commit changes locally (see setting up hgrc).
hg push # Push changes to remote server (bitbucket).
hg add # Add new file to version control (need to commit after).
hg remove # Remove a file from filesystem and version control (need to commit after).
hg mv # Move a file in the filesystem and version control (need to commit after).
hg tag # Create name for revision (e.g., version number).
hg update -r REV/TAG # Revert to revision or tag.
hg revert FILE # Revert file to last commit (can also revert to revision)
hg log # List all commits (good idea to pipe to less under UNIX).
hg status # Show status of all files, can use -m to only show modified files.
hg init # Initialise mercurial repository in directory (for new repositories only).

Setting up hgrc
The first time you commit you will likely an error ‘no username supplied’ to fix this you need to add the following lines to .hg/hgrc

The tag command is particularly useful for creating version numbers (e.g., version1.1) or noting the version of code used for publications etc. It does take some getting into but you soon get used to running ‘hg commit’ whenever you make changes.