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