However, of git-debrebase in Debian does not make anything harder for
derivatives, and it can make some things easier.
+=head1 TERMINOLOGY
+
+=over
+
+=item Pseudomerge
+
+A merge which does not actually merge the trees;
+instead, it is constructed by taking the tree
+from one of the parents
+(ignoring the contents of the other parents).
+These are used to make a rewritten history fast forward
+from a previous tip,
+so that it can be pushed and pulled normally.
+Manual construction of pseudomerges can be done with
+C<git merge -s ours>
+but is not normally needed when using git-debrebase.
+
+=item Packaging files
+
+Files in the source tree within B<debian/>,
+excluding anything in B<debian/patches/>.
+
+=item Upstream
+
+The version of the package without Debian's packaging.
+Typically provided by the actual upstream project,
+and sometimes tracked by Debian contributors in a branch C<upstream>.
+
+Upstream contains upstream files,
+but some upstreams also contain packaging files in B<debian/>.
+Any such non-upstream files found in upstream
+are thrown away by git-debrebase
+each time a new upstream version is incorporated.
+
+=item Upstream files
+
+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, often deleted, and regenerated when needed
+(such as when uploading to Debian),
+by git-debrebase.
+
+=item Interchange branch; breakwater; stitched; laundered
+
+See L</BRANCHES AND BRANCH STATES - OVERVIEW>.
+
+=item Anchor; Packaging
+
+See L</BRANCH CONTENTS - DETAILED SPECIFICATION>.
+
+=item ffq-prev; debrebase-last
+
+See L</STITCHING, PSEUDO-MERGES, FFQ RECORD>.
+
+=back
+
=head1 DIAGRAM
------/--A!----/--B3!--%--/--> interchange view
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
+ / / / no ref refers to this: we
--#-----#-------#-----> upstream reconstruct its identity by
- inspecting interchange branch
+ inspecting interchange branch
Key:
1,2,3 commits touching upstream files only
-/- pseudomerge; contents are identical to
/ parent lower on diagram.
- % dgit-generated commit of debian/patches.
+ % dgit- or git-debrebase- generated commit of debian/patches.
`3.0 (quilt)' only; generally dropped by git-debrebase.
* Maintainer's HEAD was here while they were editing,
B<breakwater>.
The breakwater contains unmodified upstream source,
but with Debian's packaging superimposed
-(replacing any C<debian/> directory that may be in upstream).
+(replacing any C<debian/> directory that may be in
+the upstream commits).
The breakwater does not contain any representation of
the delta queue (not even debian/patches).
The part of the breakwater processed by git-debrebase
An B<anchor> commit,
which is usually a special two-parent merge:
-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,
-whose packaging files (if any) are irrelevant,
-and whose upstream files are identical to the anchor's.
+
+The first parent
+contains the most recent version, at that point,
+of the Debian packaging (in debian/);
+it also often contains upstream files,
+but they are to be ignored.
+Often the first parent is a previous breakwater tip.
+
+The second parent
+is an upstream source commit.
+It may sometimes contain a debian/ subdirectory,
+but if so that is to be ignored.
+The second parent's upstream files
+are identical to the anchor's.
Anchor merges always contain
C<[git-debrebase anchor: ...]>
as a line in the commit message.
+
Alternatively,
an anchor may be a single-parent commit which introduces
the C<debian/> directory and makes no other changes:
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 first parent.
-
-=item dgit dsc import
-
-Debian .dsc source package import(s) made by dgit.
-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.
-This is the form normally generated by dgit
-when it imports .dsc-based uploads.
+the one with the later commit date
+(or, if the commit dates are the same,
+the first parent)
+is treated as
+the contributing parent.
+
+=item dgit dsc import pseudomerge
+
+Debian .dsc source package import(s)
+made by dgit
+(during dgit fetch of a package most recently
+uploaded to Debian without dgit,
+or during dgit import-dsc).
+
+git-debrebase requires that
+each such import is in the fast-forwarding
+format produced by dgit:
+a two-parent pseudomerge,
+whose contributing parent is in the
+non-fast-forwarding
+dgit dsc import format (not described further here),
+and whose overwritten parent is
+the previous interchange tip
+(eg, the previous tip of the dgit suite branch).
=back
[git-debrebase[ COMMIT-TYPE [ ARGS...]]: PROSE, MORE PROSE]
-git-debrebase does not pay attention to anything after the colon,
-so PROSE is ignored.
+git-debrebase treats anything after the colon as a comment,
+paying no attention to PROSE.
The full set of annotations is:
[git-debrebase: split mixed commit, debian part]
[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: export and commit patches]
[git-debrebase convert-from-gbp: drop patches]
[git-debrebase anchor: declare upstream]
tags are added to the pre-existing commit message,
when git-debrebase rewrites the commit.
-=head1 TERMINOLOGY
-
-=over
-
-=item Pseudomerge
-
-A merge which does not actually merge the trees;
-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.
-Manual construction of pseudomerges can be done with
-C<git merge -s ours>
-but is not normally needed when using git-debrebase.
-
-=item Packaging files
-
-Files in the source tree within B<debian/>,
-excluding anything in B<debian/patches/>.
-
-=item Upstream
-
-The version of the package without Debian's packaging.
-Typically provided by the actual upstream project,
-and sometimes tracked by Debian contributors in a branch C<upstream>.
-
-Upstream contains upstream files,
-but some upstreams also contain packaging files in B<debian/>.
-Any such non-upstream files found in upstream
-are thrown away by git-debrebase
-each time a new upstream version is incorporated.
-
-=item Upstream files
-
-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, often deleted, and regenerated when needed,
-by git-debrebase.
-
-=back
-
=head1 APPENDIX - DGIT IMPORT HANDLING
+The dgit .dsc import format is not documented or specified
+(so some of the following terms are not defined anywhere).
+The dgit import format it is defined by the implementation in dgit,
+of which git-debrebase has special knowledge.
+
Consider a non-dgit NMU followed by a dgit NMU:
- interchange --/--B3!--%--/----D*-->
+ interchange --/--B3!--%--//----D*-->
/ /
% 4
/ 3
1 0 00 =XBC%
/
/
- --@--A breakwater
- /
- --#--------> upstream
+ --@--A breakwater
+ /
+ --#--------> upstream
Supplementary key:
=XBC% dgit tarball import of .debian.tar.gz containing
- Debian packaging including changes B C and quilt 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
- &_ dgit nearly-breakwater import
+ 00 dgit tarball import of supplementary upstream piece
+ &_ dgit import nearly-breakwater-anchor
+ // dgit fetch / import-dsc pseudomerge to make fast forward
+
&' git-debrebase converted import (upstream files only)
- D' git-debrebase converted debian/ changes import
+ C' git-debrebase converted packaging change import
* ** before and after HEAD
=item I. No new upstream version
(0 + 00 eq #)
- --/--B3!--%--/------D*-------------/-->
- / / /
- % 4 4**
- / 3 3
- / 2 2
- / 1 1
- 2 &_ /
- / /| \ /
+ --/--B3!--%--//-----D*-------------/-->
+ / / /
+ % 4 4**
+ / 3 3
+ / 2 2
+ / 1 1
+ 2 &_ /
+ / /| \ /
1 0 00 =XBC% /
- / /
- / /
- --@--A-----B-----------------------C--D
- /
- --#----------------------------------------->
+ / /
+ / /
+ --@--A-----B---------------------C'---D
+ /
+ --#----------------------------------------->
=item II. New upstream
(0 + 00 neq #)
- --/--B3!--%--/------D*-------------/-->
- / / /
- % 4 4**
- / 3 3
- / 2 2
- / 1 1
- 2 &_ /
- / /| \ /
+ --/--B3!--%--//-----D*-------------/-->
+ / / /
+ % 4 4**
+ / 3 3
+ / 2 2
+ / 1 1
+ 2 &_ /
+ / /| \ /
1 0 00 =XBC% /
- / /
- / /
- --@--A-----B--------------------@--C--D
- / /
- --#----------------------- - - / - - ----->
- /
- &'
- /|
- 0 00
+ / /
+ / /
+ --@--A-----B-----------------@---C'---D
+ / /
+ --#--------------------- - - / - - --------->
+ /
+ &'
+ /|
+ 0 00
=back
~ianmdlvl / dgit.git / blobdiff