Key Mappings

One of Neovim's strengths is that it allows a great deal of customization, and key mappings are some of the most common features of a personal configuration.

Often called key binds, key bindings, and key maps, key mappings are often used in several ways:

  1. They can be used to remap a command from the default to a different command that makes more sense to the user
  2. They can create shortcuts for longer combinations of keys or commands.
  3. They can be used like long-lived macros that are executed when the keymap is invoked
  4. They can provide a more convenient means of executing commands, user-commands, of combinations thereof.

In short, key maps are one of several options that Neovim provides to define your own commands.

Key maps can be defined in any of your search directories, but the three most common are:

plugin/filename.lua
Files in the plugin/ folder are sourced each time a new buffer is opened. Key maps that should be globally-available can be created here. Unless specified otherwise, we will assume that key maps are defined here.
ftplugin/filename.lua
Files in the ftplugins/ folder are sourced each time a buffer of that filetype is opened. Key maps that should apply to specific file types can be created here.
lua/filename.lua
Files in the lua/ directory can be required from lua files contained in other locations. Key maps contained in a required file will be set. Key maps defined in this directory can be configured to load under specific conditions defined in lua.
Note

As you might have noticed in the search directories section that there is a search directory called keymap/. Unfortunately, although this appears to be a logical place to define key maps, based on our tests, it does not appear that keymap definitions in this directory are recognized.

Let's get started.