dgit - tutorial for package maintainers already using
git-buildpackage(1)
This document explains how
dgit can be incorporated into a
git-buildpackage(1) package-maintenance workflow. This should be read
jointly with
git-buildpackage(1)'s documentation. Some reasons why you
might want to incorporate
dgit into your existing workflow:
- •
- Benefit from dgit's safety catches. In particular, ensure
that your upload always matches exactly your git HEAD.
- •
- Provide a better, more detailed git history to downstream
dgit users, such as people using dgit to do an NMU (see
dgit-nmu-simple(7) and dgit-user(7)).
Note that we assume a patches-unapplied repository: the upstream source
committed to the git repository is unpatched.
git-buildpackage(1) can
work with patched-applied repositories, but is normally used with
patches-unapplied.
If you have configured an
export-dir in your gbp.conf, you should tell
dgit about it:
% git config --global dgit.default.build-products-dir /home/spwhitton/build-area
If you run
% git config dgit.default.quilt-mode gbp
in your repository, you can omit
--gbp wherever it occurs below.
Note that this does require that you always work from your gbp master branch,
never the dgit patches-applied branch.
You can perform test builds like this:
% dgit [--include-dirty] gbp-build [OPTIONS]
where
--include-dirty is needed for testing uncommitted changes, and
OPTIONS are any further options to be passed on to
gbp-buildpackage(1).
If you are doing a source-only upload, you do not need to prepare a
_source.changes, as
dgit push-source will take of that on your
behalf.
If you need to include binaries with your upload, you will probably want to use
sbuild(1),
pbuilder(1) or
cowbuilder(1):
% dgit --rm-old-changes --gbp sbuild
replacing 'sbuild' with 'pbuilder' or 'cowbuilder' if appropriate.
We use
--rm-old-changes to ensure that there is exactly one changes file
corresponding to this package, so we can be confident we're uploading what we
intend (though
dgit push will do some safety checks).
Note that none of the commands in this section are required to upload with dgit.
You can invoke
gbp-buildpackage(1),
pbuilder(1),
cowbuilder(1) and
sbuild(1) directly. However, the defaults for
these tools may leave you with something that dgit will refuse to upload
because it doesn't match your git HEAD.
As a general rule, leave all signing and tagging to dgit.
Don't use
--git-tag:
dgit push will do this for you. To do a
source-only upload:
% dgit --gbp push-source
or if you need to include binaries,
% dgit --gbp push
This will push your git history to the dgit-repos, but you probably want to
follow it up with a push to salsa.
You will need to pass
--overwrite if the previous upload was not
performed with dgit.
If this is first ever dgit push of the package, consider passing
--deliberately-not-fast-forward instead of
--overwrite. This
avoids introducing a new origin commit into the dgit view of your git history.
(This origin commit would represent the most recent non-dgit upload of the
package, but this should already be represented in your git history.)
Alternatively, you can use
git-debpush(1). For the first upload you
should pass the
--gbp quilt mode option (see
git-debpush(1)).
dgit pull can't yet incorporate NMUs into patches-unapplied gbp branches.
You can just apply the NMU diff the traditional way. The next upload will
require
--overwrite.
dgit(1),
dgit(7)
This tutorial was written and is maintained by Sean Whitton
<
[email protected]>.