glep / Guides
Listing files by name
Use glep --files as a Glob replacement: list files matching a glob, scoped by path, filtered by type, depth and hidden or ignored status.
On this page
glep --files is glep’s Glob replacement. It lists files from the index instead of walking and reading the tree, after the usual freshness sweep. This page describes glep 2.0.0; see Upgrading from 0.3.1 if you are coming from 0.3.1.
First principles
A listing needs only the set of file names, not their contents. Two facts make that set cheap to keep:
- The manifest, the index’s file table, already holds every file’s path. Listing is a filter over it, with no file reads.
- The set changes only when a file is created, deleted or renamed, and each of those changes the modification time (mtime) of the directory that holds the file. On macOS, glep caches each leaf directory’s listing and reuses it while that directory’s mtime is unchanged.
Directory mtimes do not propagate upward, so only leaf directories can be trusted from the cache. Interior directories are always listed live.
List every file
glep --files
Prints every non-hidden file, one path per line, sorted by path. Binary files and files over the size cap are included: they are in the manifest even though their contents are not indexed.
Match a glob
With --files, the first positional argument is a glob, not a path:
glep --files '*.rs' # any .rs file at any depth
glep --files 'src/*.rs' # .rs files directly in src/
glep --files '**/*.py' # any .py file at any depth
glep --files 'src/**/*.rs' # .rs files anywhere under src/
Globs use gitignore-style semantics. A glob without a slash matches the file name at any depth. Once a glob contains a slash, it is matched against the path relative to the current directory, and * does not cross directory separators.
Quote the glob so your shell does not expand it.
Scope to a directory
To list one directory, pass a glob first and the directory after it:
glep --files '**' src # everything under src/
glep --files '*.rs' src # .rs files under src/
glep --files src lists nothing: src is taken as the glob. From a subdirectory, globs match the path relative to that subdirectory:
cd src
glep --files '*.rs' # lib.rs, main.rs
A listing scoped to a directory, by an operand or by running from a subdirectory, reads only that subtree from a live sweep and never opens, builds or writes the index.
Narrow further
The filters from content search also apply:
glep --files -t py # all Python files by type
glep --files -T md # everything except Markdown
glep --files -g '*.toml' -g '*.yaml'
glep --files -g '!tests/**' # exclude a directory
glep --files -d 2 '**' src # at most two levels below src
glep --files --sortr modified # newest first
--sort and --sortr take path, modified, accessed, created or none.
Hidden and ignored files
glep --files --hidden # include dotfiles and dot-directories
glep --files --no-ignore # include ignored files (live walk, no index)
glep --files -uu # both
.git and .glep never appear. --no-ignore and the other flags that change which files exist walk the tree live on every call and never touch the index; see Searching file contents.
Exit codes
glep --files exits 0 when at least one file is listed and 1 when nothing matches.
Speed
The listing itself is an in-memory filter. Before it, the freshness sweep is the main cost on large trees, and --ttl skips it within a read burst. On macOS, a root-wide listing answered from the listing cache needs no full sweep at all.
On the Linux kernel tree, the README’s table, measured on 0.3.1, lists all .c files in 195 ms with the sweep and 45 ms with --ttl, against 71 ms for rg --files and 74 ms for fd. In 2.0.0 the listing cache and its cheaper pruned walk brought --files '**/*.c' to 30.8 ms mean, against 70.3 ms for ripgrep, in the changelog’s measurements. See Benchmarks.