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

[Jonathan Nieder <jrnieder@gmail.com>]

With its new semantics, "git reset --merge" is more suitable for
undoing a failed merge than "git reset --hard" is.  It is especially
nice if you forget that you are in a merge and make a change or two:

  git merge something-complicated
  ... notice conflicts, walk away ...
  vi foo.c
  git commit; # fails because the index has unmerged entries
  git reset --merge

The modern (post-1.7.0) semantics of git reset --merge ensure that
the changes to foo.c will be preserved by this sequence of commands,
unless foo.c was one of the files with conflicts.

So in the spirit of ed4a6baa (Documentation: suggest `reset --merge`
in How Merge Works section, 2010-01-23), recommend it in place of
"reset --hard".

One caveat: for habitual adders-to-index, "git reset --merge" is
no better than "git reset --hard" (though still no worse).

  vi foo.c
  git add -u
  git diff --cached --check; # fails because conflict markers are present
  git reset --merge; # equivalent to git reset --hard

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/git-merge.txt   |    2 +-
 Documentation/git-reset.txt   |    9 +++++----
 Documentation/user-manual.txt |    9 ++++++++-
 3 files changed, 14 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 84043cc..498931b 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -213,7 +213,7 @@ After seeing a conflict, you can do two things:
 
  * Decide not to merge.  The only clean-ups you need are to reset
    the index file to the `HEAD` commit to reverse 2. and to clean
-   up working tree changes made by 2. and 3.; `git-reset --hard` can
+   up working tree changes made by 2. and 3.; `git reset --merge` can
    be used for this.
 
  * Resolve the conflicts.  Git will mark the conflicts in
diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index fd72976..1d0d9e6 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -179,7 +179,7 @@ $ git pull                         <1>
 Auto-merging nitfol
 CONFLICT (content): Merge conflict in nitfol
 Automatic merge failed; fix conflicts and then commit the result.
-$ git reset --hard                 <2>
+$ git reset --merge                <2>
 $ git pull . topic/branch          <3>
 Updating from 41223... to 13134...
 Fast-forward
@@ -189,9 +189,10 @@ $ git reset --hard ORIG_HEAD       <4>
 <1> Try to update from the upstream resulted in a lot of
 conflicts; you were not ready to spend a lot of time merging
 right now, so you decide to do that later.
-<2> "pull" has not made merge commit, so "git reset --hard"
-which is a synonym for "git reset --hard HEAD" clears the mess
-from the index file and the working tree.
+<2> "pull" has not made merge commit, so "git reset --merge"
+which is a synonym for "git reset --merge HEAD" clears the mess
+from the index file and the working tree.  "git reset --hard"
+would work as well.
 <3> Merge a topic branch into the current branch, which resulted
 in a fast-forward.
 <4> But you decided that the topic branch is not ready for public
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index fc56da6..9120ad5 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1372,12 +1372,19 @@ Undoing a merge
 ---------------
 
 If you get stuck and decide to just give up and throw the whole mess
-away, you can always return to the pre-merge state with
+away, you can always return to the last commit's state with
 
 -------------------------------------------------
 $ git reset --hard HEAD
 -------------------------------------------------
 
+If you have changes that should be preserved in files not touched by
+the merge, instead use
+
+-------------------------------------------------
+$ git reset --merge HEAD
+-------------------------------------------------
+
 Or, if you've already committed the merge that you want to throw away,
 
 -------------------------------------------------
-- 
1.7.2.3.557.gab647.dirty