NAME

       dgit - tutorial for package maintainers of Debian-native packages

INTRODUCTION

       This document describes elements of a workflow for using dgit to maintain a Debian package
       that uses one of the native source formats ("1.0" & "3.0 (native)").

       •   We expect that your git history is fast-forwarding.

       •   You should be prepared to tolerate a small amount of ugliness in your git history in
           the form of merges which stitch the dgit-generated archive view into your maintainer
           history.

           This is to handle uploads that were not made with dgit, such as the uploads you made
           before switching to this workflow, or NMUs.

   Benefits
       •   Benefit from dgit's safety catches.  In particular, ensure that your upload always
           matches exactly your git HEAD.

       •   Provide a better, more detailed history to downstream dgit users.

       •   Incorporate an NMU with one command.

FIRST PUSH WITH DGIT

       You do not need to do anything special to your tree to push with dgit.

       Simply prepare your git tree in the usual way, and then:

           % dgit -wgf sbuild -A -c sid
           % dgit -wgf --overwrite push

       (Do not make any tags yourself: dgit push will do that.)

       You may use dgit pbuilder or dgit cowbuilder instead of dgit sbuild; see dgit(1) for the
       syntax of those subcommands.

       The --overwrite option tells dgit that you are expecting that your git history is not a
       descendant of the history which dgit synthesised from the previous non-dgit uploads.

       dgit will make a merge commit on your branch but without making any code changes (ie, a
       pseudo-merge) so that your history, which will be pushed to the dgit git server, is fast
       forward from the dgit archive view.

       Alternatively, if this was the first ever dgit push of the package, you can avoid this
       merge commit by passing "--deliberately-not-fast-forward" instead of "--overwrite".  This
       avoids introducing a new origin commit into your git history.

SUBSEQUENT PUSHES

           % dgit -wgf push

       That's it.

INCORPORATING AN NMU

           % dgit pull

       That's it.

       Or, if you would prefer to review the changes, you can do this:

           % dgit fetch
           % dgit diff HEAD..dgit/dgit/sid

       If you do not merge the NMU into your own git history, the next push will then require
       --overwrite.

SEE ALSO

       dgit(1), dgit(7)