fzf.fish 🔍🐟

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

About this repository

This is a (personal) fork of PatrickF1/fzf.fish where the following functions added:

• __fzf_search_docker_container.fish
• __fzf_search_docker_image.fish
• __fzf_search_ghq.fish
• __fzf_search_git_branch.fish
• __fzf_search_git_tag.fish
• __fzf_search_process.fish
• __fzf_search_z.fish

Features

Use fzf.fish to interactively find and insert different shell entities into the command line:

File paths

• Search input: recursive listing of current directory's non-hidden files
• Key binding and mnemonic: Ctrl+Alt+F (F for file)
• Preview window: file with syntax highlighting, directory contents, or file type
• Remarks
  • prepends ./ to the selection if only one selection is made and it becomes the only token on the command line, making it easy to execute if an executable, or cd into if a directory (see cd docs)
  • 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
  • Tab to multi-select

Modified paths

• Search input: the current repository's git status
• Key binding and mnemonic: Ctrl+Alt+S (S for status)
• Remarks: Tab to multi-select

A commit hash

• Search input: the current repository's formatted git log
• Key binding and mnemonic: Ctrl+Alt+L (L for log)
• Preview window: commit message and diff

A previously run command

• Search input: the command history from all interactive sessions of Fish
• Key binding and mnemonic: Ctrl+R (R for reverse-i-search)
• Preview window: the entire command, wrapped

A shell variable

• Search input: all the variable names of the environment currently in scope
• Key binding and mnemonic: Ctrl+V (V for variable)
• Preview window: the scope info and values of the variable
• Remarks
  • $history is excluded for technical reasons so use the search command history feature instead to inspect it

The prompt used in the screencasts was created using IlanCosman/tide.

Installation

First, install a proper version of these CLIs:

CLI	Minimum version required	Description
fish	3.2.0	a modern shell
fzf	0.27.2	command-line fuzzy finder that powers this plugin
fd	7.5.0	much faster and friendlier alternative to find
bat	0.16.0	smarter cat with syntax highlighting

On certain distribution of Linux, you need to alias fdfind to fd (see #93).

Next, 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 a convenient wrapper for configuring its key bindings. It is flexible, has no learning curve, and is thoroughly documented. See

fzf_configure_bindings --help

Play around with it--it's safe to repeatedly execute in the same fish session without residual bindings or other side effects. Once you're done, add the fzf_configure_bindings command that works for you to your config.fish in order to persist the bindings.

Pass fzf options to all commands

fzf supports setting default options via the FZF_DEFAULT_OPTS environment variable. If it is set, fzf implicitly prepends it to the options passed to it on every execution, scripted and interactive.

To make fzf's interface friendlier, fzf.fish takes the liberty of setting a sane FZF_DEFAULT_OPTS if it is not already set. See conf.d/fzf.fish for more details. This affects fzf even outside of this plugin. If you would like to remove this side effect or just want to customize fzf's default options, then set export your own FZF_DEFAULT_OPTS variable. For example:

set --export FZF_DEFAULT_OPTS --height 50% --no-extended +i

Pass fzf options to a specific command

The following variables can store custom options that will be passed to fzf by their respective feature:

Feature	Variable
Search directory	fzf_dir_opts
Search git status	fzf_git_status_opts
Search git log	fzf_git_log_opts
Search command history	fzf_history_opts
Search shell variables	fzf_shell_vars_opts

They are always appended last to fzf's argument list. Because fzf uses the option appearing last when options conflict, your custom options can override hardcoded options. Custom fzf options unlocks a variety of possibilities in customizing and augmenting each feature such as:

• add key bindings within fzf to operate on the selected line:
  • open file in Vim
  • preview image files
  • copy to clipboard
  • git checkout commit
  • git reset file
• adjust the preview command or window
• re-populate fzf's input list on demand
• change the search mode

Change the command used to preview files

The search directory feature, by default, uses bat to preview the contents of files. bat is a well-adopted cat replacement with syntax highlighting, line numbers, and more. If you would like to change the preview tool (to cat to avoid installing a new dependency, or to add custom logic such as binary or image preview), you may set the fzf_preview_file_cmd variable. For example, in your config.fish, you may put:

set fzf_preview_file_cmd cat

Do not specify a target path in the command, as fzf.fish will prepend the file to preview to the command itself.

Change the command used to preview directories

The search directory feature, by default, uses ls to preview the contents of directories. To integrate with the variety of ls replacements available (e.g. exa, lsd, tree), the command used to preview directories is configurable through the fzf_preview_dir_cmd variable. Set fzf_preview_dir_cmd in your config.fish:

set fzf_preview_dir_cmd exa --all --color=always

As above, do not specify a target path in the command. fzf.fish will prepend the directory to preview to the command itself.

Change the files searched

To pass custom options to fd when it is executed to populate the list of files for the search directory feature, set the fzf_fd_opts variable. For example, to include hidden files but not .git, put this in your config.fish:

set fzf_fd_opts --hidden --exclude=.git

Change the key binding for a single command

See the Cookbook Wiki page.

Further reading

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

• How does fzf.fish compare to other popular fzf plugins for fish?
• Why isn't this feature working for me?
• How can I integrate this plugin into my workflow?
• How can I contribute to this plugin?