3 files changed, 335 insertions, 55 deletions
@@ -7,5 +7,6 @@ debian/*.substvars
diff --git a/dgit-nmu-simple.7.pod b/dgit-nmu-simple.7.pod
new file mode 100644
@@ -0,0 +1,108 @@
+dgit-nmu-simple - tutorial for DDs wanting to NMU with git
+=head1 INTRODUCTION AND SCOPE
+This tutorial describes how a Debian Developer can do
+a straightforward NMU
+of a package in Debian, using dgit.
+This document won't help you decide whether
+an NMU is a good idea or
+whether it be well received.
+The Debian Developers' Reference has some
+(sometimes questionable) guidance on this.
+Conversely, you do not need to know anything
+about the usual maintainer's workflow.
+If appropriate, you can work on many different packages,
+making similar changes,
+without worrying about the individual maintainers' git practices.
+This tutorial only covers changes which
+can sensibly be expressed as a
+reasonably small number of linear commits
+(whether to Debian packaging or to upstream files or both).
+If you want to do a new upstream version,
+you probably want to do as the maintainer would have done.
+You'll need to find out what the maintainer's
+git practices are
+consult the appropriate C<dgit-maint-*(7)> workflow tutorial,
+ % dgit clone glibc jessie
+ % cd glibc
+ % git am ~/glibc-security-fix.diff
+ [ edit debian/changelog to introduce a ~ version, and commit it ]
+ % dpkg-buildpackage -uc -b
+ [ run your tests ]
+ [ edit debian/changelog to prepare for release, and commit it ]
+ % dgit -wgf sbuild -A -c jessie
+ [ final tests on generated .debs ]
+ % dgit -wgf push jessie
+ [ enter your gnupg passphrase as prompted ]
+ [ see that push and upload are successful ]
+ [ prepare and email NMU diff (git-diff, git-format-patch) ]
+=head1 WHAT KIND OF CHANGES AND COMMITS TO MAKE
+When preparing an NMU, the git commits you make on the dgit branch
+should be simple linear series of commmits with good commit messages.
+The commit messages will be published in various ways,
+including perhaps being used as the cover messages for
+genrated quilt patches.
+Do not make merge commits.
+Do not try to rebase to drop patches - if you need to revert a
+change which is actually a Debian patch,
+If you need to modify a Debian patch,
+make a new commit which fixes what needs fixing,
+and explain in the commit message which patch it should be
+(perhaps by use of a commit message in C<git rebase --autosquash -i>
+(Of course if you have specific instructions from the maintainer,
+you can follow those instead.
+But the procedure in this tutorial is legitimate for any maintainer,
+in the sense that it should generate an upload to which the
+maintainer cannot reasonably object.)
+=head1 RELEVANT BRANCHES
+dgit clone will put you on a branch like C<dgit/sid>.
+There is a pseudo-remote called C<dgit> which also contains a branch
+like C<dgit/sid>, so you do things like
+C<git diff dgit/dgit/sid>
+to see what changes you have made.
+=head1 KEEPING YOUR WORKING TREE TIDY
+Don't forget to C<git add> any new files you create.
+Otherwise git clean
+(which is requested with the C<-wgf> option in the recipe above)
+will delete them.
+Many package builds leave dirty git trees.
+So, commit before building.
+That way you can use C<git reset --hard>.
+If you follow this approach
+you don't need to care about the build dirtying the
+It also means you don't care about the package clean target,
+which is just as well because many package clean targets are broken.
+=head1 SEE ALSO
+dgit(1), dgit(7), dgit-maint-*(7)
diff --git a/dgit-user.7.pod b/dgit-user.7.pod
index 54bfa1d..d27cd93 100644
@@ -1,24 +1,33 @@
-dgit - tutorial for users of Debian-derived distros supported by dgit
+dgit-user - making and sharing changes to Debian packages, with git
dgit lets you fetch the source code to every package on your
- as if your distro used git to maintain all of it.
+as if your distro used git to maintain all of it.
You can then edit it,
build updated binary packages
and install and run them.
You can also share your work with others.
-This tutorial assumes you have basic familiarity with git.
+This tutorial gives some recipes and hints for this.
+It assumes you have basic familiarity with git.
It does not assume any initial familiarity with
- Debian's packaging processes.
+Debian's packaging processes.
+If you are a package maintainer within Debian; a DM or DD;
+and/or a sponsee:
+this tutorial is not for you.
+Try L<dgit-nmu-simple(7)>, L<dgit-maint-*(7)>,
+or L<dgit(1)> and L<dgit(7)>.
+(These runes will be discussed later.)
% dgit clone glibc jessie
@@ -32,6 +41,15 @@ It does not assume any initial familiarity with
+ % git clean -xdf
+ % git reset --hard
@@ -46,9 +64,16 @@ Later:
=head1 FINDING THE RIGHT SOURCE CODE - DGIT CLONE
+ % dgit clone glibc jessie
+ % cd glibc
dgit clone needs to be told the source package name
(which might be different to the binary package name)
-and the codename of the Debian release
+and the codename or alias of the Debian release
(this is called the "suite").
=head2 Finding the source package name
@@ -79,9 +104,14 @@ That's where C<:i386> comes from.)
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 C<jessie> (Debian 8) is Debian stable and
+Debian C<jessie> (Debian 8) is Debian C<stable>; and
the current version of Ubuntu is C<yakkety> (Yakkety Yak, 16.10).
+You can specify either
+the codename C<jessie> or the alias C<stable>.
+If you don't say, you get C<sid>,
+which is Debian C<unstable> - the main work-in progress branch.
If you don't know what you're running, try this:
@@ -94,15 +124,33 @@ If you don't know what you're running, try this:
-=head1 EDITING THE SOURCE CODE
+=head1 WHAT DGIT CLONE PRODUCES
-=head2 What kind of source tree you get when you dgit clone
+=head2 What branches are there
-If the Debian package is actually a version of an upstream release,
+dgit clone will give you a new working tree,
+and arrange for you to be on a branch like
+There is a tracking branch for the contents of the archive, called
+(and similarly for other suites). This can be updated with
+C<dgit fetch jessie>.
+This, the I<remote suite branch>,
+is synthesized by your local copy of dgit.
+It is fast forwarding.
+(You can also dgit fetch in a tree that wasn't made by dgit clone.
+If there's no C<debian/changelog>
+you'll have to supply a C<-p>I<package> option to dgit fetch.)
+=head2 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 that git commands C<git grep> work properly.
+You should find C<git grep> helpful to find where to edit.
-The package's Debian metadata and the script for building binary
+The package's Debian metadata and the scripts for building binary
packages are under C<debian/>.
C<debian/control>, C<debian/changelog> and C<debian/rules> are the
@@ -111,11 +159,17 @@ technical details.
For many Debian packages,
there will also be some things in C<debian/patches/>.
-These will probably be in your git history
-(one way or another),
-and they are not used when building a package
-based on a git histroy obtained with dgit.
-It is best to ignore them.
+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".)
=head2 What kind of history you get
@@ -125,8 +179,8 @@ the Debian maintainer's own git history,
or upstream's git history.
But for many packages the real git history
-does not exist or
-cannot be obtained in a standard form
+does not exist,
+or has not been published in a dgitish form.
So yuu may find that the history is a rather short
history invented by dgit.
@@ -137,53 +191,107 @@ to make a rebasing branch fast-forward.
If the package maintainer is using git then
after dgit clone
you may find that there is a useful C<vcs-git> remote
-referring to the Debian package maintainers repository
-for the pacakge.
+referring to the Debian package maintainer's repository
+for the package.
You can see what's there with C<git fetch vcs-git>.
But use what you find there with care:
-Debian maintainers' git histories are often in
-formats which are very confusing and idiosyncratic
-from the point of view of those new to Debian git packaging.
+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!
-=head2 Always commit first
+=head2 Always commit before building
-When using git with some arbitrary Debian package
-you should normally 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'
-This is because Debian package builds are often quite messy:
+Debian package builds are often quite messy:
they may modify files which are also committed to git,
or leave outputs and teporary files not covered by C<.gitignore>.
Kf you always commit,
-you can use C<git reset --hard> and C<git clean -xdf>
-to put things back.
-But if you create a new file
-B<don't forget> to say C<git add>, and commit,
-as otherwise C<git clean> will delete your new file.
+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 C<git add -p>
+to help commit what you actually wanted to keep.)
+These are destructive commands which delete all new files
+(so you B<must> remember to say C<git add>)
+and throw away edits to every file
+(so you B<must> remember to commit).
+=head2 Update the changelog (at least once) before building
-=head2 Update the changelog (at least once)
+ % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
The binaries you build will have a version number which ultimately
-comes from the C<debian/changelog>. You want to be able to tell your
+comes from the C<debian/changelog>.
+You want to be able to tell your
binaries apart from your distro's.
So you should update C<debian/changelog>
to add a new stanza at the top,
for your build.
-An easy way to do this is this rune:
+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 C<dpkg-dev-el> has a good Emacs mode
+for editing changelogs.
+Alternatively, you could edit the changelog with another text editor,
+or run C<dch> or C<gbp dch> with different options.
+Choosing a good version number is slightly tricky and
+a complete treatment is beyond the scope of this tutorial.
+=head2 Actually building
- % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
+ % sudo apt-get build-dep glibc
+ % dpkg-buildpackage -uc -b
-which adds a new entry with a new version number chosen in a
-reasonably sensible way, and commits the result to your git branch.
+apt-get build-dep installs the build dependencies according to the
+official package, not your modified one. So if you've changed the
+build dependencies you might have to install some of them by hand.
+dpkg-buildpackage is the primary tool for building a Debian source
+C<-uc> means not to pgp-sign the results.
+C<-b> means build all binary packages,
+but not to build a source package.
+ % sudo dpkg -i ../libc6_*.deb
You can use C<dpkg -i> to install the
.debs that came out of your package.
@@ -191,42 +299,105 @@ If the dependencies aren't installed,
you will get an error, which can usually be fixed with
C<apt-get -f install>.
+If you're working on a library package and your system has multiple
+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.
+The proper solution
+is to build the package for all the architectures you
+You'll need a chroot for each of the secondary architectures.
+This iw somewhat tiresome,
+even though Debian has excellent tools for managing chroots.
+C<sbuild-createchroot> from the sbuild package is a
+good starting point.
+Otherwise you could deinstall the packages of interest
+for those other architectures
+with something like C<dpkg --remove libpcre3:i386>.
+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 verseion is controlled by C<debian/changelog> - see above,)
+This is not ideal because it makes it hard to tell what is installed,
+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 C<--force-overwrite> to dpkg will help
+- assuming you know what you're doing.
=head1 SHARING YOUR WORK
The C<dgit/jessie> branch (or whatever) is a normal git branch.
-You can use C<git push> to any suitable git server.
+You can use C<git push> to publish it on any suitable git server.
+Anyone who gets that git branch from you
+will be able to build binary packages
+just as you did.
If you want to contribute your changes back to Debian,
you should probably send them as attachments to
an email to the
L<Debian Bug System|https://bugs.debian.org/>
(either a followup to an existing bug, or a new bug).
-Patches in C<<git-format-patch> format are usually very welcome.
+Patches in C<git-format-patch> format are usually very welcome.
-Anyone who gets that git branch from you
-will be able to build binary packages
-just as you did.
+=head2 Source packages
-git branch is not sufficient to build a I<source package>.
+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 you need to provide a source package,
-you will probably want to read one of the other tutorials,
-such as L<dgit-nmu-simple(7)>, L<dgit-sponsorship(7)> or
-multi-arch clash problem
+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 C<1.0> "native"
+source package, which is just a tarball
+with accompanying .dsc metadata file:
+ % git rm debian/source/version
+ % git commit -m 'switch to 1.0 source format'
+ % dgit -wgf --dpkg-buildpackage:-sn build-source
-=head1 SEE ALSO
+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
+=head1 SEE ALSO
-This tutorial was written and is maintained by Sean Whitton <email@example.com>. It contains contributions from other dgit contributors too - see the dgit copyright file.