Words on Macs: 4 Command and control

Cornerstone comparing files; if you want something grander, you can use an external tool such as Kaleidoscope.

Have you ever had a word processor or other editing app freeze on you, trashing your work? Or has an editor asked you to make changes, then a bit later changed their mind again?

There is more to (serious) writing than just being a wordsmith. All smiths need good tools, and your tools can help keep order no matter how scatty and disorganised you tend to be.

Depending on what you are writing and how you work, there are many more tools available to help or hinder you in that task. These fall into two main groups:

  • writing environments, which try to provide you with note-keeping, aids to structure your work, integrated research and reference facilities, and more;
  • document management environments, which are generally concerned with version control (version control systems, or VCS).

Content management systems (CMS) are generally much grander in aims and scale, and probably most relevant to technical authoring in corporate or large organisational settings.

Writing environments

The original environment to assist writing is the hypertext-based Tinderbox, which is now based on XML and a thoroughly mature product. It costs $249 from here. Another well-established product is aimed more at research and technical work: DEVONthink (£39.99 from the App Store) and its big sibling DEVONthinkPro Office (£100.84) from here should be on the shortlist of all writers.

More recently Scrivener has become hugely popular, particularly among those writing longer fiction works, screenplays, and the like. Its corkboard centrepiece seems very natural to many, and it is only £34.99 from the App Store. If you prefer a notebook metaphor instead, Circus Ponies Notebook 4 should be a strong contender; it is £44.99 from the App Store.

Which, if any, of these you choose is a very personal matter. However they are each well-proved and essential tools for many who make their living from their words.

Version control

Many writers find those tools helpful, but hardly any use version control. Look at another group of professionals whose writing earns their living, software developers, and you will find that almost all work with a VCS. Although there are obvious differences in terms of the content that they work on, a great many writers could benefit from using a VCS.

The basics are simple. Instead of throwing all your work into a few files tucked away in a folder, your source files (which include source text, illustrations, other media such as movies, and stylesheets) are kept in a repository, a database hosted by a VCS server. When you are working on a document, you check it out, make changes, and then check it back in again. The VCS keeps a track of each document as it develops, and at any time you can go back and compare the current version with earlier. If you decide that you want to discard some changes, you can merge in older content, and establish exactly what has changed by comparing versions.

Although software developers mainly work with plain text source code, components can include images, sound, movies, and other rich content. So VCS have broadened their scope considerably, and all the better ones will be more than happy to handle binary files for word processors and more. They have also become much easier to use: you should never have to tinker around in Terminal either trying to get a VCS server to work, or managing your source files. You do have to develop a bit of discipline, but by and large a VCS will protect you from yourself, relatively unobtrusively.

Even if you decide not to implement a VCS just yet, there is one powerful tool which you should consider: Kaleidoscope (£52.99 from the App Store) is a very sophisticated file comparison tool, which compares text files, images, and folders, allows you to merge changes, and supports most VCS servers. Although expensive there is nothing else quite like it.

Manual versions

The most basic VCS is manual, and something that you have probably already been doing. The idea here is simple: you make periodic backup copies of your document and other working files as you go along. Then if you want to revert to an earlier version, you simply go to the folder containing your backups, and find the one that you need.

For simple projects, and with good discipline, this can work very well and has been the mainstay for many of us for years. However it gets very complex when projects consist of multiple files, such as lots of linked images, or each chapter in a separate document. The more complex it gets, the less likely you are to make the most important backups.

It is also wholly dependent on you remembering to make backups at the right time. When you want to revert to an older version of a document, it is common to discover that no backup captured the document at just the right moment, and you have to waste time remembering what you wrote.

Unless you buy Kaleidoscope, there is also no good means of comparing files, and none of merging changes. Again this can result in your wasting a lot of precious time which you can ill afford.

Timed saves

The next step up in this is to use an editing app which supports timed automatic saving or backups, as some do. Again this can be great for single-document projects, but there is still no file comparison or merge beyond the facilities provided in the editor you use.

Time Machine

Time Machine, built into recent versions of OS X, provides automatic timed backups of all changed files, into a designated hard-linked archive. This gets round the problem of trying to remember when to make backups, and is excellent for general backup. However it lacks the other features of VCS, and cannot compare versions or merge changes. In general it is best used in addition to a proper VCS.


Since OS X 10.7 (Lion), apps have been progressively giving access to a built-in versioning system. This is now available in many but by no means all of the text editors and document processors. When it works properly, it is very simple to use. You work on your document(s) normally, and it will automatically save a new version of your work every hour, more often when you make a lot of changes.

When you want to look back at an old version, the Revert To command in the File menu opens a browser identical to that of Time Machine, with your current document on the left, and the right side shows all the older versions which it saved for you.

OS X's version browser is identical to that of Time Machine, but does not offer any facility to compare versions.
OS X’s version browser is identical to that of Time Machine, but does not offer any facility to compare versions.

