dgit-maint-gbp.7.pod

   1 =head1 NAME
   2
   3 dgit - tutorial for package maintainers already using git-buildpackage(1)
   4
   5 =head1 INTRODUCTION
   6
   7 This document explains how B<dgit> can be incorporated into a
   8 git-buildpackage(1) package-maintenance workflow.  This should be read
   9 jointly with git-buildpackage(1)'s documentation.  Some reasons why
  10 you might want to incorporate B<dgit> into your existing workflow:
  11
  12 =over 4
  13
  14 =item
  15
  16 Benefit from dgit's safety catches.  In particular, ensure that your
  17 upload always matches exactly your git HEAD.
  18
  19 =item
  20
  21 Provide a better, more detailed git history to downstream dgit users,
  22 such as people using dgit to do an NMU (see dgit-nmu-simple(7) and
  23 dgit-user(7)).
  24
  25 =item
  26
  27 Incorporate NMUs with a single command (see below).
  28
  29 =back
  30
  31 Note that we assume a patches-unapplied repository: the upstream
  32 source committed to the git repository is unpatched.
  33 git-buildpackage(1) can work with patched-applied repositories, but is
  34 normally used with patches-unapplied.
  35
  36 =head1 GIT CONFIGURATION
  37
  38 If you run
  39
  40 =over 4
  41
  42     % git config dgit.default.quilt-mode gbp
  43
  44 =back
  45
  46 in your repository, you can omit I<--gbp> wherever it occurs below.
  47
  48 Note that this does require that you always work from your gbp master
  49 branch, never the dgit patches-applied branch.
  50
  51 =head1 BUILDING
  52
  53 If you use gbp-buildpackage(1) to generate your orig tarballs, you
  54 will need to perform the first build with gbp-buildpackage(1) directly
  55 (this is due to Debian bug #841084).
  56
  57 Otherwise, you can perform builds like this:
  58
  59 =over 4
  60
  61     % dgit [--allow-dirty] gbp-build [OPTIONS]
  62
  63 =back
  64
  65 where I<--allow-dirty> is needed for testing uncommitted changes, and
  66 I<OPTIONS> are any further options to be passed on to
  67 gbp-buildpackage(1).
  68
  69 When you are ready to build for upload, you will probably want to use
  70 sbuild(1) or pbuilder(1), or do a source-only upload.  Either
  71
  72 =over 4
  73
  74     % dgit --rm-old-changes --gbp sbuild
  75
  76 =back
  77
  78 or
  79
  80 =over 4
  81
  82     % dgit --rm-old-changes gbp-build --git-pbuilder
  83
  84 =back
  85
  86 or
  87
  88 =over 4
  89
  90     % dgit --rm-old-changes --gbp build-source
  91
  92 =back
  93
  94 We use I<--rm-old-changes> to ensure that there is exactly one changes
  95 file corresponding to this package, so we can be confident we're
  96 uploading what we intend (though B<dgit push> will do some safety
  97 checks).
  98
  99 Note that all of the commands in this section are not required to
 100 upload with dgit.  You can invoke gbp-buildpackage(1), pbuilder(1) and
 101 sbuild(1) directly.  However, the defaults for these tools may leave
 102 you with something that dgit will refuse to upload because it doesn't
 103 match your git HEAD.  As a general rule, leave all signing and tagging
 104 to dgit.
 105
 106 =head1 UPLOADING
 107
 108 Don't use I<--git-tag>: B<dgit push> will do this for you.  To upload:
 109
 110 =over 4
 111
 112     % dgit --gbp push
 113
 114 =back
 115
 116 This will push your git history to the dgit-repos, but you probably
 117 want to follow it up with a push to alioth.
 118
 119 You will need to pass I<--overwrite> if the previous upload was not
 120 performed with dgit.
 121
 122 =head1 INCORPORATING NMUS
 123
 124 B<dgit pull> can't yet incorporate NMUs into patches-unapplied gbp
 125 branches.  You can just apply the NMU diff the traditional way.  The
 126 next upload will require I<--overwrite>.
 127
 128 =head1 SEE ALSO
 129
 130 dgit(1), dgit(7)
 131
 132 =head1 AUTHOR
 133
 134 This tutorial was written and is maintained by Sean Whitton <spwhitton@spwhitton.name>.