.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "dgit-nmu-simple 7"
.TH dgit-nmu-simple 7 "Debian Project" "perl v5.28.1" "dgit"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
dgit\-nmu\-simple \- tutorial for DDs wanting to NMU with git
.SH "INTRODUCTION AND SCOPE"
.IX Header "INTRODUCTION AND SCOPE"
This tutorial describes how a Debian Developer can do
a straightforward \s-1NMU\s0
of a package in Debian, using dgit.
.PP
This document won't help you decide whether
an \s-1NMU\s0 is a good idea or
whether it be well received.
The Debian Developers' Reference has some
(sometimes questionable) guidance on this.
.PP
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 practices.
.PP
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).
.PP
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 \f(CW\*(C`dgit\-maint\-*(7)\*(C'\fR workflow tutorial,
.SH "SUMMARY"
.IX Header "SUMMARY"
.Vb 10
\&    % dgit clone glibc jessie
\&    % cd glibc
\&    % git am ~/glibc\-security\-fix.diff
\&    % dch \-\-nmu "Apply upstream\*(Aqs 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) ]
.Ve
.SH "WHAT KIND OF CHANGES AND COMMITS TO MAKE"
.IX Header "WHAT KIND OF CHANGES AND COMMITS TO MAKE"
When preparing an \s-1NMU,\s0 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.
.PP
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.
.PP
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 \f(CW\*(C`git rebase \-\-autosquash \-i\*(C'\fR
format).
.PP
(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.)
.SH "RELEVANT BRANCHES"
.IX Header "RELEVANT BRANCHES"
dgit clone will put you on a branch like \f(CW\*(C`dgit/sid\*(C'\fR.
There is a pseudo-remote called \f(CW\*(C`dgit\*(C'\fR which also contains a branch
like \f(CW\*(C`dgit/sid\*(C'\fR, so you do things like
\&\f(CW\*(C`git diff dgit/dgit/sid\*(C'\fR
to see what changes you have made.
.SH "KEEPING YOUR WORKING TREE TIDY"
.IX Header "KEEPING YOUR WORKING TREE TIDY"
Don't forget to \f(CW\*(C`git add\*(C'\fR any new files you create.
Otherwise git clean
(which is requested with the \f(CW\*(C`\-wgf\*(C'\fR option in the recipe above)
will delete them.
.PP
Many package builds leave dirty git trees.
So, commit before building.
That way you can use \f(CW\*(C`git reset \-\-hard\*(C'\fR.
.PP
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.
.SH "OTHER GIT BRANCHES"
.IX Header "OTHER GIT BRANCHES"
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).
.PP
If the maintainer has advertised a git repo with
Vcs-Git
dgit will set up a remote for it,
so you can do
.Sp
.Vb 1
\&    % git fetch vcs\-git
.Ve
.PP
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.
.SH "UPLOADING TO DELAYED"
.IX Header "UPLOADING TO DELAYED"
You can use dgit's \fI\-\-delayed\fR option
to upload to the \s-1DELAYED\s0 queue.
However, you should read the warning about this option in \fBdgit\fR\|(1).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBdgit\fR\|(1), \fBdgit\fR\|(7), dgit\-maint\-*(7)