git-debrebase(5): Rework the description a bit

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

diff --git a/git-debrebase.5.pod b/git-debrebase.5.pod
index f207c954f16e579e57594b8b47d806d50342b975..f181a40ec50a543472e04f079785a4435c67de51 100644 (file)
--- a/git-debrebase.5.pod
+++ b/git-debrebase.5.pod
@@ -10,14 +10,14 @@ Debian packages based on upstream source code.
 
 The Debian packaging
 has a fast forwarding history.
 
 The Debian packaging
 has a fast forwarding history.

-The changes to upstream files are represented
+The delta queue (changes to upstream files) is represented

 as a series of individual git commits,
 which can worked on with rebase,
 and also shared.
 
 git-debrebase is designed to work well with dgit.
 git-debrebase can also be used in workflows without source packages,
 as a series of individual git commits,
 which can worked on with rebase,
 and also shared.
 
 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 Debian.
+for example to work on Debian-format packages outside or alongside Debian.

 
 git-debrebase is not very suitable for use by Debian derivatives,
 to work on packages inherited from Debian,
 
 git-debrebase is not very suitable for use by Debian derivatives,
 to work on packages inherited from Debian,


@@ -28,13 +28,13 @@ provided by your upstream.
 
            ------/--A!----/--B3!--%--/--> interchange view
                 /        /          /      with debian/ directory
 
            ------/--A!----/--B3!--%--/--> interchange view
                 /        /          /      with debian/ directory

-               %        %          %       all upstream changes applied
+               %        %          %       entire delta queue applied

               /        /          /        3.0 (quilt) has debian/patches
              /        /          3*
             /        /          /
            2*       2*         2
           /        /          /
               /        /          /        3.0 (quilt) has debian/patches
              /        /          3*
             /        /          /
            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


@@ -54,13 +54,12 @@ provided by your upstream.
      /         parent lower on diagram.
 
       %       dgit-generated commit of debian/patches.
      /         parent lower on diagram.
 
       %       dgit-generated commit of debian/patches.

-              `3.0 (quilt)' only; dropped by rebase tool.
+              `3.0 (quilt)' only; generally dropped by git-debrebase.

 
       *       Maintainer's HEAD was here while they were editing,
               before they said they were done, at which point their
 
       *       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'.)
+              tools made -/- (and maybe %) to convert to
+              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


@@ -73,7 +72,7 @@ the B<interchange branch>.
 This branch is found on Debian contributor's workstations
 (typically, a maintainer would call it B<master>),
 in the Debian dgit git server as the suite branch (B<dgit/dgit/sid>)
 This branch is found on Debian contributor's workstations
 (typically, a maintainer would call it B<master>),
 in the Debian dgit git server as the suite branch (B<dgit/dgit/sid>)

-and on other git servers which support Debian owrk
+and on other git servers which support Debian work

 (eg B<master> on salsa).
 
 The interchange branch is fast-forwarding
 (eg B<master> on salsa).
 
 The interchange branch is fast-forwarding


@@ -83,41 +82,47 @@ It is possible to have multiple different interchange branches
 for the same package,
 stored as different local and remote git branches.
 However, divergence should be avoided where possible -
 for the same package,
 stored as different local and remote git branches.
 However, divergence should be avoided where possible -

-see L</STITCHING, PSEUDO-MERGES, FFQ RECORD>.
+see L</OTHER MERGES>.

 
 A suitable interchange branch can be used directly with dgit.
 In this case each dgit archive suite branch is a separate
 interchange branch.
 
 
 A suitable interchange branch can be used directly with dgit.
 In this case each dgit archive suite branch is a separate
 interchange branch.
 

-Within the ancenstry of the interchange branch,
-there is another importnt, implicit branch, the
+Within the ancestry of the interchange branch,
+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).
 B<breakwater>.
 The breakwater contains unmodified upstream source,
 but with Debian's packaging superimposed
 (replacing any C<debian/> directory that may be in upstream).

-The breakwater does not contain any representation
-of Debian's changes to upstream files.
-The breakwater starts at an B<anchor>,
+The breakwater does not contain any representation of
+the delta queue.
+The part of the breakwater processed by git-debrebase
+is the part since the most reecent B<anchor>,

 which is usually a special merge generated by git-debrebase.
 
 When working, locally,
 the user's branch can be in a rebasing state,
 known as B<unstitched>.
 which is usually a special merge generated by git-debrebase.
 
 When working, locally,
 the user's branch can be in a rebasing state,
 known as B<unstitched>.

