What is fzf?
fzf is a general-purpose, interactive command-line fuzzy finder written by Junegunn Choi. It reads a list of items from standard input, opens an interactive full-screen TUI for filtering, and writes the selected items to standard output.
Core Philosophy
fzf is a filter in the Unix pipeline sense. It doesn't know what data it's filtering — files, processes, git commits, Docker containers, SSH hosts. Whatever produces lines, fzf can filter it. Whatever consumes lines, fzf feeds it.
How fzf Fits the Unix Pipeline
flowchart LR
PRODUCER["Producer\n(ls, find, git log,\nps, history, cat)"]
FZF["fzf\n(interactive filter)"]
CONSUMER["Consumer\n(nvim, kill, ssh,\ngit checkout, rm)"]
PRODUCER -->|stdin| FZF
FZF -->|stdout| CONSUMER
Everything is a pipe:
# Producer → fzf → Consumer
find . -name "*.log" | fzf | xargs tail -f
git branch | fzf | xargs git checkout
ps aux | fzf | awk '{print $2}' | xargs kill
cat /etc/hosts | fzf | awk '{print $1}' | xargs ping -c 1
What "Fuzzy" Means
Fuzzy matching means you don't need to type exact characters. fzf scores each candidate against your query and ranks them:
Query: "nvconf"
Matches (ranked by score):
~/.config/nvim/init.lua ← best: all chars present
~/.config/nvim/lua/config/lsp.lua ← good
/etc/nginx/nginx.conf ← weaker match
The scoring algorithm rewards:
- Consecutive matches —
abcmatchingabcbeatsa..b..c - Word-boundary matches — matching the start of words/path segments
- Leftmost matches — matches near the beginning of the string
What fzf Is NOT
| Misconception | Reality |
|---|---|
| A file manager | fzf just selects from lists — what you do with the selection is up to you |
A replacement for grep | grep filters non-interactively; fzf is interactive |
| A search engine | fzf scores against pre-generated input; it doesn't search the filesystem itself |
| A GUI tool | fzf is a TUI that runs entirely inside the terminal |
Key Features
- Blazing fast — written in Go, handles millions of items without lag
- Zero dependencies — a single binary, works anywhere
- Portable — Linux, macOS, Windows (WSL), BSD
- Composable — integrates with any Unix tool via pipes
- Extensible —
--preview,--bind,--header, transforms - Shell integration — CTRL-T, CTRL-R, ALT-C built-in for bash/zsh/fish
Core Use Cases
| Use Case | Command pattern |
|---|---|
| Open a file | nvim $(fzf) |
| Kill a process | ps aux | fzf | awk '{print $2}' | xargs kill |
| Checkout git branch | git branch | fzf | xargs git checkout |
| Search shell history | CTRL-R (built-in integration) |
| SSH to a host | cat ~/.ssh/config | grep Host | fzf | xargs ssh |
| Connect to Docker container | docker ps | fzf | awk '{print $1}' | xargs docker exec -it |