Quickstart

A few minutes from zero to seeing recovered matches. Every command is runnable verbatim from a scratch directory.

Build a repo that hides matches

QS=$(mktemp -d) && cd "$QS"
git init -q
printf 'timeout = 30\n'  > config.py        # tracked
printf 'timeout = 5\n'   > .env.local        # hidden dotfile
mkdir cache && printf 'timeout = 999\n' > cache/build.py
printf 'cache/\n'        > .gitignore        # gitignore the cache
git add -A && git commit -qm 'initial'

Three files contain timeout: one tracked, one hidden, one gitignored.

What a naive search sees

rg timeout .
config.py:1:timeout = 30

One of three, exit 0. The search looks complete. It is not.

What rf sees

rf content timeout .
content 'timeout' in .: 3 file(s), 1 by default, 2 hidden by filters
  hidden       .env.local
  vcs_ignore   cache/build.py
  default      config.py
  ! IGNORE_VCS: 1 match(es) hidden by default; add -u (ignore .gitignore/.ignore rules)
  ! HIDDEN_SKIPPED: 1 match(es) hidden by default; add -uu (also search hidden/dotfiles)
  $ rg -u 'timeout' .
  $ rg -uu 'timeout' .

All three matches. Each recovered file is attributed to the filter that hid it, and each miss carries a paste-ready rg command to confirm it independently.

The same thing as JSON

Piped or with --json, rf prints one structured envelope instead of the summary:

rf content timeout . --json
{
  "ok": true,
  "data": [
    { "file": ".env.local",     "surfaced_by": "hidden" },
    { "file": "cache/build.py", "surfaced_by": "vcs_ignore" },
    { "file": "config.py",      "surfaced_by": "default" }
  ],
  "meta": { "matched_files": 3, "default_matched_files": 1, "hidden_by_filters": 2 }
}

The warnings array (elided here) holds one entry per miss. See the JSON contract for every key.

An empty result is not an error

Search for a term that is not there:

rf content nonexistent-token . ; echo "exit $?"
exit 0

rf returns exit 0 with data: []. A plain rg would exit 1 and conflate “no match” with “the search failed.” See Exit codes.

Clean up

cd / && rm -rf "$QS"

Next steps