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

Hi,

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

Johannes Schindelin [off-list ref] writes:

quoted

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

quoted

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

quoted

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

quoted

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

quoted

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

quoted

+Author
+------
+Written by Johannes E. Schindelin [off-list ref]

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