From: しらいしななこ <nanako3@bluebottle.com>
Date: Sun, 01 Jul 2007 09:06:29 GMT
Subject: Re: [PATCH] Document git-stash
Message-ID: <200707010910.l619A23b027837@mi0.bluebottle.com>
In-Reply-To: <20070701080757.GA6093@coredump.intra.peff.net>

Hi,

Quoting Jeff King <peff@peff.net>:

>> +(no subcommand)::
>> +
>> +	Save your local modifications to a new 'stash', and run `git-reset
>> +	--hard` to revert them.
>
> For orthogonality's sake, should this be 'git-stash save', aliased to
> just 'git-stash'? It would make this heading a little more intuitive,
> and the very first paragraph (describing all of the modes) a little more
> clear.

Johannes earlier asked for the same thing, and I think it is a good change.

>> +apply [<stash>]::
>> +
>> +	Restores the changes recorded in the stash on top of the current
>
> s/Restores/Restore/ to match the imperative of the other command
> descriptions.
>
>> +	working tree state.  When no `<stash>` is given, applies the latest
>> +	one.  The working directory must match the index.  When the changes
>> +	conflict, you need to resolve them by hand and mark the result with
>> +	`git add` as usual.  When the changes are cleanly merged, your
>> +	earlier local changes stored in the stash becomes the differences
>> +	between the index and the working tree (i.e. `git diff`), except
>> +	that newly created files are registered in the index (i.e. `git diff
>> +	--cached` is necessary to review the newly added files).
>
> I'm not quite sure I understand what this is saying.

I don't understand myself anymore, either (^_^;) I just tried to follow
Jnio's earlier suggestion in his message.  He said this.

| The three-way merge is done correctly here, and I would imagine
| the users would feel the UI quite natural _if_ this merge
| conflicts.  "git diff" would show only the conflicted paths
| (because the updates coming from the old working tree is placed
| in the index for cleanly merged paths), editing a conflicted
| file and "git add $that_path" would resolve.  That's exactly the
| same workflow for a conflicted merge.
|
| However, I think it is a bit counterintuitive to update the
| working tree change to the index if the merge did not conflict.
| It might be better to run an equivalent of "git reset", so that
| after "git save restore", the user can say "git diff" (not "git
| diff HEAD") to view the local changes.  Perhaps...

>> +clear::
>> +	Removes all the stashed states.
>
> Maybe a note to indicate that this can lose data? Something like:
>
>   ...stashed states. Note that those states will then be subject to
>   pruning, and may be difficult or impossible to recover.

I see.  When I wrote it, I thought that saying "removes" was enough.  It
seemed obvious to me that you would lose it when you remove it.

Thanks for fixing my language.  I am not very good at writing English,
but you probably have already found it out (^_^;).

-- 
Nanako Shiraishi
http://ivory.ap.teacup.com/nanako3/

----------------------------------------------------------------------
Finally - A spam blocker that actually works.
http://www.bluebottle.com