NOTES.git-debrebase

   1 TODO
   2    reference docs
   3       git-debrebase(5)   data model
   4       git-debrebase(1)   command line
   5    tutorial
   6       dgit-maint-debrebase(7)
   7       someone should set branch.<name>.mergeOptions to include --ff-only ?
   8
   9    clean up remains of NOTES and README
  10
  11    arrange for dgit to automatically stitch on push
  12
  13 ========================================
  14
  15 #  refs/ffq-prev/REF    relates to refs/REF
  16
  17 =======================================
  18
  19 special commit tags
  20 overall format
  21   [git-debrebase[ COMMIT-TYPE [ ARGS...]]: PROSE, MORE PROSE]
  22
  23 [git-debrebase: split mixed commit, debian part]
  24 [git-debrebase: split mixed commit, upstream-part]
  25 [git-debrebase: convert dgit import, debian changes]
  26 [git-debrebase anchor: convert dgit import, upstream changes]
  27
  28 [git-debrebase upstream-combine . PIECE[ PIECE...]: new upstream]
  29 [git-debrebase anchor: new upstream NEW-UPSTREAM-VERSION, merge]
  30 [git-debrebase: new upstream NEW-UPSTREAM-VERSION, changelog]
  31
  32 [git-debrebase convert-from-gbp: drop patches]
  33 [git-debrebase anchor: declare upstream]
  34 [git-debrebase pseudomerge: stitch]
  35
  36 [git-debrebase convert-to-gbp: commit patches]
  37
  38 m{^\[git-debrebase (?:\w*-)?upstream combine \.((?: $extra_orig_namepart_re)+)\]}
  39
  40 Every anchor commit must be a merge.  In principle, this is not
  41 necessary.  After all, we are relying on the
  42     [git-debrebase anchor: ...]
  43 commit message annotation in "declare" anchor merges (which
  44 do not have any upstream changes), to distinguish those anchor
  45 merges from ordinary pseudomerges (which we might just try to strip).
  46
  47 However, the user is going to be doing git-rebase a lot.  We really
  48 don't want them to rewrite an anchor commit.  git-rebase
  49 trips up on merges, so that is a useful safety catch.
  50
  51 =======================================
  52
  53 workflow
  54
  55   git-debrebase blah [implies start]       strips pseudomerge(s)
  56
  57   commit / git-debrebase / etc.
  58
  59   dgit --damp-run push
  60       hook: call git-debrebase prep-push   dgit push does not update remote
  61       or something, must add patches at least
  62
  63   commit / git-debrebase / etc.            strips patches
  64
  65   dgit push
  66       hook: call git-debrebase prep-push   dgit push DOES update remote
  67
  68   commit / git-debrebase / etc.            strips last pm, but arranges
  69                                            that remade pm will incorporate it
  70
  71 ========================================
  72
  73 Theory for ffq-prev
  74
  75 When we strip a pm, we need to maybe record it (or something) as the
  76 new start point.
  77
  78 When we do a thing
  79
  80     with no recorded ffq-prev
  81
  82         ffq-prev is our current tip
  83
  84         obviously it is safe to say we will overwrite this
  85         we do check whether there are not-included changes in the remotes
  86         because if the new ffq-prev is not ff from the remotes
  87         the later pushes will fail
  88
  89         this model tends to keep ad-hoc commits made on our
  90         tip branch before we did rebase start, in the
  91         `interchange view' and also in the rebase stack.
  92
  93         also we can explicitly preserve with
  94         git-debrebase stitch
  95
  96         It is always safe to rewind ffq-prev: all
  97         that does is overwrite _less_ stuff.
  98
  99         in any case putative ffq-prev must be ff from remote.
 100         Otherwise when we push it will not be ff, even though we have
 101         made pseudomerge to overwrite ffq-prev.  So if we spot
 102         this, report an error.  see above
 103
 104     with a recorded ffq-prev
 105
 106         we may need to advance ffq-prev, to allow us to generate
 107         future pseudomerges that will be pushable
 108
 109         advancing ffq-prev is dangerous, since it might
 110         effectively cancel the commits that will-ovewrite is advanced
 111         over.
 112
 113         ??? advance it to merge-base( current remote, current tip )
 114         if possible (see above), - ie to current remote, subject
 115         to the condition that that is an ancestor of current tip
 116
 117         currently this is not implemented
 118
 119         better maybe to detect divergence ?  but it is rather late
 120         by then!
 121
 122 We check we are ff from remotes before recording new ffq-prev
 123
 124   ---------- now follows much the same info in different words ----------
 125
 126 1. git-debrebase [-i etc.]
 127
 128      should:
 129         check for ffq-prev
 130         if is already a ffq-prev, fine, do no more
 131         if not:
 132
 133         check our origin branch exists and we are ff from it
 134         if not fail
 135
 136         check our other might-be-pushed to branches
 137         check we are ff from them
 138         if not fail
 139
 140         set ffq-prev to something which is ff from
 141           all above branches
 142
 143         we use our tip, as discussed above
 144         (optionally, can use some other commit which is ff
 145          from all of the above, eg one of them)
 146
 147 N. git-debrebase [--noop-ok] record-ffq-prev
 148
 149      does what is described above
 150
 151 2. git-debrebase [--noop-ok] stitch
 152
 153     makes pseudomerge with ffq-prev
 154     deletes ffq-prev
 155
 156     we will teach dgit to do
 157        git-debrebase stitch
 158
 159 3. git-debrebase push
 160
 161     like git push only does stitch first
 162     ??? command line parsing!
 163
 164 4. git-debrebase release
 165
 166     stiches, finalises changelog, signs tags, pushes everything
 167     for the future, when there is some automatic builder
 168
 169 ffq-prev for each ref
 170     refs/heads/FOO
 171 is
 172     refs/ffq-prev/FOO
 173
 174 ========================================
 175
 176 import from gbp
 177
 178 what about dgit view branch ?
 179 ideally, would make pseudomerge over dgit view
 180 would need to check that dgit view is actually dgit view of
 181   ond of our ancestors
 182 failing that first push will need --overwrite
 183 that is what is currently implemented
 184
 185 ========================================
 186
 187 how to handle divergence and merges (if not detected soon enough)
 188
 189 same problem
 190  if merge, look at branches before merge
 191  generate new combined branch
 192  pseudomerge to overwrite merge
 193
 194 current avaiable strategies:
 195
 196  maybe launder foreign branch
 197
 198  if foreign branch is nmuish, can rebase it onto ours
 199
 200  could merge breakwaters (use analyse to find them)
 201  merge breakwaters (assuming same upstream)
 202  manually construct new patch queue by inspection of
 203   the other two patch queues
 204
 205  instead of manually constructing patch queue, could use
 206   gbp pq export and git merge the patch queues
 207   (ie work with interdiffs)
 208
 209  if upstreams are different and one is ahead
 210   simply treat that as "ours" and
 211   do the work to import changes from the other
 212
 213  if upstreams have diverged, can
 214   resolve somehow to make new upstream
 215   do new-upstream on each branch separately
 216   now reduced to previously "solved" problem
 217
 218  in future, auto patch queue merge algorithm
 219   determine next patch to apply
 220   there are three versions o..O, l..L, r..R
 221   we have already constructed m (previous patch or merged breakwater)
 222   try using vector calculus in the implied cube and compute
 223    multiple ways to check consistency ?
 224
 225 ========================================
 226
 227 #    git-ffqrebase start [BASE]
 228 #                # records previous HEAD so it can be overwritten
 229 #                # records base for future git-ffqrebase
 230 #    git-ffqrebase set-base BASE
 231 #    git-ffqrebase <git-rebase options>
 232 #    git-ffqrebase finish
 233 #    git-ffqrebase status [BRANCH]