bionic (7) dgit-maint-gbp.7.gz

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 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 builds like this:

           % dgit [--allow-dirty] gbp-build [OPTIONS]

       where --allow-dirty is needed for testing uncommitted changes, and OPTIONS are any further options to be
       passed on to gbp-buildpackage(1).

       When you are ready to build for upload, you will probably want to use sbuild(1) or pbuilder(1), or do a
       source-only upload.  Either

           % dgit --rm-old-changes --gbp sbuild

       or

           % dgit --rm-old-changes gbp-build --git-pbuilder

       or

           % dgit --rm-old-changes --gbp build-source

       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 all of the commands in this section are not required to upload with dgit.  You can invoke
       gbp-buildpackage(1), pbuilder(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 upload:

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

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