2018-01-11 15:05:52 +02:00
|
|
|
.\" Automatically generated by Pandoc 2.0.6
|
2016-09-22 23:48:41 +02:00
|
|
|
.\"
|
2017-01-07 03:07:29 +02:00
|
|
|
.TH "rg" "1"
|
2016-09-22 23:48:41 +02:00
|
|
|
.hy
|
|
|
|
.SH NAME
|
|
|
|
.PP
|
|
|
|
rg \- recursively search current directory for lines matching a pattern
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.PP
|
2018-01-11 15:05:52 +02:00
|
|
|
rg [\f[I]OPTIONS\f[]] \f[I]PATTERN\f[] [\f[I]PATH\f[] ...]
|
2016-09-22 23:48:41 +02:00
|
|
|
.PP
|
2018-01-11 15:05:52 +02:00
|
|
|
rg [\f[I]OPTIONS\f[]] [\-e \f[I]PATTERN\f[] ...] [\-f \f[I]FILE\f[] ...]
|
|
|
|
[\f[I]PATH\f[] ...]
|
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
2016-11-13 04:48:11 +02:00
|
|
|
.PP
|
2018-01-11 15:05:52 +02:00
|
|
|
rg [\f[I]OPTIONS\f[]] \-\-files [\f[I]PATH\f[] ...]
|
2016-09-22 23:48:41 +02:00
|
|
|
.PP
|
2018-01-11 15:05:52 +02:00
|
|
|
rg [\f[I]OPTIONS\f[]] \-\-type\-list
|
2016-09-22 23:48:41 +02:00
|
|
|
.PP
|
2018-01-11 15:05:52 +02:00
|
|
|
rg [\f[I]OPTIONS\f[]] \-\-help
|
2016-09-22 23:48:41 +02:00
|
|
|
.PP
|
2018-01-11 15:05:52 +02:00
|
|
|
rg [\f[I]OPTIONS\f[]] \-\-version
|
2016-09-22 23:48:41 +02:00
|
|
|
.SH DESCRIPTION
|
|
|
|
.PP
|
2016-11-06 19:21:36 +02:00
|
|
|
ripgrep (rg) combines the usability of The Silver Searcher (an ack
|
2016-09-22 23:48:41 +02:00
|
|
|
clone) with the raw speed of grep.
|
2016-11-06 19:21:36 +02:00
|
|
|
.PP
|
2016-12-12 14:03:37 +02:00
|
|
|
ripgrep\[aq]s regex engine uses finite automata and guarantees linear
|
|
|
|
time searching.
|
|
|
|
Because of this, features like backreferences and arbitrary lookaround
|
|
|
|
are not supported.
|
|
|
|
.PP
|
2017-08-24 01:14:27 +02:00
|
|
|
Note that ripgrep may abort unexpectedly when using default settings if
|
|
|
|
it searches a file that is simultaneously truncated.
|
|
|
|
This behavior can be avoided by passing the \-\-no\-mmap flag.
|
|
|
|
.PP
|
2016-11-06 19:21:36 +02:00
|
|
|
Project home page: https://github.com/BurntSushi/ripgrep
|
2018-01-11 15:05:52 +02:00
|
|
|
.SH POSITIONAL ARGUMENTS
|
|
|
|
.TP
|
|
|
|
.B \f[I]PATTERN\f[]
|
|
|
|
A regular expression used for searching.
|
|
|
|
To match a pattern beginning with a dash, use the \-e/\-\-regexp option.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
|
|
|
.B \f[I]PATH\f[]
|
|
|
|
A file or directory to search.
|
|
|
|
Directories are searched recursively.
|
|
|
|
Paths specified expicitly on the command line override glob and ignore
|
|
|
|
rules.
|
|
|
|
.RS
|
|
|
|
.RE
|
2016-09-22 23:48:41 +02:00
|
|
|
.SH COMMON OPTIONS
|
|
|
|
.TP
|
|
|
|
.B \-a, \-\-text
|
|
|
|
Search binary files as if they were text.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
|
|
|
.B \-c, \-\-count
|
|
|
|
Only show count of line matches for each file.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
|
|
|
.B \-\-color \f[I]WHEN\f[]
|
2017-05-26 00:04:45 +02:00
|
|
|
Whether to use color in the output.
|
|
|
|
Valid values are never, auto, always or ansi.
|
2017-08-24 01:14:27 +02:00
|
|
|
The default is auto.
|
|
|
|
When always is used, coloring is attempted based on your environment.
|
|
|
|
When ansi is used, coloring is forcefully done using ANSI escape color
|
|
|
|
codes.
|
2016-09-22 23:48:41 +02:00
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
|
|
|
.B \-e, \-\-regexp \f[I]PATTERN\f[] ...
|
|
|
|
Use PATTERN to search.
|
|
|
|
This option can be provided multiple times, where all patterns given are
|
|
|
|
searched.
|
2016-11-06 19:10:55 +02:00
|
|
|
This is also useful when searching for patterns that start with a dash.
|
2016-09-22 23:48:41 +02:00
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
|
|
|
.B \-F, \-\-fixed\-strings
|
|
|
|
Treat the pattern as a literal string instead of a regular expression.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
|
|
|
.B \-g, \-\-glob \f[I]GLOB\f[] ...
|
|
|
|
Include or exclude files for searching that match the given glob.
|
2017-03-13 02:31:09 +02:00
|
|
|
This always overrides any other ignore logic if there is a conflict, but
|
|
|
|
is otherwise applied in addition to ignore files (e.g., .gitignore or
|
|
|
|
\&.ignore).
|
2016-09-22 23:48:41 +02:00
|
|
|
Multiple glob flags may be used.
|
|
|
|
Globbing rules match .gitignore globs.
|
|
|
|
Precede a glob with a \[aq]!\[aq] to exclude it.
|
|
|
|
.RS
|
2017-03-13 02:31:09 +02:00
|
|
|
.PP
|
|
|
|
The \-\-glob flag subsumes the functionality of both the \-\-include and
|
|
|
|
\-\-exclude flags commonly found in other tools.
|
2017-05-26 22:24:49 +02:00
|
|
|
.PP
|
|
|
|
Values given to \-g must be quoted or your shell will expand them and
|
|
|
|
result in unexpected behavior.
|
|
|
|
.PP
|
|
|
|
Combine with the \-\-files flag to return matched filenames (i.e., to
|
|
|
|
replicate ack/ag\[aq]s \-g flag).
|
|
|
|
For example:
|
2017-03-13 02:31:09 +02:00
|
|
|
.IP
|
|
|
|
.nf
|
|
|
|
\f[C]
|
2017-05-26 22:24:49 +02:00
|
|
|
rg\ \-g\ \[aq]*.foo\[aq]\ \-\-files
|
2017-03-13 02:31:09 +02:00
|
|
|
\f[]
|
|
|
|
.fi
|
2017-05-26 22:24:49 +02:00
|
|
|
.RE
|
2016-09-22 23:48:41 +02:00
|
|
|
.TP
|
|
|
|
.B \-h, \-\-help
|
|
|
|
Show this usage message.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
|
|
|
.B \-i, \-\-ignore\-case
|
|
|
|
Case insensitive search.
|
2016-09-28 22:30:57 +02:00
|
|
|
Overridden by \-\-case\-sensitive.
|
2016-09-22 23:48:41 +02:00
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
|
|
|
.B \-n, \-\-line\-number
|
|
|
|
Show line numbers (1\-based).
|
|
|
|
This is enabled by default at a tty.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
|
|
|
.B \-N, \-\-no\-line\-number
|
|
|
|
Suppress line numbers.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
|
|
|
.B \-q, \-\-quiet
|
|
|
|
Do not print anything to stdout.
|
2016-09-25 21:01:27 +02:00
|
|
|
If a match is found in a file, stop searching that file.
|
2016-09-22 23:48:41 +02:00
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
|
|
|
.B \-t, \-\-type \f[I]TYPE\f[] ...
|
|
|
|
Only search files matching TYPE.
|
|
|
|
Multiple type flags may be provided.
|
|
|
|
Use the \-\-type\-list flag to list all available types.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
|
|
|
.B \-T, \-\-type\-not \f[I]TYPE\f[] ...
|
|
|
|
Do not search files matching TYPE.
|
|
|
|
Multiple not\-type flags may be provided.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
|
|
|
.B \-u, \-\-unrestricted ...
|
|
|
|
Reduce the level of \[aq]smart\[aq] searching.
|
|
|
|
A single \-u doesn\[aq]t respect .gitignore (etc.) files.
|
|
|
|
Two \-u flags will search hidden files and directories.
|
|
|
|
Three \-u flags will search binary files.
|
2017-05-26 22:24:49 +02:00
|
|
|
\-uu is equivalent to \f[C]grep\ \-r\f[], and \-uuu is equivalent to
|
|
|
|
\f[C]grep\ \-a\ \-r\f[].
|
2016-09-22 23:48:41 +02:00
|
|
|
.RS
|
2017-03-13 02:24:45 +02:00
|
|
|
.PP
|
|
|
|
Note that the \-u flags are convenient aliases for other combinations of
|
|
|
|
flags.
|
2017-05-26 22:24:49 +02:00
|
|
|
\-u aliases \-\-no\-ignore.
|
|
|
|
\-uu aliases \-\-no\-ignore \-\-hidden.
|
|
|
|
\-uuu aliases \-\-no\-ignore \-\-hidden \-\-text.
|
2016-09-22 23:48:41 +02:00
|
|
|
.RE
|
|
|
|
.TP
|
|
|
|
.B \-v, \-\-invert\-match
|
|
|
|
Invert matching.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
|
|
|
.B \-w, \-\-word\-regexp
|
|
|
|
Only show matches surrounded by word boundaries.
|
|
|
|
This is equivalent to putting \\b before and after the search pattern.
|
|
|
|
.RS
|
|
|
|
.RE
|
2017-08-09 12:53:35 +02:00
|
|
|
.TP
|
|
|
|
.B \-x, \-\-line\-regexp
|
|
|
|
Only show matches surrounded by line boundaries.
|
|
|
|
This is equivalent to putting ^...$ around the search pattern.
|
|
|
|
.RS
|
|
|
|
.RE
|
2016-09-22 23:48:41 +02:00
|
|
|
.SH LESS COMMON OPTIONS
|
|
|
|
.TP
|
|
|
|
.B \-A, \-\-after\-context \f[I]NUM\f[]
|
|
|
|
Show NUM lines after each match.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
|
|
|
.B \-B, \-\-before\-context \f[I]NUM\f[]
|
|
|
|
Show NUM lines before each match.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
|
|
|
.B \-C, \-\-context \f[I]NUM\f[]
|
|
|
|
Show NUM lines before and after each match.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
Completely re-work colored output and tty handling.
This commit completely guts all of the color handling code and replaces
most of it with two new crates: wincolor and termcolor. wincolor
provides a simple API to coloring using the Windows console and
termcolor provides a platform independent coloring API tuned for
multithreaded command line programs. This required a lot more
flexibility than what the `term` crate provided, so it was dropped.
We instead switch to writing ANSI escape sequences directly and ignore
the TERMINFO database.
In addition to fixing several bugs, this commit also permits end users
to customize colors to a certain extent. For example, this command will
set the match color to magenta and the line number background to yellow:
rg --colors 'match:fg:magenta' --colors 'line:bg:yellow' foo
For tty handling, we've adopted a hack from `git` to do tty detection in
MSYS/mintty terminals. As a result, ripgrep should get both color
detection and piping correct on Windows regardless of which terminal you
use.
Finally, switch to line buffering. Performance doesn't seem to be
impacted and it's an otherwise more user friendly option.
Fixes #37, Fixes #51, Fixes #94, Fixes #117, Fixes #182, Fixes #231
2016-11-20 18:14:52 +02:00
|
|
|
.B \-\-colors \f[I]SPEC\f[] ...
|
|
|
|
This flag specifies color settings for use in the output.
|
|
|
|
This flag may be provided multiple times.
|
|
|
|
Settings are applied iteratively.
|
|
|
|
Colors are limited to one of eight choices: red, blue, green, cyan,
|
|
|
|
magenta, yellow, white and black.
|
2017-01-07 03:07:29 +02:00
|
|
|
Styles are limited to nobold, bold, nointense or intense.
|
Completely re-work colored output and tty handling.
This commit completely guts all of the color handling code and replaces
most of it with two new crates: wincolor and termcolor. wincolor
provides a simple API to coloring using the Windows console and
termcolor provides a platform independent coloring API tuned for
multithreaded command line programs. This required a lot more
flexibility than what the `term` crate provided, so it was dropped.
We instead switch to writing ANSI escape sequences directly and ignore
the TERMINFO database.
In addition to fixing several bugs, this commit also permits end users
to customize colors to a certain extent. For example, this command will
set the match color to magenta and the line number background to yellow:
rg --colors 'match:fg:magenta' --colors 'line:bg:yellow' foo
For tty handling, we've adopted a hack from `git` to do tty detection in
MSYS/mintty terminals. As a result, ripgrep should get both color
detection and piping correct on Windows regardless of which terminal you
use.
Finally, switch to line buffering. Performance doesn't seem to be
impacted and it's an otherwise more user friendly option.
Fixes #37, Fixes #51, Fixes #94, Fixes #117, Fixes #182, Fixes #231
2016-11-20 18:14:52 +02:00
|
|
|
.RS
|
|
|
|
.PP
|
|
|
|
The format of the flag is {type}:{attribute}:{value}.
|
2017-04-09 15:08:49 +02:00
|
|
|
{type} should be one of path, line, column or match.
|
Completely re-work colored output and tty handling.
This commit completely guts all of the color handling code and replaces
most of it with two new crates: wincolor and termcolor. wincolor
provides a simple API to coloring using the Windows console and
termcolor provides a platform independent coloring API tuned for
multithreaded command line programs. This required a lot more
flexibility than what the `term` crate provided, so it was dropped.
We instead switch to writing ANSI escape sequences directly and ignore
the TERMINFO database.
In addition to fixing several bugs, this commit also permits end users
to customize colors to a certain extent. For example, this command will
set the match color to magenta and the line number background to yellow:
rg --colors 'match:fg:magenta' --colors 'line:bg:yellow' foo
For tty handling, we've adopted a hack from `git` to do tty detection in
MSYS/mintty terminals. As a result, ripgrep should get both color
detection and piping correct on Windows regardless of which terminal you
use.
Finally, switch to line buffering. Performance doesn't seem to be
impacted and it's an otherwise more user friendly option.
Fixes #37, Fixes #51, Fixes #94, Fixes #117, Fixes #182, Fixes #231
2016-11-20 18:14:52 +02:00
|
|
|
{attribute} can be fg, bg or style.
|
|
|
|
Value is either a color (for fg and bg) or a text style.
|
|
|
|
A special format, {type}:none, will clear all color settings for {type}.
|
|
|
|
.PP
|
|
|
|
For example, the following command will change the match color to
|
|
|
|
magenta and the background color for line numbers to yellow:
|
2017-05-26 22:24:49 +02:00
|
|
|
.IP
|
|
|
|
.nf
|
|
|
|
\f[C]
|
|
|
|
rg\ \-\-colors\ \[aq]match:fg:magenta\[aq]\ \-\-colors\ \[aq]line:bg:yellow\[aq]\ foo.
|
|
|
|
\f[]
|
|
|
|
.fi
|
Completely re-work colored output and tty handling.
This commit completely guts all of the color handling code and replaces
most of it with two new crates: wincolor and termcolor. wincolor
provides a simple API to coloring using the Windows console and
termcolor provides a platform independent coloring API tuned for
multithreaded command line programs. This required a lot more
flexibility than what the `term` crate provided, so it was dropped.
We instead switch to writing ANSI escape sequences directly and ignore
the TERMINFO database.
In addition to fixing several bugs, this commit also permits end users
to customize colors to a certain extent. For example, this command will
set the match color to magenta and the line number background to yellow:
rg --colors 'match:fg:magenta' --colors 'line:bg:yellow' foo
For tty handling, we've adopted a hack from `git` to do tty detection in
MSYS/mintty terminals. As a result, ripgrep should get both color
detection and piping correct on Windows regardless of which terminal you
use.
Finally, switch to line buffering. Performance doesn't seem to be
impacted and it's an otherwise more user friendly option.
Fixes #37, Fixes #51, Fixes #94, Fixes #117, Fixes #182, Fixes #231
2016-11-20 18:14:52 +02:00
|
|
|
.RE
|
|
|
|
.TP
|
2016-09-22 23:48:41 +02:00
|
|
|
.B \-\-column
|
|
|
|
Show column numbers (1 based) in output.
|
|
|
|
This only shows the column numbers for the first match on each line.
|
|
|
|
Note that this doesn\[aq]t try to account for Unicode.
|
|
|
|
One byte is equal to one column.
|
2017-01-12 01:53:35 +02:00
|
|
|
This implies \-\-line\-number.
|
2016-09-22 23:48:41 +02:00
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
2017-01-11 01:16:15 +02:00
|
|
|
.B \-\-context\-separator \f[I]SEPARATOR\f[]
|
2016-09-22 23:48:41 +02:00
|
|
|
The string to use when separating non\-continuous context lines.
|
|
|
|
Escape sequences may be used.
|
|
|
|
[default: \-\-]
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
|
|
|
.B \-\-debug
|
|
|
|
Show debug messages.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
2017-03-13 02:24:45 +02:00
|
|
|
.B \-E, \-\-encoding \f[I]ENCODING\f[]
|
|
|
|
Specify the text encoding that ripgrep will use on all files searched.
|
|
|
|
The default value is \[aq]auto\[aq], which will cause ripgrep to do a
|
|
|
|
best effort automatic detection of encoding on a per\-file basis.
|
|
|
|
Other supported values can be found in the list of labels here:
|
|
|
|
https://encoding.spec.whatwg.org/#concept\-encoding\-get
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
2017-05-26 22:24:49 +02:00
|
|
|
.B \-f, \-\-file \f[I]FILE\f[] ...
|
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
2016-11-13 04:48:11 +02:00
|
|
|
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
|
2016-09-22 23:48:41 +02:00
|
|
|
.B \-\-files
|
|
|
|
Print each file that would be searched (but don\[aq]t search).
|
|
|
|
.RS
|
2016-12-22 14:21:22 +02:00
|
|
|
.PP
|
|
|
|
Combine with the \-g flag to return matched paths, for example:
|
2017-05-26 22:24:49 +02:00
|
|
|
.IP
|
|
|
|
.nf
|
|
|
|
\f[C]
|
|
|
|
rg\ \-g\ \[aq]*.foo\[aq]\ \-\-files
|
|
|
|
\f[]
|
|
|
|
.fi
|
2016-09-22 23:48:41 +02:00
|
|
|
.RE
|
|
|
|
.TP
|
2016-09-26 00:32:41 +02:00
|
|
|
.B \-l, \-\-files\-with\-matches
|
|
|
|
Only show path of each file with matches.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
2016-11-20 03:15:41 +02:00
|
|
|
.B \-\-files\-without\-match
|
2016-11-20 01:48:59 +02:00
|
|
|
Only show path of each file with no matches.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
2016-09-22 23:48:41 +02:00
|
|
|
.B \-H, \-\-with\-filename
|
2017-09-06 11:34:57 +02:00
|
|
|
Display the file name for matches.
|
2016-09-22 23:48:41 +02:00
|
|
|
This is the default when more than one file is searched.
|
2017-09-06 11:34:57 +02:00
|
|
|
If \-\-heading is enabled, the file name will be shown above clusters of
|
|
|
|
matches from each file; otherwise, the file name will be shown on each
|
|
|
|
match.
|
2016-09-22 23:48:41 +02:00
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
2016-09-25 01:23:19 +02:00
|
|
|
.B \-\-no\-filename
|
|
|
|
Never show the filename for a match.
|
|
|
|
This is the default when one file is searched.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
2016-09-22 23:48:41 +02:00
|
|
|
.B \-\-heading
|
2016-11-29 00:39:45 +02:00
|
|
|
Show the file name above clusters of matches from each file instead of
|
|
|
|
showing the file name for every match.
|
2016-09-22 23:48:41 +02:00
|
|
|
This is the default mode at a tty.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
|
|
|
.B \-\-no\-heading
|
2016-11-29 00:39:45 +02:00
|
|
|
Don\[aq]t group matches by each file.
|
|
|
|
If \-H/\-\-with\-filename is enabled, then file names will be shown for
|
|
|
|
every line matched.
|
2017-05-24 22:15:55 +02:00
|
|
|
This is the default mode when not at a tty.
|
2016-09-22 23:48:41 +02:00
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
|
|
|
.B \-\-hidden
|
|
|
|
Search hidden directories and files.
|
|
|
|
(Hidden directories and files are skipped by default.)
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
2017-08-24 01:14:27 +02:00
|
|
|
.B \-\-iglob \f[I]GLOB\f[] ...
|
|
|
|
Include or exclude files/directories case insensitively.
|
|
|
|
This always overrides any other ignore logic if there is a conflict, but
|
|
|
|
is otherwise applied in addition to ignore files (e.g., .gitignore or
|
|
|
|
\&.ignore).
|
|
|
|
Multiple glob flags may be used.
|
|
|
|
Globbing rules match .gitignore globs.
|
|
|
|
Precede a glob with a \[aq]!\[aq] to exclude it.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
2017-05-26 22:24:49 +02:00
|
|
|
.B \-\-ignore\-file \f[I]FILE\f[] ...
|
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
2016-11-13 04:48:11 +02:00
|
|
|
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
|
2016-09-22 23:48:41 +02:00
|
|
|
.B \-L, \-\-follow
|
|
|
|
Follow symlinks.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
2018-01-01 16:00:31 +02:00
|
|
|
.B \-\-line\-number\-width \f[I]NUM\f[]
|
|
|
|
Specify a width for the displayed line number.
|
|
|
|
If number of digits in the line number is less than this number, it is
|
|
|
|
left padded with spaces.
|
|
|
|
Note: This setting has no effect if \-\-no\-line\-number is enabled.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
2017-04-09 14:49:19 +02:00
|
|
|
.B \-M, \-\-max\-columns \f[I]NUM\f[]
|
|
|
|
Don\[aq]t print lines longer than this limit in bytes.
|
|
|
|
Longer lines are omitted, and only the number of matches in that line is
|
|
|
|
printed.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
2017-02-28 06:53:52 +02:00
|
|
|
.B \-m, \-\-max\-count \f[I]NUM\f[]
|
2016-11-06 20:09:53 +02:00
|
|
|
Limit the number of matching lines per file searched to NUM.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
2017-02-28 06:53:52 +02:00
|
|
|
.B \-\-max\-filesize \f[I]NUM\f[]+\f[I]SUFFIX\f[]?
|
|
|
|
Ignore files larger than \f[I]NUM\f[] in size.
|
|
|
|
Directories will never be ignored.
|
|
|
|
.RS
|
|
|
|
.PP
|
|
|
|
\f[I]SUFFIX\f[] is optional and may be one of K, M or G.
|
|
|
|
These correspond to kilobytes, megabytes and gigabytes respectively.
|
|
|
|
If omitted the input is treated as bytes.
|
|
|
|
.RE
|
|
|
|
.TP
|
2016-09-28 22:30:57 +02:00
|
|
|
.B \-\-maxdepth \f[I]NUM\f[]
|
|
|
|
Descend at most NUM directories below the command line arguments.
|
|
|
|
A value of zero searches only the starting\-points themselves.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
2016-09-22 23:48:41 +02:00
|
|
|
.B \-\-mmap
|
|
|
|
Search using memory maps when possible.
|
|
|
|
This is enabled by default when ripgrep thinks it will be faster.
|
|
|
|
(Note that mmap searching doesn\[aq]t currently support the various
|
|
|
|
context related options.)
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
2016-11-06 21:36:08 +02:00
|
|
|
.B \-\-no\-messages
|
|
|
|
Suppress all error messages.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
2016-09-22 23:48:41 +02:00
|
|
|
.B \-\-no\-mmap
|
|
|
|
Never use memory maps, even when they might be faster.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
|
|
|
.B \-\-no\-ignore
|
2016-09-24 04:44:17 +02:00
|
|
|
Don\[aq]t respect ignore files (.gitignore, .ignore, etc.) This implies
|
|
|
|
\-\-no\-ignore\-parent.
|
2016-09-22 23:48:41 +02:00
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
|
|
|
.B \-\-no\-ignore\-parent
|
|
|
|
Don\[aq]t respect ignore files in parent directories.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
2016-09-25 03:31:24 +02:00
|
|
|
.B \-\-no\-ignore\-vcs
|
|
|
|
Don\[aq]t respect version control ignore files (e.g., .gitignore).
|
|
|
|
Note that .ignore files will continue to be respected.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
2017-04-09 14:49:19 +02:00
|
|
|
.B \-0, \-\-null
|
2016-09-27 01:21:17 +02:00
|
|
|
Whenever a file name is printed, follow it with a NUL byte.
|
|
|
|
This includes printing filenames before matches, and when printing a
|
|
|
|
list of matching files such as with \-\-count, \-\-files\-with\-matches
|
|
|
|
and \-\-files.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
2017-04-09 14:49:19 +02:00
|
|
|
.B \-o, \-\-only\-matching
|
|
|
|
Print only the matched (non\-empty) parts of a matching line, with each
|
|
|
|
such part on a separate output line.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
2018-01-12 01:45:51 +02:00
|
|
|
.B \-\-passthru, \-\-passthrough
|
|
|
|
Show both matching and non\-matching lines.
|
|
|
|
This is equivalent to adding ^ to the list of search patterns.
|
|
|
|
This option overrides \-\-count and cannot be used with
|
|
|
|
\-\-only\-matching or \-\-replace.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
2017-01-11 01:16:15 +02:00
|
|
|
.B \-\-path\-separator \f[I]SEPARATOR\f[]
|
|
|
|
The path separator to use when printing file paths.
|
|
|
|
This defaults to your platform\[aq]s path separator, which is / on Unix
|
|
|
|
and \\ on Windows.
|
|
|
|
This flag is intended for overriding the default when the environment
|
|
|
|
demands it (e.g., cygwin).
|
|
|
|
A path separator is limited to a single byte.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
2016-09-22 23:48:41 +02:00
|
|
|
.B \-p, \-\-pretty
|
2017-05-26 22:24:49 +02:00
|
|
|
Alias for \-\-color=always \-\-heading \-\-line\-number.
|
2016-09-22 23:48:41 +02:00
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
2016-10-11 02:19:45 +02:00
|
|
|
.B \-r, \-\-replace \f[I]ARG\f[]
|
|
|
|
Replace every match with the string given when printing search results.
|
|
|
|
Neither this flag nor any other flag will modify your files.
|
|
|
|
.RS
|
|
|
|
.PP
|
|
|
|
Capture group indices (e.g., $5) and names (e.g., $foo) are supported in
|
|
|
|
the replacement string.
|
2017-01-10 23:43:28 +02:00
|
|
|
.PP
|
|
|
|
Note that the replacement by default replaces each match, and NOT the
|
|
|
|
entire line.
|
|
|
|
To replace the entire line, you should match the entire line.
|
|
|
|
For example, to emit only the first phone numbers in each line:
|
|
|
|
.IP
|
|
|
|
.nf
|
|
|
|
\f[C]
|
|
|
|
rg\ \[aq]^.*([0\-9]{3}\-[0\-9]{3}\-[0\-9]{4}).*$\[aq]\ \-\-replace\ \[aq]$1\[aq]
|
|
|
|
\f[]
|
|
|
|
.fi
|
2016-10-11 02:19:45 +02:00
|
|
|
.RE
|
|
|
|
.TP
|
2016-09-28 22:30:57 +02:00
|
|
|
.B \-s, \-\-case\-sensitive
|
2017-10-11 01:18:36 +02:00
|
|
|
Search case sensitively (default).
|
|
|
|
Overrides \-\-ignore\-case and \-\-smart\-case.
|
2016-09-28 22:30:57 +02:00
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
2016-09-25 03:51:04 +02:00
|
|
|
.B \-S, \-\-smart\-case
|
|
|
|
Search case insensitively if the pattern is all lowercase.
|
|
|
|
Search case sensitively otherwise.
|
2016-09-28 22:30:57 +02:00
|
|
|
This is overridden by either \-\-case\-sensitive or \-\-ignore\-case.
|
2017-12-18 23:04:56 +02:00
|
|
|
Note: This feature is smart enough to treat simple classes like \\S as
|
|
|
|
lowercase, but may not handle more complex syntax like \\p{Ll} as
|
|
|
|
expected.
|
2016-09-25 03:51:04 +02:00
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
2017-01-07 05:43:59 +02:00
|
|
|
.B \-\-sort\-files
|
|
|
|
Sort results by file path.
|
|
|
|
Note that this currently disables all parallelism and runs search in a
|
|
|
|
single thread.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
2016-09-22 23:48:41 +02:00
|
|
|
.B \-j, \-\-threads \f[I]ARG\f[]
|
|
|
|
The number of threads to use.
|
2017-01-08 23:06:20 +02:00
|
|
|
0 means use the number of logical CPUs (capped at 12).
|
2016-09-22 23:48:41 +02:00
|
|
|
[default: 0]
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
|
|
|
.B \-\-version
|
|
|
|
Show the version number of ripgrep and exit.
|
|
|
|
.RS
|
|
|
|
.RE
|
2016-09-23 03:32:38 +02:00
|
|
|
.TP
|
|
|
|
.B \-\-vimgrep
|
|
|
|
Show results with every match on its own line, including line numbers
|
|
|
|
and column numbers.
|
2017-05-26 22:24:49 +02:00
|
|
|
With this option, a line with more than one match will be printed more
|
|
|
|
than once.
|
2016-09-23 03:32:38 +02:00
|
|
|
.RS
|
2017-05-26 22:24:49 +02:00
|
|
|
.PP
|
|
|
|
Recommended .vimrc configuration:
|
|
|
|
.IP
|
|
|
|
.nf
|
|
|
|
\f[C]
|
|
|
|
\ \ set\ grepprg=rg\\\ \-\-vimgrep
|
|
|
|
\ \ set\ grepformat^=%f:%l:%c:%m
|
|
|
|
\f[]
|
|
|
|
.fi
|
|
|
|
.PP
|
|
|
|
Use :grep to grep for something, then :cn and :cp to navigate through
|
|
|
|
the matches.
|
2016-09-23 03:32:38 +02:00
|
|
|
.RE
|
2016-09-22 23:48:41 +02:00
|
|
|
.SH FILE TYPE MANAGEMENT OPTIONS
|
|
|
|
.TP
|
|
|
|
.B \-\-type\-list
|
|
|
|
Show all supported file types and their associated globs.
|
|
|
|
.RS
|
|
|
|
.RE
|
|
|
|
.TP
|
|
|
|
.B \-\-type\-add \f[I]ARG\f[] ...
|
|
|
|
Add a new glob for a particular file type.
|
2016-09-25 20:36:53 +02:00
|
|
|
Only one glob can be added at a time.
|
|
|
|
Multiple \-\-type\-add flags can be provided.
|
|
|
|
Unless \-\-type\-clear is used, globs are added to any existing globs
|
|
|
|
inside of ripgrep.
|
2016-09-25 00:55:48 +02:00
|
|
|
Note that this must be passed to every invocation of rg.
|
2016-10-11 02:19:45 +02:00
|
|
|
Type settings are NOT persisted.
|
2017-05-26 22:24:49 +02:00
|
|
|
Example:
|
2016-09-22 23:48:41 +02:00
|
|
|
.RS
|
2017-01-02 02:32:46 +02:00
|
|
|
.IP
|
|
|
|
.nf
|
|
|
|
\f[C]
|
2017-05-26 22:24:49 +02:00
|
|
|
\ \ rg\ \-\-type\-add\ \[aq]foo:*.foo\[aq]\ \-tfoo\ PATTERN
|
2017-01-02 02:32:46 +02:00
|
|
|
\f[]
|
|
|
|
.fi
|
2016-09-25 00:55:48 +02:00
|
|
|
.PP
|
2017-01-02 02:32:46 +02:00
|
|
|
\-\-type\-add can also be used to include rules from other types with
|
|
|
|
the special include directive.
|
|
|
|
The include directive permits specifying one or more other type names
|
|
|
|
(separated by a comma) that have been defined and its rules will
|
|
|
|
automatically be imported into the type specified.
|
|
|
|
For example, to create a type called src that matches C++, Python and
|
|
|
|
Markdown files, one can use:
|
|
|
|
.IP
|
|
|
|
.nf
|
|
|
|
\f[C]
|
2017-05-26 22:24:49 +02:00
|
|
|
\ \ \-\-type\-add\ \[aq]src:include:cpp,py,md\[aq]
|
2017-01-02 02:32:46 +02:00
|
|
|
\f[]
|
|
|
|
.fi
|
|
|
|
.PP
|
|
|
|
Additional glob rules can still be added to the src type by using the
|
|
|
|
\-\-type\-add flag again:
|
|
|
|
.IP
|
|
|
|
.nf
|
|
|
|
\f[C]
|
2017-05-26 22:24:49 +02:00
|
|
|
\ \ \-\-type\-add\ \[aq]src:include:cpp,py,md\[aq]\ \-\-type\-add\ \[aq]src:*.foo\[aq]
|
2017-01-02 02:32:46 +02:00
|
|
|
\f[]
|
|
|
|
.fi
|
|
|
|
.PP
|
|
|
|
Note that type names must consist only of Unicode letters or numbers.
|
|
|
|
Punctuation characters are not allowed.
|
2016-10-11 02:19:45 +02:00
|
|
|
.RE
|
2016-09-22 23:48:41 +02:00
|
|
|
.TP
|
|
|
|
.B \-\-type\-clear \f[I]TYPE\f[] ...
|
2016-09-25 00:55:48 +02:00
|
|
|
Clear the file type globs previously defined for TYPE.
|
|
|
|
This only clears the default type definitions that are found inside of
|
|
|
|
ripgrep.
|
|
|
|
Note that this must be passed to every invocation of rg.
|
2016-09-22 23:48:41 +02:00
|
|
|
.RS
|
|
|
|
.RE
|
2017-01-07 05:52:57 +02:00
|
|
|
.SH SHELL COMPLETION
|
|
|
|
.PP
|
|
|
|
Shell completion files are included in the release tarball for Bash,
|
|
|
|
Fish, Zsh and PowerShell.
|
|
|
|
.PP
|
|
|
|
For \f[B]bash\f[], move \f[C]rg.bash\-completion\f[] to
|
|
|
|
\f[C]$XDG_CONFIG_HOME/bash_completion\f[] or
|
|
|
|
\f[C]/etc/bash_completion.d/\f[].
|
|
|
|
.PP
|
|
|
|
For \f[B]fish\f[], move \f[C]rg.fish\f[] to
|
|
|
|
\f[C]$HOME/.config/fish/completions\f[].
|