On several occasions recently I have needed to mirror a remote Subversion repository on my laptop for development. The circumstances were a little different in each case, but the basic need was the same. In the most recent instance I wanted to track the Typo Subversion repository while at the same time managing my own local patches.

In the old days with CVS I would create a “vendor branch” and merge upstream changes onto the trunk. While this is possible with Subversion, it is more work than I really wanted to invest. This also only solves the problem of tracking upstream changes in the repository. I had one situation in which I needed to merge some of my local changes with the upstream repository. The vendor branch solution doesn’t really help in that instance.

Discovering Darcs

Meanwhile, I had heard of Darcs and wanted to use it in a few projects to get a feel for how it worked. For those who are unfamiliar with Darcs, it is a distributed version control system. Centralized version control systems like CVS and Subversion are based on a central repository that tracks snapshots of the code as it exists at given points in time. In a distributed version control system there is no central repository: each developer’s working copy is a repository. This means, among other things, that the paradigm of tracking changes as snapshots will not work in a distributed system. Instead, changes must be tracked as a series of patches that can be moved between repositories independently. Darcs’ creator, David Roundy, formulated his theory of patches to describe how this works in Darcs. See the Darcs manual for more information.

There is a pretty good introduction to Darcs over at the caboose blog titled Darcs for Rails Users. Michael Jakl has a couple of good articles on Darcs: an introduction to Darcs and why he perfers Darcs over Subversion. Finally, Tom Moertel points to some recent reviews of distributed SCM systems.

Enter Tailor

Still, I wasn’t quite ready to trust Darcs with my code, so the idea of mirroring a Subversion repository with Darcs was appealing. I could use Darcs as my primary version control tool, but if things didn’t work out the Subversion repository would still be there. So I began looking specifically for a tool that would allow me to mirror the Subversion repository with Darcs.

Fortunately there is such a tool: Tailor. Tailor is a Python script that can copy changes between different SCM systems. It works by fetching changes from a source repository and the “replaying” those changes into the destination repository. There is more information in the README file.

You can download a tarball from http://darcs.arstecnica.it/ or get the latest code using Darcs:

darcs get --partial http://darcs.arstecnica.it/tailor

Once you have the Tailor code you can run it in place or install it by running the following command as root (or with sudo):

python setup.py install

Making it work

Here are the steps that I followed to mirror the Typo repository to Darcs using Tailor.

First I created a directory ~/Projects/typo where all of the Typo related code would live. I want my current working version of the code to live in a working directory. Tailor requires a local hybrid repository that contains both Subversion and Darcs metadata. I named this directory master. Note that Tailor will create these directories the first time it is run.

The next step is to create the Tailor configuration file. Here is the file I use:

[DEFAULT]
verbose = True
projects = typo
patch-name-format = %(revision)s
refill-changelogs = True

[typo]
root-directory = ~/Projects/typo
target = darcs:tailor
source = svn:tailor
start-revision = 1110
state-file = tailor.state

[darcs:tailor] 
repository = ~/Projects/typo/master
subdir = master

[svn:tailor]
repository = svn://typosphere.org/typo
module = /trunk
subdir = master

The start-revision parameter specifies which source revision at which to start the conversion. Tailor can be slow, so it usually isn’t a good idea to try to convert the whole repository unless it is very small. In the specific case of the Typo repository, the conversion would quit on me halfway through if I tried to convert the whole thing. If you get strange errors during the conversion, try using a more recent revision as the start-revision. One thing to watch out for is that you cannot use a tag revision as the start-revision.

I saved this file in ~/Projects/typo and then ran Tailor for the first time:

tailor --configfile typo.tailor

Once the initial conversion finished, I cloned the master repository with Darcs:

darcs get master working

Now I can work with the repository in the working directory like any other Darcs repository. When I want to merge changes from the upstream repository I run Tailor again and “pull” the changes into the working repository with darcs pull,

Alternatives

If your primary goal is to mirror a Subversion repository, there are tools other than Darcs and Tailor that will work. I happen to like Darcs’ workflow, so that is what I chose. SVK is a distributed SCM system that is built on top of Subversion. Scott Laird has a series of articles on using SVK to mirror the Typo repository. There is a new tool called Piston that may also work, depending on your requirements.

Caveat Programmer

There are some problems to watch out for when using Tailor. For one, it is very flaky on Windows. I have used it on Windows with Cygwin, but always with very mixed results. Also, the conversion process seems to be very fragile and can fail often. Usually just restarting the script is enough to complete the conversion successfully.

Tags: darcs, subversion, tailor, typo