git-debrebase(5): more from README

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

diff --git a/README.git-debrebase b/README.git-debrebase
index 49fae981d8520be7f987c77b5ad15afd86beb2d2..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 100644 (file)
--- a/README.git-debrebase
+++ b/README.git-debrebase
@@ -1,32 +0,0 @@
-
-
-So it would be possible to write a `git-debrebase' tool which would
-take (for example) B4, above, and be able to perform functions like:
-
- * Strip pseudomerges: Rewrite the current branch so it contains no
-   pseudomerges, turning ...B3 into ...@-A-1-2-B3.  (This should
-   make a note, in your .git/ somewhere, of the original branch
-   tip so that it can be overwritten with a pseudomerge.)
-
- * Cleanup branch: Reorganise the current branch so that the debian/
-   changes come first, turning -@-A-1-2-B3 into ...@-A-B-1-2-3.
-
- * New upstream rebase: Start rebasing onto a new upstream version,
-   turning ...#..@-A-B-1-2-3 into (...#..@-A-B-|...#'-)@'-1-2.  This
-   would be a wrapper around git-rebase, which prepares @' and then
-   tries to rebase 1 2 onto @'.  So if you ask for an interactive
-   rebase @' doesn't appear in your commit list.
-
-   Note that the construction of @' cannot fail because @' simply
-   copies debian/ from B and and everything else from #'.  (Rebasing A
-   and B is undesirable.  We want the debian/ files to be non-rebasing
-   so we can `git log' and get the packaging history.)
-
- * Record pseudomerge.  This is like "committing" your patch queue.
-   The LH parent is taken from the previously recorded tip.  (We could
-   perhaps check that this is consistent with what we see in
-   debian/changelog, but that is not a sufficient check so the
-   recorded tip check is primary.)
-
-Maybe some of these operations should automatically edit
-debian/changelog.

diff --git a/git-debrebase.5.pod b/git-debrebase.5.pod
index 1c73ea3a15990a401d1f0097f14cd48fa71dd94e..ce982369c3132af1110e2d6d4f62b104659403c0 100644 (file)
--- a/git-debrebase.5.pod
+++ b/git-debrebase.5.pod
@@ -269,6 +269,68 @@ We use the commit message annotation to
 distinguish the special anchor merges from other general merges,
 so we can at least detect unsupported merges.
 
 distinguish the special anchor merges from other general merges,
 so we can at least detect unsupported merges.
 

+=head1 LEGAL OPERATIONS
+
+The following basic operations follows from this model
+(refer to the diagram above):
+
+=over
+
+=item Append linear commits
+
+No matter the branch state,
+it is always fine to simply git commit
+(or cherry-pick etc.)
+commits containing upstream file changes, packaging changes,
+or both.
+
+=item Launder branch
+
+Record the previous tip in ffq-prev,
+if we were stitched before.
+
+Reorganise the current branch so that the debian/
+changes come first,
+turning C<-@-A-1-2-B3> into C<...@-A-B-1-2-3>.
+
+Drop pseudomerges and any quilt patches.
+
+=item Interactive rebase
+
+With a laundered branch,
+one can do an interactive git rebase of the delta queue.
+
+=item New upstream rebase
+
+Start rebasing onto a new upstream version,
+turning C<...#..@-A-B-1-2-3> into C<(...#..@-A-B-|...#'-)@'-1-2>.
+
+This has to be a wrapper around git-rebase,
+which prepares @' and then tries to rebase 1 2 onto @'.
+If the user asks for an interactive rebase,
+@' doesn't appear in thec ommit list.
+
+Note that the construction of @' cannot fail
+because @' simply copies debian/ from B and and everything else from #'.
+(Rebasing A and B is undesirable.
+We want the debian/ files to be non-rebasing
+so that git log shows the packaging history.)
+
+=item Stitch 
+
+Make a pseudomerge,
+overwriting (and consuming) ffq-prev.
+
+=item Commit patches
+
+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.)
+
+=back
+

 =head1 TERMINOLOGY
 
 =over
 =head1 TERMINOLOGY
 
 =over