git-debrebase(1),(5): More changes from conversation with Sean

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod
index 9140702339a470609ac6c5815fb4525731b3e8de..7e126246bfd9e534d2998591539956fc24025099 100644 (file)
--- a/git-debrebase.1.pod
+++ b/git-debrebase.1.pod
@@ -17,8 +17,11 @@ This is the command line reference.
 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
 
@@ -299,14 +302,15 @@ in the text for the relvant operation.
 
 =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
 

diff --git a/git-debrebase.5.pod b/git-debrebase.5.pod
index f749f628b6e0eeb2dfd6ca6ea9bd464b4e1a45fd..d3ecda88242e2c33b9484426a042708fe14fbd6c 100644 (file)
--- a/git-debrebase.5.pod
+++ b/git-debrebase.5.pod
@@ -34,7 +34,9 @@ derivatives, and it can make some things easier.
 =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.
@@ -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),
 by git-debrebase.
 
 =back
@@ -148,7 +151,8 @@ 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).
+(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.
+
 Alternatively,
 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
+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
 
@@ -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]