git-debrebase.1.pod

   1 =head1 NAME
   2
   3 git-debrebase - delta queue rebase tool for Debian packaging
   4
   5 =head1 INTRODUCTION
   6
   7 git-debrebase is a tool for representing in git,
   8 and manpulating,
   9 Debian packages based on upstream source code.
  10
  11 This is the command line reference.
  12 Please read the tutorial
  13 L<dgit-maint-debrebase(5)>.
  14
  15 For background, theory of operation,
  16 and definitions of the terms used here,
  17 see L<git-debrebase(5)>.
  18
  19 =head1 PRINCIPAL OPERATIONS
  20
  21 =over
  22
  23 =item git-debrebase [-- <git-rebase options...>]
  24
  25 Unstitches and launders the branch.
  26 (See L</UNSTITCHING AND LAUNDERING> below.)
  27
  28 Then optionally edits the Debian delta queue,
  29 using git-rebase, by running
  30
  31     git rebase <git-rebase options> <breakwater-tip>
  32
  33 Do not pass a base branch argument:
  34 git-debrebase will supply that.
  35 Do not use --onto, or --fork-point.
  36 Useful git-rebase options include -i and --autosquash.
  37
  38 If git-rebase stops for any reason,
  39 you may git-rebase --abort, --continue, or --skip, as usual.
  40 If you abort the git-rebase,
  41 the branch will still have been laundered,
  42 but everything in the rebase will be undone.
  43
  44 =item git-debrebase stitch [--prose=<for commit message>]
  45
  46 Stitch the branch,
  47 consuming ffq-prev.
  48
  49 If there is no ffq-prev, it is an error, unless --noop-ok.
  50
  51 =item git-debrebase new-upstream-v0 <new-version> [<upstream-details>...]
  52
  53 Rebases the delta queue
  54 onto a new upstream version.  In detail:
  55
  56 Firstly, checks that the proposed rebase seems to make sense:
  57 It is a problem unless the new upstream(s)
  58 are fast forward from the previous upstream(s)
  59 as found in the current breakwater anchor.
  60 And, in the case of a multi-piece upstream,
  61 if the pieces are not in the same order, with the same names.
  62
  63 If all seems well, unstitches and launders the branch.
  64
  65 Then,
  66 generates
  67 (in a private working area)
  68 a new anchor merge commit,
  69 on top of the breakwater tip,
  70 and on top of that a commit to
  71 update the version number in debian/changelog.
  72
  73 Finally,
  74 starts a git-rebase
  75 of the delta queue onto these new commits.
  76
  77 That git-rebase may complete successfully,
  78 or it may require your assistance,
  79 just like a normal git-rebase.
  80
  81 If you git-rebase --abort,
  82 the whole new upstream operation is aborted,
  83 but the laundering will still have been done.
  84
  85 The <upstream-details> are, optionally, in order:
  86
  87 =over
  88
  89 =item <upstream-commitish>
  90
  91 The new upstream branch (or commitish).
  92 Default is C<upstream>.
  93
  94 It is a problem if the upstream contains a debian/ directory;
  95 if forced to proceed,
  96 git-debrebase will disregard the upstream's debian/ and
  97 take (only) the packaging from the current breakwater.
  98
  99 =item <piece-name> <piece-upstream-commitish>
 100
 101 Specifies that this is a multi-piece upstream.
 102 (A multi-component upstream, in dpkg-source terminology.)
 103 May be repeated.
 104
 105 When such a pair is specified,
 106 git-debrebase will first combine the pieces of the upstream
 107 together,
 108 and then use the result as the combined new upstream.
 109
 110 For each <piece-name>,
 111 the tree of the <piece-upstream-commitish>
 112 becomes the subdirectory <piece-name>
 113 in the combined new upstream
 114 (supplanting any subdirectory that might be there in
 115 the main upstream branch).
 116
 117 <piece-name> has a restricted syntax:
 118 it may contain only ASCII alphanumerics and hyphens.
 119
 120 The combined upstream is itself recorded as a commit,
 121 with each of the upstream pieces' commits as parents.
 122 The combined commit contains an annotation
 123 to allow a future git-debrebase new upstream operation
 124 to make the coherency checks described above.
 125
 126 =item <git-rebase options>
 127
 128 These will be passed to git rebase.
 129
 130 If the upstream rebase is troublesome, -i may be helpful.
 131 As with plain git-debrebase,
 132 do not specify a base, or --onto, or --fork-point.
 133
 134 =back
 135
 136 If you are planning to generate a .dsc,
 137 you will also need to have, or generate,
 138 actual orig tarball(s),
 139 which must be identical to the rev-spec(s)
 140 passed to git-debrebase.
 141 git-debrebase does not concern itself with source packages
 142 so neither helps with this, nor checks it.
 143 L<git-archive(1)>, L<dgit(1)> and L<gbp(1)> may be able to help.
 144
 145 =back
 146
 147 =head1 UNSTITCHING AND LAUNDERING
 148
 149 Several operations unstitch and launder the branch first.
 150 In detail this means:
 151
 152 =head2 Establish the current branch's ffq-prev
 153
 154 If it is not yet recorded, we
 155 check that the current branch is ahead of relevant
 156 remote tracking branches.
 157
 158 The remote tracking branches checked by default are
 159 obtained from the git config.
 160 In each case it is a problem if we are behind the checked remote,
 161 or if we have diverged from it.
 162 All the checks are local:
 163 git-debrebase does not fetch anything from anywhere.
 164
 165 We check the branch we would merge from
 166 (remote.<branch>.merge, remote.<branch>.remote)
 167 and the branch we would push to
 168 (remote.<branch>.pushRemote etc.).
 169 For local dgit suite branches
 170 we check the corresponding tracking remote.
 171 If we are on C<master>, we check remotes/dgit/dgit/sid.
 172 The resulting ref names to check are filtered through
 173 branch.<branch>.ffq-ffrefs,
 174 which is a semicolon-separated list of glob patterns,
 175 each optionally preceded by !; first match wins.
 176
 177 If these checks pass,
 178 or are forced,
 179 we then record the current tip as ffq-prev.
 180
 181 =head2 Examine the branch
 182
 183 Analyse the current HEAD's history to find the anchor
 184 in its breakwater,
 185 and the most recent breakwater tip.
 186
 187 =head2 Rewrite the commits into laundered form
 188
 189 Mixed debian+upstream commits are split into two commits each.
 190 Delta queue (upstream files) commits bubble to the top.
 191 Pseudomerges,
 192 and quilt patch additions,
 193 are dropped.
 194
 195 This rewrite will always succeed, by construction.
 196 The result is the laundered branch.
 197
 198 =head1 UNDERLYING AND SUPPLEMENTARY OPERATIONS
 199
 200 =over
 201
 202 =item git-debrebase breakwater
 203
 204 Prints the breakwater tip commitid.
 205 Fails if your HEAD branch is not laundered.
 206
 207 =back
 208
 209 =head1 SEE ALSO
 210
 211 git-debrebase(1),
 212 dgit-maint-rebase(7),
 213 dgit(1)