[PATCH v2] doc: Add missing "-n" (dry-run) option to reflog man page

[PATCH v2] doc: Add missing "-n" (dry-run) option to reflog man page

[Robert P. J. Day]

While the "git reflog" man page supports both "--dry-run" and "-n" for
a dry run, the man page mentions only the former, not the latter.

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

---

  sorry, i accidentally chopped off the leading lines of the patch in
the earlier post.

diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt
index 44c736f1a..472a6808c 100644
--- a/Documentation/git-reflog.txt
+++ b/Documentation/git-reflog.txt
@@ -20,9 +20,9 @@ depending on the subcommand:
 'git reflog' ['show'] [log-options] [<ref>]
 'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]
 	[--rewrite] [--updateref] [--stale-fix]
-	[--dry-run] [--verbose] [--all | <refs>...]
+	[--dry-run | -n] [--verbose] [--all | <refs>...]
 'git reflog delete' [--rewrite] [--updateref]
-	[--dry-run] [--verbose] ref@\{specifier\}...
+	[--dry-run | -n] [--verbose] ref@\{specifier\}...
 'git reflog exists' <ref>

 Reference logs, or "reflogs", record when the tips of branches and


-- 

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

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

Re: [PATCH v2] doc: Add missing "-n" (dry-run) option to reflog man page

[Junio C Hamano]

"Robert P. J. Day" <rpjday@crashcourse.ca> writes:

> While the "git reflog" man page supports both "--dry-run" and "-n" for
> a dry run, the man page mentions only the former, not the latter.
>
> Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
>
> ---

I have a suspicion that this was deliberately omitted in order to
keep the lines in the description short and concise.  Just adding
5-columns may appear not to hurt too much, but these things tend to
accumulate, so...

Queued, so that I won't lose sight of it, but won't merge unless
somebody else strongly feels about it.

Thanks.

>
>   sorry, i accidentally chopped off the leading lines of the patch in
> the earlier post.
>
> diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt
> index 44c736f1a..472a6808c 100644
> --- a/Documentation/git-reflog.txt
> +++ b/Documentation/git-reflog.txt
> @@ -20,9 +20,9 @@ depending on the subcommand:
>  'git reflog' ['show'] [log-options] [<ref>]
>  'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]
>  	[--rewrite] [--updateref] [--stale-fix]
> -	[--dry-run] [--verbose] [--all | <refs>...]
> +	[--dry-run | -n] [--verbose] [--all | <refs>...]
>  'git reflog delete' [--rewrite] [--updateref]
> -	[--dry-run] [--verbose] ref@\{specifier\}...
> +	[--dry-run | -n] [--verbose] ref@\{specifier\}...
>  'git reflog exists' <ref>
>
>  Reference logs, or "reflogs", record when the tips of branches and

Re: [PATCH v2] doc: Add missing "-n" (dry-run) option to reflog man page

[Robert P. J. Day]

On Wed, 22 Nov 2017, Junio C Hamano wrote:

> "Robert P. J. Day" <rpjday@crashcourse.ca> writes:
>
> > While the "git reflog" man page supports both "--dry-run" and "-n" for
> > a dry run, the man page mentions only the former, not the latter.
> >
> > Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
> >
> > ---
>
> I have a suspicion that this was deliberately omitted in order to
> keep the lines in the description short and concise.  Just adding
> 5-columns may appear not to hurt too much, but these things tend to
> accumulate, so...
>
> Queued, so that I won't lose sight of it, but won't merge unless
> somebody else strongly feels about it.

  i appreciate the need for brevity, but this just takes us back to,
is there a standard for man pages, given how they bounce around all
over the place?

  i tossed in that missing "-n" option for "man git-reflog" since it
was the *only* option missing from the SYNOPSIS, and it didn't mess up
the aesthetics. but there are other examples that clearly aren't worth
the trouble:

  $ man git-clean
  SYNOPSIS
    git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>...

where *only* the short forms are used in the SYNOPSIS.

  and, finally, there are examples that mix and match, like:

  $ man git-commit
  SYNOPSIS
    git commit [-a | --interactive | --patch] ...

which uses "-a" instead of "--all", but "--patch" instead of "-p". i'm
fine if someone says, "there is no standard," but if there is, then
the docs should follow them.

  thoughts?

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 v2] doc: Add missing "-n" (dry-run) option to reflog man page

[Junio C Hamano]

"Robert P. J. Day" <rpjday@crashcourse.ca> writes:

>   i appreciate the need for brevity, but this just takes us back to,
> is there a standard for man pages, given how they bounce around all
> over the place?
>
>   i tossed in that missing "-n" option for "man git-reflog" since it
> was the *only* option missing from the SYNOPSIS,...

Don't we also take "-v" for "--verbose"?

I am not sure what you meant by "bounce around", but by adding "-n"
without adding "-v", doesn't this patch worsen the situation by
making the result even locally inconsistent?

Re: [PATCH v2] doc: Add missing "-n" (dry-run) option to reflog man page

[Robert P. J. Day]

On Wed, 22 Nov 2017, Junio C Hamano wrote:

> "Robert P. J. Day" <rpjday@crashcourse.ca> writes:
>
> >   i appreciate the need for brevity, but this just takes us back
> > to, is there a standard for man pages, given how they bounce
> > around all over the place?
> >
> >   i tossed in that missing "-n" option for "man git-reflog" since
> > it was the *only* option missing from the SYNOPSIS,...
>
> Don't we also take "-v" for "--verbose"?
>
> I am not sure what you meant by "bounce around", but by adding "-n"
> without adding "-v", doesn't this patch worsen the situation by
> making the result even locally inconsistent?

  i don't believe "git reflog" supports "-v", only "--verbose", or am
i misreading the source?

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 v2] doc: Add missing "-n" (dry-run) option to reflog man page

[Junio C Hamano]

"Robert P. J. Day" <rpjday@crashcourse.ca> writes:

>   i don't believe "git reflog" supports "-v", only "--verbose", or am
> i misreading the source?

Ah, then at least you are being (locally) consistent.  Sorry for a
remembo.

As to (global) consistency, in the oldest time we tried to list
every options (but only in the fully spelled form, IIRC) in the
synopsis section, but later with the proliferation of options, it
became more common to use the generic "git subcmd <options>..." form
in synopsis and leave not just the description but also the
enumeration of the options to the description part of the docs, so
we ended up with a mixture in the documentation set.  Aiming for
global consistency is a very good thing, and we need to decide what
model to adhere to and stick to it to the end.  If you want to carry
the torch and declare that we would list every option and every
short-hand (but not "--v", "--ve", "--ver", ..."--verbose" for
obvious reasons), I personally am fine with that.