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

[Junio C Hamano <gitster@pobox.com>]

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.

> +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.

> +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.

> +<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").

> +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/

> +Author
> +------
> +Written by Johannes E. Schindelin <johannes.schindelin@gmx.de>

You wrote that ;-)?