Examples of resetting.

Morten Welinder says examples of resetting is really about
recovering from botched commit/pulls.  I agree that pointers
from commands that cause a reset to be needed in the first place
would be very helpful.

Also reset examples did not mention "pull/merge" cases.

Signed-off-by: Junio C Hamano <junkio@cox.net>

4 files changed, 47 insertions, 0 deletions

diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index b92cf48315..8b91f221fe 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -66,6 +66,10 @@ OPTIONS
 	Update specified paths in the index file before committing.
 
 
+If you make a commit and then found a mistake immediately after
+that, you can recover from it with gitlink:git-reset[1].
+
+
 Author
 ------
 Written by Linus Torvalds <torvalds@osdl.org> and
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 0cac563d40..4ce799b520 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -37,6 +37,11 @@ include::merge-options.txt[]
 include::merge-strategies.txt[]
 
 
+If you tried a merge which resulted in a complex conflicts and
+would want to start over, you can recover with
+gitlink:git-reset[1].
+
+
 HOW MERGE WORKS
 ---------------
 
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index c65ca9a530..3a7d385225 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -104,6 +104,11 @@ merge the remote `origin` head into the current,
 local `master` branch.
 
 
+If you tried a pull which resulted in a complex conflicts and
+would want to start over, you can recover with
+gitlink:git-reset[1].
+
+
 SEE ALSO
 --------
 gitlink:git-fetch[1], gitlink:git-merge[1]
diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index 02048918bf..c6a269b7ef 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -111,6 +111,39 @@ remain there.
 changes still in the working tree.
 ------------
 
+Undo a merge or pull::
++
+------------
+$ git pull <1>
+Trying really trivial in-index merge...
+fatal: Merge requires file-level merging
+Nope.
+...
+Auto-merging nitfol
+CONFLICT (content): Merge conflict in nitfol
+Automatic merge failed/prevented; fix up by hand
+$ git reset --hard <2>
+
+<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.
+
+$ git pull . topic/branch <3>
+Updating from 41223... to 13134...
+Fast forward
+$ git reset --hard ORIG_HEAD <4>
+
+<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
+consumption yet.  "pull" or "merge" always leaves the original
+tip of the current branch in ORIG_HEAD, so resetting hard to it
+brings your index file and the working tree back to that state,
+and resets the tip of the branch to that commit.
+------------
 
 Author
 ------