Worked examples

Each example below shows a task, the command, and why it is shaped that way. The commands use flags from the main branch; see Release 0.3.1 and main if you run the release. Outputs come from a small sample project with src/lib.rs, src/main.rs, tests/t.rs and tests/todo.md.

First principles

A search is cheapest when the index can rule out most files, so each example follows the same order:

1. Put the most specific literal text in the pattern. That is what the index narrows on.
2. Narrow by place with path operands, globs and types. These filter the candidate list without reading files.
3. Reach for flags that need every file (-v, -c --include-zero, --passthru) or every ignored file (--no-ignore) only when the question needs them. They stay correct but cost more.

Find a definition, not every call

glep -w -t rust 'fn parse_intent'

src/lib.rs:1:pub fn parse_intent(s: &str) {}

fn parse_intent is a long literal, so the index narrows hard. -w keeps parse_intent_v2 out, and -t rust limits the search to Rust files.

Leave tests out

glep -g '!tests/**' 'parse_intent'

src/lib.rs:1:pub fn parse_intent(s: &str) {}
src/main.rs:2:    parse_intent("hi");

A ! glob excludes; -g '!tests' prunes the directory too. Several -g flags combine, and the last matching one wins.

Work inside one package

cd src
glep 'parse_intent'

lib.rs:1:pub fn parse_intent(s: &str) {}
main.rs:2:    parse_intent("hi");

glep finds the project’s index in a parent directory, searches only the current directory, and prints paths relative to it. The freshness sweep also covers only this directory, so the query is cheaper.

Run a read-only burst as an agent

glep --ttl 5 'parse_intent'
glep --ttl 5 -l 'Intent'
glep --ttl 5 --files '**/*.rs'

--ttl 5 skips the freshness sweep when the last full sweep ran less than 5 seconds ago, which on large trees removes most of each query’s cost. Drop it after any edit: inside the window, a new or changed file is invisible.

Find files missing a license header

glep --files-without-match -t rust 'SPDX-License-Identifier'

src/lib.rs
src/main.rs
tests/t.rs

The index narrows the files that might contain the header; every other Rust file is listed without being opened.

Count matches per file, zeros included

glep -c --include-zero 'TODO' -g '*.md' -g '*.rs'

src/lib.rs:0
src/main.rs:0
tests/t.rs:0
tests/todo.md:1

--include-zero needs every file in scope, so this one searches them all. Without it, -c lists only files with a match and the index narrows as usual.

Search for several patterns at once

glep -e TODO -e 'fn main'

src/main.rs:1:fn main() {
tests/todo.md:1:TODO: write tests

Patterns are ORed. For a longer list, put one pattern per line in a file and pass -f patterns.txt. With -e or -f, every positional argument is a path. Each pattern needs a literal of three bytes or more for the index to narrow: one short pattern in the list makes the whole search scan every file.

Preview a rename

glep -r 'parse_command' 'parse_intent' src

src/lib.rs:1:pub fn parse_command(s: &str) {}
src/main.rs:2:    parse_command("hi");

-r only changes what is printed. No file is modified. Capture groups resolve as $1 or ${name}.

Look inside an ignored directory once

glep 'parse_intent' target          # one ignored directory, named explicitly
glep --no-ignore 'parse_intent'     # every ignored file in the tree

A directory you name is walked live with ripgrep’s rules, even if it is ignored, so the first form searches just target/. --no-ignore walks and scans the whole tree, including node_modules and build output, at ripgrep’s cost every time. Neither adds ignored files to the index.

Search compressed logs

glep -z 'needle' logs/

-z decompresses gzip files on the fly and searches the text. Other compressed formats are searched as raw bytes.

Use lookaround or backreferences

glep -P 'parse_(?=intent)'

-P switches to the PCRE2 (Perl Compatible Regular Expressions) engine. --engine auto instead uses the default engine and switches only for patterns that need PCRE2. glep plans the index from the pattern when it can; PCRE2-only syntax that cannot be planned searches every file.

Keep output small for an agent

glep -l 'pattern' | head -20      # at most 20 file names
glep -m 3 -M 200 'pattern'        # at most 3 lines per file, no line over 200 bytes

Closing the pipe early ends glep quietly, with exit status 0 if anything matched. -M replaces long lines, such as minified code, with [Omitted long matching line].

Read results from a script

glep --json 'parse_intent'
glep --stats 'parse_intent'

--json prints one JavaScript Object Notation (JSON) object per line, ending with a summary event; --stats prints totals after the normal output. See Output formats for both shapes.

Point a tool at an index elsewhere

GLEP_INDEX_PATH=/work/repo/.glep glep 'parse_intent'

GLEP_INDEX_PATH names the index directory directly, for a process whose working directory is outside the tree. Paths print relative to the tree root.