Debugging

Tools and techniques for figuring out what ripgrep is actually doing.

--debug and --trace

ripgrep has two log levels:

• --debug prints information about which files are being searched and skipped, and why. Use this when files you expect to be searched aren't, or vice versa.
• --trace is much more verbose: every matcher, searcher, and walker decision. Use this when you suspect a regex compilation or line-stepping bug.

Both flags route through log and are wired up in crates/core/logger.rs. The output goes to stderr.

rg --debug 'pattern' . 2>&1 | head -50

Common debug findings:

• "ignored by .gitignore" — the gitignore precedence stack matched. Check global gitignores (git config core.excludesFile) and parent-directory .gitignores.
• "ignored by hidden" — --hidden would un-ignore it.
• "ignored by file size" — --max-filesize is set somewhere (config file?).

RIPGREP_CONFIG_PATH

If ripgrep is behaving differently than expected, check whether a config file is being applied:

echo $RIPGREP_CONFIG_PATH
rg --no-config 'pattern' .

Configuration loading happens in crates/core/flags/config.rs. The config file is parsed first, then CLI flags override.

--no-ignore ladder

ripgrep has a layered ignore system. To narrow down which layer is filtering a file, peel them off one at a time:

rg --no-ignore-vcs        # ignore .gitignore but keep .ignore/.rgignore
rg --no-ignore            # ignore all per-directory ignore files
rg --no-ignore --hidden   # plus include hidden files
rg -uuu                   # equivalent to all four `--no-` flags above

The implementations live in crates/ignore/src/walk.rs (WalkBuilder config methods).

Regex behaviour

If a regex isn't matching what you expect:

1. Test it against the same haystack with rg --pcre2 PATTERN to see if PCRE2 disagrees. A discrepancy points at literal extraction in crates/regex/src/literal.rs.
2. Use --debug to see whether the regex was simplified into a literal search.
3. The regex is compiled by Rust's regex crate. Its syntax docs are authoritative.

Encoding bugs

If a file's matches look mangled:

• --encoding utf-16le (or whichever encoding the file actually uses) forces transcoding via encoding_rs.
• --no-encoding reverts to the default heuristic (UTF-8 with a UTF-16 BOM detector).
• The detection logic is in crates/searcher/src/searcher/mod.rs.

mmap vs. buffered

--mmap and --no-mmap toggle the search strategy. By default ripgrep uses mmap for files when a single explicit path is provided. The decision is in crates/searcher/src/searcher/mmap.rs. Behavioural differences:

• mmap is faster for single large files but flakier on networked filesystems.
• Buffered mode allocates a LineBuffer (see crates/searcher/src/line_buffer.rs) sized via --buffer-capacity.

Reproducing in tests

If you have a reliable repro, port it into tests/regression.rs using the rgtest! macro. The convention is to name the test with the issue number, e.g., regression_3194. See Testing.

When all else fails

• Check CHANGELOG.md — most behaviours are documented there with a referenced issue number.
• git log -- crates/... for the file involved often surfaces the original PR with rationale.
• The maintainer has historically been responsive to detailed bug reports on GitHub.