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