[PATCH] Improve documentation of git-filter-branch rev-list specification.

[Carl Worth <cworth@cworth.org>]

The rev-list is not optional, and a range of a..b will not rewrite
only b. Fix these errors and improve the wording of surrounding text.

Also eliminate the discussion of using no filters to compensate for
hypothetical future bugs. It's not helpful.
---
 Documentation/git-filter-branch.txt |   34 ++++++++++++++++++++--------------
 1 files changed, 20 insertions(+), 14 deletions(-)

diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt
index ba9b4fb..985d7d5 100644
--- a/Documentation/git-filter-branch.txt
+++ b/Documentation/git-filter-branch.txt
@@ -13,23 +13,29 @@ SYNOPSIS
 	[--msg-filter <command>] [--commit-filter <command>]
 	[--tag-name-filter <command>] [--subdirectory-filter <directory>]
 	[--original <namespace>] [-d <directory>] [-f | --force]
-	[<rev-list options>...]
+	<rev-list options>...
 
 DESCRIPTION
 -----------
-Lets you rewrite git revision history by rewriting the branches mentioned
-in the <rev-list options>, applying custom filters on each revision.
-Those filters can modify each tree (e.g. removing a file or running
-a perl rewrite on all files) or information about each commit.
-Otherwise, all information (including original commit times or merge
-information) will be preserved.
-
-The command will only rewrite the _positive_ refs mentioned in the
-command line (i.e. if you pass 'a..b', only 'b' will be rewritten).
-If you specify no filters, the commits will be recommitted without any
-changes, which would normally have no effect.  Nevertheless, this may be
-useful in the future for compensating for some git bugs or such,
-therefore such a usage is permitted.
+Rewrites git revision history by applying one or more filters to a set
+of commits. The set of commits to be rewritten is supplied in
+<rev-list options> and can be as simple as one or more branch names,
+(in which case all commits reachable from those branch names will be
+rewritten).
+
+The filters can modify the tree content stored in each commit,
+(e.g. removing a file or running a perl rewrite on all files), or the
+associated information about each commit, (commit message, author,
+parent, etc.). Any information not affected by a filter (including
+original commit times or merge information) will be preserved. If you
+specify no filters, the commits will be recommitted without any
+changes.
+
+Note that passing a range of commits specified with the a..b notation
+will rewrite 'b' and all commits reachable from 'b' but not reachable
+from 'a', but will not rewrite the commit 'a' itself. This is
+consistent with the handling of a range by git-log and other git
+commands.
 
 *WARNING*! The rewritten history will have different object names for all
 the objects and will not converge with the original branch.  You will not
-- 
1.5.3.4