dgit: Drop an obsolete xxx comment

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

diff --git a/git-debrebase.5.pod b/git-debrebase.5.pod
index d3ecda88242e2c33b9484426a042708fe14fbd6c..d39ad9484986fb022e98e735a030d91f6e136063 100644 (file)
--- a/git-debrebase.5.pod
+++ b/git-debrebase.5.pod
@@ -15,6 +15,8 @@ as a series of individual git commits,
 which can worked on with rebase,
 and also shared.
 
 which can worked on with rebase,
 and also shared.
 

+=head2 DISCUSSION
+

 git-debrebase is designed to work well with dgit.
 git-debrebase can also be used in workflows without source packages,
 for example to work on Debian-format packages outside or alongside Debian.
 git-debrebase is designed to work well with dgit.
 git-debrebase can also be used in workflows without source packages,
 for example to work on Debian-format packages outside or alongside Debian.


@@ -24,9 +26,14 @@ itself is not very suitable for use by Debian derivatives,
 to work on packages inherited from Debian,
 because it assumes that you want to throw away any packaging
 provided by your upstream.
 to work on packages inherited from Debian,
 because it assumes that you want to throw away any packaging
 provided by your upstream.

-However, of git-debrebase in Debian does not make anything harder for
+However, use of git-debrebase in Debian does not make anything harder for

 derivatives, and it can make some things easier.
 
 derivatives, and it can make some things easier.
 

+When using gitk on branches managed by git-debrebase,
+B<gitk --date-order>, B<gitk --first-parent>
+and B<gitk -- :.> (or B<gitk .>)
+produce more useful output than the default.
+

 =head1 TERMINOLOGY
 
 =over
 =head1 TERMINOLOGY
 
 =over


@@ -80,6 +87,18 @@ Not used, often deleted, and regenerated when needed
 (such as when uploading to Debian),
 by git-debrebase.
 
 (such as when uploading to Debian),
 by git-debrebase.
 

+=item Interchange branch; breakwater; stitched; laundered
+
+See L</BRANCHES AND BRANCH STATES - OVERVIEW>.
+
+=item Anchor; Packaging
+
+See L</BRANCH CONTENTS - DETAILED SPECIFICATION>.
+
+=item ffq-prev; debrebase-last
+
+See L</STITCHING, PSEUDO-MERGES, FFQ RECORD>.
+

 =back
 
 =head1 DIAGRAM
 =back
 
 =head1 DIAGRAM


@@ -95,9 +114,9 @@ by git-debrebase.
          1        1          1    breakwater branch, merging baseline
         /        /          /     unmodified upstream code
     ---@-----@--A----@--B--C      plus debian/ (but no debian/patches)
          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
+      /     /       /                     no ref refers to this: we

    --#-----#-------#-----> upstream        reconstruct its identity by
    --#-----#-------#-----> upstream        reconstruct its identity by

-                                          inspecting interchange branch
+                                           inspecting interchange branch

     Key:
 
       1,2,3   commits touching upstream files only
     Key:
 
       1,2,3   commits touching upstream files only


@@ -111,7 +130,7 @@ by git-debrebase.
      -/-      pseudomerge; contents are identical to
      /         parent lower on diagram.
 
      -/-      pseudomerge; contents are identical to
      /         parent lower on diagram.
 

-      %       dgit-generated commit of debian/patches.
+      %       dgit- or git-debrebase- generated commit of debian/patches.

               `3.0 (quilt)' only; generally dropped by git-debrebase.
 
       *       Maintainer's HEAD was here while they were editing,
               `3.0 (quilt)' only; generally dropped by git-debrebase.
 
       *       Maintainer's HEAD was here while they were editing,


@@ -165,7 +184,7 @@ known as B<unstitched>.
 While a branch is unstitched,
 it is not in interchange format.
 The previous interchange branch tip
 While a branch is unstitched,
 it is not in interchange format.
 The previous interchange branch tip

-tip is recorded,
+is recorded,

 so that the previous history
 and the user's work
 can later be
 so that the previous history
 and the user's work
 can later be


