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

[Junio C Hamano <gitster@pobox.com>]

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

> Interdiff below:

Thanks.  Looks much more polished.

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