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

From: Thomas Gummerer <t.gummerer@gmail.com>
Date: Jan 28, 2017, 19:30 UTC
Message-ID: <20170128192958.GB31189@hank>
In-Reply-To: <xmqqfuk6alba.fsf@gitster.mtv.corp.google.com>

On 01/25, Junio C Hamano wrote:

Show 35 quoted lines

> Jeff King <peff@peff.net> writes:
> 
> > On Sat, Jan 21, 2017 at 08:08:02PM +0000, Thomas Gummerer wrote:
> >
> >> diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
> >> index 2e9cef06e6..0ad5335a3e 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 revert the
> >> +	the changes in the working tree to match the index.
> >> +	The <message> part is optional and gives
> >
> > Hrm. "git reset --hard" doesn't just make the working tree match the
> > index. It also resets the index to HEAD.  So either the original or your
> > new description is wrong.
> >
> > I think it's the latter. We really do reset the index unless
> > --keep-index is specified.
> 
> Correct.  So the patch is a net loss.  Perhaps not requiring readers
> to know "reset --hard" might be an improvement (I personally do not
> think so), but this loses crucial information from the description.
> 
> 	Save your local modifications (both in the working tree and
> 	to the index) to a new 'stash', and resets the index to HEAD
> 	and makes the working tree match the index (i.e. runs "git
> 	reset --hard").
> 
> That's one-and-a-half lines longer than the original, though.

Thanks all who chimed in here. My new description is definitely not right. The reason I wanted to change it is part because it's an implementation detail, and part because it's going to be not quite right when the filename argument is introduced.

How about the following:

 	Save your local modifications to a new 'stash' and roll them back
 	both in the working tree and in the index.

As an added bonus this also matches what git stash save -p does.