chiark / gitweb /
git-debrebase: Replace several `git-debrebase:' with `$us:'
[dgit.git] / git-debrebase.5.pod
index f749f62..439fd63 100644 (file)
@@ -15,6 +15,8 @@ as a series of individual git commits,
 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.
@@ -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.
-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.
 
+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
@@ -34,7 +41,9 @@ derivatives, and it can make some things easier.
 =item Pseudomerge
 
 A merge which does not actually merge the trees;
-instead, it takes its tree, by construction, from only one parent.
+instead, it is constructed by taking the tree
+from one of the parents
+(ignoring the contents of the other parents).
 These are used to make a rewritten history fast forward
 from a previous tip,
 so that it can be pushed and pulled normally.
@@ -74,9 +83,22 @@ a series of git commits.
 
 Files in B<debian/patches/> generated for the benefit of
 dpkg-source's 3.0 (quilt) .dsc source package format.
-Not used, often deleted, and regenerated when needed,
+Not used, often deleted, and regenerated when needed
+(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
@@ -92,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)
-      /     /       /                    no ref refers to this: we
+      /     /       /                     no ref refers to this: we
    --#-----#-------#-----> upstream        reconstruct its identity by
-                                          inspecting interchange branch
+                                           inspecting interchange branch
     Key:
 
       1,2,3   commits touching upstream files only
@@ -108,7 +130,7 @@ by git-debrebase.
      -/-      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,
@@ -148,7 +170,8 @@ there is another important, implicit branch, the
 B<breakwater>.
 The breakwater contains unmodified upstream source,
 but with Debian's packaging superimposed
-(replacing any C<debian/> directory that may be in upstream).
+(replacing any C<debian/> directory that may be in
+the upstream commits).
 The breakwater does not contain any representation of
 the delta queue (not even debian/patches).
 The part of the breakwater processed by git-debrebase
@@ -161,7 +184,7 @@ known as B<unstitched>.
 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
@@ -188,17 +211,24 @@ It contains B<in this order> (ancestors first):
 
 An B<anchor> commit,
 which is usually a special two-parent merge:
-The first parent is
-a previous branch tip with Debian packaging tip
-(perhaps a previous breakwater tip)
-whose upstream files are irrelevant,
-and whose packaging files are identical to the anchor's.
-The second parent is an upstream source commit,
-whose packaging files (if any) are irrelevant,
-and whose upstream files are identical to the anchor's.
+
+The first parent
+contains the most recent version, at that point,
+of the Debian packaging (in debian/);
+it also often contains upstream files,
+but they are to be ignored.
+Often the first parent is a previous breakwater tip.
+
+The second parent
+is an upstream source commit.
+It may sometimes contain a debian/ subdirectory,
+but if so that is to be ignored.
+The second parent's upstream files
+are identical to the anchor's.
 Anchor merges always contain
 C<[git-debrebase anchor: ...]>
 as a line in the commit message.
+
 Alternatively,
 an anchor may be a single-parent commit which introduces
 the C<debian/> directory and makes no other changes:
@@ -287,21 +317,30 @@ but this is not necessary as the overwritten
 parent is not examined.
 
 If the two parents have identical trees,
-the contributing parent is taken to be
-the one with the later commit date,
-or if the commit dates are the same,
-the first parent.
-
-=item dgit dsc import
-
-Debian .dsc source package import(s) made by dgit.
-Each such import must be a two-parent pseudomerge
-whose contributing parent is in the special
-dgit format (not described further here).
-The overwritten parent must be
-the previous interchange tip.
-This is the form normally generated by dgit
-when it imports .dsc-based uploads.
+the one with the later commit date
+(or, if the commit dates are the same,
+the first parent)
+is treated as
+the contributing parent.
+
+=item dgit dsc import pseudomerge
+
+Debian .dsc source package import(s)
+made by dgit
+(during dgit fetch of a package most recently 
+uploaded to Debian without dgit,
+or during dgit import-dsc).
+
+git-debrebase requires that
+each such import is in the fast-forwarding
+format produced by dgit:
+a two-parent pseudomerge,
+whose contributing parent is in the
+non-fast-forwarding
+dgit dsc import format (not described further here),
+and whose overwritten parent is
+the previous interchange tip
+(eg, the previous tip of the dgit suite branch).
 
 =back
 
