Find anything.
Compose everything.

1. Mental model: interactive filter, not file finder

fzf reads candidate records, lets a person narrow and select them, then writes accepted records. It does not inherently know what a file, process, branch, container, or command is. That ignorance makes it reusable.

producer | fzf [options] | consumer

printf '%s\n' alpha beta gamma | fzf
git branch --format='%(refname:short)' | fzf | xargs git switch

Three layers worth separating

2. Install and enable shell integration

Prefer current package from official release channel or package manager. Distribution repositories can lag, so compare fzf --version when an option from this guide is missing.

brew install fzf
fzf --version

# Debian/Ubuntu package
sudo apt install fzf

# Or follow official binary/git install

Shell setup

Modern fzf binaries embed integration scripts. Add one line to shell startup file, then start a new shell.

# ~/.zshrc
source <(fzf --zsh)

# Reload now
exec zsh

Quick health check

printf '%s\n' red green blue | fzf --height=40% --border
# type: gr   → press Enter   → terminal prints: green

3. Tutorial: from list to file launcher in 25 minutes

Work inside any small project directory. Commands inspect or open files; none modify project content unless editor saves changes.

printf '%s\n' git-status-guide.md getting-started.md glossary.md release-notes.md | fzf

fzf --height=70% --layout=reverse --border --prompt='file › '

# Explicit source with fd (if installed)
fd --type f --hidden --exclude .git | fzf --scheme=path

fzf --preview 'sed -n "1,200p" {}' \
  --preview-window='right,60%,wrap' \
  --bind='ctrl-/:toggle-preview'

# Better colorized preview when bat exists
fzf --preview 'bat --color=always --style=numbers --line-range=:300 -- {}' \
  --preview-window='right,60%,border-left'

# Shell receives one selected path
file=$(fzf) || exit
${EDITOR:-vi} -- "$file"

# Or replace fzf directly; no parsing round-trip
fzf --bind='enter:become(${EDITOR:-vi} -- {})'

rg --column --line-number --no-heading --color=always --smart-case . |
  fzf --ansi --delimiter=: \
    --preview 'bat --color=always --highlight-line {2} --line-range=:500 -- {1}' \
    --preview-window='right,60%,+{2}/2' \
    --bind='enter:become(${EDITOR:-vi} +{2} -- {1})'

printf '%s\n' alpha beta gamma delta | fzf --multi
# Tab marks and moves down; Shift-Tab marks and moves up.
# Enter prints marked rows, or current row when nothing marked.

4. Practice simulator

Browser approximation builds muscle memory without launching terminal. Type fragments; use ↑/↓, Tab, and Enter. Scoring intentionally simplified; real fzf ranking is richer.

5. Query grammar: fuzzy, exact, anchored, negative, OR

Default extended search splits query on unescaped spaces. Terms on same side of | combine with AND; bar separates alternatives. Smart-case is case-insensitive until query contains uppercase.

Scoring and schemes

• --scheme=default: general scoring.
• --scheme=path: rewards matches after path separators and prioritizes filename portion.
• --scheme=history: preserves chronological importance using input order.
• --tiebreak=CRI[,..]: order for tied scores—length (default), chunk, pathname, begin, end, index; index is implicitly appended last.
• --exact: exact becomes default; leading apostrophe switches a term back to fuzzy.
• --no-sort: retain source order while filtering; useful for logs and pre-ranked sources.

Automatic choice: when input comes from terminal (built-in walker or FZF_DEFAULT_COMMAND) and no reload/transform is bound to start, fzf picks path scheme by itself; piped input gets default. Explicit --scheme overrides.

6. Navigation, editing, and selection

--multi enables unlimited selection; --multi=3 caps it. If nothing marked, accepting returns current item. Output order follows selected item order as managed by fzf, not necessarily current visual rank—test before relying on ordering.

7. Input/output contract and exit status

Capture without losing cancel semantics

# Correct: only act when accepted
if choice=$(printf '%s\n' one two three | fzf); then
  printf 'selected: %s\n' "$choice"
else
  printf 'cancelled\n' >&2
fi

Machine-friendly modes

