NAME

       dgit - tutorial for package maintainers already using git-buildpackage(1)

INTRODUCTION

       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.

GIT CONFIGURATION

       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.

BUILDING

       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.

UPLOADING

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

INCORPORATING NMUS

       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.

SEE ALSO

       dgit(1), dgit(7)

AUTHOR

       This tutorial was written and is maintained by Sean Whitton <spwhitton@spwhitton.name>.