Please read the tutorial
L<dgit-maint-debrebase(5)>.
For background, theory of operation,
-and definitions of the terms used here,
-see L<git-debrebase(5)>.
+and definitions see L<git-debrebase(5)>.
+
+You should read this manpage in conjunction with
+L<git-debrebase(5)/TERMINOLOGY>,
+which defines many important terms used here.
=head1 PRINCIPAL OPERATIONS
=item --anchor=<commit-ish>
-Treats <commit-ish> as an anchor,
-regardless of what it's actually like.
+Treats <commit-ish> as an anchor.
+This overrides the usual automatic commit classification logic.
-(It is a problem for
-git-debrebase new-upstream operations
-if <commit-ish> is the previous anchor to be used,
-because treating an arbitrary commit as an anchor
-means forgoing upstream coherency checks.)
+It also disables some coherency checks
+which depend on metadata extracted from its commit message,
+so
+it is a problem if <commit-ish> is the anchor
+for the previous upstream version in
+git-debrebase new-upstream operations.
=item -D
=item Pseudomerge
A merge which does not actually merge the trees;
-instead, it takes its tree, by construction, from only one parent.
+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.
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,
+Not used, often deleted, and regenerated when needed
+(such as when uploading to Debian),
by git-debrebase.
=back
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]