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