*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
   require'lspconfig'.pyright.setup{}
3. Ensure your project/workspace contains a root marker which matches the
   server requirements specified in |lspconfig-all|.
4. Open a code file in Nvim. LSP will attach and provide diagnostics. >bash
   nvim main.py
5. Run `:checkhealth lsp` to see the status or to troubleshoot.

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

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

To activate a config, call its `setup{}` function. Each config name listed in
|lspconfig-all| is available as `config.<name>`. For example to activate the
"clangd" config: >lua

    require'lspconfig'.clangd.setup{}
<
                                                        *lspconfig-config_def*
You can use the `config_def` field to get the static config definition without
activating it: >lua

    local config = require'lspconfig'.clangd.config_def
<
                                                             *lspconfig-setup*
`setup{}` wraps |vim.lsp.start()|, and takes a superset of its parameters,
adding the following keys:

- {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`.

- {single_file_support} (`bool`) (default: nil) Determines if a server is
  started without a matching root directory. See |lspconfig-single-file-support|.

- {silent} (`bool`) (default: false) Whether to suppress error reporting if the
  LSP server fails to start.

- {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 fields passed to `setup{}` override the respective field in the
default configuration. There is no composition.

All |vim.lsp.start()| `config` fields (described in |vim.lsp.ClientConfig|)
can be overridden via the `setup{}` call. The most common overrides are:

- {settings} Table is sent after initialization 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.

  Example: 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: >lua
  require('lspconfig').pyright.setup{
    settings = {
      pyright = {
          disableLanguageServices = true,
          disableOrganizeImports  = true,
        }
    }
  }
<

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

For servers that don't have a config, define one via `vim.lsp.config()`
(requires Nvim 0.11 or later), see |lsp-config|.

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

See |lsp-completion|.

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

See |lsp-config| (requires Nvim 0.11 or later).

==============================================================================
ROOT DETECTION                                        *lspconfig-root-detection*

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.

Nvim provides |vim.fs.root()| to make it easy to find a "root marker" file.

==============================================================================
ADVANCED ROOT DIRECTORY DETECTION                      *lspconfig-root-advanced*
The `root_dir` field of |vim.lsp.Config| (Nvim 0.11 or later) may be
a function.

==============================================================================
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.
- also supports unnamed buffer if filetype matches the server filetype
  settings.

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.

==============================================================================
DEBUGGING AND TROUBLESHOOTING                              *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
- 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. See |lspconfig-root-detection|.
  - 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.

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

  vim.lsp.set_log_level 'trace'
  require('vim.lsp.log').set_format_func(vim.inspect)
<
Attempt to run the language server, and open the log with:

>vim
    :LspLog
<
Note that `ERROR` messages containing `stderr` only indicate that the log was
sent to `stderr`. Many servers counter-intuitively send harmless messages
via stderr.

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

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