[RFC/PATCH 2/2] Documentation: suggest "reset --keep" more often

[Jonathan Nieder <jrnieder@gmail.com>]

Practically speaking, a "reset --hard" fulfills two purposes:

 1. erase uncommitted changes (in the index and worktree)
 2. checkout a different commit without changing which branch
    HEAD is attached to

The relatively new "git reset --keep" command does (2) without
(1), which makes it simpler to use for use cases that amount to
"rewind HEAD".

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/git-bisect-lk2009.txt               |    2 +-
 Documentation/git-bisect.txt                      |    2 +-
 Documentation/git-checkout.txt                    |    2 +-
 Documentation/git-rerere.txt                      |    2 +-
 Documentation/git-reset.txt                       |    4 ++--
 Documentation/gitcore-tutorial.txt                |    6 +++---
 Documentation/gitworkflows.txt                    |    2 +-
 Documentation/howto/maintain-git.txt              |    4 ++--
 Documentation/howto/separating-topic-branches.txt |    2 +-
 Documentation/user-manual.txt                     |   13 +++++++------
 10 files changed, 20 insertions(+), 19 deletions(-)

diff --git a/Documentation/git-bisect-lk2009.txt b/Documentation/git-bisect-lk2009.txt
index 8a2ba37..b581da8 100644
--- a/Documentation/git-bisect-lk2009.txt
+++ b/Documentation/git-bisect-lk2009.txt
@@ -1188,7 +1188,7 @@ should not forget to remove the patch once the testing is done before
 exiting from the script.
 
 (Note that instead of a patch you can use "git cherry-pick BFC" to
-apply the fix, and in this case you should use "git reset --hard
+apply the fix, and in this case you should use "git reset --keep
 HEAD^" to revert the cherry-pick after testing and before returning
 from the script.)
 
diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt
index c39d957..43582a8 100644
--- a/Documentation/git-bisect.txt
+++ b/Documentation/git-bisect.txt
@@ -158,7 +158,7 @@ For example:
 $ git bisect good/bad			# previous round was good or bad.
 Bisecting: 337 revisions left to test after this
 $ git bisect visualize			# oops, that is uninteresting.
-$ git reset --hard HEAD~3		# try 3 revisions before what
+$ git reset --keep HEAD~3		# try 3 revisions before what
 					# was suggested
 ------------
 
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 22d3611..f92fe3f 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -223,7 +223,7 @@ current branch and directly points at the commit named by the tag
 (`v2.6.18` in the example above).
 
 You can use all git commands while in this state.  You can use
-`git reset --hard $othercommit` to further move around, for
+`git reset --keep $othercommit` to further move around, for
 example.  You can make changes and create a new commit on top of
 a detached HEAD.  You can even create a merge by using `git
 merge $othercommit`.
diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt
index db99d47..4ed4262 100644
--- a/Documentation/git-rerere.txt
+++ b/Documentation/git-rerere.txt
@@ -132,7 +132,7 @@ top of the tip before the test merge:
 ------------
 	$ git checkout topic
 	$ git merge master
-	$ git reset --hard HEAD^ ;# rewind the test merge
+	$ git reset --keep HEAD^ ;# rewind the test merge
 	$ ... work on both topic and master branches
 	$ git checkout master
 	$ git merge topic
diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index 1d0d9e6..301419c 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -148,7 +148,7 @@ Undo a commit, making it a topic branch::
 +
 ------------
 $ git branch topic/wip     <1>
-$ git reset --hard HEAD~3  <2>
+$ git reset --keep HEAD~3  <2>
 $ git checkout topic/wip   <3>
 ------------
 +
@@ -163,7 +163,7 @@ Undo commits permanently::
 +
 ------------
 $ git commit ...
-$ git reset --hard HEAD~3   <1>
+$ git reset --keep HEAD~3   <1>
 ------------
 +
 <1> The last three commits (HEAD, HEAD^, and HEAD~2) were bad
diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt
index c27d086..14bdceb 100644
--- a/Documentation/gitcore-tutorial.txt
+++ b/Documentation/gitcore-tutorial.txt
@@ -1182,9 +1182,9 @@ work." commit.
 
 ------------
 $ git checkout mybranch
-$ git reset --hard master^2
+$ git reset --keep master^2
 $ git checkout master
-$ git reset --hard master^
+$ git reset --keep master^
 ------------
 
 After rewinding, the commit structure should look like this:
