chiark / gitweb /
git-debrebase: bomb on totally ambiguous pseudomerges
[dgit.git] / README.git-debrebase
index cf00345..9efdc1a 100644 (file)
@@ -13,10 +13,10 @@ with a series of pseudomerges to make it fast-forwarding.
           /        /          /
          1        1          1    `breakwater' branch, merging baseline
         /        /          /     unmodified upstream code
-    ---p-----p--A----p--B--C-->   plus debian/ (but no debian/patches)
-      /     /       /
-   --#-----#-------#-----> upstream
-
+    ---p-----p--A----p--B--C      plus debian/ (but no debian/patches)
+      /     /       /                    no ref refers to this: we
+   --#-----#-------#-----> upstream        reconstruct its identity by
+                                          inspecting interchange branch
     Key:
 
       1,2,3   commits touching upstream files only
@@ -55,27 +55,28 @@ 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 ...p-A-1-2-B3.  (This should
-   make a note, in your .git/ somewhere, of the latest pseudomerge to
-   be deleted.)
+   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 -p-A-1-2-B3 into ...p-A-B-1-2-3.
 
  * New upstream rebase: Start rebasing onto a new upstream version,
-   turning ...#...p-A-B-1-2-3 into ...#'.A-B-p'-1-2.  This would be a
-   wrapper around git-rebase, which prepares p' and then tries to
-   rebase 1 2 onto p'.  So if you ask for an interactive rebase p'
-   doesn't appear in your commit list.
+   turning ...#..p-A-B-1-2-3 into (...#..p-A-B-|...#'-)p'-1-2.  This
+   would be a wrapper around git-rebase, which prepares p' and then
+   tries to rebase 1 2 onto p'.  So if you ask for an interactive
+   rebase p' doesn't appear in your commit list.
 
-   Note that the rebasing of p into p' cannot fail because p' simply
+   Note that the construction of p' cannot fail because p' 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 previous strip pseudomerge.  (We
-   should probably check that this is consistent with what we see in
-   debian/changelog, but that is not a sufficient check.)
+   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.
@@ -101,79 +102,77 @@ would get if you untarred the origs and the debian.tar.gz, and then
 deleted all the patches without applying them.
 
 
+dgit import handling
+--------------------
 
 Consider a non-dgit NMU followed by a dgit NMU:
-                                              
-                                 
-                                              
-            interchange --/--B3!--%--/----E--->
-                         /          /         
-                        %          4          
-                       /          3           
-                      /          2            
-                     /          1             
-                    2*         &_             
-                   /          /| \            
-                  1          0 00 =XBCD               
-                 /                                    
-                /                                     
-                 --p--A---> breakwater
-          /                   
+
+
+
+            interchange --/--B3!--%--/----D*-->
+                         /          /
+                        %          4
+                       /          3
+                      /          2
+                     /          1
+                    2*         &_
+                   /          /| \
+                  1          0 00 =XBC%
+                 /
+                /
+                 --p--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            
-                                                                 
+
+
+ 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                             
-                                                                 
-    D'        git-debrebase converted debian/ changes import     
-                                                                 
-Want to transform this into:                                     
-                                                                 
- I. No new upstream version (0 + 00 eq #)                               
-                                                                 
-                        --/--B3!--%--/------D--------------/-->          
-                         /          /                    /       
-                        %          4                    4        
-                       /          3                    3         
-                      /          2                    2          
-                     /          1                    1           
-                    2*         &_                   /            
-                   /          /| \                 /             
-                  1          0 00 =XBC%            /                    
-                 /                                       /                    
-                /                                       /             
-         --p--A-----B-----------------------C--D--->     
-          /                                         
+    &_        dgit nearly-breakwater import
+    &'        git-debrebase converted import (upstream files only)
+    D'        git-debrebase converted debian/ changes import
+
+    * **      before and after HEAD
+
+Want to transform this into:
+
+ I. No new upstream version (0 + 00 eq #)
+
+                        --/--B3!--%--/------D*-------------/-->
+                         /          /                    /
+                        %          4                    4**
+                       /          3                    3
+                      /          2                    2
+                     /          1                    1
+                    2*         &_                   /
+                   /          /| \                 /
+                  1          0 00 =XBC%            /
+                 /                                       /
+                /                                       /
+         --p--A-----B-----------------------C--D
+          /
        --#----------------------------------------->
-                                              
-                                            
- II. New upstream (0 + 00 neq #)                 
-                                                                 
-                                 interchange                     
-                                                                 
-                        --/--B3!--%--/------E--------------/-->          
-                         /          /                    /       
-                        %          4                    4        
-                       /          3                    3         
-                      /          2                    2          
-                     /          1                    1           
-                    2*         &_                   /            
-                   /          /| \                 /             
-                  1          0 00 =XBC%            /           
-                 /                               /                    
-                /                               /             
-         --p--A-----B--------------------p--C--D--->     
-          /                             /           
+
+
+ II. New upstream (0 + 00 neq #)
+
+                        --/--B3!--%--/------D*-------------/-->
+                         /          /                    /
+                        %          4                    4**
+                       /          3                    3
+                      /          2                    2
+                     /          1                    1
+                    2*         &_                   /
+                   /          /| \                 /
+                  1          0 00 =XBC%            /
+                 /                               /
+                /                               /
+         --p--A-----B--------------------p--C--D
+          /                             /
        --#----------------------- - -  /  - - ----->
                                       /
                                      &'