From: Jon Seymour <jon.seymour@gmail.com>
Date: Sat, 14 Aug 2010 00:30:25 GMT
Subject: Re: [PATCH v4 9/9] Documentation: git stash branch now tolerates non-stash references.
Message-ID: <AANLkTi=U5HaHvXMjum3zpZgBRD68gPN=vk7f8iy7Q-VM@mail.gmail.com>
In-Reply-To: <7vr5i3mj4h.fsf@alter.siamese.dyndns.org>

On Fri, Aug 13, 2010 at 10:49 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Jon Seymour <jon.seymour@gmail.com> writes:
>
> 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
>

Ok, I'll have another crack at it, and address the other issues you
have noted in another round.

Thanks for the review.

jon.