Save your work

21 Aug 2018

My first revision control system for software projects was to zip the files and put a date stamp in the file name, something like this:

The system was a pain to use (no way to tell how the 11-01 version differs from the 11-15 version) but better than some other systems in the wild.1 Eventually I learned to use Mercurial, which is both easy to use and free of charge. I use it for my resume’, letters, software projects, configuration files, brochures, everything I work on that gets revised.

A real revision control system

Mercurial is designed to offer a small, safe, and easy to use command set which is powerful enough for most users…Potentially dangerous actions are available via extensions you need to enable, so the basic interface is easy to use, easy to learn and hard to break.

On everyone’s laptop

Mercurial is a distributed revision control system, which means that coworkers can clone the parent repository and keep it on their laptop. This allows you to read and edit any of the documents in the repository without sending another network request to the parent (and hoping the network isn’t running too slow). Very handy for teams that aren’t working in the same building. A bonus is that everyone who clones the parent repository has a full backup of the repository in case of system crash, fire, earthquake, hurricane, etc.


When you make a code or document change you want to save, you commit the change to the repository. It logs your name, email address, the date and time, and prompts you to write a brief summary of the changes you’ve made. Now if anyone has a question about the change, they can inspect the commit log.

Branching and Merging

Branches allow you to keep new features that are still under development away from the production branch. For instance the repository for this website has a release branch, and everything on that branch is considered published. When I develop new features for the website I do it on a separate branch. When that feature is ready for release, I merge its branch with the release branch.

Multiple writers can edit the same document at the same time and Mercurial will merge the changes together and alert you of any conflicts.


The diff command allows you to compare two different revisions, line by line. Very useful when a web app suddenly stops working: review the changesets (revisions) between the time it was last known to work and when it stopped working, and one of those changesets is the culprit.

Revision control built into the document

A Microsoft Word document contains the revisions and comments made by everyone who edited the file. This makes it easy to email the file and its entire revision history to coworkers for further revision and comment.

On the other hand, it’s a terrible idea to routinely use email for shuttling sensitive documents around:

  1. If you forget to delete the revision history before emailing the document, it can lead to disaster.
  2. Email is notoriously insecure, more like a postcard than a sealed envelope.
  3. Who has the document with the latest revisions? It could be on anyone’s laptop. With Mercurial, the latest revision is in one place.

In the end, you’re better off using a real revision control system like Mercurial.

  1. On my first day as a System Control and Data Aquisition (SCADA) tech at a water treatment plant I went hunting for the latest revision of the plant’s control software. I found a drawer containing twenty Zip drives, each carefully labelled Plant App: The Latest