# usages:
#
-# git-debrebase [<options>] new-upstream-v0 \
-# <new-version> [<orig-commitish> \
-# [<extra-orig-name> <extra-orig-commitish> ...] \
-# [<git-rebase options>...]]
-#
-# git-debrebase [<options> --] [<git-rebase options...>]
# git-debrebase [<options>] analyse
-# git-debrebase [<options>] breakwater # prints breakwater tip only
-# git-debrebase [<options>] stitch [--prose=<for commit message>]
# git-debrebase [<options>] launder-v0 # prints breakwater tip etc.
# git-debrebase [<options>] downstream-rebase-launder-v0 # experimental
-#
-# git-debrebase [<options>] convert-from-gbp [<upstream-git-rev>]
-# git-debrebase [<options>] convert-to-gbp
# problems / outstanding questions:
#
# multi-orig upstreams are represented with an anchor merge
# from a single upstream commit which combines the orig tarballs
+ # Every anchor tagged this way must be a merge.
+ # We are relying on the
+ # [git-debrebase anchor: ...]
+ # commit message annotation in "declare" anchor merges (which
+ # do not have any upstream changes), to distinguish those
+ # anchor 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 an anchor commit.
+ # git-rebase trips up on merges, so that is a useful safety
+ # catch.
+ #
+ # BreakwaterStart commits are also anchors in the terminology
+ # of git-debrebase(5), but they are untagged (and always
+ # manually generated).
+
my $badanchor = sub { $unknown->("git-debrebase \`anchor' but @_"); };
@p == 2 or return $badanchor->("has other than two parents");
$haspatches and return $badanchor->("contains debian/patches");