Skip to content
glep

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
  1. First principles
  2. Patterns
  3. Regex engines
  4. How the index narrows a search
  5. Scoping to paths
  6. Glob and type filters
  7. Output modes
  8. Context
  9. Multiline
  10. Inverted matches
  11. Hidden files
  12. Ignored files
  13. Binary, encoded and compressed files
  14. Errors on individual files

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:

  1. Choose candidate files. The index, path operands, globs, types, and the hidden and ignore rules decide which files to open.
  2. 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 regex crate, 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 auto uses the default engine and falls back to PCRE2 for a pattern the default engine rejects.
  • --no-unicode turns off Unicode mode, --multiline-dotall lets . match newlines under -U, and --crlf treats \r\n as the line terminator.

PCRE2-only syntax cannot be planned, so such a pattern searches every file. The answer stays correct.

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 -E encoding 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 / --glob uses 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.
  • --iglob matches case-insensitively, and --glob-case-insensitive makes every -g case-insensitive.
  • -t / --type and -T / --type-not use ripgrep’s file type table. --type-add 'name:*.ext' and --type-clear name change it, and --type-list prints it.
  • -d / --max-depth limits how far below each operand to search.
  • --ignore-file PATH adds 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-global and --no-ignore-parent, which each turn off one ignore source.
  • -L / --follow (follow symbolic links) and --one-file-system.
  • --require-git outside 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 / --text searches binary files as text. --binary searches them and reports a match with a binary file matches notice. --null-data treats NUL as the line terminator.
  • -E LABEL / --encoding decodes files before searching (for example utf-16, latin1, shift_jis). -E auto is the default and transcodes files with a byte-order mark; -E none turns that off.
  • -z / --search-zip decompresses gzip files on the fly. Other compressed formats are searched raw.
  • --pre COMMAND searches 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-glob limits 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.