fzf

What this skill does

# 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, fish, and Nushell

## 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
```

**Version note:** This skill is documented against **fzf 0.73.x**. The `fzf --bash`/`--zsh`/`--fish` integration flags require **fzf ≥0.48**, `--nushell` requires **≥0.73**, and `--tmux`/`--popup` are newer still. For the version that introduced any specific feature, see [references/version-features.md](references/version-features.md).

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

# Nushell (fzf 0.73+) — write to a Nushell autoload dir
fzf --nushell | save -f ($nu.user-autoload-dirs | first | path join "_fzf_integration.nu")
```

The `--bash`/`--zsh`/`--fish` flags require **fzf ≥0.48**; `--nushell` requires **fzf ≥0.73**.

### 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 between the cleaned and raw history line (`toggle-raw`, fzf 0.66+)
- 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 (fzf 0.53+)

```bash
# Open in tmux popup (requires tmux 3.3+ or Zellij 0.44+)
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
```

In fzf 0.71+, `--popup` is the newer name (it also targets Zellij floating panes); `--tmux` still works as an alias.

## 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
# Default is smart-case: case-insensitive until the query
# contains an uppercase letter, then case-sensitive.
-e, --exact            # Exact match (disable fuzzy)
-i                     # Force case-insensitive (override smart-case)
+i                     # Force case-sensitive (override smart-case)
--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 (fzf 0.38+) |
| `execute(cmd)` | Run command, return to fzf |
| `execute-silent(c