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

Thomas Gummerer [off-list ref] 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.

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.

"... roll them back both ..." is unclear where they are rolled back
to.  

Perhaps "roll them back ... to HEAD" or something?

On 01/30, Junio C Hamano wrote:

Thomas Gummerer [off-list ref] writes:

quoted

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.

quoted

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