[docs] git stash show also accepts -p|--patch option

[docs] git stash show also accepts -p|--patch option

[Elijah Lynn]

Was reading `git help stash`and noticed the --patch option says:

> This option is only valid for `push` and `save` commands.

But this isn't true, the `git stash show` command also accepts the
--patch command and is very useful as it shows the diff of the stash
whereas without --patch it just shows the filenames that changed. I
see this text in master too
https://github.com/git/git/blob/master/Documentation/git-stash.txt.

I can gladly submit a patch if this will be acceptable to update the
docs to state that -p|--patch is applicable to the `show` command as
well.

Elijah Lynn
www.elijahlynn.net

Re: [docs] git stash show also accepts -p|--patch option

[Martin Ågren]

Hi Elijah,

Welcome to the list. :-)

On Mon, 20 Apr 2020 at 09:36, Elijah Lynn <elijah@elijahlynn.net> wrote:
>
> Was reading `git help stash`and noticed the --patch option says:
>
> > This option is only valid for `push` and `save` commands.
>
> But this isn't true, the `git stash show` command also accepts the
> --patch command and is very useful as it shows the diff of the stash
> whereas without --patch it just shows the filenames that changed. I
> see this text in master too
> https://github.com/git/git/blob/master/Documentation/git-stash.txt.

Interesting!

There are two *different* "--patch" involved here. One is used to
interactively select hunks with "push" and "save". Another is the one
from the "git-log/diff" machinery. This is the one that can be used with
"git stash show" and "git stash list". That is, "git stash show" doesn't
really know about it -- it just passes on "--patch" and other arguments.

For example, for "list", the manpage for git-stash says "The command
takes options applicable to the git log command to control what is shown
and how. See git-log(1)."

So there are in a sense lots of options that aren't documented in
git-stash(1). But certainly "--patch" is a bit special in that there are
basically two *different* options by the same name.

> I can gladly submit a patch if this will be acceptable to update the
> docs to state that -p|--patch is applicable to the `show` command as
> well.

I think it could be useful to be a bit clearer about this. One question
is how... :-) Maybe under "--patch" one could make some short mention of
this. Perhaps

  (`--patch` can also be used with "show" and "list", but that is
  'another' `--patch`, see ....)

? Maybe you have other ideas?

Thanks
Martin