git-debrebase(5): Document commit message annotations

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

3 files changed, 53 insertions, 36 deletions

diff --git a/NOTES.git-debrebase b/NOTES.git-debrebase
index 09237d5..508d590 100644
--- a/NOTES.git-debrebase
+++ b/NOTES.git-debrebase
@@ -10,42 +10,6 @@ TODO
 
    arrange for dgit to automatically stitch on push
 
-=======================================
-
-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 anchor: convert dgit import, upstream changes]
-
-[git-debrebase upstream-combine . PIECE[ PIECE...]: new upstream]
-[git-debrebase anchor: new upstream NEW-UPSTREAM-VERSION, merge]
-[git-debrebase: new upstream NEW-UPSTREAM-VERSION, changelog]
-
-[git-debrebase convert-from-gbp: drop patches]
-[git-debrebase anchor: declare upstream]
-[git-debrebase pseudomerge: stitch]
-
-[git-debrebase convert-to-gbp: commit patches]
-
-m{^\[git-debrebase (?:\w*-)?upstream combine \.((?: $extra_orig_namepart_re)+)\]}
-
-Every anchor commit must be a merge.  In principle, this is not
-necessary.  After all, 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.
-
-=======================================
-
 workflow
 
   git-debrebase blah [implies start]       strips pseudomerge(s)
diff --git a/git-debrebase b/git-debrebase
index cdd6348..5b2312d 100755
--- a/git-debrebase
+++ b/git-debrebase
@@ -438,6 +438,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");
diff --git a/git-debrebase.5.pod b/git-debrebase.5.pod
index 6fc1ae5..6d61baa 100644
--- a/git-debrebase.5.pod
+++ b/git-debrebase.5.pod
@@ -352,6 +352,42 @@ in B<debian/patches/>.
 
 =back
 
+=head1 COMMIT MESSAGE ANNOTATIONS
+
+git-debrebase makes annotations
+in the messages of commits it generates.
+
+The general form is
+
+  [git-debrebase[ COMMIT-TYPE [ ARGS...]]: PROSE, MORE PROSE]
+
+git-debrebase does not pay attention to anything after the colon,
+so PROSE is ignored.
+
+The full set of annotations is:
+  [git-debrebase: split mixed commit, debian part]
+  [git-debrebase: split mixed commit, upstream-part]
+  [git-debrebase: convert dgit import, debian changes]
+  [git-debrebase anchor: convert dgit import, upstream changes]
+
+  [git-debrebase upstream-combine . PIECE[ PIECE...]: new upstream]
+  [git-debrebase anchor: new upstream NEW-UPSTREAM-VERSION, merge]
+  [git-debrebase: new upstream NEW-UPSTREAM-VERSION, changelog]
+
+  [git-debrebase convert-from-gbp: drop patches]
+  [git-debrebase anchor: declare upstream]
+  [git-debrebase pseudomerge: stitch]
+
+  [git-debrebase convert-to-gbp: commit patches]
+
+Only anchor merges have the C<[git-debrebase anchor: ...]> tag.
+Single-parent anchors are not generated by git-debrebase,
+and when made manually should not be tagged.
+
+The C<split mixed commit> and C<convert dgit import>
+tags are added to the pre-existing commit message,
+when git-debrebase rewrites the commit.
+
 =head1 TERMINOLOGY
 
 =over