dgit-maint-gbp






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









                             ‐2‐


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

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
<spwhitton@spwhitton.name>.