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.  (Maybe the
  63               tooling is simply `dgit push'.)
  64
  65       !       NMUer's HEAD was here when they said `dgit push'.
  66               Rebase branch launderer turns each ! into an
  67               equivalent *.
  68
  69 =head1 BRANCHES AND BRANCH STATES
  70
  71 git-debrebase has one primary branch,
  72 the B<interchange branch>.
  73 This branch is found on Debian contributor's workstations
  74 (typically, a maintainer would call it B<master>),
  75 in the Debian dgit git server as the suite branch (B<dgit/dgit/sid>)
  76 and on other git servers which support Debian owrk
  77 (eg B<master> on salsa).
  78
  79 The interchange branch is fast-forwarding
  80 (by virtue of pseudomerges, where necessary).
  81
  82 It is possible to have multiple different interchange branches
  83 for the same package,
  84 stored as different local and remote git branches.
  85 However, divergence should be avoided where possible -
  86 see L</STITCHING, PSEUDO-MERGES, FFQ RECORD>.
  87
  88 A suitable interchange branch can be used directly with dgit.
  89 In this case each dgit archive suite branch is a separate
  90 interchange branch.
  91
  92 Within the ancenstry of the interchange branch,
  93 there is another importnt, implicit branch, the
  94 B<breakwater>.
  95 The breakwater contains unmodified upstream source,
  96 but with Debian's packaging superimposed
  97 (replacing any C<debian/> directory that may be in upstream).
  98 The breakwater does not contain any representation
  99 of Debian's changes to upstream files.
 100 The breakwater starts at an 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 When a branch is unstitched,
 107 its previous tip is recorded so that it can later be
 108 stitched into the fast-forwarding interchange form.
 109
 110 An unstitched branch may be in
 111 B<laundered>
 112 state,
 113 which means it has a more particular special form
 114 convenient for manipulating the changes to upstream files.
 115
 116 =head1 BRANCH CONTENTS
 117
 118 It is most convenient to describe the
 119 B<laundered>
 120 state first.
 121 It contains B<in this order> (ancestors first):
 122
 123 =over
 124
 125 =item Anchor
 126
 127 An B<anchor> commit,
 128 which is usually a special two-parent merge:
 129 The first parent is a previous breakwater branch,
 130 whose upstream files are irrelevant,
 131 and whose packaging files are identical to the anchor's.
 132 The second parent is an upstream source commit;
 133 whose packaging files (if any) are irrelevant,
 134 and whose upstream files are identical to the anchor's.
 135 Anchor merges always contain
 136 C<[git-debrebase anchor: ...]>
 137 as a line in the commit message.
 138 Alternatively,
 139 an anchor may be a single-parent commit which introduces
 140 the C<debian/> directory and makes no other changes:
 141 ie, the start of Debian packaging.
 142
 143 =item Packaging
 144
 145 Zero or more single-parent commits
 146 containing only packaging changes.
 147 (And no changes to B<debian/patches/>.)
 148
 149 =item Delta from upstream
 150
 151 Zero or more single-parent commits
 152 contaioning only changes to upstream files.
 153
 154 =back
 155
 156 The
 157 B<unstitched>
 158 (unlaundered)
 159 branch state is the same,
 160 except that it may contain,
 161 additionally,
 162 in B<in any order>:
 163
 164 =over
 165
 166 =item Linear commits to the source
 167
 168 Further commit(s) containing changes to
 169 to upstream files
 170 and/or
 171 to packaging,
 172 possibly mixed within a single commit.
 173 (But no changes to B<debian/patches/>.)
 174
 175 =item Patch addition for `3.0 (quilt)'
 176
 177 Commit(s) which add patches to B<debian/patches/>,
 178 and add those patches to the end of B<series>.
 179 These are only necessary or useful when working with
 180 packages in C<.dsc 3.0 (quilt)> format.
 181
 182 =back
 183
 184 The
 185 B<interchange>
 186 branch state is the same, but may additionally contain
 187 (in some order,
 188 possibly intermixed with the extra commits
 189 which may be found on an unstitched unlaundered branch):
 190
 191 =over
 192
 193 =item Pseudomerge to make fast forward
 194
 195 A pseudomerge making the branch fast forward from
 196 previous history.
 197 The contributing parent is itself in interchange format.
 198 Normally the overwritten parent is
 199 a previous tip of the interchange branch,
 200 but this is not necessary as the overwritten
 201 parent is not examined.
 202
 203 =item dgit dsc import
 204
 205 Debian .dsc source package import(s) made by dgit.
 206 Each such import must be a two-parent pseudomerge
 207 whose contributing parent is in the special
 208 dgit format (not described further here).
 209 The overwritten parent must be
 210 the previous interchange tip
 211 (and will be generated that way by normal use of dgit).
 212
 213 =back
 214
 215 =head1 STITCHING, PSEUDO-MERGES, FFQ RECORD
 216
 217 Whenever the branch C<refs/B> is unstitched,
 218 the previous tip is recorded in the git ref C<refs/ffq-prev/heads/B>.
 219
 220 Unstiched branches are not fast forward from the published
 221 interchange branches. [1]
 222 So before a branch can be pushed,
 223 the right pseudomerge must be reestablished.
 224 This is the stitch operation,
 225 which consumes the ffq-prev ref.
 226
 227 When the user has an unstituched branch,
 228 they may rewrite it freely,
 229 from the breakwater tip onwards.
 230 Such a git rebase is the default operation for git-debrebase.
 231 Rebases should not go back before the breakwater tip,
 232 and certainly not before the most recent anchor.
 233
 234 Unstitched branches must not be pushed to interchange branch refs
 235 (by the use of C<git push -f> or equivalent).
 236 It is OK to share an unstitched branch
 237 in similar circumstances and with similar warnings
 238 to sharing any other rebasing git branch.
 239
 240 [1] Strictly, for a package
 241 which has never had Debian changes to upstream files,
 242 the interchange and breakwater branches may be identical,
 243 in which case the unstitched branch is fast forward
 244 from the interchange branch and no pseudomerge is needed.
 245
 246 =head1 OTHER MERGES
 247
 248 Note that the representation described here does not permit
 249 general merges on any of the relevant branches.
 250 For this reason the tools will try to help the user
 251 avoid divergence of the interchange branch.
 252
 253 Automatic resolution of divergent interchange branches
 254 (or laundering of merges on the interchange branch)
 255 is thought to be possible,
 256 but there is no tooling for this yet:
 257
 258 Nonlinear (merging) history in the interchange branch is awkward
 259 because it (obviously) does not preserve
 260 the linearity of the delta queue.
 261 Easy merging of divergent delta queues is a research problem.
 262
 263 Nonlinear (merging) history in the breakwater branch is
 264 in principle tolerable,
 265 but each of the parents would have to be, in turn,
 266 a breakwater,
 267 and difficult qeustions arise if they don't have the same anchor.
 268
 269 We use the commit message annotation to
 270 distinguish the special anchor merges from other general merges,
 271 so we can at least detect unsupported merges.
 272
 273 =head1 TERMINOLOGY
 274
 275 =over
 276
 277 =item Pseudomerge
 278
 279 A merge which does not actually merge the trees;
 280 instead, it takes its tree by construction from one parent.
 281 These are used to make a rewritten history fast forward
 282 from a previous tip,
 283 so that it can be pushed and pulled normally.
 284 Manual construction of pseudomerges can be done with
 285 C<git merge -s ours>
 286 but is not normally needed when using git-debrebase.
 287
 288 =item Packaging files
 289
 290 Files in the source tree within B<debian/>.
 291 (Does not include anything which may exist in B<debian/patches/>.)
 292
 293 =item Upstream
 294
 295 The version of the package without Debian's packaging.
 296 Typically provided by the actual upstream project,
 297 and often tracked by Debian contributors in a branch C<upstream>.
 298
 299 =item Upstream files
 300
 301 Files in the source tree outside B<debian/>.
 302 These may include unmodified source from upstream,
 303 but also files which have been modified or created for Debian.
 304
 305 =back
 306
 307 =head1 APPENDIX - DGIT IMPORT HANDLING
 308
 309 Consider a non-dgit NMU followed by a dgit NMU:
 310
 311             interchange --/--B3!--%--/----D*-->
 312                          /          /
 313                         %          4
 314                        /          3
 315                       /          2
 316                      /          1
 317                     2*         &_
 318                    /          /| \
 319                   1          0 00 =XBC%
 320                  /
 321                 /
 322           --@--A     breakwater
 323            /
 324         --#--------> upstream
 325
 326
 327  Key:
 328
 329     =XBC%     dgit tarball import of .debian.tar.gz containing
 330               Debian packaging including changes B C and patches
 331
 332     0         dgit tarball import of upstream tarball
 333     00        dgit tarball import of supplementary upstream tarball
 334     &_        dgit nearly-breakwater import
 335     &'        git-debrebase converted import (upstream files only)
 336     D'        git-debrebase converted debian/ changes import
 337
 338     * **      before and after HEAD
 339
 340 We want to transform this into:
 341
 342  I. No new upstream version (0 + 00 eq #)
 343
 344                         --/--B3!--%--/------D*-------------/-->
 345                          /          /                     /
 346                         %          4                     4**
 347                        /          3                     3
 348                       /          2                     2
 349                      /          1                     1
 350                     2*         &_                    /
 351                    /          /| \                  /
 352                   1          0 00 =XBC%            /
 353                  /                                /
 354                 /                                /
 355           --@--A-----B-----------------------C--D
 356            /
 357         --#----------------------------------------->
 358
 359
 360  II. New upstream (0 + 00 neq #)
 361
 362                         --/--B3!--%--/------D*-------------/-->
 363                          /          /                     /
 364                         %          4                     4**
 365                        /          3                     3
 366                       /          2                     2
 367                      /          1                     1
 368                     2*         &_                    /
 369                    /          /| \                  /
 370                   1          0 00 =XBC%            /
 371                  /                                /
 372                 /                                /
 373           --@--A-----B--------------------@--C--D
 374            /                             /
 375         --#----------------------- - -  /  - - ----->
 376                                        /
 377                                       &'
 378                                      /|
 379                                     0 00
 380
 381 =head1 SEE ALSO
 382
 383 dgit(1), dgit(7), dgit-maint-*(7)