unknown_document

Deleting a key mapping is pretty simple, and uses a call signature similar to the used to [create] the key mapping in the first place: vim . keymap . del ( { mode }, -- string or list { lhs }, -- string { opts } -- optional table ) where mode and opts are the same as described in setting key mappings . When deleting key mappings, the mapping is deleted for only the modes specified, and opts supports only the buffer key, indicating whether want to delete a global or buffer -local key mapping. This method will delete the key mapping, but in most cases key mappings are created in a configuration file. This means that it will reappear next time to start Neovim. If the key mapping is created in your configuration files, deleting the mapping generally means deleting (or commenting out) the code that created it and restarting Neovim. The next section will discuss how to locate where key mappings are defined, which can help with this. What if the key mapping you wish to delete comes from outside your configuration, such as from a plugin? There are several possible solutions available: 1) Review the plugin documentation Most plugins that set key mappings will include instructions defining how to change them in the plugin's configuration. In most cases, this would be the best way to delete (or re-map) the plugins default key mappings. 1) Overwrite the key mapping When you aren't able to delete or change the key mapping from with the plugin's configuration, the next option is to re-define that mapping to perform the action you want. In that case, simply create a new key mapping that performs the action you want. As long as this key mapping is executed after the plugin is loaded, this should be an effective solution. Review the search directories section for help ensuring that this command is executed after the plugin in question is loaded. If you don't want the key mapping to do anything at all, another option would be to define a new key mapping, but set to a no-op (meaning, "no operation", or "do nothing") as follows: vim . keymap . set ( { mode }, -- string or list { lhs }, -- string "<Nop>" , { opts } -- optional table ) This literally tells Neovim to ignore the lhs , which is effectively the same as deleting the key mapping.

As Neovim has rolled out its lua API it has offered several methods of setting key mappings. A quick internet search will bring up several of them, which has led to some confusion for new users. Since then, Neovim's lua APIs have evolved and become more stable. We recommend that users use the latest API, which is as-follows: vim . keymap . set ( { mode }, -- string or table { lhs }, -- string { rhs }, -- string or function { opts } -- optional table ) {mode}: The first argument is a string or list of strings specifying the mode(s) for which this mapping should apply. Each mode is specified using its short name . Here are several examples of mode specifications: "n" -- apply in normal mode only { "n" } -- apply in normal mode only { "n" , "i" ) -- apply in normal and insert modes {lhs}: " lhs " is short for the "left-hand side", which specifies which keys should invoke the key mapping. Whether a key mapping creates a new operation or overrides an existing operation, it should be specified as the lhs . Ambiguous Key Mappings Internet forums are full of questions asking "why is the ab command so slow on my computer". In many cases, the issue is an ambiguous key mapping; if key mappings ab and abc are both defined, when ab is typed Neovim has to wait to see if the user is typing abc , or if the user intended to type only ab . This pause creates a noticeable delay. In most cases the solution is to review the key mappings and re-map any that are ambiguous. Another option for some could be to reduce the timeoutlen option from the default (1000 msec) to a shorter length. Mapleader A tool to help prevent ambiguous mappings is to use the mapleader , or often referred to simply as leader . Hitting the leader key tells Neovim to expect a key mapping that has been defined with the <leader> prefix. Since no operators or commands begin with the leader , this provides extra flexibility for creating unambiguous key mappings. Note that it is still possible to create ambiguous mappings with the <leader> . We should note that there are two types of leaders , the first is <mapleader> , which applies to global key mappings, and <maplocalleader> , which applies to buffer -local mappings. Although these are generally set to the same value, they can be set to different values. By default the leader is \ , but can be changed in your configuration files as follows: vim . g . mapleader = " " vim . g . maplocalleader = " " In this example, both leader s are set to the <space> key, which is a popular leader key since it can easily be hit with the thumb. The local and global leaders can be set to separate keys to allow different behaviors between global and buffer -local key mappings by changing the values above. When both buffer -local and global mappings are defined for an lhs , the buffer -local key mapping take precedence. {rhs}: " rhs " is short for "right-hand side", which specifies the action to be taken when the lhs is invoked. Neovim accepts several rhs formats: keys In the simplest case, the rhs of a key mapping is a simple string of keys that should substitute those of the lhs . An example of a simple key mapping and be found in the improved-J tip. command Another common use case is to use key mappings to execute command-line mode commands. The Moving Lines tip provides a good example of defining key mappings that implement a command. Note that Neovim still implements the key mapping as literal key presses, so executing the command-line command (rather than simply type the command into the command-line ) requires inserting a <CR> into the correct location. User Command After defining a user-command , it can be used in a key mapping just like any other command-line command. lua function Finally, key maps can also be defined to call custom lua functions, which can implement essentially any desired logic using Neovim's lua API. The basic pattern for implementing a key mapping with lua functions is: local callback = function () vim . print ( "Hello World!" ) end vim . keymap . set ( "n" , "test" , callback ) Which defines the test key mapping to call the callback lua function. {opts}: Neovim supports several options when defining key mappings, which can all be found in the Neovim docs . These options have sensible default values, so that only two of them need to be used in most cases: buffer The buffer option is used to define a buffer -local key mapping. Value Meaning false Create a global key mapping. This is the default true Create the keymap for the current buffer only 0 Create the keymap for the current buffer only [digit] Create the keymap for only the buffer with the specific buffer number desc Text description of what the keymap does. What this does will become more clear when we get to the listing keymaps section.

