Augment your Fish command line with mnemonic key bindings to efficiently find what you need using fzf.
fzf.fish to interactively find and insert file paths, git commit hashes, and other entities into your command line. Tab 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
- Fzf input: recursive listing of current directory's non-hidden files
- Output: relative paths of selected files
- Key binding and mnemonic: Ctrl+Alt+F (
- Preview window: file with syntax highlighting, directory contents, or file type
- directories are inserted with a trailing
/, so if you select exactly one directory, you can immediately hit ENTER to cd into it
- if the current token is a directory with a trailing slash (e.g.
.config/<CURSOR>), then that directory is searched instead
- ignores files that are also ignored by git
- directories are inserted with a trailing
🪵 Search Git Log
- Fzf input: the current repository's formatted
- Output: hashes of selected commits
- Key binding and mnemonic: Ctrl+Alt+L (
- Preview window: commit message and diff
📝 Search Git Status
- Fzf input: the current repository's
- Output: relative paths of selected lines
- Key binding and mnemonic: Ctrl+Alt+S (
- Preview window: the git diff of the file
📜 Search History
- Fzf input: Fish's command history
- Output: selected commands
- Key binding and mnemonic: Ctrl+R (
- Preview window: the entire command with Fish syntax highlighting
🖥️ Search Processes
- Fzf input: the pid and command of all running processes, outputted by
- Output: pids of selected processes
- Key binding and mnemonic: Ctrl+Alt+P (
- Preview window: the CPU usage, memory usage, start time, and other information about the process
💲 Search Variables
- Fzf input: all the shell variables currently in scope
- Output: selected shell variables
- Key binding and mnemonic: Ctrl+V (
- Preview window: the variable's scope info and values
$historyis excluded for technical reasons so use Search History instead to inspect it
First, install a proper version of these CLI dependencies:
|CLI||Minimum version required||Description|
|fish||3.2.0||a modern shell|
|fzf||0.27.2||fuzzy finder that powers this plugin|
|fd||8.5.0||faster, colorized alternative to
fd and bat only need to be installed if you will use Search Directory.
fzf.fish is incompatible with other fzf plugins, check for and remove these two common alternatives.
Finally, install this plugin with Fisher.
fzf.fishcan be installed manually or with other plugin managers but only Fisher is officially supported.
fisher install PatrickF1/fzf.fish
Customize key bindings
fzf.fish includes an ergonomic wrapper for configuring its key bindings. Read its documentation with this command:
Once you've determined the desired
fzf_configure_bindings command, add it to your
config.fish in order to persist the bindings.
Always pass some options to fzf
fzf supports global default options via the FZF_DEFAULT_OPTS environment variable. If set, fzf implicitly prepends its value to the options it receives on every execution, scripted and interactive.
fzf.fish locally sets a sane
FZF_DEFAULT_OPTS whenever it executes fzf. If you export your own
FZF_DEFAULT_OPTS, then yours will be used instead.
Pass fzf options for a specific command
The following variables can store custom options that will be passed to fzf by their respective command:
|Search Git Log||
|Search Git Status||
They are appended last to fzf's options list. Because fzf uses the last instance of an option if it is specified multiple times, custom options will always take precedence. Custom fzf options unlock a variety of customizations and augmentations such as:
- add key bindings within fzf to operate on the selected line:
- open file in Vim
- preview image files
- git reset file
- adjust the preview command or window
- re-populate fzf's input list on demand
- change the search mode
Find more ideas and implementation tips in the Cookbook.
Change how Search Directory previews directories and regular files
Search Directory, by default, calls
ls to preview directories and
bat to preview regular files.
To use your own directory preview command (e.g. to use one of the many
ls replacements such as
exa), set it in
set fzf_preview_dir_cmd exa --all --color=always
And to use your own file preview command (e.g. to
cat to avoid having to install
bat, or to add logic for previewing images), set it in
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 in Search Directory
To pass custom options to
fd when it is executed to populate the list of files for Search Directory, set them in
fzf_fd_opts. For example, this includes hidden files but not
set fzf_fd_opts --hidden --exclude=.git
fd hides files listed in
.gitignore. You can disable this behavior by adding the
--no-ignore flag to
Change the commit formatting used by Search Git Log
Search Git Log calls
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.
Find answers to these questions and more in the project Wiki:
- How does
fzf.fishcompare to other popular fzf plugins for Fish?
- Why isn't this command working?
- How can I customize this command?
- How can I contribute to this plugin?