ripgrep
Prefer rg over grep for text search, and prefer rg --files over find | grep when the real task is path discovery.
Verified locally against ripgrep 15.1.0 on April 10, 2026. The skill is repo-agnostic, but the examples assume a Unix-like shell and an rg binary in PATH.
Decision Tree
What kind of search do you need?
- Search file contents for text, symbols, regexes, or literals
- Start with rg - Read references/commands.md
- Find filenames or paths without reading file contents
- Start with rg --files [path] - Then filter that list with a second rg if needed - Read references/patterns.md
- Search only specific languages, globs, hidden files, ignored files, compressed data, or multiline blocks
- Read references/commands.md - If results seem wrong or missing, read references/gotchas.md
- Make ripgrep behavior repeatable with config files, aliases, or custom file types
- Read references/configuration.md
- Feed results into automation, scripts, editors, or other tools
- Prefer --json, -0, -l, --count-matches, or --sort path as appropriate - Read references/patterns.md
- The user wants full-file reading, structured JSON queries, or filesystem metadata
- Do not force rg into a role it is bad at - Read the file directly, or use jq, find, or fd
Default Operating Rules
- Use
rgfirst for text search. Only fall back togrepwhenrgis unavailable or exact POSIX grep behavior is the real requirement. - Use
-Ffor user-provided literals unless the user clearly asked for regex semantics. - Narrow the search early with an explicit path plus
-tor-ginstead of searching the entire tree and cleaning up later. - Use
rg --filesfor path discovery, then pipe into anotherrgfor filename filtering instead of composingfind... | grep.... - Escalate ignore overrides gradually: normal search, then
--hidden, then-uor--no-ignore, then-uuor-uuuonly if the missing-result hypothesis justifies it. - Use
--debugwhen results are missing and you need to know what ripgrep skipped. - Use
--jsonor-n --color never --no-headingfor machine consumption. Prefer--sort pathwhen deterministic output matters more than maximum speed.
Quick Reference
| Need | Command | Notes |
|---|---|---|
| Literal text search | rg -n -F 'needle' path/ | Best default for user-provided strings with punctuation |
| Regex search | rg -n 'foo\\s+bar' path/ | Use single quotes so the shell does not interfere |
| Filenames only | rg --files path/ | Respects ignore files by default |
| Filter filenames | `rg --files | rg '(^ |
| Match specific languages | rg -n -t py 'pattern' src/ | -t includes, -T excludes |
| Match specific globs | rg -n -g '*.tsx' 'pattern' src/ | Later globs override earlier ones |
| Search hidden or ignored content | rg --hidden 'pattern' then rg -u 'pattern' | Escalate only as needed |
| Files with matches | rg -l 'pattern' path/ | Use before opening files |
| Count individual matches | rg --count-matches 'pattern' path/ | -c counts matching lines, not matches |
| Machine-readable output | rg --json 'pattern' path/ | Best for tools and scripts |
| Lookaround or backreferences | rg -P '...' path/ | Requires PCRE2 support in the build |
| Multiline blocks | rg -U '(?s)start.*end' file | Multiline is slower and more memory-hungry |
| Diagnose skipped files | rg --debug 'pattern' path/ | Shows ignore and skip reasons |
Reading Guide
| Task | Read |
|---|---|
| Correct command, flag, or output mode | references/commands.md |
| Config files, aliases, custom types, and environment setup | references/configuration.md |
| Agent search workflows, filename discovery, shell pipelines, and deterministic output | references/patterns.md |
| Missing results, quoting issues, multiline surprises, JSON limits, and other traps | references/gotchas.md |
Verified Behaviors
rg --filesrespects ignore rules by default and excluded an ignoredlogs/app.login local probes..rgignoreoverrode.ignore, and--no-ignorerestored access to the same ignored file.--hiddensurfaced hidden content without turning off ignore handling.- The order of
-gflags changed the result set exactly as upstream documents: later globs overrode earlier ones. RIPGREP_CONFIG_PATHsuccessfully loaded--smart-caseand a customwebtype from a config file.--jsonemittedbegin,match,end, andsummarymessages in JSON Lines format.-U '(?s)...'matched across lines, and-Plookaround worked on this machine because the local build includes PCRE2.
Gotchas
rgis not a byte-for-byte drop-in replacement for POSIXgrep; it is the default search tool when speed, recursion, ignore handling, or Unicode-aware regex matter.- Missing results are usually an ignore, hidden-file, glob-order, or quoting problem before they are a ripgrep bug. Run
--debugbefore switching tools. --replacechanges printed output only. It never edits files.--jsonis for search results, not every output mode. It does not combine with--files,-l, or-c.-Pand-Uare powerful but costlier than the default engine and normal line-oriented search. Use them deliberately.
Helper Scripts
scripts/probe_ripgrep.pybuilds a temporary corpus and verifies realrgbehavior such as ignore precedence, JSON output, multiline matching, and PCRE2 support.scripts/validate.pychecks structure, frontmatter, references, required files, and Python syntax.scripts/test_skill.pyruns validation, checks eval coverage, verifies cross-references, and executes the ripgrep probe suite.