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 =head1 GIT CONFIGURATION
  32
  33 If you run
  34
  35 =over 4
  36
  37     % git config dgit.default.quilt-mode gbp
  38
  39 =back
  40
  41 in your repository, you can omit I<--gbp> wherever it occurs below.
  42
  43 Note that this does require that you always work from your gbp master
  44 branch, never the dgit patches-applied branch.
  45
  46 =head1 BUILDING
  47
  48 If you use gbp-buildpackage(1) to generate your orig tarballs, you
  49 will need to perform the first build with gbp-buildpackage(1) directly
  50 (this is due to Debian bug #841084).
  51
  52 Otherwise, you can perform builds like this:
  53
  54 =over 4
  55
  56     % dgit [--allow-dirty] gbp-build [OPTIONS]
  57
  58 =back
  59
  60 where I<--allow-dirty> is needed for testing uncommitted changes, and
  61 I<OPTIONS> are any further options to be passed on to
  62 gbp-buildpackage(1).
  63
  64 When you are ready to build for upload, you will probably want to use
  65 sbuild(1) or pbuilder(1), or do a source-only upload.  Either
  66
  67 =over 4
  68
  69     % dgit --rm-old-changes --gbp sbuild
  70
  71 =back
  72
  73 or
  74
  75 =over 4
  76
  77     % dgit --rm-old-changes gbp-build --git-pbuilder
  78
  79 =back
  80
  81 or
  82
  83 =over 4
  84
  85     % dgit --rm-old-changes --gbp build-source
  86
  87 =back
  88
  89 We use I<--rm-old-changes> to ensure that there is exactly one changes
  90 file corresponding to this package, so we can be confident we're
  91 uploading what we intend (though B<dgit push> will do some safety
  92 checks).
  93
  94 Note that all of the commands in this section are not required to
  95 upload with dgit.  You can invoke gbp-buildpackage(1), pbuilder(1) and
  96 sbuild(1) directly.  However, the defaults for these tools may leave
  97 you with something that dgit will refuse to upload because it doesn't
  98 match your git HEAD.  As a general rule, leave all signing and tagging
  99 to dgit.
 100
 101 =head1 UPLOADING
 102
 103 Don't use I<--git-tag>: B<dgit push> will do this for you.  To upload:
 104
 105 =over 4
 106
 107     % dgit --gbp push
 108
 109 =back
 110
 111 This will push your git history to the dgit-repos, but you probably
 112 want to follow it up with a push to alioth.
 113
 114 You will need to pass I<--overwrite> if the previous upload was not
 115 performed with dgit.
 116
 117 =head1 INCORPORATING NMUS
 118
 119 =over 4
 120
 121     % dgit --gbp pull
 122
 123 =back
 124
 125 Alternatively, you can apply the NMU diff to your repository.  The
 126 next push will then 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>.