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 TERMINOLOGY
 273
 274 =over
 275
 276 =item Pseudomerge
 277
 278 A merge which does not actually merge the trees;
 279 instead, it takes its tree by construction from one parent.
 280 These are used to make a rewritten history fast forward
 281 from a previous tip,
 282 so that it can be pushed and pulled normally.
 283 Manual construction of pseudomerges can be done with
 284 C<git merge -s ours>
 285 but is not normally needed when using git-debrebase.
 286
 287 =item Packaging files
 288
 289 Files in the source tree within B<debian/>.
 290 (Does not include anything which may exist in B<debian/patches/>.)
 291
 292 =item Upstream
 293
 294 The version of the package without Debian's packaging.
 295 Typically provided by the actual upstream project,
 296 and often tracked by Debian contributors in a branch C<upstream>.
 297
 298 =item Upstream files
 299
 300 Files in the source tree outside B<debian/>.
 301 These may include unmodified source from upstream,
 302 but also files which have been modified or created for Debian.
 303
 304 =back
 305
 306 =head1 APPENDIX - DGIT IMPORT HANDLING
 307
 308 Consider a non-dgit NMU followed by a dgit NMU:
 309
 310             interchange --/--B3!--%--/----D*-->
 311                          /          /
 312                         %          4
 313                        /          3
 314                       /          2
 315                      /          1
 316                     2*         &_
 317                    /          /| \
 318                   1          0 00 =XBC%
 319                  /
 320                 /
 321           --@--A     breakwater
 322            /
 323         --#--------> upstream
 324
 325
 326  Key:
 327
 328     =XBC%     dgit tarball import of .debian.tar.gz containing
 329               Debian packaging including changes B C and patches
 330
 331     0         dgit tarball import of upstream tarball
 332     00        dgit tarball import of supplementary upstream tarball
 333     &_        dgit nearly-breakwater import
 334     &'        git-debrebase converted import (upstream files only)
 335     D'        git-debrebase converted debian/ changes import
 336
 337     * **      before and after HEAD
 338
 339 We want to transform this into:
 340
 341 =over
 342
 343 =item I. No new upstream version
 344
 345  (0 + 00 eq #)
 346                         --/--B3!--%--/------D*-------------/-->
 347                          /          /                     /
 348                         %          4                     4**
 349                        /          3                     3
 350                       /          2                     2
 351                      /          1                     1
 352                     2*         &_                    /
 353                    /          /| \                  /
 354                   1          0 00 =XBC%            /
 355                  /                                /
 356                 /                                /
 357           --@--A-----B-----------------------C--D
 358            /
 359         --#----------------------------------------->
 360
 361 =item II. New upstream
 362
 363  (0 + 00 neq #)
 364
 365                         --/--B3!--%--/------D*-------------/-->
 366                          /          /                     /
 367                         %          4                     4**
 368                        /          3                     3
 369                       /          2                     2
 370                      /          1                     1
 371                     2*         &_                    /
 372                    /          /| \                  /
 373                   1          0 00 =XBC%            /
 374                  /                                /
 375                 /                                /
 376           --@--A-----B--------------------@--C--D
 377            /                             /
 378         --#----------------------- - -  /  - - ----->
 379                                        /
 380                                       &'
 381                                      /|
 382                                     0 00
 383
 384 =back
 385
 386 =head1 SEE ALSO
 387
 388 git-debrebase(1),
 389 dgit-maint-rebase(7),
 390 dgit(1)