dgit-user - Man Page

For many packages, the source package name is obvious. 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 :i386 comes from.)

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 jessie (Debian 8) is Debian stable; and the current version of Ubuntu is yakkety (Yakkety Yak, 16.10). You can specify either the codename jessie or the alias stable. If you don't say, you get sid, which is Debian unstable - the main work-in progress branch.

If you don't know what you're running, try this:

    % grep '^deb' /etc/apt/sources.list
    deb http://the.earth.li/debian/ jessie main non-free contrib
    ...
    %

For Debian, you should add ,-security to the end of the suite name, unless you're on unstable or testing. Hence, in our example jessie becomes jessie,-security. (Yes, with a comma.)

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

For each release (like jessie) there is a tracking branch for the contents of the archive, called remotes/dgit/dgit/jessie (and similarly for other suites).  This can be updated with dgit fetch jessie. This, 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 jessie,-security means that it should include  any updates available in jessie-security. The comma notation is a request to dgit to track jessie, or jessie-security if there is an update for the package there.

(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.)

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 comments in the git history. The contents of debian/patches are ignored when building binaries from dgitish git branches.

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

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.

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.

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 jessie,-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!

    % 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.

If you always commit, you can use

    % git clean -xdf
    % git reset --hard

to tidy up after a build. (If you forgot to commit, don't use those commands; 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).

    % 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.

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).

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.

    % mk-build-deps --root-cmd=sudo --install
    % 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.

You can build in an schroot chroot, with sbuild, instead of in your main environment.  (sbuild is used by the Debian build daemons.)

    % git clean -xdf
    % sbuild -c jessie -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.

    % sudo apt install ../libc6_*.deb

    % sudo dpkg -i ../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.

The git branch is not sufficient to build a source package the way Debian does. Source packages are somewhat awkward to work with. Indeed many plausible git histories or git trees cannot be converted into a suitable source package. So I recommend you share your git branch instead.

If a git branch is not enough, and you need to provide a source package but don't care about its format/layout (for example because some software you have consumes source packages, not git histories) you can use this recipe to generate a 3.0 (native) source package, which is just a tarball with accompanying .dsc metadata file:

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

If you need to provide a good-looking source package, be prepared for a lot more work. You will need to read much more, perhaps starting with dgit-nmu-simple(7), dgit-sponsorship(7) or dgit-maint-*(7)