[PATCH] notes: fix erroneous "git notes prune [-n | -v]" message

[PATCH] notes: fix erroneous "git notes prune [-n | -v]" message

[Robert P. J. Day]

It seems clear that the man page SYNPOSIS and the usage message
referring to:

  git notes prune [-n | -v]

is incorrect, as "-n" (dry run) and "-v" (verbose) are not
alternatives, so fix both places to refer to:

  git notes prune [-n] [-v | -q]

to match the rest of the man page.

Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>

---

diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index 43677297f..c75748963 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -18,7 +18,7 @@ SYNOPSIS
 'git notes' merge --commit [-v | -q]
 'git notes' merge --abort [-v | -q]
 'git notes' remove [--ignore-missing] [--stdin] [<object>...]
-'git notes' prune [-n | -v]
+'git notes' prune [-n] [-v | -q]
 'git notes' get-ref


diff --git a/builtin/notes.c b/builtin/notes.c
index d7754db14..43bfe3d6a 100644
--- a/builtin/notes.c
+++ b/builtin/notes.c
@@ -33,7 +33,7 @@ static const char * const git_notes_usage[] = {
 	N_("git notes merge --commit [-v | -q]"),
 	N_("git notes merge --abort [-v | -q]"),
 	N_("git notes [--ref <notes-ref>] remove [<object>...]"),
-	N_("git notes [--ref <notes-ref>] prune [-n | -v]"),
+	N_("git notes [--ref <notes-ref>] prune [-n] [-v | -q]"),
 	N_("git notes [--ref <notes-ref>] get-ref"),
 	NULL
 };

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

Re: [PATCH] notes: fix erroneous "git notes prune [-n | -v]" message

[Jonathan Nieder]

Hi,

Robert P. J. Day wrote:

> It seems clear that the man page SYNPOSIS and the usage message
> referring to:
>
>   git notes prune [-n | -v]
>
> is incorrect, as "-n" (dry run) and "-v" (verbose) are not
> alternatives, so fix both places to refer to:
>
>   git notes prune [-n] [-v | -q]
>
> to match the rest of the man page.
>
> Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
> ---

Hm.  What does "git notes prune -q" do?

The docs describe what --dry-run and --verbose do for "git notes prune"
but its description of --quiet seems to be specific to "git notes
merge".  Should the usage summary be

 git notes [--ref=<notes-ref>] prune [-n] [-v]

instead?  That would also be consistent with "git notes prune -h":

  $ git notes prune -h
  usage: git notes prune [<options>]

      -n, --dry-run         do not remove, show only
      -v, --verbose         report pruned notes

Thanks,
Jonathan

Re: [PATCH] notes: fix erroneous "git notes prune [-n | -v]" message

[Robert P. J. Day]

On Tue, 21 Nov 2017, Jonathan Nieder wrote:

> Hi,
>
> Robert P. J. Day wrote:
>
> > It seems clear that the man page SYNPOSIS and the usage message
> > referring to:
> >
> >   git notes prune [-n | -v]
> >
> > is incorrect, as "-n" (dry run) and "-v" (verbose) are not
> > alternatives, so fix both places to refer to:
> >
> >   git notes prune [-n] [-v | -q]
> >
> > to match the rest of the man page.
> >
> > Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
> > ---
>
> Hm.  What does "git notes prune -q" do?
>
> The docs describe what --dry-run and --verbose do for "git notes prune"
> but its description of --quiet seems to be specific to "git notes
> merge".  Should the usage summary be
>
>  git notes [--ref=<notes-ref>] prune [-n] [-v]
>
> instead?  That would also be consistent with "git notes prune -h":
>
>   $ git notes prune -h
>   usage: git notes prune [<options>]
>
>       -n, --dry-run         do not remove, show only
>       -v, --verbose         report pruned notes

  you're right ... i'm just getting familiar with the whole
parse-options.h stuff, and confused OPT__VERBOSE with OPT__VERBOSITY:

  #define OPT__VERBOSE(var, h)  OPT_COUNTUP('v', "verbose", (var), (h))
  #define OPT__QUIET(var, h)    OPT_COUNTUP('q', "quiet",   (var), (h))
  #define OPT__VERBOSITY(var) \
        { OPTION_CALLBACK, 'v', "verbose", (var), NULL, N_("be more verbose"), \
          PARSE_OPT_NOARG, &parse_opt_verbosity_cb, 0 }, \
        { OPTION_CALLBACK, 'q', "quiet", (var), NULL, N_("be more quiet"), \
          PARSE_OPT_NOARG, &parse_opt_verbosity_cb, 0 }

so it should simply be corrected to:

  git notes prune [-n] [-v]

sound about right?

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

Re: [PATCH] notes: fix erroneous "git notes prune [-n | -v]" message

[Jonathan Nieder]

Robert P. J. Day wrote:

> so it should simply be corrected to:
>
>   git notes prune [-n] [-v]
>
> sound about right?

Sounds good to me.

Thanks for finding these confusing docs, by the way.

Jonathan