chiark / gitweb /
git-debrebase(5): Terminology fixes, cleanups
authorIan Jackson <ijackson@chiark.greenend.org.uk>
Sun, 18 Feb 2018 22:28:31 +0000 (22:28 +0000)
committerIan Jackson <ijackson@chiark.greenend.org.uk>
Sun, 18 Feb 2018 22:28:31 +0000 (22:28 +0000)
Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>
git-debrebase.5.pod

index ce982369c3132af1110e2d6d4f62b104659403c0..6fc1ae54962b3495e239d352f304bb008146a416 100644 (file)
@@ -10,14 +10,14 @@ Debian packages based on upstream source code.
 
 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,
-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,
@@ -28,7 +28,7 @@ provided by your upstream.
 
            ------/--A!----/--B3!--%--/--> interchange view
                 /        /          /      with debian/ directory
-               %        %          %       all upstream changes applied
+               %        %          %       entire delta queue applied
               /        /          /        3.0 (quilt) has debian/patches
              /        /          3*
             /        /          /
@@ -54,11 +54,11 @@ provided by your upstream.
      /         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
-              tools generated [% and] -/- commit[s] to convert to
+              tools made -/- (and maybe %) to convert to
               the fast-forwarding interchange branch.
 
       !       NMUer's HEAD was here when they said `dgit push'.
@@ -72,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>)
-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
@@ -82,35 +82,39 @@ 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 -
-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.
 
-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).
-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>.
-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
-convenient for manipulating the changes to upstream files.
+convenient for manipulating the delta queue.
 
 =head1 BRANCH CONTENTS
 
@@ -125,10 +129,12 @@ 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 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.
-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
@@ -143,9 +149,9 @@ ie, the start of Debian packaging.
 
 Zero or more single-parent commits
 containing only packaging changes.
-(And no changes to B<debian/patches/>.)
+(And no quilt patch changes.)
 
-=item Delta from upstream
+=item Delta queue commits
 
 Zero or more single-parent commits
 contaioning only changes to upstream files.
@@ -169,14 +175,16 @@ to upstream files
 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>.
-These are only necessary or useful when working with
+These are only necessary when working with
 packages in C<.dsc 3.0 (quilt)> format.
+For git-debrebase they are purely an output;
+they are deleted when branches are laundered.
 
 =back
 
@@ -199,6 +207,12 @@ a previous tip of the interchange branch,
 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.
@@ -206,8 +220,9 @@ 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
-(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
 
@@ -237,7 +252,7 @@ in similar circumstances and with similar warnings
 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.
@@ -289,8 +304,9 @@ or both.
 Record the previous tip in ffq-prev,
 if we were stitched before.
 
-Reorganise the current branch so that the debian/
+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.
@@ -308,7 +324,7 @@ 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 theommit list.
+@' 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 #'.
@@ -319,9 +335,14 @@ so that git log shows the packaging history.)
 =item Stitch 
 
 Make a pseudomerge,
-overwriting (and consuming) ffq-prev.
+whose contributing parent to is the unstitched branch
+and
+whose overwritten parent is ffq-prev,
+consuming ffq-prev in the process.
+Ideally the contributing parent would be a laundered branch,
+or perhaps a laundered branch with a quilt patch addition commit.
 
-=item Commit patches
+=item Commit quilt patches
 
 To generate a tree which can be represented as a
 3.0 (quilt) .dsc source packages,
@@ -338,7 +359,7 @@ in B<debian/patches/>.
 =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.
@@ -363,6 +384,17 @@ 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.
 
+=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
@@ -388,7 +420,7 @@ Consider a non-dgit NMU followed by a dgit NMU:
  Key:
 
     =XBC%     dgit tarball import of .debian.tar.gz containing
-              Debian packaging including changes B C and 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