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