Search Guide
Choose a retrieval route, narrow the workspace, and tune Zvec-Grep results.
Zvec-Grep offers complementary routes behind one zg <query> command. Start with the route that matches what you know, then narrow the search space before increasing the result count.
Choose a Route
| Your intent | Command | Behavior |
|---|---|---|
| Discover by meaning or combine meaning with keywords | zg "authentication flow" | Hybrid ranked sample |
| Rank known terms by relevance | zg --fts "AuthService" | BM25-ranked sample |
| Search only by conceptual similarity | zg --vector "where credentials are validated" | Vector-ranked sample |
| Find every literal or regex occurrence | zg --rg -n -F "AuthService" src | Exhaustive unless bounded |
Use --rg for exact or exhaustive work. Use indexed retrieval when wording or location is unknown, or when the answer requires relationships across files.
The default positional query combines lexical and vector retrieval:
zg --preview detail "where are user preferences restored at startup" --limit 5Positional words are joined into one query, even when separately quoted. To run separate queries, repeat --hybrid, --fts, or --vector:
zg --hybrid "connection pool" --hybrid "socket timeout"When a question also contains exact anchors, fuse them into one ranked plan:
zg --hybrid "authentication flow" --fts "ForbiddenError" --fuse --limit 10Narrow the Workspace
zg "plugin lifecycle" -g "src/**" -g "!src/generated/**" -t ts| Option | Use it to |
|---|---|
-g, --glob, --iglob | Include or exclude paths |
-t, --type, -T, --type-not | Filter file types |
--modified-after / --modified-before | Filter by modification time |
Control Results and Freshness
| Option | Effect |
|---|---|
--limit <n> | Maximum results per query group |
--preview none|short|full|detail | Source previews; detail adds metadata, outlines, and file grouping |
--debug / --trace | Query and per-hit diagnostics |
--refresh background|wait|off | Index freshness policy |
Output defaults to --preview short in terminals, pipes, and redirected files. full includes all available content of each retrieved item; it does not fetch an entire file.
Indexed results report fresh or possibly_stale. Refresh defaults to background in server mode and off in direct mode; direct mode cannot refresh in the background. Use --refresh wait when changes must be indexed before searching.
Improve Weak Results
- Confirm the workspace root and index state with
zg --status. - Restrict the query to relevant paths or file types.
- Add one or two concrete anchors with
--fts. - Switch to
--rgwhen the target text is known. - Review Supported Content and the selected Embedding Models.
Run zg --help search for the installed version's complete flag reference. If results remain weak, follow Troubleshooting.