Packaging with Darcs

About Darcs

David Roundy's Darcs is a distributed version control system that can work very nicely for Debian package maintenance. It is the only DVCS that has full-fledged support for cherrypicking of patches, which is a nice feature for this sort of work. Darcs does not need a central repo or network connectivity, though it can certainly work in that model of you so desire. Every repository in Darcs is a branch, branching is cheap, and commits to a central repo are a merge.

The Model

The basic idea of Debian package maintenance with Darcs is that you maintain two branches (repositories): one for the unmodified upstream source, and another for your Debian packages. You import new upstream versions into the upstream repository, then merge from the upstream repo into the Debian repo to update your Debian packages.

The Tools

You'll want to apt-get install darcs darcs-buildpackage. The darcs package, of course, provides the Darcs installation. If you're not already familiar with Darcs, go over and read the tutorial and the GettingStarted page on the Darcs wiki.

darcs-buildpackage is a set of tools by ?JohnGoerzen to automate the use of Darcs for maintaining Debian packages. The tools are:

Getting Started

First, you'll want to edit ~/.darcs-buildpackage and tell it where you intend to keep your Debian and upstream repositories. Mine looks like:

debianrepo = /home/jgoerzen/repo/debian/%(package)s
upstreamrepo = /home/jgoerzen/repo/debian/%(package)s.upstream

Next, you'll want to decide if you want to import existing history or start from scratch.

Importing the upstream code

From an upstream Darcs repo

You can use Darcs to track a Darcs-based upstream with darcs get and darcs pull, for example

darcs get "*" /home/arnouten/dev/debian/jack-tools.upstream

From source packages (keeps track of history)

To import existing history, you'll need a set of source packages (diff.gz, dsc, and orig.tar.gz). Run dbp-importdsc on each .dsc file, in order from oldest to newest. It will automatically Do The Right Thing and import into your Debian and upstream repos as appropriately, merging between them as well.

Starting Fresh

If you have no history you want to import, you'll want to start with an upstream tarball or directory. Use dbp-importorig /path/to/file.tar.gz packagename 1.2.3 where 1.2.3 is the upstream version you're importing. dbp-importorig will import the specified file into the upstream repo for the specified package (creating this repo if necessary), and tag it with the specified version.

Creating the Debian repo

Then, you will do something like:

cd ~/repo/debian
darcs get packagename.upstream packagename

to initialize your Debian repo. Now in your Debian repo, you can use dh_make to start hacking away (don't forget to darcs add the debian/ dir and all the files you create). Use darcs record early and often to commit changes.


When it's time to build, just use darcs-buildpackage in place of debuild. It will pass arguments on to debuild. If darcs-buildpackage detects that you need an orig.tar.gz (or a tar.gz for Debian-native packages), it will build one for you using the Darcs repo. (If you already have one, it won't replace it.) It will also pass on the required arguments to exclude _darcs from the tar.gz and diff.gz files as per Debian policy.

Once you've built and uploaded, it's a good idea to run dbp-markdeb to tag this version in your repository. Then you can check it out directly later. You may also want to darcs push your package to a public repository somewhere, for other users to see.

New Upstream

When a new upstream version comes out, use dbp-importorig again to import it into your upstream repo. Then, from your Debian repo, run:

darcs pull ../packagename.upstream

to import the upstream changes into the Debian repo. Hack away, resolve any conflicts, and darcs record early and often.

More Info

See also:

CategoryDeveloper CategoryPackaging