README.git-debrebase

   1
   2
   3 My preferred answer is that it is a constantly rebasing branch topped
   4 with a series of pseudomerges to make it fast-forwarding.
   5
   6            ------/--A!----/--B3!--%--/--> interchange view
   7                 /        /          /      with debian/ directory
   8                %        %          %       all upstream changes applied
   9               /        /          /        3.0 (quilt) has debian/patches
  10              /        /          3*
  11             /        /          /
  12            2*       2*         2
  13           /        /          /
  14          1        1          1    `breakwater' branch, merging baseline
  15         /        /          /     unmodified upstream code
  16     ---p-----p--A----p--B--C-->   plus debian/ (but no debian/patches)
  17       /     /       /
  18    --#-----#-------#-----> upstream
  19
  20     Key:
  21
  22       1,2,3   commits touching upstream files only
  23       A,B,C   commits touching debian/ only
  24       B3      mixed commit (eg made by an NMUer)
  25       #       upstream releases
  26
  27      -p-      special merge, takes contents of debian/ from the
  28      /         previous `breakwater' commit and rest from upstream
  29
  30      -/-      pseudomerge; contents are identical to
  31      /         parent lower on diagram.
  32
  33       %       dgit-generated commit of debian/patches.
  34               `3.0 (quilt)' only; dropped by rebase tool.
  35
  36       *       Maintainer's HEAD was here while they were editing,
  37               before they said they were done, at which point their
  38               tools generated [% and] -/- commit[s] to convert to
  39               the fast-forwarding interchange branch.  (Maybe the
  40               tooling is simply `dgit push'.)
  41
  42       !       NMUer's HEAD was here when they said `dgit push'.
  43               Rebase branch launderer turns each ! into an
  44               equivalent *.
  45
  46
  47 Looking from the tip of the interchange view, it is I think always
  48 possible to classify these commits appropriately: pseudomerges are
  49 fairly obvious (if all three trees are identical, we descend to the
  50 parent with the most recent commit date), and the `p' special merge is
  51 the only non-pseudo merge and has a special form.
  52
  53 So it would be possible to write a `git-debrebase' tool which would
  54 take (for example) B4, above, and be able to perform functions like:
  55
  56  * Strip pseudomerges: Rewrite the current branch so it contains no
  57    pseudomerges, turning ...B3 into ...p-A-1-2-B3.  (This should
  58    make a note, in your .git/ somewhere, of the latest pseudomerge to
  59    be deleted.)
  60
  61  * Cleanup branch: Reorganise the current branch so that the debian/
  62    changes come first, turning -p-A-1-2-B3 into ...p-A-B-1-2-3.
  63
  64  * New upstream rebase: Start rebasing onto a new upstream version,
  65    turning ...#...p-A-B-1-2-3 into ...#'.A-B-p'-1-2.  This would be a
  66    wrapper around git-rebase, which prepares p' and then tries to
  67    rebase 1 2 onto p'.  So if you ask for an interactive rebase p'
  68    doesn't appear in your commit list.
  69
  70    Note that the rebasing of p into p' cannot fail because p' simply
  71    copies debian/ from B and and everything else from #'.  (Rebasing A
  72    and B is undesirable.  We want the debian/ files to be non-rebasing
  73    so we can `git log' and get the packaging history.)
  74
  75  * Record pseudomerge.  This is like "committing" your patch queue.
  76    The LH parent is taken from the previous strip pseudomerge.  (We
  77    should probably check that this is consistent with what we see in
  78    debian/changelog, but that is not a sufficient check.)
  79
  80 Maybe some of these operations should automatically edit
  81 debian/changelog.
  82
  83 The only thing that this can't easily do is permit nonlinear (ie,
  84 merging) history on the `packaging-only' branch, because upstream
  85 might contain debian/ files too, so it is not possible to distinguish
  86 a merge of two `packaging-only' branches from the special merge `p'.
  87 (Indeed I since upstream might copy debian/ from us, I think it is not
  88 easy to reliably distinguish the two parents of a `p'.  In the most
  89 exciting edge case, upstream might `git merge' a previous instance of
  90 our interchange view, but I think even then everything still works.)
  91
  92 Sean Whitton writes ("Re: Feedback on 3.0 source format problems"):
  93 >  Does the [breakwater] branch contain debian/ alone?
  94
  95 No, it also contains a complete unmodified copy of the upstream code.
  96 (Except that if upstream had a debian/ directory, it is completely
  97 replaced.)
  98
  99 For `3.0 (quilt)' the breakwater branch contains roughly what you
 100 would get if you untarred the origs and the debian.tar.gz, and then
 101 deleted all the patches without applying them.
 102
 103
 104
 105 Consider a non-dgit NMU followed by a dgit NMU:
 106
 107
 108
 109             interchange --/--B3!--%--/----E--->
 110                          /          /
 111                         %          4
 112                        /          3
 113                       /          2
 114                      /          1
 115                     2*         &_
 116                    /          /| \
 117                   1          0 00 =XBCD
 118                  /
 119                 /
 120           --p--A---> breakwater
 121            /
 122         --#--------> upstream
 123
 124
 125  Key:
 126
 127     =XBC%     dgit tarball import of .debian.tar.gz containing
 128               Debian packaging including changes B C and patches
 129
 130     0         dgit tarball import of upstream tarball
 131
 132     00        dgit tarball import of supplementary upstream tarball
 133
 134     &_        dgit nearly-breakwater import
 135
 136     &'        git-debrebase converted import
 137
 138     D'        git-debrebase converted debian/ changes import
 139
 140 Want to transform this into:
 141
 142  I. No new upstream version (0 + 00 eq #)
 143
 144                         --/--B3!--%--/------D--------------/-->
 145                          /          /                     /
 146                         %          4                     4
 147                        /          3                     3
 148                       /          2                     2
 149                      /          1                     1
 150                     2*         &_                    /
 151                    /          /| \                  /
 152                   1          0 00 =XBC%            /
 153                  /                                /
 154                 /                                /
 155           --p--A-----B-----------------------C--D--->
 156            /
 157         --#----------------------------------------->
 158
 159
 160  II. New upstream (0 + 00 neq #)
 161
 162                                   interchange
 163
 164                         --/--B3!--%--/------E--------------/-->
 165                          /          /                     /
 166                         %          4                     4
 167                        /          3                     3
 168                       /          2                     2
 169                      /          1                     1
 170                     2*         &_                    /
 171                    /          /| \                  /
 172                   1          0 00 =XBC%            /
 173                  /                                /
 174                 /                                /
 175           --p--A-----B--------------------p--C--D--->
 176            /                             /
 177         --#----------------------- - -  /  - - ----->
 178                                        /
 179                                       &'
 180                                      /|
 181                                     0 00