Configuration

On this page

.greplm/config.toml is created by greplm init or on the first greplm index. It controls the walk and indexing:

include = []                       # glob whitelist (empty = all text files)
exclude = ["**/.git/**", "**/node_modules/**", "**/target/**", "**/.greplm/**"]
max_file_size = 4194304            # skip files larger than this (bytes); 0 = no limit
respect_gitignore = true
index_hidden = false
index_binary = false               # index NUL-containing (binary) files, like grep -a
index_empty = false                # index zero-byte files
backend = "auto"                   # auto | rayon (see note below)
merge_threshold = 16               # auto-compact once segments exceed this

backend selects the ingest read backend. Only the portable rayon backend exists today (a pool of buffered reads across worker threads), so auto and rayon are equivalent; the key is kept so config.toml stays forward-compatible if another backend is added. greplm status reports the backend actually in use.

A batched-submission backend (io_uring on Linux) was considered and dropped in 0.5.0: with a warm page cache, reads are ~5.6% of per-file indexing CPU against ~92% for tree-sitter parsing, and reads already overlap parsing across the worker pool. See the roadmap for the measurement.

A config.toml from before 0.5.0 may still say backend = "io-uring". That keeps working — it resolves to the portable backend and logs a warning — so nothing breaks; set it to "auto" to silence the warning.

Environment overrides

These GREPLM_* variables override the file for one-off runs (no need to edit config.toml):

Variable	Effect
GREPLM_MAX_FILE_SIZE	Override max_file_size (bytes)
GREPLM_RESPECT_GITIGNORE	1/true or 0/false
GREPLM_INDEX_HIDDEN	1/true or 0/false
GREPLM_INDEX_BINARY	1/true or 0/false
GREPLM_INDEX_EMPTY	1/true or 0/false
GREPLM_LOG	Log level (debug, info, warn, …)
GREPLM_NO_SAVINGS	1 to disable token-savings recording
GREPLM_FRESHNESS	MCP query freshness: strict for read-after-write (reindex before answering), else lazy (default)
GREPLM_SEMANTIC_MODEL	Path to a Model2Vec model directory (semantic search)
GREPLM_DAEMON_TIMEOUT_MS	Client read timeout for daemon queries, in milliseconds (default 30000); on timeout the query falls back to in-process

The greplm index flags --index-binary, --index-empty, and --max-file-size set the corresponding env vars for that run.

Semantic search ranking (advanced)

Only relevant to greplm semantic-search, which requires a build with --features semantic. Semantic results fuse a BM25 retriever and an embedding retriever with weighted reciprocal-rank fusion; these knobs exist so the weights can be swept offline against a corpus. The defaults were chosen for robustness across dissimilar repositories, so you should not need to change them — they are documented because they exist, not because they are tuning advice.

Variable	Default	Effect
GREPLM_SEM_WBM25	1.0	BM25 weight for natural-language queries
GREPLM_SEM_WEMB	2.5	Embedding weight for natural-language queries
GREPLM_SEM_WBM25_SYM	1.0	BM25 weight when the query looks like a symbol
GREPLM_SEM_WEMB_SYM	0.35	Embedding weight when the query looks like a symbol
GREPLM_SEM_PATHW	0.012	Rerank nudge for a query term matching the file path
GREPLM_SEM_NAMEW	0.004	Rerank nudge for a query term matching the symbol name
GREPLM_SEM_DEDUP_FILE	1.0	Above 0, keep only the best-scoring chunk per file