Subject: Re: [PATCH v2 1/9] git-stash.txt: be explicit about subcommand options

From: Junio C Hamano <[email-masked]>
Date: Tue, 09 Feb 2021 23:17:54 -0800

Denton Liu <[email-masked]> writes:

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

Makes sense.

> diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
> index 31f1beb65b..04e55eb826 100644
> --- 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
>  	Instead, all non-option arguments are concatenated to form the stash
>  	message.
>  
> -list [<options>]::
> +list [<log-options>]::
>  
>  	List the stash entries that you currently have.  Each 'stash entry' is
>  	listed with its name (e.g. `stash@{0}` is the latest entry, `stash@{1}` is
> @@ -83,7 +83,7 @@ stash@{1}: On master: 9cc0589... Add git-stash
>  The command takes options applicable to the 'git log'
>  command to control what is shown and how. See linkgit:git-log[1].
>  
> -show [<options>] [<stash>]::
> +show [<diff-options>] [<stash>]::
>  
>  	Show the changes recorded in the stash entry as a diff between the
>  	stashed contents and the commit back when the stash entry was first

This makes me wonder if we should also update the SYNOPSIS that
talks about the "list" and "show" operations taking a generic
"<options>", though.