glep / Guides
Searching file contents
Search file contents with glep: patterns and engines, path scoping, glob and type filters, output modes, context, binary, hidden and ignored files.
On this page
Content search is glep’s Grep replacement. The flags use ripgrep’s spellings and meanings, and the default output is the same bytes as rg -n --no-heading --color=never --sort path. This page describes glep 2.0.0; release 0.3.1 has a smaller flag set, listed in Upgrading from 0.3.1.
First principles
Every search runs in two steps:
- Choose candidate files. The index, path operands, globs, types, and the hidden and ignore rules decide which files to open.
- Match inside them. ripgrep’s regex engines and printers find and print the matches.
The index only ever makes step 1 smaller, and only when it can prove a file cannot match. Step 2 is ripgrep’s own code. So a flag that defeats the proof, such as -v, costs speed, never correctness, and a flag that changes which files exist, such as --no-ignore, skips the index entirely.
Patterns
The first positional argument is a regular expression, in the syntax of Rust’s regex crate, the same as ripgrep’s default engine.
glep 'fn \w+_intent'
glep -F 'parse_intent("' # fixed string, no regex metacharacters
glep -i 'hello' # case-insensitive
glep -S 'hello' # smart case: insensitive unless the pattern has uppercase
glep -w 'parse' # whole words only
glep -x -F 'fn main() {' # whole lines only (-F, since { is regex syntax)
-i, -S and -s (case-sensitive, the default) are a last-wins trio, and -w and -x are a last-wins pair, as in ripgrep.
Several patterns are ORed together:
glep -e TODO -e FIXME # repeat -e
glep -f patterns.txt # one pattern per line from a file
printf 'TODO\nFIXME\n' | glep -f - # patterns from standard input
With any -e or -f, every positional argument is a path: glep -e foo src searches for foo under src/. Use -e when the pattern is literally index or status, which would otherwise run those subcommands:
glep -e index
A pattern that starts with a dash works after -e, with =, or after --:
glep -e '-> Result'
glep --regexp=-v
glep -- -v
Regex engines
- The default engine is Rust’s
regexcrate, with ripgrep’s settings. -P(--pcre2) uses PCRE2 (Perl Compatible Regular Expressions) with its just-in-time compiler, for lookaround and backreferences:glep -P 'parse_(?=intent)'.--engine autouses the default engine and falls back to PCRE2 for a pattern the default engine rejects.--no-unicodeturns off Unicode mode,--multiline-dotalllets.match newlines under-U, and--crlftreats\r\nas the line terminator.
PCRE2-only syntax cannot be planned, so such a pattern searches every file. The answer stays correct.
How the index narrows a search
glep extracts the literal strings a match must contain, turns them into trigrams, and intersects the index’s posting lists to find candidate files. Only those files are searched. How it works has the details.
These patterns cannot be narrowed and search every file in parallel:
- Patterns with no literal of three bytes or more:
ab,.*,\w+,[0-9]{2}. - Alternations where any branch has no such literal:
parse_intent|ab. - Anything under
-v,--passthru,-c --include-zero,--pre, or an-Eencoding other than UTF-8.
Case-insensitive search narrows on the pattern’s ASCII trigrams. Trigrams containing non-ASCII characters are skipped, because a non-ASCII letter can fold to a letter of a different byte length.
Files over the size cap and UTF-16 files are never in the index, so they are always searched. See Indexing and freshness.
Scoping to paths
Positional arguments after the pattern are path operands:
glep 'TODO' src/ tests/
glep 'TODO' src/main.rs
./src,src, and absolute paths inside the tree all work. Paths print relative to the current directory.- Results group by operand in command-line order, in path order within each. A file under two operands prints twice, as in ripgrep.
- A file named as an operand is always searched, even if it is ignored, hidden or binary. Binary data in it is reported as
binary file matches. - A directory the index holds no file under (an ignored directory such as
target, a symbolic link to a directory, or a path outside the tree) is walked live with ripgrep’s rules. - A missing operand prints
glep: <path>: No such file or directory (os error 2)and makes the exit code 2; the other operands are still searched. - With no operand, the search covers the current directory. Run from a subdirectory, that is the subdirectory, not the whole tree.
Glob and type filters
glep -g '*.rs' 'unsafe'
glep -g '!tests/**' 'unsafe' # exclude a directory
glep --iglob '*.MD' 'todo' # case-insensitive glob
glep -t rust -t py 'parse'
glep -T js 'parse' # exclude a type
glep -d 1 'parse' src # at most one level below src
-g/--globuses gitignore-style semantics. A glob without a slash matches at any depth; once it contains a slash,*does not cross directory separators. Globs match the path relative to the current directory.!negates, and the last matching glob wins.-g '!dir'prunes the whole directory.--iglobmatches case-insensitively, and--glob-case-insensitivemakes every-gcase-insensitive.-t/--typeand-T/--type-notuse ripgrep’s file type table.--type-add 'name:*.ext'and--type-clear namechange it, and--type-listprints it.-d/--max-depthlimits how far below each operand to search.--ignore-file PATHadds an ignore file whose rules match relative to the current directory.
A positive -g glob does not bring back files that ignore rules exclude. This differs from ripgrep, where rg -g '*.log' also searches gitignored logs: glep filters the indexed set, which never holds ignored files. Add --no-ignore for that. A glob or -t type does rescue a hidden file, as in ripgrep.
Output modes
glep -l 'pattern' # each matching file once
glep --files-without-match 'pattern' # each file with no match
glep -c 'pattern' # path:count of matching lines
glep --count-matches 'pattern' # path:count of matches
glep --json 'pattern' # JSON Lines (JavaScript Object Notation) events
glep -q 'pattern' # no output, exit code only
These modes are last-wins, as in ripgrep: glep -l --json prints JSON. Per-line options include -o (only the matched part), -r (replace the match in the output), -m N (at most N matching lines per file), -M N (omit lines longer than N bytes), --heading, --vimgrep, --column and --stats. Output formats shows each shape.
Context
glep -C 2 'pattern' # 2 lines before and after
glep -A 3 'pattern' # 3 lines after
glep -B 1 -A 2 'pattern' # 1 before, 2 after
glep --passthru 'pattern' # every line, matches marked
-A and -B override -C for their side. Groups that are not adjacent, including groups in different files, are separated by a -- line, as in ripgrep. Context is ignored in -l and -c modes. With --json, context lines arrive as context events. --passthru and the context flags are a last-wins pair.
Multiline
glep -U 'goodbye\nfoo'
-U / --multiline lets a match span lines, so the pattern may contain \n. ^ and $ still match at line boundaries. Under -U, -c counts matches only when the pattern can really span lines; otherwise it counts lines, as in ripgrep.
Inverted matches
glep -v 'pattern'
-v prints lines that do not match. A file without the pattern still has lines that do not match it, so -v cannot use the index and searches every file.
Hidden files
glep --hidden 'TODO'
By default, files and directories whose names start with a dot are left out, as in ripgrep. --hidden includes them. Hidden files are always in the index, so this needs no rebuild. A ! rule in .gitignore, .ignore or .rgignore that whitelists a dotfile also makes it visible. .git is always excluded, even with --hidden; rg --hidden does search .git.
Ignored files
glep --no-ignore 'needle'
--no-ignore searches files that .gitignore, .ignore, .rgignore and global excludes would skip, such as node_modules or target. It bypasses the index entirely: it does not open, update or write .glep/, and it walks and scans the tree live. It costs the same as rg --no-ignore, every time. This is deliberate: ignored trees must never enter the index.
The same live scan runs for every flag that changes which files exist:
-u(--no-ignore),-uu(adds--hidden) and-uuu(adds--binary), ripgrep’s ladder.--no-ignore-dot,--no-ignore-vcs,--no-ignore-exclude,--no-ignore-globaland--no-ignore-parent, which each turn off one ignore source.-L/--follow(follow symbolic links) and--one-file-system.--require-gitoutside a git repository.--no-index, which walks and scans without the index on purpose.
.git and .glep are still excluded. With --no-ignore, the words index and status are treated as patterns, not subcommands.
Binary, encoded and compressed files
- By default, a file with a NUL byte is treated as binary, as in ripgrep. A NUL in the first 64 KiB means the file prints nothing; a later NUL ends the search of that file there, with ripgrep’s warning.
-a/--textsearches binary files as text.--binarysearches them and reports a match with abinary file matchesnotice.--null-datatreats NUL as the line terminator.-E LABEL/--encodingdecodes files before searching (for exampleutf-16,latin1,shift_jis).-E autois the default and transcodes files with a byte-order mark;-E noneturns that off.-z/--search-zipdecompresses gzip files on the fly. Other compressed formats are searched raw.--pre COMMANDsearches each file’s preprocessed output instead of its bytes. The command receives the file’s path as its only argument and the file on standard input.--pre-globlimits it to matching files.
Errors on individual files
If a file or directory cannot be read during a search, glep prints glep: <path>: <error> to stderr, keeps searching, and exits 2 at the end, as ripgrep does. With -q, a match still exits 0. --no-messages hides the messages but not the exit code.