• --filter=QUERY: print matching items and exit; useful for tests/scripts, no interactive UI.
• --select-1: auto-select if initial result has exactly one match.
• --exit-0: exit if initial result has no match.
• --print-query: first output record is query, then selections.
• --expect=ctrl-e,ctrl-v: first output record identifies accept key; remaining records are choices.
• --read0 --print0: NUL-delimited input/output for arbitrary filenames.

# GNU/BSD find emits NULs; loop consumes NULs
find . -type f -print0 |
  fzf --read0 --print0 --multi |
  while IFS= read -r -d '' path; do
    printf 'picked: %q\n' "$path"
  done

8. Fields, display transforms, accepted values, placeholders

Structured lines often contain machine ID plus human label. fzf can search/display selected fields while preserving or transforming emitted value.

# input: id TAB name TAB environment
printf '42\tPayments API\tprod\n17\tDocs site\tstaging\n' |
  fzf --delimiter=$'\t' --with-nth=2,3 --accept-nth=1

Field expressions

1 first-1 last2.. from second..-2 through second-last3..5 range.. all

Command placeholders

9. Preview windows: context without commitment

Preview command executes whenever focus changes. It receives placeholders and size variables such as $FZF_PREVIEW_LINES and $FZF_PREVIEW_COLUMNS.

fzf --preview 'bat --color=always --style=plain -- {}' \
  --preview-window='right,55%,wrap,border-left' \
  --preview-label=' file preview ' \
  --bind='ctrl-/:change-preview-window(right,55%|down,45%|hidden|)'

Preview the right kind of object

# Directory: tree; file: bat
fzf --preview '
  if [ -d {} ]; then
    tree -C -L 2 -- {}
  else
    bat --color=always --style=numbers --line-range=:300 -- {}
  fi
'

10. Layout and appearance

Good presentation communicates scope, available actions, and current mode. fzf can run full-screen, occupy terminal height, or open as a floating pane.

fzf --height='~70%' --layout=reverse --style='full:rounded' \
  --input-label=' query ' --list-label=' matches ' \
  --preview-label=' preview ' --ghost='type to filter' \
  --footer='Enter accept · Tab select · Esc cancel'

Raw mode and list fidelity

--raw keeps non-matching items visible with a distinct gutter; matching items remain navigable as matches. --no-sort retains input order, while --tac reverses it. These controls help dashboards/logs where surrounding records and source order carry meaning.

11. Bindings and actions: turn selector into interface

Binding shape: KEY:ACTION. Separate bindings with comma; chain actions with +. Quote whole argument for shell.

fzf --multi \
  --bind='ctrl-a:select-all,ctrl-d:deselect-all' \
  --bind='ctrl-/:toggle-preview' \
  --bind='alt-enter:execute(${EDITOR:-vi} -- {})' \
  --bind='enter:become(${EDITOR:-vi} -- {})'

Action delimiters

Parentheses are readable: execute(vim {}). If command contains parentheses, choose paired delimiter unlikely to conflict: execute[cmd], execute{cmd}, execute~cmd~. Colon form consumes rest of binding and must be last.

Choose effect semantics deliberately

• execute(...): visible interactive command; fzf returns afterward.
• execute-silent(...): no alternate-screen switch; best for quick invisible effect. Still blocks unless command backgrounds itself.
• become(...): replaces fzf, simplest final launcher, preserves exit behavior better than parsing text through xargs.

12. Dynamic data: reloads, events, transforms

reload(...) swaps candidates while fzf stays open. Events trigger actions from state changes. Together they create live process pickers, search launchers, log viewers, and dashboards.

Manual process refresh

ps -ef |
  fzf --header-lines=1 --layout=reverse --track --id-nth=2 \
    --header='Ctrl-R refreshes · Enter prints process row' \
    --bind='ctrl-r:reload(ps -ef)'

Interactive ripgrep launcher

RG='rg --column --line-number --no-heading --color=always --smart-case'
fzf --ansi --disabled --query='' \
  --bind="start,change:reload:$RG {q} || true" \
  --delimiter=: \
  --preview='bat --color=always --highlight-line {2} -- {1}' \
  --preview-window='right,60%,+{2}/2' \
  --bind='enter:become(${EDITOR:-vi} +{2} -- {1})'

