From: Eric Sunshine <sunshine@sunshineco.com>
Date: Tue, 02 Feb 2021 17:37:07 GMT
Subject: Re: [PATCH 1/9] git-stash.txt: be explicit about subcommand options
Message-ID: <CAPig+cRuD19xwfmkn2E4669n+0BPJg24NBOp-Zjv9uKDTXedFA@mail.gmail.com>
In-Reply-To: <17675b9e4c0c50e6bfd5219c933b5ba1148ab86c.1612258145.git.liu.denton@gmail.com>

On Tue, Feb 2, 2021 at 4:36 AM Denton Liu <liu.denton@gmail.com> wrote:
> Currently, the options for the `list` and `show` subcommands are just
> listed as `<options>`. This seems to imply, from a cursory glance at the
> summary, that they take the stash options listed below. However, reading
> more carefully, we see that they take log options and diff options
> respectively.
>
> Make it more obvious that they take log and diff options by explicitly
> stating this in the subcommand summary.
>
> Signed-off-by: Denton Liu <liu.denton@gmail.com>
> ---
> diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
> @@ -67,7 +67,7 @@ save [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q
> -list [<options>]::
> +list [<log options>]::
>
> -show [<options>] [<stash>]::
> +show [<diff options>] [<stash>]::

I might suggest that it is more common to hyphenate these words than
to separate them with spaces:

    list [<log-options>]::
    show [<diff-options>] [<stash>]::