glep / Reference
CLI reference
Every glep argument, flag, subcommand, default value, environment variable and exit code, taken from the clap parser in src/cli.rs.
On this page
This reference matches glep 2.0.0 (src/cli.rs at the v2.0.0 release). The 0.3.1 release has a much smaller flag set; see Flags added since 0.3.1.
First principles
glep accepts ripgrep’s flag spellings for the same reason it prints ripgrep’s bytes: an agent or script that knows rg should need nothing new. Two rules from ripgrep carry over. A repeated flag is last-wins (-A1 -A2 means -A2), while list flags such as -e, -g and -t accumulate. A flag that takes a value takes the next word verbatim, even one starting with a dash (-e -foo).
What a flag costs depends on what it does to the index:
- Matching and printing flags (
-i,-w,-o,--json, and most others) leave the index alone. Narrowing works as usual. - Flags that defeat narrowing (
-v,--passthru,-c --include-zero,--pre, a non-UTF-8-E) still use the index’s file list but search every file. - Flags that change which files exist (
--no-ignore,-u, the--no-ignore-*family,-L,--one-file-system,--require-gitoutside a repository,--no-index) never open the index and run a live scan at ripgrep’s cost.
Synopsis
glep [OPTIONS] [PATTERN] [PATHS]...
glep [OPTIONS] -e PATTERN... [PATHS]...
glep [OPTIONS] --files [GLOB] [PATHS]...
glep [OPTIONS] index
glep [OPTIONS] status
Positional arguments
PATTERN: the regular expression to search for. With--files, this slot is a glob instead. The wordsindexandstatusin this slot run subcommands (see below).PATHS...: path operands that limit the search. Relative (src,./src) and absolute paths are accepted. A file operand is always searched. With any-eor-f(and no--files), every positional argument is a path.
Subcommands
glep has no separate subcommand parser. These words are recognized in the pattern slot when none of -e, -f, --files or --no-ignore is given:
index: build the index from scratch for the current tree (the nearest.glep/above the current directory, or the current directory). Printsglep: indexed N filesto stderr. Honors--max-filesize. Fails withglep: another glep holds the index lockif another glep holds the lock.status: bring the index up to date (building it if needed), then print three lines to stdout:files:,skipped (binary/oversized/utf16):, andlast sweep epoch:(Unix seconds).
To search for the literal word index or status, use -e index.
Search options
Patterns:
-e, --regexp <PATTERN>: a pattern. Repeatable; all patterns are ORed.-f, --file <FILE>: read patterns from a file, one per line;-f -reads standard input. Repeatable; ORed with-e. An empty line matches every line.-F, --fixed-strings: treat patterns as literal strings.
Case and word boundaries:
-i, --ignore-case: case-insensitive.-S, --smart-case: case-insensitive unless the pattern has an uppercase character.-s, --case-sensitive: case-sensitive (the default).-i,-Sand-sare last-wins.-w, --word-regexp: match whole words only.-x, --line-regexp: match whole lines only.-wand-xare last-wins.-v, --invert-match: print lines that do not match. Disables index narrowing.
Engine and regex settings:
-P, --pcre2: use PCRE2 (Perl Compatible Regular Expressions) with just-in-time (JIT) compilation.--engine <ENGINE>:default,pcre2, orauto(the default engine, falling back to PCRE2 when a pattern needs it). Last-wins with-P.-U, --multiline: allow matches to span lines. Overrides--stop-on-nonmatch.--multiline-dotall: make.match newlines (visible under-U).--no-unicode: turn off Unicode mode in the regex.--crlf: treat\r\nas the line terminator. Last-wins with--null-data.--null-data: use NUL as the line terminator. Implies-a.--dfa-size-limit <SIZE>,--regex-size-limit <SIZE>: regex engine limits;K,M,Gsuffixes accepted.-E, --encoding <LABEL>: decode files before searching (for exampleutf-16,latin1,shift_jis).auto(default) transcodes files with a byte-order mark;noneturns that off. A non-UTF-8 label disables index narrowing.--no-encoding: back to-E auto.
Output options
Output modes (last-wins, as in ripgrep):
-l, --files-with-matches: print each matching file path once.--files-without-match: print each file with no match.-c, --count: printpath:countof matching lines per file.--count-matches: printpath:countof matches per file.--json: print ripgrep-compatible JSON Lines events (one JavaScript Object Notation object per line), ending with a summary event. See Output formats.
Quiet and summaries:
-q, --quiet: print nothing; the exit code reports whether anything matched.--jsonstill prints its summary event and--statsits block.--include-zero: with-c, also printpath:0for searched files with no match. Disables index narrowing.--stats: print ripgrep’s statistics block after the results.
Per-line output:
-n, --line-number: show line numbers (already the default).-N, --no-line-number: hide line numbers.--column: show the column of the first match.-b, --byte-offset: show the byte offset of each printed line.--vimgrep: one line per match aspath:line:column:text.-o, --only-matching: print only the matched part.-r, --replace <TEXT>: replace each match in the output;$1and${name}resolve capture groups. Files are not changed.-m, --max-count <NUM>: stop after NUM matching lines per file.-m 0exits 1 without searching.-M, --max-columns <NUM>: replace lines longer than NUM bytes with an omission note.--max-columns-preview: with-M, show a preview of the long line instead.--trim: remove leading whitespace from printed lines.
Paths and separators:
--heading: print each file’s path on its own line above its matches.-H, --with-filename: always print the path. The default, except when the only operand is a single file.-I, --no-filename: never print the path. Last-wins with-H.-0, --null: end printed paths with NUL.--path-separator <SEP>: replace the path separator in output (one byte;""keeps the default).--field-match-separator <SEP>,--field-context-separator <SEP>: separators between fields on match and context lines (defaults:and-).--context-separator <SEP>: separator between context groups (default--).--no-context-separatorprints none.
Escapes such as \t and \x7F are decoded in every separator flag.
Color and terminals:
--color <WHEN>:auto(the default: color when stdout is a terminal, none when it is a pipe or file),always,ansi, ornever, as in ripgrep.--colors <SPEC>: a color spec such aspath:fg:magenta. Repeatable.-p, --pretty: same as--color always --heading --line-number; a later flag overrides its part.--hyperlink-format <FORMAT>: Operating System Command 8 (OSC 8) terminal hyperlinks for paths (for exampledefault,file,kitty). Written only when color is on.--hostname-bin <COMMAND>: program whose output is the host name used by{host}in hyperlink formats.--line-buffered: flush output after every line.
Context:
-C, --context <N>: N lines before and after each match.-A, --after-context <N>: N lines after. Overrides-Cfor that side.-B, --before-context <N>: N lines before. Overrides-Cfor that side.--passthru(alias--passthrough): print every line, matches marked. Last-wins with the context flags. Disables index narrowing.--stop-on-nonmatch: stop reading a file at the first non-matching line after a match.
Filters
--files: list files matching a glob (the pattern slot) instead of searching content. With no glob, list every file.-g, --glob <GLOB>: keep files matching this glob;!excludes. Repeatable; the last matching glob wins. A glob without/matches at any depth; with/,*does not cross separators. Globs match the path relative to the current directory.--iglob <GLOB>: like-g, case-insensitive. These rules come after every-grule.--glob-case-insensitive: make every-gcase-insensitive.-t, --type <TYPE>: keep files of this type. Repeatable. An unknown type is an error.-T, --type-not <TYPE>: drop files of this type. Repeatable.--type-add <SPEC>: add a type,name:globorname:include:a,b. Repeatable.--type-clear <TYPE>: clear a type’s globs. Repeatable.-d, --max-depth <N>(alias--maxdepth): search at most N levels below each operand. A file operand is depth 0.--hidden: include hidden (dot-prefixed) files and directories..gitis always excluded.--ignore-file <PATH>: an extra ignore file. Repeatable. Its rules match paths relative to the current directory, as in ripgrep, wherever the file itself lives. The tree’s own whitelist rules beat them.--ignore-file-case-insensitive: match--ignore-filerules case-insensitively.--sort <FIELD>,--sortr <FIELD>: sort results bypath,modified,accessed,created, ornone;--sortrreverses. Last-wins pair.
Live-scan options
Each of these runs a live walk and scan that never opens, updates or writes the index:
--no-ignore: include files that ignore files and global excludes skip.-u, --unrestricted:-uis--no-ignore,-uuadds--hidden,-uuuadds--binary.--no-ignore-dot: do not respect.ignoreand.rgignorefiles.--no-ignore-vcs: do not respect.gitignore,.git/info/excludeor the global gitignore.--no-ignore-exclude: do not respect.git/info/exclude.--no-ignore-global: do not respect the global gitignore.--no-ignore-parent: do not respect ignore files in the directories above each operand.--require-git: apply git ignore rules only inside a git repository, as ripgrep does by default. Outside a repository this is a live scan.-L, --follow: follow symbolic links.--one-file-system: do not descend into other mounted filesystems.--no-index: skip the index for this run.
.git and .glep stay excluded under all of them.
Binary, compressed and preprocessed files
-a, --text: search binary files as text.--binary: search binary files and report a match with abinary file matchesnotice. Last-wins with-a.-z, --search-zip: decompress gzip files while searching. Other formats are searched raw.--pre <COMMAND>: search each file’s preprocessed output. The file path is the command’s only argument, and the file is also its standard input. Disables index narrowing.--pre-glob <GLOB>: apply--preonly to matching files;!globexempts files. Repeatable.--mmap: accepted for compatibility; no effect.--no-mmap: stream every file through the searcher’s buffer instead of searching it as one slice.
Index options
--ttl <SECONDS>: skip the freshness sweep if the last one ran within this many seconds. Default:0(always sweep).--max-filesize <SIZE>: files larger than this are not indexed and are scanned live instead.K,MandGsuffixes accepted. Default:1048576(1 MiB).
General
-j, --threads <N>: search worker threads.0or unset means automatic:GLEP_THREADSif set, else the performance-core count on Apple Silicon Macs, else one per core.--no-messages: hide error messages. The exit code is unchanged.--no-ignore-messages: hide messages about ignore files that cannot be read or parsed.--debug,--trace: print debugging information to stderr.--type-list: print every file type and its globs, then exit. Reflects--type-addand--type-clear.--pcre2-version: print the PCRE2 version, then exit.--generate <KIND>: print a man page (man) or shell completions (complete-bash,complete-zsh,complete-fish,complete-powershell), then exit.-h, --help: print help.-V, --version: print the version.
Compatibility spellings
glep also accepts ripgrep’s negated and alias spellings, so scripts written for rg run unchanged. Each acts where it stands on the command line: -uu --no-hidden hides dotfiles again.
- Negations:
--no-require-git,--no-hidden,--no-text,--no-binary,--no-pcre2,--no-follow,--no-crlf,--no-multiline,--no-multiline-dotall,--no-fixed-strings,--no-invert-match,--no-json,--no-stats,--no-trim,--no-search-zip,--no-column,--no-byte-offset,--no-include-zero,--no-max-columns-preview,--no-line-buffered,--no-block-buffered,--no-one-file-system,--no-glob-case-insensitive,--no-ignore-file-case-insensitive,--no-pre,--no-heading,--no-sort-files. - Re-enables:
--ignore,--ignore-dot,--ignore-vcs,--ignore-exclude,--ignore-global,--ignore-parent,--no-ignore-filesand--ignore-files,--unicode,--messages,--ignore-messages. - Aliases:
--print0(-0),--sort-files(--sort path),--depth(-d). - No-ops:
--no-config(glep reads no config file) and--block-buffered. - Deprecated ripgrep pairs:
--auto-hybrid-regexand--pcre2-unicode, with their--no-forms.
Flags added since 0.3.1
The 0.3.1 release accepts only -e (once), -i, -F, -U, -l, -c, --json, -C, -A, -B, --files, -g, -t, --hidden, --no-ignore, --ttl, --max-filesize, -h and -V. Every other flag on this page is new in 2.0.0. In 0.3.1, -l and -c conflict with --json, -c conflicts with -l, and --max-filesize takes a plain byte count. See Upgrading from 0.3.1.
Environment variables
GLEP_INDEX_PATH: path to an index directory (a.glep/) to use instead of searching upward for one. Its parent is the tree root.GLEP_TIMING: when set to any value, print per-stage timings to stderr.GLEP_THREADS: default number of search worker threads when-jis absent or0. An explicit-j Nwins.GLEP_SYNC_BUILD: when set, the first query always builds the index inline, never in the background.GLEP_BG_BUILD_MIN_BYTES: the tree size above which the first query builds the index in the background (default 64 MiB;K,M,Gsuffixes accepted).GLEP_NO_BULK_SWEEP: macOS only. Use the portable directory walker instead of thegetattrlistbulkfast path.GLEP_NO_DIRCACHE: macOS only. Turn off the listing cache keyed on directory modification times.
Exit codes
0: a match was found, a file was listed, or a subcommand succeeded.1: no match and no error.-m 0, or an empty pattern set without-v, exits 1 without searching.2: an error. Examples: an invalid regex or flag value, a missing path operand, an unreadable file or directory, a failing--precommand, or no pattern and no--files(glep: a pattern is required (or --files)). Per-file errors do not stop the search. With-q, a match still exits 0.- With no path operand, a search whose filters leave no file at all prints
glep: No files were searched, which means glep probably applied a filter you didn't expect.and exits 2, as ripgrep does.
Errors print to stderr with a glep: prefix. Argument errors print clap’s usage message. If the reader of stdout closes early (for example glep pattern | head -5), glep stops quietly with the status the results so far decide.
Files
.glep/in the tree root holds the index. See Indexing and freshness.