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
 120
 121 It is most convenient to describe the
 122 B<laundered>
 123 state first.
 124 It contains B<in this order> (ancestors first):
 125
 126 =over
 127
 128 =item Anchor
 129
 130 An B<anchor> commit,
 131 which is usually a special two-parent merge:
 132 The first parent is
 133 a previous branch tip with Debian packaging tip
 134 (perhaps a previous breakwater tip)
 135 whose upstream files are irrelevant,
 136 and whose packaging files are identical to the anchor's.
 137 The second parent is an upstream source commit,
 138 whose packaging files (if any) are irrelevant,
 139 and whose upstream files are identical to the anchor's.
 140 Anchor merges always contain
 141 C<[git-debrebase anchor: ...]>
 142 as a line in the commit message.
 143 Alternatively,
 144 an anchor may be a single-parent commit which introduces
 145 the C<debian/> directory and makes no other changes:
 146 ie, the start of Debian packaging.
 147
 148 =item Packaging
 149
 150 Zero or more single-parent commits
 151 containing only packaging changes.
 152 (And no quilt patch changes.)
 153
 154 =item Delta queue commits
 155
 156 Zero or more single-parent commits
 157 contaioning only changes to upstream files.
 158
 159 =back
 160
 161 The
 162 B<unstitched>
 163 (unlaundered)
 164 branch state is the same,
 165 except that it may contain,
 166 additionally,
 167 in B<in any order>:
 168
 169 =over
 170
 171 =item Linear commits to the source
 172
 173 Further commit(s) containing changes to
 174 to upstream files
 175 and/or
 176 to packaging,
 177 possibly mixed within a single commit.
 178 (But not quilt patch changes.)
 179
 180 =item Quilt patch addition for `3.0 (quilt)'
 181
 182 Commit(s) which add patches to B<debian/patches/>,
 183 and add those patches to the end of B<series>.
 184 These are only necessary when working with
 185 packages in C<.dsc 3.0 (quilt)> format.
 186 For git-debrebase they are purely an output;
 187 they are deleted when branches are laundered.
 188
 189 =back
 190
 191 The
 192 B<interchange>
 193 branch state is the same, but may additionally contain
 194 (in some order,
 195 possibly intermixed with the extra commits
 196 which may be found on an unstitched unlaundered branch):
 197
 198 =over
 199
 200 =item Pseudomerge to make fast forward
 201
 202 A pseudomerge making the branch fast forward from
 203 previous history.
 204 The contributing parent is itself in interchange format.
 205 Normally the overwritten parent is
 206 a previous tip of the interchange branch,
 207 but this is not necessary as the overwritten
 208 parent is not examined.
 209
 210 If the two parents have identical trees,
 211 the contributing parent is taken to be
 212 the one with the later commit date,
 213 or if the commit dates are the same,
 214 the left parent.
 215
 216 =item dgit dsc import
 217
 218 Debian .dsc source package import(s) made by dgit.
 219 Each such import must be a two-parent pseudomerge
 220 whose contributing parent is in the special
 221 dgit format (not described further here).
 222 The overwritten parent must be
 223 the previous interchange tip.
 224 This is the form normally generated by dgit
 225 when it imports .dsc-based uploads.
 226
 227 =back
 228
 229 =head1 STITCHING, PSEUDO-MERGES, FFQ RECORD
 230
 231 Whenever the branch C<refs/B> is unstitched,
 232 the previous tip is recorded in the git ref C<refs/ffq-prev/B>.
 233
 234 Unstiched branches are not fast forward from the published
 235 interchange branches [1].
 236 So before a branch can be pushed,
 237 the right pseudomerge must be reestablished.
 238 This is the stitch operation,
 239 which consumes the ffq-prev ref.
 240
 241 When the user has an unstitched branch,
 242 they may rewrite it freely,
 243 from the breakwater tip onwards.
 244 Such a git rebase is the default operation for git-debrebase.
 245 Rebases should not go back before the breakwater tip,
 246 and certainly not before the most recent anchor.
 247
 248 Unstitched branches must not be pushed to interchange branch refs
 249 (by the use of C<git push -f> or equivalent).
 250 It is OK to share an unstitched branch
 251 in similar circumstances and with similar warnings
 252 to sharing any other rebasing git branch.
 253
 254 [1] Strictly, for a package
 255 which has never had a Debian delta queue,
 256 the interchange and breakwater branches may be identical,
 257 in which case the unstitched branch is fast forward
 258 from the interchange branch and no pseudomerge is needed.
 259
 260 =head1 OTHER MERGES
 261
 262 Note that the representation described here does not permit
 263 general merges on any of the relevant branches.
 264 For this reason the tools will try to help the user
 265 avoid divergence of the interchange branch.
 266
 267 Automatic resolution of divergent interchange branches
 268 (or laundering of merges on the interchange branch)
 269 is thought to be possible,
 270 but there is no tooling for this yet:
 271
 272 Nonlinear (merging) history in the interchange branch is awkward
 273 because it (obviously) does not preserve
 274 the linearity of the delta queue.
 275 Easy merging of divergent delta queues is a research problem.
 276
 277 Nonlinear (merging) history in the breakwater branch is
 278 in principle tolerable,
 279 but each of the parents would have to be, in turn,
 280 a breakwater,
 281 and difficult qeustions arise if they don't have the same anchor.
 282
 283 We use the commit message annotation to
 284 distinguish the special anchor merges from other general merges,
 285 so we can at least detect unsupported merges.
 286
 287 =head1 LEGAL OPERATIONS
 288
 289 The following basic operations follows from this model
 290 (refer to the diagram above):
 291
 292 =over
 293
 294 =item Append linear commits
 295
 296 No matter the branch state,
 297 it is always fine to simply git commit
 298 (or cherry-pick etc.)
 299 commits containing upstream file changes, packaging changes,
 300 or both.
 301
 302 (This may make the branch unlaundered.)
 303
 304 =item Launder branch
 305
 306 Record the previous tip in ffq-prev,
 307 if we were stitched before.
 308
 309 Reorganise the current branch so that the packaging
 310 changes come first,
 311 followed by the delta queue,
 312 turning C<-@-A-1-2-B3> into C<...@-A-B-1-2-3>.
 313
 314 Drop pseudomerges and any quilt patches.
 315
 316 =item Interactive rebase
 317
 318 With a laundered branch,
 319 one can do an interactive git rebase of the delta queue.
 320
 321 =item New upstream rebase
 322
 323 Start rebasing onto a new upstream version,
 324 turning C<...#..@-A-B-1-2-3> into C<(...#..@-A-B-|...#'-)@'-1-2>.
 325
 326 This has to be a wrapper around git-rebase,
 327 which prepares @' and then tries to rebase 1 2 onto @'.
 328 If the user asks for an interactive rebase,
 329 @' doesn't appear in the commit list.
 330
 331 Note that the construction of @' cannot fail
 332 because @' simply copies debian/ from B and and everything else from #'.
 333 (Rebasing A and B is undesirable.
 334 We want the debian/ files to be non-rebasing
 335 so that git log shows the packaging history.)
 336
 337 =item Stitch
 338
 339 Make a pseudomerge,
 340 whose contributing parent to is the unstitched branch
 341 and
 342 whose overwritten parent is ffq-prev,
 343 consuming ffq-prev in the process.
 344 Ideally the contributing parent would be a laundered branch,
 345 or perhaps a laundered branch with a quilt patch addition commit.
 346
 347 =item Commit quilt patches
 348
 349 To generate a tree which can be represented as a
 350 3.0 (quilt) .dsc source packages,
 351 the delta queue must be reified inside the git tree
 352 in B<debian/patches/>.
 353 These patch files can be stripped out and/or regenerated as needed.
 354
 355 =back
 356
 357 =head1 COMMIT MESSAGE ANNOTATIONS
 358
 359 git-debrebase makes annotations
 360 in the messages of commits it generates.
 361
 362 The general form is
 363
 364   [git-debrebase[ COMMIT-TYPE [ ARGS...]]: PROSE, MORE PROSE]
 365
 366 git-debrebase does not pay attention to anything after the colon,
 367 so PROSE is ignored.
 368
 369 The full set of annotations is:
 370   [git-debrebase: split mixed commit, debian part]
 371   [git-debrebase: split mixed commit, upstream-part]
 372   [git-debrebase: convert dgit import, debian changes]
 373   [git-debrebase anchor: convert dgit import, upstream changes]
 374
 375   [git-debrebase upstream-combine . PIECE[ PIECE...]: new upstream]
 376   [git-debrebase anchor: new upstream NEW-UPSTREAM-VERSION, merge]
 377   [git-debrebase: new upstream NEW-UPSTREAM-VERSION, changelog]
 378
 379   [git-debrebase convert-from-gbp: drop patches]
 380   [git-debrebase anchor: declare upstream]
 381   [git-debrebase pseudomerge: stitch]
 382
 383   [git-debrebase convert-to-gbp: commit patches]
 384
 385 Only anchor merges have the C<[git-debrebase anchor: ...]> tag.
 386 Single-parent anchors are not generated by git-debrebase,
 387 and when made manually should not be tagged.
 388
 389 The C<split mixed commit> and C<convert dgit import>
 390 tags are added to the pre-existing commit message,
 391 when git-debrebase rewrites the commit.
 392
 393 =head1 TERMINOLOGY
 394
 395 =over
 396
 397 =item Pseudomerge
 398
 399 A merge which does not actually merge the trees;
 400 instead, it takes its tree, by construction, from only one parent.
 401 These are used to make a rewritten history fast forward
 402 from a previous tip,
 403 so that it can be pushed and pulled normally.
 404 Manual construction of pseudomerges can be done with
 405 C<git merge -s ours>
 406 but is not normally needed when using git-debrebase.
 407
 408 =item Packaging files
 409
 410 Files in the source tree within B<debian/>.
 411 (Does not include anything which may exist in B<debian/patches/>.)
 412
 413 =item Upstream
 414
 415 The version of the package without Debian's packaging.
 416 Typically provided by the actual upstream project,
 417 and often tracked by Debian contributors in a branch C<upstream>.
 418
 419 =item Upstream files
 420
 421 Files in the source tree outside B<debian/>.
 422 These may include unmodified source from upstream,
 423 but also files which have been modified or created for Debian.
 424
 425 =item Delta queue
 426
 427 Debian's changes to upstream files:
 428 a series of git commits.
 429
 430 =item Quilt patches
 431
 432 Files in B<debian/patches/> generated for the benefit of
 433 dpkg-source's 3.0 (quilt) .dsc source package format.
 434 Not used, and often deleted, by git-debrebase.
 435
 436 =back
 437
 438 =head1 APPENDIX - DGIT IMPORT HANDLING
 439
 440 Consider a non-dgit NMU followed by a dgit NMU:
 441
 442             interchange --/--B3!--%--/----D*-->
 443                          /          /
 444                         %          4
 445                        /          3
 446                       /          2
 447                      /          1
 448                     2*         &_
 449                    /          /| \
 450                   1          0 00 =XBC%
 451                  /
 452                 /
 453           --@--A     breakwater
 454            /
 455         --#--------> upstream
 456
 457
 458  Key:
 459
 460     =XBC%     dgit tarball import of .debian.tar.gz containing
 461               Debian packaging including changes B C and quilt patches
 462
 463     0         dgit tarball import of upstream tarball
 464     00        dgit tarball import of supplementary upstream tarball
 465     &_        dgit nearly-breakwater import
 466     &'        git-debrebase converted import (upstream files only)
 467     D'        git-debrebase converted debian/ changes import
 468
 469     * **      before and after HEAD
 470
 471 We want to transform this into:
 472
 473 =over
 474
 475 =item I. No new upstream version
 476
 477  (0 + 00 eq #)
 478                         --/--B3!--%--/------D*-------------/-->
 479                          /          /                     /
 480                         %          4                     4**
 481                        /          3                     3
 482                       /          2                     2
 483                      /          1                     1
 484                     2*         &_                    /
 485                    /          /| \                  /
 486                   1          0 00 =XBC%            /
 487                  /                                /
 488                 /                                /
 489           --@--A-----B-----------------------C--D
 490            /
 491         --#----------------------------------------->
 492
 493 =item II. New upstream
 494
 495  (0 + 00 neq #)
 496
 497                         --/--B3!--%--/------D*-------------/-->
 498                          /          /                     /
 499                         %          4                     4**
 500                        /          3                     3
 501                       /          2                     2
 502                      /          1                     1
 503                     2*         &_                    /
 504                    /          /| \                  /
 505                   1          0 00 =XBC%            /
 506                  /                                /
 507                 /                                /
 508           --@--A-----B--------------------@--C--D
 509            /                             /
 510         --#----------------------- - -  /  - - ----->
 511                                        /
 512                                       &'
 513                                      /|
 514                                     0 00
 515
 516 =back
 517
 518 =head1 SEE ALSO
 519
 520 git-debrebase(1),
 521 dgit-maint-rebase(7),
 522 dgit(1)