null-ls.nvim
Reloaded, maintained by the community.
Only the repo name is changed for compatibility concerns. All the API and future changes will keep in place as-is.
Replace jose-elias-alvarez/null-ls.nvim
with nvimtools/none-ls.nvim
in your
choice of package manager.
That's it.
Open a pull request to become a collaborator. If you have contributed to
null-ls.nvim
before, simply open an issue or comment on that commit.
If you want to make changes, open a new pull request. Find another collaborator to review your changes, as a review is required for the PR to be merged by yourself (subject to change if there are more collaborators in the future).
Use Neovim as a language server to inject LSP diagnostics, code actions, and more via Lua.
Neovim's LSP ecosystem is growing, and plugins like telescope.nvim and trouble.nvim make it a joy to work with LSP features like code actions and diagnostics.
Unlike the VS Code and coc.nvim ecosystems, Neovim doesn't provide a way for non-LSP sources to hook into its LSP client. null-ls is an attempt to bridge that gap and simplify the process of creating, sharing, and setting up LSP sources using pure Lua.
null-ls is also an attempt to reduce the boilerplate required to set up general-purpose language servers and improve performance by removing the need for external processes.
null-ls is in beta status. Please see below for steps to follow if something doesn't work the way you expect (or doesn't work at all).
null-ls is developed on and tested against the latest stable version of Neovim.
Support for versions built from HEAD
is provided on a best-effort basis, and
users are encouraged to contribute fixes to any issues exclusive to these
versions.
null-ls sources are able to hook into the following LSP features:
Code actions
Diagnostics (file- and project-level)
Formatting (including range formatting)
Hover
Completion
null-ls includes built-in sources for each of these features to provide out-of-the-box functionality. See BUILTINS for a list of available built-in sources and BUILTIN_CONFIG for instructions on how to set up and configure these sources.
null-ls also provides helpers to streamline the process of spawning and transforming the output of command-line processes into an LSP-friendly format. If you want to create your own source, either for personal use or for a plugin, see HELPERS for details.
Install null-ls using your favorite package manager. The plugin depends on plenary.nvim, which you are (probably) already using.
To get started, you must set up null-ls and register at least one source. See BUILTINS for a list of available built-in sources and CONFIG for information about setting up and configuring null-ls.
local null_ls = require("null-ls")
null_ls.setup({
sources = {
null_ls.builtins.formatting.stylua,
null_ls.builtins.completion.spell,
require("none-ls.diagnostics.eslint"), -- requires none-ls-extras.nvim
},
})
The definitive source for information about null-ls is its documentation, which contains information about how null-ls works, how to set it up, and how to create sources.
Contributions to add new features and built-ins for any language are always welcome. See CONTRIBUTING for guidelines.
The following example demonstrates a diagnostic source that will parse the
current buffer's content and show instances of the word really
as LSP
warnings.
local null_ls = require("null-ls")
local no_really = {
method = null_ls.methods.DIAGNOSTICS,
filetypes = { "markdown", "text" },
generator = {
fn = function(params)
local diagnostics = {}
-- sources have access to a params object
-- containing info about the current file and editor state
for i, line in ipairs(params.content) do
local col, end_col = line:find("really")
if col and end_col then
-- null-ls fills in undefined positions
-- and converts source diagnostics into the required format
table.insert(diagnostics, {
row = i,
col = col,
end_col = end_col + 1,
source = "no-really",
message = "Don't use 'really!'",
severity = vim.diagnostic.severity.WARN,
})
end
end
return diagnostics
end,
},
}
null_ls.register(no_really)
null-ls includes helpers to simplify the process of spawning and capturing the
output of CLI programs. This example shows how to pass the content of the
current buffer to markdownlint
via stdin
and convert its output (which it
sends to stderr
) into LSP diagnostics:
local null_ls = require("null-ls")
local helpers = require("null-ls.helpers")
local markdownlint = {
method = null_ls.methods.DIAGNOSTICS,
filetypes = { "markdown" },
-- null_ls.generator creates an async source
-- that spawns the command with the given arguments and options
generator = null_ls.generator({
command = "markdownlint",
args = { "--stdin" },
to_stdin = true,
from_stderr = true,
-- choose an output format (raw, json, or line)
format = "line",
check_exit_code = function(code, stderr)
local success = code <= 1
if not success then
-- can be noisy for things that run often (e.g. diagnostics), but can
-- be useful for things that run on demand (e.g. formatting)
print(stderr)
end
return success
end,
-- use helpers to parse the output from string matchers,
-- or parse it manually with a function
on_output = helpers.diagnostics.from_patterns({
{
pattern = [[:(%d+):(%d+) [%w-/]+ (.*)]],
groups = { "row", "col", "message" },
},
{
pattern = [[:(%d+) [%w-/]+ (.*)]],
groups = { "row", "message" },
},
}),
}),
}
null_ls.register(markdownlint)
NOTE: If you run into issues when using null-ls, please follow the steps below and do not open an issue on the Neovim repository. null-ls is not an actual LSP server, so we need to determine whether issues are specific to this plugin before sending anything upstream.
:checkhealth
output is wrong! What do I do?Checking whether a given command is executable is tricky, and null-ls' health check doesn't handle all cases. null-ls' internal command resolution is independent of its health check output, which is for informational purposes.
If you're not sure whether a given command is running as expected, enable debug mode and check your log.
Use vim.lsp.buf.format()
. See :help vim.lsp.buf.format()
for usage
instructions.
See this wiki page.
See this wiki page.
For a built-in solution, use :lua vim.diagnostic.setqflist()
. You can also use
a plugin like trouble.nvim.
Set debug
flag to true
in your config:
require("null-ls").setup({
debug = true,
})
Use :NullLsLog
to open your debug log in the current Neovim instance or
:NullLsInfo
to get the path to your debug log.
As with LSP logging, debug mode will slow down Neovim. Make sure to disable the option after you've collected the information you're looking for.
In most cases, yes. null-ls tries to act like an actual LSP server as much as possible, so it should work seamlessly with most LSP-related plugins. If you run into problems, please try to determine which plugin is causing them and open an issue.
This wiki page mentions plugins that require specific configuration options / tweaks to work with null-ls.
Thanks to hard work by @folke, the plugin wraps the mechanism Neovim uses to spawn language servers to start a client entirely in-memory. The client attaches to buffers that match defined sources and receives and responds to requests, document changes, and other events from Neovim.
More testing is necessary, but since null-ls uses pure Lua and runs entirely in memory without any external processes, in most cases it should run faster than similar solutions. If you notice that performance is worse with null-ls than with an alternative, please open an issue!
timeout
error messageThis issue occurs when a formatter takes longer than the default timeout value. This is an automatic mechanism and controlled by Neovim. You might want to increase the timeout in your call:
vim.lsp.buf.format({ timeout_ms = 2000 })
The test suite includes unit and integration tests and depends on plenary.nvim.
Run make test
in the root of the project to run the suite or
FILE=filename_spec.lua make test-file
to test an individual file.
To avoid a dependency on any plugin managers, the test suite will set up its
plugin runtime under the ./tests
directory to always have a plenary version
available.
If you run into plenary-related issues while running the tests, make sure you
have an up-to-date version of the plugin by clearing that cache with:
make clean
.
All tests expect to run on the latest release version of Neovim and are not
guaranteed to work on versions built from HEAD
.
efm-langserver and diagnostic-languageserver: general-purpose language servers that can provide formatting and diagnostics from CLI output.
nvim-lint: a Lua plugin that focuses on providing diagnostics from CLI output.
formatter.nvim: a Lua plugin that (surprise) focuses on formatting.
hover.nvim: Hover plugin framework for Neovim.