fzf - Command-Line Fuzzy Finder

Overview

fzf is a general-purpose command-line fuzzy finder. It reads a list of items from STDIN, allows interactive selection using fuzzy matching, and outputs the selected item(s) to STDOUT. Think of it as an interactive grep.

Key characteristics:

•Fast: Processes millions of items instantly
•Portable: Single binary, works everywhere
•Versatile: Customizable via event-action binding mechanism
•Integrated: Built-in shell integrations for bash, zsh, and fish

When to Use This Skill

Use fzf when:

•Selecting files interactively: vim $(fzf) or fuzzy completion with **<TAB>
•Searching command history: CTRL-R for fuzzy history search
•Navigating directories: ALT-C to cd into selected directory
•Building interactive scripts: Create selection menus for any list
•Filtering output: Pipe any command output through fzf
•Integrating with other tools: ripgrep, fd, git, etc.

Prerequisites

CRITICAL: Before proceeding, you MUST verify that fzf is installed:

bash

fzf --version

If fzf is not installed:

•DO NOT attempt to install it automatically
•STOP and inform the user that fzf is required
•RECOMMEND manual installation with the following instructions:

bash

# macOS
brew install fzf

# Debian/Ubuntu
sudo apt install fzf

# Arch Linux
sudo pacman -S fzf

# From source
git clone --depth 1 https://github.com/junegunn/fzf.git ~/.fzf
~/.fzf/install

# Other systems: see https://github.com/junegunn/fzf#installation

If fzf is not available, exit gracefully and do not proceed with the workflow below.

Shell Integration

fzf provides shell integration that enables powerful keybindings (CTRL-T, CTRL-R, ALT-C) and fuzzy completion (**<TAB>). These features require the user to configure their shell.

Note: Shell integration setup is the user's responsibility. If keybindings don't work, RECOMMEND the user add the appropriate line to their shell config:

bash

# Bash (~/.bashrc)
eval "$(fzf --bash)"

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

# Fish (~/.config/fish/config.fish)
fzf --fish | source

Key Bindings (requires shell integration)

Key	Function	Description
`CTRL-T`	File selection	Paste selected files/directories onto command line
`CTRL-R`	History search	Fuzzy search command history
`ALT-C`	Directory jump	cd into selected directory

CTRL-R extras:

•Press CTRL-R again to toggle sort by relevance
•Press ALT-R to toggle raw mode (see surrounding items)
•Press CTRL-/ or ALT-/ to toggle line wrapping

Fuzzy Completion (`**<TAB>`)

Trigger fuzzy completion with ** followed by TAB:

bash

# Files under current directory
vim **<TAB>

# Files under specific directory
vim ../fzf**<TAB>

# Directories only
cd **<TAB>

# Process IDs (for kill)
kill -9 **<TAB>

# SSH hostnames
ssh **<TAB>

# Environment variables
export **<TAB>

Search Syntax

fzf uses extended-search mode by default. Multiple search terms are separated by spaces.

Token	Match Type	Description
`sbtrkt`	Fuzzy match	Items matching `sbtrkt`
`'wild`	Exact match	Items containing `wild` exactly
`'wild'`	Exact boundary	Items with `wild` at word boundaries
`^music`	Prefix match	Items starting with `music`
`.mp3$`	Suffix match	Items ending with `.mp3`
`!fire`	Inverse match	Items NOT containing `fire`
`!^music`	Inverse prefix	Items NOT starting with `music`
`!.mp3$`	Inverse suffix	Items NOT ending with `.mp3`

OR operator: Use | to match any of several patterns:

bash

# Files starting with 'core' and ending with go, rb, or py
^core go$ | rb$ | py$

Escape spaces: Use \ to match literal space characters.

Basic Usage

Simple Selection

bash

# Select a file and open in vim
vim $(fzf)

# Safer with xargs (handles spaces, cancellation)
fzf --print0 | xargs -0 -o vim

# Using become() action (best approach)
fzf --bind 'enter:become(vim {})'

Multi-Select

bash

# Enable multi-select with -m
fzf -m

# Select with TAB, deselect with Shift-TAB
# Selected items printed on separate lines

Preview Window

bash

# Basic preview
fzf --preview 'cat {}'

# With syntax highlighting (requires bat)
fzf --preview 'bat --color=always {}'