@@ -369,8 +388,8 @@ general merges on any of the relevant branches.
 For this reason the tools will try to help the user
 avoid divergence of the interchange branch.
 
 For this reason the tools will try to help the user
 avoid divergence of the interchange branch.
 

-See dgit-maint-rebase(7) XXX TBD
-for a discussio of what kinds of behaviours
+See dgit-maint-rebase(7)
+for a discussion of what kinds of behaviours

 should be be avoided
 because
 they might generate such merges.
 should be be avoided
 because
 they might generate such merges.


@@ -389,7 +408,7 @@ Nonlinear (merging) history in the breakwater branch is
 in principle tolerable,
 but each of the parents would have to be, in turn,
 a breakwater,
 in principle tolerable,
 but each of the parents would have to be, in turn,
 a breakwater,

-and difficult qeustions arise if they don't have the same anchor.
+and difficult questions arise if they don't have the same anchor.

 
 We use the commit message annotation to
 distinguish the special anchor merges from other general merges,
 
 We use the commit message annotation to
 distinguish the special anchor merges from other general merges,


@@ -468,6 +487,48 @@ These patch files can be stripped out and/or regenerated as needed.
 
 =back
 
 
 =back
 

+=head1 ILLEGAL OPERATIONS
+
+Some git operations are not permitted in this data model.
+Performing them will break git-debrebase.
+
+=over
+
+=item General merges
+
+See L</OTHER MERGES>, above.
+
+=item git-rebase starting too soon, or without base argument
+
+git-rebase must not be invoked in such a way that
+the chosen base is before the anchor,
+or before the last pseudomerge.
+This is because git-rebase mangles merges.
+git rebase --preserve-merges is also dangerous.
+
+git-rebase without a base argument will often start too early.
+
+For these reasons,
+it is better to use git-debrebase and
+let it choose the base
+for your rebase.
+If you do realise you have make this mistake,
+it is best to use the reflog to recover to a suitable
+good previous state.
+
+=item Editing debian/patches
+
+debian/patches is an output from git-debrebase,
+not an input.
+If you edit patches git-debrebase will complain
+and refuse to work.
+If you add patches your work is likely to be discarded.
+
+Instead of editing patches,
+use git-debrebase to edit the corresponding commits.
+
+=back
+

 =head1 COMMIT MESSAGE ANNOTATIONS
 
 git-debrebase makes annotations
 =head1 COMMIT MESSAGE ANNOTATIONS
 
 git-debrebase makes annotations


@@ -489,6 +550,7 @@ The full set of annotations is:
   [git-debrebase upstream-combine . PIECE[ PIECE...]: new upstream]
   [git-debrebase anchor: new upstream NEW-UPSTREAM-VERSION, merge]
   [git-debrebase: new upstream NEW-UPSTREAM-VERSION, changelog]
   [git-debrebase upstream-combine . PIECE[ PIECE...]: new upstream]
   [git-debrebase anchor: new upstream NEW-UPSTREAM-VERSION, merge]
   [git-debrebase: new upstream NEW-UPSTREAM-VERSION, changelog]

+  [git-debrebase: export and commit patches]

 
   [git-debrebase convert-from-gbp: drop patches]
   [git-debrebase anchor: declare upstream]
 
   [git-debrebase convert-from-gbp: drop patches]
   [git-debrebase anchor: declare upstream]


@@ -498,7 +560,8 @@ The full set of annotations is:
 
 Only anchor merges have the C<[git-debrebase anchor: ...]> tag.
 Single-parent anchors are not generated by git-debrebase,
 
 Only anchor merges have the C<[git-debrebase anchor: ...]> tag.
 Single-parent anchors are not generated by git-debrebase,

-and when made manually should not be tagged.
+and when made manually should not
+contain any C<[git-debrebase ...]> annotation.

 
 The C<split mixed commit> and C<convert dgit import>
 tags are added to the pre-existing commit message,
 
 The C<split mixed commit> and C<convert dgit import>
 tags are added to the pre-existing commit message,


@@ -506,9 +569,14 @@ when git-debrebase rewrites the commit.
 
 =head1 APPENDIX - DGIT IMPORT HANDLING
 
 
 =head1 APPENDIX - DGIT IMPORT HANDLING
 

