The goal of nvim-treesitter
is both to provide a simple and easy way to use the interface for tree-sitter in Neovim and to provide some basic functionality such as highlighting based on it:
Traditional highlighting (left) vs Treesitter-based highlighting (right). More examples can be found in our gallery.
Warning: Treesitter and nvim-treesitter highlighting are an experimental feature of nightly versions of Neovim. Please consider the experience with this plug-in as experimental until Neovim 0.5 is released! You can find the current roadmap here. The roadmap and all features of this plugin are open to change, and any suggestion will be highly appreciated!
Nvim-treesitter is based on three interlocking features: language parsers, queries, and modules, where modules provide features โ e.g., highlighting โ based on queries for syntax objects extracted from a given buffer by language parsers. Users will generally only need to interact with parsers and modules as explained in the next section. For more detailed information on setting these up, see "Advanced setup".
Table of contents
Quickstart
Requirements
- Neovim nightly
tar
andcurl
in your path (or alternativlygit
)- A C compiler in your path and libstdc++ installed (Windows users please read this!).
Installation
You can install nvim-treesitter
with your favorite package manager (or using the native package
feature of vim, see :h packages
).
E.g., if you are using vim-plug, put this in your init.vim
file:
Plug 'nvim-treesitter/nvim-treesitter', {'do': ':TSUpdate'} " We recommend updating the parsers on update
Language parsers
Treesitter uses a different parser for every language, which needs to be generated via tree-sitter-cli
from a grammar.js
file, then compiled to a .so
library that needs to be placed in neovim's runtimepath
(typically under parser/{language}.so
).
To simplify this, nvim-treesitter
provides commands to automate this process.
If the language is already supported by nvim-treesitter
, you can install it with
:TSInstall {language}
This command supports tab expansion.
You can also get a list of all available languages and their installation status with :TSInstallInfo
.
Parsers not on this list can be added manually by following the steps described under "Adding parsers" below.
If you update nvim-treesitter
and want to make sure the parser is at the latest compatible version (as specified in nvim-treesitter
's lockfile.json
), use :TSUpdate {language}
.
To update all parsers unconditionally, use :TSUpdate all
or just :TSUpdate
.
Modules
Each module provides a distinct tree-sitter-based feature such as highlighting, indentation, or folding; see :h nvim-treesitter-modules
or "Available modules" below for a list of modules and their options.
All modules are disabled by default and need to be activated explicitly in your init.vim
, e.g., via
lua <<EOF
require'nvim-treesitter.configs'.setup {
ensure_installed = "maintained", -- one of "all", "maintained" (parsers with maintainers), or a list of languages
ignore_install = { "javascript" }, -- List of parsers to ignore installing
highlight = {
enable = true, -- false will disable the whole extension
disable = { "c", "rust" }, -- list of language that will be disabled
},
}
EOF
Each module can also be enabled or disabled interactively through the following commands:
:TSBufEnable {module} " enable module on current buffer
:TSBufDisable {module} " disable module on current buffer
:TSEnableAll {module} [{ft}] " enable module on every buffer. If filetype is specified, enable only for this filetype.
:TSDisableAll {module} [{ft}] " disable module on every buffer. If filetype is specified, disable only for this filetype.
:TSModuleInfo [{module}] " list information about modules state for each filetype
Check :h nvim-treesitter-commands
for a list of all available commands.
It may be necessary to reload the buffer (e.g., via :e
) after enabling a module interactively.
Supported languages
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.
The following is a list of languages for which a parser can be installed through :TSInstall
; a checked box means that nvim-treesitter
also contains queries at least for the highlight
module.
We are looking for maintainers to add more parsers and to write query files for their languages.
- bash (maintained by @TravonteD)
- beancount (maintained by @polarmutex)
- bibtex (maintained by @theHamsta by asking @clason)
- c (maintained by @vigoux)
- c_sharp (maintained by @Luxed)
- clojure (maintained by @sogaiu)
- comment (maintained by @stsewd)
- commonlisp (maintained by @theHamsta)
- cpp (maintained by @theHamsta)
- css (maintained by @TravonteD)
- dart (maintained by @Akin909)
- devicetree (maintained by @jedrzejboczar)
- dockerfile (maintained by @camdencheek)
- elixir (maintained by @nifoc)
- elm
- erlang (maintained by @ostera)
- fennel (maintained by @TravonteD)
- fish (maintained by @krnik, @ram02z)
- fortran
- Godot (gdscript) (maintained by @Shatur95)
- Glimmer and Ember (maintained by @alexlafroscia)
- go (maintained by @theHamsta, @WinWisely268)
- gomod (maintained by @camdencheek)
- graphql (maintained by @bkegley)
- haskell
- html (maintained by @TravonteD)
- java (maintained by @p00f)
- javascript (maintained by @steelsojka)
- jsdoc (maintained by @steelsojka)
- json (maintained by @steelsojka)
- JSON with comments (maintained by @WhyNotHugo)
- julia (maintained by @mroavi, @theHamsta)
- kotlin (maintained by @tormodatt)
- latex (maintained by @theHamsta by asking @clason)
- ledger (maintained by @cbarrete)
- lua (maintained by @vigoux)
- nix (maintained by @leo60228)
- ocaml (maintained by @undu)
- ocaml_interface (maintained by @undu)
- ocamllex (maintained by @undu)
- php (maintained by @tk-shirasaka)
- python (maintained by @stsewd, @theHamsta)
- ql (maintained by @pwntester)
- Tree-sitter query language (maintained by @steelsojka)
- r (maintained by @jimhester)
- regex (maintained by @theHamsta)
- rst (maintained by @stsewd)
- ruby (maintained by @TravonteD)
- rust (maintained by @vigoux)
- scala
- scss (maintained by @elianiva)
- sparql (maintained by @bonabeavis)
- supercollider (maintained by @madskjeldgaard)
- svelte (maintained by @elianiva)
- swift
- teal (maintained by @euclidianAce)
- toml (maintained by @tk-shirasaka)
- tsx (maintained by @steelsojka)
- turtle (maintained by @bonabeavis)
- typescript (maintained by @steelsojka)
- verilog (maintained by @zegervdv)
- vue (maintained by @WhyNotHugo)
- yaml (maintained by @stsewd)
- zig (maintained by @Himujjal)
Available modules
Modules provide the top-level features of nvim-treesitter
.
The following is a list of modules included in nvim-treesitter
and their configuration via init.vim
(where multiple modules can be combined in a single call to setup
).
Note that not all modules work for all languages (depending on the queries available for them).
Additional modules can be provided as external plugins.
Highlight
Consistent syntax highlighting.
lua <<EOF
require'nvim-treesitter.configs'.setup {
highlight = {
enable = true,
custom_captures = {
-- Highlight the @foo.bar capture group with the "Identifier" highlight group.
["foo.bar"] = "Identifier",
},
},
}
EOF
Incremental selection
Incremental selection based on the named nodes from the grammar.
lua <<EOF
require'nvim-treesitter.configs'.setup {
incremental_selection = {
enable = true,
keymaps = {
init_selection = "gnn",
node_incremental = "grn",
scope_incremental = "grc",
node_decremental = "grm",
},
},
}
EOF
Indentation
Tree-sitter based indentation.
lua <<EOF
require'nvim-treesitter.configs'.setup {
indent = {
enable = true
}
}
EOF
Folding
Tree-sitter based folding. (Technically not a module because it's per windows and not per buffer.)
set foldmethod=expr
set foldexpr=nvim_treesitter#foldexpr()
This will respect your foldnestmax
setting.
Advanced setup
Adding parsers
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:
- Clone the repository or create a new project in, say,
~/projects/tree-sitter-zimbu
. Make sure that thetree-sitter-cli
executable is installed and in your path; see https://tree-sitter.github.io/tree-sitter/creating-parsers#installation for installation instructions. - Run
tree-sitter generate
in this directory (followed bytree-sitter test
for good measure). - Add the following snippet to your
init.vim
:
lua <<EOF
local parser_config = require "nvim-treesitter.parsers".get_parser_configs()
parser_config.zimbu = {
install_info = {
url = "~/projects/tree-sitter-zimbu", -- local path or git repo
files = {"src/parser.c"}
},
filetype = "zu", -- if filetype does not agrees with parser name
used_by = {"bar", "baz"} -- additional filetypes that use this parser
}
EOF
- Start
nvim
and:TSInstall zimbu
.
You can also skip step 2 and use :TSInstallFromGrammar zimbu
to install directly from a grammar.js
in the top-level directory specified by url
.
Once the parser is installed, you can update it (from the latest revision of the main
branch if url
is a Github repository) with :TSUpdate zimbu
.
Update parsers used_by
Sometimes needs to use some parser for different filetype.
Add the following snippet to your init.vim
:
lua <<EOF
local parser_config = require "nvim-treesitter.parsers".get_parser_configs()
parser_config.typescript.used_by = "javascriptflow"
EOF
Adding queries
Queries are what nvim-treesitter
uses to extract informations from the syntax tree; they are
located in the queries/{language}/*
runtime directories (like the queries
folder of this plugin), e.g., queries/{language}/{locals,highlights,textobjects}.scm
.
Other modules may require additional queries such as folding.scm
.
nvim-treesitter
considers queries as any runtime file (see :h rtp
), i.e.,
- if the file is in any
after/queries/
folder, then it will be used to extend the already defined queries. - Otherwise, it will be used as a base to define the query, the first query found (with the highest priority) will be the only one to be used.
This hybrid approach is the most standard way; in this case
- if you want to rewrite (or write) a query, don't use
after/queries
; - if you want to override a part of a query (only one match for example), use the
after/queries
directory.
Adding modules
If you wish you write your own module, you need to support
- tree-sitter language detection support;
- attaching and detaching to buffers;
- all nvim-treesitter commands.
At the top level, you can use the define_modules
function to define one or more modules or module groups:
lua <<EOF
require'nvim-treesitter'.define_modules {
my_cool_plugin = {
attach = function(bufnr, lang)
-- Do cool stuff here
end,
detach = function(bufnr)
-- Undo cool stuff here
end,
is_supported = function(lang)
-- Check if the language is supported
end
}
}
EOF
with the following properties:
module_path
specifies a require path (string) that exports a module with anattach
anddetach
function. This is not required if the functions are on this definition.enable
determines if the module is enabled by default. This is usually overridden by the user.disable
takes a list of languages that this module is disabled for. This is usually overridden by the user.is_supported
takes a function that takes a language and determines if this module supports that language.attach
takes a function that attaches to a buffer. This is required ifmodule_path
is not provided.detach
takes a function that detaches from a buffer. This is required ifmodule_path
is not provided.
Extra features
Statusline indicator
echo nvim_treesitter#statusline(90) " 90 can be any length
module->expression_statement->call->identifier
Utilities
You can get some utility functions with
local ts_utils = require 'nvim-treesitter.ts_utils'
Check :h nvim-treesitter-utils
for more information.
Troubleshooting
Before doing anything, make sure you have the latest version of this plugin and run :checkhealth nvim_treesitter
.
It can also help to update the parsers via :TSUpdate
.
X
does not work for {language}
...
Feature First, check the ## {language} parser healthcheck
section of :checkhealth
for any warning.
If there is one, it's highly likely that this is the cause of the problem.
If everything is okay, then it might be an actual error.
In that case, feel free to open an issue here.
module 'vim.treesitter.query' not found
I get Make sure you have the latest nightly version of Neovim.
Error detected while processing .../plugin/nvim-treesitter.vim
every time I open Neovim
I get This is probably due to a change in a parser's grammar or its queries.
Try updating the parser that you suspect has changed (:TSUpdate {language}
) or all of them (:TSUpdate
).
If the error persists after updating all parsers,
please open an issue.
#78
I experience weird highlighting issues similar toThis is a well known issue, which arises when the tree and the buffer have gotten out of sync. As this is an upstream issue, we don't have any definite fix. To get around this, you can force reparsing the buffer with
:write | edit | TSBufEnable highlight
This will save, restore and enable highlighting for the current buffer.
nvim-treesitter
's foldexpr
similar to #194
I experience bugs when using This might happen, and is known to happen, with vim-clap
.
To avoid these kind of errors, please use setlocal
instead of set
for the respective filetypes.
module 'nvim-treesitter.configs' not found
at startup
I run into errors like This is because of rtp
management in nvim
, adding packadd nvim-treesitter
should fix the issue.