@@ -1660,7 +1660,7 @@ we just did and start over.  We would want to get the master
 branch before these two merges by resetting it to 'master~2':
 
 ------------
-$ git reset --hard master~2
+$ git reset --keep master~2
 ------------
 
 You can make sure `git show-branch` matches the state before
diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt
index 1ef55ff..4a35a92 100644
--- a/Documentation/gitworkflows.txt
+++ b/Documentation/gitworkflows.txt
@@ -301,7 +301,7 @@ topics on 'next':
 [caption="Recipe: "]
 =====================================
 * `git checkout next`
-* `git reset --hard master`
+* `git reset --keep master`
 * `git merge ai/topic_in_next1`
 * `git merge ai/topic_in_next2`
 * ...
diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt
index d527b30..f0c9e1b 100644
--- a/Documentation/howto/maintain-git.txt
+++ b/Documentation/howto/maintain-git.txt
@@ -166,7 +166,7 @@ by doing the following:
 
    then replace some parts with the new patch, and reapplying:
 
-     $ git reset --hard ai/topic~$n
+     $ git reset --keep ai/topic~$n
      $ git am -3 -s 000*.txt
 
    The full test suite is always run for 'maint' and 'master'
@@ -212,7 +212,7 @@ by doing the following:
  - Rebuild "pu" to merge the tips of topics not in 'next'.
 
      $ git checkout pu
-     $ git reset --hard next
+     $ git reset --keep next
      $ git merge ai/topic     ;# repeat for all remaining topics
      $ make test
 
diff --git a/Documentation/howto/separating-topic-branches.txt b/Documentation/howto/separating-topic-branches.txt
index 6d3eb8e..b54826f 100644
--- a/Documentation/howto/separating-topic-branches.txt
+++ b/Documentation/howto/separating-topic-branches.txt
@@ -80,7 +80,7 @@ The last diff better not to show anything other than cleanups
 for crufts.  Then I can finally clean things up:
 
         $ git branch -D topic
-        $ git reset --hard HEAD^ ;# nuke pretend merge
+        $ git reset --keep HEAD^ ;# nuke pretend merge
 
                                 "topicB"
                o---o---o---o---o
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 9120ad5..427717d 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -143,7 +143,7 @@ If you decide that you'd rather see version 2.6.17, you can modify
 the current branch to point at v2.6.17 instead, with
 
 ------------------------------------------------
-$ git reset --hard v2.6.17
+$ git reset --keep v2.6.17
 ------------------------------------------------
 
 Note that if the current branch head was your only reference to a
@@ -531,13 +531,13 @@ says "bisect".  Choose a safe-looking commit nearby, note its commit
 id, and check it out with:
 
 -------------------------------------------------
-$ git reset --hard fb47ddb2db...
+$ git reset --keep fb47ddb2db...
 -------------------------------------------------
 
 then test, run "bisect good" or "bisect bad" as appropriate, and
 continue.
 
-Instead of "git bisect visualize" and then "git reset --hard
+Instead of "git bisect visualize" and then "git reset --keep
 fb47ddb2db...", you might just want to tell git that you want to skip
 the current commit:
 
@@ -1388,7 +1388,7 @@ $ git reset --merge HEAD
 Or, if you've already committed the merge that you want to throw away,
 
 -------------------------------------------------
-$ git reset --hard ORIG_HEAD
+$ git reset --keep ORIG_HEAD
 -------------------------------------------------
 
 However, this last command can be dangerous in some cases--never
@@ -2011,7 +2011,8 @@ error: failed to push to 'ssh://yourserver.com/~you/proj.git'
 
 This can happen, for example, if you:
 
-	- use `git reset --hard` to remove already-published commits, or
+	- use `git reset --hard` or `git reset --keep` to remove
+	  already-published commits, or
 	- use `git commit --amend` to replace already-published commits
 	  (as in <<fixing-a-mistake-by-rewriting-history>>), or
 	- use `git rebase` to rebase any already-published commits (as
@@ -2585,7 +2586,7 @@ patches, then reset the state to before the patches:
 
 -------------------------------------------------
 $ git format-patch origin
-$ git reset --hard origin
+$ git reset --keep origin
 -------------------------------------------------
 
 Then modify, reorder, or eliminate patches as preferred before applying
-- 
1.7.2.3.557.gab647.dirty