Skip to content
glep

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
  1. First principles
  2. Standard output
  3. With context
  4. Headings (–heading)
  5. Files with matches (-l)
  6. Count (-c)
  7. Vim-style (–vimgrep)
  8. Replacements (-r)
  9. File listing (–files)
  10. Statistics (–stats)
  11. JSON Lines (–json)
  12. Line terminators
  13. Colors and hyperlinks
  14. stderr
  15. Known differences from ripgrep

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 (searches and bytes searched), which are lower than ripgrep’s.
  • Results come out in path order, the order rg --sort path uses, 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.rs prints 1:pub fn parse_intent(s: &str) {}. -H puts it back; -I always leaves it out.
  • On a terminal, output is colored by default. Piped or redirected output has no color. Use --color never or --color always to 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_lines and bytes_printed come from the same printer ripgrep uses and match ripgrep for the same query.
  • searches, searches_with_match and bytes_searched count only the files glep actually opened. The index removes most files before they are opened, so these are lower than ripgrep’s.
  • elapsed_total and stats.elapsed are both the wall time of the whole search.
  • With a path operand like ./src, bytes_printed can differ from ripgrep’s, because ripgrep prints ./src/x and glep prints src/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.

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 ./src prints src/x where rg prints ./src/x (likewise for .. operands). On Windows, a typed src/main.rs prints as src\main.rs, where rg keeps the spelling typed.
  • --files takes a glob in the pattern slot, where rg takes paths.
  • A positive -g or --iglob glob does not bring back files that ignore rules exclude. Add --no-ignore.
  • .git and .glep are never listed or searched, even under -uu.
  • .gitignore rules apply outside a git repository too (like rg --no-require-git); pass --require-git for rg’s default.
  • --max-filesize caps 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 searches and bytes searched counters 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.