=over 4
- % dgit clone glibc jessie
+ % dgit clone glibc jessie,-security
% cd glibc
- % wget 'https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=28250;mbox=yes;msg=89' | patch -p1 -u
+ % 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 glibc
=over 4
% cd glibc
- % dgit pull jessie
+ % dgit pull jessie,-security
% gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
% dpkg-buildpackage -uc -b
% sudo dpkg -i ../libc6_*.deb
=over 4
- % dgit clone glibc jessie
+ % dgit clone glibc jessie,-security
% cd glibc
=back
=back
+For Debian, you should add C<,-security>
+to the end of the suite name,
+unless you're on unstable or testing.
+Hence, in our example
+C<jessie> becomes C<jessie,-security>.
+(Yes, with a comma.)
+
=head1 WHAT DGIT CLONE PRODUCES
=head2 What branches are there
dgit clone will give you a new working tree,
-and arrange for you to be on a branch like
-C<dgit/jessie>.
+and arrange for you to be on a branch named like
+C<dgit/jessie,-security> (yes, with a comma in the branch name).
-There is a tracking branch for the contents of the archive, called
+For each release (like C<jessie>)
+there is a tracking branch for the contents of the archive, called
C<remotes/dgit/dgit/jessie>
(and similarly for other suites). This can be updated with
C<dgit fetch jessie>.
is synthesized by your local copy of dgit.
It is fast forwarding.
+Debian separates out the security updates, into C<*-security>.
+Telling dgit C<jessie,-security> means that it should include
+any updates available in C<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 C<debian/changelog>
you'll have to supply a C<-p>I<package> option to dgit fetch.)
(For Debian afficionados:
the git trees that come out of dgit are
-"patches-applied packaging branches".)
+"patches-applied packaging branches
+without a .pc directory".)
=head2 What kind of history you get
But for many packages the real git history
does not exist,
or has not been published in a dgitish form.
-So yuu may find that the history is a rather short
+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
+C<jessie,-security>.
If the package maintainer is using git then
after dgit clone
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>.
+or leave outputs and temporary files not covered by C<.gitignore>.
-Kf you always commit,
+If you always commit,
you can use
=over 4
C<-b> means build all binary packages,
but not to build a source package.
+=head2 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.)
+
+=over 4
+
+ % git clean -xdf
+ % sbuild -c jessie -A --no-clean-source \
+ --dpkg-source-opts='-Zgzip -z1 --format=1.0 -sn'
+
+=back
+
+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.
+
=head1 INSTALLING
+=head2 Debian Jessie or older
+
=over 4
% sudo dpkg -i ../libc6_*.deb
you will get an error, which can usually be fixed with
C<apt-get -f install>.
+=head2 Debian Stretch or newer
+
+=over 4
+
+ % sudo apt install ../libc6_*.deb
+
+=back
+
=head1 Multiarch
If you're working on a library package and your system has multiple
is to build the package for all the architectures you
have enabled.
You'll need a chroot for each of the secondary architectures.
-This iw somewhat tiresome,
+This is somewhat tiresome,
even though Debian has excellent tools for managing chroots.
C<sbuild-createchroot> from the sbuild package is a
good starting point.
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,)
+(The version 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.
+and because it will mislead and confuse apt.
With the "same number" approach you may still get errors like
=head1 SHARING YOUR WORK
-The C<dgit/jessie> branch (or whatever) is a normal git branch.
+The C<dgit/jessie,-security> branch (or whatever) is a normal git branch.
You can use C<git push> to publish it on any suitable git server.
Anyone who gets that git branch from you
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"
+you can use this recipe to generate a C<3.0 (native)>
source package, which is just a tarball
with accompanying .dsc metadata file:
=over 4
- % git rm debian/source/version
- % git commit -m 'switch to 1.0 source format'
- % dgit -wgf --dpkg-buildpackage:-sn build-source
+ % echo '3.0 (native)' >debian/source/format
+ % git commit -m 'switch to native source format' debian/source/format
+ % dgit -wgf build-source
=back