Version control

To ensure good collaboration, you need 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, and then …final v2 REVISED.doc. Often we’ll include a cover note in our email saying I had to make a few updates – please use this version!.

Tip: If you have to name new versions of a file, just add the date in YYYMMDD format, e.g. proposal-20171201.doc. If you have multiple versions in a folder, they will then be listed alphabetically. If you’re creating several versions in one day, add the hour and minute as -HHMM: proposal-20171201-1530.

Renaming and resending files is a common, crude attempt at version control. Our intentions are good, and we’re actually providing two key pieces of a proper version-control system:

  1. We’re trying to give each version a unique name.
  2. In our cover note, we’re trying to describe our changes.

These 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? Saerch for the Draftback browser extension. 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.

Compared to distribution version control below, there are also downsides:

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 on different versions at different times. I can work on my version of a document now, and my colleague on theirs 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 that original source of truth ‘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 origin. It is astonishing how many tiny changes get picked up at this point.

This approach makes a bunch of useful things possible:

The downside of this kind of version control is that it is hard to learn. Braches and occasionally conflicting versions can be confusing. You need a level head to resolve problems when they do crop up.

The most popular software for this kind of version control is called Git. In Git, a project is a directory (a folder) 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 effectively handles Git commands for you 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.