Occasionally we all forget which key mapping we defined for which action, and need to go review the mapping to recall. Similarly, sometimes we want to modify a key mapping but don't recall exactly where it was defined. Neovim has a pretty convenient built-in mechanism to help with these scenarios. The most basic form of listing key mapping is the :map command, which lists all key mappings defined for all modes: :map While comprehensive, the amount of content can be a bit unwieldy. For this reason, Neovim includes several ways to filter the output. The :map command is one of a group of commands that can be used to list key mappings. In fact, while this command lists all key mapping, regardless of mode , the others limit their output to their specific mode . They are: Command Description :map Display key bindings for all modes :nmap Display key bindings for normal mode :vmap Display key bindings for visual mode :imap Display key bindings for insert mode The next filter that we will look at is allows us to filter the list according to the {lhs}. For example, to see key mappings with {lhs} starting with g : :map g Of course, these filters can be combined. Repeating for normal mode key mappings: :nmap g The next filter limits the output to buffer -local key mappings: :map <buffer> The :filter command provide some additional flexibility when filtering mappings. :filter {pattern} {command} When used, :filter matches the specified pattern against {lhs}, {rhs} and {desc} fields, which makes it handy to list key mappings when you only remember a portion of the description, for example. This is one reason to apply sensible desc entries when creating key mappings. When verbose is used the listing will also display where the key mapping was defined. This is useful for locating where to go to modify the key mapping. Finally, while most of this section focuses on limiting the amount of output, the final topic uses the :verbose command to increase the amount of output we get for each entry This command can be involved with the following signature: :verbose {command} {pattern} For example, to see normal -mode key mappings starting with g : :verbose nmap g When the :verbose command is used the output includes an additional line that indicates from where the key mapping most-recently set, which can be helpful when locating a key mapping definition.

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: They can be used to remap a command from the default to a different command that makes more sense to the user They can create shortcuts for longer combinations of keys or commands. They can be used like long-lived macros that are executed when the keymap is invoked 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.

