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