LlamaLabs

Many times I’ve been looking at a configuration file on a server, wondering who made the last change to this file? What did they change? Whatever they did, it broke something.

When there’s more than one person making changes to system configuration, I like to keep that system configuration under version control. It makes it easier to track who is making configuration changes, it provides a history of the changes, and you can set up a post-commit hook to notify team members about the changes that are being committed.

One nice feature in Subversion is Keyword Substitution. Keyword substitution allows you to embed keyword anchors into your file that get expanded to show useful information about the file such as the revision, revision date, URL.

I like to embed the Id and the Url near the top of configuration files in a comment block. The Id contains filename, revision, revision time, and user and the Url describes the full URL to the latest version of the file in the repository.

Whenever I encounter a configuration file in a system that has these substitutions in place, I can immediately tell where I need to go in order to check out and commit changes to the file.

Below is an example of how to use Subversion’s keyword substitution. I’ll set up a local subversion repository, add a file and do the keyword substitution. I’m going to do this on my macbook.

First, create an empty repository called ’system’:

macbook ~ $ sudo mkdir /usr/local/svn
macbook ~ $ sudo chown $USER /usr/local/svn
macbook ~ $ sudo chgrp $USER /usr/local/svn
macbook ~ $ svnadmin create /usr/local/svn/system
macbook ~ $

Next, check out the repository and change directory into the checked out copy. Note, I’m skipping the normal repository structure (trunk, tags, branches) to keep things simple.

macbook ~ $ svn co file:///usr/local/svn/system system
Checked out revision 0.
macbook ~ $ cd system/
macbook ~ $

Make a sample configuration file full of comments:

macbook system $ cat >sample.cfg<<EOD
> # this is a sample configuration file
> #
> # \$Id\$
> # \$URL\$
> #
> EOD
macbook system $

Add the file to the repository:

macbook system $ svn add sample.cfg 
A         sample.cfg
macbook system $ svn ci -m 'adding sample config file to demonstrate keyword substitution'
Adding         sample.cfg
Transmitting file data .
Committed revision 1.
macbook system $

Notice how the keyword anchors are in the file, not the substitutions.

macbook system $ cat sample.cfg 
# this is a sample configuration file
#
# $Id$
# $URL$
#
macbook system $

We’ll need to enable the keyword substitution for sample.cfg using ’svn propset svn:keywords’.

macbook system $ svn propset svn:keywords "Id URL" sample.cfg
property 'svn:keywords' set on 'sample.cfg'
macbook system $ svn st
 M     sample.cfg
macbook system $ svn ci -m 'enabling keyword substitution for Id and URL on sample.cfg'
Sending        sample.cfg
 
Committed revision 2.
macbook system $

Now let’s look at our configuration file:

macbook system $ cat sample.cfg 
# this is a sample configuration file
#
# $Id: sample.cfg 2 2009-07-22 06:46:35Z dustin $
# $URL: file:///usr/local/svn/system/sample.cfg $
#
macbook system $

There’s our Id and URL. Note, if you checked out an existing repository over HTTP(S) or SSH, the URL would reflect that URL. So for a team accessing the SVN repository through Apache+WebDAV the example may look like this:

macbook system $ cat sample.cfg 
# this is a sample configuration file
#
# $Id: sample.cfg 2 2009-07-22 06:46:35Z dustin $
# $URL: https://svn.example.com/svn/system/sample.cfg $
#
macbook system $

Make sure to read through the docs at Keyword Substitution for more examples and additional details.