Useful events

reload-sync keeps old list until replacement command completes. --track --id-nth=FIELD helps retain focus across reloads by stable identity.

External control with --listen

fzf can accept actions over local HTTP or Unix domain socket. This enables another process to send up, reload(...), or composed actions while interface runs.

# Terminal 1: local Unix socket (path must end in .sock)
# --no-tmux keeps fzf inline even if your defaults enable --popup/--tmux
fzf --listen=/tmp/my-picker.sock --no-tmux

# Terminal 2: send harmless navigation action
curl --unix-socket /tmp/my-picker.sock http -d 'down'

13. Built-in shell integration

Fuzzy completion

In Bash/Zsh integration, type trigger (default **) then Tab in supported contexts:

vim **<Tab>        # files/directories
cd **<Tab>          # directories
ssh **<Tab>         # hostnames
kill -9 **<Tab>     # processes
export **<Tab>      # variables

Customize before sourcing

# ~/.zshrc, before source <(fzf --zsh)
export FZF_CTRL_T_OPTS="--preview 'bat --color=always --style=numbers -- {}'"
export FZF_ALT_C_OPTS="--preview 'tree -C -L 2 -- {}'"
export FZF_CTRL_R_OPTS="--height=60% --layout=reverse --border"
source <(fzf --zsh)

14. Configuration: defaults without surprising scripts

FZF_DEFAULT_OPTS applies everywhere—interactive commands, scripts, plugins, shell integration. Keep universal defaults visual and conservative. Put workflow behavior in aliases/functions.

# Safe-ish global presentation
export FZF_DEFAULT_OPTS='
  --height=70%
  --layout=reverse
  --border
  --info=inline-right
  --cycle
  --bind=ctrl-/:toggle-preview
'

# Alternative: keep defaults in a file, parsed like FZF_DEFAULT_OPTS
export FZF_DEFAULT_OPTS_FILE="$HOME/.fzfrc"

Reusable function pattern

# Zsh/Bash: choose Git branch and switch
fbr() {
  local branch
  branch=$(git for-each-ref --format='%(refname:short)' refs/heads |
    fzf --scheme=path --prompt='branch › ' \
      --preview='git log --color=always --oneline --decorate -20 {}') || return
  git switch -- "$branch"
}

Function owns source, UI, cancel branch, and effect. Easier to test than dense alias; avoids global side effects.

15. Practical recipes

fzf --multi \
  --preview='bat --color=always --style=numbers --line-range=:300 -- {}' \
  --bind='enter:become(${EDITOR:-vi} -- {+})'

cdir() {
  local dir
  dir=$(find . -type d -not -path '*/.git/*' |
    fzf --scheme=path --preview='ls -la -- {}') || return
  cd -- "$dir" || return
}

branch=$(git for-each-ref --sort=-committerdate \
  --format='%(refname:short)\t%(committerdate:relative)\t%(subject)' refs/heads |
  fzf --delimiter=$'\t' --with-nth=1,2,3 --accept-nth=1 \
    --preview='git log --color=always --oneline --decorate -30 {1}') || exit
git switch -- "$branch"

git log --color=always --format='%C(yellow)%h%Creset %C(cyan)%ad%Creset %s%C(auto)%d' --date=short |
  fzf --ansi --no-sort --scheme=history \
    --preview='git show --color=always {1}' \
    --bind='enter:become(git show --color=always {1} | less -R)'

rg --column --line-number --no-heading --color=always --smart-case . |
  fzf --ansi --delimiter=: \
    --preview='bat --color=always --highlight-line {2} -- {1}' \
    --preview-window='right,60%,+{2}/2' \
    --bind='enter:become(${EDITOR:-vi} +{2} -- {1})'

pid=$(ps -eo pid,user,%cpu,%mem,command |
  fzf --header-lines=1 --layout=reverse --prompt='process › ' \
    --preview='ps -p {1} -o pid,ppid,user,%cpu,%mem,lstart,command' \
    --accept-nth=1) || exit
