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