-When a branch is unstitched,
-its previous tip is recorded so that it can later be
+While a branch is unstitched,
+its previous tip is recorded,
+so that the previous history
+and the user's work
+can later be

 stitched into the fast-forwarding interchange form.
 
 An unstitched branch may be in
 B<laundered>
 state,
 which means it has a more particular special form
 stitched into the fast-forwarding interchange form.
 
 An unstitched branch may be in
 B<laundered>
 state,
 which means it has a more particular special form

-convenient for manipulating the changes to upstream files.
+convenient for manipulating the delta queue.

 
 

-=head1 BRANCH CONTENTS
+=head1 BRANCH CONTENTS - DETAILED SPECIFICATION

 
 It is most convenient to describe the
 
 It is most convenient to describe the

-B<laundered>
-state first.
+B<breakwater>
+branch first.
+A breakwater is B<fast-forwarding>,
+but is not usually named by a ref.

 It contains B<in this order> (ancestors first):
 
 =over
 It contains B<in this order> (ancestors first):
 
 =over


@@ -126,10 +131,12 @@ It contains B<in this order> (ancestors first):
 
 An B<anchor> commit,
 which is usually a special two-parent merge:
 
 An B<anchor> commit,
 which is usually a special two-parent merge:

-The first parent is a previous breakwater branch,
+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.
 whose upstream files are irrelevant,
 and whose packaging files are identical to the anchor's.

-The second parent is an upstream source commit;
+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.
 Anchor merges always contain
 whose packaging files (if any) are irrelevant,
 and whose upstream files are identical to the anchor's.
 Anchor merges always contain


@@ -144,22 +151,35 @@ ie, the start of Debian packaging.
 
 Zero or more single-parent commits
 containing only packaging changes.
 
 Zero or more single-parent commits
 containing only packaging changes.

-(And no changes to B<debian/patches/>.)
+(And no quilt patch changes.)
+
+=back
+
+The
+B<laundered>
+branch state is B<rebasing>.
+A laundered branch is based on a breakwater
+but also contains, additionally,
+B<after> the breakwater,
+a representation of the delta queue:
+
+=over

 
 

-=item Delta from upstream
+=item Delta queue commits

 
 Zero or more single-parent commits
 contaioning only changes to upstream files.
 
 =back
 
 
 Zero or more single-parent commits
 contaioning only changes to upstream files.
 
 =back
 

-The
+An

 B<unstitched>
 (unlaundered)
 B<unstitched>
 (unlaundered)

-branch state is the same,
+branch state is also B<rebasing>.
+It has the same contents as the laundered state,

 except that it may contain,
 additionally,
 except that it may contain,
 additionally,

-in B<in any order>:
+in B<in any order but after the breakwater>:

 
 =over
 
 
 =over
 


@@ -170,20 +190,25 @@ to upstream files
 and/or
 to packaging,
 possibly mixed within a single commit.
 and/or
 to packaging,
 possibly mixed within a single commit.

-(But no changes to B<debian/patches/>.)
+(But not quilt patch changes.)

 
 

-=item Patch addition for `3.0 (quilt)'
+=item Quilt patch addition for `3.0 (quilt)'

 
 Commit(s) which add patches to B<debian/patches/>,
 and add those patches to the end of B<series>.
 
 Commit(s) which add patches to B<debian/patches/>,
 and add those patches to the end of B<series>.

-These are only necessary or useful when working with
+These are only necessary when working with

 packages in C<.dsc 3.0 (quilt)> format.
 packages in C<.dsc 3.0 (quilt)> format.

+For git-debrebase they are purely an output;
+they are deleted when branches are laundered.

 
 =back
 
 
 =back
 

-The
+Finally, an

 B<interchange>
 B<interchange>

-branch state is the same, but may additionally contain
+branch is B<fast forwarding>.
+It has the same contents as an
+unlaundered branch state,
+but may (and usually will) additionally contain

 (in some order,
 possibly intermixed with the extra commits
 which may be found on an unstitched unlaundered branch):
 (in some order,
 possibly intermixed with the extra commits
 which may be found on an unstitched unlaundered branch):


@@ -200,6 +225,12 @@ a previous tip of the interchange branch,
 but this is not necessary as the overwritten
 parent is not examined.
 
 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 left parent.
+

 =item dgit dsc import
 
 Debian .dsc source package import(s) made by dgit.
 =item dgit dsc import
 
 Debian .dsc source package import(s) made by dgit.


@@ -207,24 +238,25 @@ 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
 whose contributing parent is in the special
 dgit format (not described further here).
 The overwritten parent must be

