faf
fast as f*#! filename search.
faf is a parallel filesystem search tool written in Rust.
It matches filenames only and stays out of file contents.
Pair it with delfaf to mass-delete whatever the last faf run found.
why this exists
Most search tools scan file contents, allocate per entry, or stall on output locks. faf walks the tree on every core, matches raw filename bytes, and writes results in large batches.
install
cargo
The crate is named fafind because faf was already taken on crates.io.
It installs the faf binary.
packages
# Arch (AUR)
# Homebrew
AUR packaging notes: packaging/aur/README.md.
from source
Requires Rust 1.88 or newer (edition 2024).
Unix only - Linux and macOS. The build fails on Windows by design.
usage
root defaults to /.
matching modes
default (stem match)
Matches the filename without its extension.
An extension on the query is ignored, so faf main.rs is the same as faf main.
Matches main.rs and main.go.
Does not match domain.rs.
substring (-s)
Matches foobar.txt, myfoo.rs, prefoo, and notes.foo.
The whole filename is searched, extension included.
exact (-p)
Matches Makefile only.
-s and -p cannot be combined.
terminal colors
When stdout is a terminal and -0 is not set, matches are highlighted:
| Color | Applies to |
|---|---|
| Dim | Path before the filename |
| Green | The matched part of the name |
| Bold green | Stem in -p mode |
| Yellow | Extension in stem and -p modes |
| Orange | Non-matching parts of the name in -s mode |
--color auto is the default.
Use --color always or --color never to override.
what gets walked
- hidden files and directories are included
- symlinks are never followed
.gitignoreis ignored unless--gitignoreis passed
flags
case insensitive (-i)
ASCII names use a byte-wise fold. Non-ASCII names and queries fall back to full Unicode case folding.
limit depth
exclude (-x)
Values are comma separated.
The flag may repeat and may follow the root.
A value with a /, or starting with ~, is a path.
Anything else is an exact filename and excludes files and directories with that name.
A path names one entry under the root, and an excluded directory is pruned.
~ expands through HOME.
Relative paths resolve from the current directory, then from the root.
The root itself is never excluded, and symlinks are not followed.
Modifiers narrow a group of values:
| Flag | Long form | Meaning |
|---|---|---|
-xf |
--exclude-file |
files only |
-xd |
--exclude-dir |
directories only |
-xp |
--exclude-precise |
exact name, the same as -x for names |
-xs |
--exclude-substr |
substring of the name, or of the path below the root when the value has a / |
-xs paths are matched below the root with a leading slash, so /c/ matches ./c/main.c and ./x/c/y but never the root itself.
Trailing slashes are kept, so build/ does not match builder/.
Modifier letters stack in any order and cluster after other short flags: -xsf, -xdp, and -sxd all work.
Only a tail made entirely of f, d, p, and s counts as modifiers, so -xfoo excludes the name foo and -x f needs the space.
Name values honor -i.
respect .gitignore
filter by type (-f / -d / --type)
-f and -d stack with the other short flags, so -sd, -pf, and -id all work.
They cannot be combined with each other or contradict an explicit --type.
null-separated output (-0)
|
Disables color.
verbose (-v)
Prints [SCAN], [SKIP], and [ERROR] lines to stderr.
Each path value given to -x gets an [EXCLUDE] line showing what it resolved to, whether it exists, and whether it was ignored for being the root or outside it.
Matches still go to stdout, but as [MATCH] <path> lines with color and -0 ignored.
Use it to trace a walk, not to feed another program.
quiet (-q)
Suppresses the summary line on stderr.
performance
- Every core walks the tree through a work-stealing scheduler.
- Filenames are matched as raw bytes, with no UTF-8 decoding or per-entry allocation in the matcher.
- Substring search uses a prebuilt SIMD
memmemfinder. - Non-ASCII names take a cold Unicode path only when
-ineeds it. - Each worker batches output into a private buffer and writes it in 64 KiB chunks, whether stdout is a terminal or a pipe.
- When the reader closes the pipe, as in
faf -s foo / | head, the walk stops instead of scanning the rest of the disk. - Exclude rules are grouped by kind and by entry type, so an entry pays one boolean load when no rule applies to it, and path rules compare only the part of the path below the root.
output
- newline-separated by default, NUL-separated with
-0 - raw OS bytes, no re-encoding
- the matched paths are also written to a cache file for
delfaf, always NUL-separated
The cache path is $FAF_LAST, else $XDG_CACHE_HOME/faf/last, else ~/.cache/faf/last.
A failed cache write never changes the exit code.
exit codes
0 = matches found
1 = no matches
2 = invalid usage
what this is NOT
- not a content search tool (use
greporrg) - not a fuzzy matcher
changelog
See CHANGELOG.md.
license
MIT