1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
|
*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:
|
