Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>
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,
------/--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*
/ / /
/ / / 3.0 (quilt) has debian/patches
/ / 3*
/ / /
/ 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
+ tools made -/- (and maybe %) to convert to
the fast-forwarding interchange branch.
! NMUer's HEAD was here when they said `dgit push'.
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>)
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
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>.
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.
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
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.)
-=item Delta from upstream
+=item Delta queue commits
Zero or more single-parent commits
contaioning only changes to upstream files.
Zero or more single-parent commits
contaioning only changes 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.
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.
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.
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.
Record the previous tip in ffq-prev,
if we were stitched before.
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
+followed by the delta queue,
turning C<-@-A-1-2-B3> into C<...@-A-B-1-2-3>.
Drop pseudomerges and any quilt patches.
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,
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 #'.
Note that the construction of @' cannot fail
because @' simply copies debian/ from B and and everything else from #'.
=item Stitch
Make a pseudomerge,
=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 quilt patches
To generate a tree which can be represented as a
3.0 (quilt) .dsc source packages,
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;
=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.
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
=back
=head1 APPENDIX - DGIT IMPORT HANDLING
Key:
=XBC% dgit tarball import of .debian.tar.gz containing
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
0 dgit tarball import of upstream tarball
00 dgit tarball import of supplementary upstream tarball
~ianmdlvl / dgit.git / commitdiff