diff options
author | Ian Jackson <ijackson@chiark.greenend.org.uk> | 2018-02-18 22:46:58 +0000 |
---|---|---|
committer | Ian Jackson <ijackson@chiark.greenend.org.uk> | 2018-06-16 16:06:59 +0100 |
commit | b822b6c13035de35290d03c497fdbd72560e3d34 (patch) | |
tree | e9ef0965444be132fc6d85b2a8c540dcb2ec7d7d | |
parent | 4d17885419daca2127f870a06503ec5643d0f626 (diff) |
git-debrebase(5): Document commit message annotations
Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>
-rw-r--r-- | NOTES.git-debrebase | 36 | ||||
-rwxr-xr-x | git-debrebase | 17 | ||||
-rw-r--r-- | git-debrebase.5.pod | 36 |
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 |