Re: [PATCH] Add a manual page for git-stash

[Johannes Schindelin <Johannes.Schindelin@gmx.de>]

Hi,

On Sat, 30 Jun 2007, Junio C Hamano wrote:

> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
> 
> > +DESCRIPTION
> > +-----------
> > +Use 'git stash' when you want to record the current state of the
> > +working directory and the index, but want to go back to a clean
> > +working directory.
> > +
> > +For example, if you have to pull, but are in the middle of some
> > +interesting work, not yet ready to be committed, use git-stash.
> > +
> > +The default operation (when called without options), is to save
> > +the changes away.
> > +
> > +
> > +OPTIONS
> > +-------
> > +clear::
> > +	Undo _all_ stashes (dangerous!).
> > +
> > +list [<stashname>]::
> > +	List all stashed states.
> > +
> 
> I suspect that is not what the implementation intends to do.
> "list -n 4", "list --since=1.hour" would make sense, but "list
> stash@{12}" would probably not.

Okay, I misunderstood the _intention_ of the code, then.

> > +show [<stashname>]::
> > +	Show a combined diff of the stashed working directory, index and
> > +	HEAD.
> 
> Is that what it does?  I had an impression that "show stash@{2}"
> shows a regular diff between the base and the stashed working
> tree state.

Ah, you're completely right! Somehow my tired eyes read what I expected to 
find there.

> > +apply [<stashname>]::
> > +	Try to apply the stashed changes to the current HEAD. You need
> > +	a clean working directory for that, i.e. you must not have changes
> > +	relative to HEAD in your working directory or index.
> 
> The implementation appears to apply on a clean index without
> restriction to where the HEAD is.  I hinted that that behaviour
> is fine in my previous message, but on the other hand haven't
> convinced myself enough to say that it would not confuse end
> users.  Maybe insisting on not just clean index but no changes
> from the HEAD would reduce confusion?  I dunno.

I am sure confused why the index state is stashed away when it is not 
used...

> > +<stashname>::
> > +	A name of a stashed state. Typically something like 'stash@{2}'
> > +	or 'stash@{2.days.ago}'.
> 
> Probably this should be defined in DESCRIPTION, along with the
> definition of what a stash is ("records the difference between
> the HEAD when the stash was created and the working tree state
> in such a way that it can be applied to a different state
> later").

Okay.

> > +DISCUSSION
> > +----------
> > +
> > +The state is saved as three commits:
> > +
> > +- HEAD,
> > +- a commit which contains the state of the index, which has HEAD as a
> > +  parent, and
> > +- a commit which contains the state of the working directory (only the
> > +  tracked files, though), which has both HEAD and the second commit
> > +  as parents.
> > +
> > +The third commit holds the complete information of the stash, and is
> > +stored as the ref 'refs/stash'.
> > +
> > +Since that commit does not have any reference to other stashed states,
> > +the stash listing relies on the reflog of 'refs/stash'. Therefore,
> > +the stashed states are garbage collected like all the other reflogs.
> 
> Nit; s/the other reflogs/the other reflog entries/

Okay.

> > +Author
> > +------
> > +Written by Johannes E. Schindelin <johannes.schindelin@gmx.de>
> 
> You wrote that ;-)?

No. ;-)

Hey, be nice. It's a new role for me, usually others document what _I_ 
wrote, not vice versa :-)

Ciao,
Dscho