*lspconfig.txt* For Nvim version 0.6.1+ Last change: 2021 Nov 7 ============================================================================== TABLE OF CONTENTS *lspconfig-toc* 1. Introduction (|lspconfig|) 2. LSP overview (|lspconfig-lsp|) 3. Quickstart (|lspconfig-quickstart|) 4. Setup {} (|lspconfig-setup|) 5. Global defaults (|lspconfig-global-defaults|) 6. Server configurations (|lspconfig-configurations|) 6a. Adding servers (|lspconfig-adding-servers|) 7. Root directories (|lspconfig-root-detection|) 7a. Advanced detection (|lspconfig-root-advanced|) 7b. Single file support (|lspconfig-single-file-support|) 8. Commands (|lspconfig-commands|) 9. Keybindings (|lspconfig-keybindings|) 10. Completion (|lspconfig-completion|) 11. Debugging (|lspconfig-debugging|) 12. Logging (|lspconfig-logging|) 13. Scope (|lspconfig-scope|) ============================================================================== INTRODUCTION *lspconfig* `lspconfig` is a collection of community contributed configurations for the built-in language server client in Neovim core. This plugin provides four primary functionalities: - default launch commands, initialization options, and settings for each server - a root directory resolver which attempts to detect the root of your project - an autocommand mapping that either launches a new language server or attempts to attach a language server to each opened buffer if it falls under a tracked project - utility commands such as LspInfo, LspStart, LspStop, and LspRestart for managing language server instances `lspconfig` is not required to use the built-in client, it is only one front-end interface for when a language server specific plugin is not available. See |lspconfig-server-configurations| by typing `K` over it for the complete list of language servers configurations. ============================================================================== LSP OVERVIEW *lspconfig-lsp* Nvim supports the Language Server Protocol (LSP) via the built-in language server client. LSP facilitates many features, some of which include: - go-to-definition - find-references - hover - completion - rename - format - refactor These features are implemented in Neovim core, not `lspconfig`. See `:help lsp` for more details. NOTE: Feature availability depends on the implementation details of the server. A server may implement only a subset of these features. Always consult the server documentation before filing a bug report on a missing feature. ============================================================================== QUICKSTART *lspconfig-quickstart* - ensure the server is installed and executable from the command line - enable the server in your Neovim configuration (Lua example): > require'lspconfig'.clangd.setup{} < - create a new project, ensure that it contains a root marker which matches the server requirements specified in |lspconfig-server-configurations|. - open a file within that project, such as `main.c`. - If you need more information about a server configuration, read the corresponding entry in |lspconfig-server-configurations|. ============================================================================== THE SETUP METAMETHOD *lspconfig-setup* `lspconfig` consists of a collection of language server configurations. Each configuration exposes a `setup {}` metamethod which makes it easy to directly use the default configuration or selectively override the defaults. `setup {}` is the primary interface by which users interact with `lspconfig`. Using the default configuration for a server is simple: > require'lspconfig'.clangd.setup{} < The available server names are listed in |lspconfig-server-configurations| and match the server name in `config.SERVER_NAME` defined in each configuration's source file. The purpose of `setup{}` is to wrap the call to Nvim's built-in `vim.lsp.start_client()` with an autocommand that automatically launch a language server. This autocommand calls `start_client()` or `vim.lsp.buf_attach_client()` depending on whether the current file belongs to a project with a currently running client. See |lspconfig-root-detection| for more details. The `setup{}` function takes a table which contains a superset of the keys listed in `:help vim.lsp.start_client()` with the following unique entries: - {root_dir} `function(filename, bufnr)` Returns either a filepath (string) or nil. The language server will only start if the function returns a filepath. If a root directory (string) is returned which is unique from any previously returned root_dir, a new server will be spawned with that root directory. See |lspconfig-root-detection| for more details - {name} `string` Defaults to the server's name (`clangd`, `pyright`, etc.). - {filetypes} `list[string] | nil` Set of filetypes for which to attempt to resolve {root_dir}. May be empty, or server may specify a default value. - {autostart} `bool` (default: true) Controls if the `FileType` autocommand that launches a language server is created. If `false`, allows for deferring language servers until manually launched with `:LspStart` (|lspconfig-commands|). - {single_file_support} `bool` (default: nil) Determines if a server is started without a matching root directory. See |lspconfig-single-file-support|. - {on_new_config} `function(new_config, new_root_dir)` Function executed after a root directory is detected. This is used to modify the server configuration (including `cmd` itself). Most commonly, this is used to inject additional arguments into `cmd`. If overriding `on_new_config`, ensure that you read the `on_new_config` defined in the source file of the default configuration in `lspconfig`. The original `on_new_config` snippet for a given server should likely be included in your new override. Some configurations use `on_new_config` to dynamically set or modify `cmd`. Note: all entries passed to `setup {}` override the entry in the default configuration. There is no composition. All `config` elements described in `:help vim.lsp.start_client()` can additionally be overridden via the `setup {}` call. The most commonly passed overrides to `setup {}` are: - {capabilities} `table ` a table which represents the neovim client capabilities. Useful for broadcasting to the server additional functionality (snippets, off-protocol features) provided by plugins. - {cmd} `list[string]` a list where each entry corresponds to the blankspace delimited part of the command that launches the server. The first entry is the binary used to run the language server. Additional entries are passed as arguments. The equivalent `cmd` for: > foo --bar baz < is: > {'foo', '--bar', 'baz} < - {handlers} `list[functions]` a list of handlers which override the function used to process a response from a given language server. Applied only to the server referenced by setup. See |lsp-handler|. - {init_options} `table ` a table passed during the initialization notification after launching a language server. Equivalent to the `initializationOptions` field found in `InitializeParams` in the LSP specification. See upstream server documentation for available initialization options. - {on_attach} `function(client, bufnr)` Callback invoked by Nvim's built-in client when attaching a buffer to a language server. Often used to set Nvim (buffer or global) options or to override the Nvim client properties (`resolved_capabilities`) after a language server attaches. Most commonly used for settings buffer local keybindings. See |lspconfig-keybindings| for a usage example. - {settings} `table ` The `settings` table is sent in `on_init` via a `workspace/didChangeConfiguration` notification from the Nvim client to the language server. These settings allow a user to change optional runtime settings of the language server. As an example, to set the following settings found in the pyright documentation: `pyright.disableLanguageServices`: `boolean` `pyright.disableOrganizeImports`: `boolean` Nested keys need to be translated into a nested table and passed to the settings field in `setup {}` as follows: > require('lspconfig').pyright.setup{ settings = { pyright = { disableLanguageServices = true, disableOrganizeImports = true, } } } < ============================================================================== OVERRIDING GLOBAL DEFAULTS *lspconfig-global-defaults* The global defaults for all servers can be overridden by extending the `default_config` table. > local lspconfig = require'lspconfig' lspconfig.util.default_config = vim.tbl_extend( "force", lspconfig.util.default_config, { autostart = false, handlers = { ["window/logMessage"] = function(err, method, params, client_id) if params and params.type <= vim.lsp.protocol.MessageType.Log then vim.lsp.handlers["window/logMessage"](err, method, params, client_id) end end; ["window/showMessage"] = function(err, method, params, client_id) if params and params.type <= vim.lsp.protocol.MessageType.Warning.Error then vim.lsp.handlers["window/showMessage"](err, method, params, client_id) end end; } } ) < `setup {}` can additionally override these defaults in subsequent calls. ============================================================================== SERVER CONFIGURATIONS *lspconfig-configurations* See |lspconfig-server-configurations| by typing `K` over it for the complete list of language servers configurations. While the `setup {}` function is the primary interface to `lspconfig`, for servers for which there is not a configuration, it is necessary to define a configuration directly. This can be useful if there is an outstanding PR that is in review, or when developing a language server that is unavailable publicly. This can be done through the `configs` module. The `configs` module is a singleton where configs are defined. The schema for validating using `vim.validate` is: > configs.SERVER_NAME = { default_config = {'t'}; on_new_config = {'f', true}; on_attach = {'f', true}; commands = {'t', true}; docs = {'t', true}; } < where the structure of the docs table is as follows: > docs = { description = {'s', true}; default_config = {'t', true}; } < `commands` is a map of `name:definition` key:value pairs, where `definition` is a list whose first value is a function implementing the command, and the rest are either array values which will be formed into flags for the command, or special keys like `description`. Example: > commands = { TexlabBuild = { function() buf_build(0) end; "-range"; description = "Build the current buffer"; }; }; < The `configs.__newindex` metamethod consumes the config definition and returns an object with a `setup()` method, to be invoked by users: > require'lspconfig'.SERVER_NAME.setup{} After you set `configs.SERVER_NAME` you can add arbitrary language-specific functions to it if necessary. Example: > configs.texlab.buf_build = buf_build < ============================================================================== ADDING NEW SERVERS *lspconfig-adding-servers* The three steps for adding and enabling a new server configuration are: - load the `lspconfig` module (note that this is a stylistic choice) > local lspconfig = require 'lspconfig' < - define the configuration > local configs = require 'lspconfig.configs' -- Check if the config is already defined (useful when reloading this file) if not configs.foo_lsp then configs.foo_lsp = { default_config = { cmd = {'/home/neovim/lua-language-server/run.sh'}; filetypes = {'lua'}; root_dir = function(fname) return lspconfig.util.find_git_ancestor(fname) end; settings = {}; }; } end - call `setup()` to enable the FileType autocmd > lspconfig.foo_lsp.setup{} < ============================================================================== ROOT DETECTION *lspconfig-root-detection* *lspconfig-root-dir* A project's `root_dir` is used by `lspconfig` to determine whether `lspconfig` should start a new server, or attach a previous one, to the current file. `lspconfig` automatically launches language servers by defining a filetype autocommand based on the `filetypes` specified in the default configuration of each server, optionally overridable by the `filetypes` table passed to `setup`. This autocommand triggers a search from the current file position in the filesystem hierarchy up to the top level directory of your filesystem. The `root_dir` entry of each configuration is a function that returns true if the current directory in this traversal matches a given root pattern. The following utility functions are provided by `lspconfig`. Each function call below returns a function that takes as its argument the current buffer path. - `util.root_pattern`: function which takes multiple arguments, each corresponding to a different root pattern against which the contents of the current directory are matched using |vim.fin.glob()| while traversing up the filesystem. > root_dir = util.root_pattern('pyproject.toml', 'requirements.txt') < - `util.find_git_ancestor`: a function that locates the first parent directory containing a `.git` directory. > root_dir = util.find_git_ancestor - `util.find_node_modules_ancestor`: a function that locates the first parent directory containing a `node_modules` directory. > root_dir = util.find_node_modules_ancestor < - `util.find_package_json_ancestor`: a function that locates the first parent directory containing a `package.json`. > root_dir = util.find_json_ancestor < Note: On Windows, `lspconfig` always assumes forward slash normalized paths with capitalized drive letters. ============================================================================== ADVANCED ROOT DIRECTORY DETECTION *lspconfig-root-advanced* *lspconfig-root-composition* The `root_dir` key in `config` and `setup` can hold any function of the form > function custom_root_dir(filename, bufnr) returns nil | string > This allows for rich composition of root directory patterns which is necessary for some project structures. Example (for Kotlin): > local root_files = { 'settings.gradle', -- Gradle (multi-project) 'settings.gradle.kts', -- Gradle (multi-project) 'build.xml', -- Ant 'pom.xml', -- Maven } local fallback_root_files = { 'build.gradle', -- Gradle 'build.gradle.kts', -- Gradle } root_dir = function(fname) local primary = util.root_pattern(unpack(root_files))(fname) local fallback = util.root_pattern(unpack(fallback_root_files))(fname) return primary or fallback end < Browsing the source of the default configurations is recommended. ============================================================================== SINGLE FILE SUPPORT *lspconfig-single-file-support* Language servers require each project to have a `root` in order to provide features that require cross-file indexing. Some servers support not passing a root directory as a proxy for single file mode under which cross-file features may be degraded. `lspconfig` offers limited support for an implicit single-file mode by: - first trying to resolve the root directory pattern - then, if `single_file_support` is enabled for a given language server configuration, starting the server without sending `rootDirectory` or `workspaceFolders` during initialization. - attaching subsequent files in the parent directory to the same server instance, depending on filetype. Cross-file features (navigation, hover) may or may not work depending on the language server. For a full feature-set, consider moving your files to a directory with a project structure `lspconfig` can infer. Note that in the event that the LSP specification is extended to support a standard for single-file mode, lspconfig will adopt that standard. ============================================================================== COMMANDS *lspconfig-commands* - `:LspInfo` shows the status of active and configured language servers. Note that client id refers to the Nvim RPC instance connected to a given language server. The following commands support tab-completion for all arguments. All commands that require a client id can either leverage tab-completion or the info contained in `:LspInfo`: - `:LspStart ` launches the requested (configured) client, but only if it successfully resolves a root directory. Note: Defaults to all configured servers matching the current buffer filetype. - `:LspStop ` stops the server with the given client id. Defaults to stopping all servers active on the current buffer. - `:LspRestart ` restarts the client with the given client id, and will attempt to reattach to all previously attached buffers. ============================================================================== EXAMPLE KEYBINDINGS *lspconfig-keybindings* `lspconfig`, and the core client, do not map any keybindings by default. The following is an example Lua block which demonstrates how to leverage `on-attach` to selectively apply keybindings after a language servers has attached to a given buffer. > > -- Mappings. -- See `:help vim.diagnostic.*` for documentation on any of the below functions local opts = { noremap=true, silent=true } vim.api.nvim_set_keymap('n', 'e', 'lua vim.diagnostic.open_float()', opts) vim.api.nvim_set_keymap('n', '[d', 'lua vim.diagnostic.goto_prev()', opts) vim.api.nvim_set_keymap('n', ']d', 'lua vim.diagnostic.goto_next()', opts) vim.api.nvim_set_keymap('n', 'q', 'lua vim.diagnostic.setloclist()', opts) -- Use an on_attach function to only map the following keys -- after the language server attaches to the current buffer local on_attach = function(client, bufnr) -- Enable completion triggered by vim.api.nvim_buf_set_option(bufnr, 'omnifunc', 'v:lua.vim.lsp.omnifunc') -- Mappings. -- See `:help vim.lsp.*` for documentation on any of the below functions vim.api.nvim_buf_set_keymap(bufnr, 'n', 'gD', 'lua vim.lsp.buf.declaration()', opts) vim.api.nvim_buf_set_keymap(bufnr, 'n', 'gd', 'lua vim.lsp.buf.definition()', opts) vim.api.nvim_buf_set_keymap(bufnr, 'n', 'K', 'lua vim.lsp.buf.hover()', opts) vim.api.nvim_buf_set_keymap(bufnr, 'n', 'gi', 'lua vim.lsp.buf.implementation()', opts) vim.api.nvim_buf_set_keymap(bufnr, 'n', '', 'lua vim.lsp.buf.signature_help()', opts) vim.api.nvim_buf_set_keymap(bufnr, 'n', 'wa', 'lua vim.lsp.buf.add_workspace_folder()', opts) vim.api.nvim_buf_set_keymap(bufnr, 'n', 'wr', 'lua vim.lsp.buf.remove_workspace_folder()', opts) vim.api.nvim_buf_set_keymap(bufnr, 'n', 'wl', 'lua print(vim.inspect(vim.lsp.buf.list_workspace_folders()))', opts) vim.api.nvim_buf_set_keymap(bufnr, 'n', 'D', 'lua vim.lsp.buf.type_definition()', opts) vim.api.nvim_buf_set_keymap(bufnr, 'n', 'rn', 'lua vim.lsp.buf.rename()', opts) vim.api.nvim_buf_set_keymap(bufnr, 'n', 'ca', 'lua vim.lsp.buf.code_action()', opts) vim.api.nvim_buf_set_keymap(bufnr, 'n', 'gr', 'lua vim.lsp.buf.references()', opts) vim.api.nvim_buf_set_keymap(bufnr, 'n', 'f', 'lua vim.lsp.buf.formatting()', opts) end -- Use a loop to conveniently call 'setup' on multiple servers and -- map buffer local keybindings when the language server attaches local servers = { 'pyright', 'rust_analyzer', 'tsserver' } for _, lsp in pairs(servers) do require('lspconfig')[lsp].setup { on_attach = on_attach, flags = { -- This will be the default in neovim 0.7+ debounce_text_changes = 150, } } end < Note: these keymappings are meant for illustration and override some infrequently used default mappings. ============================================================================== COMPLETION SUPPORT *lspconfig-completion* Manually triggered completion can be provided by Nvim's built-in omnifunc. See `:help omnifunc` for more details. For autocompletion, Nvim does not offer built-in functionality at this time. Consult the `lspconfig` wiki, which provides configuration examples for using a completion plugin with the built-in client ============================================================================== DEBUGGING *lspconfig-debugging* While using language servers should be easy, debugging issues can be challenging. First, it is important to identify the source of the issue, which is typically (in rough order): - the language server itself - a plugin - overrides in a user configuration - the built-in client in Nvim core - `lspconfig` The first step in debugging is to test with a minimal configuration (such as `../test/minimal_init.lua`). Historically, many users problems are due to plugins or misconfiguration. Should that fail, identifying which component is the culprit is challenging. The following are the only categories of bugs that pertain to `lspconfig`. - The root directory inferred for your project is wrong, or it should be detected but is not due to a bug in the `lspconfig` path utilities. - The server is launching, but you believe that the default settings, initialization options, or command arguments are suboptimal and should be replaced based on your understanding of the server documentation. All bugs Nvim's built-in client should be reported to the Nvim core issue tracker. All bugs pertaining to plugins should be reported to the respective plugin. All missing features in a language server should be reported to the upstream language server issue tracker. For debugging `lspconfig` issues, the most common hurdles users face are: - The language server is not installed or is otherwise not executable. `lspconfig` does not install language servers for you. Ensure the `cmd` defined in `server_configurations.md` is executable from the command line. If the absolute path to the binary is not supplied in `cmd`, ensure it is on your PATH. - No root detected. `lspconfig` is built around the concept of projects. See |lspconfig-root-detection| for more details. Most of the time, initializing a git repo will suffice. - Misconfiguration. Often users will override `cmd`, `on_init`, or `handlers`. Ensure that you debug by using a stock configuration to ensure your customizations are not introducing issues. |LspInfo| provides an overview of your active and configured language servers which can be useful for debugging. Note that it will not report any configuration changes applied in `on_new_config`. ============================================================================== LOGGING *lspconfig-logging* When debugging language servers, it is helpful to enable additional logging in the built-in client, specifically considering the RPC logs. Example: > vim.lsp.set_log_level 'trace' if vim.fn.has 'nvim-0.5.1' == 1 then require('vim.lsp.log').set_format_func(vim.inspect) end < Attempt to run the language server, and open the log with: > :lua vim.cmd('e'..vim.lsp.get_log_path()) < Note that `ERROR` messages containing `stderr` only indicate that the log was sent to `stderr`. Many servers counter-intuitively send harmless messages via stderr. ============================================================================== SCOPE *lspconfig-scope* `lspconfig` is a community effort to create default configurations that fit within the scope of an official plugin for Nvim. All features that are not strictly providing default configurations for language servers will be removed from `lspconfig` in time. The power of the Neovim LSP ecosystem is in the composability and flexibility of integrating multiple plugins which maximizes user choice and freedom. `lspconfig` also opts to adhere strictly to the LSP specification, with some small allowances when small modifications to a server configuration are necessary to enable features critical to its usability. For more featureful options, the `lspconfig` wiki lists community created plugins that build upon the built-in client to provide functionality tailored to specific language servers. ============================================================================== vim:tw=78:ts=8:ft=help:norl: