Version control

To ensure good collaboration, you need two main things: good team communication, and version control.

We’ve all sent someone a file named …final.doc, only to send them another one hours later called …final v2.doc, or …final FINAL.doc. Often we’ll include a cover note in our email saying I changed the numbers; please use this version!.

Tip: The best way to name files is to use the date in YYYMMDD format, e.g. proposal-20171201.doc. If you have multiple versions in a folder, they will be listed alphabetically. If you’re creating several versions in one day, add the hour and minute as HHMM: proposal-20171201-1530.

That is a common, crude attempt at version control. There are two things we’re trying to do here:

  1. We’re trying to name each version uniquely.
  2. In our cover-note email, we’re trying to describe what changes we made in that version.

Those are the building blocks of good version control: unique names, and descriptions of what changed.

Trying to do version control over email leads to disaster. The wrong version gets designed. Your colleague works on text you’ve already updated. No one knows who has the master version.

Luckily we don’t have to suffer this pain if we use a version-control system. There are two kinds of version-control:

Both are great, for different reasons.

Real-time version control

In real-time version control, your editing software keeps a history of the document for you. And all collaborators work on the same document at the same time. Changes they make are recorded automatically and stored in a document’s history, so that you can roll back to any point in that history. Google Docs does this. To see a Google Doc’s history, you go to ‘File > Version history’.

Did you know you can have your Google Docs edits played back to you like a video? Go to draftback.com to try it out. Also, you’ll notice that you can replay edits from the beginning of a document’s history even if you didn’t have access to the document from its beginning.

A big advantage of real-time version control is that it’s automatic: you don’t need to do anything to get it. Some downsides are:

So automatic version history is really just constant back-up. Purists wouldn’t call it ‘version control’, because it doesn’t relly provide ‘control’.

Asynchronous, distributed version control

Software developers and tech-savvy writers use asynchronous, distributed version control. What does that mean?

‘Asynchronous’ means everyone can work at different times. I can work on a document now, and my colleague later today, and we’ll merge our versions tomorrow.

‘Distributed’ means we don’t have to be working on the same copy of the document. I’ll work in my copy, even offline, and Christina will work in hers. Later we’ll merge our versions into one master version, which is the ultimate source of truth. We call it ‘the origin’.

In this system, each contributor:

  1. checks out their own copy of the project
  2. works on it
  3. takes a snapshot of their changes, and
  4. sends that snapshot to the origin to be merged in.

Each time you take a snapshot – which is usually called a ‘commit’ – you describe what you just changed and your snapshot gets a unique ID.

That description and ID are saved in the project’s history forever, and anyone can go back, find them, and revisit the files at that point.

Since each team member is working on their own copy of the original, team members can have the ability, and authority, to vet each others’ changes before they’re merged into the original. It is astonishing how many tiny changes get picked up at this point, which saves everyone from endless amounts of pain later on.

This approach makes a bunch of useful things possible:

The most popular software for this kind of version control is called Git. In Git, a project is just a directory whose contents are tracked. We call that directory or project a repository – or repo for short.

Git basics

Git can be used from the command line or with Git software that provides a graphical user interface (GUI), like GitHub Desktop. The GUI really just enters Git commands for you in the command line behind the scenes, and gives you a visual view of what’s going on.

Here are the most common Git commands, and what they do. If you’re using Git from the command line, you’d type these in while in the project folder.

There is much more to Git, but you’ll use just those commands 90 per cent of the time.