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