git-debrebase(5): All of README now in (5)

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

diff --git a/git-debrebase.5.pod b/git-debrebase.5.pod
index f207c954f16e579e57594b8b47d806d50342b975..ce982369c3132af1110e2d6d4f62b104659403c0 100644 (file)
--- a/git-debrebase.5.pod
+++ b/git-debrebase.5.pod
@@ -34,7 +34,7 @@ provided by your upstream.
             /        /          /
            2*       2*         2
           /        /          /
             /        /          /
            2*       2*         2
           /        /          /

-         1        1          1    `breakwater' branch, merging baseline
+         1        1          1    breakwater branch, merging baseline

         /        /          /     unmodified upstream code
     ---@-----@--A----@--B--C      plus debian/ (but no debian/patches)
       /     /       /                    no ref refers to this: we
         /        /          /     unmodified upstream code
     ---@-----@--A----@--B--C      plus debian/ (but no debian/patches)
       /     /       /                    no ref refers to this: we


@@ -59,8 +59,7 @@ provided by your upstream.
       *       Maintainer's HEAD was here while they were editing,
               before they said they were done, at which point their
               tools generated [% and] -/- commit[s] to convert to
       *       Maintainer's HEAD was here while they were editing,
               before they said they were done, at which point their
               tools generated [% and] -/- commit[s] to convert to

-              the fast-forwarding interchange branch.  (Maybe the
-              tooling is simply `dgit push'.)
+              the fast-forwarding interchange branch.

 
       !       NMUer's HEAD was here when they said `dgit push'.
               Rebase branch launderer turns each ! into an
 
       !       NMUer's HEAD was here when they said `dgit push'.
               Rebase branch launderer turns each ! into an


@@ -270,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


@@ -304,6 +365,88 @@ but also files which have been modified or created for Debian.
 
 =back
 
 
 =back
 

+=head1 APPENDIX - DGIT IMPORT HANDLING
+
+Consider a non-dgit NMU followed by a dgit NMU:
+
+            interchange --/--B3!--%--/----D*-->
+                         /          /
+                        %          4
+                       /          3
+                      /          2
+                     /          1
+                    2*         &_
+                   /          /| \
+                  1          0 00 =XBC%
+                 /
+                /
+                 --@--A     breakwater
+          /
+       --#--------> upstream
+
+
+ Key:
+
+    =XBC%     dgit tarball import of .debian.tar.gz containing
+              Debian packaging including changes B C and patches
+
+    0         dgit tarball import of upstream tarball
+    00        dgit tarball import of supplementary upstream tarball
+    &_        dgit nearly-breakwater import
+    &'        git-debrebase converted import (upstream files only)
+    D'        git-debrebase converted debian/ changes import
+
+    * **      before and after HEAD
+
+We want to transform this into:
+
+=over
+
+=item I. No new upstream version
+
+ (0 + 00 eq #)
+                        --/--B3!--%--/------D*-------------/-->
+                         /          /                    /
+                        %          4                    4**
+                       /          3                    3
+                      /          2                    2
+                     /          1                    1
+                    2*         &_                   /
+                   /          /| \                 /
+                  1          0 00 =XBC%            /
+                 /                                       /
+                /                                       /
+         --@--A-----B-----------------------C--D
+          /
+       --#----------------------------------------->
+
+=item II. New upstream
+
+ (0 + 00 neq #)
+
+                        --/--B3!--%--/------D*-------------/-->
+                         /          /                    /
+                        %          4                    4**
+                       /          3                    3
+                      /          2                    2
+                     /          1                    1
+                    2*         &_                   /
+                   /          /| \                 /
+                  1          0 00 =XBC%            /
+                 /                               /
+                /                               /
+         --@--A-----B--------------------@--C--D
+          /                             /
+       --#----------------------- - -  /  - - ----->
+                                      /
+                                     &'
+                                    /|
+                                   0 00
+
+=back
+

 =head1 SEE ALSO
 
 =head1 SEE ALSO
 

-dgit(1), dgit(7), dgit-maint-*(7)
+git-debrebase(1),
+dgit-maint-rebase(7),
+dgit(1)