# Customize preview window position/size
fzf --preview 'cat {}' --preview-window=right,50%
fzf --preview 'cat {}' --preview-window=up,40%,border-bottom

Display Modes

Height Mode

bash

# Use 40% of terminal height
fzf --height 40%

# Adaptive height (shrinks for small lists)
seq 5 | fzf --height ~100%

# With layout options
fzf --height 40% --layout reverse --border

tmux Mode

bash

# Open in tmux popup (requires tmux 3.3+)
fzf --tmux center         # Center, 50% width/height
fzf --tmux 80%            # Center, 80% width/height
fzf --tmux left,40%       # Left side, 40% width
fzf --tmux bottom,30%     # Bottom, 30% height

Essential Options

Layout and Appearance

bash

--height=HEIGHT[%]     # Non-fullscreen mode
--layout=reverse       # Display from top (default: bottom)
--border[=STYLE]       # rounded, sharp, bold, double, block
--margin=MARGIN        # Margin around finder
--padding=PADDING      # Padding inside border
--info=STYLE           # default, inline, hidden

Search Behavior

bash

-e, --exact            # Exact match (disable fuzzy)
-i                     # Case-insensitive
+i                     # Case-sensitive
--scheme=SCHEME        # default, path, history
--algo=TYPE            # v2 (quality), v1 (performance)

Input/Output

bash

-m, --multi            # Enable multi-select
--read0                # Read NUL-delimited input
--print0               # Print NUL-delimited output
--ansi                 # Enable ANSI color processing

Field Processing

bash

--delimiter=STR        # Field delimiter (default: AWK-style)
--nth=N[,..]           # Limit search to specific fields
--with-nth=N[,..]      # Transform display of each line

Event Bindings

Customize behavior with --bind:

bash

# Basic syntax
fzf --bind 'KEY:ACTION'
fzf --bind 'EVENT:ACTION'
fzf --bind 'KEY:ACTION1+ACTION2'  # Chain actions

# Examples
fzf --bind 'ctrl-a:select-all'
fzf --bind 'ctrl-d:deselect-all'
fzf --bind 'ctrl-/:toggle-preview'
fzf --bind 'enter:become(vim {})'

Key Actions (Selection)

Action	Description
`accept`	Accept current selection
`abort`	Abort and exit
`toggle`	Toggle selection of current item
`select-all`	Select all matches
`deselect-all`	Deselect all
`toggle-all`	Toggle all selections

Useful Actions

Action	Description
`reload(cmd)`	Reload list from command
`become(cmd)`	Replace fzf with command
`execute(cmd)`	Run command, return to fzf
`execute-silent(cmd)`	Run command silently
`preview(cmd)`	Change preview command
`toggle-preview`	Show/hide preview
`change-prompt(str)`	Change prompt string

Events

Event	Triggered When
`start`	fzf starts
`load`	Input loading completes
`change`	Query string changes
`focus`	Focused item changes
`result`	Result list updates

For complete action reference, see references/actions.md.

Environment Variables

Core Configuration

bash

# Default command when input is TTY
export FZF_DEFAULT_COMMAND='fd --type f --hidden --follow --exclude .git'

# Default options (applied to all fzf invocations)
export FZF_DEFAULT_OPTS='--height 40% --layout reverse --border'

# Options file (alternative to FZF_DEFAULT_OPTS)
export FZF_DEFAULT_OPTS_FILE=~/.fzfrc

Shell Integration Variables

bash

# CTRL-T options
export FZF_CTRL_T_COMMAND="fd --type f"
export FZF_CTRL_T_OPTS="--preview 'bat --color=always {}'"

# CTRL-R options
export FZF_CTRL_R_OPTS="--bind 'ctrl-y:execute-silent(echo -n {2..} | pbcopy)+abort'"

# ALT-C options
export FZF_ALT_C_COMMAND="fd --type d"
export FZF_ALT_C_OPTS="--preview 'tree -C {}'"

Completion Customization

bash

# Change trigger sequence (default: **)
export FZF_COMPLETION_TRIGGER='~~'

# Completion options
export FZF_COMPLETION_OPTS='--border --info=inline'

Common Patterns

Find and Edit Files

bash

# Using fd for better performance
fd --type f | fzf --preview 'bat --color=always {}' | xargs -o vim

