2 files changed, 61 insertions, 37 deletions
diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod
index 9140702..7e12624 100644
@@ -17,8 +17,11 @@ This is the command line reference.
Please read the tutorial
For background, theory of operation,
-and definitions of the terms used here,
+and definitions see L<git-debrebase(5)>.
+You should read this manpage in conjunction with
+which defines many important terms used here.
=head1 PRINCIPAL OPERATIONS
@@ -299,14 +302,15 @@ in the text for the relvant operation.
-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,
+it is a problem if <commit-ish> is the anchor
+for the previous upstream version in
+git-debrebase new-upstream operations.
diff --git a/git-debrebase.5.pod b/git-debrebase.5.pod
index f749f62..d3ecda8 100644
@@ -34,7 +34,9 @@ derivatives, and it can make some things easier.
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.
@@ -74,7 +76,8 @@ a series of git commits.
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),
@@ -148,7 +151,8 @@ 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).
+(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
@@ -188,17 +192,24 @@ 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 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.
an anchor may be a single-parent commit which introduces
the C<debian/> directory and makes no other changes:
@@ -287,21 +298,30 @@ 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 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
+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).
@@ -457,8 +477,8 @@ The general form is
[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]