dgit-maint-native.7.pod

   1 =head1 NAME
   2
   3 dgit - tutorial for package maintainers of Debian-native packages
   4
   5 =head1 INTRODUCTION
   6
   7 This document describes elements of a workflow for using B<dgit> to
   8 maintain a Debian package that uses one of the native source formats
   9 ("1.0" & "3.0 (native)").
  10
  11 =over 4
  12
  13 =item
  14
  15 We expect that your git history is fast-forwarding.
  16
  17 =item
  18
  19 You should be prepared to tolerate a small amount of
  20 ugliness in your git history
  21 in the form of merges which stitch
  22 the dgit-generated archive view
  23 into your maintainer history.
  24
  25 This is to handle uploads that were not made with dgit,
  26 such as the uploads you made before switching to this workflow,
  27 or NMUs.
  28
  29 =back
  30
  31 =head2 Benefits
  32
  33 =over 4
  34
  35 =item
  36
  37 Benefit from dgit's safety catches.  In particular, ensure that your
  38 upload always matches exactly your git HEAD.
  39
  40 =item
  41
  42 Provide a better,
  43 more detailed history
  44 to downstream dgit users.
  45
  46 =item
  47
  48 Incorporate an NMU with one command.
  49
  50 =back
  51
  52 =head1 FIRST PUSH WITH DGIT
  53
  54 You do not need to do anything special to your tree
  55 to push with dgit.
  56
  57 Simply prepare your git tree in the usual way, and then:
  58
  59 =over 4
  60
  61     % dgit -wgf sbuild -A -c sid
  62     % dgit -wgf --overwrite push
  63
  64 =back
  65
  66 (Do not make any tags yourself: dgit push will do that.)
  67
  68 You may use B<dgit pbuilder> or B<dgit cowbuilder>
  69 instead of B<dgit sbuild>;
  70 see dgit(1) for the syntax of those subcommands.
  71
  72 The --overwrite option tells dgit that you are expecting
  73 that your git history is not a descendant of the
  74 history which dgit synthesised from the previous
  75 non-dgit uploads.
  76
  77 dgit will make a merge commit
  78 on your branch
  79 but without making any code changes
  80 (ie, a pseudo-merge)
  81 so that your history,
  82 which will be pushed to the dgit git server,
  83 is fast forward from the dgit archive view.
  84
  85 Alternatively,
  86 if this was the first ever dgit push of the package,
  87 you can avoid this merge commit by
  88 passing C<--deliberately-not-fast-forward>.
  89 instead of C<--overwrite>.
  90 This avoids introducing a new origin commit into
  91 your git history.
  92
  93 =head1 SUBSEQUENT PUSHES
  94
  95 =over 4
  96
  97     % dgit -wgf push
  98
  99 =back
 100
 101 That's it.
 102
 103 =head1 INCORPORATING AN NMU
 104
 105 =over 4
 106
 107     % dgit pull
 108
 109 =back
 110
 111 That's it.
 112
 113 Or, if you would prefer to review the changes,
 114 you can do this:
 115
 116 =over 4
 117
 118     % dgit fetch
 119     % dgit diff HEAD..dgit/dgit/sid
 120
 121 =back
 122
 123 If you do not merge the NMU into your own git history,
 124 the next push will then require I<--overwrite>.
 125
 126 =head1 SEE ALSO
 127
 128 dgit(1), dgit(7)