Jon Seymour <jon.seymour@xxxxxxxxx> writes:
> Update the documentation to indicate that git stash branch only attempts
> to drop the specified stash if it looks like stash reference.
>
> Also changed the synopsis to more clearly indicate which commands require
> a stash entry reference as opposed to merely a stash-like commit.
>
> Signed-off-by: Jon Seymour <jon.seymour@xxxxxxxxx>
> ---
> Documentation/git-stash.txt | 37 ++++++++++++++++++++-----------------
> 1 files changed, 20 insertions(+), 17 deletions(-)
>
> diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
> index 473889a..499ac48 100644
> --- a/Documentation/git-stash.txt
> +++ b/Documentation/git-stash.txt
> @@ -9,10 +9,11 @@ SYNOPSIS
> --------
> [verse]
> 'git stash' list [<options>]
> -'git stash' show [<stash>]
> -'git stash' drop [-q|--quiet] [<stash>]
> -'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>]
> -'git stash' branch <branchname> [<stash>]
> +'git stash' show [<stash-like>]
> +'git stash' drop [-q|--quiet] [<stash-entry>]
> +'git stash' pop [--index] [-q|--quiet] [<stash-entry>]
> +'git stash' apply [--index] [-q|--quiet] [<stash-like>]
> +'git stash' branch <branchname> [<stash-like>]
> 'git stash' [save [--patch] [-k|--[no-]keep-index] [-q|--quiet] [<message>]]
> 'git stash' clear
> 'git stash' create
> @@ -80,15 +81,15 @@ 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 [<stash>]::
> +show [<stash-like>]::
>
> Show the changes recorded in the stash as a diff between the
> - stashed state and its original parent. When no `<stash>` is given,
> + stashed state and its original parent. When no `<stash-like>` is given,
> shows the latest one. By default, the command shows the diffstat, but
> it will accept any format known to 'git diff' (e.g., `git stash show
> -p stash@\{1}` to view the second most recent stash in patch form).
Hmm.
Is there anything that describes how <stash-like>, <stash-entry> and
<stash> relate to each other? I do not think a regular reader can answer
by reading the description after the patch these questions:
- Is a <stash-entry> a <stash-like>?
- Is the opposite true?
etc...
Perhaps we can simply call these two-parent merge commits a <stash>,
define that these commands as working on a <stash>, add notes to certain
subcommands that the <stash> they take must be on the stash ref (as
opposed to a freestanding one you can create with "stash create"), and be
done with it?
Also what is the error condition? I am assuming that your <stash-entry>
is a <stash-like> that is on the reflog of refs/stash, but if you give a
<stash-like> that is not a <stash-entry> (iow a freestanding <stash>) to a
subcommand that wants to see <stash-entry>, what happens, and does the
document describe it as an error?
> -pop [--index] [-q|--quiet] [<stash>]::
> +pop [--index] [-q|--quiet] [<stash-entry>]::
>
> Remove a single stashed state from the stash list and apply it
> on top of the current working tree state, i.e., do the inverse
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html