dgit−nmu−simple − tutorial for DDs wanting to NMU with git

This tutorial describes how a Debian Developer can do a
straightforward NMU of a package in Debian, using dgit.

     This document won’t help you decide whether an NMU is a
good idea or whether it be well received.  The Debian
Developers’ Reference has some (sometimes questionable)
guidance on this.

     Conversely, you do not need to know anything about the
usual maintainer’s git workflow.  If appropriate, you can
work on many different packages, making similar changes,
without worrying about the individual maintainers’ git

     This tutorial only covers changes which can sensibly be
expressed as a reasonably small number of linear commits
(whether to Debian packaging or to upstream files or both).

     If you want to do a new upstream version, you probably
want to do as the maintainer would have done.  You’ll need
to find out what the maintainer’s git practices are and
consult the appropriate "dgit−maint−*(7)" workflow tutorial,

    % dgit clone glibc jessie
    % cd glibc
    % git am ~/glibc−security−fix.diff
    % dch −−nmu "Apply upstream's fix for foo bug."
    % git add debian/changelog && git commit −m"NMU changelog entry"
    % dpkg−buildpackage −uc −b
    [ run your tests ]
    % dch −r && git add debian/changelog && git commit −m"Finalise NMU"
    % dgit −wgf sbuild −A −c jessie
    [ final tests on generated .debs ]
    % dgit −wgf [−−delayed=5] push jessie
    [ enter your gnupg passphrase as prompted ]
    [ see that push and upload are successful ]
    [ prepare and email NMU diff (git−diff, git−format−patch) ]

When preparing an NMU, the git commits you make on the dgit
branch should be simple linear series of commits with good
commit messages.  The commit messages will be published in
various ways, including perhaps being used as the cover
messages for generated quilt patches.

     Do not make merge commits.  Do not try to rebase to
drop patches − if you need to revert a change which is
actually a Debian patch, use git‐revert.

     If you need to modify a Debian patch, make a new commit
which fixes what needs fixing, and explain in the commit
message which patch it should be squashed with (perhaps by


use of a commit message in "git rebase −−autosquash −i"

     (Of course if you have specific instructions from the
maintainer, you can follow those instead.  But the procedure
in this tutorial is legitimate for any maintainer, in the
sense that it should generate an upload to which the
maintainer cannot reasonably object.)

dgit clone will put you on a branch like "dgit/sid".  There
is a pseudo‐remote called "dgit" which also contains a
branch like "dgit/sid", so you do things like "git diff
dgit/dgit/sid" to see what changes you have made.

Don’t forget to "git add" any new files you create.
Otherwise git clean (which is requested with the "−wgf"
option in the recipe above) will delete them.

     Many package builds leave dirty git trees.  So, commit
before building.  That way you can use "git reset −−hard".

     If you follow this approach you don’t need to care
about the build dirtying the tree.  It also means you don’t
care about the package clean target, which is just as well
because many package clean targets are broken.

The dgit git history (visible in gitk and git log) is not
necessarily related to the maintainer’s or upstream’s git
history (if any).

     If the maintainer has advertised a git repo with Vcs‐
Git dgit will set up a remote for it, so you can do

    % git fetch vcs−git

     You can cherry pick changes from there, for example.
Note that the maintainer’s git history may not be suitable
for use with dgit.  For example, it might be a patches‐
unapplied branch or even contain only a debian/ directory.

You can use dgit’s −−delayed option to upload to the DELAYED
queue.  However, you should read the warning about this
option in dgit(1).

dgit(1), dgit(7), dgit−maint−*(7)