-TODO
- more tests, see "todo" in gdr-editw
- reference docs
- git-debrebase(5) data model
- git-debrebase(1) command line
- tutorial
- dgit-maint-debrebase(7)
- someone should set branch.<name>.mergeOptions to include --ff-only ?
-
- clean up remains of NOTES and README
-
- arrange for dgit to automatically stitch on push
-
-# git-ffqrebase start [BASE]
-# # records previous HEAD so it can be overwritten
-# # records base for future git-ffqrebase
-# git-ffqrebase set-base BASE
-# git-ffqrebase <git-rebase options>
-# git-ffqrebase finish
-# git-ffqrebase status [BRANCH]
+# problems / outstanding questions:
#
-# refs/ffq-prev/REF relates to refs/REF
+# * new-upstream has an awkward UI for multiple upstream pieces.
+# You end up with giant runic command lines. Does this matter /
+# One consequence of the lack of richness it can need -f in
+# fairly sensible situations.
#
-# git-debrebase without start, if already started, is willing
-# to strip pseudomerges provided that they overwrite exactly
-# the previous HEAD
-# xxxx is this right ? what matters is have we pushed
-# I think in fact the right answer is:
-# git-debrebase always strips out pseudomerges from its branch
-# a pseudomerge is put in at the time we want to push
-# at that time, we make a pseudomerge of the remote tracking
-# branch (if raw git) or the dgit view (if dgit)
-# for raw git git-ffqrebase, do want preciseley to record
-# value of remote tracking branch or our branch, on start, so we
-# overwrite only things we intend to
-# the previous pseudomerge check for tags and remote branches ?
-
-
-=========
-
-special commit tags
-overall format
- [git-debrebase[ COMMIT-TYPE [ ARGS...]]: PROSE, MORE PROSE]
-
-[git-debrebase: split mixed commit, debian part]
-[git-debrebase: split mixed commit, upstream-part]
-[git-debrebase: convert dgit import, debian changes]
-[git-debrebase breakwater: convert dgit import, upstream changes]
-
-[git-debrebase upstream-combine . PIECE[ PIECE...]: new upstream]
-[git-debrebase breakwater: new upstream NEW-UPSTREAM-VERSION, merge]
-[git-debrebase: new upstream NEW-UPSTREAM-VERSION, changelog]
-
-[git-debrebase convert-from-gbp: drop patches]
-[git-debrebase breakwater: declare upstream]
-[git-debrebase pseudomerge: stitch]
-
-m{^\[git-debrebase (?:\w*-)?upstream combine \.((?: $extra_orig_namepart_re)+)\]}
-
-Every breakwater commit must be a merge. In principle, this is not
-necessary. After all, we are relying on the
- [git-debrebase breakwater: ...]
-commit message annotation in "declare" breakwater merges (which
-do not have any upstream changes), to distinguish those breakwater
-merges from ordinary pseudomerges (which we might just try to strip).
-
-However, the user is going to be doing git-rebase a lot. We really
-don't want them to rewrite a breakwater base commit. git-rebase
-trips up on merges, so that is a useful safety catch.
-
-
-=========
-
-workflow
-
- git-debrebase blah [implies start] strips pseudomerge(s)
-
- commit / git-debrebase / etc.
+# * There should be a good convention for the version number,
+# and unfinalised or not changelog, after new-upstream.
+#
+# * Handing of multi-orig dgit new-upstream .dsc imports is known to
+# be broken. They may be not recognised, improperly converted, or
+# their conversion may be unrecognised.
+#
+# * We need to develop a plausible model that works for derivatives,
+# who probably want to maintain their stack on top of Debian's.
+# downstream-rebase-launder-v0 may be a starting point?
+# maybe the hypothetical git-ffqrebase is part of it too.
+
- dgit --damp-run push
- hook: call git-debrebase prep-push adds new pm ? passes --overwrite ?
- dgit push does not update remote
+# undocumented usages:
+#
+# git-debrebase [<options>] downstream-rebase-launder-v0 # experimental
- commit / git-debrebase / etc. strips pm(s) including last one
- dgit push
- hook: call git-debrebase prep-push adds new pm ? passes --overwrite ?
- dgit push DOES update remote
+========================================
- commit / git-debrebase / etc. strips last pm, but arranges
- that remade pm will incorporate it
+Theory for ffq-prev
-Aha!
+ refs/ffq-prev/REF relates to refs/REF
When we strip a pm, we need to maybe record it (or something) as the
new start point.
-We do this if the pm is contained within the output branch.
-
-Actually this is not special to PMs.
-
-We need to record a new to-be-overwritten commit
- merge-base( our branch tip, relevant remote )
-
-If this is not a descendant of the relevant remote, then we are going
-to have a problem when we push so issue a warning or fail.
-
-
-
-How about
-
- git-debrebase start or git-debrebase [continue]
-
- with no recorded will-overwrite
-
- putative will-overwrite is
- one model:
- our current tip
- obviously it is safe to say we will overwrite this
- we do not need to worry about whether this will
- overwrite not-included changes in the remote
- because either the will-overwrite is not
- ff from the remote (in which case later failure,
- see below); or the will-overwrite _is_ ff
- from the remote ie our tip is later than the
- remote and includes all of its changes
+When we do a thing
- this model tends to keep ad-hoc commits made on our
- tip branch before we did rebase start, in the
- `interchange view' and also in the rebase stack.
+ with no recorded ffq-prev
- other model:
- merge-base( current remote, current tip )
+ ffq-prev is our current tip
- it is safe to overwrite current tip, by the
- argument above
+ obviously it is safe to say we will overwrite this
+ we do check whether there are not-included changes in the remotes
+ because if the new ffq-prev is not ff from the remotes
+ the later pushes will fail
- it is always safe to rewind will-overwrite: all
- that does is overwrite _less_ stuff
+ this model tends to keep ad-hoc commits made on our
+ tip branch before we did rebase start, in the
+ `interchange view' and also in the rebase stack.
- this is the earliest overwrite we can make that
- will be pushable to the remote
+ also we can explicitly preserve with
+ git-debrebase stitch
- in practical terms this can only be ff from the
- current remote if it is equal to the current remote;
- so what we are actually checking below is that our tip
- is ff from the remote. This ought to be true before
- the first of our rebases.
+ It is always safe to rewind ffq-prev: all
+ that does is overwrite _less_ stuff.
- this model tends to rewind and rebase ad-hoc commits
- made on our tip branch before we did rebase start,
- this is better
-
- in any case putative will-overwrite must be ff from remote.
+ in any case putative ffq-prev must be ff from remote.
Otherwise when we push it will not be ff, even though we have
- made pseudomerge to overwrite will-overwrite. So if we spot
- this, report an error.
+ made pseudomerge to overwrite ffq-prev. So if we spot
+ this, report an error. see above
- with a recorded will-overwrite
+ with a recorded ffq-prev
- we may need to advance will-overwrite, to allow us to generate
+ we may need to advance ffq-prev, to allow us to generate
future pseudomerges that will be pushable
- advancing will-overwrite is dangerous, since it might
+ advancing ffq-prev is dangerous, since it might
effectively cancel the commits that will-ovewrite is advanced
over.
- we advance it to merge-base( current remote, current tip )
+ ??? advance it to merge-base( current remote, current tip )
if possible (see above), - ie to current remote, subject
to the condition that that is an ancestor of current tip
-In each case we can strip pseudomerges freely, as needed. We do not
-want to record what pseudomerges we strip, because whether we need to
-keep them depends (only) on whether they have been pushed.
+ currently this is not implemented
-Is that actually true ? What if the user actually _wanted_ to keep
-the pseudomerge despite not having pushed it ?
+ better maybe to detect divergence ? but it is rather late
+ by then!
-In that case we need to advance will-overwrite past it. We could
-provide an explicit command to do this: it would advance
-will-overwrite to the current tip (see rules above, which show that
-this is OK). Or maybe to the last pseudomerge on the current tip,
-so that the overall result will be series of pseudomerges.
+We check we are ff from remotes before recording new ffq-prev
========================================
-So, pm handling specifics:
-
-strategy is to avoid making needless pseudomerges
-pseudomerges that exist will be preserved
-(by being included in will-overwrite)
-
-This is good because the presence of a pseudomerge means we know we
-want to keep it; and that allows explicit control over history detail
-level.
-
-It does mean we must avoid making the pseudomerges unnecessarily.
-They should be made just before (ideally, part of) dgit push.
-
-1. git-debrebase [-i etc.]
-
- should:
- check for will-overwrite
- if is already a will-overwrite, fine, do no more
- if not:
-
- check our origin branch exists and we are ff from it
- if not fail
-
- check our other might-be-pushed to branches
- check we are ff from them
- if not fail
-
- set will-overwrite to something which is ff from
- all above branches
-
- we use our tip, as discussed above
- (optionally, can use some other commit which is ff
- from all of the above, eg one of them)
-
-N. git-debrebase [--noop-ok] record-ffq-prev
-
- does what is described above
-
-2. git-debrebase [--noop-ok] stitch
-
- makes pseudomerge with will-overwrite
- deletes will-overwrite
-
- we will teach dgit to do
- git-debrebase stitch
-
-3. git-debrebase push
-
- like git push only does stitch first
- ??? command line parsing!
-
-4. git-debrebase release
-
- stiches, finalises changelog, signs tags, pushes everything
- for the future, when there is some automatic builder
-
-will-overwrite for each ref
- refs/heads/FOO
-is
- refs/ffq-prev/FOO
-
-========================================
-
-import from gbp
-
-[ all this is done now:
- inputs:
- current HEAD (patches-unapplied),
- this is going to be the base of the old breakwater
- nominated upstream
-
- checks:
- HEAD:<upstream> = upstream:<upstream>
- upstream..HEAD:<upstream> is empty (overrideable)
- upstremm:debian is empty (overrideable)
-
- procedure:
- construct
- run gbp pq import to generate pq branch
- new breakwater is
- old HEAD
- commit to remove d/patches
- breakwater pseudomerge with upstream
- "rebase" of pq branch, each commit with d/patches stripped
-]
-
-what about dgit view branch ?
-ideally, would make pseudomerge over dgit view
-would need to check that dgit view is actually dgit view of
- ond of our ancestors
-failing that first push will need --overwrite
-
-========================================
-
-divergence, merges:
+how to handle divergence and merges (if not detected soon enough)
same problem
if merge, look at branches before merge
we have already constructed m (previous patch or merged breakwater)
try using vector calculus in the implied cube and compute
multiple ways to check consistency ?
+
+========================================
+
+For downstreams of Debian, sketch of git-ffqrebase
+
+# git-ffqrebase start [BASE]
+# # records previous HEAD so it can be overwritten
+# # records base for future git-ffqrebase
+# git-ffqrebase set-base BASE
+# git-ffqrebase <git-rebase options>
+# git-ffqrebase finish
+# git-ffqrebase status [BRANCH]