ripgrep

# ripgrep Text Search Use ripgrep (rg) when the user needs fast text or regex content search from the command line. The useful outcome is a copy-pasteable command plus a clear statement of what it matches, what it skips, and why. ## Triage Start with the smallest tool that can answer the question. - For trivial in-conversation lookups, use the harness's built-in ripgrep-backed search tool instead of shelling out to rg. - Use rg for exact names, strings, regex content searches, file lists, counts, and pipeline-friendly output. - Use ast-grep for syntax shape: descendants, ancestors, call forms, decorators, missing constructs, or nested contexts. - Use language tooling for semantic facts such as type resolution, references, imports, or rename safety. Before trusting local behavior, verify the binary: `rg --version` should print a ripgrep version plus enabled features such as `+PCRE2`. If it does not, run `which rg` — an alias or another tool named rg may shadow it. ## Defaults Model rg is a filter wrapped around a search. By default it: - searches the current directory recursively (`rg foo` equals `rg foo ./`), - respects `.gitignore`, `.ignore`, and `.rgignore` rules (precedence: `.rgignore` over `.ignore` over `.gitignore`), - skips hidden files and directories, - skips binary files (any file containing a NUL byte), - does not follow symlinks (opt in with `-L/--follow`). Escalation ladder: `-u` disables ignore-file handling, `-uu` also searches hidden files, `-uuu` also searches binary files — roughly `grep -r` with no smart filtering. Individual toggles: `--no-ignore`, `--hidden`, `-a/--text`. When rg "can't find" a file, diagnose before changing the pattern: 1. `rg --files | rg name` — is the file in the searched set at all? 2. `rg pattern --debug` — which ignore rule or config excluded it? A `*` rule in the global gitignore is the most common cause. 3. `rg pattern -uuu` — does the match appear with all filtering off? ## Workflow 1. Compose the simplest command that could work; prefer `-F` for literals. 2. Dry-run the file set with `--files` plus your `-g`/`-t` filters when the search scope matters. 3. Run on a narrow path first (`rg pattern src/module`), then widen. 4. For complex or shell-hostile patterns, write one pattern per line to a file and use `-f patterns.txt` (patterns are ORed). On Windows this is the preferred escape hatch from quoting problems; save the file as UTF-8 without BOM. 5. Report the command, what it matches, and what it may miss. ## Filtering - Paths: `rg foo src tests README.md`. Explicitly named files bypass ignore rules and hidden-file skipping. - Globs: `-g '*.toml'` includes; `-g '!*.toml'` excludes — on the command line `!` negates, the reverse of gitignore whitelist semantics. Later globs override earlier ones. Quote globs so the shell does not expand them. `--iglob` is the case-insensitive form. Glob patterns use `/` separators on every platform, including Windows. - Types: `-t py` includes a type, `-T js` excludes one; `--type-list` shows the globs behind each type. `--type-add 'web:*.{html,css,js}'` defines a type for the current invocation only; persist it in the config file. - Limits: `--max-filesize 1M` skips large files; `--max-depth NUM` caps traversal depth. ## Regex Engines - The default engine (Rust regex) guarantees worst-case linear time but has no lookaround and no backreferences — such patterns fail at compile time with a parse error. - `-P/--pcre2` switches to PCRE2, which supports lookaround and backrefs but can backtrack catastrophically. It requires a build with `+PCRE2` in `rg --version`; otherwise rg reports PCRE2 is not available. - `--engine auto` uses the default engine and falls back to PCRE2 only when the pattern needs it. - `-F` treats the pattern as a literal string; `-w` requires word boundaries; `-x` requires the pattern to match the whole line; `-e PAT` or `--` safely pass patterns that start with `-`. - Case: `-i` insensitive, `-s` sensitive, `-S` smart-case (insensitive unless the pattern contains an uppercase letter). - Multiline: `-U` lets a match span lines; add `--multiline-dotall` when `.` must match newlines. A bare `\n` in a pattern errors without `-U`. - Unicode is on by default; disable it for a sub-pattern with `(?-u:...)`. ## Output & Pipelines - Context: `-A NUM`, `-B NUM`, `-C NUM`. - `-o` prints only the matched text; `-r REPL` rewrites the match in the output, supporting `$1`, `$0`, and named groups. See Hard Constraints. - Machine-readable: `--json` emits JSON Lines with byte offsets and submatches; `--vimgrep` prints `file:line:column:text` with one match per line; `--column` adds column numbers. - Lists and counts: `-l` prints files with matches, `--files-without-match` the inverse; `-c` counts matched lines per file — use `--count-matches` for total matches; `--stats` appends aggregate totals. - Piping changes defaults: at a TTY rg shows colors, line numbers, and headings; when piped it drops them. Force with `--color=always`, `-n`, or `--heading`. - Output order is non-deterministic because rg searches in parallel. `--sort path` gives stable order but disables parallelism; `-j1` is a cheaper determinism knob. ## Windows Quoting - cmd.exe: only double quotes delimit strings; single quotes are literal characters, so `rg '^foo'` searches for a pattern containing quotes. Use `rg "^foo"`. Escape a literal `%` as `%%`. - PowerShell: prefer single quotes for regexes; `$` inside double quotes triggers variable expansion, so `rg "foo$"` breaks while `rg 'foo$'` works. - Git Bash / MSYS2: POSIX single quotes work, but a pattern or argument starting with `/` may be silently rewritten by path translation. Fix with a doubled slash (`rg //foo`) or `MSYS_NO_PATHCONV=1 rg /foo`. - Escape hatch for any shell: put the pattern in a file and use `-f file`, saved as UTF-8 without BOM. - UTF-16 files (common on Windows) are transcoded automatically via BOM sniffing; force an encoding with `-E utf-16le` when there is no BOM. ## Hard Constraints 1. `-r/--replace` rewrites rg's OUTPUT only. ripgrep never modifies files and has no in-place edit flag. For real edits use the sanctioned pipeline `rg foo -l -0 | xargs -0 sed -i 's/foo/bar/g'` (BSD/macOS sed needs `-i ''`), or a purpose-built tool such as fastmod. 2. Zero matches usually means default filtering, not a bad regex. Walk the Defaults Model diagnosis (`--files`, `--debug`, `-uuu`) before rewriting the pattern. 3. Lookaround or backreferences on the default engine fail at compile time. Route to `-P/--pcre2` after checking `rg --version` for `+PCRE2`, or restate the pattern without those features. ## Debugging Checklist Zero matches: 1. Verify the binary: `rg --version` and `which rg`. 2. `rg --files | rg name` — is the target file searched at all? 3. Add `--debug` — which ignore rule or config file excluded it? 4. Try `-uuu` — do matches appear with all filtering disabled? 5. Simplify: drop to a `-F` literal, then add regex features back. 6. On Windows, suspect shell quoting; move the pattern to `-f file`. 7. For non-UTF-8 files without a BOM, set `-E` explicitly. Too many matches: 1. Scope with a path argument, `-g`, or `-t`. 2. Add `-w` for word boundaries or `-x` for whole-line matches. 3. Use `-s` when smart-case or `-i` over-matches. 4. Cap with `-m NUM` matching lines per file. ## Output Contract When answering an rg task, include: 1. `Command`: copy-pasteable, naming the target shell when quoting matters. 2. `Why these flags`: one line per non-obvious flag. 3. `What it matches / misses`: the filtering and engine boundaries in effect. 4. `Caveats`: ignore-file surprises, output ordering, encoding, or version gates (this skill documents ripgrep 15.1.0 behavior). ## Reference Load `references/cli_reference.md` when the task needs detailed flag semantics, the engine comparison, config-file format, preprocessors and compressed search, encodings, or JSON output details.