threads / patch / 47272

v2doc: Add missing "-n" (dry-run) option to reflog man page

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

## tl;dr

6 messages between Nov 21, 2017 and Nov 22, 2017. Diffs are folded; open one to read it.

replies: 5people: 2as markdown or json

Robert P. J. Day· Nov 21, 2017, 15:39 UTC · lore

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.
Show changes to Documentation/git-reflog.txt +2 −2
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
========================================================================
Junio C Hamano· Nov 22, 2017, 03:28 UTC · re: Robert P. J. Day · lore

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

"Robert P. J. Day" <rpjday@crashcourse.ca> writes:
Show 6 quoted lines
> 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.
Show 20 quoted lines
>
>   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· Nov 22, 2017, 07:59 UTC · re: Junio C Hamano · lore

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

On Wed, 22 Nov 2017, Junio C Hamano wrote:
Show 16 quoted lines
> "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
========================================================================
Junio C Hamano· Nov 22, 2017, 10:41 UTC · re: Robert P. J. Day · lore

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

"Robert P. J. Day" <rpjday@crashcourse.ca> writes:
Show 6 quoted lines
>   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?

Robert P. J. Day· Nov 22, 2017, 10:45 UTC · re: Junio C Hamano · lore

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

On Wed, 22 Nov 2017, Junio C Hamano wrote:
Show 14 quoted lines
> "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
========================================================================
Junio C Hamano· Nov 22, 2017, 16:03 UTC · re: Robert P. J. Day · lore

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

"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.

← back to recent threads