git-debrebase: maintain debrebase-last

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

diff --git a/git-debrebase.5.pod b/git-debrebase.5.pod
index 6d61baad9fd0ebb471157314b957d01dc3de9b97..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,7 +358,7 @@ 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