diff options
author | Andrew Gallant <jamslam@gmail.com> | 2018-02-05 18:45:45 -0500 |
---|---|---|
committer | Andrew Gallant <jamslam@gmail.com> | 2018-02-06 12:07:59 -0500 |
commit | 65539403288c984c5175a612c9519437742fc95c (patch) | |
tree | 056d146f6fc56cd229eb7266a9e46805644ad62a /doc | |
parent | b50ae9a99c46acf40d1c47c2e0ef6947fefbc044 (diff) |
doc: generate man page
This commit uses the recent refactoring for defining flags to
automatically generate a man page. This finally allows us to define the
documentation for each flag in a single place.
The man page is generated on every build, if and only if `asciidoc` is
installed. When generated, it is placed in Cargo's `OUT_DIR` directory,
which is the same place that shell completions live.
Diffstat (limited to 'doc')
-rwxr-xr-x | doc/convert-to-man | 5 | ||||
-rw-r--r-- | doc/rg.1 | 692 | ||||
-rw-r--r-- | doc/rg.1.md | 456 | ||||
-rw-r--r-- | doc/rg.1.txt.tpl | 136 |
4 files changed, 136 insertions, 1153 deletions
diff --git a/doc/convert-to-man b/doc/convert-to-man deleted file mode 100755 index 60761dba..00000000 --- a/doc/convert-to-man +++ /dev/null @@ -1,5 +0,0 @@ -#!/bin/sh -e - -pandoc -s -f markdown-smart -t man rg.1.md -o rg.1 -sed -i.bak 's/\.TH.*/.TH "rg" "1"/g' rg.1 -rm -f rg.1.bak # BSD `sed` requires the creation of a back-up file diff --git a/doc/rg.1 b/doc/rg.1 deleted file mode 100644 index b8112463..00000000 --- a/doc/rg.1 +++ /dev/null @@ -1,692 +0,0 @@ -.\" Automatically generated by Pandoc 2.0.6 -.\" -.TH "rg" "1" -.hy -.SH NAME -.PP -rg \- recursively search current directory for lines matching a pattern -.SH SYNOPSIS -.PP -rg [\f[I]OPTIONS\f[]] \f[I]PATTERN\f[] [\f[I]PATH\f[] ...] -.PP -rg [\f[I]OPTIONS\f[]] [\-e \f[I]PATTERN\f[] ...] [\-f \f[I]FILE\f[] ...] -[\f[I]PATH\f[] ...] -.PP -rg [\f[I]OPTIONS\f[]] \-\-files [\f[I]PATH\f[] ...] -.PP -rg [\f[I]OPTIONS\f[]] \-\-type\-list -.PP -rg [\f[I]OPTIONS\f[]] \-\-help -.PP -rg [\f[I]OPTIONS\f[]] \-\-version -.SH DESCRIPTION -.PP -ripgrep (rg) combines the usability of The Silver Searcher (an ack -clone) with the raw speed of grep. -.PP -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 -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 -Project home page: https://github.com/BurntSushi/ripgrep -.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 -.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[] -Whether to use color in the output. -Valid values are never, auto, always or ansi. -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. -.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. -This is also useful when searching for patterns that start with a dash. -.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. -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 -.PP -The \-\-glob flag subsumes the functionality of both the \-\-include and -\-\-exclude flags commonly found in other tools. -.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: -.IP -.nf -\f[C] -rg\ \-g\ \[aq]*.foo\[aq]\ \-\-files -\f[] -.fi -.RE -.TP -.B \-h, \-\-help -Show this usage message. -.RS -.RE -.TP -.B \-i, \-\-ignore\-case -Case insensitive search. -Overridden by \-\-case\-sensitive. -.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. -If a match is found in a file, stop searching that file. -.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. -\-uu is equivalent to \f[C]grep\ \-r\f[], and \-uuu is equivalent to -\f[C]grep\ \-a\ \-r\f[]. -.RS -.PP -Note that the \-u flags are convenient aliases for other combinations of -flags. -\-u aliases \-\-no\-ignore. -\-uu aliases \-\-no\-ignore \-\-hidden. -\-uuu aliases \-\-no\-ignore \-\-hidden \-\-text. -.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 -.TP -.B \-x, \-\-line\-regexp -Only show matches surrounded by line boundaries. -This is equivalent to putting ^...$ around the search pattern. -.RS -.RE -.TP -.B \-z, \-\-search\-zip -Search in compressed files. -Currently gz, bz2, xz and lzma formats are supported. -.RS -.PP -Note that ripgrep expects to find the decompression binaries for the -respective formats in your system\[aq]s PATH for use with this flag. -.RE -.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 -.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. -Styles are limited to nobold, bold, nointense or intense. -.RS -.PP -The format of the flag is {type}:{attribute}:{value}. -{type} should be one of path, line, column or match. -{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: -.IP -.nf -\f[C] -rg\ \-\-colors\ \[aq]match:fg:magenta\[aq]\ \-\-colors\ \[aq]line:bg:yellow\[aq]\ foo. -\f[] -.fi -.RE -.TP -.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. -This implies \-\-line\-number. -.RS -.RE -.TP -.B \-\-context\-separator \f[I]SEPARATOR\f[] -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 -.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 -.B \-f, \-\-file \f[I]FILE\f[] ... -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 -.PP -Combine with the \-g flag to return matched paths, for example: -.IP -.nf -\f[C] -rg\ \-g\ \[aq]*.foo\[aq]\ \-\-files -\f[] -.fi -.RE -.TP -.B \-l, \-\-files\-with\-matches -Only show path of each file with matches. -.RS -.RE -.TP -.B \-\-files\-without\-match -Only show path of each file with no matches. -.RS -.RE -.TP -.B \-H, \-\-with\-filename -Display the file name for matches. -This is the default when more than one file is searched. -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. -.RS -.RE -.TP -.B \-\-no\-filename -Never show the filename for a match. -This is the default when one file is searched. -.RS -.RE -.TP -.B \-\-heading -Show the file name above clusters of matches from each file instead of -showing the file name for every match. -This is the default mode at a tty. -.RS -.RE -.TP -.B \-\-no\-heading -Don\[aq]t group matches by each file. -If \-H/\-\-with\-filename is enabled, then file names will be shown for -every line matched. -This is the default mode when not at a tty. -.RS -.RE -.TP -.B \-\-hidden -Search hidden directories and files. -(Hidden directories and files are skipped by default.) -.RS -.RE -.TP -.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 -.B \-\-ignore\-file \f[I]FILE\f[] ... -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 -.RE -.TP -.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 -.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 -.B \-m, \-\-max\-count \f[I]NUM\f[] -Limit the number of matching lines per file searched to NUM. -.RS -.RE -.TP -.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 -.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 -.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 -.B \-\-no\-config -Never read configuration files. -When this flag is present, ripgrep will not respect the -RIPGREP_CONFIG_PATH environment variable. -.RS -.PP -If ripgrep ever grows a feature to automatically read configuration -files in pre\-defined locations, then this flag will also disable that -behavior as well. -.RE -.TP -.B \-\-no\-messages -Suppress all error messages. -.RS -.RE -.TP -.B \-\-no\-mmap -Never use memory maps, even when they might be faster. -.RS -.RE -.TP -.B \-\-no\-ignore -Don\[aq]t respect ignore files (.gitignore, .ignore, etc.) This implies -\-\-no\-ignore\-parent. -.RS -.RE -.TP -.B \-\-no\-ignore\-parent -Don\[aq]t respect ignore files in parent directories. -.RS -.RE -.TP -.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 -.B \-0, \-\-null -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 -.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 -.B \-\-passthru, \-\-passthrough -Show both matching and non\-matching lines. -This option cannot be used with \-\-only\-matching or \-\-replace. -.RS -.RE -.TP -.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 -.B \-p, \-\-pretty -Alias for \-\-color=always \-\-heading \-\-line\-number. -.RS -.RE -.TP -.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. -.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 -.RE -.TP -.B \-s, \-\-case\-sensitive -Search case sensitively (default). -Overrides \-\-ignore\-case and \-\-smart\-case. -.RS -.RE -.TP -.B \-S, \-\-smart\-case -Search case insensitively if the pattern is all lowercase. -Search case sensitively otherwise. -This is overridden by either \-\-case\-sensitive or \-\-ignore\-case. -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. -.RS -.RE -.TP -.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 -.B \-j, \-\-threads \f[I]ARG\f[] -The number of threads to use. -0 means use the number of logical CPUs (capped at 12). -[default: 0] -.RS -.RE -.TP -.B \-\-version -Show the version number of ripgrep and exit. -.RS -.RE -.TP -.B \-\-vimgrep -Show results with every match on its own line, including line numbers -and column numbers. -With this option, a line with more than one match will be printed more -than once. -.RS -.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. -.RE -.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. -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. -Note that this must be passed to every invocation of rg. -Type settings are NOT persisted. -Example: -.RS -.IP -.nf -\f[C] -\ \ rg\ \-\-type\-add\ \[aq]foo:*.foo\[aq]\ \-tfoo\ PATTERN -\f[] -.fi -.PP -\-\-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] -\ \ \-\-type\-add\ \[aq]src:include:cpp,py,md\[aq] -\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] -\ \ \-\-type\-add\ \[aq]src:include:cpp,py,md\[aq]\ \-\-type\-add\ \[aq]src:*.foo\[aq] -\f[] -.fi -.PP -Note that type names must consist only of Unicode letters or numbers. -Punctuation characters are not allowed. -.RE -.TP -.B \-\-type\-clear \f[I]TYPE\f[] ... -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. -.RS -.RE -.SH CONFIGURATION FILES -.PP -ripgrep supports reading configuration files that change ripgrep\[aq]s -default behavior. -The format of the configuration file is an "rc" style and is very -simple. -It is defined by two rules: -.IP -.nf -\f[C] -1.\ Every\ line\ is\ a\ shell\ argument,\ after\ trimming\ ASCII\ whitespace. -2.\ Lines\ starting\ with\ \[aq]#\[aq]\ (optionally\ preceded\ by\ any\ amount\ of -\ \ \ ASCII\ whitespace)\ are\ ignored. -\f[] -.fi -.PP -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. -.PP -For example, if your ripgreprc file contained a single line: -.IP -.nf -\f[C] -\-\-smart\-case -\f[] -.fi -.PP -then the following command -.IP -.nf -\f[C] -RIPGREP_CONFIG_PATH=wherever/.ripgreprc\ rg\ foo -\f[] -.fi -.PP -would behave identically to the following command -.IP -.nf -\f[C] -rg\ \-\-smart\-case\ foo -\f[] -.fi -.PP -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. -.PP -Conflicts between configuration files and explicit arguments are handled -exactly like conflicts in the same command line invocation. -That is, this command: -.IP -.nf -\f[C] -RIPGREP_CONFIG_PATH=wherever/.ripgreprc\ rg\ foo\ \-\-case\-sensitive -\f[] -.fi -.PP -is exactly equivalent to -.IP -.nf -\f[C] -rg\ \-\-smart\-case\ foo\ \-\-case\-sensitive -\f[] -.fi -.PP -in which case, the \-\-case\-sensitive flag would override the -\-\-smart\-case flag. -.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[]. diff --git a/doc/rg.1.md b/doc/rg.1.md deleted file mode 100644 index c92c6aa3..00000000 --- a/doc/rg.1.md +++ /dev/null @@ -1,456 +0,0 @@ -# NAME - -rg - recursively search current directory for lines matching a pattern - -# SYNOPSIS - -rg [*OPTIONS*] *PATTERN* [*PATH* ...] - -rg [*OPTIONS*] [-e *PATTERN* ...] [-f *FILE* ...] [*PATH* ...] - -rg [*OPTIONS*] --files [*PATH* ...] - -rg [*OPTIONS*] --type-list - -rg [*OPTIONS*] --help - -rg [*OPTIONS*] --version - -# DESCRIPTION - -ripgrep (rg) combines the usability of The Silver Searcher (an ack clone) with -the raw speed of grep. - -ripgrep's regex engine uses finite automata and guarantees linear time -searching. Because of this, features like backreferences and arbitrary -lookaround are not supported. - -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. - -Project home page: https://github.com/BurntSushi/ripgrep - -# POSITIONAL ARGUMENTS - -*PATTERN* -: A regular expression used for searching. To match a pattern beginning with a - dash, use the -e/--regexp option. - -*PATH* -: A file or directory to search. Directories are searched recursively. Paths - specified expicitly on the command line override glob and ignore rules. - -# COMMON OPTIONS - --a, --text -: Search binary files as if they were text. - --c, --count -: Only show count of line matches for each file. - ---color *WHEN* -: Whether to use color in the output. Valid values are never, auto, always or - ansi. 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. - --e, --regexp *PATTERN* ... -: Use PATTERN to search. This option can be provided multiple times, where all - patterns given are searched. This is also useful when searching for patterns - that start with a dash. - --F, --fixed-strings -: Treat the pattern as a literal string instead of a regular expression. - --g, --glob *GLOB* ... -: Include or exclude files for searching that match the given glob. 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 '!' to exclude it. - - The --glob flag subsumes the functionality of both the --include and - --exclude flags commonly found in other tools. - - Values given to -g must be quoted or your shell will expand them and result - in unexpected behavior. - - Combine with the --files flag to return matched filenames - (i.e., to replicate ack/ag's -g flag). For example: - - rg -g '*.foo' --files - --h, --help -: Show this usage message. - --i, --ignore-case -: Case insensitive search. Overridden by --case-sensitive. - --n, --line-number -: Show line numbers (1-based). This is enabled by default at a tty. - --N, --no-line-number -: Suppress line numbers. - --q, --quiet -: Do not print anything to stdout. If a match is found in a file, stop - searching that file. - --t, --type *TYPE* ... -: Only search files matching TYPE. Multiple type flags may be provided. Use the - --type-list flag to list all available types. - --T, --type-not *TYPE* ... -: Do not search files matching TYPE. Multiple not-type flags may be provided. - --u, --unrestricted ... -: Reduce the level of 'smart' searching. A single -u doesn't respect .gitignore - (etc.) files. Two -u flags will search hidden files and directories. Three - -u flags will search binary files. -uu is equivalent to `grep -r`, and -uuu - is equivalent to `grep -a -r`. - - Note that the -u flags are convenient aliases for other combinations of - flags. -u aliases --no-ignore. -uu aliases --no-ignore --hidden. - -uuu aliases --no-ignore --hidden --text. - --v, --invert-match -: Invert matching. - --w, --word-regexp -: Only show matches surrounded by word boundaries. This is equivalent to - putting \\b before and after the search pattern. - --x, --line-regexp -: Only show matches surrounded by line boundaries. This is equivalent to - putting ^...$ around the search pattern. - --z, --search-zip -: Search in compressed files. Currently gz, bz2, xz and lzma - formats are supported. - - Note that ripgrep expects to find the decompression binaries for the - respective formats in your system's PATH for use with this flag. - -# LESS COMMON OPTIONS - --A, --after-context *NUM* -: Show NUM lines after each match. - --B, --before-context *NUM* -: Show NUM lines before each match. - --C, --context *NUM* -: Show NUM lines before and after each match. - ---colors *SPEC* ... -: 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. Styles are limited to nobold, bold, nointense or intense. - - The format of the flag is {type}:{attribute}:{value}. {type} should be one - of path, line, column or match. {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}. - - For example, the following command will change the match color to magenta - and the background color for line numbers to yellow: - - rg --colors 'match:fg:magenta' --colors 'line:bg:yellow' foo. - ---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't try - to account for Unicode. One byte is equal to one column. This implies - --line-number. - ---context-separator *SEPARATOR* -: The string to use when separating non-continuous context lines. Escape - sequences may be used. [default: --] - ---debug -: Show debug messages. - --E, --encoding *ENCODING* -: Specify the text encoding that ripgrep will use on all files - searched. The default value is 'auto', 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 - --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). - - Combine with the -g flag to return matched paths, for example: - - rg -g '*.foo' --files - --l, --files-with-matches -: Only show path of each file with matches. - ---files-without-match -: Only show path of each file with no matches. - --H, --with-filename -: Display the file name for matches. This is the default when - more than one file is searched. 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. - ---no-filename -: Never show the filename for a match. This is the default when - one file is searched. - ---heading -: Show the file name above clusters of matches from each file instead of - showing the file name for every match. This is the default mode at a tty. - ---no-heading -: Don't group matches by each file. If -H/--with-filename is enabled, then - file names will be shown for every line matched. This is the default mode - when not at a tty. - ---hidden -: Search hidden directories and files. (Hidden directories and files are - skipped by default.) - ---iglob *GLOB* ... -: 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 '!' to exclude it. - ---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. - ---line-number-width *NUM* -: 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. - --M, --max-columns *NUM* -: Don't print lines longer than this limit in bytes. Longer lines are omitted, - and only the number of matches in that line is printed. - --m, --max-count *NUM* -: Limit the number of matching lines per file searched to NUM. - ---max-filesize *NUM*+*SUFFIX*? -: Ignore files larger than *NUM* in size. Directories will never be ignored. - - *SUFFIX* 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. - ---maxdepth *NUM* -: Descend at most NUM directories below the command line arguments. - A value of zero searches only the starting-points themselves. - ---mmap -: Search using memory maps when possible. This is enabled by default - when ripgrep thinks it will be faster. (Note that mmap searching - doesn't currently support the various context related options.) - ---no-config -: Never read configuration files. When this flag is present, ripgrep will not - respect the RIPGREP_CONFIG_PATH environment variable. - - If ripgrep ever grows a feature to automatically read configuration files - in pre-defined locations, then this flag will also disable that behavior as - well. - ---no-messages -: Suppress all error messages. - ---no-mmap -: Never use memory maps, even when they might be faster. - ---no-ignore -: Don't respect ignore files (.gitignore, .ignore, etc.) - This implies --no-ignore-parent. - ---no-ignore-parent -: Don't respect ignore files in parent directories. - ---no-ignore-vcs -: Don't respect version control ignore files (e.g., .gitignore). - Note that .ignore files will continue to be respected. - --0, --null -: 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. - --o, --only-matching -: Print only the matched (non-empty) parts of a matching line, with each such - part on a separate output line. - ---passthru, --passthrough -: Show both matching and non-matching lines. This option cannot be used with - --only-matching or --replace. - ---path-separator *SEPARATOR* -: The path separator to use when printing file paths. This defaults to your - platform'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. - --p, --pretty -: Alias for --color=always --heading --line-number. - --r, --replace *ARG* -: Replace every match with the string given when printing search results. - Neither this flag nor any other flag will modify your files. - - Capture group indices (e.g., $5) and names (e.g., $foo) are supported - in the replacement string. - - 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: - - rg '^.*([0-9]{3}-[0-9]{3}-[0-9]{4}).*$' --replace '$1' - --s, --case-sensitive -: Search case sensitively (default). Overrides --ignore-case and --smart-case. - --S, --smart-case -: Search case insensitively if the pattern is all lowercase. - Search case sensitively otherwise. This is overridden by either - --case-sensitive or --ignore-case. 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. - ---sort-files -: Sort results by file path. Note that this currently - disables all parallelism and runs search in a single thread. - --j, --threads *ARG* -: The number of threads to use. 0 means use the number of logical CPUs - (capped at 12). [default: 0] - ---version -: Show the version number of ripgrep and exit. - ---vimgrep -: Show results with every match on its own line, including - line numbers and column numbers. With this option, a line with - more than one match will be printed more than once. - - Recommended .vimrc configuration: - - set grepprg=rg\ --vimgrep - set grepformat^=%f:%l:%c:%m - - Use :grep to grep for something, then :cn and :cp to navigate through the - matches. - -# FILE TYPE MANAGEMENT OPTIONS - ---type-list -: Show all supported file types and their associated globs. |