Home

Awesome

<div align="center">

fzf.fish 🔍🐟

latest release badge build status badge awesome badge

</div>

Augment your Fish command line with mnemonic key bindings to efficiently find what you need using fzf.

https://user-images.githubusercontent.com/1967248/197308919-51d04602-2d5f-46aa-a96e-6cf1617e3067.mov

Search commands

Use fzf.fish to interactively find and insert file paths, git commit hashes, and other entities into your command line. <kbd>Tab</kbd> to select multiple entries. If you trigger a search while your cursor is on a word, that word will be used to seed the fzf query and will be replaced by your selection. All searches include a preview of the entity hovered over to help you find what you're looking for.

📁 Search Directory

Search Directory example

🪵 Search Git Log

Search Git Log example

📝 Search Git Status

Search Git Status example

📜 Search History

Search History example

🖥️ Search Processes

Search Processes example

💲 Search Variables

Search Variables example

Installation

First, install a proper version of these CLI dependencies:

CLIMinimum version requiredDescription
fish3.4.0a modern shell
fzf0.33.0fuzzy finder that powers this plugin
fd8.5.0faster, colorized alternative to find
bat0.16.0smarter cat with syntax highlighting

fd and bat only need to be installed if you will use Search Directory.

Next, because fzf.fish is incompatible with other fzf plugins, check for and remove these two common alternatives.

Finally, install this plugin with Fisher.

fzf.fish can be installed manually or with other plugin managers but only Fisher is officially supported.

fisher install PatrickF1/fzf.fish

Configuration

Customize key bindings

fzf.fish includes an ergonomic function for configuring its key bindings. Read its documentation:

fzf_configure_bindings --help

Call fzf_configure_bindings in your config.fish in order to persist your custom bindings.

Change fzf options for all commands

fzf supports global default options via the FZF_DEFAULT_OPTS and FZF_DEFAULT_OPTS_FILE environment variables. If neither are set, fzf.fish sets its own default opts whenever it executes fzf.

Change fzf options for a specific command

Each command's fzf options can be configured via a variable:

CommandVariable
Search Directoryfzf_directory_opts
Search Git Logfzf_git_log_opts
Search Git Statusfzf_git_status_opts
Search Historyfzf_history_opts
Search Processesfzf_processes_opts
Search Variablesfzf_variables_opts

The value of each variable is appended last to fzf's options list. Because fzf uses the last instance of an option if it is specified multiple times, custom options take precedence. Custom fzf options unlock a variety of augmentations:

Find more ideas and tips in the Cookbook.

Change how Search Directory previews directories and regular files

Search Directory, by default, executes ls to preview directories and bat to preview regular files.

To use your own directory preview command, set it in fzf_preview_dir_cmd:

set fzf_preview_dir_cmd eza --all --color=always

And to use your own file preview command, set it in fzf_preview_file_cmd:

set fzf_preview_file_cmd cat -n

Omit the target path for both variables as fzf.fish will itself specify the argument to preview.

Change what files are listed by Search Directory

To pass custom options to fd when Search Directory executes it to populate the list of files, set them in fzf_fd_opts:

set fzf_fd_opts --hidden --max-depth 5

<a id='fd-gi'></a>By default, fd hides files listed in .gitignore. You can disable this behavior by adding the --no-ignore flag to fzf_fd_opts.

Change Search Git Log's commit formatting

Search Git Log executes git log --format to format the list of commits. To use your own commit log format, set it in fzf_git_log_format. For example, this shows the hash and subject for each commit:

set fzf_git_log_format "%H %s"

The format must be one line per commit and the hash must be the first field, or else Search Git Log will fail to determine which commits you selected.

Integrate with a diff highlighter

To pipe the git diff previews from Search Git Log and Search Git Status through a highlighter tool (e.g. delta or diff-so-fancy), set a command invoking the highlighter in fzf_diff_highlighter. It should not pipe its output to a pager:

# width=20 so delta decorations don't wrap around small fzf preview pane
set fzf_diff_highlighter delta --paging=never --width=20
# Or, if using DFS
set fzf_diff_highlighter diff-so-fancy

Change Search History's date time format

Search History shows the date time each command was executed. To change how its formatted, set your strftime format string in fzf_history_time_format. For example, this shows the date time as DD-MM-YY:

set fzf_history_time_format %d-%m-%y

Do not to include the vertical box-drawing character (not to be confused with the pipe character |) as it is relied on to delineate the date time from the command.

Further reading

Find answers to these questions and more in the project Wiki: