glep / Reference
Output formats
The exact shapes of glep's standard, heading, count, file-listing, stats and JSON Lines output, and the few places where they differ from ripgrep.
On this page
Output is glep’s interface: agents and hooks parse it, so its bytes are the contract. This page shows each shape as printed by glep 2.0.0. Release 0.3.1 prints the standard, context, -l, -c, --files and --json shapes the same way and has none of the others.
First principles
- glep prints through
grep-printer, the crate ripgrep 15 prints with, configured the way ripgrep configures it. The format is inherited, not reimplemented, so matching ripgrep is the default rather than a goal to chase. - The index changes which files are opened, never what is printed about them. The only visible traces are the counters that count opened files (
searchesandbytes searched), which are lower than ripgrep’s. - Results come out in path order, the order
rg --sort pathuses, while the search runs on several threads. A printer thread restores the order, so the output is the same on every run.
Standard output
One line per matching line, path:line_number:text:
src/lib.rs:1:pub fn parse_intent(s: &str) {}
src/main.rs:2: parse_intent("hi");
This is byte-compatible with rg -n --no-heading --color=never --sort path. The parity harness in tests/parity.rs checks stdout and the exit code against real ripgrep for about 400 cases, including case-insensitive Unicode, multiline, counts, context, hidden files, binary files and --no-ignore.
- Paths are relative to the directory glep runs in, without a
./prefix. - When the only operand is a single file, the path is left out, as in ripgrep:
glep parse_intent src/lib.rsprints1:pub fn parse_intent(s: &str) {}.-Hputs it back;-Ialways leaves it out. - On a terminal, output is colored by default. Piped or redirected output has no color. Use
--color neveror--color alwaysto choose.
With context
Context lines use - instead of : after the path and line number. A -- line separates groups that are not adjacent, including groups in different files:
src/lib.rs:1:pub fn parse_intent(s: &str) {}
--
src/main.rs-1-fn main() {
src/main.rs:2: parse_intent("hi");
src/main.rs-3-}
--field-match-separator, --field-context-separator and --context-separator change the three separators; --no-context-separator drops the -- line.
Headings (–heading)
Each file’s path on its own line, then its matches, with a blank line between files:
src/lib.rs
1:pub fn parse_intent(s: &str) {}
src/main.rs
2: parse_intent("hi");
-p (--pretty) is --heading plus line numbers and --color always.
Files with matches (-l)
One path per line, each file once:
src/lib.rs
src/main.rs
--files-without-match prints the files that have no match, in the same shape.
Count (-c)
path:count per matching file. Files with no match are omitted unless --include-zero is given:
src/lib.rs:1
src/main.rs:1
-c counts matching lines; --count-matches counts matches, so a line with two matches counts twice.
Vim-style (–vimgrep)
One line per match, path:line:column:text, always with the path:
src/lib.rs:1:8:pub fn parse_intent(s: &str) {}
src/main.rs:2:5: parse_intent("hi");
--column adds the column of the first match to the standard format, and -b adds the byte offset of each line.
Replacements (-r)
-r TEXT replaces each match in the printed line. Capture groups resolve as $1 or ${name}. Files are never changed.
glep -r parse_command parse_intent src
src/lib.rs:1:pub fn parse_command(s: &str) {}
src/main.rs:2: parse_command("hi");
File listing (–files)
One path per line, sorted by path. --sort and --sortr change the order, and -0 ends each path with NUL instead of a newline.
Statistics (–stats)
--stats prints ripgrep’s statistics block after the results:
src/lib.rs:1:pub fn parse_intent(s: &str) {}
src/main.rs:2: parse_intent("hi");
2 matches
2 matched lines
2 files contained matches
2 files searched
83 bytes printed
70 bytes searched
0.000312 seconds spent searching
0.000312 seconds total
files searched and bytes searched count only the files glep opened after index narrowing.
JSON Lines (–json)
--json prints ripgrep’s JSON event stream, one JavaScript Object Notation (JSON) object per line: for each file with a match, a begin event, match and context events, and an end event with per-file stats. The stream ends with one summary event.
{"type":"begin","data":{"path":{"text":"src/lib.rs"}}}
{"type":"match","data":{"path":{"text":"src/lib.rs"},
"lines":{"text":"pub fn parse_intent(s: &str) {}\n"},"line_number":1,"absolute_offset":0,
"submatches":[{"match":{"text":"parse_intent"},"start":7,"end":19}]}}
{"type":"end","data":{"path":{"text":"src/lib.rs"},"binary_offset":null,"stats":{...}}}
{"data":{"elapsed_total":{"secs":0,"nanos":723250,"human":"0.000723s"},
"stats":{"elapsed":{...},"searches":1,"searches_with_match":1,"bytes_searched":32,
"bytes_printed":267,"matched_lines":1,"matches":1}},"type":"summary"}
Each event is one line in real output. The example above is wrapped for width, and {...} marks stats objects shortened here.
The summary event has the same field names and nesting as ripgrep’s. Some values differ by design:
matches,matched_linesandbytes_printedcome from the same printer ripgrep uses and match ripgrep for the same query.searches,searches_with_matchandbytes_searchedcount only the files glep actually opened. The index removes most files before they are opened, so these are lower than ripgrep’s.elapsed_totalandstats.elapsedare both the wall time of the whole search.- With a path operand like
./src,bytes_printedcan differ from ripgrep’s, because ripgrep prints./src/xand glep printssrc/x.
With -r, each submatch also carries its replacement, as in ripgrep 15. When nothing matches, --json prints only the summary event and glep exits 1. With -q, the summary event is still printed.
The output modes -l, --files-without-match, -c, --count-matches and --json are last-wins: glep -l --json prints JSON, and glep --json -l prints paths.
Line terminators
Records and separators end with the searcher’s line terminator, as in ripgrep: a newline by default, CRLF (carriage return and line feed) under --crlf, and NUL under --null-data.
Colors and hyperlinks
With color on, glep uses ripgrep’s default colors. --colors 'path:fg:magenta' and similar specs change them, and highlight: styles the non-matching text of a matching line. --hyperlink-format adds terminal hyperlinks to paths, but only when color is on, as in ripgrep.
stderr
Diagnostics go to stderr, prefixed with glep:: index build progress, rebuild notices, per-file read errors, and errors. With GLEP_TIMING set, stage timings also go to stderr. stdout carries only results.
Known differences from ripgrep
These are the differences the README lists; everything else is meant to be identical.
- Paths under an operand print relative to the current directory:
glep pat ./srcprintssrc/xwhere rg prints./src/x(likewise for..operands). On Windows, a typedsrc/main.rsprints assrc\main.rs, where rg keeps the spelling typed. --filestakes a glob in the pattern slot, where rg takes paths.- A positive
-gor--iglobglob does not bring back files that ignore rules exclude. Add--no-ignore. .gitand.glepare never listed or searched, even under-uu..gitignorerules apply outside a git repository too (likerg --no-require-git); pass--require-gitfor rg’s default.--max-filesizecaps what the index stores (larger files are still searched) instead of skipping files.- glep never reads standard input, so a search with no path argument always searches the tree.
- The
searchesandbytes searchedcounters count only the files glep opened. - Binary files are read as ripgrep 15.0 reads them, in whole 64 KiB buffers with a fresh buffer per file. ripgrep 15.1 and later, and ripgrep’s per-thread buffer reuse, can stop at a different line on some binary files with a NUL past the first 64 KiB.