Repository files navigation

null-ls.nvim Reloaded, maintained by the community.

Only the repo name is changed for compatibility concerns. All the API and futurechanges will keep in place as-is.

Replacejose-elias-alvarez/null-ls.nvim withnvimtools/none-ls.nvim in yourchoice of package manager.

That's it.

Open a pull request to become a collaborator. If you have contributed tonull-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 collaboratorto review your changes, as a review is required for the PR to be merged byyourself (subject to change if there are more collaborators in the future).

Use Neovim as a language server to inject LSP diagnostics, code actions, andmore via Lua.

Neovim's LSP ecosystem is growing, and plugins liketelescope.nvim andtrouble.nvim make it a joy to work withLSP features like code actions and diagnostics.

Unlike the VS Code and coc.nvim ecosystems, Neovim doesn't provide a way fornon-LSP sources to hook into its LSP client. null-ls is an attempt to bridgethat gap and simplify the process of creating, sharing, and setting up LSPsources using pure Lua.

null-ls is also an attempt to reduce the boilerplate required to set upgeneral-purpose language servers and improve performance by removing the needfor external processes.

null-ls is inbeta status. Please see below for steps to follow if somethingdoesn'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 fromHEAD is provided on a best-effort basis, andusers are encouraged to contribute fixes to any issues exclusive to theseversions.

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 provideout-of-the-box functionality. SeeBUILTINS for a list ofavailable built-in sources andBUILTIN_CONFIG forinstructions on how to set up and configure these sources.

null-ls also provides helpers to streamline the process of spawning andtransforming 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,seeHELPERS for details.

Install null-ls using your favorite package manager. The plugin depends onplenary.nvim, which you are(probably) already using.

To get started, you must set up null-ls and register at least one source. SeeBUILTINS for a list of available built-in sources andCONFIG for information about setting up and configuringnull-ls.

localnull_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 itsdocumentation, which contains information about how null-lsworks, how to set it up, and how to create sources.

Contributions to add new features and built-ins for any language are alwayswelcome. SeeCONTRIBUTING for guidelines.

The following example demonstrates a diagnostic source that will parse thecurrent buffer's content and show instances of the wordreally as LSPwarnings.

localnull_ls=require("null-ls")localno_really= {method=null_ls.methods.DIAGNOSTICS,filetypes= {"markdown","text"},generator= {fn=function(params)localdiagnostics= {}-- sources have access to a params object-- containing info about the current file and editor statefori,lineinipairs(params.content)dolocalcol,end_col=line:find("really")ifcolandend_colthen-- null-ls fills in undefined positions-- and converts source diagnostics into the required formattable.insert(diagnostics, {row=i,col=col,end_col=end_col+1,source="no-really",message="Don't use 'really!'",severity=vim.diagnostic.severity.WARN,                    })endendreturndiagnosticsend,    },}null_ls.register(no_really)

null-ls includes helpers to simplify the process of spawning and capturing theoutput of CLI programs. This example shows how to pass the content of thecurrent buffer tomarkdownlint viastdin and convert its output (which itsends tostderr) into LSP diagnostics:

localnull_ls=require("null-ls")localhelpers=require("null-ls.helpers")localmarkdownlint= {method=null_ls.methods.DIAGNOSTICS,filetypes= {"markdown"},-- null_ls.generator creates an async source-- that spawns the command with the given arguments and optionsgenerator=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)localsuccess=code<=1ifnotsuccessthen-- 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)endreturnsuccessend,-- use helpers to parse the output from string matchers,-- or parse it manually with a functionon_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 stepsbelow anddo not open an issue on the Neovim repository. null-ls is not anactual LSP server, so we need to determine whether issues are specific to thisplugin before sending anything upstream.

1. Make sure your configuration is in line with the latest version of thisdocument.
2. Enable debug mode andcheck the output of your source(s). If the CLI program is not properlyconfigured or is otherwise not running as expected, that's an issue with theprogram, not null-ls.
3. Check the documentation for available configuration options that might solveyour issue.
4. If you're having trouble configuring null-ls or want to know how to achieve aspecific result, open a discussion.
5. If you believe the issue is with null-ls itself or you want to request a newfeature, open an issue and provide the information requested in the issuetemplate.

Checking whether a given command is executable is tricky, and null-ls' healthcheck doesn't handle all cases. null-ls' internal command resolution isindependent 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 checkyour log.

Usevim.lsp.buf.format(). See:help vim.lsp.buf.format() for usageinstructions.

Seethis wiki page.

Seethis wiki page.

For a built-in solution, use:lua vim.diagnostic.setqflist(). You can also usea plugin liketrouble.nvim.

1. Setdebug flag totrue in your config:

   require("null-ls").setup({debug=true,})

2. 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 theoption 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 aspossible, so it should work seamlessly with most LSP-related plugins. If you runinto problems, please try to determine which plugin is causing them and open anissue.

This wiki pagementions plugins that require specific configuration options / tweaks to workwith null-ls.

Thanks to hard work by @folke, the plugin wraps the mechanism Neovim uses tospawn language servers to start a client entirely in-memory. The client attachesto 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 inmemory without any external processes, in most cases it should run faster thansimilar solutions. If you notice that performance is worse with null-ls thanwith an alternative, please open an issue!

This issue occurs when a formatter takes longer than the default timeout value.This is an automatic mechanism and controlled by Neovim. You might want toincrease 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.Runmake test in the root of the project to run the suite orFILE=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 itsplugin runtime under the./tests directory to always have a plenary versionavailable.

If you run into plenary-related issues while running the tests, make sure youhave 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 notguaranteed to work on versions built fromHEAD.

• efm-langserver anddiagnostic-languageserver:general-purpose language servers that can provide formatting and diagnosticsfrom CLI output.

• nvim-lint: a Lua plugin thatfocuses on providing diagnostics from CLI output.

• formatter.nvim: a Lua pluginthat (surprise) focuses on formatting.

• hover.nvim: Hover plugin frameworkfor Neovim.