Skip to content

PatrickF1/fzf.fish

main
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

Make the header box for Git staged/unstaged/merged/etc. look nicer.
Old:
+--------+
| Staged |
+--------+
New:
โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ
โ”‚ Staged โ”‚
โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ
63c8f8e

Git stats

Files

Permalink
Failed to load latest commit information.

fzf.fish ๐Ÿ”๐ŸŸ

latest release badge build status badge awesome badge

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

Search commands

Use 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

Search Directory example

  • Fzf input: recursive listing of current directory's non-hidden files
  • Output: relative paths of selected files
  • Key binding and mnemonic: Ctrl+Alt+F (F for file)
  • Preview window: file with syntax highlighting, directory contents, or file type
  • Remarks
    • 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

๐Ÿชต Search Git Log

Search Git Log example

  • Fzf input: the current repository's formatted git log
  • Output: hashes of selected commits
  • Key binding and mnemonic: Ctrl+Alt+L (L for log)
  • Preview window: commit message and diff

๐Ÿ“ Search Git Status

Search Git Status example

  • Fzf input: the current repository's git status
  • Output: relative paths of selected lines
  • Key binding and mnemonic: Ctrl+Alt+S (S for status)
  • Preview window: the git diff of the file

๐Ÿ“œ Search History

Search History example

  • Fzf input: Fish's command history
  • Output: selected commands
  • Key binding and mnemonic: Ctrl+R (R for reverse-i-search)
  • Preview window: the entire command with Fish syntax highlighting

๐Ÿ–ฅ๏ธ Search Processes

Search Processes example

  • Fzf input: the pid and command of all running processes, outputted by ps
  • Output: pids of selected processes
  • 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

๐Ÿ’ฒ Search Variables

Search Variables example

  • Fzf input: all the shell variables currently in scope
  • Output: selected shell variables
  • Key binding and mnemonic: Ctrl+V (V for variable)
  • Preview window: the variable's scope info and values
  • $history is excluded for technical reasons so use Search History instead to inspect it

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 8.5.0 faster, colorized alternative to find
bat 0.16.0 smarter 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 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 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:

Command Variable
Search Directory fzf_directory_opts
Search Git Log fzf_git_log_opts
Search Git Status fzf_git_status_opts
Search History fzf_history_opts
Search Processes fzf_processes_opts
Search Variables fzf_variables_opts

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:

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 fzf_preview_dir_cmd:

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 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 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 .git:

set fzf_fd_opts --hidden --exclude=.git

By default, fd hides files listed in .gitignore. You can disable this behavior by adding the --no-ignore flag to fzf_fd_opts.

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.

Further reading

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