Breaking changes

[jose-elias-alvarez]

This issue will track any breaking changes made to null-ls.

We follow the Conventional Commits specification, so breaking changes will always be marked with a !. If you use packer.nvim, it'll highlight breaking changes on update.

Messages here will include the ID of the last commit before the breaking change. If a commit breaks your workflow or you're stuck on an old version of Neovim, you can pin the plugin to the previous commit using Packer:

use({ "jose-elias-alvarez/null-ls.nvim", commit = "commit-id-goes-here" })

For larger changes (e.g. removing support for an older Neovim version), I'll try to make a compatibility branch, which you can also specify with Packer:

use({ "jose-elias-alvarez/null-ls.nvim", branch = "branch-name-goes-here" })

NOTE: Once support for a previous version of Neovim has been removed, no further changes / fixes will target that version, and any issues related to unsupported versions will be closed.

[jose-elias-alvarez]

72e5466a81dbdbef90c97dc2f13b55c90a093a54 removed support for Neovim 0.5.0. Please update to 0.5.1 if you're able.

Last commit: 3e7390735501d0507bf2c2b5c2e7a16f58deeb81

[jose-elias-alvarez]

a238346eaf78ec3f59cc79627d11094b4f17e08e removed support for Neovim 0.5.1. Please update to 0.6.0 if you're at all able to do so (you'll get lots of other improvements, too).

Compatibility branch: 0.5.1-compat

Last commit: 8828af78d8c2d96a884769a070951a47c2e6a6ff

[jose-elias-alvarez]

f368efcf1df9197a24f41589434b2166700d962 removes the plugin's integration with nvim-lspconfig and deprecates the null_ls.config method. This change streamlines setup and protects null-ls from breakage caused by upstream changes. The merged PR also bundles several performance improvements and bug fixes, so updating is recommended.

To migrate, simply move all of your current config options into null_ls.setup:

-- old style
local null_ls = require("null-ls")

null_ls.config({
    sources = sources,
})
require("lspconfig")["null-ls"].setup({ on_attach = on_attach })

-- new style
local null_ls = require("null-ls")

-- all options go into setup
null_ls.setup({
    sources = sources,
    on_attach = on_attach,
})

Last commit: 385f3177a199e98e2f527b4de44eb955563eff96

[jose-elias-alvarez]

742739910ef5ef93efcaed32a5b875d7833b42af removes the conditional helper, previously exposed via require("null-ls.helpers").conditional. It's trivial to replicate its behavior (which is why it was removed):

local sources = {
    -- null-ls allows defining function sources that either return a source or nil
    function()
        local utils = require("null-ls.utils").make_conditional_utils()
        return utils.root_has_file(".eslintrc.js") and b.formatting.eslint_d or b.formatting.prettier
    end,
}

Note that the functionality available via builtin.with({ condition = ... }) has not been removed.

The commit also includes two other non-breaking changes that may affect users:

1. ~~Previously, built-in sources with a user-defined condition were checked on registration. Now, null-ls will register sources unconditionally and check condition when the source first runs. Since this gives us access to editor and project state, this change makes condition more useful and shouldn't affect behavior, but it may affect how active sources are reported via :NullLsInfo / the info API.~~ This has been changed and should not result in observable differences in behavior.
2. The with() method for built-ins now only allows a subset of options to be configured. All valid options are documented in BUILTINS. Note that helpers.make_builtin is only intended for sources included in the main null-ls repo, and other uses are not explicitly supported. If an option you use is no longer supported and you think it should be, please open an issue.

Previous commit: 2b8967dd7e6ae5f36274041c398b0941c4b889c1

[jose-elias-alvarez]

a340a309d0c9fb9a0be1c637e7712429d5126ab2 removed info.get_active_sources(), as its functionality was completely superseded by the source API.

Previous commit: 06491cfff0ae8bfc6200942352bee332fe562301

[agentzhao]

7427399 removes the conditional helper, previously exposed via require("null-ls.helpers").conditional. It's trivial to replicate its behavior (which is why it was removed):

local sources = {
    -- null-ls allows defining function sources that either return a source or nil
    function()
        local utils = require("null-ls.utils").make_conditional_utils()
        return utils.root_has_file(".eslintrc.js") and b.formatting.eslint_d or b.formatting.prettier
    end,
}

Note that the functionality available via builtin.with({ condition = ... }) has not been removed.

The commit also includes two other non-breaking changes that may affect users:

1. ~Previously, built-in sources with a user-defined `condition` were checked on registration. Now, null-ls will register sources unconditionally and check `condition` when the source first runs. Since this gives us access to editor and project state, this change makes `condition` more useful and shouldn't affect behavior, but it may affect how active sources are reported via `:NullLsInfo` / the `info` API.~ This has been changed and should not result in observable differences in behavior.

