Rewrite synopsis to clarify the two primary uses of git-checkout.

diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index c6a269b7ef56d830ad493467a63637b2afee9e83..b7b9798bf9d34cf64fac48d61a442c5291a7b73a 100644 (file)
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -3,7 +3,7 @@ git-reset(1)
 
 NAME
 ----
-git-reset - Reset current HEAD to the specified state.
+git-reset - Reset current HEAD to the specified state
 
 SYNOPSIS
 --------
@@ -145,6 +145,32 @@ brings your index file and the working tree back to that state,
 and resets the tip of the branch to that commit.
 ------------
 
+Interrupted workflow::
++
+Suppose you are interrupted by an urgent fix request while you
+are in the middle of a large change.  The files in your
+working tree are not in any shape to be committed yet, but you
+need to get to the other branch for a quick bugfix.
++
+------------
+$ git checkout feature ;# you were working in "feature" branch and
+$ work work work       ;# got interrupted
+$ git commit -a -m 'snapshot WIP' <1>
+$ git checkout master
+$ fix fix fix
+$ git commit ;# commit with real log
+$ git checkout feature
+$ git reset --soft HEAD^ ;# go back to WIP state <2>
+$ git reset <3>
+
+<1> This commit will get blown away so a throw-away log message is OK.
+<2> This removes the 'WIP' commit from the commit history, and sets
+    your working tree to the state just before you made that snapshot.
+<3> After <2>, the index file still has all the WIP changes you
+    committed in <1>.  This sets it to the last commit you were
+    basing the WIP changes on.
+------------
+
 Author
 ------
 Written by Junio C Hamano <junkio@cox.net> and Linus Torvalds <torvalds@osdl.org>
@@ -156,4 +182,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 GIT
 ---
 Part of the gitlink:git[7] suite
-