nvim-treesitter/nvim-treesitter

The nvim-treesitter plugin provides

1. functions for installing, updating, and removing tree-sitter parsers;
2. a collection of queries for enabling tree-sitter features built into Neovim for these languages;
3. a staging ground for treesitter-based features considered for upstreaming to Neovim.

For details on these and how to help improving them, see CONTRIBUTING.md.

• Neovim 0.12.0 or later (nightly)
• tar and curl in your path
• tree-sitter-cli (0.26.1 or later, installed via your package manager, not npm)
• a C compiler in your path (see https://docs.rs/cc/latest/cc/#compile-time-requirements)

You can install nvim-treesitter with your favorite package manager (or using the native package feature of vim, see :h packages).

This plugin is only guaranteed to work with specific versions of language parsers** (as specified in the parser.lua table). When upgrading the plugin, you must make sure that all installed parsers are updated to the latest version via :TSUpdate. It is strongly recommended to automate this; e.g., using the following spec with lazy.nvim:

{
  'nvim-treesitter/nvim-treesitter',
  lazy = false,
  build = ':TSUpdate'
}

nvim-treesitter can be configured by calling setup. You do not need to call setup for nvim-treesitter to work using default values.

require('nvim-treesitter').setup {
  -- Directory to install parsers and queries to (prepended to `runtimepath` to have priority)
  install_dir = vim.fn.stdpath('data') .. '/site'
}

Parsers and queries can then be installed with

require('nvim-treesitter').install { 'rust', 'javascript', 'zig' }

(This is a no-op if the parsers are already installed.) Note that this function runs asynchronously; for synchronous installation in a script context ("bootstrapping"), you need to wait() for it to finish:

require('nvim-treesitter').install({ 'rust', 'javascript', 'zig' }):wait(300000) -- wait max. 5 minutes

Check :h nvim-treesitter-commands for a list of all available commands.

For nvim-treesitter to support a specific feature for a specific language requires both a parser for that language and an appropriate language-specific query file for that feature.

A list of the currently supported languages can be found on this page. If you wish to add a new language or improve the queries for an existing one, please see our contributing guide.

nvim-treesitter provides queries for the following features. These are not automatically enabled.

Treesitter highlighting is provided by Neovim, see :h treesitter-highlight. To enable it for a filetype, put vim.treesitter.start() in a ftplugin/<filetype>.lua in your config directory, or place the following in your init.lua:

vim.api.nvim_create_autocmd('FileType', {
  pattern = { '<filetype>' },
  callback = function() vim.treesitter.start() end,
})

Treesitter-based folding is provided by Neovim. To enable it, put the following in your ftplugin or FileType autocommand:

vim.wo[0][0].foldexpr = 'v:lua.vim.treesitter.foldexpr()'
vim.wo[0][0].foldmethod = 'expr'

Treesitter-based indentation is provided by this plugin but considered experimental. To enable it, put the following in your ftplugin or FileType autocommand:

vim.bo.indentexpr = "v:lua.require'nvim-treesitter'.indentexpr()"

(Note the specific quotes used.)

Injections are used for multi-language documents, see :h treesitter-language-injections. No setup is needed.

These queries can be used to look up definitions and references to identifiers in a given scope. They are not used in this plugin and are provided for (limited) backward compatibility.

If you have a parser that is not on the list of supported languages (either as a repository on Github or in a local directory), you can add it manually for use by nvim-treesitter as follows:

1. Add the following snippet in a User TSUpdate autocommand:

vim.api.nvim_create_autocmd('User', { pattern = 'TSUpdate',
callback = function()
  require('nvim-treesitter.parsers').zimbu = {
    install_info = {
      url = 'https://github.com/zimbulang/tree-sitter-zimbu',
      revision = <sha>, -- commit hash for revision to check out; HEAD if missing
      -- optional entries:
      branch = 'develop', -- only needed if different from default branch
      location = 'parser', -- only needed if the parser is in subdirectory of a "monorepo"
      generate = true, -- only needed if repo does not contain pre-generated `src/parser.c`
      generate_from_json = false, -- only needed if repo does not contain `src/grammar.json` either
      queries = 'queries/neovim', -- also install queries from given directory
    },
  }
end})

Alternatively, if you have a local checkout, you can instead use

    install_info = {
      path = '~/parsers/tree-sitter-zimbu',
      -- optional entries
      location = 'parser',
      generate = true,
      generate_from_json = false,
      queries = 'queries/neovim', -- symlink queries from given directory
    },

This will always use the state of the directory as-is (i.e., branch and revision will be ignored).

1. If the parser name differs from the filetype(s) used by Neovim, you need to register the parser via

vim.treesitter.language.register('zimbu', { 'zu' })

If Neovim does not detect your language's filetype by default, you can use Neovim's vim.filetype.add() to add a custom detection rule.

1. Start nvim and :TSInstall zimbu.

You can use the same approach for overriding parser information. E.g., if you always want to generate the lua parser from grammar, add

vim.api.nvim_create_autocmd('User', { pattern = 'TSUpdate',
callback = function()
  require('nvim-treesitter.parsers').lua.install_info.generate = true
end})

Queries can be placed anywhere in your runtimepath under queries/<language>, with earlier directories taking precedence unless the queries are marked with ; extends; see :h treesitter-query-modelines.