@@ -339,8 +378,11 @@ from the interchange branch and no pseudomerge is needed.
 When ffq-prev is not present,
 C<refs/debrebase-last/B> records some ancestor of refs/B,
 (usually, the result of last stitch).
-This can be used to quickly determine whether refs/B
-is being maintained in git-debrebase form.
+This is used for status printing and some error error checks -
+especially for printing guesses what a problem is.
+To determine whether a branch is 
+is being maintained in git-debrebase form
+it is necessary to walk its history.
 
 =head1 OTHER MERGES
 
@@ -349,8 +391,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.
 
-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.
@@ -369,7 +411,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,
-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,
@@ -448,6 +490,63 @@ These patch files can be stripped out and/or regenerated as needed.
 
 =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.
+
+=item Renaming (etc.) branch while unstitched
+
+The previous HEAD,
+which will be pseudomerged over
+by operations like git-debrebase stitch,
+is recorded in a ref name dervied from your branch name.
+
+If you rename unstitched branches,
+this information can get out of step.
+
+Conversely,
+creating a new branch from an unstitched branch
+is good for making a branch to play about in,
+but the result cannot be stitched.
+
+=back
+
 =head1 COMMIT MESSAGE ANNOTATIONS
 
 git-debrebase makes annotations
@@ -455,30 +554,36 @@ in the messages of commits it generates.
 
 The general form is
 
-  [git-debrebase[ COMMIT-TYPE [ ARGS...]]: PROSE, MORE PROSE]
+  [git-debrebase COMMIT-TYPE [ ARGS...]: PROSE, MORE PROSE]
 
-git-debrebase does not pay attention to anything after the colon,
-so PROSE is ignored.
+git-debrebase treats anything after the colon as a comment,
+paying no attention to PROSE.
 
 The full set of annotations is:
-  [git-debrebase: split mixed commit, debian part]
-  [git-debrebase: split mixed commit, upstream-part]
-  [git-debrebase: convert dgit import, debian changes]
+  [git-debrebase split: mixed commit, debian part]
+  [git-debrebase split: mixed commit, upstream-part]
+  [git-debrebase onvert dgit import: debian changes]
   [git-debrebase anchor: convert dgit import, upstream changes]
 
   [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 changelog: new upstream NEW-UPSTREAM-VERSION]
+  [git-debrebase make-patches: export and commit patches]
 
   [git-debrebase convert-from-gbp: drop patches]
   [git-debrebase anchor: declare upstream]
   [git-debrebase pseudomerge: stitch]
 
+  [git-debrebase merged-breakwater: constructed from vanilla merge]
+
   [git-debrebase convert-to-gbp: commit patches]
+  [git-debrebase convert-from-dgit-view upstream-import-convert: VERSION]
+  [git-debrebase convert-from-dgit-view drop-patches]
 
 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,
@@ -486,9 +591,14 @@ when git-debrebase rewrites the commit.
 
 =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:
 
-            interchange --/--B3!--%--/----D*-->
+            interchange --/--B3!--%--//----D*-->
                          /          /
                         %          4
                        /          3
@@ -499,21 +609,22 @@ Consider a non-dgit NMU followed by a dgit NMU:
                   1          0 00 =XBC%
                  /
                 /
-                 --@--A     breakwater
-          /
-       --#--------> upstream
+          --@--A     breakwater
+           /
+        --#--------> upstream
 
 
  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
-    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)
-    D'        git-debrebase converted debian/ changes import
+    C'        git-debrebase converted packaging change import
 
     * **      before and after HEAD
 
@@ -524,43 +635,43 @@ We want to transform this into:
 =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%            /
-                 /                                       /
-                /                                       /
-         --@--A-----B-----------------------C--D
-          /
-       --#----------------------------------------->
+                 /                                /
+                /                                /
+          --@--A-----B---------------------C'---D
+           /
+        --#----------------------------------------->
 
 =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%            /
-                 /                               /
-                /                               /
-         --@--A-----B--------------------@--C--D
-          /                             /
-       --#----------------------- - -  /  - - ----->
-                                      /
-                                     &'
-                                    /|
-                                   0 00
+                 /                                /
+                /                                /
+          --@--A-----B-----------------@---C'---D
+           /                          /
+        --#--------------------- - - / - - --------->
+                                    /
+                                   &'
+                                  /|
+                                 0 00
 
 =back