Motivation

Figure 1: A toy of the GitHub mascot. Image credit: Unslash

Version control allows us to understand the history of a piece of work (typically the writing of a paper for academics). This lets us and others understand what was done, when, and with the aid of well written comments/commit messages, why it was done. This greatly increases the transparency of the work, which is crucial for reproducibility. A version control system allows us to do this cleanly, with no debris from previous versions of files strewn about various folders which could confuse us or others trying to understand how we arrived at out final results. This can be especially useful with code, as we no longer need to keep large chunks of unused code commented out just in case we want it later.

But perhaps the greatest benefit is the ease of collaboration good version control allows for. Particularly when combined with version control hosting services, such as GitHub, GitLab or Bitbucket, version control allows many people, potential all over the world and in different time zones, to work on the same files. The changes from different people can be tracked separately, and there are powerful tools communicate in a more structured way, via pull requests, code reviews and issues for example.

Basic workflow

A typical workflow using version control is as follows:

1. Create files - these should be plain text, usually code and/or markup or some kind
2. Work on these files - adding, deleting or changing content
3. Create a snapshot - explicitly record the state of a file/s at that particular time, with a message summarising what was done

In Git, which I will focus on for the remainder of the article as it the most popular, these snapshots are called “commits”. This can feel a little strange at first, but you quickly get used to it. Personally, I’ve found a nice added benefit to using Git as a tool for delimitating where my day ends. The last thing I do each day is commit all the work I’ve done, giving me a nice sense of accomplishment (or terrible shame if I’ve been unproductive…), and giving my brain a signal that work is over it’s time to switch gears.

Learning resources

Figure 2: Image credit: Unsplash

If I’ve managed to convince you to give version control a go then do be warned if you using Windows - getting things set up will be a bit ugly. Windows is a pretty terrible operating system for doing anything, but it’s especially bad for these kinds of things.

In an ideal world more people would realise that there are operating systems that you don’t have to pay for and don’t include spyware. I’m talking about Linux for the uninitiated. If you’ve got an old clunker computer that’s unusably slow, try installing a lightweight Linux distribution and marvel at how much difference a good OS can make. Without getting into some boring details, MacOS effectively has the same backbone as Linux, so that works well enough (but Linux is still way better!).

That’s not to say it can’t be done of course, especially with the help of these lovely resources:

• A great resource for many facets of reproducible research is The Turing Way
• Another great resource, particularly for integrating Git with R is Happy Git with R
• The Pro Git book is another great resource for a more in depth understanding of how Git works, and some of it’s more advanced features