git-debrebase.1.pod

   1 =head1 NAME
   2
   3 git-debrebase - delta queue rebase tool for Debian packaging
   4
   5 =head1 SYNOPSYS
   6
   7  git-debrebase [<options...>] [-- <git-rebase options...>]
   8  git-debrebase [<options...>] <operation> [<operation options...>
   9
  10 =head1 INTRODUCTION
  11
  12 git-debrebase is a tool for representing in git,
  13 and manpulating,
  14 Debian packages based on upstream source code.
  15
  16 This is the command line reference.
  17 Please read the tutorial
  18 L<dgit-maint-debrebase(5)>.
  19 For background, theory of operation,
  20 and definitions of the terms used here,
  21 see L<git-debrebase(5)>.
  22
  23 =head1 PRINCIPAL OPERATIONS
  24
  25 =over
  26
  27 =item git-debrebase [-- <git-rebase options...>]
  28
  29 Unstitches and launders the branch.
  30 (See L</UNSTITCHING AND LAUNDERING> below.)
  31
  32 Then optionally edits the Debian delta queue,
  33 using git-rebase, by running
  34
  35     git rebase <git-rebase options> <breakwater-tip>
  36
  37 Do not pass a base branch argument:
  38 git-debrebase will supply that.
  39 Do not use --onto, or --fork-point.
  40 Useful git-rebase options include -i and --autosquash.
  41
  42 If git-rebase stops for any reason,
  43 you may git-rebase --abort, --continue, or --skip, as usual.
  44 If you abort the git-rebase,
  45 the branch will still have been laundered,
  46 but everything in the rebase will be undone.
  47
  48 =item git-debrebase stitch [--prose=<for commit message>]
  49
  50 Stitch the branch,
  51 consuming ffq-prev.
  52
  53 If there is no ffq-prev, it is an error, unless --noop-ok.
  54
  55 It is a problem if the branch is not laundered.
  56
  57 =item git-debrebase new-upstream-v0 <new-version> [<upstream-details>...]
  58
  59 Rebases the delta queue
  60 onto a new upstream version.  In detail:
  61
  62 Firstly, checks that the proposed rebase seems to make sense:
  63 It is a problem unless the new upstream(s)
  64 are fast forward from the previous upstream(s)
  65 as found in the current breakwater anchor.
  66 And, in the case of a multi-piece upstream
  67 (a multi-component upstream, in dpkg-source terminology),
  68 if the pieces are not in the same order, with the same names.
  69
  70 If all seems well, unstitches and launders the branch.
  71
  72 Then,
  73 generates
  74 (in a private working area)
  75 a new anchor merge commit,
  76 on top of the breakwater tip,
  77 and on top of that a commit to
  78 update the version number in debian/changelog.
  79
  80 Finally,
  81 starts a git-rebase
  82 of the delta queue onto these new commits.
  83
  84 That git-rebase may complete successfully,
  85 or it may require your assistance,
  86 just like a normal git-rebase.
  87
  88 If you git-rebase --abort,
  89 the whole new upstream operation is aborted,
  90 except for the laundering.
  91
  92 The <upstream-details> are, optionally, in order:
  93
  94 =over
  95
  96 =item <upstream-commit-ish>
  97
  98 The new upstream branch (or commit-ish).
  99 Default is C<upstream>.
 100
 101 It is a problem if the upstream contains a debian/ directory;
 102 if forced to proceed,
 103 git-debrebase will disregard the upstream's debian/ and
 104 take (only) the packaging from the current breakwater.
 105
 106 =item <piece-name> <piece-upstream-commit-ish>
 107
 108 Specifies that this is a multi-piece upstream.
 109 May be repeated.
 110
 111 When such a pair is specified,
 112 git-debrebase will first combine the pieces of the upstream
 113 together,
 114 and then use the result as the combined new upstream.
 115
 116 For each <piece-name>,
 117 the tree of the <piece-upstream-commit-ish>
 118 becomes the subdirectory <piece-name>
 119 in the combined new upstream
 120 (supplanting any subdirectory that might be there in
 121 the main upstream branch).
 122
 123 <piece-name> has a restricted syntax:
 124 it may contain only ASCII alphanumerics and hyphens.
 125
 126 The combined upstream is itself recorded as a commit,
 127 with each of the upstream pieces' commits as parents.
 128 The combined commit contains an annotation
 129 to allow a future git-debrebase new upstream operation
 130 to make the coherency checks described above.
 131
 132 =item <git-rebase options>
 133
 134 These will be passed to git rebase.
 135
 136 If the upstream rebase is troublesome, -i may be helpful.
 137 As with plain git-debrebase,
 138 do not specify a base, or --onto, or --fork-point.
 139
 140 =back
 141
 142 If you are planning to generate a .dsc,
 143 you will also need to have, or generate,
 144 actual orig tarball(s),
 145 which must be identical to the rev-spec(s)
 146 passed to git-debrebase.
 147 git-debrebase does not concern itself with source packages
 148 so neither helps with this, nor checks it.
 149 L<git-deborig(1)>,
 150 L<git-archive(1)>, L<dgit(1)> and
 151 L<gbp-import-orig(1)> may be able to help.
 152
 153 This subcommand has -v0 in its name because we are not yet sure
 154 that its command line syntax is optimal.
 155 We may want to introduce an incompatible replacement syntax
 156 under the name C<new-upstream>.
 157
 158 =item git-debrebase convert-from-gbp [<upstream-commit-ish>]
 159
 160 Cnnverts a gbp patches-unapplied branch
 161 (not a gbp pq patch queue branch)
 162 into a git-debrebase interchange branch.
 163
 164 This is done by generating a new anchor merge,
 165 converting the quilt patches as a delta queue,
 166 and dropping the patches from the tree.
 167
 168 The upstream commit-ish should correspond to
 169 the gbp upstream branch, if there is one.
 170 It is a problem if it is not an ancestor of HEAD,
 171 or if the history between the upstream and HEAD
 172 contains commits which make changes to upstream files.
 173
 174 It is also a problem if the specified upstream
 175 has a debian/ subdirectory.
 176 This check exists to detect certain likely user errors,
 177 but if this situation is true and expected,
 178 forcing it is fine.
 179
 180 The result is a well-formed git-debrebase interchange branch.
 181 The result is also fast-forward from the gbp branch.
 182
 183 Note that it is dangerous not to know whether you are
 184 dealing with a gbp patches-unappled branch containing quilt patches,
 185 or a git-debrebase interchange branch.
 186 At worst,
 187 using the wrong tool for the branch format might result in
 188 a dropped patch queue!
 189
 190 =back
 191
 192 =head1 UNDERLYING AND SUPPLEMENTARY OPERATIONS
 193
 194 =over
 195
 196 =item git-debrebase breakwater
 197
 198 Prints the breakwater tip commitid.
 199 If your HEAD branch is not fully laundered,
 200 prints the tip of the so-far-laundered breakwater.
 201
 202 =item git-debrebase anchor
 203
 204 Prints the breakwater anchor commitid.
 205
 206 =item git-debrebase analyse
 207
 208 Walks the history of the current branch,
 209 most recent commit first,
 210 back until the most recent anchor,
 211 printing the commit object id,
 212 and commit type and info
 213 (ie the semantics in the git-debrebase model)
 214 for each commit.
 215
 216 =item git-debrebase record-ffq-prev
 217
 218 Establishes the current branch's ffq-prev,
 219 as discussed in L</UNSTITCHING AND LAUNDERING>,
 220 but does not launder the branch or move HEAD.
 221
 222 It is an error if the ffq-prev could not be recorded.
 223 It is also an error if an ffq-prev has already been recorded,
 224 unless --noop-ok.
 225
 226 =item git-debrebase launder-v0
 227
 228 Launders the branch without recording anything in ffq-prev.
 229 Then prints some information about the current branch.
 230 Do not use this operation;
 231 it will be withdrawn soon.
 232
 233 =item git-debrebase convert-to-gbp
 234
 235 Converts a laundered branch into a
 236 gbp patches-unapplied branch containing quilt patches.
 237 The result is not fast forward from the interchange branch,
 238 and any ffq-prev is deleted.
 239
 240 This is provided mostly for the test suite
 241 and for unusual situations.
 242 It should only be used with a care and
 243 with a proper understanding of the underlying theory.
 244
 245 Be sure to not accidentally treat the result as
 246 a git-debrebase branch,
 247 or you will drop all the patches!
 248
 249 =back
 250
 251 =head1 OPTIONS
 252
 253 This section documents the general options
 254 to git-debrebase
 255 (ie, the ones which immediately follow
 256 git-debrebase
 257 or
 258 git debrebase
 259 on the command line).
 260 Individual operations may have their own options which are
 261 docuented under each operation.
 262
 263 =over
 264
 265 =item -f<problem-id>
 266
 267 Turns problems with id <problem-id> into warnings.
 268
 269 Some troublesome things which git-debrebase encounters
 270 are B<problem>s.
 271 (The specific instances are discussed
 272 in the text for the relvant operation.)
 273
 274 When a problem is detected,
 275 a message is printed to stderr containing the problem id
 276 (in the form C<-f<problem-idE<gt>>),
 277 along with some prose.
 278
 279 If problems are detected, git-debrebase does not continue,
 280 unless the relevant -f<problem-id> is specified,
 281 or --force is specified.
 282
 283 =item --force
 284
 285 Turns all problems into warnings.
 286 See the -f<problem-id> option.
 287
 288 Do not invoke git-debrebase --force in scripts and aliases;
 289 instead, specify the particular -f<problem-id> for expected problems.
 290
 291 =item --noop-ok
 292
 293 Suppresses the error in
 294 some situations where git-debrebase does nothing,
 295 because there is nothing to do.
 296
 297 The specific instances are discussed
 298 in the text for the relvant operation.
 299
 300 =item --anchor=<commit-ish>
 301
 302 Treats <commit-ish> as an anchor,
 303 regardless of what it's actually like.
 304
 305 (It is a problem for
 306 git-debrebase new-upstream operations
 307 if <commit-ish> is the previous anchor to be used,
 308 because treating an arbitrary commit as an anchor
 309 means forgoing upstream coherency checks.)
 310
 311 =item -D
 312
 313 Requests (more) debugging.  May be repeated.
 314
 315 =back
 316
 317 =head1 UNSTITCHING AND LAUNDERING
 318
 319 Several operations unstitch and launder the branch first.
 320 In detail this means:
 321
 322 =head2 Establish the current branch's ffq-prev
 323
 324 If ffq-prev is not yet recorded,
 325 git-debrebase checks that the current branch is ahead of relevant
 326 remote tracking branches.
 327 The relevant branches depend on
 328 the current branch (and its
 329 git configuration)
 330 and are as follows:
 331
 332 =over
 333
 334 =item
 335
 336 The branch that git would merge from
 337 (remote.<branch>.merge, remote.<branch>.remote);
 338
 339 =item
 340
 341 The branch git would push to, if different
 342 (remote.<branch>.pushRemote etc.);
 343
 344 =item
 345
 346 For local dgit suite branches,
 347 the corresponding tracking remote;
 348
 349 =item
 350
 351 If you are on C<master>,
 352 remotes/dgit/dgit/sid.
 353
 354 =back
 355
 356 The apparently relevant ref names to check are filtered through
 357 branch.<branch>.ffq-ffrefs,
 358 which is a semicolon-separated list of glob patterns,
 359 each optionally preceded by !; first match wins.
 360
 361 In each case it is a problem if
 362 the local HEAD is behind the checked remote,
 363 or if local HEAD has diverged from it.
 364 All the checks are done locally using the remote tracking refs:
 365 git-debrebase does not fetch anything from anywhere.
 366
 367 If these checks pass,
 368 or are forced,
 369 git-debrebse then records the current tip as ffq-prev.
 370
 371 =head2 Examine the branch
 372
 373 git-debrebase
 374 analyses the current HEAD's history to find the anchor
 375 in its breakwater,
 376 and the most recent breakwater tip.
 377
 378 =head2 Rewrite the commits into laundered form
 379
 380 Mixed debian+upstream commits are split into two commits each.
 381 Delta queue (upstream files) commits bubble to the top.
 382 Pseudomerges,
 383 and quilt patch additions,
 384 are dropped.
 385
 386 This rewrite will always succeed, by construction.
 387 The result is the laundered branch.
 388
 389 =head1 SEE ALSO
 390
 391 git-debrebase(1),
 392 dgit-maint-rebase(7),
 393 dgit(1),
 394 gitglossary(7)