diff options
| author | Andrew Gallant <jamslam@gmail.com> | 2018-02-06 18:49:30 -0500 |
|---|---|---|
| committer | Andrew Gallant <jamslam@gmail.com> | 2018-02-10 12:12:47 -0500 |
| commit | 904c75bd302311fe9e5e5a7238299e0105e19c8b (patch) | |
| tree | 18149741e03f452fc50bd0e086e091f04b91bd4c /README.md | |
| parent | ca3e0e8a498a0cb50960f32e9353d99b853c37a8 (diff) | |
doc: overhaul documentation
This commit cleans up the README and splits portions of it out into
a user guide (GUIDE.md) and a FAQ (FAQ.md). The README now provides a
small list of documentation "quick" links to various parts of the docs.
This commit also does a few other minor touchups.
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 430 |
1 files changed, 72 insertions, 358 deletions
@@ -1,11 +1,11 @@ ripgrep (rg) ------------ -`ripgrep` is a line-oriented search tool that recursively searches your current -directory for a regex pattern while respecting your gitignore rules. To a first -approximation, ripgrep combines the usability of The Silver Searcher (similar -to `ack`) with the raw speed of GNU grep. `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 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. [](https://travis-ci.org/BurntSushi/ripgrep) [](https://ci.appveyor.com/project/BurntSushi/ripgrep) @@ -13,23 +13,36 @@ Windows, macOS and Linux, with binary downloads available for Dual-licensed under MIT or the [UNLICENSE](http://unlicense.org). + ### CHANGELOG Please see the [CHANGELOG](CHANGELOG.md) for a release history. +### Documentation quick links + +* [Installation](#installation) +* [User Guide](GUIDE.md) +* [Frequently Asked Questions](FAQ.md) +* [Regex syntax](https://docs.rs/regex/0.2.5/regex/#syntax) +* [Configuration files](GUIDE.md#configuration-file) +* [Shell completions](FAQ.md#complete) +* [Building](#building) + + ### Screenshot of search results [](http://burntsushi.net/stuff/ripgrep1.png) + ### Quick examples comparing tools This example searches the entire Linux kernel source tree (after running `make defconfig && make -j8`) for `[A-Z]+_SUSPEND`, where all matches must be words. Timings were collected on a system with an Intel i7-6900K 3.2 GHz, and -ripgrep was compiled using the `compile` script in this repo. +ripgrep was compiled with SIMD enabled. Please remember that a single benchmark is never enough! See my -[blog post on `ripgrep`](http://blog.burntsushi.net/ripgrep/) +[blog post on ripgrep](http://blog.burntsushi.net/ripgrep/) for a very detailed comparison with more benchmarks and analysis. | Tool | Command | Line count | Time | @@ -69,65 +82,62 @@ large file (~9.3GB, In the above benchmark, passing the `-n` flag (for showing line numbers) increases the times to `2.640s` for ripgrep and `10.277s` for GNU grep. -### Why should I use `ripgrep`? + +### Why should I use ripgrep? * It can replace both The Silver Searcher and GNU grep because it is generally faster than both. (N.B. It is not, strictly speaking, a "drop-in" replacement for both, but the feature sets are far more similar than different.) -* Like The Silver Searcher, `ripgrep` defaults to recursive directory search +* Like The Silver Searcher, 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 + hidden and binary files by default. ripgrep also implements full support for `.gitignore`, whereas there are many bugs related to that functionality in The Silver Searcher. -* `ripgrep` can search specific types of files. For example, `rg -tpy foo` +* ripgrep can search specific types of files. For example, `rg -tpy foo` limits your search to Python files and `rg -Tjs foo` excludes Javascript - files from your search. `ripgrep` can be taught about new file types with + files from your search. ripgrep can be taught about new file types with custom matching rules. -* `ripgrep` supports many features found in `grep`, such as showing the context +* ripgrep supports many features found in `grep`, such as showing the context of search results, searching multiple patterns, highlighting matches with - color and full Unicode support. Unlike GNU grep, `ripgrep` stays fast while + color and full Unicode support. Unlike GNU grep, ripgrep stays fast while supporting Unicode (which is always on). -* `ripgrep` supports searching files in text encodings other than UTF-8, such +* ripgrep supports searching files in text encodings other than UTF-8, such 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.) -* `ripgrep` supports searching files compressed in a common format (gzip, xz, +* ripgrep supports searching files compressed in a common format (gzip, xz, lzma or bzip2 current) with the `-z/--search-zip` flag. -In other words, use `ripgrep` if you like speed, filtering by default, fewer +In other words, use ripgrep if you like speed, filtering by default, fewer bugs, and Unicode support. -### Why shouldn't I use `ripgrep`? -I'd like to try to convince you why you *shouldn't* use `ripgrep`. This should +### Why shouldn't I use ripgrep? + +I'd like to try to convince you why you *shouldn't* use ripgrep. This should give you a glimpse at some important downsides or missing features of -`ripgrep`. +ripgrep. -* `ripgrep` uses a regex engine based on finite automata, so if you want fancy - regex features such as backreferences or lookaround, `ripgrep` won't provide - them to you. `ripgrep` does support lots of things though, including, but not +* ripgrep uses a regex engine based on finite automata, so if you want fancy + regex features such as backreferences or lookaround, ripgrep won't provide + them to you. ripgrep does support lots of things though, including, but not limited to: lazy quantification (e.g., `a+?`), repetitions (e.g., `a{2,5}`), begin/end assertions (e.g., `^\w+$`), word boundaries (e.g., `\bfoo\b`), and support for Unicode categories (e.g., `\p{Sc}` to match currency symbols or `\p{Lu}` to match any uppercase letter). (Fancier regexes will never be supported.) -* `ripgrep` doesn't have multiline search. (Unlikely to ever be supported.) +* ripgrep doesn't have multiline search. (Will happen as an opt-in feature.) -In other words, if you like fancy regexes or multiline search, then `ripgrep` +In other words, if you like fancy regexes or multiline search, then ripgrep may not quite meet your needs (yet). -### 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/ ### Is it really faster than everything else? Generally, yes. A large number of benchmarks with detailed analysis for each is [available on my blog](http://blog.burntsushi.net/ripgrep/). -Summarizing, `ripgrep` is fast because: +Summarizing, ripgrep is fast because: * It is built on top of [Rust's regex engine](https://github.com/rust-lang-nursery/regex). @@ -138,7 +148,7 @@ Summarizing, `ripgrep` is fast because: 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 - latter is better for large directories. `ripgrep` chooses the best searching + latter is better for large directories. ripgrep chooses the best searching strategy for you automatically. * Applies your ignore patterns in `.gitignore` files using a [`RegexSet`](https://doc.rust-lang.org/regex/regex/struct.RegexSet.html). @@ -148,11 +158,19 @@ Summarizing, `ripgrep` is fast because: [`crossbeam`](https://docs.rs/crossbeam) and [`ignore`](https://docs.rs/ignore). + +### 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/ + + ### Installation -The binary name for `ripgrep` is `rg`. +The binary name for ripgrep is `rg`. -**[Archives of precompiled binaries for `ripgrep` are available for Windows, +**[Archives of precompiled binaries for ripgrep are available for Windows, macOS and Linux.](https://github.com/BurntSushi/ripgrep/releases)** Users of platforms not explicitly mentioned below (such as Debian) are advised to download one of these archives. @@ -179,53 +197,53 @@ $ brew tap burntsushi/ripgrep https://github.com/BurntSushi/ripgrep.git $ brew install burntsushi/ripgrep/ripgrep-bin ``` -If you're a **Windows Chocolatey** user, then you can install `ripgrep` from the [official repo](https://chocolatey.org/packages/ripgrep): +If you're a **Windows Chocolatey** user, then you can install ripgrep from the [official repo](https://chocolatey.org/packages/ripgrep): ``` $ choco install ripgrep ``` -If you're an **Arch Linux** user, then you can install `ripgrep` from the official repos: +If you're an **Arch Linux** user, then you can install ripgrep from the official repos: ``` $ pacman -S ripgrep ``` -If you're a **Gentoo** user, you can install `ripgrep` from the [official repo](https://packages.gentoo.org/packages/sys-apps/ripgrep): +If you're a **Gentoo** user, you can install ripgrep from the [official repo](https://packages.gentoo.org/packages/sys-apps/ripgrep): ``` $ emerge sys-apps/ripgrep ``` -If you're a **Fedora 27+** user, you can install `ripgrep` from official repositories. +If you're a **Fedora 27+** user, you can install ripgrep from official repositories. ``` $ sudo dnf install ripgrep ``` -If you're a **Fedora 24+** user, you can install `ripgrep` from [copr](https://copr.fedorainfracloud.org/coprs/carlwgeorge/ripgrep/): +If you're a **Fedora 24+** user, you can install ripgrep from [copr](https://copr.fedorainfracloud.org/coprs/carlwgeorge/ripgrep/): ``` $ sudo dnf copr enable carlwgeorge/ripgrep $ sudo dnf install ripgrep ``` -If you're a **RHEL/CentOS 7** user, you can install `ripgrep` from [copr](https://copr.fedorainfracloud.org/coprs/carlwgeorge/ripgrep/): +If you're a **RHEL/CentOS 7** user, you can install ripgrep from [copr](https://copr.fedorainfracloud.org/coprs/carlwgeorge/ripgrep/): ``` $ 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 ``` -If you're a **Nix** user, you can install `ripgrep` from +If you're a **Nix** user, you can install ripgrep from [nixpkgs](https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/text/ripgrep/default.nix): ``` $ nix-env --install ripgrep -$ # (Or using the attribute name, which is also `ripgrep`.) +$ # (Or using the attribute name, which is also ripgrep.) ``` -If you're an **Ubuntu** user, `ripgrep` can be installed from the `snap` store. +If you're an **Ubuntu** user, ripgrep can be installed from the `snap` store. * Note that if you are using `16.04 LTS` or later, snap is already installed. * For older versions you can install snap using [this guide](https://docs.snapcraft.io/core/install-ubuntu). @@ -234,8 +252,8 @@ If you're an **Ubuntu** user, `ripgrep` can be installed from the `snap` store. sudo snap install rg ``` -If you're a **Rust programmer**, `ripgrep` can be installed with `cargo`. -* Note that the minimum supported version of Rust for ripgrep is **1.17**, +If you're a **Rust programmer**, ripgrep can be installed with `cargo`. +* Note that the minimum supported version of Rust for ripgrep is **1.20**, 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 @@ -245,189 +263,15 @@ If you're a **Rust programmer**, `ripgrep` can be installed with `cargo`. $ cargo install ripgrep ``` -`ripgrep` isn't currently in any other package repositories. +ripgrep isn't currently in any other package repositories. [I'd like to change that](https://github.com/BurntSushi/ripgrep/issues/10). -### Whirlwind tour - -The command-line usage of `ripgrep` doesn't differ much from other tools that -perform a similar function, so you probably already know how to use `ripgrep`. -The full details can be found in `rg --help`, but let's go on a whirlwind tour. - -`ripgrep` detects when its printing to a terminal, and will automatically -colorize your output and show line numbers, just like The Silver Searcher. -Coloring works on Windows too! Colors can be controlled more granularly with -the `--color` flag. - -One last thing before we get started: generally speaking, `ripgrep` assumes the -input it is reading to be UTF-8. However, if ripgrep notices a file is encoded as -UTF-16, then it will know how to search it. For other encodings, you'll need to -explicitly specify them with the `-E/--encoding` flag. - -To recursively search the current directory, while respecting all `.gitignore` -files, ignore hidden files and directories and skip binary files: - -``` -$ rg foobar -``` - -The above command also respects all `.ignore` files, including in parent -directories. `.ignore` files can be used when `.gitignore` files are -insufficient. In all cases, `.ignore` patterns take precedence over -`.gitignore`. - -To ignore all ignore files, use `-u`. To additionally search hidden files -and directories, use `-uu`. To additionally search binary files, use `-uuu`. -(In other words, "search everything, dammit!") In particular, `rg -uuu` is -similar to `grep -a -r`. - -``` -$ rg -uu foobar # similar to `grep -r` -$ rg -uuu foobar # similar to `grep -a -r` -``` - -(Tip: If your ignore files aren't being adhered to like you expect, run your -search with the `--debug` flag.) - -Make the search case insensitive with `-i`, invert the search with `-v` or -show the 2 lines before and after every search result with `-C2`. - -Force all matches to be surrounded by word boundaries with `-w`. - -Search and replace (find first and last names and swap them): - -``` -$ rg '([A-Z][a-z]+)\s+([A-Z][a-z]+)' --replace '$2, $1' -``` - -Named groups are supported: - -``` -$ rg '(?P<first>[A-Z][a-z]+)\s+(?P<last>[A-Z][a-z]+)' --replace '$last, $first' -``` - -Up the ante with full Unicode support, by matching any uppercase Unicode letter -followed by any sequence of lowercase Unicode letters (good luck doing this -with other search tools!): - -``` -$ rg '(\p{Lu}\p{Ll}+)\s+(\p{Lu}\p{Ll}+)' --replace '$2, $1' -``` - -Search only files matching a particular glob: - -``` -$ rg foo -g 'README.*' -``` - -<!--*--> - -Or exclude files matching a particular glob: - -``` -$ rg foo -g '!*.min.js' -``` - -Search and return paths matching a particular glob (i.e., `-g` flag in ag/ack): - -``` -$ rg -g 'doc*' --files -``` - -Search only HTML and CSS files: - -``` -$ rg -thtml -tcss foobar -``` - -Search everything except for Javascript files: - -``` -$ rg -Tjs foobar -``` - -To see a list of types supported, run `rg --type-list`. To add a new type, use -`--type-add`, which must be accompanied by a pattern for searching (`rg` won't -persist your type settings): - -``` -$ rg --type-add 'foo:*.{foo,foobar}' -tfoo bar -``` - -The type `foo` will now match any file ending with the `.foo` or `.foobar` -extensions. - -### Regex syntax - -The syntax supported is -[documented as part of Rust's regex library](https://doc.rust-lang.org/regex/regex/index.html#syntax). - -### Configuration files - -ripgrep supports reading configuration files that change ripgrep's default -behavior. The format of the configuration file is an "rc" style and is very -simple. It is defined by two rules: - -1. Every line is a shell argument, after trimming ASCII whitespace. -2. Lines starting with '#' (optionally preceded by any amount of - ASCII whitespace) are ignored. - -ripgrep will look for a single configuration file if and only if the -`RIPGREP_CONFIG_PATH` environment variable is set and is non-empty. ripgrep -will parse shell arguments from this file on startup and will behave as if -the arguments in this file were prepended to any explicit arguments given to -ripgrep on the command line. - -For example, if your ripgreprc file contained a single line: - - --smart-case - -then the following command - - RIPGREP_CONFIG_PATH=wherever/.ripgreprc rg foo - -would behave identically to the following command - - rg --smart-case foo - -ripgrep also provides a flag, --no-config, that when present will suppress -any and all support for configuration. This includes any future support for -auto-loading configuration files from pre-determined paths. - -Conflicts between configuration files and explicit arguments are handled -exactly like conflicts in the same command line invocation. That is, this -command: - - RIPGREP_CONFIG_PATH=wherever/.ripgreprc rg foo --case-sensitive - -is exactly equivalent to - - rg --smart-case foo --case-sensitive - -in which case, the --case-sensitive flag would override the --smart-case flag. - -### Shell completions - -Shell completion files are included in the release tarball for Bash, Fish, Zsh -and PowerShell. - -For **bash**, move `complete/rg.bash-completion` to `$XDG_CONFIG_HOME/bash_completion` -or `/etc/bash_completion.d/`. - -For **fish**, move `complete/rg.fish` to `$HOME/.config/fish/completions/`. - -For **PowerShell**, add `. _rg.ps1` to your PowerShell -[profile](https://technet.microsoft.com/en-us/library/bb613488(v=vs.85).aspx) -(note the leading period). If the `_rg.ps1` file is not on your `PATH`, do -`. /path/to/_rg.ps1` instead. - -For **zsh**, move `complete/_rg` to one of your `$fpath` directories. ### Building -`ripgrep` is written in Rust, so you'll need to grab a +ripgrep is written in Rust, so you'll need to grab a [Rust installation](https://www.rust-lang.org/) in order to compile it. -`ripgrep` compiles with Rust 1.17 (stable) or newer. Building is easy: +ripgrep compiles with Rust 1.20 (stable) or newer. Building is easy: ``` $ git clone https://github.com/BurntSushi/ripgrep @@ -437,8 +281,8 @@ $ ./target/release/rg --version 0.1.3 ``` -If you have a Rust nightly compiler, then you can enable optional SIMD -acceleration like so: +If you have a Rust nightly compiler and a recent Intel CPU, then you can enable +optional SIMD acceleration like so: ``` RUSTFLAGS="-C target-cpu=native" cargo build --release --features 'simd-accel avx-accel' @@ -447,144 +291,14 @@ RUSTFLAGS="-C target-cpu=native" cargo build --release --features 'simd-accel av If your machine doesn't support AVX instructions, then simply remove `avx-accel` from the features list. Similarly for SIMD. + ### Running tests -`ripgrep` is relatively well-tested, including both unit tests and integration +ripgrep is relatively well-tested, including both unit tests and integration tests. To run the full test suite, use: ``` -$ cargo test +$ cargo test --all ``` from the repository root. - -### Tips - -#### Windows Powershell - -##### Powershell Profile - -To customize powershell on start-up, there is a special powershell script that has to be created. -In order to find its location, type `$profile` -See [more](https://technet.microsoft.com/en-us/library/bb613488(v=vs.85).aspx) for profile details. - -Any powershell code in this file gets evaluated at the start of console. -This way you can have own aliases to be created at start. - -##### Setup function alias - -Often you can find a need to make alias for the favourite utility. - -But powershell function aliases do not behave like your typical linux shell alias. - -You always need to propagate arguments and **Stdin** input. -But it cannot be done simply as `function grep() { $input | rg.exe --hidden $args }` - -Use below example as reference to how setup alias in powershell. - -```powershell -function grep { - $count = @($input).Count - $input.Reset() - - if ($count) { - $input | rg.exe --hidden $args - } - else { - rg.exe --hidden $args - } -} -``` - -Powershell special variables: -* input - is powershell **Stdin** object that allows you to access its content. -* args - is array of arguments passed to this function. - -This alias checks whether there is **Stdin** input and propagates only if there is some lines. -Otherwise empty `$input` will make powershell to trigger `rg` to search empty **Stdin** - -##### Piping non-ASCII content to ripgrep - -When piping input into native executables in PowerShell, the encoding of the -input is controlled by the `$OutputEncoding` variable. By default, this is set -to US-ASCII, and any characters in the pipeline that don't have encodings in -US-ASCII are converted to `?` (question mark) characters. - -To change this setting, set `$OutputEncoding` to a different encoding, as -represented by a .NET encoding object. Some common examples are below. The -value of this variable is reset when PowerShell restarts, so to make this -change take effect every time PowerShell is started add a line setting the -variable into your PowerShell profile. - -Example `$OutputEncoding` settings: -* UTF-8 without BOM: `$OutputEncoding = [System.Text.UTF8Encoding]::new()` -* The console's output encoding: -`$OutputEncoding = [System.Console]::OutputEncoding` - -If you continue to have encoding problems, you can also force the encoding -that the console will use for printing to UTF-8 with -`[System.Console]::OutputEncoding = [System.Text.Encoding]::UTF8`. This -will also reset when PowerShell is restarted, so you can add that line -to your profile as well if you want to make the setting permanent. - -#### How do I make the output look like ag's? - -Use the `--colors` flag, like so: - - rg --colors line:fg:yellow \ - --colors line:style:bold \ - --colors path:fg:green \ - --colors path:style:bold \ - --colors match:fg:black \ - --colors match:bg:yellow \ - --colors match:style:nobold \ - foo - -### Known issues - -#### I just hit Ctrl+C in the middle of ripgrep's output and now my terminal's foreground color is wrong! - -Type in `color` in cmd.exe (Command Prompt) and `echo -ne "\033[0m"` on Unix -to restore your original foreground color. - -In PowerShell, you can add the following code to your profile which will -restore the original foreground color when `Reset-ForegroundColor` is called. -Including the `Set-Alias` line will allow you to call it with simply `color`. - -```powershell -$OrigFgColor = $Host.UI.RawUI.ForegroundColor -function Reset-ForegroundColor { - $Host.UI.RawUI.ForegroundColor = $OrigFgColor -} -Set-Alias -Name color -Value Reset-ForegroundColor -``` - -PR [#187](https://github.com/BurntSushi/ripgrep/pull/187) fixed this, and it -was later deprecated in -[#281](https://github.com/BurntSushi/ripgrep/issues/281). A full explanation is -available [here][msys issue explanation]. - -[msys issue explanation]: https://github.com/BurntSushi/ripgrep/issues/281#issuecomment-269093893 - -#### When I run `rg` it executes some other command! - -It's likely that you have a shell alias or even another tool called `rg` which -is interfering with `ripgrep` — run `which rg` to see what it is. - -(Notably, the `rails` plug-in for -[Oh My Zsh](https://github.com/robbyrussell/oh-my-zsh/wiki/Plugins#rails) sets -up an `rg` alias for `rails generate`.) - -Problems like this can be resolved in one of several ways: - -* If you're using the OMZ `rails` plug-in, disable it by editing the `plugins` - array in your zsh configuration. -* Temporarily bypass an existing `rg` alias by calling `ripgrep` as - `command rg`, `\rg`, or `'rg'`. -* Temporarily bypass an existing alias or another tool named `rg` by calling - `ripgrep` by its full path (e.g., `/usr/bin/rg` or `/usr/local/bin/rg`). -* Permanently disable an existing `rg` alias by adding `unalias rg` to the - bottom of your shell configuration file (e.g., `.bash_profile` or `.zshrc`). -* Give `ripgrep` its own alias that doesn't conflict with other tools/aliases by - adding a line like the following to the bottom of your shell configuration - file: `alias ripgrep='command rg'` |