[PATCH] Add hints to revert documentation about other ways to undo changes

[Tarmigan <tarmigan+git@gmail.com>]

[Resending to git list.  Original was rejected by vger with
Message headers can not have 8-bit non-ASCII characters in it; Use
MIME encodings if such are needed!
so trying to mail list directly for discussion.  This copy is probably
mangled in the forward.]

From: Tarmigan Casebolt <tarmigan+git@gmail.com>
Date: Tue, Aug 19, 2008 at 10:06 AM
Subject: [PATCH] Add hints to revert documentation about other ways to
undo changes
To: gitster@pobox.com

Based on its name, people may read the 'git revert' documentation when
they want to undo local changes, especially people who have used other
SCM's.  'git revert' may not be what they had in mind, but git
provides several other ways to undo changes to files.  We can help
them by pointing them towards the git commands that do what they might
want to do.

Cc: Daniel Barkalow <barkalow@iabervon.org>
Cc: "Peter Valdemar Mørch (Lists)" <4ux6as402@sneakemail.com>
Cc: Lea Wiemann <lewiemann@gmail.com>
Signed-off-by: Tarmigan Casebolt <tarmigan+git@gmail.com>
---

I put this in a Note: in the DESCRIPTION section.  If there is
consensus about moving it somewhere else, I can send another patch.

 Documentation/git-revert.txt |    9 +++++++++
 1 files changed, 9 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
index 98cfa3c..d46f090 100644
--- a/Documentation/git-revert.txt
+++ b/Documentation/git-revert.txt
@@ -15,6 +15,15 @@ Given one existing commit, revert the change the
patch introduces, and record a
 new commit that records it.  This requires your working tree to be clean (no
 modifications from the HEAD commit).

+Note: Despite its name, 'git revert' may not undo changes in the way
+that you expect.  If you want to throw away all uncommitted changes in
+your working directory, you should see linkgit:git-reset[1],
+particulary the '--hard' option.  If you want to extract specific
+files as they were in another commit, you should see
+linkgit:git-checkout[1], specifically the 'git checkout <commit> --
+<filename>' syntax.  Take care with these alternatives as both will
+discard uncommitted changes in your working directory.
+
 OPTIONS
 -------
 <commit>::
--
1.6.0