glep / Get started
Quickstart
Build a glep index in a project, run a first content search and file listing, search from a subdirectory, and read the exit codes.
On this page
This page assumes glep is installed. See Installation. The examples show the output of glep 2.0.0; release 0.3.1 differs in places, listed in Upgrading from 0.3.1.
First principles
- The index is a cache of your tree’s contents, keyed by 3-byte sequences. It never holds anything the tree does not, so deleting
.glep/loses nothing but time. - Every query checks the cache against the tree before it answers (the freshness sweep). After the first build you never manage the index by hand.
- glep finds the cache by walking up from the current directory to the nearest
.glep/, the way git finds.git/. Where you build the index decides which tree it covers.
1. Build the index
Run this once, from the project root:
cd your-project
glep index
glep index prints glep: indexed N files to stderr, and on large trees a progress line every 5,000 files. The build reads every file once and records its trigrams. On the Linux kernel tree it took 28 s, against 1.3 to 3.5 s for one ripgrep full scan, so it pays off only over repeated searches.
The step is optional. With no index anywhere above the current directory, the first query builds one in the current directory. On a tree holding more than 64 MiB, that first query answers with a full scan and builds the index in a detached low-priority process (inline on Windows). See Indexing and freshness.
The agent hooks only act when the session’s working directory contains .glep/. If you use them, run glep index in the project root.
.glep/ contains its own .gitignore with *, so git never tracks it. glep does not touch your project’s .gitignore.
2. Search file contents
glep 'parse_intent'
src/lib.rs:1:pub fn parse_intent(s: &str) {}
src/main.rs:2: parse_intent("hi");
The format is path:line:text, the same bytes rg -n --no-heading --color=never --sort path prints. Common ripgrep flags work:
glep -i 'todo' src/ # case-insensitive, only under src/
glep -w 'parse' # whole words only
glep -l 'parse_intent' # file names only
glep -c 'parse_intent' # per-file count of matching lines
glep -C 2 'parse_intent' # two lines of context on each side
glep -g '*.rs' 'unsafe' # only files matching a glob
More in Searching file contents.
3. List files by name
glep --files '*.rs'
src/lib.rs
src/main.rs
With --files, the first positional argument is a glob, not a path. glep --files with no glob lists every file. More in Listing files by name.
4. Check the index
glep status
files: 5
skipped (binary/oversized/utf16): 0
last sweep epoch: 1792899548
files counts every file in the index, hidden ones included. skipped counts files whose contents are not indexed: binary files, files over the size cap, and UTF-16 files. They are still searched when a query needs them. last sweep epoch is the time of the last full freshness sweep, in Unix seconds; status runs one before it prints.
5. Search from a subdirectory
glep finds the index in a parent directory, limits the search to the directory you are in, and prints paths relative to it, as rg does:
cd src
glep 'parse_intent'
lib.rs:1:pub fn parse_intent(s: &str) {}
main.rs:2: parse_intent("hi");
glep index run from a subdirectory rebuilds the index of the tree it belongs to, not a new one.
Exit codes
0: at least one match (or at least one file listed).1: no matches. This is not an error.2: an error, such as an invalid regex, a missing path operand, or an unreadable file. Messages go to stderr prefixed withglep:. The search still covers everything it can, and with-qa match still exits0.
Edits are visible immediately
Every query first sweeps the tree for changed files and reindexes them, so a file you just edited, created or deleted is reflected in the next search. There is nothing to restart.
For read-only bursts you can trade that for speed with --ttl, which skips the sweep if the last recorded full sweep ran within the given number of seconds. A --ttl query that sweeps records its sweep time, which starts the window. A file created inside that window is invisible until the window ends:
glep --ttl 60 'parse_intent' > /dev/null # sweeps and starts a 60-second window
echo 'parse_intent_new' > src/new.rs
glep --ttl 60 'parse_intent_new' # exit 1: the sweep was skipped
glep 'parse_intent_new' # src/new.rs:1:parse_intent_new
Drop --ttl after any edit. See Indexing and freshness.