git-reset.txt: reset --soft is not a no-op

diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index 9cf31485feec4b03850edb1f2f3a4b765245f4cc..8762a0c6b9f8be1dbc41a6f3e601b4a9f3d862b6 100644 (file)
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -15,7 +15,7 @@ SYNOPSIS
 DESCRIPTION
 -----------
 In the first and second form, copy entries from <commit> to the index.
-In the third form, set the current branch to <commit>, optionally
+In the third form, set the current branch head to <commit>, optionally
 modifying index and worktree to match.  The <commit> defaults to HEAD
 in all forms.
 
@@ -36,16 +36,16 @@ This means that `git reset -p` is the opposite of `git add -p` (see
 linkgit:git-add[1]).
 
 'git reset' [--<mode>] [<commit>]::
-       This form points the current branch to <commit> and then
+       This form resets the current branch head to <commit> and then
        updates index and working tree according to <mode>, which must
        be one of the following:
 +
 --
 --soft::
-       Does not touch the index file nor the working tree at all, but
-       requires them to be in a good order. This leaves all your changed
-       files "Changes to be committed", as 'git status' would
-       put it.
+       Does not touch the index file nor the working tree at all (but
+       resets the head to <commit>, just like all modes do). This leaves
+       all your changed files "Changes to be committed", as 'git status'
+       would put it.
 
 --mixed::
        Resets the index but not the working tree (i.e., the changed files
@@ -294,8 +294,10 @@ In these tables, A, B, C and D are some different states of a
 file. For example, the first line of the first table means that if a
 file is in state A in the working tree, in state B in the index, in
 state C in HEAD and in state D in the target, then "git reset --soft
-target" will put the file in state A in the working tree, in state B
-in the index and in state D in HEAD.
+target" will leave the file in the working tree in state A and in the
+index in state B.  It resets (i.e. moves) the HEAD (i.e. the tip of
+the current branch, if you are on one) to "target" (which has the file
+in state D).
 
       working index HEAD target         working index HEAD
       ----------------------------------------------------