Ian Jackson: Don’t use apt-get source; use dgit


If you are a Debian user who knows git, don’t work with Debian source packages. Don’t use apt source, or dpkg-source. Instead, use dgit and work in git.

Also, don’t use: “VCS” links on official Debian web pages, debcheckout, or Debian’s (semi-)official gitlab, Salsa. These are suitable for Debian experts only; for most people they can be beartraps. Instead, use dgit.


Struggling with Debian source packages?

A friend of mine recently asked for help on IRC. They’re an experienced Debian administrator and user, and were trying to: make a change to a Debian package; build and install and run binary packages from it; and record that change for their future self, and their colleagues. They ended up trying to comprehend quilt.

quilt is an ancient utility for managing sets of source code patches, from well before the era of modern version control. It has many strange behaviours and footguns. Debian’s ancient and obsolete tarballs-and-patches source package format (which I designed the initial version of in 1993) nowadays uses quilt, at least for most packages.

You don’t want to deal with any of this nonsense. You don’t want to learn quilt, and suffer its misbehaviours. You don’t want to learn about Debian source packages and wrestle dpkg-source.

Happily, you don’t need to.

Just use dgit

One of dgit’s main objectives is to minimise the amount of Debian craziness you need to learn. dgit aims to empower you to make changes to the software you’re running, conveniently and with a minimum of fuss.

You can use dgit to get the source code to a Debian package, as a git tree, with dgit clone (and dgit fetch). The git tree can be made into a binary package directly.

The only things you really need to know are:

  1. By default dgit fetches from Debian unstable, the main work-in-progress branch. You may want something like dgit clone PACKAGE bookworm,-security (yes, with a comma).

  2. You probably want to edit debian/changelog to make your packages have a different version number.

  3. To build binaries, run dpkg-buildpackage -uc -b.

  4. Debian package builds are often disastrously messsy: builds might modify source files; and the official debian/rules clean can be inadequate, or crazy. Always commit before building, and use git clean and git reset --hard instead of running clean rules from the package.

Don’t try to make a Debian source package. (Don’t read the dpkg-source manual!) Instead, to preserve and share your work, use the git branch.

dgit pull or dgit fetch can be used to get updates.

There is a more comprehensive tutorial, with example runes, in the dgit-user(7) manpage. (There is of course complete reference documentation, but you don’t need to bother reading it.)


But I don’t want to learn yet another tool

One of dgit’s main goals is to save people from learning things you don’t need to. It aims to be straightforward, convenient, and (so far as Debian permits) unsurprising.

So: don’t learn dgit. Just run it and it will be fine :-).

Shouldn’t I be using “official” Debian git repos?

Absolutely not.

Unless you are a Debian expert, these can be terrible beartraps. One possible outcome is that you might build an apparently working program but without the security patches. Yikes!

I discussed this in more detail in 2021 in another blog post plugging dgit.

Gosh, is Debian really this bad?

Yes. On behalf of the Debian Project, I apologise.

Debian is a very conservative institution. Change usually comes very slowly. (And when rapid or radical change has been forced through, the results haven’t always been pretty, either technically or socially.)

Sadly this means that sometimes much needed change can take a very long time, if it happens at all. But this tendency also provides the stability and reliability that people have come to rely on Debian for.

I’m a Debian maintainer. You tell me dgit is something totally different!

dgit is, in fact, a general bidirectional gateway between the Debian archive and git.

So yes, dgit is also a tool for Debian uploaders. You should use it to do your uploads, whenever you can. It’s more convenient and more reliable than git-buildpackage and dput runes, and produces better output for users. You too can start to forget how to deal with source packages!

A full treatment of this is beyond the scope of this blog post.


Debian Debian Planet