kill -TERM "$pid"

name=$(env | cut -d= -f1 | sort | fzf --prompt='env › ') || exit
printf '%s=%s\n' "$name" "${!name}"  # Bash indirect expansion

id=$(docker ps --format '{{.ID}}\t{{.Names}}\t{{.Image}}\t{{.Status}}' |
  fzf --delimiter=$'\t' --with-nth=2.. --accept-nth=1 \
    --preview='docker logs --tail 100 {1} 2>&1') || exit
docker exec -it "$id" sh

# Function so cd affects your shell and `return` is valid
zd() {
  local dir
  dir=$(zoxide query --list |
    fzf --scheme=path --preview='ls -la -- {}') || return
  cd -- "$dir" || return
}

printf '%s\n' src/app.ts src/app.test.ts docs/api.md |
  fzf --filter='app !test'
# suitable for assertions; exits 1 when nothing matches

16. Safety, quoting, and portability

Common unsafe shape

# Fragile: word splitting, option injection, cancel ambiguity
rm $(find . -type f | fzf --multi)

# Safer: NUL records + explicit loop + --
find . -type f -print0 | fzf --read0 --print0 --multi |
  while IFS= read -r -d '' path; do
    printf 'would remove: %q\n' "$path"  # review first
  done

Portability notes

• macOS ships BSD tools; GNU-only flags may fail. sed -n, find -print0, and quoted shell loops travel better—but BSD sed rejects -- end-of-options, so omit it there.
• bat, fd, rg, tree, zoxide are optional companions, not fzf requirements.
• Action commands run through $SHELL -c on Unix. Script snippets needing Bash should declare Bash.
• Terminal key encodings vary; some Ctrl/modified bindings cannot be distinguished.

17. Performance and large/streaming inputs

• Stream early. fzf begins rendering before producer finishes unless --sync.
• Let specialized search tools search. Use ripgrep for file contents; fzf for interactive narrowing.
• Bound infinite streams. --tail=100000 --tac --no-sort --exact limits memory and shows newest records first.
• Keep previews cheap. Limit lines; avoid repeated network/API calls on focus.
• Avoid unnecessary transforms. --with-nth retains original lines and increases memory use.
• Choose algorithm only with evidence. Default v2 optimizes ranking; --algo=v1 trades optimal scoring for speed.

# Follow logs, retain latest 100k records
tail -f app.log |
  fzf --tail=100000 --tac --no-sort --exact \
    --preview-window='down,40%,follow' --preview='printf "%s\n" {}'

18. Troubleshooting

Debug in layers

1. Run producer alone. Confirm records and delimiters.
2. Pipe into plain fzf. Confirm matching/selection.
3. Add display/field options. Confirm accepted output using | od -c or | sed -n l.
4. Add preview. Replace command temporarily with printf '%s\n' {}.
5. Add bindings one at a time.
6. Add final effect only after inspecting exact emitted value.

19. Exercises: build fluency

if color=$(printf '%s\n' red orange yellow green blue indigo violet black | fzf); then
  printf 'You chose %s.\n' "$color"
fi

20. Retrieval quiz

Answer aloud before revealing. Mark honestly; score persists locally in this browser.

21. One-page cheat sheet

# Universal starting pattern
choice=$(producer | fzf --prompt='choose › ' --preview='inspect {}') || exit
consumer -- "$choice"

22. Sources and version note

This guide prioritizes installed fzf 0.74.2 help/man page, then official project documentation. Features differ across releases; use local fzf --man as authority for installed binary.

• Official fzf repository and README — installation, shell integration, core examples.
• Official advanced examples — reloads, ripgrep, previews, Git and process workflows.
• Official changelog — feature/version history.
• fzf --help and fzf --man — option, action, event, environment, placeholder, and exit-status semantics for local 0.74.2 binary.

Guide examples target POSIX-ish shell where practical and label Bash/Zsh assumptions. Optional tools: ripgrep (rg), bat, fd, tree, zoxide, Git, Docker.

Printed from local fzf field guide.