Managing VCS Repositories with Woodchuck

Mon, 03 Oct 2011 15:56:54 -0400
hacking, maemo, woodchuck

At the recent GNU Hackers Meeting, I gave a talk about Woodchuck. (I'll publish another post when the video is made available.) The talk resulted in a lot of great feedback including a question from Arne Babenhauserheide whether Woodchuck could be used to automatically synchronize git or mercurial repositories.

I hadn't considered using Woodchuck to synchronize version control respoitories, but it is a fitting application of Woodchuck: some data is periodically transferred over the network in the background. I immediately saw two major applications in my own life: a means to periodically push changes to a personal back up repository; and automatically fetching change sets so that when I don't have network connectivity, I still have a recent version of a repository that I'm tracking.

I decided to implement Arne's suggestion. It's called VCS Sync. To configure it, you create a file in your home directory called .vcssync. The file is JSON-based with the extension that lines starting with // are accepted as comments. The file has the following shape:

    {
      "directory1": [ { action1 }, { action2 }, ..., { actionM } ],
      "directory2": [ { action1 }, { action2 } ],
      ...
      "directoryN": [ { action1 } ],
    }

That is, there is a top-level hash mapping directories to arrays of actions. An action consists of four possible arguments: 'sync' (either 'push' or 'pull'), 'remote' (the remote repository, default: origin), 'refs' (the set of branches, e.g., +master:master, default: 'master') and 'freshness' (how often to perform the action, in hours).

Here's an example configuration file:

    // To register changes, run 'vcssync -r'.
    {
        "~/src/woodchuck": [
          // Pull daily.
          {"sync": "pull", "remote": "origin", "freshness": 24},
          // Backup every tracked branch every few hours.
          {"sync": "push", "remote": "backups", "refs": "+*:*", "freshness": 3}
        ],
        "~/src/gpodder": [
          // Pull every few days.
          {"sync": "pull", "remote": "origin", "freshness": 96}
        ]
    }

VCS Sync automatically figures out the repository format and invokes the right tool (currently only git and mercurial are supported; patches for other VCSes are welcome).

After you install the configuration file, you need to run 'vcssync -r' to inform Woodchuck of any changes to the configuration file.

You can use this on the N900, however, because this is a programmer's tool and you need to edit a file to use it, it is not installable using the hildon application manager. Instead, you'll need to run 'apt-get install vcssync' from the command line (the package is in the same repository as the Woodchuck server). If you encounter problems, consult $HOME/.vcssync.log.

I also use this script on my laptop, which runs Debian. Building packages for Debian is easy, just check out woodchuck and use dpkg-buildpackage:

    git clone http://hssl.cs.jhu.edu/~neal/woodchuck.git
    cd woodchuck
    dpkg-buildpackage -us -uc -rfakeroot

This (currently) generates eight packages. In addition to vcssync, you'll also need to install murmeltier (my Woodchuck implmentation), and pywoodchuck (a Python interface to Woodchuck).