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,
------/--A!----/--B3!--%--/--> interchange view
/ / / with debian/ directory
- % % % all upstream changes applied
+ % % % entire delta queue applied
/ / / 3.0 (quilt) has debian/patches
/ / 3*
/ / /
/ 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'.
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
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
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
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.
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
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.
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
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.
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.
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 #'.
=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,
=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 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
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
~ianmdlvl / dgit.git / commitdiff