The secret plan behind the “3.0 (quilt)” Debian source package format

New source package formats do wondersWhile I have spent countless hours working on the new source format known as “3.0 (quilt)”, I’ve just realized that I have never blogged about its features and the reasons that lead me to work on it. Let’s fix this.

The good old “1.0” format

Up to 2008, dpkg-source was only able to cope with a single source format (now named “1.0”). That format was used since the inception of the project. While it worked fine for most cases, it suffered from a number of limitations—mainly because it stored the Debian packaging files as a patch to apply on top of the upstream source tarball.

This patch can have two functions: creating the required files in the debian sub-directory and applying changes to the upstream sources. Over time, if the maintainer made several modifications to the upstream source code, they would end up entangled (and undocumented) in this single patch. In order to solve this problem, patch systems were created (dpatch, quilt, simple-patchsys, dbs, …) and many maintainers started using them. Each implementation is slightly different but the basic principle is always the same: store the upstream changes as multiple patches in the debian/patches/ directory and apply them at build-time (and remove them during cleanup).

Design goals for the new formats

When I started working on the new source package format, I set out to get rid of all the known limitations and to integrate a patch system in dpkg-source. I wanted to clear up the situation so that learning packaging only requires to learn one patch system and would not require modifying debian/rules to use it. I picked quilt because it was popular, came with a large set of features, and was not suffering from NIH syndrome. This lead to the “3.0 (quilt)” source format.

I also created “3.0 (native)” as a distinct format. “1.0” was able to generate two types of source packages (native and non-native) but I did not want to continue with this mistake of mixing both in a single format. The KISS principle dictated that the user should pick the format of his choice, put it in debian/source/format and be done with it. Now the build can rightfully fail when the requirements are not met instead of doing something unexpected as a fallback.

Features of “3.0 (quilt)”

This is the format that replaces the non-native variant of the 1.0 source format. The features below are specific to the new format and differentiate it from its ancestor:

  • Supports compression formats other than gzip: bzip2, lzma, xz.
  • Can use multiple upstream tarballs.
  • Can include binary files in the debian packaging.
  • Automatically replaces the “debian” directory present in the upstream tarball (no repacking required).
  • Creates a new quilt-managed patch in debian/patches/ when it finds changes to the upstream files.

Features of “3.0 (native)”

This format is very similar to the native variant of the 1.0 source format except for two things:

  • it supports compression formats other than gzip: bzip2, lzma, xz.
  • it excludes by default a bunch of files that should usually not be part of the tarball (VCS specific files, vim backup files, etc.)


Looking back at the history is interesting. This project already spans multiple years and is not really over until a majority of packages have switched to the new formats.

  • January 2008: the discussion how to cope with patches sanely rages on My initial decisions are the result of this discussion.
  • March 2008: I have implemented the new formats and I request feedback. dpkg 1.14.17 (uploaded to experimental) is the first release supporting them.
  • April 2008: I ask ftpmasters to support the new source packages in #457345.
  • June 2008: Lenny freeze. dpkg is not supposed to change anymore. Several changes concerning the new source formats are still accepted in the following months given that this code is not yet used in production and must only be present so that lenny can cope with new source packages once squeeze starts using them.
  • February 2009: Lenny release.
  • March 2009: Work on squeeze has started, ftpmasters have done nothing to support new source formats, I submit a patch in #457345 to speed things up. I start a wiki page to track the project’s progress and to answer common questions of maintainers.
  • November 2009: After an ftpmaster sprint, it’s now possible to upload new source packages in unstable. This draws massive attention to the new format and some people start complaining about some design decisions. The implementation of “3.0 (quilt)” changes a lot during this month. dpkg in lenny is even updated to keep up with those changes.
  • March 2010: Up to now, I was planning to let dpkg-source build new source packages by default at some point in the future. After several rounds of discussions, I agree that it’s not the best course of action and decides instead to make debian/source/format mandatory. The maintainer must be explicit about the source format that s/he wants to use.
  • October 2010: The new source formats are relatively popular, a third of the source packages have already switched: see the graph. The squeeze freeze in August clearly stopped the trend, hopefully it will continue once squeeze is released.
  • June 2013: Project is finished?

