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