git-debrebase: maintain debrebase-last

[dgit.git] / git-debrebase.5.pod

diff --git a/git-debrebase.5.pod b/git-debrebase.5.pod
index 6fc1ae54962b3495e239d352f304bb008146a416..dce648e84a5135475edc5267c8ec3701b064e19f 100644 (file)
--- a/git-debrebase.5.pod
+++ b/git-debrebase.5.pod
@@ -229,16 +229,16 @@ when it imports .dsc-based uploads.
 =head1 STITCHING, PSEUDO-MERGES, FFQ RECORD
 
 Whenever the branch C<refs/B> is unstitched,
-the previous tip is recorded in the git ref C<refs/ffq-prev/heads/B>.
+the previous tip is recorded in the git ref C<refs/ffq-prev/B>.
 
 Unstiched branches are not fast forward from the published
-interchange branches. [1]
+interchange branches [1].
 So before a branch can be pushed,
 the right pseudomerge must be reestablished.
 This is the stitch operation,
 which consumes the ffq-prev ref.
 
-When the user has an unstituched branch,
+When the user has an unstitched branch,
 they may rewrite it freely,
 from the breakwater tip onwards.
 Such a git rebase is the default operation for git-debrebase.
@@ -257,6 +257,12 @@ the interchange and breakwater branches may be identical,
 in which case the unstitched branch is fast forward
 from the interchange branch and no pseudomerge is needed.
 
+When ffq-prev is not present,
+C<refs/debrebase-last/B> records some ancestor of refs/B,
+(usually, the result of last stitch).
+This can be used to quickly determine whether refs/B
+is being maintained in git-debrebase form.
+
 =head1 OTHER MERGES
 
 Note that the representation described here does not permit
@@ -299,10 +305,13 @@ it is always fine to simply git commit
 commits containing upstream file changes, packaging changes,
 or both.
 
+(This may make the branch unlaundered.)
+
 =item Launder branch
 
 Record the previous tip in ffq-prev,
-if we were stitched before.
+if we were stitched before
+(and delete debrebase-last).
 
 Reorganise the current branch so that the packaging
 changes come first,
@@ -338,7 +347,8 @@ Make a pseudomerge,
 whose contributing parent to is the unstitched branch
 and
 whose overwritten parent is ffq-prev,
-consuming ffq-prev in the process.
+consuming ffq-prev in the process
+(and writing debrebase-last instead).
 Ideally the contributing parent would be a laundered branch,
 or perhaps a laundered branch with a quilt patch addition commit.
 
@@ -348,10 +358,46 @@ To generate a tree which can be represented as a
 3.0 (quilt) .dsc source packages,
 the delta queue must be reified inside the git tree
 in B<debian/patches/>.
-(These can be stripped out and/or regenerated as needed.)
+These patch files can be stripped out and/or regenerated as needed.
 
 =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