Hi,
On Sat, 30 Jun 2007, Junio C Hamano wrote:
> Johannes Schindelin <Johannes.Schindelin@xxxxxx> 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@xxxxxx>
>
> 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
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
