Notice of Breaking Changes

[clason]

This issue is used to announce breaking changes (and possibly other critical info). Users are strongly encouraged to subscribe to this issue to get notified of such changes.

Every breaking change is added as a new comment.

[clason]

#2272 switched our Lua parser to one with better coverage. Old queries are not compatible with the new parser.

To make sure you update to the new one, do :TSUninstall lua followed by :TSInstall lua (making sure to restart Neovim). Third-party modules providing Lua queries need to adapt to the new parser.

[clason]

#2436 updated the LaTeX parser to a version that is incompatible with previous queries. Plugins and color schemes that bundle their own queries need to be adapted.

In case of errors, please bisect your config to find the outdated plugin and open an issue in the corresponding repository.

[kyazdani42]

#2471 deprecates the used_by property for the parser definitions.

This is now set via the filetype_to_parsername table exported from the parsers module:

local ft_to_parser = require"nvim-treesitter.parsers".filetype_to_parsername
ft_to_parser.someft = "python" -- the someft filetype will use the python parser and queries.

[clason]

#2764 has renamed the functions

• :TSEnableAll -> :TSEnable
• :TSDisableAll -> :TSDisable

[clason]

#2763 deprecates ensure_install='maintained', with removal slated for April 30, 2022. Either specify an explicit list of actually used parsers or 'all' (not recommended).

Rationale: Over time, the category 'maintained' (which only indicates that a parser has a maintainer listed) has lost its usefulness, as it has become impossible to guarantee the sort of stability that is implied by "maintained".

[clason]

As of #2806, Nvim-treesitter requires Neovim 0.7.0 or later. This is technically not breaking (only verified in :checkhealth), but it will allow us to make breaking changes for earlier versions in the coming days (see #2793).

[clason]

#2808 removed all bundled filetype detection and ftplugins. These should be handled by Neovim (which includes them as of 0.7.0); new ones are easy to add via the new vim.filetype.add() function in Neovim.

[clason]

#2809 removes ensure_install='maintained'. Specify an explicit list of parsers (or use 'all' in combination with ignore_install).

[clason]

#3035 updated the Swift parser to a version that is incompatible with some previous queries. Plugins and color schemes that bundle their own queries need to be adapted.

As always, check your runtime path for outdated parsers or queries:

echo nvim_get_runtime_file('*/swift.so', v:true)
echo nvim_get_runtime_file('queries/swift/*.scm', v:true)

[clason]

#3048 changed the Markdown parser to a new, split, parser that improves performance. Important: you need to install both markdown and markdown_inline parsers to get the same highlighting as before. (Conversely, you can uninstall the markdown_inline parser to improve performance further at the expense of less highlighting.)

To upgrade,

1. update nvim-treesitter, ignoring any errors from automatic parser updates; restart Neovim
2. :TSUninstall markdown
3. :TSInstall markdown markdown_inline

Queries are not compatible; as always, make sure you do not have stale parsers or queries lying around.

[clason]

#2818 changed the Vala parser to an officially maintained one. Plugins and color schemes that bundle their own queries need to be adapted.

[clason]

#3555 switched the help parser to a different repository and improved implementation. To make sure you update to the new one, do :TSUninstall help followed by :TSInstall help (making sure to restart Neovim and removing the impatient Lua cache if used). Third-party modules providing help queries need to adapt to the new parser.

[clason]

#3656 removed the obsolete TS* highlighting groups. Users and plugins should instead directly use the capture name as a highlight group. E.g., instead of

hi link TSPunctDelimit Delimiter

do

hi link @punctuation.delimiter Delimiter

Nvim-treesitter now requires Nvim 0.8.0 or higher.

[clason]

#3791 switched the Erlang parser to a different maintained repository. To make sure you update to the new one, do :TSUninstall erlang followed by :TSInstall erlang (making sure to restart Neovim and removing the impatient Lua cache if used). Third-party modules providing erlang queries need to adapt to the new parser.

[amaanq]

#4524 rework indentation styling/format to be aligned with upstream, any plugins/modules that modified this will have to use the new captures specified in the docs

[clason]

#4593 renamed the help parser to vimdoc, following the upstream change. Make sure to change ensure_installed and any language-specific highlight groups accordingly.

[clason]

#4944 switched the Matlab parser to a different maintained repository. To make sure you update to the new one, do :TSUninstall matlab followed by :TSInstall matlab (making sure to restart Neovim after updating nvim-treesitter). Third-party modules providing matlab queries need to adapt to the new parser.

[amaanq]

#5185 changed the upstream proto parser to a maintained one, just update the parser with :TSUninstall proto and :TSInstall proto

[clason]

#5234 raised the minimum Neovim version to v0.9.1 and changed the format of all injection queries to the upstream syntax. If you need to stay on Nvim 0.8.x, lock nvim-treesitter to v0.9.1.

[amaanq]

#5222 switched the upstream perl parser to a maintained one, just update the parser with :TSUninstall perl and :TSInstall perl

[clason]

#5902 raised the minimum Neovim version to v0.9.2, which includes a required fix for empty injections.

[clason]

#5895 changed the list of admissible capture names to more closely align with upstream tree-sitter and Helix, making sharing/adapting queries easier. This requires changes in colorschemes; see CONTRIBUTING.md and the commit message 1ae9b0e for a detailed list of changes. If you cannot adapt your colorscheme (yet), pin nvim-treesitter at v0.9.2.

[clason]

#5779 switched the angular parser to one supporting v17. To update, :TSUninstall angular and :TSInstall angular. Plugins and color schemes that bundle their own queries need to be adapted.

[clason]

#6027 switched the slint parser to a new official upstream version. To update, :TSUninstall slint and :TSInstall slint. Plugins and color schemes that bundle their own queries need to be adapted.