rg — Output Modes

Output Control

Files only (-l / --files-with-matches) — list matching files

rg -l 'include::partial' ~/atelier/_bibliotheca/domus-captures/docs/modules/ROOT/pages/codex/

Prints only file paths containing at least one match. Stops searching each file after the first hit — fast. Pipe to xargs for batch operations: rg -l 'old' | xargs sed -i 's/old/new/g'.

Files without matches (--files-without-match) — the anti-audit

rg --files-without-match ':description:' ~/atelier/_bibliotheca/domus-captures/docs/modules/ROOT/pages/codex/rg/

Lists files that do NOT contain the pattern. The inverse of -l. Here: find pages missing the :description: header attribute.

JSON output (--json) piped to jq — structured results

rg --json 'TODO' ~/atelier/_bibliotheca/domus-captures/docs/modules/ROOT/ | jq -r 'select(.type == "match") | "\(.data.path.text):\(.data.line_number):\(.data.lines.text)"' | head -5

--json emits one JSON object per line (JSON Lines format). Three types: begin (file start), match (each hit), end (file summary). Pipe to jq for programmatic extraction.

Vimgrep format (--vimgrep) — editor integration

rg --vimgrep 'FIXME' ~/atelier/_bibliotheca/domus-captures/docs/modules/ROOT/partials/ | head -5

Expected format:

/path/to/file.adoc:12:5:// FIXME: update this section

Outputs file:line:column:match — the format vim -q expects for quickfix lists. Works with any editor that supports errorformat/quickfix.

Context lines (-A/-B/-C) — surrounding context

rg -B 2 -A 2 'source,bash' ~/atelier/_bibliotheca/domus-captures/docs/modules/ROOT/partials/codex/rg/basics.adoc | head -20

-B N = N lines before, -A N = N lines after, -C N = N lines both. Matches separated by -- delimiters. Same semantics as grep -A/-B/-C.

Only matching text (-o) — extract the match, discard the line

rg -o '\{[a-z-]+\}' ~/atelier/_bibliotheca/domus-captures/docs/modules/ROOT/partials/codex/rg/basics.adoc

Prints only the matched portion, not the full line. Useful for extracting patterns: attribute references, IPs, URLs, UUIDs.

Replace matches (-r) with capture group — transform output

rg 'include::partial\$codex/rg/(\S+)\.adoc\[\]' -r '$1' ~/atelier/_bibliotheca/domus-captures/docs/modules/ROOT/pages/codex/rg/ -o

-r replaces the matched text in output. $1 references the first capture group. This does NOT modify files — it transforms the displayed output. Combine with -o to print only the replacement.

Column number (--column) — pinpoint match position

rg --column 'include::' ~/atelier/_bibliotheca/domus-captures/docs/modules/ROOT/pages/codex/rg/basics/searching.adoc

Adds the byte offset (column) of the first match on each line. Useful for editor integration and precise position reporting.

Stats summary (--stats) — aggregate match statistics

rg --stats 'include::' ~/atelier/_bibliotheca/domus-captures/docs/modules/ROOT/pages/ 2>&1 | tail -8

Expected output (partial):

42 matches
28 matched lines
15 files contained matches
187 files searched

--stats prints a summary to stderr after results. Pipe stderr with 2>&1 to capture it.

Sorted output (--sort path) — deterministic ordering

rg --sort path -l 'xref:' ~/atelier/_bibliotheca/domus-captures/docs/modules/ROOT/pages/codex/rg/

By default rg output order is non-deterministic (parallel search). --sort path sorts by file path. Also available: --sort modified, --sort accessed, --sort created. --sortr for reverse.