From b822b6c13035de35290d03c497fdbd72560e3d34 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Sun, 18 Feb 2018 22:46:58 +0000 Subject: [PATCH] git-debrebase(5): Document commit message annotations Signed-off-by: Ian Jackson --- NOTES.git-debrebase | 36 ------------------------------------ git-debrebase | 17 +++++++++++++++++ git-debrebase.5.pod | 36 ++++++++++++++++++++++++++++++++++++ 3 files changed, 53 insertions(+), 36 deletions(-) diff --git a/NOTES.git-debrebase b/NOTES.git-debrebase index 09237d59..508d590c 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 cdd6348a..5b2312d8 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 6fc1ae54..6d61baad 100644 --- a/git-debrebase.5.pod +++ b/git-debrebase.5.pod @@ -352,6 +352,42 @@ in B. =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 and C +tags are added to the pre-existing commit message, +when git-debrebase rewrites the commit. + =head1 TERMINOLOGY =over -- 2.30.2