*lsp.txt*   LSP


                            NVIM REFERENCE MANUAL


LSP client/framework                                     *lsp* *LSP*

Nvim supports the Language Server Protocol (LSP), which means it acts as
a client to LSP servers and includes a Lua framework `vim.lsp` for building
enhanced LSP tools.

    https://microsoft.github.io/language-server-protocol/

LSP facilitates features like go-to-definition, find references, hover,
completion, rename, format, refactor, etc., using semantic whole-project
analysis (unlike |ctags|).

                                      Type |gO| to see the table of contents.

==============================================================================
QUICKSTART                                              *lsp-quickstart*

Nvim provides an LSP client, but the servers are provided by third parties.
Follow these steps to get LSP features:

1. Install language servers using your package manager or by following the
   upstream installation instructions. You can find language servers here:
   https://microsoft.github.io/language-server-protocol/implementors/servers/

2. Use |vim.lsp.config()| to define a configuration for an LSP client
   (see https://github.com/neovim/nvim-lspconfig for examples).
   Example: >lua
     vim.lsp.config['luals'] = {
       -- Command and arguments to start the server.
       cmd = { 'lua-language-server' },

       -- Filetypes to automatically attach to.
       filetypes = { 'lua' },

       -- Sets the "root directory" to the parent directory of the file in the
       -- current buffer that contains either a ".luarc.json" or a
       -- ".luarc.jsonc" file. Files that share a root directory will reuse
       -- the connection to the same LSP server.
       -- Nested lists indicate equal priority, see |vim.lsp.Config|.
       root_markers = { { '.luarc.json', '.luarc.jsonc' }, '.git' },

       -- Specific settings to send to the server. The schema for this is
       -- defined by the server. For example the schema for lua-language-server
       -- can be found here https://raw.githubusercontent.com/LuaLS/vscode-lua/master/setting/schema.json
       settings = {
         Lua = {
           runtime = {
             version = 'LuaJIT',
           }
         }
       }
     }

3. Use |vim.lsp.enable()| to enable a configuration.
   Example: >lua
     vim.lsp.enable('luals')
<
4. Open a code file matching one of the `filetypes` specified in the config.
   Note: Depending on the LSP server, you may need to ensure your project has
   a |lsp-root_markers| file so the workspace can be recognized.

5. Check that LSP is active ("attached") for the buffer: >vim
    :checkhealth vim.lsp
<
6. (Optional) Configure keymaps and autocommands to use LSP features.
   |lsp-attach|

==============================================================================
DEFAULTS                                                *lsp-defaults*

When the Nvim LSP client starts it enables diagnostics |vim.diagnostic| (see
|vim.diagnostic.config()| to customize). It also sets various default options,
listed below, if (1) the language server supports the functionality and (2)
the options are empty or were set by the builtin runtime (ftplugin) files. The
options are not restored when the LSP client is stopped or detached.

GLOBAL DEFAULTS
                                          *grr* *gra* *grn* *gri* *i_CTRL-S*
These GLOBAL keymaps are created unconditionally when Nvim starts:
- "grn" is mapped in Normal mode to |vim.lsp.buf.rename()|
- "gra" is mapped in Normal and Visual mode to |vim.lsp.buf.code_action()|
- "grr" is mapped in Normal mode to |vim.lsp.buf.references()|
- "gri" is mapped in Normal mode to |vim.lsp.buf.implementation()|
- "gO" is mapped in Normal mode to |vim.lsp.buf.document_symbol()|
- CTRL-S is mapped in Insert mode to |vim.lsp.buf.signature_help()|

BUFFER-LOCAL DEFAULTS
- 'omnifunc' is set to |vim.lsp.omnifunc()|, use |i_CTRL-X_CTRL-O| to trigger
  completion.
- 'tagfunc' is