Skip to content
glep

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
  1. First principles
  2. Synopsis
  3. Positional arguments
  4. Subcommands
  5. Search options
  6. Output options
  7. Filters
  8. Live-scan options
  9. Binary, compressed and preprocessed files
  10. Index options
  11. General
  12. Compatibility spellings
  13. Flags added since 0.3.1
  14. Environment variables
  15. Exit codes
  16. Files

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-git outside 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 words index and status in 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 -e or -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). Prints glep: indexed N files to stderr. Honors --max-filesize. Fails with glep: another glep holds the index lock if 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):, and last 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, -S and -s are last-wins.
  • -w, --word-regexp: match whole words only.
  • -x, --line-regexp: match whole lines only. -w and -x are 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, or auto (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\n as 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, G suffixes accepted.
  • -E, --encoding <LABEL>: decode files before searching (for example utf-16, latin1, shift_jis). auto (default) transcodes files with a byte-order mark; none turns 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: print path:count of matching lines per file.
  • --count-matches: print path:count of 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. --json still prints its summary event and --stats its block.
  • --include-zero: with -c, also print path:0 for 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 as path:line:column:text.
  • -o, --only-matching: print only the matched part.
  • -r, --replace <TEXT>: replace each match in the output; $1 and ${name} resolve capture groups. Files are not changed.
  • -m, --max-count <NUM>: stop after NUM matching lines per file. -m 0 exits 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-separator prints 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, or never, as in ripgrep.
  • --colors <SPEC>: a color spec such as path: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 example default, 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 -C for that side.
  • -B, --before-context <N>: N lines before. Overrides -C for 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 -g rule.
  • --glob-case-insensitive: make every -g case-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:glob or name: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. .git is 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-file rules case-insensitively.
  • --sort <FIELD>, --sortr <FIELD>: sort results by path, modified, accessed, created, or none; --sortr reverses. 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: -u is --no-ignore, -uu adds --hidden, -uuu adds --binary.
  • --no-ignore-dot: do not respect .ignore and .rgignore files.
  • --no-ignore-vcs: do not respect .gitignore, .git/info/exclude or 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 a binary file matches notice. 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 --pre only to matching files; !glob exempts 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, M and G suffixes accepted. Default: 1048576 (1 MiB).

General

  • -j, --threads <N>: search worker threads. 0 or unset means automatic: GLEP_THREADS if 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-add and --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-files and --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-regex and --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 -j is absent or 0. An explicit -j N wins.
  • 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, G suffixes accepted).
  • GLEP_NO_BULK_SWEEP: macOS only. Use the portable directory walker instead of the getattrlistbulk fast 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 --pre command, 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