As you can see this project is not over yet, although the most difficult part is already behind me. For my part, the biggest lesson is that you won’t ever get enough review until your work is used within unstable. So if you have a Debian project that impacts a lot of people, make sure to organize an official review process from the start. And specifying your project through a Debian Enhancement Proposal is probably the best way to achieve this.

If you appreciate the work that I put into this project, feel free to join Flattr and to flattr dpkg from time to time. Or check out my page “Support my work“.

Everything you need to know about conffiles: configuration files managed by dpkg

The Debian policy dictates that package upgrades must take care of preserving user changes to configuration files. This article will explain you how most packages ensure this. This is important knowledge for anyone who has to manage upgrades: knowing how it works lets you easily automate most of it and deal correctly with the fallout.

How dpkg manages configuration files

Most packages rely on dpkg to properly install configuration files. Dpkg keeps a checksum of the last installed version of configuration file. When it must install a new version, it calculates the checksum of the currently installed file and if it doesn’t match anymore, it knows that the user has edited the file. In that case, instead of overwriting the configuration file, it asks the user what to do. You probably already have seen those questions, they look like this:

Configuration file `/etc/bash.bashrc'
 ==> Modified (by you or by a script) since installation.
 ==> Package distributor has shipped an updated version.
   What would you like to do about it ?  Your options are:
    Y or I  : install the package maintainer's version
    N or O  : keep your currently-installed version
      D     : show the differences between the versions
      Z     : start a shell to examine the situation
 The default action is to keep your current version.
*** bash.bashrc (Y/I/N/O/D/Z) [default=N] ? 

In this specific example, if you answer “Y” or “I” (for “yes” or “install”), dpkg will install the new version of /etc/bash.bashrc but it will also backup the current version in /etc/bash.bashrc.dpkg-old. If you answer “N” or “O” (for “no” or “old”), dpkg will install the new version in /etc/bash.bashrc.dpkg-dist and /etc/bash.bashrc is left untouched. The two other answers allow you to examine the differences before taking a decision. Note that if you choose to start a shell, the new version is currently available as /etc/bash.bashrc.dpkg-new (and since Squeeze there are convenient environment variables $DPKG_CONFFILE_OLD and $DPKG_CONFFILE_NEW in case you want to create a custom review script).

All configurations files managed by dpkg are called “conffiles” because that’s the name of the field where they are recorded in the dpkg database. You can display the list of conffiles for any package:

$ dpkg --status bash
 /etc/skel/.profile ecb6d3479ac3823f1da7f314d871989b
 /etc/skel/.bashrc 2afdd6c53990f2387a7ef9989af0bc07
 /etc/skel/.bash_logout 22bfb8c1dd94b5f3813a2b25da67463f
 /etc/bash.bashrc 5b3c3bc73d236e4e1b6f9b6c1ed5964e

The command “dpkg-query --showformat='${Conffiles}\n' --show bash” can give you the same information if you need to retrieve only that field. The 32 characters after the filename are the MD5 checksum of the original configuration file provided by the package.

Avoiding the conffile prompt

Every time that dpkg must install a new conffile that you have modified (and a removed file is only a particular case of a modified file in dpkg’s eyes), it will stop the upgrade and wait your answer. This can be particularly annoying for major upgrades. That’s why you can give predefined answers to dpkg with the help of multiple --force-conf* options:

  • --force-confold: do not modify the current configuration file, the new version is installed with a .dpkg-dist suffix. With this option alone, even configuration files that you have not modified are left untouched. You need to combine it with --force-confdef to let dpkg overwrite configuration files that you have not modified.
  • --force-confnew: always install the new version of the configuration file, the current version is kept in a file with the .dpkg-old suffix.
  • --force-confdef: ask dpkg to decide alone when it can and prompt otherwise. This is the default behavior of dpkg and this option is mainly useful in combination with --force-confold.
  • --force-confmiss: ask dpkg to install the configuration file if it’s currently missing (for example because you have removed the file by mistake).

If you use Apt, you can pass options to dpkg with a command-line like this:

$ apt-get -o Dpkg::Options::="--force-confdef" -o Dpkg::Options::="--force-confold" dist-upgrade

You can also make those options permanent by creating /etc/apt/apt.conf.d/local:

Dpkg::Options {

Bringing up the conffile prompt at any time

The conffile prompt is only displayed when dpkg detects that the package provides an new version of the conffile. Thus reinstalling the same package will not bring up the prompt. But you can instruct dpkg to ask nevertheless with the --force-confask option. This is a new feature in Debian Squeeze. It will only ask for files that are locally modified.

If you want to read more articles like this one, click here to subscribe to my free newsletter. You can also follow me on, Twitter and Facebook.

How to customize dpkg-source’s behaviour in your Debian source package

dpkg-source is the program that generates the Debian source package when a new package version is built. It offers many interesting command-line options but they are often not used because people don’t know how to ensure that they are used every time the package is built. Let’s fill that gap!

It is possible to forward some options to dpkg-source by typing them on the dpkg-buildpackage command line but you’d have to remember to type them every time. You could create a shell alias to avoid typing them but then you can’t have different options for different packages. Not very practical.

The proper solution has been implemented last year (in dpkg 1.15.5). It is now possible to put options in debian/source/options. Any long option (those starting with “--“) can be put in that file, one option per line with the leading “--” stripped.

Here’s an example:

# Bzip2 compression for debian.tar
compression = "bzip2"
compression-level = 7
# Do not generate diff for changes in config.(sub|guess)
extend-diff-ignore = "(^|/)config.(sub|guess)$"

Notice that spaces around the equal sign are possible contrary on the command line. You can use quotes around the value but it’s not required.

The debian/source/options file is part of the source package so if someone else grabs the resulting source package and rebuilds everything, they will use the options that you defined in that file.

You can also use debian/source/local-options but this time the file will not be included in the resulting source package. This is interesting for options that you want to use when you build from the VCS (Version Control Repository, aka git/svn/bzr/etc.) but that people downloading the resulting source package should not have. Some options (like --unapply-patches) are only allowed in that file to ensure a consistent experience for users of source packages.

You can learn more about the existing options in the dpkg-source manual page. Read it, I’m sure you’ll learn something. Did you know that you can tell dpkg-source to abort if you have upstream changes not managed by an existing patch in debian/patches? It’s --abort-on-upstream-changes and it’s only allowed in debian/source/local-options.

Be sure to subscribe to the RSS feed or to the email newsletter to not miss useful documentation for Debian contributors!

How to make 110.28 EUR in one month with free software and Flattr

Flattr FOSS Logo

  1. Create an account on (mine is here);
  2. Submit the URL of your free software project to the Flattr directory with a good description and the proper tags (here’s my entry for dpkg);
  3. Add a Flattr button on your website (I put one on;
  4. Inform your users and reach out to free software users using Flattr by registering your project in Flattr FOSS.

And I’m not alone, Joey Hess made 25 EUR in one week only.

And right now only 30K people are using Flattr. I expect this number to increase significantly now that invites are no longer required to open a Flattr account (see the announce on Flattr’s blog).

It’s time to spread the word about Flattr FOSS!

Quick news: dpkg, collab-maint, alioth and the future

Dpkg got rid of Perl

Let’s start with the interesting part and the great news: dpkg 1.15.8 (to be uploaded soon) will no longer need perl! After my changes to rewrite update-alternatives in C, Guillem recently pushed the rewrite of dpkg-divert/mksplit in C. Please test it out (binary package for i386 or .dsc).

This is rather exciting news for those who would like to use dpkg in embedded contexts. And it’s great to see this completed in time for Squeeze. In Squeeze+1, we might go one step further and merge cdebconf, the C replacement for debconf.

I got rid of some recurring administrative tasks

I have been administrating the Alioth server since its inception (see the announce I sent in 2003) but I’m no longer enjoying the day-to-day administrative work that it represents. That’s why I just retired from the team. We recently recruited Tollef Fog Heen so the number of admins is still the same (that said, Alioth could benefit from some more help, if you’re a DD and interested, drop a mail to or come to #alioth).

Same goes for the collab-maint project. I have dealt with hundreds of requests to add new contributors to the project since it’s the central repository where all Debian developers have write access and where they put the VCS for their packages that do not belong to a more specialized team. The new administrator that will approve the requests is Xavier Oswald and he’s doing the work under the umbrella of the New Maintainer’s Front Desk.

The future

I will continue to spend the same amount of time on Debian, the time freed will quickly be reallocated to other Debian and free software related projects. In fact, I even anticipated a bit by launching Flattr FOSS last week but that’s a relatively simple project. :-)

The other projects that will never all fit in the freed time: I want to spend more time working on dpkg. I do plan to blog more often too, but I’m sure you’ll notice that yourself soon. I would like to see my Debian book translated into English (another post coming on the topic sometimes soon). In my dreams, I could even start yet another software project, I have some ideas that I really would like to see implemented but I don’t see how that could fit in this year’s planning… unless I can convince someone else to implement them! Maybe I should blog about them.

Rewriting update-alternatives in C

Among the goals listed in dpkg’s roadmap, there’s the C rewrite of the remaining perl scripts provided by the dpkg binary package (dpkg-dev is not concerned, it will remain a collection of perl scripts). Of the remaining scripts, update-alternatives was the largest piece of code (~1100 lines of perl) and I started converting it to C a few weeks ago (based on preliminary work of Guillem). It’s now 2200 lines of C…

Thanks to the relatively extensive test-suite that I wrote last year, I’m relatively confident that this new update-alternatives won’t break your system. That said, it still needs some real-life usage to ensure everything is really ok (and users actively trying to break it are even better). Thus I would be glad if you could try it out ( binary package for i386 or .dsc) and report back to

The rewrite of the 2 other remaining scripts is almost completed in a branch of Guillem. Hopefully this can be our last project completed in time for Squeeze as far as dpkg goes. It would be a great achievement for people that would like to use dpkg in embedded environments and avoid perl due to its size.

Note: nobody sponsored that work. But it’s not too late :-)

Debian related goals for 2010

Here’s stuff that I’d like to do this year, more or less by decreasing order of importance:

  • translate my Debian book into English and get it published;
  • finish the cleanup of the perl API in dpkg-dev in order to create libdpkg-perl;
  • create dpkg-buildflags to export default build flags that packages should use (and get rid of the code setting those environment variables in dpkg-buildpackage), needed to properly fix #489771;
  • ensure the new source formats continue to gain acceptance by improving whatever is needed;
  • design a generic vcs-buildpackage infrastructure to be integrated in dpkg-dev. This design will probably happen through a DEP (Debian Enhancement Proposal) to ensure we have had proper discussion before someone gets to the implementation;
  • continue fixing dpkg bugs faster than they are reported;
  • enhance our infrastructure to ease interaction between contributors and to have a better view of how each package is maintained (see my last blog entry on this topic);
  • update the developers-reference where needed and fix some of the numerous wishlist bugs;
  • rewrite in C the last perl scripts provided by the dpkg binary package (update-alternatives/mksplit mainly, for dpkg-divert there’s a preliminary patch available already) so that it’s easier to build a minimal system without perl-base;
  • integrate the 3-way merge tool for Debian changelogs in dpkg-dev;

All of this probably doesn’t fit in my free time (being a father since last month does not help increasing my free time :-)), so if you’re interested in seeing one or more of those projects completed, and if you know some person/company that could sponsor them, get in touch with me!

5 years of Freexian

5 years ago I founded my own company Freexian SARL with the goal to make a living out of my free software experience. I marketed the company as being specialized on the Debian distribution in the hope to combine my Debian work and my professional work.

Given that Freexian is still alive I think I met the first goal. My free software experience allowed me to complete many projects: a large number of development projects for embedded devices running a custom Linux distribution (usually built with debian udebs), the development of a Debian derivative (SLIS) and some recurring tasks of remote system administration.

However, even if I use Debian daily for all my work, very few of the projects that I complete for customers have direct results in terms of improvements for Debian (except some bugreports and some related fixes). And even when I’m able to contribute something back to Debian, it’s usually not in areas that I care about.

My focus within Debian is on the technical and organizational infrastructure of the project: as a dpkg/dpkg-dev maintainer I try to improve the packaging infrastructure, as a QA member I maintain the Package Tracking System to ease collaboration, as an Alioth admin I ensure all DD can host VCS repositories for their Debian related projects, as a developers-reference co-maintainer I try to share good packaging practices, etc. Given this bias, it’s difficult to find customer projects that would let me contribute in those areas. Thus I think I need to try another approach: the simplest solution would be to find sponsors for some of my own Debian-related projects (if you have something else to suggest, please leave a comment — either in the blog or by mail).

That said finding sponsors looks like a difficult task in itself. While I can imagine (for example) a company using Debian on embedded devices that would like to sponsor the rewrite of update-alternatives in C in order to get rid of the perl dependency in the dpkg package (if you know such a company, get in touch with me!), I don’t see who would have an interest in sponsoring the time that I need to contribute new sections to the developers-reference manual. But who knows… maybe I should just try and publicly solicit sponsorship for some of the projects that I care about. In any case, suggestions and comments are welcome!

New source formats allowed in testing/unstable

The ftpmasters merged my dak branch last week during their meeting and have enabled the support of new source formats “3.0 (quilt)” and “3.0 (native)” in testing, unstable and testing-proposed-updates. I have uploaded 3 packages using the new formats already: logidee-tools using “3.0 (native)”, quilt and ftplib using “3.0 (quilt)”. The latter is arch any and has been successfully built on all architectures even those that still use an old version of sbuild (it looks like the fears that the old version would not cope with the new format were unfounded). For logidee-tools I built it with “-Zbzip2” in order to use bzip2 compression on the native tarball.

I have updated the wiki page and the release goal page with latest information. Feel free to convert some of your packages to give it a try. For ftplib, it led me to discover a Debian specific patch that I completely missed when I took the package over. This is precisely the kind of benefit that I expect from generalizing this format, it will encourage us to have separate documented patches instead of keeping everything hidden inside the usual .diff.gz. Combined with DEP-3 (patch tagging guidelines), we have a better infrastructure to share our patches with the rest of the free software community.

The next step is to fix all bugs listed here and make dpkg-source use the new source formats by default (#553928). Feel free to help by preparing patches (and offering NMUs), it’s a release goal to have all packages buildable with new source formats.

3-way merge of Debian changelog files

I’ve been considering for some time now to create a merge tool specifically suited for debian/changelog files. My goal was to let Git use it automatically thanks to gitattributes.

I’ve just gone ahead, so let me introduce you git-merge-dch. Grab it with git clone git://, you can build a package if you wish. Beware, you need to have a dpkg-dev 1.15.5 that is not yet published (so you need to build dpkg from its git repository, git clone git:// as I rely on features that I introduced recently… you will also need the libalgorithm-merge-perl package.

Using it in a git repository requires two changes:

  • defining a new merge driver somewhere in the git configuration (in .git/config or ~/.gitconfig for example):
    [merge "git-merge-dch"]
            name = debian/changelog merge driver
            driver = git-merge-dch -m %O %A %B %A
  • defining the merge attribute for debian/changelog files either in .gitattributes in the repository itself or in .git/info/attributes:
    debian/changelog merge=git-merge-dch

Now you can safely maintain two branches of a package with changelog files evolving separately and merge one into the other without creating undue conflicts. Suppose you created an experimental branch for version 2.28 (you use a version 2.28-1~exp1) when 2.26.2 was current stable in the master branch. In the mean time, 2.26.3 got out and was packaged in master. Next time you merge stable into experimental, the changelog entries for 2.28 and 2.26.3 won’t collide despite being at the same place in the changelog file compared to the common ancestor.

Let’s continue with this example, 2.28 is out. Instead of adding a new changelog entry with “New upstream release” without further changes, you keep the current changelog entry and simply change the version into 2.28-1. While preparing this you discover a branch with fixes that was based on 2.28-1~exp1, if you merge it it will reintroduce a 2.28-1~exp1 entry that you don’t want. Fortunately you can use the --merge-prereleases (-m) option of git-merge-dch so that it strip the prerelease part of the version string and considers 2.28-1~exp1 and 2.28-1 to be the same entry really.

The only limitation is that this merge tool will remove any lines which are not parsed by Dpkg::Changelog (and which in theory are not supposed to be there).

Feel free to test, share your comments, report bugs and send patches!

Update: the script has been merged in dpkg-dev (>= 1.15.7) under the name dpkg-mergechangelogs.