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.
 
+=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