For some the changes this has brought about in the File menu are confusing: instead of the clear and simple Save and Save as, there are Duplicate and Rename. When you want to make a fresh copy of a document without its legacy of older versions, use Duplicate. When you want to change the name of a document, just use Rename.

The features are though seriously limited. As with other backup systems (rather than proper VCS) there is no facility to identify the changes made between different versions, nor to control the merge of changes into any version. Worse, these versions are tucked away in an SQLite database which is itself hidden in the .DocumentRevisions-V100 folder at the top level of your startup volume. That is locked even from admin users, and there are no tools to clean the database up, huck out old disused versions, or do any other maintenance. However it does come free with those apps which support it.

There is also a similar system offered by Draft Control (£29.99 from the App Store), which performs automatic timed saves, versioning in those backups, and most importantly includes features for change tracking and version comparison. This supports native formats used by major products, including Microsoft Word, Pages, the office suites, Scrivener, Mellel, RTF, TeX, PDF, and all plain text formats. If you don’t want to go the whole hog and use a proper VCS, then Draft Control should be almost as good.


If you already have Apple’s free Xcode software development environment (free from the App Store), then you already have a superb VCS which you should put to use in your writing projects. Although Xcode itself performs all the main functions, you should consider setting it up with Xcode Server, which is a part of OS X Server 4.0.3 (£14.99 from the App Store, a snip!).

Create a repository for Xcode Server to offer to clients, by clicking on the + button.
Create a repository for Xcode Server to offer to clients, by clicking on the + button.

First install OS X Server, and select the Xcode Server service. Create a repository to hold the document data, and turn that service on. You can then open Xcode, create a new project, and hook that up with the Xcode Server, which is in fact running Git, one of the leading modern VCS servers. You can get Xcode to crash doing this if you are not careful: initially you should store your project in a local repository, not Git’s, typically in the Xcode folder inside your Documents folder. Once you have set the project up and populated it, you can then load its local files back to the server’s repository.

Once you have set the repository up and enabled connections, turn Xcode Server on.
Once you have set the repository up and enabled connections, turn Xcode Server on.

As a front end, Xcode is powerful, sophisticated, but straightforward in use. It handles most common text (XML, HTML, RTF, and more) formats but sadly not (La)TeX at present, together with all common image formats, PDF, and more. If you are using an output engine such as TeX, you can also set it up to process source into PDF, using the command line tools. The only caution is that included files, such as images, may need path tweaks so that those tools can find them.

Comparing files using Xcode's built in facility.
Comparing files using Xcode’s built in facility.

If you do not wish to use OS X Server, Xcode should be able to connect to a regular Git server (free from here), or Apache Subversion (free from here). If you prefer, you could try the commercial Perforce, which is free for up to 20 users, from here, but you would need to use a different front end.

Xcode is a an amazing bargain, with superb file comparison, merging, and all the bells and whistles of a high-end VCS.


Cornerstone is a worthy alternative if you want a simpler, packaged product which you can just install and go. Available from the App Store it will cost you £44.99, but is a neatly produced combination of Subversion server and friendly front end, ideal for those who would not wish to go near Xcode if at all possible.

Cornerstone's listing of a multi-file writing project. This is a working copy which is then written back to the master in the repository.
Cornerstone’s listing of a multi-file writing project. This is a working copy which is then written back to the master in the repository.

All you have to do is create your repository, add your working files, and you can then start work on them. When you Commit changes, it automatically increments the version number, and archives the previous version of the document. Whilst working, you commit changes in small saves to working copies, and then when ready commit those back into the main repository. Its compare and merge features are extremely flexible, and if you want more you can always hook Kaleidoscope up.

Cornerstone comparing files; if you want something grander, you can use an external tool such as Kaleidoscope.
Cornerstone comparing files; if you want something grander, you can use an external tool such as Kaleidoscope.

Although Cornerstone allows you to view a wide range of document types, including images, it is intended to be used with external document editors. It helps if you set those, using the Finder’s Get Info dialog, so that double-clicking a document in your working copy of the repository opens the right editor. This is a bit more tricky with HTML, as most users prefer that to open in their default browser, rather than chosen HTML editor. There is a feature which allows you to open documents with other apps, but there is no contextual menu command to do so at present.


Anyone who takes their writing seriously should take backup and version control very seriously. At the very least you should use OS X’s versioning if your editor supports it, or Draft Control. If you regularly work on projects which use more than a couple of source files, or work with other authors, then you should take a serious look at Cornerstone or Xcode.

I have been involved in several multi-author and multi-editor publishing projects, including books on computer science, and it never ceases to astonish me that for most, turning on Word’s Track Changes feature is as close as they get to proper version control. Now that good VCS are cheap and easy to use, this is extraordinarily dumb.

In the long run they will provide the support that you need, and save you time and effort.