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