X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=git-debrebase;h=75a8f51a96b1638bd6d4847c0b6f721bd113a51a;hb=92c9546d19a2e4edf3de98b7487d582237a19ca0;hp=cdd6348a122efc405a6de50d3338d6b1356da12d;hpb=4b9de539daea1c590687fcf144b0f36cc99609ed;p=dgit.git

diff --git a/git-debrebase b/git-debrebase
index cdd6348a..75a8f51a 100755
--- a/git-debrebase
+++ b/git-debrebase
@@ -19,22 +19,9 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 
-# usages:
+# undocumented 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:
 #
@@ -438,6 +425,23 @@ sub classify ($) {
 	# 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");