+The dgit .dsc import format is not documented or specified
+(so some of the following terms are not defined anywhere).
+The dgit import format it is defined by the implementation in dgit,
+of which git-debrebase has special knowledge.
+

 Consider a non-dgit NMU followed by a dgit NMU:
 
 Consider a non-dgit NMU followed by a dgit NMU:
 

-            interchange --/--B3!--%--/----D*-->
+            interchange --/--B3!--%--//----D*-->

                          /          /
                         %          4
                        /          3
                          /          /
                         %          4
                        /          3


@@ -519,21 +587,22 @@ Consider a non-dgit NMU followed by a dgit NMU:
                   1          0 00 =XBC%
                  /
                 /
                   1          0 00 =XBC%
                  /
                 /

-                 --@--A     breakwater
-          /
-       --#--------> upstream
+          --@--A     breakwater
+           /
+        --#--------> upstream

 
 
  Supplementary key:
 
     =XBC%     dgit tarball import of .debian.tar.gz containing
 
 
  Supplementary key:
 
     =XBC%     dgit tarball import of .debian.tar.gz containing

-              Debian packaging including changes B C and quilt patches
-
+               Debian packaging including changes B C and quilt patches

     0         dgit tarball import of upstream tarball
     0         dgit tarball import of upstream tarball

-    00        dgit tarball import of supplementary upstream tarball
-    &_        dgit nearly-breakwater import
+    00        dgit tarball import of supplementary upstream piece
+    &_        dgit import nearly-breakwater-anchor
+    //        dgit fetch / import-dsc pseudomerge to make fast forward
+

     &'        git-debrebase converted import (upstream files only)
     &'        git-debrebase converted import (upstream files only)

-    D'        git-debrebase converted debian/ changes import
+    C'        git-debrebase converted packaging change import

 
     * **      before and after HEAD
 
 
     * **      before and after HEAD
 


@@ -544,43 +613,43 @@ We want to transform this into:
 =item I. No new upstream version
 
  (0 + 00 eq #)
 =item I. No new upstream version
 
  (0 + 00 eq #)

-                        --/--B3!--%--/------D*-------------/-->
-                         /          /                    /
-                        %          4                    4**
-                       /          3                    3
-                      /          2                    2
-                     /          1                    1
-                    2          &_                   /
-                   /          /| \                 /
+                        --/--B3!--%--//-----D*-------------/-->
+                         /          /                     /
+                        %          4                     4**
+                       /          3                     3
+                      /          2                     2
+                     /          1                     1
+                    2          &_                    /
+                   /          /| \                  /

                   1          0 00 =XBC%            /
                   1          0 00 =XBC%            /

-                 /                                       /
-                /                                       /
-         --@--A-----B-----------------------C--D
-          /
-       --#----------------------------------------->
+                 /                                /
+                /                                /
+          --@--A-----B---------------------C'---D
+           /
+        --#----------------------------------------->

 
 =item II. New upstream
 
  (0 + 00 neq #)
 
 
 =item II. New upstream
 
  (0 + 00 neq #)
 

-                        --/--B3!--%--/------D*-------------/-->
-                         /          /                    /
-                        %          4                    4**
-                       /          3                    3
-                      /          2                    2
-                     /          1                    1
-                    2          &_                   /
-                   /          /| \                 /
+                        --/--B3!--%--//-----D*-------------/-->
+                         /          /                     /
+                        %          4                     4**
+                       /          3                     3
+                      /          2                     2
+                     /          1                     1
+                    2          &_                    /
+                   /          /| \                  /

                   1          0 00 =XBC%            /
                   1          0 00 =XBC%            /

-                 /                               /
-                /                               /
-         --@--A-----B--------------------@--C--D
-          /                             /
-       --#----------------------- - -  /  - - ----->
-                                      /
-                                     &'
-                                    /|
-                                   0 00
+                 /                                /
+                /                                /
+          --@--A-----B-----------------@---C'---D
+           /                          /
+        --#--------------------- - - / - - --------->
+                                    /
+                                   &'
+                                  /|
+                                 0 00

 
 =back
 
 
 =back