X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=git-debrebase.5.pod;h=ce982369c3132af1110e2d6d4f62b104659403c0;hb=8bce000d9c9af3912aeefe1f3874ce3b125cae04;hp=f207c954f16e579e57594b8b47d806d50342b975;hpb=47e5e2edc83917f5e21e00586a0907c1f641f174;p=dgit.git

diff --git a/git-debrebase.5.pod b/git-debrebase.5.pod
index f207c954..ce982369 100644
--- a/git-debrebase.5.pod
+++ b/git-debrebase.5.pod
@@ -34,7 +34,7 @@ provided by your upstream.
             /        /          /
            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
@@ -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
-              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
@@ -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.
 
+=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
@@ -304,6 +365,88 @@ but also files which have been modified or created for Debian.
 
 =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
 
-dgit(1), dgit(7), dgit-maint-*(7)
+git-debrebase(1),
+dgit-maint-rebase(7),
+dgit(1)