1RG(1) RG(1)
2
6 rg - recursively search current directory for lines matching a pattern
7
9 rg [OPTIONS] PATTERN [PATH...]
10 rg [OPTIONS] -e PATTERN... [PATH...]
12 rg [OPTIONS] -f PATTERNFILE... [PATH...]
14 rg [OPTIONS] --files [PATH...]
16 rg [OPTIONS] --type-list
18 command | rg [OPTIONS] PATTERN
20 rg [OPTIONS] --help
22 rg [OPTIONS] --version
24
26 ripgrep (rg) recursively searches your current directory for a regex
27 pattern. By default, ripgrep will respect your .gitignore and
28 automatically skip hidden files/directories and binary files.
29 ripgrep’s regex engine uses finite automata and guarantees linear time
31 searching. Because of this, features like backreferences and arbitrary
32 lookaround are not supported.
33
35 ripgrep uses Rust’s regex engine, which documents its syntax:
36 https://docs.rs/regex/0.2.5/regex/#syntax
37 ripgrep uses byte-oriented regexes, which has some additional
39 documentation:
40 https://docs.rs/regex/0.2.5/regex/bytes/index.html#syntax
41 To a first approximation, ripgrep uses Perl-like regexes without
43 look-around or backreferences. This makes them very similar to the
44 "extended" (ERE) regular expressions supported by egrep, but with a few
45 additional features like Unicode character classes.
46
48 PATTERN
49 A regular expression used for searching. To match a pattern
50 beginning with a dash, use the -e/--regexp option.
51 PATH
53 A file or directory to search. Directories are searched
54 recursively. Paths specified expicitly on the command line override
55 glob and ignore rules.
56
58 -A, --after-context NUM
59 Show NUM lines after each match.
60 This overrides the --context flag.
62 -B, --before-context NUM
64 Show NUM lines before each match.
65 This overrides the --context flag.
67 -b, --byte-offset
69 Print the 0-based byte offset within the input file before each
70 line of output. If -o (--only-matching) is specified, print the
71 offset of the matching part itself.
72 -s, --case-sensitive
74 Search case sensitively.
75 This overrides the -i/--ignore-case and -S/--smart-case flags.
77 --color WHEN
79 This flag controls when to use colors. The default setting is auto,
80 which means ripgrep will try to guess when to use colors. For
81 example, if ripgrep is printing to a terminal, then it will use
82 colors, but if it is redirected to a file or a pipe, then it will
83 suppress color output. ripgrep will suppress color output in some
84 other circumstances as well. For example, if the TERM environment
85 variable is not set or set to dumb, then ripgrep will not use
86 colors.
87 The possible values for this flag are:
89 never Colors will never be used.
91 auto The default. ripgrep tries to be smart.
92 always Colors will always be used regardless of where output is sent.
93 ansi Like 'always', but emits ANSI escapes (even in a Windows console).
94 When the --vimgrep flag is given to ripgrep, then the default value
96 for the --color flag changes to never.
97 --colors COLOR_SPEC ...
99 This flag specifies color settings for use in the output. This flag
100 may be provided multiple times. Settings are applied iteratively.
101 Colors are limited to one of eight choices: red, blue, green, cyan,
102 magenta, yellow, white and black. Styles are limited to nobold,
103 bold, nointense, intense, nounderline or underline.
104 The format of the flag is {type}:{attribute}:{value}. {type}
106 should be one of path, line, column or match. {attribute} can be
107 fg, bg or style. {value} is either a color (for fg and bg) or a
108 text style. A special format, {type}:none, will clear all color
109 settings for {type}.
110 For example, the following command will change the match color to
112 magenta and the background color for line numbers to yellow:
113 rg --colors 'match:fg:magenta' --colors 'line:bg:yellow' foo.
115 Extended colors can be used for {value} when the terminal supports
117 ANSI color sequences. These are specified as either x (256-color)
118 or x,x,x (24-bit truecolor) where x is a number between 0 and 255
119 inclusive. x may be given as a normal decimal number or a
120 hexadecimal number, which is prefixed by 0x.
121 For example, the following command will change the match background
123 color to that represented by the rgb value (0,128,255):
124 rg --colors 'match:bg:0,128,255'
126 or, equivalently,
128 rg --colors 'match:bg:0x0,0x80,0xFF'
130 Note that the the intense and nointense style flags will have no
132 effect when used alongside these extended color codes.
133 --column
135 Show column numbers (1-based). This only shows the column numbers
136 for the first match on each line. This does not try to account for
137 Unicode. One byte is equal to one column. This implies
138 --line-number.
139 This flag can be disabled with --no-column.
141 -C, --context NUM
143 Show NUM lines before and after each match. This is equivalent to
144 providing both the -B/--before-context and -A/--after-context flags
145 with the same value.
146 This overrides both the -B/--before-context and -A/--after-context
148 flags.
149 --context-separator SEPARATOR
151 The string used to separate non-contiguous context lines in the
152 output. Escape sequences like \x7F or \t may be used. The default
153 value is --.
154 -c, --count
156 This flag suppresses normal output and shows the number of lines
157 that match the given patterns for each file searched. Each file
158 containing a match has its path and count printed on each line.
159 Note that this reports the number of lines that match and not the
160 total number of matches.
161 If only one file is given to ripgrep, then only the count is
163 printed if there is a match. The --with-filename flag can be used
164 to force printing the file path in this case.
165 This overrides the --count-matches flag. Note that when --count is
167 combined with --only-matching, then ripgrep behaves as if
168 --count-matches was given.
169 --count-matches
171 This flag suppresses normal output and shows the number of
172 individual matches of the given patterns for each file searched.
173 Each file containing matches has its path and match count printed
174 on each line. Note that this reports the total number of individual
175 matches and not the number of lines that match.
176 If only one file is given to ripgrep, then only the count is
178 printed if there is a match. The --with-filename flag can be used
179 to force printing the file path in this case.
180 This overrides the --count flag. Note that when --count is combined
182 with --only-matching, then ripgrep behaves as if --count-matches
183 was given.
184 --debug
186 Show debug messages. Please use this when filing a bug report.
187 --dfa-size-limit NUM+SUFFIX?
189 The upper size limit of the regex DFA. The default limit is 10M.
190 This should only be changed on very large regex inputs where the
191 (slower) fallback regex engine may otherwise be used if the limit
192 is reached.
193 The argument accepts the same size suffixes as allowed in with the
195 --max-filesize flag.
196 -E, --encoding ENCODING
198 Specify the text encoding that ripgrep will use on all files
199 searched. The default value is auto, which will cause ripgrep to do
200 a best effort automatic detection of encoding on a per-file basis.
201 Other supported values can be found in the list of labels here:
202 https://encoding.spec.whatwg.org/#concept-encoding-get
203 -f, --file PATTERNFILE ...
205 Search for patterns from the given file, with one pattern per line.
206 When this flag is used multiple times or in combination with the
207 -e/--regexp flag, then all patterns provided are searched. Empty
208 pattern lines will match all input lines, and the newline is not
209 counted as part of the pattern.
210 A line is printed if and only if it matches at least one of the
212 patterns.
213 --files
215 Print each file that would be searched without actually performing
216 the search. This is useful to determine whether a particular file
217 is being search or not.
218 -l, --files-with-matches
220 Only print the paths with at least one match.
221 This overrides --files-without-match.
223 --files-without-match
225 Only print the paths that contain zero matches. This
226 inverts/negates the --files-with-matches flag.
227 This overrides --files-with-matches.
229 -F, --fixed-strings
231 Treat the pattern as a literal string instead of a regular
232 expression. When this flag is used, special regular expression meta
233 characters such as .(){}*+ do not need to be escaped.
234 This flag can be disabled with --no-fixed-strings.
236 -L, --follow
238 When this flag is enabled, ripgrep will follow symbolic links while
239 traversing directories. This is disabled by default. Note that
240 ripgrep will check for symbolic link loops and report errors if it
241 finds one.
242 This flag can be disabled with --no-follow.
244 -g, --glob GLOB ...
246 Include or exclude files and directories for searching that match
247 the given glob. This always overrides any other ignore logic.
248 Multiple glob flags may be used. Globbing rules match .gitignore
249 globs. Precede a glob with a ! to exclude it.
250 --heading
252 This flag prints the file path above clusters of matches from each
253 file instead of printing the file path as a prefix for each matched
254 line. This is the default mode when printing to a terminal.
255 This overrides the --no-heading flag.
257 --hidden
259 Search hidden files and directories. By default, hidden files and
260 directories are skipped. Note that if a hidden file or a directory
261 is whitelisted in an ignore file, then it will be searched even if
262 this flag isn’t provided.
263 This flag can be disabled with --no-hidden.
265 --iglob GLOB ...
267 Include or exclude files and directories for searching that match
268 the given glob. This always overrides any other ignore logic.
269 Multiple glob flags may be used. Globbing rules match .gitignore
270 globs. Precede a glob with a ! to exclude it. Globs are matched
271 case insensitively.
272 -i, --ignore-case
274 When this flag is provided, the given patterns will be searched
275 case insensitively. The case insensitivity rules used by ripgrep
276 conform to Unicode’s "simple" case folding rules.
277 This flag overrides -s/--case-sensitive and -S/--smart-case.
279 --ignore-file PATH ...
281 Specifies a path to one or more .gitignore format rules files.
282 These patterns are applied after the patterns found in .gitignore
283 and .ignore are applied and are matched relative to the current
284 working directory. Multiple additional ignore files can be
285 specified by using the --ignore-file flag several times. When
286 specifying multiple ignore files, earlier files have lower
287 precedence than later files.
288 If you are looking for a way to include or exclude files and
290 directories directly on the command line, then used -g instead.
291 -v, --invert-match
293 Invert matching. Show lines that do not match the given patterns.
294 -n, --line-number
296 Show line numbers (1-based). This is enabled by default when
297 searching in a terminal.
298 -x, --line-regexp
300 Only show matches surrounded by line boundaries. This is equivalent
301 to putting ^...$ around all of the search patterns. In other words,
302 this only prints lines where the entire line participates in a
303 match.
304 This overrides the --word-regexp flag.
306 -M, --max-columns NUM
308 Don’t print lines longer than this limit in bytes. Longer lines are
309 omitted, and only the number of matches in that line is printed.
310 When this flag is omitted or is set to 0, then it has no effect.
312 -m, --max-count NUM
314 Limit the number of matching lines per file searched to NUM.
315 --max-depth NUM
317 Limit the depth of directory traversal to NUM levels beyond the
318 paths given. A value of zero only searches the explicitly given
319 paths themselves.
320 For example, rg --max-depth 0 dir/ is a no-op because dir/ will not
322 be descended into. rg --max-depth 1 dir/ will search only the
323 direct children of dir.
324 --max-filesize NUM+SUFFIX?
326 Ignore files larger than NUM in size. This does not apply to
327 directories.
328 The input format accepts suffixes of K, M or G which correspond to
330 kilobytes, megabytes and gigabytes, respectively. If no suffix is
331 provided the input is treated as bytes.
332 Examples: --max-filesize 50K or --max-filesize 80M
334 --mmap
336 Search using memory maps when possible. This is enabled by default
337 when ripgrep thinks it will be faster.
338 Memory map searching doesn’t currently support all options, so if
340 an incompatible option (e.g., --context) is given with --mmap, then
341 memory maps will not be used.
342 Note that ripgrep may abort unexpectedly when --mmap if it searches
344 a file that is simultaneously truncated.
345 This flag overrides --no-mmap.
347 --no-config
349 Never read configuration files. When this flag is present, ripgrep
350 will not respect the RIPGREP_CONFIG_PATH environment variable.
351 If ripgrep ever grows a feature to automatically read configuration
353 files in pre-defined locations, then this flag will also disable
354 that behavior as well.
355 --no-filename
357 Never print the file path with the matched lines. This is the
358 default when ripgrep is explicitly instructed to search one file or
359 stdin.
360 This flag overrides --with-filename.
362 --no-heading
364 Don’t group matches by each file. If --no-heading is provided in
365 addition to the -H/--with-filename flag, then file paths will be
366 printed as a prefix for every matched line. This is the default
367 mode when not printing to a terminal.
368 This overrides the --heading flag.
370 --no-ignore
372 Don’t respect ignore files (.gitignore, .ignore, etc.). This
373 implies --no-ignore-parent and --no-ignore-vcs.
374 This flag can be disabled with the --ignore flag.
376 --no-ignore-global
378 Don’t respect ignore files that come from "global" sources such as
379 git’s core.excludesFile configuration option (which defaults to
380 `$HOME/.config/git/ignore).
381 This flag can be disabled with the --ignore-global flag.
383 --no-ignore-messages
385 Suppresses all error messages related to parsing ignore files such
386 as .ignore or .gitignore.
387 This flag can be disabled with the --ignore-messages flag.
389 --no-ignore-parent
391 Don’t respect ignore files (.gitignore, .ignore, etc.) in parent
392 directories.
393 This flag can be disabled with the --ignore-parent flag.
395 --no-ignore-vcs
397 Don’t respect version control ignore files (.gitignore, etc.). This
398 implies --no-ignore-parent for VCS files. Note that .ignore files
399 will continue to be respected.
400 This flag can be disabled with the --ignore-vcs flag.
402 -N, --no-line-number
404 Suppress line numbers. This is enabled by default when not
405 searching in a terminal.
406 --no-messages
408 Suppress all error messages related to opening and reading files.
409 Error messages related to the syntax of the pattern given are still
410 shown.
411 This flag can be disabled with the --messages flag.
413 --no-mmap
415 Never use memory maps, even when they might be faster.
416 This flag overrides --mmap.
418 -0, --null
420 Whenever a file path is printed, follow it with a NUL byte. This
421 includes printing file paths before matches, and when printing a
422 list of matching files such as with --count, --files-with-matches
423 and --files. This option is useful for use with xargs.
424 -o, --only-matching
426 Print only the matched (non-empty) parts of a matching line, with
427 each such part on a separate output line.
428 --passthru
430 Print both matching and non-matching lines.
431 Another way to achieve a similar effect is by modifying your
433 pattern to match the empty string. For example, if you are
434 searching using rg foo then using rg "^|foo" instead will emit
435 every line in every file searched, but only occurrences of foo will
436 be highlighted. This flag enables the same behavior without needing
437 to modify the pattern.
438 This flag conflicts with the --only-matching and --replace flags.
440 --path-separator SEPARATOR
442 Set the path separator to use when printing file paths. This
443 defaults to your platform’s path separator, which is / on Unix and
444 \ on Windows. This flag is intended for overriding the default when
445 the environment demands it (e.g., cygwin). A path separator is
446 limited to a single byte.
447 --pre COMMAND
449 For each input FILE, search the standard output of COMMAND FILE
450 rather than the contents of FILE. This option expects the COMMAND
451 program to either be an absolute path or to be available in your
452 PATH. Either an empty string COMMAND or the --no-pre flag will
453 disable this behavior.
454 WARNING: When this flag is set, ripgrep will unconditionally spawn a
456 process for every file that is searched. Therefore, this can incur an
457 unnecessarily large performance penalty if you don't otherwise need the
458 flexibility offered by this flag.
459 A preprocessor is not run when ripgrep is searching stdin.
461 When searching over sets of files that may require one of several
463 decoders as preprocessors, COMMAND should be a wrapper program or
464 script which first classifies FILE based on magic numbers/content
465 or based on the FILE name and then dispatches to an appropriate
466 preprocessor. Each COMMAND also has its standard input connected to
467 FILE for convenience.
468 For example, a shell script for COMMAND might look like:
470 case "$1" in
472 *.pdf)
473 exec pdftotext "$1" -
474 ;;
475 *)
476 case $(file "$1") in
477 *Zstandard*)
478 exec pzstd -cdq
479 ;;
480 *)
481 exec cat
482 ;;
483 esac
484 ;;
485 esac
486 The above script uses pdftotext to convert a PDF file to plain
488 text. For all other files, the script uses the file utility to
489 sniff the type of the file based on its contents. If it is a
490 compressed file in the Zstandard format, then pzstd is used to
491 decompress the contents to stdout.
492 This overrides the -z/--search-zip flag.
494 -p, --pretty
496 This is a convenience alias for --color always --heading
497 --line-number. This flag is useful when you still want pretty
498 output even if you’re piping ripgrep to another program or file.
499 For example: rg -p foo | less -R.
500 -q, --quiet
502 Do not print anything to stdout. If a match is found in a file,
503 then ripgrep will stop searching. This is useful when ripgrep is
504 used only for its exit code (which will be an error if no matches
505 are found).
506 When --files is used, then ripgrep will stop finding files after
508 finding the first file that matches all ignore rules.
509 --regex-size-limit NUM+SUFFIX?
511 The upper size limit of the compiled regex. The default limit is
512 10M.
513 The argument accepts the same size suffixes as allowed in the
515 --max-filesize flag.
516 -e, --regexp PATTERN ...
518 A pattern to search for. This option can be provided multiple
519 times, where all patterns given are searched. Lines matching at
520 least one of the provided patterns are printed. This flag can also
521 be used when searching for patterns that start with a dash.
522 For example, to search for the literal -foo, you can use this flag:
524 rg -e -foo
526 You can also use the special -- delimiter to indicate that no more
528 flags will be provided. Namely, the following is equivalent to the
529 above:
530 rg -- -foo
532 -r, --replace REPLACEMENT_TEXT
534 Replace every match with the text given when printing results.
535 Neither this flag nor any other ripgrep flag will modify your
536 files.
537 Capture group indices (e.g., $5) and names (e.g., $foo) are
539 supported in the replacement string.
540 Note that the replacement by default replaces each match, and NOT
542 the entire line. To replace the entire line, you should match the
543 entire line.
544 This flag can be used with the -o/--only-matching flag.
546 -z, --search-zip
548 Search in compressed files. Currently gz, bz2, xz, lzma and lz4
549 files are supported. This option expects the decompression binaries
550 to be available in your PATH.
551 This flag can be disabled with --no-search-zip.
553 -S, --smart-case
555 Searches case insensitively if the pattern is all lowercase. Search
556 case sensitively otherwise.
557 This overrides the -s/--case-sensitive and -i/--ignore-case flags.
559 --sort-files
561 Sort results by file path. Note that this currently disables all
562 parallelism and runs search in a single thread.
563 This flag can be disabled with --no-sort-files.
565 --stats
567 Print aggregate statistics about this ripgrep search. When this
568 flag is present, ripgrep will print the following stats to stdout
569 at the end of the search: number of matched lines, number of files
570 with matches, number of files searched, and the time taken for the
571 entire search to complete.
572 This set of aggregate statistics may expand over time.
574 Note that this flag has no effect if --files, --files-with-matches
576 or --files-without-match is passed.
577 -a, --text
579 Search binary files as if they were text. When this flag is
580 present, ripgrep’s binary file detection is disabled. This means
581 that when a binary file is searched, its contents may be printed if
582 there is a match. This may cause escape codes to be printed that
583 alter the behavior of your terminal.
584 When binary file detection is enabled it is imperfect. In general,
586 it uses a simple heuristic. If a NUL byte is seen during search,
587 then the file is considered binary and search stops (unless this
588 flag is present).
589 Note that when the -u/--unrestricted flag is provided for a third
591 time, then this flag is automatically enabled.
592 This flag can be disabled with --no-text.
594 -j, --threads NUM
596 The approximate number of threads to use. A value of 0 (which is
597 the default) causes ripgrep to choose the thread count using
598 heuristics.
599 -t, --type TYPE ...
601 Only search files matching TYPE. Multiple type flags may be
602 provided. Use the --type-list flag to list all available types.
603 --type-add TYPE_SPEC ...
605 Add a new glob for a particular file type. Only one glob can be
606 added at a time. Multiple --type-add flags can be provided. Unless
607 --type-clear is used, globs are added to any existing globs defined
608 inside of ripgrep.
609 Note that this MUST be passed to every invocation of ripgrep. Type
611 settings are NOT persisted.
612 Example:
614 rg --type-add 'foo:*.foo' -tfoo PATTERN.
616 --type-add can also be used to include rules from other types with
618 the special include directive. The include directive permits
619 specifying one or more other type names (separated by a comma) that
620 have been defined and its rules will automatically be imported into
621 the type specified. For example, to create a type called src that
622 matches C++, Python and Markdown files, one can use:
623 --type-add 'src:include:cpp,py,md'
625 Additional glob rules can still be added to the src type by using
627 the --type-add flag again:
628 --type-add 'src:include:cpp,py,md' --type-add 'src:*.foo'
630 Note that type names must consist only of Unicode letters or
632 numbers. Punctuation characters are not allowed.
633 --type-clear TYPE ...
635 Clear the file type globs previously defined for TYPE. This only
636 clears the default type definitions that are found inside of
637 ripgrep.
638 Note that this MUST be passed to every invocation of ripgrep. Type
640 settings are NOT persisted.
641 --type-list
643 Show all supported file types and their corresponding globs.
644 -T, --type-not TYPE ...
646 Do not search files matching TYPE. Multiple type-not flags may be
647 provided. Use the --type-list flag to list all available types.
648 -u, --unrestricted ...
650 Reduce the level of "smart" searching. A single -u won’t respect
651 .gitignore (etc.) files. Two -u flags will additionally search
652 hidden files and directories. Three -u flags will additionally
653 search binary files.
654 -uu is roughly equivalent to grep -r and -uuu is roughly equivalent
656 to grep -a -r.
657 --vimgrep
659 Show results with every match on its own line, including line
660 numbers and column numbers. With this option, a line with more than
661 one match will be printed more than once.
662 -H, --with-filename
664 Display the file path for matches. This is the default when more
665 than one file is searched. If --heading is enabled (the default
666 when printing to a terminal), the file path will be shown above
667 clusters of matches from each file; otherwise, the file name will
668 be shown as a prefix for each matched line.
669 This flag overrides --no-filename.
671 -w, --word-regexp
673 Only show matches surrounded by word boundaries. This is roughly
674 equivalent to putting \b before and after all of the search
675 patterns.
676 This overrides the --line-regexp flag.
678
680 If ripgrep finds a match, then the exit status of the program is 0. If
681 no match could be found, then the exit status is non-zero.
682
684 ripgrep supports reading configuration files that change ripgrep’s
685 default behavior. The format of the configuration file is an "rc" style
686 and is very simple. It is defined by two rules:
687 1. Every line is a shell argument, after trimming ASCII whitespace.
689 2. Lines starting with # (optionally preceded by any amount of ASCII
691 whitespace) are ignored.
692 ripgrep will look for a single configuration file if and only if the
694 RIPGREP_CONFIG_PATH environment variable is set and is non-empty.
695 ripgrep will parse shell arguments from this file on startup and will
696 behave as if the arguments in this file were prepended to any explicit
697 arguments given to ripgrep on the command line.
698 For example, if your ripgreprc file contained a single line:
700 --smart-case
702 then the following command
704 RIPGREP_CONFIG_PATH=wherever/.ripgreprc rg foo
706 would behave identically to the following command
708 rg --smart-case foo
710 another example is adding types
712 --type-add
714 web:*.{html,css,js}*
715 would behave identically to the following command
717 rg --type-add 'web:*.{html,css,js}*' foo
719 same with using globs
721 --glob=!git/*
723 or
725 --glob
727 !git/*
728 would behave identically to the following command
730 rg --glob '!git/*' foo
732 ripgrep also provides a flag, --no-config, that when present will
734 suppress any and all support for configuration. This includes any
735 future support for auto-loading configuration files from pre-determined
736 paths.
737 Conflicts between configuration files and explicit arguments are
739 handled exactly like conflicts in the same command line invocation.
740 That is, this command:
741 RIPGREP_CONFIG_PATH=wherever/.ripgreprc rg foo --case-sensitive
743 is exactly equivalent to
745 rg --smart-case foo --case-sensitive
747 in which case, the --case-sensitive flag would override the
749 --smart-case flag.
750
752 Shell completion files are included in the release tarball for Bash,
753 Fish, Zsh and PowerShell.
754 For bash, move rg.bash to $XDG_CONFIG_HOME/bash_completion or
756 /etc/bash_completion.d/.
757 For fish, move rg.fish to $HOME/.config/fish/completions.
759 For zsh, move _rg to one of your $fpath directories.
761
763 ripgrep may abort unexpectedly when using default settings if it
764 searches a file that is simultaneously truncated. This behavior can be
765 avoided by passing the --no-mmap flag which will forcefully disable the
766 use of memory maps in all cases.
767
769 0.9.0 -SIMD -AVX
770
772 https://github.com/BurntSushi/ripgrep
773 Please report bugs and feature requests in the issue tracker.
775
777 Andrew Gallant <jamslam@gmail.com>
778 08/04/2018 RG(1)