*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 collection of configs. It has no API or
"framework". 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*

Each config 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()). This "composability" is a central feature of vim.lsp.config,
which allows nvim-lspconfig to just provide the config "defaults".

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 these differences 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
  - However, defining `root_dir` as a function is very flexible and may fit
    your use-case instead. https://github.com/neovim/neovim/issues/32037#issuecomment-2825599872

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

Any server-specific commands provided by a config are buffer-local and
prefixed with "Lsp". Thus you can see available commands (from a LSP-enabled
buffer) by typing: >vim

    :Lsp<tab>

The following _global_ commands are provided by nvim-lspconfig:

: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 server with the given client-id or config name. Defaults to
stopping all servers active on the current buffer. To force stop language
servers: >vim
    :LspStop!

:LspRestart [client_id] or [config_name]                         *:LspRestart*
Restarts the client with the given client-id or config name, and attempts
to reattach to all previously attached buffers. Defaults to restarting all
active servers. To force stop language servers when restarting: >vim
    :LspRestart!

==============================================================================
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|.

------------------------------------------------------------------------------
NEW CONFIGS                                           *lspconfig-new*

To create a new config, see |lsp-config| (requires Nvim 0.11+).
To contribute a config to nvim-lspconfig, see ../CONTRIBUTING.md.

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

See |lsp-completion|.

==============================================================================
Migrate to vim.lsp.config                                *lspconfig-nvim-0.11*

The "framework" part of nvim-lspconfig is DEPRECATED. The "configs" are NOT
deprecated, but were moved to the lsp/ directory so that |vim.lsp.config()|
automatically finds them.

This means:
- `require'lspconfig'[…]` must NOT be used. Use `vim.lsp.config(…)` instead.
- The `require'lspconfig'` quasi-framework will be DELETED, and is not
  supported in Nvim 0.11+.
- The nvim-lspconfig configs (|lspconfig-all|) now live in "lsp/" instead of
  "lua/lspconfig/".
- To use the configs, call `vim.lsp.config(…)` instead of `require'lspconfig'[…]`.

MIGRATION INSTRUCTIONS

To migrate:
- Upgrade to Nvim 0.11 or later.
- Change `require'lspconfig'[…]` to `vim.lsp.config(…)`.
  - Some field names changed, see |lspconfig-vs-vim.lsp.config|.
  - See |lsp-config| for details.

BACKGROUND

Since Nvim 0.11, nvim-lspconfig provides configs in its "lsp/" directory. The
old configs still exist in "lua/lspconfig/configs/" but are deprecated and
will be DELETED.

This means the "configs" role of nvim-lspconfig continues to be relevant, but
it is now a "data-only" repository instead of a "framework". The only change
needed from you, and from plugins, is to use the Nvim 0.11 `vim.lsp.config`
interface to setup LSP configs instead of the old `require'lspconfig'`
quasi-framework.

==============================================================================
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: