Source: https://velofy.co/glep/examples/

[glep](https://velofy.co/glep/) / Guides

# Worked examples

Worked glep examples for common search tasks: definitions, exclusions, subdirectories, agent bursts, missing headers, renames, ignored and compressed files.

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](https://velofy.co/glep/installation/#release-031-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](https://velofy.co/glep/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.