Overview
rg (ripgrep) searches the text in all the files under the current folder, or the places you name, and prints the lines that match. It is built for searching source code: it is fast, it skips files that .gitignore lists, hidden files and binary files, and it uses regular expressions by default. It prints the file name and line number when it searches many files.
Background
rg is an open-source tool whose guide is in its repository. It is a separate program from grep, with different defaults, and is installed on request, not by default on most systems. The tool tested here is ripgrep 15.2.0.
Examples
Search one file; the matching line is printed:
printf 'one\ntwo\nthree\n' > f.txt && rg two f.txt
Add the line number with -n:
printf 'one\ntwo\nthree\n' > f.txt && rg -n two f.txt
Count the lines that match, with -c:
printf 'one\ntwo\nthree\n' > f.txt && rg -c o f.txt
Ignore case with -i:
printf 'one\ntwo\nthree\n' > f.txt && rg -i TWO f.txt
Search several places; each match starts with its file name:
mkdir logs && printf 'two\n' > logs/a.log && printf 'one\ntwo\n' > f.txt && rg two logs f.txt | sort
List the files that contain a match, with -l:
mkdir logs && printf 'two\n' > logs/a.log && printf 'one\n' > f.txt && rg -l two .
Match whole words only with -w; the status is 1 when nothing matches:
printf 'one\ntwo\n' > f.txt && { rg -w tw f.txt || echo none; }
List the files rg would search, with --files, and restrict by name with -g:
mkdir src && printf 'x\n' > src/m.rs && printf 'y\n' > f.txt && rg -g '*.rs' --files
Options
-n
Show line numbers.
-i
Ignore case.
-w
Match whole words only.
-l
Print only the names of files with a match.
-c
Print the number of matching lines in each file.
-g
Include or exclude files by a glob, as in -g '*.rs'.
-F
Treat the pattern as a fixed string, not a regular expression.
--files
List the files that would be searched.
Common mistakes
rg skips files that are ignored by .gitignore, hidden files and binary files, so a file you expect may not be searched; add --no-ignore, --hidden or -uuu to include them. The pattern is a regular expression, so ., ( and [ have meanings; use -F for plain text. When its output is not a terminal, rg leaves out the file name for a single file and the heading layout, which can surprise a script. The order of results from several files can vary between runs, because it searches in parallel; add --sort path for a stable order.
Portability
rg is a different program from grep, so options such as -r (which means replace in rg) do not mean what they do in grep. The examples were executed on ripgrep 15.2.0. The Common examples were executed on ripgrep 15.2.0 (see the development guide for the exact check).
About upstream rg
This is the upstream ripgrep tool, installed as rg. It is one program on every system; the version is what differs.
References
Original explanations, with upstream documentation for further reading. FreeBSD references are comparison material, not a claim of Apple version equivalence.