Switch from Docopt to Clap.

There were two important reasons for the switch:

1. Performance. Docopt does poorly when the argv becomes large, which is
   a reasonable common use case for search tools. (e.g., use with xargs)
2. Better failure modes. Clap knows a lot more about how a particular
   argv might be invalid, and can therefore provide much clearer error
   messages.

While both were important, (1) made it urgent.

Note that since Clap requires at least Rust 1.11, this will in turn
increase the minimum Rust version supported by ripgrep from Rust 1.9 to
Rust 1.11. It is therefore a breaking change, so the soonest release of
ripgrep with Clap will have to be 0.3.

There is also at least one subtle breaking change in real usage.
Previous to this commit, this used to work:

    rg -e -foo

Where this would cause ripgrep to search for the string `-foo`. Clap
currently has problems supporting this use case
(see: https://github.com/kbknapp/clap-rs/issues/742),
but it can be worked around by using this instead:

    rg -e [-]foo

or even

    rg [-]foo

and this still works:

    rg -- -foo

This commit also adds Bash, Fish and PowerShell completion files to the
release, fixes a bug that prevented ripgrep from working on file
paths containing invalid UTF-8 and shows short descriptions in the
output of `-h` but longer descriptions in the output of `--help`.

Fixes #136, Fixes #189, Fixes #210, Fixes #230

doc/rg.1

@@ -7,11 +7,11 @@
 rg \- recursively search current directory for lines matching a pattern
 .SH SYNOPSIS
 .PP
-rg [\f[I]options\f[]] \-e PATTERN ...
-[\f[I]<\f[]path\f[I]> ...\f[]]
-.PP
 rg [\f[I]options\f[]] <\f[I]pattern\f[]> [\f[I]<\f[]path\f[I]> ...\f[]]
 .PP
+rg [\f[I]options\f[]] (\-e PATTERN | \-f FILE) ...
+[\f[I]<\f[]path\f[I]> ...\f[]]
+.PP
 rg [\f[I]options\f[]] \-\-files [\f[I]<\f[]path\f[I]> ...\f[]]
 .PP
 rg [\f[I]options\f[]] \-\-type\-list
@@ -163,6 +163,15 @@ Show debug messages.
 .RS
 .RE
 .TP
+.B \-f, \-\-file FILE ...
+Search for patterns from the given file, with one pattern per line.
+When this flag is used or multiple times or in combination with the
+\-e/\-\-regexp flag, then all patterns provided are searched.
+Empty pattern lines will match all input lines, and the newline is not
+counted as part of the pattern.
+.RS
+.RE
+.TP
 .B \-\-files
 Print each file that would be searched (but don\[aq]t search).
 .RS
@@ -202,6 +211,16 @@ Search hidden directories and files.
 .RS
 .RE
 .TP
+.B \-\-ignore\-file FILE ...
+Specify additional ignore files for filtering file paths.
+Ignore files should be in the gitignore format and are matched relative
+to the current working directory.
+These ignore files have lower precedence than all other ignore files.
+When specifying multiple ignore files, earlier files have lower
+precedence than later files.
+.RS
+.RE
+.TP
 .B \-L, \-\-follow
 Follow symlinks.
 .RS

doc/rg.1.md

@@ -4,10 +4,10 @@ rg - recursively search current directory for lines matching a pattern
 
 # SYNOPSIS
 
-rg [*options*] -e PATTERN ... [*<*path*> ...*]
-
 rg [*options*] <*pattern*> [*<*path*> ...*]
 
+rg [*options*] (-e PATTERN | -f FILE) ... [*<*path*> ...*]
+
 rg [*options*] --files [*<*path*> ...*]
 
 rg [*options*] --type-list
@@ -107,6 +107,12 @@ Project home page: https://github.com/BurntSushi/ripgrep
 --debug
 : Show debug messages.
 
+-f, --file FILE ...
+: Search for patterns from the given file, with one pattern per line. When this
+  flag is used or multiple times or in combination with the -e/--regexp flag,
+  then all patterns provided are searched. Empty pattern lines will match all
+  input lines, and the newline is not counted as part of the pattern.
+
 --files
 : Print each file that would be searched (but don't search).
 
@@ -132,6 +138,14 @@ Project home page: https://github.com/BurntSushi/ripgrep
 : Search hidden directories and files. (Hidden directories and files are
   skipped by default.)
 
+--ignore-file FILE ...
+: Specify additional ignore files for filtering file paths.
+  Ignore files should be in the gitignore format and are matched
+  relative to the current working directory. These ignore files
+  have lower precedence than all other ignore files. When
+  specifying multiple ignore files, earlier files have lower
+  precedence than later files.
+
 -L, --follow
 : Follow symlinks.