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