Excursus

Serendipity can be good. After my last post, a discussion of the pros and cons of subversion emerged in this thread of the Textmate mailing list. Though focused on web development, many of the insights are generalizable. I am not involved in web development, nor am I a programmer. But I do keep LaTeX documents, BibTeX files, a directory of PDFs, notes in markdown, and remind calendar files in a subversion repository. Whether or not you use subversion, if you are producing complex documents, some form of version control is a real godsend. Be it subversion, mercurial, perforce, darcs, or what have you, some form of version control should be at the center of a writer’s workflow.

Most academics might wonder what the big deal is. After all, many save versions of their latest research in an ad hoc fashion, say, with multiple Word files (shudder). The problem is that it is ad hoc and unreliable. Version control is not magic, it requires discipline, but it provides the framework for keeping track of revisions in a non-ad hoc manner. It may well save you a lot of grief.

In subversion, your files are kept in a subversion repository that can either reside locally on your machine or, ideally, on a server. Directories of files can be checked out. This is your working copy, and it resides locally on your machine. You edit the files in your working copy, and when satisfied, you commit your changes to the subversion repository. The working copy can also be updated to propagate the current state of the repository.

There are two aspects of committing that require discipline.

First, nothing is forcing you to commit your changes, and it is easy to get lazy. Personally, I commit and commit often. Remember, commits are free, and the more commits you make, the more detailed record you have of the revisions that you are making. I definitely commit before deleting anything, be it a section, a paragraph, or a memorable if misplaced line—just in case I want to access that material at a later time.

Second, subversion tracks changes to a directory of files. Each time you commit the revision number of the entire repository is incremented. When you commit you enter a commit message. If you commit changes to multiple files, your message must detail the changes to each of these. Fortunately, subversion provides tools to make this easier. Suppose you have been editing the files in your working copy and want to remind yourself what you have done. The command:

svn status

will provide you with detailed information about how your working copy differs from its state when last updated, including which files have been modified, which have been added, and so on. Suppose you want to remind yourself of the changes made to a modified file. The command:

svn diff

will reveal the local modifications in the working copy.

Remember, the more detailed your commit messages, they more useful they will be to you. At first the discipline can seem onerous. But beyond the utility of providing a detailed record of revisions, it is an occasion to reflect on what you have achieved, and what needs to be done. Like the confessional for Catholics, or the weekly review for GTD geeks, the exercise of formal reflection can be good for you.

Next time, I will detail a few more basic concepts of subversion and outline a typical single-user workflow.