2016-09-12 01:27:50 +02:00
|
|
|
ripgrep (rg)
|
|
|
|
------------
|
2018-02-07 01:49:30 +02:00
|
|
|
ripgrep is a line-oriented search tool that recursively searches your current
|
|
|
|
directory for a regex pattern while respecting your gitignore rules. ripgrep
|
|
|
|
has first class support on Windows, macOS and Linux, with binary downloads
|
|
|
|
available for [every release](https://github.com/BurntSushi/ripgrep/releases).
|
|
|
|
ripgrep is similar to other popular search tools like The Silver Searcher,
|
|
|
|
ack and grep.
|
2016-12-12 14:03:37 +02:00
|
|
|
|
2018-08-03 23:26:22 +02:00
|
|
|
[![Linux build status](https://travis-ci.org/BurntSushi/ripgrep.svg)](https://travis-ci.org/BurntSushi/ripgrep)
|
2016-09-23 12:56:56 +02:00
|
|
|
[![Windows build status](https://ci.appveyor.com/api/projects/status/github/BurntSushi/ripgrep?svg=true)](https://ci.appveyor.com/project/BurntSushi/ripgrep)
|
2018-05-24 12:46:08 +02:00
|
|
|
[![Crates.io](https://img.shields.io/crates/v/ripgrep.svg)](https://crates.io/crates/ripgrep)
|
2016-09-23 12:56:56 +02:00
|
|
|
|
|
|
|
Dual-licensed under MIT or the [UNLICENSE](http://unlicense.org).
|
|
|
|
|
2018-02-07 01:49:30 +02:00
|
|
|
|
2017-03-13 03:57:50 +02:00
|
|
|
### CHANGELOG
|
|
|
|
|
2017-03-13 03:58:29 +02:00
|
|
|
Please see the [CHANGELOG](CHANGELOG.md) for a release history.
|
2017-03-13 03:57:50 +02:00
|
|
|
|
2018-02-07 01:49:30 +02:00
|
|
|
### Documentation quick links
|
|
|
|
|
|
|
|
* [Installation](#installation)
|
|
|
|
* [User Guide](GUIDE.md)
|
|
|
|
* [Frequently Asked Questions](FAQ.md)
|
2018-08-28 01:13:57 +02:00
|
|
|
* [Regex syntax](https://docs.rs/regex/1/regex/#syntax)
|
2018-02-07 01:49:30 +02:00
|
|
|
* [Configuration files](GUIDE.md#configuration-file)
|
|
|
|
* [Shell completions](FAQ.md#complete)
|
|
|
|
* [Building](#building)
|
|
|
|
|
|
|
|
|
2016-09-23 12:56:56 +02:00
|
|
|
### Screenshot of search results
|
|
|
|
|
|
|
|
[![A screenshot of a sample search with ripgrep](http://burntsushi.net/stuff/ripgrep1.png)](http://burntsushi.net/stuff/ripgrep1.png)
|
|
|
|
|
2018-02-07 01:49:30 +02:00
|
|
|
|
2016-11-07 00:59:57 +02:00
|
|
|
### Quick examples comparing tools
|
2016-09-23 12:56:56 +02:00
|
|
|
|
|
|
|
This example searches the entire Linux kernel source tree (after running
|
|
|
|
`make defconfig && make -j8`) for `[A-Z]+_SUSPEND`, where all matches must be
|
2016-11-07 01:02:45 +02:00
|
|
|
words. Timings were collected on a system with an Intel i7-6900K 3.2 GHz, and
|
2018-02-07 01:49:30 +02:00
|
|
|
ripgrep was compiled with SIMD enabled.
|
2016-09-23 12:56:56 +02:00
|
|
|
|
|
|
|
Please remember that a single benchmark is never enough! See my
|
2018-02-07 01:49:30 +02:00
|
|
|
[blog post on ripgrep](http://blog.burntsushi.net/ripgrep/)
|
2016-09-23 12:56:56 +02:00
|
|
|
for a very detailed comparison with more benchmarks and analysis.
|
|
|
|
|
|
|
|
| Tool | Command | Line count | Time |
|
|
|
|
| ---- | ------- | ---------- | ---- |
|
2018-01-09 02:21:23 +02:00
|
|
|
| ripgrep (Unicode) | `rg -n -w '[A-Z]+_SUSPEND'` | 450 | **0.106s** |
|
|
|
|
| [git grep](https://www.kernel.org/pub/software/scm/git/docs/git-grep.html) | `LC_ALL=C git grep -E -n -w '[A-Z]+_SUSPEND'` | 450 | 0.553s |
|
|
|
|
| [The Silver Searcher](https://github.com/ggreer/the_silver_searcher) | `ag -w '[A-Z]+_SUSPEND'` | 450 | 0.589s |
|
|
|
|
| [git grep (Unicode)](https://www.kernel.org/pub/software/scm/git/docs/git-grep.html) | `LC_ALL=en_US.UTF-8 git grep -E -n -w '[A-Z]+_SUSPEND'` | 450 | 2.266s |
|
|
|
|
| [sift](https://github.com/svent/sift) | `sift --git -n -w '[A-Z]+_SUSPEND'` | 450 | 3.505s |
|
|
|
|
| [ack](https://github.com/petdance/ack2) | `ack -w '[A-Z]+_SUSPEND'` | 1878 | 6.823s |
|
|
|
|
| [The Platinum Searcher](https://github.com/monochromegane/the_platinum_searcher) | `pt -w -e '[A-Z]+_SUSPEND'` | 450 | 14.208s |
|
2016-09-23 12:56:56 +02:00
|
|
|
|
|
|
|
(Yes, `ack` [has](https://github.com/petdance/ack2/issues/445) a
|
|
|
|
[bug](https://github.com/petdance/ack2/issues/14).)
|
|
|
|
|
2016-11-07 00:55:38 +02:00
|
|
|
Here's another benchmark that disregards gitignore files and searches with a
|
|
|
|
whitelist instead. The corpus is the same as in the previous benchmark, and the
|
2017-10-31 23:17:35 +02:00
|
|
|
flags passed to each command ensure that they are doing equivalent work:
|
2016-11-07 00:55:38 +02:00
|
|
|
|
|
|
|
| Tool | Command | Line count | Time |
|
|
|
|
| ---- | ------- | ---------- | ---- |
|
2018-01-09 02:21:23 +02:00
|
|
|
| ripgrep | `rg -L -u -tc -n -w '[A-Z]+_SUSPEND'` | 404 | **0.079s** |
|
|
|
|
| [ucg](https://github.com/gvansickle/ucg) | `ucg --type=cc -w '[A-Z]+_SUSPEND'` | 390 | 0.163s |
|
|
|
|
| [GNU grep](https://www.gnu.org/software/grep/) | `egrep -R -n --include='*.c' --include='*.h' -w '[A-Z]+_SUSPEND'` | 404 | 0.611s |
|
2016-11-07 00:55:38 +02:00
|
|
|
|
2016-11-07 02:45:18 +02:00
|
|
|
(`ucg` [has slightly different behavior in the presence of symbolic links](https://github.com/gvansickle/ucg/issues/106).)
|
2016-11-07 00:55:38 +02:00
|
|
|
|
2017-10-31 23:17:35 +02:00
|
|
|
And finally, a straight-up comparison between ripgrep and GNU grep on a single
|
2016-11-07 00:59:57 +02:00
|
|
|
large file (~9.3GB,
|
|
|
|
[`OpenSubtitles2016.raw.en.gz`](http://opus.lingfil.uu.se/OpenSubtitles2016/mono/OpenSubtitles2016.raw.en.gz)):
|
2016-11-07 00:55:38 +02:00
|
|
|
|
|
|
|
| Tool | Command | Line count | Time |
|
|
|
|
| ---- | ------- | ---------- | ---- |
|
2018-01-09 02:21:23 +02:00
|
|
|
| ripgrep | `rg -w 'Sherlock [A-Z]\w+'` | 5268 | **2.108s** |
|
|
|
|
| [GNU grep](https://www.gnu.org/software/grep/) | `LC_ALL=C egrep -w 'Sherlock [A-Z]\w+'` | 5268 | 7.014s |
|
2016-11-07 00:55:38 +02:00
|
|
|
|
|
|
|
In the above benchmark, passing the `-n` flag (for showing line numbers)
|
2018-01-09 02:21:23 +02:00
|
|
|
increases the times to `2.640s` for ripgrep and `10.277s` for GNU grep.
|
2016-11-07 00:55:38 +02:00
|
|
|
|
2018-02-07 01:49:30 +02:00
|
|
|
|
|
|
|
### Why should I use ripgrep?
|
2016-09-23 12:56:56 +02:00
|
|
|
|
2018-08-03 23:26:22 +02:00
|
|
|
* It can replace many use cases served by other search tools
|
|
|
|
because it contains most of their features and is generally faster. (See
|
|
|
|
[the FAQ](FAQ.md#posix4ever) for more details on whether ripgrep can truly
|
|
|
|
replace grep.)
|
|
|
|
* Like other tools specialized to code search, ripgrep defaults to recursive
|
|
|
|
directory search and won't search files ignored by your `.gitignore` files.
|
|
|
|
It also ignores hidden and binary files by default. ripgrep also implements
|
|
|
|
full support for `.gitignore`, whereas there are many bugs related to that
|
|
|
|
functionality in other code search tools claiming to provide the same
|
|
|
|
functionality.
|
2018-02-07 01:49:30 +02:00
|
|
|
* ripgrep can search specific types of files. For example, `rg -tpy foo`
|
2016-09-23 12:56:56 +02:00
|
|
|
limits your search to Python files and `rg -Tjs foo` excludes Javascript
|
2018-02-07 01:49:30 +02:00
|
|
|
files from your search. ripgrep can be taught about new file types with
|
2016-09-23 12:56:56 +02:00
|
|
|
custom matching rules.
|
2018-02-07 01:49:30 +02:00
|
|
|
* ripgrep supports many features found in `grep`, such as showing the context
|
2016-09-23 12:56:56 +02:00
|
|
|
of search results, searching multiple patterns, highlighting matches with
|
2018-02-07 01:49:30 +02:00
|
|
|
color and full Unicode support. Unlike GNU grep, ripgrep stays fast while
|
2016-09-23 12:56:56 +02:00
|
|
|
supporting Unicode (which is always on).
|
2018-08-28 01:13:57 +02:00
|
|
|
* ripgrep has optional support for switching its regex engine to use PCRE2.
|
|
|
|
Among other things, this makes it possible to use look-around and
|
2018-09-07 23:43:24 +02:00
|
|
|
backreferences in your patterns, which are not supported in ripgrep's default
|
2018-08-28 01:13:57 +02:00
|
|
|
regex engine. PCRE2 support is enabled with `-P`.
|
2018-02-07 01:49:30 +02:00
|
|
|
* ripgrep supports searching files in text encodings other than UTF-8, such
|
Add support for additional text encodings.
This includes, but is not limited to, UTF-16, latin-1, GBK, EUC-JP and
Shift_JIS. (Courtesy of the `encoding_rs` crate.)
Specifically, this feature enables ripgrep to search files that are
encoded in an encoding other than UTF-8. The list of available encodings
is tied directly to what the `encoding_rs` crate supports, which is in
turn tied to the Encoding Standard. The full list of available encodings
can be found here: https://encoding.spec.whatwg.org/#concept-encoding-get
This pull request also introduces the notion that text encodings can be
automatically detected on a best effort basis. Currently, the only
support for this is checking for a UTF-16 bom. In all other cases, a
text encoding of `auto` (the default) implies a UTF-8 or ASCII
compatible source encoding. When a text encoding is otherwise specified,
it is unconditionally used for all files searched.
Since ripgrep's regex engine is fundamentally built on top of UTF-8,
this feature works by transcoding the files to be searched from their
source encoding to UTF-8. This transcoding only happens when:
1. `auto` is specified and a non-UTF-8 encoding is detected.
2. A specific encoding is given by end users (including UTF-8).
When transcoding occurs, errors are handled by automatically inserting
the Unicode replacement character. In this case, ripgrep's output is
guaranteed to be valid UTF-8 (excluding non-UTF-8 file paths, if they
are printed).
In all other cases, the source text is searched directly, which implies
an assumption that it is at least ASCII compatible, but where UTF-8 is
most useful. In this scenario, encoding errors are not detected. In this
case, ripgrep's output will match the input exactly, byte-for-byte.
This design may not be optimal in all cases, but it has some advantages:
1. In the happy path ("UTF-8 everywhere") remains happy. I have not been
able to witness any performance regressions.
2. In the non-UTF-8 path, implementation complexity is kept relatively
low. The cost here is transcoding itself. A potentially superior
implementation might build decoding of any encoding into the regex
engine itself. In particular, the fundamental problem with
transcoding everything first is that literal optimizations are nearly
negated.
Future work should entail improving the user experience. For example, we
might want to auto-detect more text encodings. A more elaborate UX
experience might permit end users to specify multiple text encodings,
although this seems hard to pull off in an ergonomic way.
Fixes #1
2017-03-09 03:22:48 +02:00
|
|
|
as UTF-16, latin-1, GBK, EUC-JP, Shift_JIS and more. (Some support for
|
|
|
|
automatically detecting UTF-16 is provided. Other text encodings must be
|
|
|
|
specifically specified with the `-E/--encoding` flag.)
|
2018-02-07 01:49:30 +02:00
|
|
|
* ripgrep supports searching files compressed in a common format (gzip, xz,
|
2018-04-27 11:37:53 +02:00
|
|
|
lzma, bzip2 or lz4) with the `-z/--search-zip` flag.
|
2018-07-13 15:54:51 +02:00
|
|
|
* ripgrep supports arbitrary input preprocessing filters which could be PDF
|
|
|
|
text extraction, less supported decompression, decrypting, automatic encoding
|
|
|
|
detection and so on.
|
2016-09-23 12:56:56 +02:00
|
|
|
|
2018-02-07 01:49:30 +02:00
|
|
|
In other words, use ripgrep if you like speed, filtering by default, fewer
|
2018-08-28 01:13:57 +02:00
|
|
|
bugs and Unicode support.
|
2017-01-10 02:55:56 +02:00
|
|
|
|
|
|
|
|
2018-02-07 01:49:30 +02:00
|
|
|
### Why shouldn't I use ripgrep?
|
|
|
|
|
2018-08-03 23:26:22 +02:00
|
|
|
Despite initially not wanting to add every feature under the sun to ripgrep,
|
|
|
|
over time, ripgrep has grown support for most features found in other file
|
|
|
|
searching tools. This includes searching for results spanning across multiple
|
|
|
|
lines, and opt-in support for PCRE2, which provides look-around and
|
|
|
|
backreference support.
|
2017-01-10 02:55:56 +02:00
|
|
|
|
2018-08-03 23:26:22 +02:00
|
|
|
At this point, the primary reasons not to use ripgrep probably consist of one
|
|
|
|
or more of the following:
|
2017-01-10 02:55:56 +02:00
|
|
|
|
2018-08-03 23:26:22 +02:00
|
|
|
* You need a portable and ubiquitous tool. While ripgrep works on Windows,
|
|
|
|
macOS and Linux, it is not ubiquitous and it does not conform to any
|
|
|
|
standard such as POSIX. The best tool for this job is good old grep.
|
2018-09-07 18:05:08 +02:00
|
|
|
* There still exists some other feature (or bug) not listed in this README that
|
|
|
|
you rely on that's in another tool that isn't in ripgrep.
|
2018-08-03 23:26:22 +02:00
|
|
|
* There is a performance edge case where ripgrep doesn't do well where another
|
|
|
|
tool does do well. (Please file a bug report!)
|
|
|
|
* ripgrep isn't possible to install on your machine or isn't available for your
|
|
|
|
platform. (Please file a bug report!)
|
2016-09-23 12:56:56 +02:00
|
|
|
|
2018-01-09 01:31:34 +02:00
|
|
|
|
2016-09-23 12:56:56 +02:00
|
|
|
### Is it really faster than everything else?
|
|
|
|
|
2017-09-04 17:14:57 +02:00
|
|
|
Generally, yes. A large number of benchmarks with detailed analysis for each is
|
2016-09-23 12:56:56 +02:00
|
|
|
[available on my blog](http://blog.burntsushi.net/ripgrep/).
|
|
|
|
|
2018-02-07 01:49:30 +02:00
|
|
|
Summarizing, ripgrep is fast because:
|
2016-09-23 12:56:56 +02:00
|
|
|
|
|
|
|
* It is built on top of
|
|
|
|
[Rust's regex engine](https://github.com/rust-lang-nursery/regex).
|
|
|
|
Rust's regex engine uses finite automata, SIMD and aggressive literal
|
2018-08-03 23:26:22 +02:00
|
|
|
optimizations to make searching very fast. (PCRE2 support can be opted into
|
|
|
|
with the `-P/--pcre2` flag.)
|
2016-09-23 12:56:56 +02:00
|
|
|
* Rust's regex library maintains performance with full Unicode support by
|
|
|
|
building UTF-8 decoding directly into its deterministic finite automaton
|
|
|
|
engine.
|
|
|
|
* It supports searching with either memory maps or by searching incrementally
|
|
|
|
with an intermediate buffer. The former is better for single files and the
|
2018-02-07 01:49:30 +02:00
|
|
|
latter is better for large directories. ripgrep chooses the best searching
|
2016-09-23 12:56:56 +02:00
|
|
|
strategy for you automatically.
|
|
|
|
* Applies your ignore patterns in `.gitignore` files using a
|
2018-08-28 01:13:57 +02:00
|
|
|
[`RegexSet`](https://docs.rs/regex/1/regex/struct.RegexSet.html).
|
2016-09-23 12:56:56 +02:00
|
|
|
That means a single file path can be matched against multiple glob patterns
|
|
|
|
simultaneously.
|
2016-11-07 01:51:00 +02:00
|
|
|
* It uses a lock-free parallel recursive directory iterator, courtesy of
|
2016-11-07 00:55:38 +02:00
|
|
|
[`crossbeam`](https://docs.rs/crossbeam) and
|
|
|
|
[`ignore`](https://docs.rs/ignore).
|
2016-09-23 12:56:56 +02:00
|
|
|
|
2018-02-07 01:49:30 +02:00
|
|
|
|
|
|
|
### Feature comparison
|
|
|
|
|
|
|
|
Andy Lester, author of [ack](https://beyondgrep.com/), has published an
|
|
|
|
excellent table comparing the features of ack, ag, git-grep, GNU grep and
|
|
|
|
ripgrep: https://beyondgrep.com/feature-comparison/
|
|
|
|
|
2018-08-03 23:26:22 +02:00
|
|
|
Note that ripgrep has grown a few significant new features recently that
|
|
|
|
are not yet present in Andy's table. This includes, but is not limited to,
|
|
|
|
configuration files, passthru, support for searching compressed files,
|
|
|
|
multiline search and opt-in fancy regex support via PCRE2.
|
|
|
|
|
2018-02-07 01:49:30 +02:00
|
|
|
|
2016-09-23 12:56:56 +02:00
|
|
|
### Installation
|
|
|
|
|
2018-02-07 01:49:30 +02:00
|
|
|
The binary name for ripgrep is `rg`.
|
2016-09-23 12:56:56 +02:00
|
|
|
|
2018-02-07 01:49:30 +02:00
|
|
|
**[Archives of precompiled binaries for ripgrep are available for Windows,
|
2017-10-14 06:08:33 +02:00
|
|
|
macOS and Linux.](https://github.com/BurntSushi/ripgrep/releases)** Users of
|
2018-02-18 17:31:12 +02:00
|
|
|
platforms not explicitly mentioned below are advised to download one of these
|
|
|
|
archives.
|
2017-10-01 03:05:12 +02:00
|
|
|
|
|
|
|
Linux binaries are static executables. Windows binaries are available either as
|
|
|
|
built with MinGW (GNU) or with Microsoft Visual C++ (MSVC). When possible,
|
|
|
|
prefer MSVC over GNU, but you'll need to have the [Microsoft VC++ 2015
|
|
|
|
redistributable](https://www.microsoft.com/en-us/download/details.aspx?id=48145)
|
2016-09-23 12:56:56 +02:00
|
|
|
installed.
|
|
|
|
|
2017-10-14 06:08:33 +02:00
|
|
|
If you're a **macOS Homebrew** or a **Linuxbrew** user,
|
2017-09-18 15:56:37 +02:00
|
|
|
then you can install ripgrep either
|
2016-10-10 06:45:02 +02:00
|
|
|
from homebrew-core, (compiled with rust stable, no SIMD):
|
|
|
|
|
|
|
|
```
|
|
|
|
$ brew install ripgrep
|
|
|
|
```
|
|
|
|
|
|
|
|
or you can install a binary compiled with rust nightly (including SIMD and all
|
|
|
|
optimizations) by utilizing a custom tap:
|
2016-09-23 12:56:56 +02:00
|
|
|
|
|
|
|
```
|
2016-09-26 19:53:19 +02:00
|
|
|
$ brew tap burntsushi/ripgrep https://github.com/BurntSushi/ripgrep.git
|
2018-03-07 19:44:06 +02:00
|
|
|
$ brew install ripgrep-bin
|
2016-09-23 12:56:56 +02:00
|
|
|
```
|
|
|
|
|
2018-05-24 19:01:28 +02:00
|
|
|
If you're a **MacPorts** user, then you can install ripgrep from the
|
|
|
|
[official ports](https://www.macports.org/ports.php?by=name&substr=ripgrep):
|
|
|
|
|
|
|
|
```
|
|
|
|
$ sudo port install ripgrep
|
|
|
|
```
|
|
|
|
|
2018-08-03 23:26:22 +02:00
|
|
|
If you're a **Windows Chocolatey** user, then you can install ripgrep from the
|
|
|
|
[official repo](https://chocolatey.org/packages/ripgrep):
|
2017-02-28 21:40:33 +02:00
|
|
|
|
|
|
|
```
|
|
|
|
$ choco install ripgrep
|
|
|
|
```
|
|
|
|
|
2018-08-03 23:26:22 +02:00
|
|
|
If you're a **Windows Scoop** user, then you can install ripgrep from the
|
|
|
|
[official bucket](https://github.com/lukesampson/scoop/blob/master/bucket/ripgrep.json):
|
2018-03-10 15:15:22 +02:00
|
|
|
|
|
|
|
```
|
|
|
|
$ scoop install ripgrep
|
|
|
|
```
|
|
|
|
|
2018-02-07 01:49:30 +02:00
|
|
|
If you're an **Arch Linux** user, then you can install ripgrep from the official repos:
|
2016-09-23 12:56:56 +02:00
|
|
|
|
|
|
|
```
|
2016-10-05 14:26:19 +02:00
|
|
|
$ pacman -S ripgrep
|
2016-09-23 12:56:56 +02:00
|
|
|
```
|
|
|
|
|
2018-08-03 23:26:22 +02:00
|
|
|
If you're a **Gentoo** user, you can install ripgrep from the
|
|
|
|
[official repo](https://packages.gentoo.org/packages/sys-apps/ripgrep):
|
2016-11-02 04:01:04 +02:00
|
|
|
|
|
|
|
```
|
2017-10-24 14:26:10 +02:00
|
|
|
$ emerge sys-apps/ripgrep
|
2016-11-02 04:01:04 +02:00
|
|
|
```
|
|
|
|
|
2019-01-28 15:15:36 +02:00
|
|
|
If you're a **Fedora** user, you can install ripgrep from official
|
2018-08-03 23:26:22 +02:00
|
|
|
repositories.
|
2018-01-07 21:33:52 +02:00
|
|
|
|
|
|
|
```
|
|
|
|
$ sudo dnf install ripgrep
|
|
|
|
```
|
|
|
|
|
2019-01-23 04:46:11 +02:00
|
|
|
If you're an **openSUSE Leap 15.0** user, you can install ripgrep from the
|
|
|
|
[utilities repo](https://build.opensuse.org/package/show/utilities/ripgrep):
|
|
|
|
|
|
|
|
```
|
|
|
|
$ sudo zypper ar https://download.opensuse.org/repositories/utilities/openSUSE_Leap_15.0/utilities.repo
|
|
|
|
$ sudo zypper install ripgrep
|
|
|
|
```
|
|
|
|
|
|
|
|
|
2018-08-03 23:26:22 +02:00
|
|
|
If you're an **openSUSE Tumbleweed** user, you can install ripgrep from the
|
|
|
|
[official repo](http://software.opensuse.org/package/ripgrep):
|
2018-04-09 13:22:04 +02:00
|
|
|
|
|
|
|
```
|
|
|
|
$ sudo zypper install ripgrep
|
|
|
|
```
|
|
|
|
|
2018-08-03 23:26:22 +02:00
|
|
|
If you're a **RHEL/CentOS 7** user, you can install ripgrep from
|
|
|
|
[copr](https://copr.fedorainfracloud.org/coprs/carlwgeorge/ripgrep/):
|
2016-10-16 11:06:52 +02:00
|
|
|
|
|
|
|
```
|
2018-01-07 21:33:52 +02:00
|
|
|
$ sudo yum-config-manager --add-repo=https://copr.fedorainfracloud.org/coprs/carlwgeorge/ripgrep/repo/epel-7/carlwgeorge-ripgrep-epel-7.repo
|
|
|
|
$ sudo yum install ripgrep
|
2016-10-16 11:06:52 +02:00
|
|
|
```
|
|
|
|
|
2018-02-07 01:49:30 +02:00
|
|
|
If you're a **Nix** user, you can install ripgrep from
|
2016-10-26 05:01:18 +02:00
|
|
|
[nixpkgs](https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/text/ripgrep/default.nix):
|
|
|
|
|
|
|
|
```
|
|
|
|
$ nix-env --install ripgrep
|
2018-02-07 01:49:30 +02:00
|
|
|
$ # (Or using the attribute name, which is also ripgrep.)
|
2016-10-26 05:01:18 +02:00
|
|
|
```
|
|
|
|
|
2018-02-20 14:01:49 +02:00
|
|
|
If you're a **Debian** user (or a user of a Debian derivative like **Ubuntu**),
|
|
|
|
then ripgrep can be installed using a binary `.deb` file provided in each
|
2018-09-14 08:41:05 +02:00
|
|
|
[ripgrep release](https://github.com/BurntSushi/ripgrep/releases).
|
2018-02-18 17:31:12 +02:00
|
|
|
|
|
|
|
```
|
2018-09-08 16:46:40 +02:00
|
|
|
$ curl -LO https://github.com/BurntSushi/ripgrep/releases/download/0.10.0/ripgrep_0.10.0_amd64.deb
|
|
|
|
$ sudo dpkg -i ripgrep_0.10.0_amd64.deb
|
2018-02-18 17:31:12 +02:00
|
|
|
```
|
|
|
|
|
2018-08-22 01:47:12 +02:00
|
|
|
If you run Debian Buster (currently Debian testing) or Debian sid, ripgrep is
|
2018-08-17 12:35:43 +02:00
|
|
|
[officially maintained by Debian](https://tracker.debian.org/pkg/rust-ripgrep).
|
|
|
|
```
|
|
|
|
$ sudo apt-get install ripgrep
|
|
|
|
```
|
|
|
|
|
2018-09-14 17:33:56 +02:00
|
|
|
If you're an **Ubuntu Cosmic (18.10)** (or newer) user, ripgrep is
|
|
|
|
[available](https://launchpad.net/ubuntu/+source/rust-ripgrep) using the same
|
|
|
|
packaging as Debian:
|
|
|
|
|
2018-09-14 08:41:05 +02:00
|
|
|
```
|
|
|
|
$ sudo apt-get install ripgrep
|
|
|
|
```
|
|
|
|
|
2018-04-30 21:25:51 +02:00
|
|
|
(N.B. Various snaps for ripgrep on Ubuntu are also available, but none of them
|
|
|
|
seem to work right and generate a number of very strange bug reports that I
|
|
|
|
don't know how to fix and don't have the time to fix. Therefore, it is no
|
|
|
|
longer a recommended installation option.)
|
2018-01-13 01:44:28 +02:00
|
|
|
|
2018-08-03 23:26:22 +02:00
|
|
|
If you're a **FreeBSD** user, then you can install ripgrep from the
|
|
|
|
[official ports](https://www.freshports.org/textproc/ripgrep/):
|
2018-05-14 12:45:39 +02:00
|
|
|
|
|
|
|
```
|
|
|
|
# pkg install ripgrep
|
|
|
|
```
|
|
|
|
|
2018-08-03 23:26:22 +02:00
|
|
|
If you're an **OpenBSD** user, then you can install ripgrep from the
|
|
|
|
[official ports](http://openports.se/textproc/ripgrep):
|
2018-05-14 12:45:39 +02:00
|
|
|
|
|
|
|
```
|
|
|
|
$ doas pkg_add ripgrep
|
|
|
|
```
|
|
|
|
|
2018-08-03 23:26:22 +02:00
|
|
|
If you're a **NetBSD** user, then you can install ripgrep from
|
|
|
|
[pkgsrc](http://pkgsrc.se/textproc/ripgrep):
|
2018-05-14 12:45:39 +02:00
|
|
|
|
|
|
|
```
|
|
|
|
# pkgin install ripgrep
|
|
|
|
```
|
|
|
|
|
2018-02-07 01:49:30 +02:00
|
|
|
If you're a **Rust programmer**, ripgrep can be installed with `cargo`.
|
2018-08-03 23:26:22 +02:00
|
|
|
|
2019-01-29 20:10:43 +02:00
|
|
|
* Note that the minimum supported version of Rust for ripgrep is **1.32.0**,
|
2017-10-03 17:36:37 +02:00
|
|
|
although ripgrep may work with older versions.
|
|
|
|
* Note that the binary may be bigger than expected because it contains debug
|
|
|
|
symbols. This is intentional. To remove debug symbols and therefore reduce
|
|
|
|
the file size, run `strip` on the binary.
|
2016-09-23 12:56:56 +02:00
|
|
|
|
|
|
|
```
|
|
|
|
$ cargo install ripgrep
|
|
|
|
```
|
|
|
|
|
2018-06-22 02:10:53 +02:00
|
|
|
When compiling with Rust 1.27 or newer, this will automatically enable SIMD
|
|
|
|
optimizations for search.
|
2018-03-10 21:02:06 +02:00
|
|
|
|
2018-02-07 01:49:30 +02:00
|
|
|
ripgrep isn't currently in any other package repositories.
|
2016-09-23 12:56:56 +02:00
|
|
|
[I'd like to change that](https://github.com/BurntSushi/ripgrep/issues/10).
|
|
|
|
|
2017-05-29 22:02:09 +02:00
|
|
|
|
2016-09-23 12:56:56 +02:00
|
|
|
### Building
|
|
|
|
|
2018-02-07 01:49:30 +02:00
|
|
|
ripgrep is written in Rust, so you'll need to grab a
|
2016-09-23 12:56:56 +02:00
|
|
|
[Rust installation](https://www.rust-lang.org/) in order to compile it.
|
2019-01-29 20:10:43 +02:00
|
|
|
ripgrep compiles with Rust 1.32.0 (stable) or newer. In general, ripgrep tracks
|
2018-08-22 01:47:12 +02:00
|
|
|
the latest stable release of the Rust compiler.
|
|
|
|
|
|
|
|
To build ripgrep:
|
2016-09-23 12:56:56 +02:00
|
|
|
|
|
|
|
```
|
2016-09-24 01:34:24 +02:00
|
|
|
$ git clone https://github.com/BurntSushi/ripgrep
|
2016-09-23 12:56:56 +02:00
|
|
|
$ cd ripgrep
|
|
|
|
$ cargo build --release
|
|
|
|
$ ./target/release/rg --version
|
|
|
|
0.1.3
|
|
|
|
```
|
|
|
|
|
2018-02-07 01:49:30 +02:00
|
|
|
If you have a Rust nightly compiler and a recent Intel CPU, then you can enable
|
2018-06-22 02:10:53 +02:00
|
|
|
additional optional SIMD acceleration like so:
|
2016-09-23 12:56:56 +02:00
|
|
|
|
2019-01-24 13:58:28 +02:00
|
|
|
**WARNING**: Building with the `simd-accel` feature on the latest Rust nightly
|
|
|
|
does not work because the [`encoding_rs`](https://crates.io/crates/encoding_rs)
|
|
|
|
crate hasn't yet migrated to the new SIMD infrastructure, and the old SIMD
|
|
|
|
infrastructure no longer works on the latest nightly version of Rust.
|
|
|
|
|
2016-09-23 12:56:56 +02:00
|
|
|
```
|
2019-01-24 13:58:28 +02:00
|
|
|
RUSTFLAGS="-C target-cpu=native" cargo build --release --features 'simd-accel'
|
2016-09-23 12:56:56 +02:00
|
|
|
```
|
|
|
|
|
2019-01-24 13:58:28 +02:00
|
|
|
The `simd-accel` feature enables SIMD support in certain ripgrep dependencies
|
|
|
|
(responsible for transcoding). They are not necessary to get SIMD optimizations
|
|
|
|
for search; those are enabled automatically. Hopefully, some day, the
|
|
|
|
`simd-accel` feature will similarly become unnecessary.
|
2018-06-22 02:10:53 +02:00
|
|
|
|
2018-08-03 23:26:22 +02:00
|
|
|
Finally, optional PCRE2 support can be built with ripgrep by enabling the
|
|
|
|
`pcre2` feature:
|
|
|
|
|
|
|
|
```
|
|
|
|
$ cargo build --release --features 'pcre2'
|
|
|
|
```
|
|
|
|
|
2019-01-24 13:58:28 +02:00
|
|
|
(Tip: use `--features 'pcre2 simd-accel'` to also include compile time SIMD
|
|
|
|
optimizations, which will only work with a nightly compiler.)
|
2018-08-23 15:55:31 +02:00
|
|
|
|
|
|
|
Enabling the PCRE2 feature works with a stable Rust compiler and will
|
|
|
|
attempt to automatically find and link with your system's PCRE2 library via
|
|
|
|
`pkg-config`. If one doesn't exist, then ripgrep will build PCRE2 from source
|
|
|
|
using your system's C compiler and then statically link it into the final
|
|
|
|
executable. Static linking can be forced even when there is an available PCRE2
|
|
|
|
system library by either building ripgrep with the MUSL target or by setting
|
|
|
|
`PCRE2_SYS_STATIC=1`.
|
2018-08-03 23:26:22 +02:00
|
|
|
|
|
|
|
ripgrep can be built with the MUSL target on Linux by first installing the MUSL
|
|
|
|
library on your system (consult your friendly neighborhood package manager).
|
|
|
|
Then you just need to add MUSL support to your Rust toolchain and rebuild
|
|
|
|
ripgrep, which yields a fully static executable:
|
|
|
|
|
|
|
|
```
|
|
|
|
$ rustup target add x86_64-unknown-linux-musl
|
|
|
|
$ cargo build --release --target x86_64-unknown-linux-musl
|
|
|
|
```
|
|
|
|
|
2018-09-07 18:05:08 +02:00
|
|
|
Applying the `--features` flag from above works as expected. If you want to
|
|
|
|
build a static executable with MUSL and with PCRE2, then you will need to have
|
|
|
|
`musl-gcc` installed, which might be in a separate package from the actual
|
|
|
|
MUSL library, depending on your Linux distribution.
|
2018-08-03 23:26:22 +02:00
|
|
|
|
2018-02-07 01:49:30 +02:00
|
|
|
|
2016-09-23 12:56:56 +02:00
|
|
|
### Running tests
|
|
|
|
|
2018-02-07 01:49:30 +02:00
|
|
|
ripgrep is relatively well-tested, including both unit tests and integration
|
2016-09-23 12:56:56 +02:00
|
|
|
tests. To run the full test suite, use:
|
|
|
|
|
|
|
|
```
|
2018-02-07 01:49:30 +02:00
|
|
|
$ cargo test --all
|
2016-09-23 12:56:56 +02:00
|
|
|
```
|
|
|
|
|
|
|
|
from the repository root.
|