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 Neovim. Please consider the experience with this plug-in as experimental until Tree-Sitter support in Neovim is stable! We recommend using the nightly builds of Neovim if possible. 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".
- Neovim latest stable version or nightly
tar
andcurl
in your path (or alternativelygit
)- A C compiler in your path and libstdc++ installed (Windows users please read this!).
You can install nvim-treesitter
with your favorite package manager (or using the native package
feature of vim, see :h packages
).
NOTE: This plugin is only guaranteed to work with specific versions of language parsers (as specified in the lockfile.json
). 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., if you are using vim-plug, put this in your init.vim
file:
Plug 'nvim-treesitter/nvim-treesitter', {'do': ':TSUpdate'}
For other plugin managers such as packer.nvim
, see this Installation page from the wiki (Note that this page is community maintained).
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_to_install>
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.
To make sure a 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
.
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.
Following examples assume that you are configuring neovim with lua. If you are using vimscript, see :help lua-heredoc
.
All modules are disabled by default and need to be activated explicitly in your init.lua
, e.g., via
require'nvim-treesitter.configs'.setup {
-- One of "all", "maintained" (parsers with maintainers), or a list of languages
ensure_installed = "maintained",
-- Install languages synchronously (only applied to `ensure_installed`)
sync_install = false,
-- List of parsers to ignore installing
ignore_install = { "javascript" },
highlight = {
-- `false` will disable the whole extension
enable = true,
-- NOTE: these are the names of the parsers and not the filetype. (for example if you want to
disable highlighting for the `tex` filetype, you need to include `latex` in this list as this is
the name of the parser)
-- list of language that will be disabled
disable = { "c", "rust" },
-- Setting this to true will run `:h syntax` and tree-sitter at the same time.
-- Set this to `true` if you depend on 'syntax' being enabled (like for indentation).
-- Using this option may slow down your editor, and you may see some duplicate highlights.
-- Instead of true it can also be a list of languages
additional_vim_regex_highlighting = false,
},
}
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.
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.
Experimental parsers are parsers that are maintained, but not stable enough for
daily use yet. They are excluded from automatic installation when
ensure_installed
is set to "maintained"
.
We are looking for maintainers to add more parsers and to write query files for their languages. Check our tracking issue for open language requests.
- bash (maintained by @TravonteD)
- beancount (maintained by @polarmutex)
- bibtex (maintained by @theHamsta, @clason)
- c (maintained by @vigoux)
- c_sharp (maintained by @Luxed)
- clojure (maintained by @sogaiu)
- cmake (maintained by @uyha)
- comment (maintained by @stsewd)
- commonlisp (maintained by @theHamsta)
- cooklang (maintained by @addcninblue)
- cpp (maintained by @theHamsta)
- css (maintained by @TravonteD)
- cuda (maintained by @theHamsta)
- d (experimental, maintained by @nawordar)
- dart (maintained by @Akin909)
- devicetree (maintained by @jedrzejboczar)
- dockerfile (maintained by @camdencheek)
- dot (maintained by @rydesun)
- eex (maintained by @connorlay)
- elixir (maintained by @jonatanklosko, @connorlay)
- elm
- elvish (maintained by @ckafi)
- erlang (maintained by @ostera)
- fennel (maintained by @TravonteD)
- fish (maintained by @ram02z)
- foam (experimental, maintained by @FoamScience)
- fortran
- fusion (maintained by @jirgn)
- Godot (gdscript) (maintained by @Shatur95)
- gleam (maintained by @connorlay)
- Glimmer and Ember (maintained by @alexlafroscia)
- glsl (maintained by @theHamsta)
- go (maintained by @theHamsta, @WinWisely268)
- Godot Resources (gdresource) (maintained by @pierpo)
- gomod (maintained by @camdencheek)
- gowork (maintained by @omertuc)
- graphql (maintained by @bkegley)
- hack
- haskell
- hcl (maintained by @MichaHoffmann)
- heex (maintained by @connorlay)
- help (experimental, maintained by @vigoux)
- hjson (maintained by @winston0410)
- hocon (maintained by @antosha417)
- html (maintained by @TravonteD)
- http (maintained by @NTBBloodbath)
- java (maintained by @p00f)
- javascript (maintained by @steelsojka)
- jsdoc (maintained by @steelsojka)
- json (maintained by @steelsojka)
- json5 (maintained by @Joakker)
- JSON with comments (maintained by @WhyNotHugo)
- julia (maintained by @mroavi, @theHamsta)
- kotlin (maintained by @SalBakraa)
- lalrpop (maintained by @traxys)
- latex (maintained by @theHamsta, @clason)
- ledger (maintained by @cbarrete)
- llvm (maintained by @benwilliamgraham)
- lua (maintained by @muniftanjim)
- make (maintained by @lewis6991)
- markdown
- ninja (maintained by @alemuller)
- nix (maintained by @leo60228)
- norg (maintained by @JoeyGrajciar, @vhyrro, @mrossinek)
- ocaml (maintained by @undu)
- ocaml_interface (maintained by @undu)
- ocamllex (maintained by @undu)
- pascal (maintained by @isopod)
- perl (maintained by @ganezdragon)
- php (maintained by @tk-shirasaka)
- phpdoc (experimental, maintained by @mikehaertl)
- pioasm (maintained by @leo60228)
- prisma (maintained by @elianiva)
- pug (maintained by @zealot128)
- python (maintained by @stsewd, @theHamsta)
- ql (maintained by @pwntester)
- Tree-sitter query language (maintained by @steelsojka)
- r (maintained by @jimhester)
- rasi (maintained by @Fymyte)
- regex (maintained by @theHamsta)
- rego (maintained by @FallenAngel97)
- rst (maintained by @stsewd)
- ruby (maintained by @TravonteD)
- rust (maintained by @vigoux)
- scala (maintained by @stevanmilic)
- scss (maintained by @elianiva)
- slint (experimental, maintained by @jrmoulton)
- solidity (maintained by @YongJieYongJie)
- sparql (maintained by @bonabeavis)
- supercollider (maintained by @madskjeldgaard)
- surface (maintained by @connorlay)
- svelte (maintained by @elianiva)
- swift
- teal (maintained by @euclidianAce)
- tlaplus (maintained by @ahelwer, @susliko)
- todotxt (experimental, maintained by @arnarg)
- toml (maintained by @tk-shirasaka)
- tsx (maintained by @steelsojka)
- turtle (maintained by @bonabeavis)
- typescript (maintained by @steelsojka)
- vala (maintained by @matbme)
- verilog (experimental, maintained by @zegervdv)
- vim (maintained by @vigoux)
- vue (maintained by @WhyNotHugo)
- yaml (maintained by @stsewd)
- yang (maintained by @Hubro)
- zig (maintained by @maxxnino)
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.lua
(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.
Consistent syntax highlighting.
require'nvim-treesitter.configs'.setup {
highlight = {
enable = true,
-- Setting this to true will run `:h syntax` and tree-sitter at the same time.
-- Set this to `true` if you depend on 'syntax' being enabled (like for indentation).
-- Using this option may slow down your editor, and you may see some duplicate highlights.
-- Instead of true it can also be a list of languages
additional_vim_regex_highlighting = false,
},
}
You can add custom highlight captures with:
lua <<EOF
require"nvim-treesitter.highlight".set_custom_captures {
-- Highlight the @foo.bar capture group with the "Identifier" highlight group.
["foo.bar"] = "Identifier",
}
EOF
Incremental selection based on the named nodes from the grammar.
require'nvim-treesitter.configs'.setup {
incremental_selection = {
enable = true,
keymaps = {
init_selection = "gnn",
node_incremental = "grn",
scope_incremental = "grc",
node_decremental = "grm",
},
},
}
Indentation based on treesitter for the =
operator.
NOTE: This is an experimental feature.
require'nvim-treesitter.configs'.setup {
indent = {
enable = true
}
}
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 foldminlines
and foldnestmax
settings.
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.lua
:
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"},
-- optional entries:
branch = "main", -- default branch in case of git repo if different from master
generate_requires_npm = false, -- if stand-alone parser without npm dependencies
requires_generate_from_grammar = false, -- if folder contains pre-generated src/parser.c
},
filetype = "zu", -- if filetype does not match the parser name
}
If you wish to set a specific parser for a filetype, you should extend the filetype_to_parsername
table:
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.
- 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
.
Note that neither :TSInstall
nor :TSInstallFromGrammar
copy query files from the grammar repository.
If you want your installed grammar to be useful, you must manually add query files to your local nvim-treesitter installation.
Note also that module functionality is only triggered if your language's filetype is correctly identified.
If Neovim does not detect your language's filetype by default, you can use Neovim's vim.filetype.add()
(0.7.0 and above) to add a custom detection rule.
If you use a git repository for your parser and want to use a specific version, you can set the revision
key
in the install_info
table for you parser config.
Queries are what nvim-treesitter
uses to extract information from the syntax tree;
they are located in the queries/{language}/*
runtime directories (see :h rtp
),
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
. You can find a
list of all supported capture names in CONTRIBUTING.md.
All queries found in the runtime directories will be combined.
By convention, if you want to write a query, use the queries/
directory,
but if you want to extend a query use the after/queries/
directory.
If you want to completely override a query, you can use :h set_query()
.
For example, to override the injections
queries from c
with your own:
require("vim.treesitter.query").set_query("c", "injections", "(comment) @comment")
Note: when using set_query
, all queries in the runtime directories will be ignored.
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:
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
}
}
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.
echo nvim_treesitter#statusline(90) " 90 can be any length
module->expression_statement->call->identifier
You can get some utility functions with
local ts_utils = require 'nvim-treesitter.ts_utils'
Check :h nvim-treesitter-utils
for more information.
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
.
First, check the health#nvim_treesitter#check
and the health#treesitter#check
sections of :checkhealth
for any warning.
If there is one, it's highly likely that this is the cause of the problem.
Next check the ## Parser/Features
subsection of the health#nvim_treesitter#check
section of :checkhealth
to ensure the desired module is enabled for your language.
If not, you might be missing query files; see Adding queries.
Finally, ensure Neovim is correctly identifying your language's filetype using the :echo &filetype
command while one of your language's files is open in Neovim.
If not, add a short Vimscript file to nvim-treesitter's ftdetect
runtime directory following Neovim's documentation on filetype detection.
You can also quickly & temporarily set the filetype for a single buffer with the :set filetype=langname
command to test whether it fixes the problem.
If everything is okay, then it might be an actual error. In that case, feel free to open an issue here.
Make sure you have the latest version of Neovim.
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.
This could be due a query file outside this plugin using outdated nodes, or due to an outdated parser.
- Make sure you have the parsers up to date with
:TSUpdate
- Make sure you don't have more than one
parser
runtime directory. You can execute this command:echo nvim_get_runtime_file('parser', v:true)
to find all runtime directories. If you get more than one path, remove the ones that are outside this plugin (nvim-treesitter
directory), so the correct version of the parser is used.
I experience weird highlighting issues similar to #78
This 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.
I experience bugs when using nvim-treesitter
's foldexpr
similar to #194
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.
This is because of rtp
management in nvim
, adding packadd nvim-treesitter
should fix the issue.
In your Lua config:
require("nvim-treesitter.install").prefer_git = true
You can either configure curl to use additional CLI arguments in your Lua config:
require("nvim-treesitter.install").command_extra_args = {
curl = { "--proxy", "<proxy url>" },
}
or you can configure git via .gitconfig
and use git instead of curl
require("nvim-treesitter.install").prefer_git = true
I want to use a mirror instead of "https://github.com/"
In your Lua config:
for _, config in pairs(require("nvim-treesitter.parsers").get_parser_configs()) do
config.install_info.url = config.install_info.url:gsub("https://github.com/", "something else")
end
require'nvim-treesitter.configs'.setup {
--
--
}