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 =back
  26
  27 Note that we assume a patches-unapplied repository: the upstream
  28 source committed to the git repository is unpatched.
  29 git-buildpackage(1) can work with patched-applied repositories, but is
  30 normally used with patches-unapplied.
  31
  32 =head1 GIT CONFIGURATION
  33
  34 If you have configured an I<export-dir> in your gbp.conf, you should
  35 tell dgit about it:
  36
  37 =over 4
  38
  39     % git config --global dgit.default.build-products-dir /home/spwhitton/build-area
  40
  41 =back
  42
  43 If you run
  44
  45 =over 4
  46
  47     % git config dgit.default.quilt-mode gbp
  48
  49 =back
  50
  51 in your repository, you can omit I<--gbp> wherever it occurs below.
  52
  53 Note that this does require that you always work from your gbp master
  54 branch, never the dgit patches-applied branch.
  55
  56 =head1 BUILDING
  57
  58 You can perform test builds like this:
  59
  60 =over 4
  61
  62     % dgit [--include-dirty] gbp-build [OPTIONS]
  63
  64 =back
  65
  66 where I<--include-dirty> is needed for testing uncommitted changes, and
  67 I<OPTIONS> are any further options to be passed on to
  68 gbp-buildpackage(1).
  69
  70 If you are doing a source-only upload, you do not need to prepare a
  71 I<_source.changes>, as B<dgit push-source> will take of that on your
  72 behalf.
  73
  74 If you need to include binaries with your upload, you will probably
  75 want to use sbuild(1), pbuilder(1) or cowbuilder(1):
  76
  77 =over 4
  78
  79     % dgit --rm-old-changes --gbp sbuild
  80
  81 =back
  82
  83 replacing 'sbuild' with 'pbuilder' or 'cowbuilder' if appropriate.
  84
  85 We use I<--rm-old-changes> to ensure that there is exactly one changes
  86 file corresponding to this package, so we can be confident we're
  87 uploading what we intend (though B<dgit push> will do some safety
  88 checks).
  89
  90 Note that none of the commands in this section are required to upload
  91 with dgit.  You can invoke gbp-buildpackage(1), pbuilder(1),
  92 cowbuilder(1) and sbuild(1) directly.  However, the defaults for these
  93 tools may leave you with something that dgit will refuse to upload
  94 because it doesn't match your git HEAD.
  95
  96 As a general rule, leave all signing and tagging to dgit.
  97
  98 =head1 UPLOADING
  99
 100 Don't use I<--git-tag>: B<dgit push> will do this for you.  To do a
 101 source-only upload:
 102
 103 =over 4
 104
 105     % dgit --gbp push-source
 106
 107 =back
 108
 109 or if you need to include binaries,
 110
 111 =over 4
 112
 113     % dgit --gbp push
 114
 115 =back
 116
 117 This will push your git history to the dgit-repos, but you probably
 118 want to follow it up with a push to salsa.
 119
 120 You will need to pass I<--overwrite> if the previous upload was not
 121 performed with dgit.
 122
 123 If this is first ever dgit push of the package, consider passing
 124 I<--deliberately-not-fast-forward> instead of I<--overwrite>.  This
 125 avoids introducing a new origin commit into the dgit view of your git
 126 history.  (This origin commit would represent the most recent non-dgit
 127 upload of the package, but this should already be represented in your
 128 git history.)
 129
 130 =head1 INCORPORATING NMUS
 131
 132 B<dgit pull> can't yet incorporate NMUs into patches-unapplied gbp
 133 branches.  You can just apply the NMU diff the traditional way.  The
 134 next upload will require I<--overwrite>.
 135
 136 =head1 SEE ALSO
 137
 138 dgit(1), dgit(7)
 139
 140 =head1 AUTHOR
 141
 142 This tutorial was written and is maintained by Sean Whitton <spwhitton@spwhitton.name>.