git-debrebase: Rename `problem'/`fproblem' to `snag'

And add a cross-reference the first time it's mentioned in the
manpage.

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

diff --git a/git-debrebase b/git-debrebase
index 00e55884abeb67a1dc676b3ad8ec67eee5311931..882614195d2ba6068d8a989018f963ce429d8843 100755 (executable)
--- a/git-debrebase
+++ b/git-debrebase
@@ -224,40 +224,40 @@ sub make_commit ($$) {
     return cmdoutput @cmd;
 }
 
-our @fproblem_force_opts;
-our $fproblems_forced;
-our $fproblems_tripped;
-sub fproblem ($$) {
+our @snag_force_opts;
+our $snags_forced;
+our $snags_tripped;
+sub snag ($$) {
     my ($tag,$msg) = @_;
-    if (grep { $_ eq $tag } @fproblem_force_opts) {
-       $fproblems_forced++;
-       print STDERR "git-debrebase: safety catch overridden (-f$tag): $msg\n";
+    if (grep { $_ eq $tag } @snag_force_opts) {
+       $snags_forced++;
+       print STDERR "git-debrebase: snag ignored (-f$tag): $msg\n";
     } else {
-       $fproblems_tripped++;
-       print STDERR "git-debrebase: safety catch tripped (-f$tag): $msg\n";
+       $snags_tripped++;
+       print STDERR "git-debrebase: snag detected (-f$tag): $msg\n";
     }
 }
 
-sub fproblems_maybe_bail () {
-    if ($fproblems_forced) {
+sub snags_maybe_bail () {
+    if ($snags_forced) {
        printf STDERR
-           "%s: safety catch trips: %d overriden by individual -f options\n",
-           $us, $fproblems_forced;
+           "%s: snags: %d overriden by individual -f options\n",
+           $us, $snags_forced;
     }
-    if ($fproblems_tripped) {
+    if ($snags_tripped) {
        if ($opt_force) {
            printf STDERR
-               "%s: safety catch trips: %d overriden by global --force\n",
-               $us, $fproblems_tripped;
+               "%s: snags: %d overriden by global --force\n",
+               $us, $snags_tripped;
        } else {
            fail sprintf
-  "%s: safety catch trips: %d blockers (you could -f<tag>, or --force)",
-               $us, $fproblems_tripped;
+  "%s: snags: %d blockers (you could -f<tag>, or --force)",
+               $us, $snags_tripped;
        }
     }
 }
-sub any_fproblems () {
-    return $fproblems_forced || $fproblems_tripped;
+sub any_snags () {
+    return $snags_forced || $snags_tripped;
 }
 
 # classify returns an info hash like this
@@ -946,7 +946,7 @@ sub record_ffq_prev_deferred () {
     #    detached
     #    weird-symref
     #    notbranch
-    # if not ff from some branch we should be ff from, is an fproblem
+    # if not ff from some branch we should be ff from, is an snag
     # if "deferred", will have added something about that to
     #   @deferred_update_messages, and also maybe printed (already)
     #   some messages about ff checks
@@ -986,10 +986,10 @@ sub record_ffq_prev_deferred () {
            $checked{$lrref} = 1;
        } elsif (is_fast_fwd $currentval, $lrval) {
            $checked{$lrref} = -1;
-           fproblem 'behind', "you are behind $lrref, divergence risk";
+           snag 'behind', "you are behind $lrref, divergence risk";
        } else {
            $checked{$lrref} = -1;
-           fproblem 'diverged', "you have diverged from $lrref";
+           snag 'diverged', "you have diverged from $lrref";
        }
     };
 
@@ -1015,7 +1015,7 @@ sub record_ffq_prev_deferred () {
        $check->("refs/remotes/dgit/dgit/sid", 'remote dgit branch for sid');
     }
 
-    fproblems_maybe_bail();
+    snags_maybe_bail();
 
     push @deferred_updates, "update $ffq_prev $currentval $git_null_obj";
     push @deferred_updates, "delete $gdrlast";
@@ -1027,8 +1027,8 @@ sub record_ffq_auto () {
     my ($status, $message) = record_ffq_prev_deferred();
     if ($status eq 'deferred' || $status eq 'exists') {
     } else {
-       fproblem $status, "could not record ffq-prev: $message";
-       fproblems_maybe_bail();
+       snag $status, "could not record ffq-prev: $message";
+       snags_maybe_bail();
     }
 }
 
@@ -1037,8 +1037,8 @@ sub ffq_prev_info () {
     my ($status, $message, $current, $ffq_prev, $gdrlast)
        = ffq_prev_branchinfo();
     if ($status ne 'branch') {
-       fproblem $status, "could not check ffq-prev: $message";
-       fproblems_maybe_bail();
+       snag $status, "could not check ffq-prev: $message";
+       snags_maybe_bail();
     }
     my $ffq_prev_commitish = $ffq_prev && git_get_ref $ffq_prev;
     return ($ffq_prev, $gdrlast, $ffq_prev_commitish);
@@ -1128,7 +1128,7 @@ sub cmd_new_upstream_v0 () {
     my $old_anchor_cl = classify $old_anchor;
     my $old_upstream;
     if (!$old_anchor_cl->{OrigParents}) {
-       fproblem 'anchor-treated',
+       snag 'anchor-treated',
            'old anchor is recognised due to --anchor, cannot check upstream';
     } else {
        $old_upstream = parsecommit
@@ -1147,7 +1147,7 @@ sub cmd_new_upstream_v0 () {
                $piece->($n, Old => $old_upstream->{CommitId}.'^'.$parentix);
            }
        } else {
-           fproblem 'upstream-confusing',
+           snag 'upstream-confusing',
                "previous upstream $old_upstream->{CommitId} is from".
                " git-debrebase but not an \`upstream-combine' commit";
        }
@@ -1157,13 +1157,13 @@ sub cmd_new_upstream_v0 () {
        if (!$old_upstream) {
            # we have complained already
        } elsif (!$pc->{Old}) {
-           fproblem 'upstream-new-piece',
+           snag 'upstream-new-piece',
                "introducing upstream piece \`$pc->{Name}'";
        } elsif (!$pc->{New}) {
-           fproblem 'upstream-rm-piece',
+           snag 'upstream-rm-piece',
                "dropping upstream piece \`$pc->{Name}'";
        } elsif (!is_fast_fwd $pc->{Old}, $pc->{New}) {
-           fproblem 'upstream-not-ff',
+           snag 'upstream-not-ff',
                "not fast forward: $pc->{Name} $pc->{Old}..$pc->{New}";
        }
     }
@@ -1171,7 +1171,7 @@ sub cmd_new_upstream_v0 () {
     printdebug "%pieces = ", (dd \%pieces), "\n";
     printdebug "\@newpieces = ", (dd \@newpieces), "\n";
 
-    fproblems_maybe_bail();
+    snags_maybe_bail();
 
     my $new_bw;
 
@@ -1179,7 +1179,7 @@ sub cmd_new_upstream_v0 () {
     in_workarea sub {
        my @upstream_merge_parents;
 
-       if (!any_fproblems()) {
+       if (!any_snags()) {
            push @upstream_merge_parents, $old_upstream->{CommitId};
        }
 
@@ -1293,7 +1293,7 @@ sub cmd_stitch () {
     }
     my $old_head = get_head();
 
-    keycommits $old_head, \&fproblem, \&fproblem, \&fproblem;
+    keycommits $old_head, \&snag, \&snag, \&snag;
 
     stitch($old_head, $ffq_prev, $gdrlast, $ffq_prev_commitish, $prose);
 }
@@ -1315,25 +1315,25 @@ sub cmd_convert_from_gbp () {
     }
 
     if (!is_fast_fwd $upstream, $old_head) {
-       fproblem 'upstream-not-ancestor',
+       snag 'upstream-not-ancestor',
            "upstream ($upstream) is not an ancestor of HEAD";
     } else {
        my $wrong = cmdoutput
            (@git, qw(rev-list --ancestry-path), "$upstream..HEAD",
             qw(-- :/ :!/debian));
        if (length $wrong) {
-           fproblem 'unexpected-upstream-changes',
+           snag 'unexpected-upstream-changes',
                "history between upstream ($upstream) and HEAD contains direct changes to upstream files - are you sure this is a gbp (patches-unapplied) branch?";
            print STDERR "list expected changes with:  git log --stat --ancestry-path $upstream_spec..HEAD -- :/ ':!/debian'\n";
        }
     }
 
     if ((git_cat_file "$upstream:debian")[0] ne 'missing') {
-       fproblem 'upstream-has-debian',
+       snag 'upstream-has-debian',
            "upstream ($upstream) contains debian/ directory";
     }
 
-    fproblems_maybe_bail();
+    snags_maybe_bail();
 
     my $work;
 
@@ -1447,7 +1447,7 @@ sub cmd_downstream_rebase_launder_v0 () {
 
 GetOptions("D+" => \$debuglevel,
           'noop-ok', => \$opt_noop_ok,
-          'f=s' => \@fproblem_force_opts,
+          'f=s' => \@snag_force_opts,
           'anchor=s' => \@opt_anchors,
           'force!') or die badusage "bad options\n";
 initdebug('git-debrebase ');

diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod
index a91ad3a74e88b9d405694d24064d37a9e1c23ace..ae095c8c194097e794ebd0b441ac6857a9d84df9 100644 (file)
--- a/git-debrebase.1.pod
+++ b/git-debrebase.1.pod
@@ -55,7 +55,7 @@ consuming ffq-prev.
 
 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>...]
 
@@ -63,7 +63,7 @@ Rebases the delta queue
 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
@@ -101,7 +101,7 @@ The <upstream-details> are, optionally, in order:
 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.
@@ -170,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.
-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.
 
-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,
@@ -265,31 +265,31 @@ docuented under each operation.
 
 =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
-are B<problem>s.
+are B<snag>s.
 (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.
 
-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
 
-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;
-instead, specify the particular -f<problem-id> for expected problems.
+instead, specify the particular -f<snag-id> for expected snags.
 
 =item --noop-ok
 
@@ -309,7 +309,7 @@ commits as anchors, pseudomerges, delta queue commits, etc.
 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
+it is a snag if <commit-ish> is the anchor
 for the previous upstream version in
 git-debrebase new-upstream operations.
 
@@ -363,7 +363,7 @@ branch.<branch>.ffq-ffrefs,
 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: