Subject: Re: [PATCH v2 1/4] Documentation/stash: remove mention of git reset --hard

From: Thomas Gummerer <[email-masked]>
Date: Sun, 5 Feb 2017 12:13:47 +0000

On 01/30, Junio C Hamano wrote:
> Thomas Gummerer <[email-masked]> writes:
> 
> > Don't mention git reset --hard in the documentation for git stash save.
> > It's an implementation detail that doesn't matter to the end user and
> > thus shouldn't be exposed to them.
> 
> Everybody understands what "reset --hard" does; it can be an
> easier-to-read "short-hand" description to say "reset --hard"
> instead of giving a lengthy description of what happens.

While this is definitely true for experienced git users, it might not
be for some people relatively new to git, which are probably the ones
that need the description most.

> Because of that, I do not necessarily agree with the above
> justification.  I'll read the remainder of the series before
> commenting further on the above.
> 
> > diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
> > index 2e9cef06e6..0fc23c25ee 100644
> > --- a/Documentation/git-stash.txt
> > +++ b/Documentation/git-stash.txt
> > @@ -47,8 +47,9 @@ OPTIONS
> >  
> >  save [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [<message>]::
> >  
> > -	Save your local modifications to a new 'stash', and run `git reset
> > -	--hard` to revert them.  The <message> part is optional and gives
> > +	Save your local modifications to a new 'stash' and roll them
> > +	back both in the working tree and in the index.
> 
> "... roll them back both ..." is unclear where they are rolled back
> to.  
> 
> Perhaps "roll them back ... to HEAD" or something?

Yeah that makes sense, thanks.

-- 
Thomas