Augment your Fish command line with mnemonic key bindings to efficiently find what you need using fzf.
Features
Use fzf.fish
to interactively find and insert the shell entities listed below into your command line. All searches--except for searching for a command--allow Tabing to multi-select. And if you trigger a search while your command line cursor is touching a word, that word will be used to seed the fzf query and will be replaced by your selection. Almost all searches include a preview of the entity hovered over so you can seamlessly determine what you need. Or, you can use the previews as an inspection tool.
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
- appends
/
if the selection is a directory and the only path selected so you can hit ENTER to immediately 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
- appends
Modified paths
- Search input: the current repository's
git status
- Key binding and mnemonic: Ctrl+Alt+S (
S
for status)
Commit hashes
- 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: Fish's command history
- Key binding and mnemonic: Ctrl+R (
R
for reverse-i-search) - Preview window: the entire command with Fish syntax highlighting
Shell variables
- 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
$history
is excluded for technical reasons so use the search command history feature instead to inspect it
Process ids
- Search input: the pid and command of all running processes, outputted by
ps
- Key binding and mnemonic: Ctrl+Alt+P (
P
for process) - Preview window: the CPU usage, memory usage, start time, and other information about the process
The prompt used in the screencasts was created using IlanCosman/tide.
Installation
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 | 7.5.0 | faster and more colorful alternative to find |
bat | 0.16.0 | smarter cat with syntax highlighting |
The search directory feature uses fd and bat to list and preview files. If your package manager doesn't install them as fd
and bat
respectively, then you can symlink them to those names.
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 an ergonomic wrapper for configuring its key bindings. Read its documentation with this command:
fzf_configure_bindings --help
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 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.
By default, fzf.fish
will set a sane FZF_DEFAULT_OPTS
every time before it executes fzf. However, if you export your own FZF_DEFAULT_OPTS
variable, then fzf.fish
will forgo setting it and yours will be used instead. See functions/_fzf_wrapper.fish for more details.
Pass fzf options for a specific feature
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 |
Search processes | fzf_processes_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 commands used to preview directories and regular files
The search directory feature, by default, calls ls
to preview directories and bat
to preview regular files.
To change the directory preview command (e.g. to use one of the many ls
replacements such as exa
), set the command in the fzf_preview_dir_cmd
variable:
set fzf_preview_dir_cmd exa --all --color=always
And to change the file preview command (e.g. to cat
to avoid installing a new dependency, or to add custom logic such as image preview), set the command in the fzf_preview_file_cmd
variable:
set fzf_preview_file_cmd cat
Omit the target path for both variables as fzf.fish
will itself specify the target to preview.
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
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 customize this feature?
- How can I contribute to this plugin?