builtin keymap or fzf keymap? when will builtin keymap being used?

[milanglacier]

Hi all, I noticed that to define keymap, we have two sets, builtin, and fzf.

However I noted that in almost all the case I need to configure the keymap for fzf, my understanding is that the external process fzf is listening to those keys so we should configure keymap for `fzf.

Then in what sceneario will builtin keymap being used? It just get me confusing and the documentation also doesn't clearly state that when will builtin keymap being used. Thank you!

[ibhagwan]

One day I will merge both these keymap tables and sort out this confusion, I'll try to make sense below.

As you probably understand fzf-lua is running fzf the binary in a neovim terminal. keymap.fzf are the binds sent to fzf's --bind= flag (part of the fzf cli), these are usually navigation, line editing, etc.

keymap.builtin on the other hand are neovim binds attached to the main fzf window (the one running terminal fzf inside), for example when you press F1 and fzf-lua will display the help window, in this workflow neovim interprests the keybind and triggers fzf-lua's help window (not interacting with the terminal at all).

Here's when it becomes more confusing, fzf-lua supports all types of previewers, "native" previewers which run in the terminal inside fzf, examples of these are the bat, git_xxx pickers, etc.

But fzf-lua also has the (default) "builtin" previewer (hence the name) which is a neovim window/buffer (not in the terminal) so now if you're running :FzfLua files previewer=bat only keymap.fzf binds will apply to the previewer but if you're running :FzfLua files previewer=builtin the keymaps in keymap.builtin apply and while try to have feature parity and keybind matching between the two that's not always the case, for example the builtin previewer supports rotating the preview layout with F5/F6 which aren't supported with fzf.

Hope this helps sort out the mess.

"Builtin" previewer (note that 2 separate neovim windows):

"Native" bat previewer (note the previwer is "contained" inside fzf)

Help win triggered by F1

[milanglacier]

Thanks for your quick response! I think I understand what builtin mean now, it means things we can do in neovim, and fzf means things we need to send to fzf to handle.

Could I ask for another question:

        builtin = {
            false, -- do not inherit from defaults

This do not inherit from defaults is also really confusing. My understanding with some experiments tell me it actually means that:

If you pass your personal keymap config to either builtin keymap or fzf keymap. Then None of the default keymaps will apply. You need to set the first key in your custom options to true so that the default will also apply? Am my understanding correct?

[ibhagwan]

If you pass your personal keymap config to either builtin keymap or fzf keymap. Then None of the default keymaps will apply. You need to set the first key in your custom options to true so that the default will also apply? Am my understanding correct?

Correct, if you set this to false, only the key binds set in your config’s keymap.xxx will apply, set to true and the default keymap tables will be merged into your config (but won’t override your maps), so for example if you set the below you’ll get all the default keybinds except for the F1 help:

  keymap = { builtin = { true, ['<F1>'] = false } },

[milanglacier]

Thank you for your quick response!

I have this config:

                actions = {
                    files = {
                        true,
                        ['alt-i'] = actions.toggle_ignore,
                        ['alt-h'] = actions.toggle_hidden,
                    },
                },

then magically I find that I cannot use fzf-lua at all because nothing works. Pressing <CR> doesn't give me response at all. And it takes me 20 minutes to figure out that I need to use this:

                actions = {
                    files = {
                        true,
                        ['alt-i'] = actions.toggle_ignore,
                        ['alt-h'] = actions.toggle_hidden,
                    },
                },

So that those default keybindings like <CR>, <C-t>, <C-v> can just work.

I think this behavior is "somewhat unexpected". Because other neovim plugins take the approach of inheritance by default, for example telescope, blink-cmp all approach with this.

However, since fzf-lua has been a stable project for years. So we should keep it as is and can't change the default behavior.

Should we update the comment to clearly state that the expeceted behavior, something like this?

require('fzf-lua').setup {
    actions = {
        -- Below are the default actions, setting any value in these tables will override
        -- the defaults, to inherit from the defaults change [1] from `false` to `true`
        files = {
            -- NOTE: you must change it to true if you want to use the default keybindings with your custom keybindings together
            false, -- do not inherit from defaults
        },
    },

}

[ibhagwan]

I think this behavior is "somewhat unexpected". Because other neovim plugins take the approach of inheritance by default, for example telescope, blink-cmp all approach with this.

Actually, this behavior is unique to keymap/actions and is by design, all other tables inherit the defaults automatically, the main reason behind this is that I found that binds are very personal, some users navigate with ctrl-p/n, some users open splits with ctrl-x and all kinds of other oddities, this way users can define whatever they want without needing to set the default keybind they don’t want to false.

For example say you wanted to change split from ctrl-s to ctrl-x, you’d need to first set ctrl-x to false and define ctrl-s, this also is not super intuitive.

However, since fzf-lua has been a stable project for years. So we should keep it as is and can't change the default behavior.

The main reason I’m careful with changes, there hasn’t been a breaking change in fzf-lua in years, as a rule of thumb, if I add something new or change an option, the old way will still work (albeit with a warning, sometimes), there’s nothing more annoying than updating your plugin and finding out nothing works and you need the README again, README should be read hopefully once, when you configure the plugin and that’s it.

Should we update the comment to clearly state that the expeceted behavior, something like this?

We should update much more than this comment, see #1601, you’re welcome to give your 2 cents there too, and Ty :)

[gennaro-tedesco]

and the default keymap tables will be merged into your config (but won’t override your maps)

Could we clarify this behaviour? It seems that they do ovverride your maps: in particular I have been trying to override the default action for highlights (see here) but I still get the default behaviour. For instance

highlights = {
  actions = {
    ["default"] = function(selected)
      vim.cmd.echo("hello, world")
    end,
  }
}

still executes the default action (changing key instead does execute whichever new function you write).

TL;DR When specifying a custom action, are we sure the default ones are being explicitly overridden?

[ibhagwan]

and the default keymap tables will be merged into your config (but won’t override your maps)

Could we clarify this behaviour? It seems that they do ovverride your maps: in particular I have been trying to override the default action for highlights (see here) but I still get the default behaviour. For instance

highlights = {
  actions = {
    ["default"] = function(selected)
      vim.cmd.echo("hello, world")
    end,
  }
}

still executes the default action (changing key instead does execute whichever new function you write).

TL;DR When specifying a custom action, are we sure the default ones are being explicitly overridden?

That is def the behavior (or should be), the reason highlights doesn’t work is because I accepted a PR that added the lines below (there was no enter action prior), never realizing someone would want to do something with the hl :)

The below should be moved into actions and then you’ll be able to override:

fzf-lua/lua/fzf-lua/providers/colorschemes.lua

Lines 147 to 152 in 34d5e40

	opts.fn_selected = function(selected)
	if selected and selected[1] == "enter" then
	vim.cmd("hi " .. selected[2])
	vim.api.nvim_exec2("hi " .. selected[2], {})
	end
	end