You can install null-ls using any package manager. Here is a simple example showing how to install it and its dependencies using packer.nvim:
use({
"jose-elias-alvarez/null-ls.nvim",
config = function()
require("null-ls").setup()
end,
requires = { "nvim-lua/plenary.nvim" },
})
As shown above, the plugin depends on plenary.nvim, so make sure you've installed that plugin, too.
Below is a simple example demonstrating how you might configure null-ls. See BUILTINS for a list of built-in sources like the ones in the example below and BUILTIN_CONFIG for information on how to configure these sources.
require("null-ls").setup({
sources = {
require("null-ls").builtins.formatting.stylua,
require("null-ls").builtins.diagnostics.eslint,
require("null-ls").builtins.completion.spell,
},
})
The following code block shows the available options and their defaults.
local defaults = {
cmd = { "nvim" },
debounce = 250,
debug = false,
default_timeout = 5000,
diagnostics_format = "#{m}",
fallback_severity = vim.diagnostic.severity.ERROR,
log_level = "warn",
notify_format = "[null-ls] %s",
on_attach = nil,
on_init = nil,
on_exit = nil,
root_dir = u.root_pattern(".null-ls-root", "Makefile", ".git"),
sources = nil,
update_in_insert = false,
}
null-ls allows configuring a subset of the options used by nvim-lspconfig's
setup
method (shared with vim.lsp.start_client
), as described
here.
If an option you want to use is missing, open an issue or PR.
Note that setting autostart = true
is unnecessary (and unsupported), as
null-ls will always attempt to attach to buffers automatically if you've
configured and registered sources.
Defines the command used to start the null-ls server. If you do not have an
nvim
binary available on your $PATH
, you should change this to an absolute
path to the binary.
The debounce
setting controls the amount of time between the last change to a
buffer and the next textDocument/didChange
notification. These notifications
cause null-ls to generate diagnostics, so this setting indirectly controls the
rate of diagnostic generation (affected by update_in_insert
, described below).
Lowering debounce
will result in quicker diagnostic refreshes at the cost of
running diagnostic sources more frequently, which can affect performance. The
default value should be enough to provide near-instantaneous feedback from most
sources without unnecessary resource usage.
Displays all possible log messages and writes them to the null-ls log, which you
can view with the command :NullLsLog
. This option can slow down Neovim, so
it's strongly recommended to disable it for normal use.
debug = true
is the same as setting log_level
to "trace"
.
Sets the amount of time (in milliseconds) after which built-in sources will time out. Note that built-in sources can define their own timeout period and that users can override the timeout period on a per-source basis, too (see BUILTIN_CONFIG.md).
Specifying a timeout with a value less than zero will prevent commands from timing out.
Sets the default format used for diagnostics. The plugin will replace the following special components with the relevant diagnostic information:
#{m}
: message#{s}
: source name (defaults tonull-ls
if not specified)#{c}
: code (if available)
For example, setting diagnostics_format
to the following:
diagnostics_format = "[#{c}] #{m} (#{s})"
Formats diagnostics as follows:
[2148] Tips depend on target shell and yours is unknown. Add a shebang or a 'shell' directive. (shellcheck)
You can also set diagnostics_format
for built-ins by using the with
method,
described in BUILTIN_CONFIG.
Defines the severity used when a diagnostic source does not explicitly define a
severity. See :help diagnostic-severity
for available values.
Enables or disables logging to file.
Plugin logs messages on several logging levels to following destinations:
- file, can be inspected by
:NullLsLog
. - neovim's notification area.
Sets the default format for vim.notify()
messages.
Can be used to customize 3rd party notification plugins
like nvim-notify.
Defines an on_attach
callback to run whenever null-ls attaches to a buffer. If
you have a common on_attach
you're using for LSP servers, you can reuse that
here, use a custom callback for null-ls, or leave this undefined.
Defines an on_init
callback to run when null-ls initializes. From here, you
can make changes to the client (the first argument) or initialize_result
(the
second argument, which as of now is not used).
Defines an on_exit
callback to run when the null-ls client exits.
Determines the root of the null-ls server. On startup, null-ls will call
root_dir
with the full path to the first file that null-ls attaches to.
local root_dir = function(fname)
return fname:match("my-project") and "my-project-root"
end
If root_dir
returns nil
, the root will resolve to the current working
directory.
A user-defined function that controls whether to enable null-ls for a given
buffer. Receives bufnr
as its first argument.
To cut down potentially expensive calls, null-ls will call should_attach
after
its own internal checks pass, so it's not guaranteed to run on each new buffer.
require("null-ls.nvim").setup({
should_attach = function(bufnr)
return not vim.api.nvim_buf_get_name(bufnr):match("^git://")
end,
})
Defines a list (array-like table) of sources for null-ls to register. Users can add built-in sources (see BUILTINS.md) or custom sources (see MAIN.md).
If you've installed an integration that provides its own sources and aren't interested in built-in sources, you don't have to define any sources here. The integration will register them independently.
Controls whether diagnostic sources run in insert mode. If set to false
,
diagnostic sources will run upon exiting insert mode, which greatly improves
performance but can create a slight delay before diagnostics show up. Set this
to true
if you don't experience performance issues with your sources.
Note that by default, Neovim will not display updated diagnostics in insert
mode. Together with the option above, you need to pass update_in_insert = true
to vim.diagnostic.config
for diagnostics to work as expected. See :help vim.diagnostic.config
for more info.
Create an empty file .null-ls-root
in the directory you want to mark as the
project root for null-ls.