*lspconfig.txt*         For Nvim version 0.10+

nvim-lspconfig provides user-contributed configs for the Nvim |lsp| client.

                                      Type |gO| to see the table of contents.

==============================================================================
INTRODUCTION                                                         *lspconfig*

nvim-lspconfig is a collection of community-contributed configurations for the
Nvim LSP client. See |lspconfig-all| for the complete list of provided
configurations.

Note: nvim-lspconfig is just a convenience layer, it is NOT required for Nvim
|LSP| support. See |lsp-quickstart| to setup LSP without nvim-lspconfig.

==============================================================================
QUICKSTART                                                *lspconfig-quickstart*

1. Install a language server, e.g. pyright. >bash
   npm i -g pyright
2. Add the language server setup to your init.lua. >lua
   vim.lsp.enable('pyright')
3. Ensure your workspace contains a root marker as specified in
   |lspconfig-all|.
4. Open a code file in Nvim. LSP will attach and provide diagnostics. >bash
   nvim main.py
5. Run `:checkhealth vim.lsp` to see the status or troubleshoot.

See also |lsp-quickstart|.

==============================================================================
USAGE                                                        *lspconfig-usage*

nvim-lspconfig is of a collection of language server configurations. Each
configuration provides defaults for |vim.lsp.config()| which you can use as-is
(by calling `vim.lsp.enable(…)`) or override (by calling |vim.lsp.config()|
before enable()).

To activate a config, call |vim.lsp.enable()|. Each config in |lspconfig-all|
is available as `vim.lsp.config('<name>')` and `vim.lsp.enable('<name>')`. For
example to activate the "clangd" config: >lua

    -- Optionally override parts of the default config...
    vim.lsp.config('clangd', {
      …
    })
    -- Enable filetype-based activation of the config.
    vim.lsp.enable('clangd')
<
                                                          *lspconfig-resolved*
You can call the "index" form of vim.lsp.config to get the resolved config
without activating it: >lua

    vim.print(vim.lsp.config['clangd'])
<
                                                 *lspconfig-vs-vim.lsp.config*
Note the these current differences/limitations of |vim.lsp.config()| compared
to the legacy nvim-lspconfig interface:

- `single_file_support` is assumed by default. Can be disabled by specifying
  `workspace_required=false` (see |vim.lsp.ClientConfig|).

- `on_new_config` is currently missing, see https://github.com/neovim/neovim/issues/32287
  Function executed after a root directory is detected. Used to modify the
  server configuration (including `cmd` itself).

==============================================================================
COMMANDS                                                    *lspconfig-commands*

:LspInfo                                                            *:LspInfo*
Alias to `:checkhealth vim.lsp`. Shows the status of active LSP clients and
servers.

:LspStart [config_name]                                            *: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 [client_id] or [config_name] ...                        *:LspStop*
Stops the servers with the given client-ids or config names. Defaults to
stopping all servers active on the current buffer. To force stop language
servers: >vim
    :LspStop ++force

:LspRestart [client_id] or [config_name] ...                     *:LspRestart*
Restarts the clients with the given client-ids or config names, and attempts
to reattach to all previously attached buffers.

==============================================================================
SERVER CONFIGS                                        *lspconfig-configurations*

See |lspconfig-all| for the list of provided LSP configurations.

If a server is missing, you can define one easily via |vim.lsp.config()|
(requires Nvim 0.11+), see |lsp-config|.

==============================================================================
COMPLETION SUPPORT                                        *lspconfig-completion*

See |lsp-completion|.

==============================================================================
ADDING NEW SERVERS                                    *lspconfig-new*

See ../CONTRIBUTING.md or |lsp-config| (requires Nvim 0.11+).

==============================================================================
DEBUGGING AND TROUBLESHOOTING                              *lspconfig-debugging*

See |lsp-log| to enable verbose logs.

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
- nvim-lspconfig

The first step in debugging is to test with a minimal configuration:
https://github.com/neovim/neovim/issues/new?assignees=&labels=bug%2Clsp&template=lsp_bug_report.yml
Historically, many 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 nvim-lspconfig.

- The root directory inferred for your project is wrong, or it should be
  detected but is not due to a bug in the nvim-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 nvim-lspconfig issues, the most common hurdles users face are:

  - The language server is not installed or is otherwise not executable.
    nvim-lspconfig does not install language servers for you. Ensure the `cmd`
    defined in |lspconfig-all| is executable from the command line. If the
    absolute path to the binary is not supplied in `cmd`, ensure it is on your
    PATH.
  - Missing filetype plugins. Certain languages are not detecting by
    Vim/Nvim because they have not yet been added to the filetype detection
    system. Ensure `:set ft?` shows the filetype and not an empty value.
  - Not triggering root detection. nvim-lspconfig is built around the concept
    of projects.
  - Not triggering root detection. Some language servers will only start
    if it is opened in a directory, or child directory, containing a file
    which signals the *root* of the project. Most of the time, this is
    a `.git` folder, but each server defines the root config in the lua file.
    See |lspconfig-all| or the source code for the list of root directories.
  - 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 which can be useful for debugging.

==============================================================================

vim:tw=78:ts=8:ft=help:norl:
