v7.3

Changes

• [Search directory] Append / instead of prepending ./ for quick cd (#185). This is a lot more natural, more comprehensible, takes up less space, more fish-y (same as what happens when you autocomplete a directory), and should lead to less bugs around search directory in the future.
• Set SHELL and FZF_DEFAULT_OPTS in wrapper around fzf (#194). Before FZF_DEFAULT_OPTS was set in config.fish. By moving that code into an internal wrapper, we no longer dirty the shell environment and eliminate the side effect of changing fzf when it is executed outside the plugin.
• Mention removing fzf_configure_bindings from config when uninstalling (e0b0cbb)

v7.2

Major bug fix

Fix bind error messages appearing in non-interactive windows (#186). Sorry to everyone who had this issue and my delay in getting this fixed.

v7.1

Added

• Define command completions for fzf_configure_bindings (#177)
• Skip config if not in interactive mode, which makes non-interactive fish shells (such as those created by tide or fzf previews) faster (#180 - @kidonng )

Fixed

• Fix default key sequence docs in fzf_configure_bindings (#175 - @jonashaag )
• Make sure --variables flag has trailing 's' in docs (7ff05ca)

v7.0

IMPORTANT: Migration required

I am so proud of this release. fzf.fish is now in a state that I am delighted by. Users will have a very seamless experience customizing it to fit their needs, while developers will have a far easier time adding new features. As should be expected for groundbreaking changes, everyone will need to manually migrate.

Thankfully, the migration process shouldn't be too painful and should be worthwhile because fzf_configure_bindings is so easy to use. Read the migration guide for instructions.

Custom key bindings elevated to a first-class feature (#172)

Background

fzf.fish ships with default key bindings that are mnemonic and have minimal conflicts with existing fish key bindings. However, for users who want to change them, the process of customizing them is frustrating and confusing at best. This frustration has culminated in a steady stream of issues, discussions, PRs, and Wiki sections around key bindings (#17, #89, #99, #108, #103, #153, #162, Wiki section). Here are the shortcomings of making custom bindings DIY:

• Besides not installing the default bindings if fzf_fish_custom_keybindings is set, the plugin provides zero assistance to the user when it comes to installing the custom bindings. Users have to study config/fzf.fish, bind documentation, and maybe even even some basic fish syntax for advanced cases. This is too daunting. Furthermore, users have to reference functions clearly denoted private (__fzf_search_*)., which feels and is hacky. Ideally, the plugin does not require typical users to dive into its code and will abstract private functions away completely.
• fzf_fish_custom_keybindings is all or nothing; users have to opt out of ALL default key bindings and re-bind them themselves even if they only want to change one. This is tedious, verbose, and unwieldy. A good plugin should allow tweaking the key binding while maintaining the rest of the defaults.
• Because the fzf_fish_custom_keybindings has to be set before config/fzf.fish is executed, it has to be created as a universal variable. Unfortunately, universal variables are a very confusing point for new fish users.
• And because it needs to be universal, it's bad practice to add it to one's config.fish. This makes it more difficult for one's fzf.fish configuration to be checked into git.

As the plugin developer, I have also been hampered by the DIY custom binding mechanism:

• Because custom bindings are painful to implement, user forego them and settle for the defaults, which puts a lot of pressure on me (subconsciously and through the many issues opened) to make the default bindings suitable for everyone. Unfortunately, the goal of having a default set of key bindings that are memorable and suitable for even 80% of users is nigh impossible. After days of research and talking to different users, I've concluded this task is ultimately futile because key bindings are remarkably idiosyncratic. Therefore, custom key bindings should be a first class feature that is well supported, completely documented, flexible, painless to use, and directly encouraged.
• Any change, even an addition (such as a new feature), to the default key bindings is a monumental event because it's not transparent and hard to communicate to users. The best I can do is to cut a new major release and post on Reddit to announce any and all key binding changes. Furthermore, the only place the default bindings can be found are on the readme. As a result, most users are probably left in the dark when their key bindings silently break on them. If more users customized their key bindings and (which they don't because again, it's not well supported) and there was an interface to quickly view the default key bindings, this would be a much smaller problem.
• Because users have to hardcode the function names in their custom key bindings, fzf.fish's internal functions are not really private and I cannot rename them. The result is that some function names no longer directly match their feature name.
• Finally, fzf_fish_custom_keybindings has a typo: key binding is two words, not one.

TL;DR The new solution

A new function called fzf_configure_bindings solves or mitigates all of the aforementioned problems. It:

• serves as a wrapper around the key bindings and fzf.fish's private functions so that they are properly abstracted away under a lightweight interface.
• allows customizing the key binding for each feature through namesake options (e.g. --directory controls the search directory key binding). Bindings can be overridden or, if the user doesn't want to use the feature, even disabled.
• uses mnemonic key sequences by default for features that the user chooses to not customize. This means that to change the key bind for a single feature, only one option needs to be specified.
• comes with great, easy-to-read help documentation that prints if used incorrectly.
• includes the default key bindings in its help message so users can easily and quickly find them.
• is robust and thoroughly tested.
• will include command completion (to be implemented later).

As a side note, fzf_fish_custom_keybindings no longer disables the default bindings.

Other changes

Search directory's key binding has changed to Ctrl+Alt+F (98c3a47)

The former binding, Ctrl+F conflicts with forward char, which is now muscle memory for many users who use it to move around the command line and accept autosuggestions.

All private functions have been renamed (a7b9608, ed97b9e)

Now that custom key bindings are painless to implement and private functions have been properly abstracted, I took this opportunity to

• use a single underscore instead of double underscore for private functions: this is shorter, distinguishes it from fish's standard lib private functions, and is more in line with other programming conventions
• rename search directory's and search's variables functions directly after them, making it consistent with the other function names and easier for developers to find

In Case You Missed It: previous v6 changes worth re-mentioning

• Allow customizing the file preview command with the variable fzf_preview_file_cmd (#156)
• [Search variables] enable selecting multiple variables. This is very convenient when needing to select multiple related variables to erase, show, query. (#165)
• [Search history] use the box-drawing character instead of the pipe character to mark off the timestamps (aaf3652)

Wow, you've read all the way to the bottom! Would appreciate any feedback from you in the discussion, or even a star on the repo :)

v6.5

This release contains 3 miscellaneous upgrades. In order of most impactful to least:

• [Search variables] enable selecting multiple variables. This is very convenient when needing to select multiple related variables to erase, show, query. (#165 -@kidonng)
• [Search history] use the box-drawing character instead of the pipe character to mark off timestamps. This is more visually appealing, uniform across different fonts, and won't get matched if the user searches for a pipe char. (aaf3652 - thanks @kidonng for suggesting it)
• Fix the plugin uninstaller so that it no longer erases all of your user key bindings (a1f9cae)

v6.4

Search directory bug fixes

This release was solely focused on patching up Search Directory. It is now more robust, reliable, and predictable than ever! Big thanks to @kidonng for finding all 4 of these bugs and starting the fixes!

• Properly show symlink info in file previews (#159)
• Previews when base dir contains spaces (patch 3) (#161)
• Previewing symlinks containing spaces (#164)
• Specifying base directories using quotes (#163)

v6.3

Allow customizing the file preview command (#156)

To allow users to implement custom file previews (great ideas include previewing images or showing hexdumps), the command used to preview files is now configurable. To change it, set the variable fzf_preview_file_cmd.

Huge thanks to @neersighted who not only came up with the idea, but implemented it within a couple short hours!

Bug fixes

• [Search git log] improve compatibility with older git versions (#151 - @kidonng )
• [Search directory] fix preview for files with spaces (again) (#152 - with help from @kidonng )

v6.2

Fish 3.2.0 is the minimum required version (#146)

Now that fish 3.2.0 has been out for almost a month, it's time to make it the minimum required version. Thankfully, the only new expectation made by the plugin is around the new set --show format. It has been simplified (see fish-shell/fish-shell#6944) such that the search shell variable preview logic, which uses set --show, can be greatly simplified. While this is technically backwards incompatible with fish 3.1.2, the only negative consequence for users who haven't upgraded should be that their variable preview won't be as clean and condensed but will still have all the essentials.

[Search directory] fix tilde in current token not expanding (83cb78f)

The bug happened when the current token is something like ~/Documents/ when executing search directory. It should have limited the search scope to ~/Documents but it didn't. Thankfully, the bug is now fixed. Thanks @kidonng for finding it!

v6.1

Important hotfix for anyone on 3.1.2 (or older)

This is a hotfix for search directory. It was broken by the v6.0 release (specifically when #133 was merged, which included an invisible character accidentally added to a comment). It doesn't affect fish 3.2+, which is why neither CI nor my local testing caught it, but for those on 3.1.2 or older, you will be completely unable to use search directory. The error you'll see looks like:

⫸  fish: Unknown command: which may include tilde, variables, etc.
in command substitution
	called on line 9 of file ~/.config/fish/functions/__fzf_search_current_dir.fish
in function '__fzf_search_current_dir'
~/.config/fish/functions/__fzf_search_current_dir.fish: Unknown error while evaluating command substitution
in function '__fzf_search_current_dir'

Big thanks to @fezboy who spotted it and quickly PRed in a fix in #142! 👏

v6.0

Allow passing custom fzf options to individual commands (#140)

By popular demand, everyone can now easily customize fzf to their hearts content!

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

• fzf_dir_opts => search directory
• fzf_git_status_opts => search git status
• fzf_git_log_opts => search git log
• fzf_history_opts => search history
• fzf_shell_vars_opts => search shell variables

They are always appended last to fzf's argument list so that they can override any hardcoded fzf options. This might lead to some people shooting themselves in the foot but also unlocks numerous opportunities for the user to customize or augment the existing features.

Some of the cool ideas now made possible include:

• add key bindings within fzf to operate on the selected line, e.g. open file in vim, preview file as image, copy to clipboard, git checkout commit, git reset commit
• adjust the preview window or command
• re-populate fzf's input list on demand
• change the search mode
• Read more in fzf docs and at betterprogramming.pub

[Search directory] expand variables in current token (#133)

Sidenote: The search directory feature was previously called search files but I've since changed the name.
Now, the search directory feature will not only expand tilde (~) in the current token, it will expand variables as well. This is useful for quickly accessing known directory variables, e.g. $XDG_CONFIG_HOME, $TMPDIR, $JAVA_HOME, $fisher_path, $__fish_user_data_dir.

Bug fixes

• Support fish_hybrid_key_bindings (#136 - @sandersantema )
• [Search directory] fix two bugs around preview for paths containing spaces (#137 - @kidonng and me)
• [Search directory] More accurate and helpful error when a previewing a path that doesn't exist (#137)

---

In case you missed it: previous changes from v5 worth re-mentioning

More configurables

The focus of work from v5 to v6 was on making fzf.fish much more configurable. fd can receive custom options by setting fzf_fd_opts (#126):

set -g fzf_fd_opts --hidden --exclude=.git

which makes it easy to configure things such as if you want to see hidden files or only show non-directory files.
Additionally, the command used to preview folders in the search directory feature can be changed by setting fzf_preview_dir_cmd (#120):

set -g fzf_preview_dir_cmd exa --all --color=always

which allows integration with popular ls replacements such as exa, lsd, colorsls, etc.

Preview entire command in command in history search with syntax highlighting (#125, #134, #135)

[Search directory] Ability to specify which directory to search (#75)

• This new behavior allows the user to choose to search a directory other than the current directory. If the current token is a directory and it has a trailing slash (e.g. vim functions/<CURSOR>), then we assume the user wants to search for files in that directory.
• This can be useful when the current directory contains large subdirectories (e.g. on macOS, the home directory contains ~/Library, which is very large). Moreover, it also allows searching a parent or sibling directory by using ../ (e.g. ../Downloads/<CURSOR>).
• What's great is that this behavior complements tab completion. When a user wants to access a file in a subdirectory, they may start typing the name of the directory and hit TAB. When tab completion writes out the directory's path, it will already append a trailing slash for the user, allowing the user to quickly execute the search files feature and search for the file in a more narrow scope.
• Variables within the current token, e.g. $XDG_CONFIG_HOME, will be expanded (#133).