1 files changed, 63 insertions, 31 deletions
diff --git a/git-debrebase.5.pod b/git-debrebase.5.pod
index ce98236..6fc1ae5 100644
@@ -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
-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
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
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
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.
@@ -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.
@@ -237,7 +252,7 @@ in similar circumstances and with similar warnings
to sharing any other rebasing git branch.
 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 thec ommit 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.)
Make a pseudomerge,
-overwriting (and consuming) ffq-prev.
+whose contributing parent to is the unstitched branch
+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/>.
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.
=head1 APPENDIX - DGIT IMPORT HANDLING
@@ -388,7 +420,7 @@ Consider a non-dgit NMU followed by a dgit NMU:
=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