-the previous interchange tip
-(and will be generated that way by normal use of dgit).
+the previous interchange tip.
+This is the form normally generated by dgit
+when it imports .dsc-based uploads.

 
 =back
 
 =head1 STITCHING, PSEUDO-MERGES, FFQ RECORD
 
 Whenever the branch C<refs/B> is unstitched,
 
 =back
 
 =head1 STITCHING, PSEUDO-MERGES, FFQ RECORD
 
 Whenever the branch C<refs/B> is unstitched,

-the previous tip is recorded in the git ref C<refs/ffq-prev/heads/B>.
+the previous tip is recorded in the git ref C<refs/ffq-prev/B>.

 
 Unstiched branches are not fast forward from the published
 
 Unstiched branches are not fast forward from the published

-interchange branches. [1]
+interchange branches [1].

 So before a branch can be pushed,
 the right pseudomerge must be reestablished.
 This is the stitch operation,
 which consumes the ffq-prev ref.
 
 So before a branch can be pushed,
 the right pseudomerge must be reestablished.
 This is the stitch operation,
 which consumes the ffq-prev ref.
 

-When the user has an unstituched branch,
+When the user has an unstitched branch,

 they may rewrite it freely,
 from the breakwater tip onwards.
 Such a git rebase is the default operation for git-debrebase.
 they may rewrite it freely,
 from the breakwater tip onwards.
 Such a git rebase is the default operation for git-debrebase.


@@ -238,11 +270,17 @@ in similar circumstances and with similar warnings
 to sharing any other rebasing git branch.
 
 [1] Strictly, for a package
 to sharing any other rebasing git branch.
 
 [1] Strictly, for a package

-which has never had Debian changes to upstream files,
+which has never had a Debian delta queue,

 the interchange and breakwater branches may be identical,
 in which case the unstitched branch is fast forward
 from the interchange branch and no pseudomerge is needed.
 
 the interchange and breakwater branches may be identical,
 in which case the unstitched branch is fast forward
 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.
+

 =head1 OTHER MERGES
 
 Note that the representation described here does not permit
 =head1 OTHER MERGES
 
 Note that the representation described here does not permit


@@ -270,6 +308,114 @@ 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.
+
+(This may make the branch unlaundered.)
+
+=item Launder branch
+
+Record the previous tip in ffq-prev,
+if we were stitched before
+(and delete debrebase-last).
+
+Reorganise the current branch so that the packaging
+changes come first,
+followed by the delta queue,
+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 the commit 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,
+whose contributing parent to is the unstitched branch
+and
+whose overwritten parent is ffq-prev,
+consuming ffq-prev in the process
+(and writing debrebase-last instead).
+Ideally the contributing parent would be a laundered branch,
+or perhaps a laundered branch with a quilt patch addition commit.
+
+=item Commit quilt 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 patch files can be stripped out and/or regenerated as needed.
+
+=back
+
+=head1 COMMIT MESSAGE ANNOTATIONS
+
+git-debrebase makes annotations
+in the messages of commits it generates.
+
+The general form is
+
+  [git-debrebase[ COMMIT-TYPE [ ARGS...]]: PROSE, MORE PROSE]
+
+git-debrebase does not pay attention to anything after the colon,
+so PROSE is ignored.
+
+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 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 convert-from-gbp: drop patches]
+  [git-debrebase anchor: declare upstream]
+  [git-debrebase pseudomerge: stitch]
+
+  [git-debrebase convert-to-gbp: commit 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.
+
+The C<split mixed commit> and C<convert dgit import>
+tags are added to the pre-existing commit message,
+when git-debrebase rewrites the commit.
+

 =head1 TERMINOLOGY
 
 =over
 =head1 TERMINOLOGY
 
 =over


@@ -277,7 +423,7 @@ so we can at least detect unsupported merges.
 =item Pseudomerge
 
 A merge which does not actually merge the trees;
 =item Pseudomerge
 
 A merge which does not actually merge the trees;

-instead, it takes its tree by construction from one parent.
+instead, it takes its tree, by construction, from only one parent.

 These are used to make a rewritten history fast forward
 from a previous tip,
 so that it can be pushed and pulled normally.
 These are used to make a rewritten history fast forward
 from a previous tip,
 so that it can be pushed and pulled normally.


@@ -302,8 +448,101 @@ Files in the source tree outside B<debian/>.
 These may include unmodified source from upstream,
 but also files which have been modified or created for Debian.
 
 These may include unmodified source from upstream,
 but also files which have been modified or created for Debian.
 

+=item Delta queue
+
+Debian's changes to upstream files:
+a series of git commits.
+
+=item Quilt patches
+
+Files in B<debian/patches/> generated for the benefit of
+dpkg-source's 3.0 (quilt) .dsc source package format.
+Not used, and often deleted, by git-debrebase.
+
+=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 quilt 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
 
 =back
 
 =head1 SEE ALSO
 

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