git-debrebase.5.pod

   1 =head1 NAME
   2
   3 git-debrebase - git data model 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 The Debian packaging
  12 has a fast forwarding history.
  13 The delta queue (changes to upstream files) is represented
  14 as a series of individual git commits,
  15 which can worked on with rebase,
  16 and also shared.
  17
  18 git-debrebase is designed to work well with dgit.
  19 git-debrebase can also be used in workflows without source packages,
  20 for example to work on Debian-format packages outside or alongside Debian.
  21
  22 git-debrebase
  23 itself is not very suitable for use by Debian derivatives,
  24 to work on packages inherited from Debian,
  25 because it assumes that you want to throw away any packaging
  26 provided by your upstream.
  27 However, of git-debrebase in Debian does not make anything harder for
  28 derivatives, and it can make some things easier.
  29
  30 =head1 TERMINOLOGY
  31
  32 =over
  33
  34 =item Pseudomerge
  35
  36 A merge which does not actually merge the trees;
  37 instead, it is constructed by taking the tree
  38 from one of the parents
  39 (ignoring the contents of the other parents).
  40 These are used to make a rewritten history fast forward
  41 from a previous tip,
  42 so that it can be pushed and pulled normally.
  43 Manual construction of pseudomerges can be done with
  44 C<git merge -s ours>
  45 but is not normally needed when using git-debrebase.
  46
  47 =item Packaging files
  48
  49 Files in the source tree within B<debian/>,
  50 excluding anything in B<debian/patches/>.
  51
  52 =item Upstream
  53
  54 The version of the package without Debian's packaging.
  55 Typically provided by the actual upstream project,
  56 and sometimes tracked by Debian contributors in a branch C<upstream>.
  57
  58 Upstream contains upstream files,
  59 but some upstreams also contain packaging files in B<debian/>.
  60 Any such non-upstream files found in upstream
  61 are thrown away by git-debrebase
  62 each time a new upstream version is incorporated.
  63
  64 =item Upstream files
  65
  66 Files in the source tree outside B<debian/>.
  67 These may include unmodified source from upstream,
  68 but also files which have been modified or created for Debian.
  69
  70 =item Delta queue
  71
  72 Debian's changes to upstream files:
  73 a series of git commits.
  74
  75 =item Quilt patches
  76
  77 Files in B<debian/patches/> generated for the benefit of
  78 dpkg-source's 3.0 (quilt) .dsc source package format.
  79 Not used, often deleted, and regenerated when needed
  80 (such as when uploading to Debian),
  81 by git-debrebase.
  82
  83 =back
  84
  85 =head1 DIAGRAM
  86
  87            ------/--A!----/--B3!--%--/--> interchange view
  88                 /        /          /      with debian/ directory
  89                %        %          %       entire delta queue applied
  90               /        /          /        3.0 (quilt) has debian/patches
  91              /        /          3*       "master" on Debian git servers
  92             /        /          /
  93            2*       2*         2
  94           /        /          /
  95          1        1          1    breakwater branch, merging baseline
  96         /        /          /     unmodified upstream code
  97     ---@-----@--A----@--B--C      plus debian/ (but no debian/patches)
  98       /     /       /                     no ref refers to this: we
  99    --#-----#-------#-----> upstream        reconstruct its identity by
 100                                            inspecting interchange branch
 101     Key:
 102
 103       1,2,3   commits touching upstream files only
 104       A,B,C   commits touching debian/ only
 105       B3      mixed commit (eg made by an NMUer)
 106       #       upstream releases
 107
 108      -@-      anchor merge, takes contents of debian/ from the
 109      /         previous `breakwater' commit and rest from upstream
 110
 111      -/-      pseudomerge; contents are identical to
 112      /         parent lower on diagram.
 113
 114       %       dgit-generated commit of debian/patches.
 115               `3.0 (quilt)' only; generally dropped by git-debrebase.
 116
 117       *       Maintainer's HEAD was here while they were editing,
 118               before they said they were done, at which point their
 119               tools made -/- (and maybe %) to convert to
 120               the fast-forwarding interchange branch.
 121
 122       !       NMUer's HEAD was here when they said `dgit push'.
 123               Rebase branch launderer turns each ! into an
 124               equivalent *.
 125
 126 =head1 BRANCHES AND BRANCH STATES - OVERVIEW
 127
 128 git-debrebase has one primary branch,
 129 the B<interchange branch>.
 130 This branch is found on Debian contributor's workstations
 131 (typically, a maintainer would call it B<master>),
 132 in the Debian dgit git server as the suite branch (B<dgit/dgit/sid>)
 133 and on other git servers which support Debian work
 134 (eg B<master> on salsa).
 135
 136 The interchange branch is fast-forwarding
 137 (by virtue of pseudomerges, where necessary).
 138
 139 It is possible to have multiple different interchange branches
 140 for the same package,
 141 stored as different local and remote git branches.
 142 However, divergence should be avoided where possible -
 143 see L</OTHER MERGES>.
 144
 145 A suitable interchange branch can be used directly with dgit.
 146 In this case each dgit archive suite branch is a separate
 147 interchange branch.
 148
 149 Within the ancestry of the interchange branch,
 150 there is another important, implicit branch, the
 151 B<breakwater>.
 152 The breakwater contains unmodified upstream source,
 153 but with Debian's packaging superimposed
 154 (replacing any C<debian/> directory that may be in
 155 the upstream commits).
 156 The breakwater does not contain any representation of
 157 the delta queue (not even debian/patches).
 158 The part of the breakwater processed by git-debrebase
 159 is the part since the most reecent B<anchor>,
 160 which is usually a special merge generated by git-debrebase.
 161
 162 When working, locally,
 163 the user's branch can be in a rebasing state,
 164 known as B<unstitched>.
 165 While a branch is unstitched,
 166 it is not in interchange format.
 167 The previous interchange branch tip
 168 tip is recorded,
 169 so that the previous history
 170 and the user's work
 171 can later be
 172 stitched into the fast-forwarding interchange form.
 173
 174 An unstitched branch may be in
 175 B<laundered>
 176 state,
 177 which means it has a more particular special form
 178 convenient for manipulating the delta queue.
 179
 180 =head1 BRANCH CONTENTS - DETAILED SPECIFICATION
 181
 182 It is most convenient to describe the
 183 B<breakwater>
 184 branch first.
 185 A breakwater is B<fast-forwarding>,
 186 but is not usually named by a ref.
 187 It contains B<in this order> (ancestors first):
 188
 189 =over
 190
 191 =item Anchor
 192
 193 An B<anchor> commit,
 194 which is usually a special two-parent merge:
 195
 196 The first parent
 197 contains the most recent version, at that point,
 198 of the Debian packaging (in debian/);
 199 it also often contains upstream files,
 200 but they are to be ignored.
 201 Often the first parent is a previous breakwater tip.
 202
 203 The second parent
 204 is an upstream source commit.
 205 It may sometimes contain a debian/ subdirectory,
 206 but if so that is to be ignored.
 207 The second parent's upstream files
 208 are identical to the anchor's.
 209 Anchor merges always contain
 210 C<[git-debrebase anchor: ...]>
 211 as a line in the commit message.
 212
 213 Alternatively,
 214 an anchor may be a single-parent commit which introduces
 215 the C<debian/> directory and makes no other changes:
 216 ie, the start of Debian packaging.
 217
 218 =item Packaging
 219
 220 Zero or more single-parent commits
 221 containing only packaging changes.
 222 (And no quilt patch changes.)
 223
 224 =back
 225
 226 The
 227 B<laundered>
 228 branch state is B<rebasing>.
 229 A laundered branch is based on a breakwater
 230 but also contains, additionally,
 231 B<after> the breakwater,
 232 a representation of the delta queue:
 233
 234 =over
 235
 236 =item Delta queue commits
 237
 238 Zero or more single-parent commits
 239 contaioning only changes to upstream files.
 240
 241 =back
 242
 243 The merely
 244 B<unstitched>
 245 (ie, unstitched but unlaundered)
 246 branch state is also B<rebasing>.
 247 It has the same contents as the laundered state,
 248 except that it may contain,
 249 additionally,
 250 in B<in any order but after the breakwater>:
 251
 252 =over
 253
 254 =item Linear commits to the source
 255
 256 Further commit(s) containing changes to
 257 to upstream files
 258 and/or
 259 to packaging,
 260 possibly mixed within a single commit.
 261 (But not quilt patch changes.)
 262
 263 =item Quilt patch addition for `3.0 (quilt)'
 264
 265 Commit(s) which add patches to B<debian/patches/>,
 266 and add those patches to the end of B<series>.
 267
 268 These are only necessary when working with
 269 packages in C<.dsc 3.0 (quilt)> format.
 270 For git-debrebase they are purely an output;
 271 they are deleted when branches are laundered.
 272 git-debrebase takes care to make a proper patch
 273 series out of the delta queue,
 274 so that any resulting source packages are nice.
 275
 276 =back
 277
 278 Finally, an
 279 B<interchange>
 280 branch is B<fast forwarding>.
 281 It has the same contents as an
 282 unlaundered branch state,
 283 but may (and usually will) additionally contain
 284 (in some order,
 285 possibly intermixed with the extra commits
 286 which may be found on an unstitched unlaundered branch):
 287
 288 =over
 289
 290 =item Pseudomerge to make fast forward
 291
 292 A pseudomerge making the branch fast forward from
 293 previous history.
 294 The contributing parent is itself in interchange format.
 295 Normally the overwritten parent is
 296 a previous tip of an interchange branch,
 297 but this is not necessary as the overwritten
 298 parent is not examined.
 299
 300 If the two parents have identical trees,
 301 the one with the later commit date
 302 (or, if the commit dates are the same,
 303 the first parent)
 304 is treated as
 305 the contributing parent.
 306
 307 =item dgit dsc import pseudomerge
 308
 309 Debian .dsc source package import(s)
 310 made by dgit
 311 (during dgit fetch of a package most recently
 312 uploaded to Debian without dgit,
 313 or during dgit import-dsc).
 314
 315 git-debrebase requires that
 316 each such import is in the fast-forwarding
 317 format produced by dgit:
 318 a two-parent pseudomerge,
 319 whose contributing parent is in the
 320 non-fast-forwarding
 321 dgit dsc import format (not described further here),
 322 and whose overwritten parent is
 323 the previous interchange tip
 324 (eg, the previous tip of the dgit suite branch).
 325
 326 =back
 327
 328 =head1 STITCHING, PSEUDO-MERGES, FFQ RECORD
 329
 330 Whenever the branch C<refs/B> is unstitched,
 331 the previous head is recorded in the git ref C<refs/ffq-prev/B>.
 332
 333 Unstiched branches are not fast forward from the published
 334 interchange branches [1].
 335 So before a branch can be pushed,
 336 the right pseudomerge must be reestablished.
 337 This is the stitch operation,
 338 which consumes the ffq-prev ref.
 339
 340 When the user has an unstitched branch,
 341 they may rewrite it freely,
 342 from the breakwater tip onwards.
 343 Such a git rebase is the default operation for git-debrebase.
 344 Rebases should not go back before the breakwater tip,
 345 and certainly not before the most recent anchor.
 346
 347 Unstitched branches must not be pushed to interchange branch refs
 348 (by the use of C<git push -f> or equivalent).
 349 It is OK to share an unstitched branch
 350 in similar circumstances and with similar warnings
 351 to sharing any other rebasing git branch.
 352
 353 [1] Strictly, for a package
 354 which has never had a Debian delta queue,
 355 the interchange and breakwater branches may be identical,
 356 in which case the unstitched branch is fast forward
 357 from the interchange branch and no pseudomerge is needed.
 358
 359 When ffq-prev is not present,
 360 C<refs/debrebase-last/B> records some ancestor of refs/B,
 361 (usually, the result of last stitch).
 362 This can be used to quickly determine whether refs/B
 363 is being maintained in git-debrebase form.
 364
 365 =head1 OTHER MERGES
 366
 367 Note that the representation described here does not permit
 368 general merges on any of the relevant branches.
 369 For this reason the tools will try to help the user
 370 avoid divergence of the interchange branch.
 371
 372 See dgit-maint-rebase(7) XXX TBD
 373 for a discussio of what kinds of behaviours
 374 should be be avoided
 375 because
 376 they might generate such merges.
 377
 378 Automatic resolution of divergent interchange branches
 379 (or laundering of merges on the interchange branch)
 380 is thought to be possible,
 381 but there is no tooling for this yet:
 382
 383 Nonlinear (merging) history in the interchange branch is awkward
 384 because it (obviously) does not preserve
 385 the linearity of the delta queue.
 386 Easy merging of divergent delta queues is a research problem.
 387
 388 Nonlinear (merging) history in the breakwater branch is
 389 in principle tolerable,
 390 but each of the parents would have to be, in turn,
 391 a breakwater,
 392 and difficult qeustions arise if they don't have the same anchor.
 393
 394 We use the commit message annotation to
 395 distinguish the special anchor merges from other general merges,
 396 so we can at least detect unsupported merges.
 397
 398 =head1 LEGAL OPERATIONS
 399
 400 The following basic operations follows from this model
 401 (refer to the diagram above):
 402
 403 =over
 404
 405 =item Append linear commits
 406
 407 No matter the branch state,
 408 it is always fine to simply git commit
 409 (or cherry-pick etc.)
 410 commits containing upstream file changes, packaging changes,
 411 or both.
 412
 413 (This may make the branch unlaundered.)
 414
 415 =item Launder branch
 416
 417 Record the previous head in ffq-prev,
 418 if we were stitched before
 419 (and delete debrebase-last).
 420
 421 Reorganise the current branch so that the packaging
 422 changes come first,
 423 followed by the delta queue,
 424 turning C<-@-A-1-2-B3> into C<...@-A-B-1-2-3>.
 425
 426 Drop pseudomerges and any quilt patch additions.
 427
 428 =item Interactive rebase
 429
 430 With a laundered branch,
 431 one can do an interactive git rebase of the delta queue.
 432
 433 =item New upstream rebase
 434
 435 Start rebasing onto a new upstream version,
 436 turning C<...#..@-A-B-1-2-3> into C<(...#..@-A-B-, ...#'-)@'-1-2>.
 437
 438 This has to be a wrapper around git-rebase,
 439 which prepares @' and then tries to rebase 1 2 onto @'.
 440 If the user asks for an interactive rebase,
 441 @' doesn't appear in the commit list, since
 442 @' is the newbase of the rebase (see git-rebase(1)).
 443
 444 Note that the construction of @' cannot fail
 445 because @' simply copies debian/ from B and and everything else from #'.
 446 (Rebasing A and B is undesirable.
 447 We want the debian/ files to be non-rebasing
 448 so that git log shows the packaging history.)
 449
 450 =item Stitch
 451
 452 Make a pseudomerge,
 453 whose contributing parent to is the unstitched branch
 454 and
 455 whose overwritten parent is ffq-prev,
 456 consuming ffq-prev in the process
 457 (and writing debrebase-last instead).
 458 Ideally the contributing parent would be a laundered branch,
 459 or perhaps a laundered branch with a quilt patch addition commit.
 460
 461 =item Commit quilt patches
 462
 463 To generate a tree which can be represented as a
 464 3.0 (quilt) .dsc source packages,
 465 the delta queue must be reified inside the git tree
 466 in B<debian/patches/>.
 467 These patch files can be stripped out and/or regenerated as needed.
 468
 469 =back
 470
 471 =head1 COMMIT MESSAGE ANNOTATIONS
 472
 473 git-debrebase makes annotations
 474 in the messages of commits it generates.
 475
 476 The general form is
 477
 478   [git-debrebase[ COMMIT-TYPE [ ARGS...]]: PROSE, MORE PROSE]
 479
 480 git-debrebase treats anything after the colon as a comment,
 481 paying no attention to PROSE.
 482
 483 The full set of annotations is:
 484   [git-debrebase: split mixed commit, debian part]
 485   [git-debrebase: split mixed commit, upstream-part]
 486   [git-debrebase: convert dgit import, debian changes]
 487   [git-debrebase anchor: convert dgit import, upstream changes]
 488
 489   [git-debrebase upstream-combine . PIECE[ PIECE...]: new upstream]
 490   [git-debrebase anchor: new upstream NEW-UPSTREAM-VERSION, merge]
 491   [git-debrebase: new upstream NEW-UPSTREAM-VERSION, changelog]
 492
 493   [git-debrebase convert-from-gbp: drop patches]
 494   [git-debrebase anchor: declare upstream]
 495   [git-debrebase pseudomerge: stitch]
 496
 497   [git-debrebase convert-to-gbp: commit patches]
 498
 499 Only anchor merges have the C<[git-debrebase anchor: ...]> tag.
 500 Single-parent anchors are not generated by git-debrebase,
 501 and when made manually should not be tagged.
 502
 503 The C<split mixed commit> and C<convert dgit import>
 504 tags are added to the pre-existing commit message,
 505 when git-debrebase rewrites the commit.
 506
 507 =head1 APPENDIX - DGIT IMPORT HANDLING
 508
 509 Consider a non-dgit NMU followed by a dgit NMU:
 510
 511             interchange --/--B3!--%--/----D*-->
 512                          /          /
 513                         %          4
 514                        /          3
 515                       /          2
 516                      /          1
 517                     2          &_
 518                    /          /| \
 519                   1          0 00 =XBC%
 520                  /
 521                 /
 522           --@--A     breakwater
 523            /
 524         --#--------> upstream
 525
 526
 527  Supplementary key:
 528
 529     =XBC%     dgit tarball import of .debian.tar.gz containing
 530               Debian packaging including changes B C and quilt patches
 531
 532     0         dgit tarball import of upstream tarball
 533     00        dgit tarball import of supplementary upstream tarball
 534     &_        dgit nearly-breakwater import
 535     &'        git-debrebase converted import (upstream files only)
 536     D'        git-debrebase converted debian/ changes import
 537
 538     * **      before and after HEAD
 539
 540 We want to transform this into:
 541
 542 =over
 543
 544 =item I. No new upstream version
 545
 546  (0 + 00 eq #)
 547                         --/--B3!--%--/------D*-------------/-->
 548                          /          /                     /
 549                         %          4                     4**
 550                        /          3                     3
 551                       /          2                     2
 552                      /          1                     1
 553                     2          &_                    /
 554                    /          /| \                  /
 555                   1          0 00 =XBC%            /
 556                  /                                /
 557                 /                                /
 558           --@--A-----B-----------------------C--D
 559            /
 560         --#----------------------------------------->
 561
 562 =item II. New upstream
 563
 564  (0 + 00 neq #)
 565
 566                         --/--B3!--%--/------D*-------------/-->
 567                          /          /                     /
 568                         %          4                     4**
 569                        /          3                     3
 570                       /          2                     2
 571                      /          1                     1
 572                     2          &_                    /
 573                    /          /| \                  /
 574                   1          0 00 =XBC%            /
 575                  /                                /
 576                 /                                /
 577           --@--A-----B--------------------@--C--D
 578            /                             /
 579         --#----------------------- - -  /  - - ----->
 580                                        /
 581                                       &'
 582                                      /|
 583                                     0 00
 584
 585 =back
 586
 587 =head1 SEE ALSO
 588
 589 git-debrebase(1),
 590 dgit-maint-rebase(7),
 591 dgit(1)