Re: [PATCH v3 0/3] deprecate git stash save

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 23, 2017, 01:19 UTC
Message-ID: <xmqqwp3md5jp.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <20171022170409.8565-1-t.gummerer@gmail.com>

Thomas Gummerer <t.gummerer@gmail.com> writes:

> Interdiff below:

Thanks.  Looks much more polished.

Show 13 quoted lines

>
> diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
> index 89b6a0e672..8be661007d 100644
> --- a/Documentation/git-stash.txt
> +++ b/Documentation/git-stash.txt
> @@ -86,7 +86,9 @@ The `--patch` option implies `--keep-index`.  You can use
>  
>  save [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [<message>]::
>  
> -	This option is deprecated in favour of 'git stash push'.
> +	This option is deprecated in favour of 'git stash push'.  It
> +	differs from "stash push" in that it cannot take pathspecs,
> +	and any non-option arguments form the message.

Every time I saw this line, I misread s/form/from/ and got confused.

I know the below is what the above wants the readers to eventually [*1*] know:

        'git stash save' cannot take pathspecs (nor it can be
        enhanced with new options in the future) because any
        non-option argument to it is treated as the message and has
        been deprecated.  'git stash push' supersedes 'git stash
        save'; it corrects the command line syntax by requiring '-m'
        before the message.

but I feel that the text in your patch still does not read clearly enough. But it may only be me.

Thanks.

[Footnote]

*1* By "eventually" what I mean is that it may not be necessarily a good idea to lay it out all to the reader here at this point in the document---they may not care why a subcommand is being deprecated, but for those who want to know, we need to write it down somewhere.