dgit-user(7)

📦
version 17.0 · 8 versions
, in ubuntu stonking

🎀 dgit-user(7) 🎀

okay bestie, buckle up — this is dgit-user, the manual page about making and sharing changes to Debian packages, with git. it's part of the dgit family and it's here to hold your hand through the whole vibe 💖

✨ NAME ✨

dgit-user — making and sharing changes to Debian packages, with git 🌸

🫶 INTRODUCTION 🫶

dgit lets you fetch the source code to every package on your system as if your distro used git to maintain all of it. literally all of it. the whole distro. as git. iconic behavior, no cap 👑

so then you can edit it, build updated binary packages (.debs), and install and run them. and you can share your work with others too — main character energy 💅

this tutorial is a pile of recipes and hints for doing exactly that. it assumes you've got basic familiarity with git. it does not assume any initial familiarity with Debian's packaging processes — so if that's you, you're in the right place 🦋

but if you are a package maintainer within Debian; a DM or DD; and/or a sponsee — bestie, this tutorial is not for you. try dgit-nmu-simple(7), dgit-maint-*(7), or dgit(1) and dgit(7). go get your own manual 💅

🌈 SUMMARY 🌈

so these runes? we'll unpack them later, promise. but here's the whole vibe up front:

% dgit clone glibc bookworm,-security
% cd glibc
% curl 'https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=28250;mbox=yes;msg=89' | patch -p1 -u
% git commit -a -m 'Fix libc lost output bug'
% gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
% sudo apt-get build-dep .
% dpkg-buildpackage -uc -b
% sudo dpkg -i ../libc6_*.deb

and occasionally, when things get messy:

% git clean -xdf
% git reset --hard

and then later, when you come back for round two:

% cd glibc
% dgit pull bookworm,-security
% gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
% dpkg-buildpackage -uc -b
% sudo dpkg -i ../libc6_*.deb

🔍 FINDING THE RIGHT SOURCE CODE - DGIT CLONE 🔍

% dgit clone glibc bookworm,-security
% cd glibc

dgit clone needs to be told two things, bestie:

  1. the source package name — which might be different to the binary package name, which was the name you passed to apt-get install 😭
  2. the codename or alias of the Debian release — this is called the "suite"

🦋 Finding the source package name 🦋

for many packages, the source package name is obvious. but otherwise, if you know a file that's in the package, you can look it up with dpkg:

% dpkg -S /lib/i386-linux-gnu/libc.so.6
libc6:i386: /lib/i386-linux-gnu/libc.so.6
% dpkg -s libc6:i386
Package: libc6
Status: install ok installed
...
Source: glibc