We saw earlier that Neovim supports EditorConfig . Neovim's EditorConfig implementation supports adding properties allowing project-local configuration to be customized using simple Lua functions. These callbacks open up a wide range of possibilities for project-local configuration, both of Neovim itself as well as anything that can be defined in Lua, including keymaps , plugins, and user-commands . To define new properties, create a new file called (for example) extend-editorconfig.lua in your plugins directory, which will contain the custom properties and callback functions that define their behavior. The default properties are defined in the properties table located at: require ( "editorconfig" ). properties New properties can be defined by adding them to this table, as follows: -- add a new property called my_prop to the properties table require ( "editorconfig" ). properties . my_prop = function ( bufnr , val , opts ) -- function arguments: -- bufnr: the number of the current buffer -- val: the value that was set in the .editorconfig file -- opts: a table containing all properties and values set in the .editorconfig file -- any logic can be implemented in this function -- for example -- optional logic can determine whether this value should be set if opts . charset and opts . charset ~= "utf-8" then -- return without setting the value return end -- perform conditional logic based on val if val == "abc" then -- set Neovim configuration for the current buffer vim . b [ bufnr ]. foo = true elseif val == "xyz" then -- we can even conditionally create a keymap vim . keymap . set ( "n" , "lhs" , function () -- implement keymap behavior end ) else vim . b [ bufnr ]. foo = false end end which is then called from within an .editorconfig file like this: [*] my_prop = abc The ability to define custom properties and behaviors makes Neovim's .editorconfig a powerful tool for implementing project-local configuration.

Neovim configuration is probably one of the most commonly-asked questions that new users ask. The purpose of this chapter is to provide a common-sense guide for new users to get up to speed quickly, or for more advanced users who want to get a bit more control configuring Neovim. Pre-Built Configuration For many new users, it might make sense to start with one of the community-built configurations. These provide good out-of-the-box experiences, and allow you to quickly get started with Neovim. There are several popular options available: LazyVim NvChad LunarVim AstroNvim Each of these provide details for installing and customizing, and are a great place to start. Starter Configuration Over time you may decide that you want a bit more control over your setup, but you don't necessarily want a fully-custom configuration from scratch. In this case, a good place to place to start is kickstart.nvim . kickstart.nvim provides a well-documented, single-file configuration that installs a selection of popular plugins that can get you started quickly. To get started with kickstart.nvim , simply follow along the next few sections until we get to init.lua , then follow the steps there. Once you get started with kickstart.nvim , the rest of this chapter will still be helpful for learning how you can customize your configuration as your needs evolve. Fully-Custom Configuration Finally, for those that want to start from scratch and understand every line in their configuration. The material in this chapter builds a basic configuration similar to that in kickstart.nvim , and does so in a way that the user can understand what is included and how to change it going forward. The goal is to provide a basic configuration that provides a foundation upon which your fully-custom configuration can evolve. Let's get started.

Neovim originated as a fork of Vim and while it continues to maintain backward-compatibility with Vim, the two projects have slightly different goals which has led them to evolve down slightly different paths. While Vim continues to be a great project with a great community, Neovim has added several new features that in our opinion significantly upgrade the user experience: Lua First and foremost, one of the major advantages of Neovim over Vim is the inclusion of Lua as a first-class alternative to Vimscript for plugins and configuration . Lua is easy to learn, read, and write, executes quickly, and allows Neovim to benefit from a lot of great work being done by Lua's extensive community. Tree-sitter Tree-sitter is a fast document parser that maintains a syntax tree for each document as it is edited, which basically replaces slow and often-inaccurate regular expressions when implementing a variety of features. Prior to Tree-sitter, syntax-highlighting, indentation, and folding were implemented using regular expressions, which was often slow, inaccurate, and lacked features such as the ability to handle nested code blocks. By leveraging Tree-sitter's syntax tree, Neovim gains additional contextual information about the document that can be leveraged to provide accurate and consistent syntax highlighting, indentations, and folds, improved navigation between classes, functions, parameters, conditional statements, as well as some useful extensions to text objects . You can learn more Neovim's Tree-sitter integration at the nvim-treesitter and nvim-treesitter-textobjects repos. Language Server Protocol (LSP) Neovim includes a built-in Language Server Protocol client, which provides a wide range of functionality. Whereas Tree-sitter improves the experience of working with documents, LSP provides similar benefits to projects , to provide improved code-completion, snippets, formatting, jump to definition, refactoring, etc. Learn more about setting up Neovim's LSP at the nvim-lspconfig repo. More Information This is just a brief summary of the key improvements that Neovim offers vs Vim. If you are transitioning from Vim to Neovim you can find a complete list of the differences here Neovim.io Github Home Github Releases Documentation