2. The `with()` method for built-ins now only allows a subset of options to be configured. All valid options are documented in [BUILTINS](https://github.com/jose-elias-alvarez/null-ls.nvim/blob/main/doc/BUILTINS.md). Note that `helpers.make_builtin` is **only** intended for sources included in the main null-ls repo, and other uses are not explicitly supported. If an option you use is no longer supported and you think it should be, please open an issue.

Previous commit: 2b8967d

Hi!

Before the change this is the way I used to set condition for eslint. Since the conditional helper is removed, is there a recommended way to do this?

require("null-ls.helpers").conditional(function(utils)
    local has_eslint = function(u)
      return utils.root_has_file(".eslintrc")
        or utils.root_has_file(".eslintrc.json")
        or utils.root_has_file(".eslintrc.js")
        or utils.root_has_file("package.json")
        or utils.root_has_file(".eslintrc.cjs")
        or utils.root_has_file(".eslintrc.yaml")
        or utils.root_has_file(".eslintrc.yml")
    end

    formatter.eslint_d.with({
      condition = has_eslint,
    })
    diagnostics.eslint_d.with({
      condition = has_eslint,
    })
    actions.eslint_d.with({
      condition = has_eslint,
    })
  end),

This is my null-ls config if needed. Thank you!

[jose-elias-alvarez]

0c7624fce3fefe291c75f0b6be2c1a51e5bed21e renamed the teal diagnostics source from tl check to teal. If for whatever reason you rely on or prefer the previous name, you can override it:

local sources = {
    null_ls.builtins.diagnostics.teal.with({
        name = "tl check",
    }),
}

[jose-elias-alvarez]

Modifying server.resolved_capabilities is no longer supported since neovim/neovim#17814. If you want to format with a specific server, you can use the new vim.lsp.buf.format API, which makes it easy to filter out clients you don't want to use for formatting. For example, to set up formatting on save with a filter:

local lsp_formatting = function(bufnr)
    vim.lsp.buf.format({
        filter = function(client)
            return client.name ~= "tsserver"
        end,
        bufnr = bufnr,
    })
end

local augroup = vim.api.nvim_create_augroup("LspFormatting", {})

-- add to your shared on_attach callback
local on_attach = function(client, bufnr)
    if client.supports_method("textDocument/formatting") then
        vim.api.nvim_clear_autocmds({ group = augroup, buffer = bufnr })
        vim.api.nvim_create_autocmd("BufWritePre", {
            group = augroup,
            buffer = bufnr,
            callback = function()
                lsp_formatting(bufnr)
            end,
        })
    end
end

(This is technically not a null-ls breaking change but is likely to affect a lot of users, so posting it here seems justified.)

Edit: if you are running into problems related to the merged PR, please make sure you are running not only the latest version of null-ls but have also rebuilt from the latest Neovim master.

[jose-elias-alvarez]

27e0dfc12d9eba8217b3861b772c8100608e36f7 removes the g:null_ls_disable global variable, which was used to conditionally disable null-ls. For null-ls to pick up the variable, it had to be set before null_ls.setup, which was finicky and required users to manage plugin order, which isn't ideal. The same result can be achieved by simply gating null_ls.setup behind a condition, e.g.:

if not vim.g.started_by_firenvim then
    require("null-ls").setup({
	...
    })
end

[jose-elias-alvarez]

c9348b47918bee72b541580adf31e963c9028f82 changes how null-ls logging works. We still use Plenary's file logger to handle all messages, but errors and warnings are now additionally shown using vim.notify, allowing users to override the handler for finer control / eye candy.

The commit also simplifies how logging is configured, collapsing the previous table into two top-level options:

1. log_level: sets the lowest level of messages that will be logged
2. notify_format: sets the format for messages passed to vim.notify

The debug option will continue to output all messages to a file.

Last commit: dd169992b598d5615aea5dc1903b4556a7b32423

[jose-elias-alvarez]

As of a9acd618d4d65846157b942c8c6000a8726c59a7, prefer_local and only_local no longer set the cwd of the spawned process to the directory in which the local executable was found. This mechanism was inconsistent and opaque, leading to confusion (and a bunch of issues on my end).

The approach we want to follow is to use a known set of root markers, which we can cache per buffer to improve correctness and performance. Our ESLint built-in provides a good example, so if you are using a built-in that no longer works as expected, please open a PR!

Last commit: 8ab5b579828693bb4dc206db34de51238dbd9d84

[jose-elias-alvarez]

4b403d2d724f48150ded41189ae4866492a8158b fixes a caching issue created by #1063. Any users who were directly using the from_node_modules or from_yarn_pnp command resolvers must make the following change:

local null_ls = require("null-ls")
local command_resolver = require("null-ls.helpers.command_resolver")

local prettier = null_ls.builtins.formatting.prettier.with({
    -- old
    -- dynamic_command = command_resolver.from_node_modules,

    -- new
    dynamic_command = command_resolver.from_node_modules(),
})

If you're using a built-in that depends on these helpers but are not importing one of the resolvers manually, you do not need to do anything.

[jose-elias-alvarez]

adaa799264c92eea42d500c8b98e19caf32c14dc removes support for Neovim 0.7.

Compatibility branch: 0.7-compat

Last commit: 6cc54779b494043aa5be9c711c1af1e891880535

[jose-elias-alvarez]

#1282 changes the command used by the editorconfig_checker built-in from ec to editorconfig-checker, which has been confirmed as the default name for the binary. See the linked PR for more details.

Last commit: c3e678110d5f31854c6575cf4bda3b82f3d4a884

[jose-elias-alvarez]

#1575 renames the swift-format built-in to swift_format for better Lua compatibility / consistency. If you're using the source, you'll need to update its name:

-- old
local sources = {
    null_ls.builtins.formatting["swift-format"]
}

-- new
local sources = {
    null_ls.builtins.formatting.swift_format
}

Last commit: 194f4d5cfeffe94e7c2d1d62be85bc7f12ed9e4f

[jose-elias-alvarez]

While not a breaking change, please see #1621 for an important update on the future of null-ls.