(in this example, libc6 is a "multi-arch: allowed" package, which means that it exists in several different builds for different architectures. that's where the :i386 comes from. mystery solved 🔎)

🌸 Finding the Debian release (the "suite") 🌸

internally, Debian (and derived) distros normally refer to their releases by codenames. Debian also has aliases which refer to the current stable release etc. so for example, at the time of writing Debian bookworm (Debian 12) is Debian stable; and the current version of Ubuntu is plucky (Plucky Puffin, 25.04). you can specify either the codename bookworm or the alias stable. and if you don't say anything? you get sid, which is Debian unstable — the main work-in-progress branch 🌀

if you don't know what you're running, please refer to your apt configuration in /etc/apt/sources* or in /etc/debian_version 👀

for Debian, you should add ,-security to the end of the suite name, unless you're on unstable or testing. hence, in our example bookworm becomes bookworm,-security. (yes. with a comma. it's giving chaos but it's correct 💀)

🎁 WHAT DGIT CLONE PRODUCES 🎁

💜 What branches are there 💜

dgit clone will give you a new working tree, and arrange for you to be on a branch named like dgit/bookworm,-security (yes, with a comma in the branch name. we love a funky branch name 💅).

for each release (like bookworm) there is a tracking branch for the contents of the archive, called remotes/dgit/dgit/bookworm (and similarly for other suites). this can be updated with dgit fetch bookworm. this one — the remote suite branch — is synthesized by your local copy of dgit. it is fast forwarding ⚡

Debian separates out the security updates, into *-security. telling dgit bookworm,-security means that it should include any updates available in bookworm-security. the comma notation is a request to dgit to track bookworm, or bookworm-security if there is an update for the package there. so considerate 🫶

(you can also dgit fetch in a tree that wasn't made by dgit clone. if there's no debian/changelog you'll have to supply a -ppackage option to dgit fetch.)

⭐ What kind of source tree do you get ⭐

if the Debian package is based on some upstream release, the code layout should be like the upstream version. you should find git grep helpful to find where to edit 🔎

the package's Debian metadata and the scripts for building binary packages are under debian/. debian/control, debian/changelog and debian/rules are the starting points. the Debian Policy Manual has most of the in-depth technical details 📚

for many Debian packages, there will also be some things in debian/patches/. it is best to ignore these. insofar as they are relevant, the changes there will have been applied to the actual files — probably by means of actual commits in the git history. the contents of debian/patches are ignored when building binaries from dgitish git branches. so like… don't touch, it's handled 🙈

(for Debian afficionados: the git trees that come out of dgit are "patches-applied packaging branches without a .pc directory".)

🌟 What kind of history you get 🌟

if you're lucky, the history will be a version of, or based on, the Debian maintainer's own git history, or upstream's git history. lucky you 🍀

but for many packages the real git history does not exist, or has not been published in a dgitish form. so you may find that the history is a rather short history invented by dgit. yeah. it made it up. slay, i guess 💀

dgit histories often contain automatically-generated commits, including commits which make no changes but just serve to make a rebasing branch fast-forward. this is particularly true of combining branches like bookworm,-security.

if the package maintainer is using git then after dgit clone you may find that there is a useful vcs-git remote referring to the Debian package maintainer's repository for the package. you can see what's there with git fetch vcs-git. but use what you find there with care: Debian maintainers' git repositories often have contents which are very confusing and idiosyncratic 😵‍💫 in particular, you may need to manually apply the patches that are in debian/patches before you do anything else!! consider yourself warned 💖

🔥 BUILDING 🔥

🎀 Always commit before building 🎀

% wget 'https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=28250;mbox=yes;msg=89' | patch -p1 -u
% git commit -a -m 'Fix libc lost output bug'

Debian package builds are often quite messy: they may modify files which are also committed to git, or leave outputs and temporary files not covered by .gitignore. it's a whole situation 🫠

so if you always commit, you can use

% git clean -xdf
% git reset --hard

to tidy up after a build. clean and fresh, the way it should be ✨

(if you forgot to commit — do not use those commands, bestie 😭 instead, you may find that you can use git add -p to help commit what you actually wanted to keep.)

these are destructive commands which delete all new files (so you must remember to say git add) and throw away edits to every file (so you must remember to commit). like, genuinely destructive. no undo. periodt 💀

🌸 Update the changelog (at least once) before building 🌸

% gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit

the binaries you build will have a version number which ultimately comes from the debian/changelog. you want to be able to tell your binaries apart from your distro's — otherwise it's just chaos out there 👑

so you should update debian/changelog to add a new stanza at the top, for your build.

this rune provides an easy way to do this. it adds a new changelog entry with an uninformative message and a plausible version number (containing a bit of your git commit id). lowkey genius, honestly 💅

if you want to be more sophisticated, the package dpkg-dev-el has a good Emacs mode for editing changelogs. alternatively, you could edit the changelog with another text editor, or run dch or gbp dch with different options. choosing a good version number is slightly tricky and a complete treatment is beyond the scope of this tutorial. we're keeping it cute and simple today 🎀

🦋 Actually building 🦋

% sudo apt-get build-dep .
% dpkg-buildpackage -uc -b

dpkg-buildpackage is the primary tool for building a Debian source package.

  • -uc means not to pgp-sign the results.
  • -b means build all binary packages, but not to build a source package.

💫 Using sbuild 💫

you can build in an schroot chroot, with sbuild, instead of in your main environment. (sbuild is used by the Debian build daemons, so it's got credentials 💅)

% git clean -xdf
% sbuild -d trixie -A --no-clean-source \
         --dpkg-source-opts='-Zgzip -z1 --format=1.0 -sn'
note that this will seem to leave a "source package" (.dsc and .tar.gz) in the parent directory, but that source package should not be used. it is likely to be broken. 🙈 for more information see Debian bug #868527.

💖 INSTALLING 💖

% sudo apt install ../libc6_*.deb

you can use dpkg -i to install the .debs that came out of your package.

if the dependencies aren't installed, you will get an error, which can usually be fixed with apt-get -f install. easy fix, no stress 🫶

✨ Multiarch ✨

if you're working on a library package and your system has multiple architectures enabled, you may see something like this:

dpkg: error processing package libpcre3-dev:amd64 (--configure):
 package libpcre3-dev:amd64 2:8.39-3~3.gbp8f25f5 cannot be configured because libpcre3-dev:i386 is at a different version (2:8.39-2)

the multiarch system used by Debian requires each package which is present for multiple architectures to be exactly the same across all the architectures for which it is installed. no exceptions, it's a whole thing 😤

so, your options:

  • the proper solution is to build the package for all the architectures you have enabled. you'll need a chroot for each of the secondary architectures. this is somewhat tiresome, even though Debian has excellent tools for managing chroots. sbuild-debian-developer-setup from the package of the same name and sbuild-createchroot from the sbuild package are good starting points.
  • otherwise you could deinstall the packages of interest for those other architectures with something like dpkg --remove libpcre3:i386.
  • and if neither of those are an option — your desperate last resort is to try using the same version number as the official package for your own package. (the version is controlled by debian/changelog — see above.) this is not ideal, because it makes it hard to tell what is installed, and because it will mislead and confuse apt 😵

with the "same number" approach you may still get errors like

trying to overwrite shared '/usr/include/pcreposix.h', which is
different from other instances of package libpcre3-dev

but passing --force-overwrite to dpkg will help — assuming you know what you're doing 👀

💌 SHARING YOUR WORK 💌

Okay bestie so that dgit/bookworm,-security branch (or literally whatever your branch is named, it's giving choose-your-own-adventure) is just a normal git branch. Nothing cursed. Nothing weird. You can git push it to any suitable git server and it just... lives there. Periodt. ✨

And the way that anyone who pulls that branch off you can build binary packages (.debs, babes) exactly like you did? Iconic. No extra steps, no secret sauce. 🫶

Now — if you want to fire your changes back at Debian, the move is to send them as attachments in an email to the Debian Bug System at https://bugs.debian.org/ (either as a followup on an existing bug, or as a whole new bug, your call). Patches in git-format-patch format are usually very welcome. Like, people love those. Be that person. 💅

📦 Source packages 📦

So here's the thing, and I need you to hear me: the git branch alone is not enough to build a source package the way Debian does. Source packages are, and I say this with love, somewhat awkward to work with. Fr fr. Many perfectly plausible git histories or git trees just cannot be converted into a suitable source package. So my honest recommendation? Share your git branch instead. Lowkey simpler. 🌸

But okay, if a git branch truly isn't enough, and you need to hand over a source package but genuinely don't care about its format or layout (like, say, some software you have consumes source packages and not git histories — no judgement), you can use this little recipe to generate a 3.0 (native) source package. And what even is that? It's just a tarball with an accompanying .dsc metadata file. Cute, right? 🎀

% echo '3.0 (native)' >debian/source/format
% git commit -m 'switch to native source format' debian/source/format
% dgit -wgf build-source

Now if you need to provide a source package that's actually good-looking? Bestie. Be prepared for a lot more work. 😭 You will need to read much more — maybe start with dgit-nmu-simple(7), dgit-sponsorship(7) or dgit-maint-*(7). Consider this your warning and your invitation. 🦋

✨ INSTALLING NEWER DGIT ON OLDER DISTROS ✨

If dgit breaks on the source package you're working with, it might be a bug that would be fixed by upgrading. (Not you, bestie. It's not your fault. It's giving "the software's fault". 💀)

The good news: you can probably just directly apt install the latest version of dgit.deb from Debian stable, or Debian testing. Slay. 🫶

Versions of dgit from Debian 13 (trixie) onwards document their installability on old releases in the manpage. For example, for current Debian testing, go look at https://manpages.debian.org/testing/dgit/dgit.1.en.html, and then peek in the section SUPPORT ON OLD DISTRIBUTIONS. Iykyk. 👑

🌈 SEE ALSO 🌈

And that's a wrap on this lil manual page, bestie 💖 it's brought to you by the Debian Project and the dgit+tag2upload team, and the page itself is dgit-user(7). Now go push something iconic, build something slay, and don't forget to read the docs. Mwah. 🌟🎀

📦 where this page comes from