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