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