Unopinionated FZF for Fish 🐟

Welcome to fish-fzf, an unopinionated fzf functions for your Fish shell. Bind FZF to your workflow with ease in Fish. This plugin provides just the functions so you can map them into however you want to use it.

• _fzf_cmd_history - Command history search with fzf.
• _fzf_directory_picker - Directory picker with fzf.
• _fzf_file_picker - File picker with fzf.

fzf-demo.mp4

I don't like to have unused keymaps that comes with most plugins. That's why fish-fzf exists.

Roadmap

• New function for live grep
• Test suite

Installation

First, install a proper version of these CLI dependencies:

CLI	Description
fish	a modern shell
fzf	fuzzy finder that powers this plugin
fd	faster, colorized alternative to find
bat	smarter cat with syntax highlighting

Using Nix's Home Manager (Recommended)

{
    programs.fish = {
        enable = true;
        plugins = [
            {
                name = "fish-fzf";
                src = pkgs.fetchFromGitHub {
                    owner = "y3owk1n";
                    repo = "fish-fzf";
                    rev = "v1.0.0";
                    sha256 = "generated-sha-256-values";
                };
            }
        ];
    };
}

Using Fisher

fisher install y3owk1n/fish-fzf

Manually

1. Clone this repository:

git clone https://github.com/y3owk1n/fish-fzf.git

2. Source the all the functions/*.fish file in your Fish configuration:

source /path/to/_fzf_cmd_history.fish
source /path/to/_fzf_directory_picker.fish
source /path/to/_fzf_file_picker.fish
source /path/to/_fzf_preview_cmd.fish
source /path/to/_fzf_preview_name.fish

Features

1. Command History Search

• Search and select commands from your command history using fzf.
• Replace the current command line with the selected command.
• Optionally, execute the selected command immediately.

Usage

_fzf_cmd_history [--allow-execute] [--prompt-name <custom_prompt>]

• --allow-execute (optional) - Execute the selected command immediately on select.
• --prompt-name (optional) - Custom prompt to display in fzf.

2. Directory Picker

• Navigate and select directories using fzf.
• Optionally, change the current directory or replace the current token with the selected directory path.
• Supports recursive depth and custom prompts.

Usage

_fzf_directory_picker [--allow-cd] [--recursive-depth <depth>] [--prompt-name <custom_prompt>]  [path]

• --allow-cd (optional) - Change the current directory using the selected directory path.
• --recursive-depth (optional) - Depth to recursively search for directories. Defaults to 1.
• --prompt-name (optional) - Custom prompt to display in fzf.
• path (optional) - Directory path to start in. Defaults to '.'

3. File Picker

• Browse and select files and directories using fzf.
• By default, it respects .gitignore and you can turn --show-hidden-files for searching all files.
• Optionally, open the selected file in your preferred editor or replace the current token with the selected file path.
• Supports showing hidden files, custom prompts, and opening in the editor.

Usage

_fzf_file_picker [--allow-open-in-editor]  [--show-hidden-files] [--prompt-name <custom_prompt>] [path]

• --allow-open-in-editor (optional) - Open the selected file in your preferred editor.
• --show-hidden-files (optional) - Show hidden files.
• --prompt-name (optional) - Custom prompt to display in fzf.
• path (optional) - File path to start in. Defaults to '.'

Notes

Before using --allow-open-in-editor, ensure that your preferred editor is set in the $EDITOR environment variable. You can set it using:

set -Ux EDITOR nvim # vim, code, emacs, etc.

Customization

You can customize prompts and behaviors using command-line options.

Add these functions to your Fish configuration file to tailor them to your preferences.

Examples

Command History

_fzf_cmd_history --allow-execute --prompt-name "Custom Prompt" 

Directory Picker

_fzf_directory_picker --allow-cd --recursive-depth 2 --prompt-name "Choose Directory" /path/to/start

File Picker

_fzf_file_picker --allow-open-in-editor --show-hidden-files --prompt-name "Select File" /path/to/start

Remember, these are just functions in fish shell. You can do whatever you want with them.

Make an alias / abbr and execute them on the fly

Abbr (I'm using this method)

# ~/.config/fish/config.fish

abbr --add --global -- fpc '_fzf_cmd_history --allow-execute' # Open up command history picker and allow execute on select.
abbr --add --global -- fpf '_fzf_file_picker --allow-open-in-editor --prompt-name Files' # Open up file picker in current directory, change the prompt name to 'Files' and open in editor on select.
abbr --add --global -- fpfh '_fzf_file_picker --allow-open-in-editor --show-hidden-files --prompt-name Files+' # Same as above but show hidden files.
abbr --add --global -- fpp '_fzf_directory_picker --allow-cd --prompt-name Projects ~/Dev/' # Open up directory picker in ~/Dev/ with default 1 level of recursive-depth and auto cd on select.

Alias

# ~/.config/fish/config.fish

alias fpc '_fzf_cmd_history --allow-execute'
alias fpf '_fzf_file_picker --allow-open-in-editor --prompt-name Files'
alias fpfh '_fzf_file_picker --allow-open-in-editor --show-hidden-files --prompt-name Files+'
alias fpp '_fzf_directory_picker --allow-cd --prompt-name Projects ~/Dev/'

Bind it with fish key bindings

# ~/.config/fish/functions/fish_user_key_bindings.fish

function fish_user_key_bindings
    bind \cg '_fzf_cmd_history --allow-execute'
    bind -M insert \cg `_fzf_cmd_history --allow-execute`
end

Troubleshooting

If you encounter any issues or errors, please refer to the troubleshooting section in the wiki (Not ready yet).

Contributions

Feel free to contribute by opening issues, suggesting enhancements, or submitting pull requests. We value your feedback and ideas to enhance the capabilities of fish-fzf further!

License

This plugin is licensed under the MIT License. Feel free to use, modify, and distribute it as you see fit.

Happy fishing! 🐟