=========
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 convert dgit import: upstream changes]
+[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 new-upstream combine . [PIECES...]]
-[git-debrebase new-upstream breakwater NEW-UPSTREAM-VERSION]
-[git-debrebase new-upstream changelog NEW-UPSTREAM-VERSION]
+[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 gbp2debrebase drop-patches]
-[git-debrebase declare-upstream breakwater]
+[git-debrebase: gbp2debrebase, drop patches]
+[git-debrebase breakwater: declare upstream]
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
========================================
+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)
+
+2. git-debrebase stitch
+
+ makes pseudomerge with will-overwrite
+ deletes will-overwrite
+
+3. git-debrebase push
+
+ like git push only does stitch first
+ ??? command line parsing!
+
+========================================
+
import from gbp
+[ all this is done now:
inputs:
current HEAD (patches-unapplied),
this is going to be the base of the old breakwater
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
+
+should this be called import or gbp2debrebase as it is now ?
+gbp uses "import" oddly but I'm tempted to use it normally here.