git-debrebase: avoid stack trace from badusage()

[dgit.git] / git-debrebase.1.pod

diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod
index 9140702339a470609ac6c5815fb4525731b3e8de..ae095c8c194097e794ebd0b441ac6857a9d84df9 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,
 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
 
 
 =head1 PRINCIPAL OPERATIONS
 


@@ -52,7 +55,7 @@ consuming ffq-prev.
 
 If there is no ffq-prev, it is an error, unless --noop-ok.
 
 
 If there is no ffq-prev, it is an error, unless --noop-ok.
 

-It is a problem if the branch is not laundered.
+It is a snag (see B<-f>) if the branch is not laundered.

 
 =item git-debrebase new-upstream-v0 <new-version> [<upstream-details>...]
 
 
 =item git-debrebase new-upstream-v0 <new-version> [<upstream-details>...]
 


@@ -60,7 +63,7 @@ Rebases the delta queue
 onto a new upstream version.  In detail:
 
 Firstly, checks that the proposed rebase seems to make sense:
 onto a new upstream version.  In detail:
 
 Firstly, checks that the proposed rebase seems to make sense:

-It is a problem unless the new upstream(s)
+It is a snag unless the new upstream(s)

 are fast forward from the previous upstream(s)
 as found in the current breakwater anchor.
 And, in the case of a multi-piece upstream
 are fast forward from the previous upstream(s)
 as found in the current breakwater anchor.
 And, in the case of a multi-piece upstream


@@ -98,7 +101,7 @@ The <upstream-details> are, optionally, in order:
 The new upstream branch (or commit-ish).
 Default is C<upstream>.
 
 The new upstream branch (or commit-ish).
 Default is C<upstream>.
 

-It is a problem if the upstream contains a debian/ directory;
+It is a snag if the upstream contains a debian/ directory;

 if forced to proceed,
 git-debrebase will disregard the upstream's debian/ and
 take (only) the packaging from the current breakwater.
 if forced to proceed,
 git-debrebase will disregard the upstream's debian/ and
 take (only) the packaging from the current breakwater.


@@ -167,11 +170,11 @@ and dropping the patches from the tree.
 
 The upstream commit-ish should correspond to
 the gbp upstream branch, if there is one.
 
 The upstream commit-ish should correspond to
 the gbp upstream branch, if there is one.

-It is a problem if it is not an ancestor of HEAD,
+It is a snag if it is not an ancestor of HEAD,

 or if the history between the upstream and HEAD
 contains commits which make changes to upstream files.
 
 or if the history between the upstream and HEAD
 contains commits which make changes to upstream files.
 

-It is also a problem if the specified upstream
+It is also a snag if the specified upstream

 has a debian/ subdirectory.
 This check exists to detect certain likely user errors,
 but if this situation is true and expected,
 has a debian/ subdirectory.
 This check exists to detect certain likely user errors,
 but if this situation is true and expected,


@@ -262,31 +265,31 @@ docuented under each operation.
 
 =over
 
 
 =over
 

-=item -f<problem-id>
+=item -f<snag-id>

 
 

-Turns problems with id <problem-id> into warnings.
+Turns snag(s) with id <snag-id> into warnings.

 
 Some troublesome things which git-debrebase encounters
 
 Some troublesome things which git-debrebase encounters

-are B<problem>s.
+are B<snag>s.

 (The specific instances are discussed
 in the text for the relvant operation.)
 
 (The specific instances are discussed
 in the text for the relvant operation.)
 

-When a problem is detected,
-a message is printed to stderr containing the problem id
-(in the form C<-f<problem-idE<gt>>),
+When a snag is detected,
+a message is printed to stderr containing the snag id
+(in the form C<-f<snag-idE<gt>>),

 along with some prose.
 
 along with some prose.
 

-If problems are detected, git-debrebase does not continue,
-unless the relevant -f<problem-id> is specified,
+If snags are detected, git-debrebase does not continue,
+unless the relevant -f<snag-id> is specified,

 or --force is specified.
 
 =item --force
 
 or --force is specified.
 
 =item --force
 

-Turns all problems into warnings.
-See the -f<problem-id> option.
+Turns all snags into warnings.
+See the -f<snag-id> option.

 
 Do not invoke git-debrebase --force in scripts and aliases;
 
 Do not invoke git-debrebase --force in scripts and aliases;

-instead, specify the particular -f<problem-id> for expected problems.
+instead, specify the particular -f<snag-id> for expected snags.

 
 =item --noop-ok
 
 
 =item --noop-ok
 


@@ -299,14 +302,16 @@ in the text for the relvant operation.
 
 =item --anchor=<commit-ish>
 
 
 =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 logic which automatically classifies
+commits as anchors, pseudomerges, delta queue commits, etc.

 
 

-(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 snag if <commit-ish> is the anchor
+for the previous upstream version in
+git-debrebase new-upstream operations.

 
 =item -D
 
 
 =item -D
 


@@ -358,7 +363,7 @@ branch.<branch>.ffq-ffrefs,
 which is a semicolon-separated list of glob patterns,
 each optionally preceded by !; first match wins.
 
 which is a semicolon-separated list of glob patterns,
 each optionally preceded by !; first match wins.
 

-In each case it is a problem if
+In each case it is a snag if

 the local HEAD is behind the checked remote,
 or if local HEAD has diverged from it.
 All the checks are done locally using the remote tracking refs:
 the local HEAD is behind the checked remote,
 or if local HEAD has diverged from it.
 All the checks are done locally using the remote tracking refs: