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