fafind 3.1.0

Fast parallel filesystem search by filename (installs the `faf` binary)
Documentation

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

cargo install fafind

The crate is named fafind because faf was already taken on crates.io. It installs the faf binary.

packages

# Arch (AUR)
yay -S faf-bin

# Homebrew
brew install eof0/tap/faf

AUR packaging notes: packaging/aur/README.md.

from source

Requires Rust 1.88 or newer (edition 2024).

git clone https://github.com/eof0/faf
cd faf
cargo build --release
sudo cp target/release/faf /usr/local/bin/

Unix only - Linux and macOS. The build fails on Windows by design.


usage

faf <target> [root]

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.

faf main .

Matches main.rs and main.go. Does not match domain.rs.

substring (-s)

faf -s foo .

Matches foobar.txt, myfoo.rs, prefoo, and notes.foo. The whole filename is searched, extension included.

exact (-p)

faf -p Makefile .

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
  • .gitignore is ignored unless --gitignore is passed

flags

case insensitive (-i)

faf -i readme .

ASCII names use a byte-wise fold. Non-ASCII names and queries fall back to full Unicode case folding.

limit depth

faf --max-depth 3 main .

exclude (-x)

faf main ~ -x target,node_modules
faf -f main ~ -x "~/work/typescript,~/work/c/,main.lua,main.cpp"

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 /
faf main ~ -xd build          # prune directories named build, keep files named build
faf -s main ~ -xs header,/c/  # drop names containing header and paths containing /c/
faf main ~ -xfs .bak          # files only, by substring

-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

faf --gitignore main .

filter by type (-f / -d / --type)

faf -f main .         # files only
faf -d src .          # directories only
faf --type a main .   # any (default)

-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)

faf -0 main . | xargs -0 rm

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 memmem finder.
  • Non-ASCII names take a cold Unicode path only when -i needs 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 grep or rg)
  • not a fuzzy matcher

changelog

See CHANGELOG.md.

license

MIT