# Or with become()
fd --type f | fzf --preview 'bat --color=always {}' --bind 'enter:become(vim {})'

Search File Contents (with ripgrep)

bash

# Basic ripgrep integration
rg --line-number . | fzf --delimiter : --preview 'bat --color=always {1} --highlight-line {2}'

# Open result in vim at line
rg --line-number . | fzf --delimiter : --bind 'enter:become(vim {1} +{2})'

Git Integration

bash

# Select git branch
git branch | fzf | xargs git checkout

# Select commit
git log --oneline | fzf --preview 'git show {1}' | cut -d' ' -f1

# Stage files interactively
git status -s | fzf -m | awk '{print $2}' | xargs git add

Dynamic List Reloading

bash

# Reload process list with CTRL-R
ps -ef | fzf --bind 'ctrl-r:reload(ps -ef)' --header 'Press CTRL-R to reload'

# Toggle between files and directories
fd | fzf --bind 'ctrl-d:reload(fd --type d)' --bind 'ctrl-f:reload(fd --type f)'

Interactive ripgrep Launcher

bash

# fzf as ripgrep frontend (search updates on typing)
RG_PREFIX="rg --column --line-number --no-heading --color=always"
fzf --ansi --disabled \
    --bind "start:reload:$RG_PREFIX ''" \
    --bind "change:reload:$RG_PREFIX {q} || true" \
    --bind 'enter:become(vim {1} +{2})' \
    --delimiter :

Placeholders

Use in --preview, --bind, etc.:

Placeholder	Description
`{}`	Current selection (quoted)
`{+}`	All selected items (space-separated)
`{q}`	Current query string
`{n}`	Zero-based index of current item
`{1}`, `{2}`, etc.	Nth field (with --delimiter)
`{-1}`	Last field
`{1..3}`	Fields 1 through 3
`{2..}`	Fields 2 to end

Flags:

•{+} - All selected items
•{f} - Write to temp file (for large lists)
•{r} - Raw (unquoted) output

Advanced Topics

For detailed documentation on advanced features, see:

•references/actions.md - Complete list of bindable actions
•references/options.md - Full options reference
•references/integrations.md - ripgrep, fd, git, bat integrations

Troubleshooting

"Command not found: fzf"

•fzf is not installed. See Prerequisites section for manual installation instructions
•Do NOT attempt automatic installation

Shell keybindings not working (CTRL-T, CTRL-R, ALT-C):

•Shell integration must be configured by the user
•RECOMMEND adding the appropriate line to shell config (see Shell Integration section)
•For bash, must be sourced after any PS1 modifications

Performance issues:

•Avoid --ansi in FZF_DEFAULT_OPTS (slows initial scan)
•Use --nth sparingly (requires tokenization)
•Prefer string --delimiter over regex

Preview not showing:

•Check preview command syntax
•Use {} placeholder for current selection
•Test preview command manually first

CTRL-R not finding old commands:

•fzf searches shell history, not history file
•Increase HISTSIZE and HISTFILESIZE

Resources

•Man page: man fzf or fzf --man
•Wiki examples: https://github.com/junegunn/fzf/wiki/examples
•Advanced examples: https://github.com/junegunn/fzf/blob/master/ADVANCED.md
•Theme playground: https://vitormv.github.io/fzf-themes/
•fzf-git.sh: https://github.com/junegunn/fzf-git.sh (git keybindings)

fzf - Command-Line Fuzzy Finder

Overview

When to Use This Skill

Prerequisites

Shell Integration

Key Bindings (requires shell integration)

Fuzzy Completion (**<TAB>)

Search Syntax

Basic Usage

Simple Selection

Multi-Select

Preview Window

Display Modes

Height Mode

tmux Mode

Essential Options

Layout and Appearance

Search Behavior

Input/Output

Field Processing

Event Bindings

Key Actions (Selection)

Useful Actions

Events

Environment Variables

Core Configuration

Shell Integration Variables

Completion Customization

Common Patterns

Find and Edit Files

Search File Contents (with ripgrep)

Git Integration

Dynamic List Reloading

Interactive ripgrep Launcher

Placeholders

Advanced Topics

Troubleshooting

Resources

Fuzzy Completion (`**<TAB>`)