Version Control with Git

How familiar are you with this situation: You are editing a document, data file, or analysis script. You’ve made changes that you think are good, but you’re not sure. You need to check with your supervisor or collaborator first, or your just want to know that if you decide to change your mind, you can go back to the old version. So what do you do?

Some common ad hoc solutions include

• Saving a new copy of the file, usually appending something informative like your initials, the date, and a descriptive word like “edited”, “revised”, or “final” in the file name.
• Moving “deleted” paragraphs to the bottom of the document, to be eventually deleted for real when you’re satisfied with the final draft
• Commenting out lines, or even big blocks, of code so it won’t run when we run our script, but still leaving it there in case we need it later.
• Creating new columns in spreadsheets, and using the “hide” function for old ones, to avoid deleting data we might want later.

These solutions feel reassuring, but they are often not as functional as we would like, and can lead to more problems further down the line. Some of these situations might be familiar to you:

• You’re left with a folder or email chain containing a rapidly proliferating list of documents, and relying on things like the Date Modified property to figure out which one is the most recent.
• Six months, or even two weeks, later, words like “edited” and “final” don’t mean as much to you as they did when you first typed them.
• Reverting changes means going through many different versions, trying to remember when you made the change you want to undo, or which file is likely to contain that paragraph you want back.
• Between the hidden columns or the commented lines, or the paragraphs sitting at the bottom, the contents of the file get so disorganized you can’t even tell what you meant to include and what’s just there for just-in-case.

Using a Version Control System, either manually or via a software tool like Git, allows us to be more systematic about these changes while keeping a clean, current copy of every file we’re working on. Some advantages of version control are

• All changes are well-documented, so we know who made the change, and what change was made.

• Nothing that is committed to version control is ever lost. Since all old versions of files are saved, it’s always possible to go back in time to see exactly who wrote what on a particular day, or what version of a program was used to generate a particular set of results.

• As we have this record of who made what changes when, we know who to ask if we have questions later on, and, if needed, revert to a previous version, much like the “undo” feature in an editor.

• When several people collaborate in the same project, it’s possible to accidentally overlook or overwrite someone’s changes. Version control software automatically notifies users whenever there’s a conflict between one person’s work and another’s.

Teams are not the only ones to benefit from version control: lone researchers can benefit immensely. Keeping a record of what was changed, when, and why is extremely useful for all researchers if they ever need to come back to the project later on, once their memory has faded.

Version control is the lab notebook of the digital world: it’s what professionals use to keep track of what they’ve done and to collaborate with other people. Every large software development project relies on it, and most programmers use it for their small jobs as well. And it isn’t just for software: books, papers, small data sets, and anything that changes over time or needs to be shared can and should be stored in a version control system.

Prerequisites

In this lesson we use Git from the Unix Shell. Some previous experience with the shell is expected, but isn’t mandatory.