Listing Auto-Commands :autocmd vim . api . nvim_get_autocmds ({ opts }) where opts is a table containing one or more of: --opts { group , -- optional string or integer, which group(s) to include event , -- optional string or list of strings, which event(s) to include -- 0 or 1 of the following: pattern , -- optional string or list of strings, pattern filter -- for buffer-local auto-commands: buffer -- optional integer or list of integers } Note that pattern and buffer are mutually-exclusive, if either is present the other cannot. This functions returns a list of tables, where each table represents an auto-command that matched the filter(s) specified in opts , and table contains the following keys: { id , -- integer, auto-command id group , -- integer, group id group_name , -- string, auto-group name desc , -- string, auto-command description event , -- string, event name command , -- string, command or nil if Lua callback callback , -- optional function or string once , -- boolean, whether the auto-command is fired only once (default false) pattern , -- string, the auto-command pattern buflocal , -- boolean, true if the auto-command is buffer local buffer -- integer, the buffer number }

While user-commands allow functions to be written then executed manually as needed, auto-commands allow functions to execute automatically as a result of various events , such as creating a new buffer or pressing a key. Auto-commands can be created using the Lua API as follows: vim . api . nvim_create_autocmd ( { event }, -- string or list { opts } -- table ) where event is a string or list of strings containing the names of the events that should trigger this auto-command , and opts is a table that accepts a variety of keys and values: -- opts { group , -- optional string or integer pattern , -- string or list of strings buffer , -- optional integer desc , -- optional string, -- optional lua function callback = function ( args ) -- implement command logic here end , command , -- optional string once , -- bool (default false), nested -- bool (default false) } callback and command are mutually-exclusive, only one can be used at a time. When callback is defined it can be defined as an anonymous function, as shown in the example, or it can be defined elsewhere and passed by reference. When called, the callback function is passed a table of information: -- args { id , -- integer event , -- string group , -- integer or nil match , -- string buf , -- integer or nil file , -- string or nil } where: id is the auto-command id event is the name of the event that triggered this auto-command group is the auto-group id or nil match is the name of the entity that matched to trigger this auto-command buf is the number of the buffer that triggered this event or nil file is the name of the buffer that triggered this event or nil

In most cases auto-commands are created in configuration files, so the best way to delete them is often to simply delete them code that creates them and restart Neovim. However, there are times were deleting [[auto-commands] from the current session might be required. Neovim's Lua API provides two functions for deleting auto-commands . This first method deletes auto-commands by id : vim . api . nvim_del_autocmd ( id ) where id is the unique id of the auto-command . So how can we find that? There are two ways to do so. First, the auto-command id is returned when the auto-command is created . A pattern for using it might be like this: local id = vim . api . nvim_create_autocmd ({ name }, { opts }) ... -- other code here vim . api . nvim_del_autocmd ( id ) but that's not so useful in many scenarios, since creating an auto-command and deleting it in the same file doesn't make a lot of sense. Another option that can be more useful is to list and filter the auto-commands using the vim.api.nvim_get_autocmds function we learned about in the previous section. After executing this command retrieving the list and verifying that the filters are targeting the correct auto-commands , one of two paths can be taken to delete the auto-commands : if additional logic is required to select specific auto-commands to delete, a loop can iterate over the results, the logic can be applied for each auto-command , then the id field can be used to delete individual auto-commands one by one, or The opts passed to vim.api.nvim_get_autocmds can be passed to vim.api.nvim_clear_autocmds and all matching auto-commands will get cleared. Keep in mind that either of these methods will only delete the auto-command for the remainder of the current session; when Neovim starts and sources configuration and code that creates auto-commands will apply them again.