From b19b5ce17195f830fd2474c625e242cfc3aa5f90 Mon Sep 17 00:00:00 2001 From: Christian Clason Date: Sun, 18 May 2025 10:37:50 +0200 Subject: docs: final update after rewrite Make clear this is not the default branch --- CONTRIBUTING.md | 6 +++--- README.md | 47 +++++++++++++++++++++++++---------------------- TODO.md | 28 ---------------------------- 3 files changed, 28 insertions(+), 53 deletions(-) delete mode 100644 TODO.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 983499e81..f665ce1ed 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -22,15 +22,15 @@ To add a new parser, edit the following files: zimbu = { install_info = { url = 'https://github.com/zimbulang/tree-sitter-zimbu', -- git repo; use `path` for local path - revision = 'v2.1', -- tag or commit hash, will be updated automatically + revision = 'v2.1', -- tag or commit hash -- 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 = true, -- only needed if grammar.js has npm-installed dependencies + generate_from_json = false, -- only needed if repo does not contain `src/grammar.json` either }, maintainers = { '@me' }, -- the _query_ maintainers - tier = 1, -- stable: track versioned releases + tier = 1, -- stable: track versioned releases instead of latest commit -- optional entries: requires = { 'vim' }, -- if the queries inherit from another language readme_note = "an example language", diff --git a/README.md b/README.md index 703a41781..ef3a9f32c 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,17 @@

nvim-treesitter

-
-

- - Matrix Chat - - - Linting and Style - - - Syntax files - -

-
- - ->[!WARNING] -> This branch is a [full, incompatible, rewrite of `nvim-treesitter`](https://github.com/nvim-treesitter/nvim-treesitter/issues/4767) and [work in progress](TODO.md). The **stable** branch is [`master`](https://github.com/nvim-treesitter/nvim-treesitter/tree/master). The `nvim-treesitter` plugin provides 1. functions for installing, updating, and removing [**tree-sitter parsers**](SUPPORTED_LANGUAGES.md); -2. a collection of **queries** for enabling tree-sitter features built into Neovim for these languages. +2. a collection of **queries** for enabling tree-sitter features built into Neovim for these languages; +3. a staging ground for [treesitter-based features](#Supported-features) considered for upstreaming to Neovim. For details on these and how to help improving them, see [CONTRIBUTING.md](./CONTRIBUTING.md). +>[!CAUTION] +> This is a full, incompatible, rewrite. If you can't or don't want to update, check out the [`master` branch](https://github.com/nvim-treesitter/nvim-treesitter/blob/master/README.md) (which is locked but will remain available for backward compatibility). + # Quickstart ## Requirements @@ -35,6 +22,12 @@ For details on these and how to help improving them, see [CONTRIBUTING.md](./CON - a C compiler in your path (see ) - `Node` (23.0.0 or later) for some parsers (see the [list of supported languages](SUPPORTED_LANGUAGES.md)) +>[!IMPORTANT] +> The **support policy** for Neovim is +> 1. the _latest_ [stable release](https://github.com/neovim/neovim/releases/tag/stable); +> 2. the _latest_ [nightly prerelease](https://github.com/neovim/neovim/releases/tag/nightly). +> Other versions may work but are neither tested nor considered for fixes. In general, compatibility with Nvim 0.X is removed after the release of Nvim 0.(X+1).1. + ## Installation You can install `nvim-treesitter` with your favorite package manager (or using the native `package` feature of vim, see `:h packages`). @@ -43,14 +36,20 @@ This plugin is only guaranteed to work with specific versions of language parser It is strongly recommended to automate this; e.g., using [lazy.nvim](https://github.com/folke/lazy.nvim) ```lua -require('lazy').setup( - { 'nvim-treesitter/nvim-treesitter', build = ':TSUpdate', lazy = false } -) +require('lazy').setup({ + 'nvim-treesitter/nvim-treesitter', + lazy = false, + branch = 'main', + build = ':TSUpdate' +}) ``` >[!IMPORTANT] > This plugin does not support lazy-loading. +>[!IMPORTANT] +> Make sure to specify the `main` branch since (for now) the default branch is [`master`](https://github.com/nvim-treesitter/nvim-treesitter/blob/master/README.md). + ## Setup `nvim-treesitter` can be configured by calling `setup`. The following snippet lists the available options and their default values. **You do not need to call `setup` for `nvim-treesitter` to work using default values.** @@ -69,6 +68,7 @@ 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: + ```lua require('nvim-treesitter').install({ 'rust', 'javascript', 'zig' }):wait(300000) -- wait max. 5 minutes ``` @@ -143,13 +143,14 @@ callback = function() 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` + generate_from_json = false, -- only needed if repo does not contain `src/grammar.json` either }, } end}) ``` Alternatively, if you have a local checkout, you can instead use + ```lua install_info = { path = '~/parsers/tree-sitter-zimbu', @@ -177,6 +178,7 @@ If Neovim does not detect your language's filetype by default, you can use [Neov ### Modifying parsers You can use the same approach for overriding parser information. E.g., if you always want to generate the `lua` parser from grammar, add + ```lua vim.api.nvim_create_autocmd('User', { pattern = 'TSUpdate', callback = function() @@ -189,6 +191,7 @@ end}) Queries can be placed anywhere in your `runtimepath` under `queries/`, with earlier directories taking precedence unless the queries are marked with `; extends`; see [`:h treesitter-query-modelines`](https://neovim.io/doc/user/treesitter.html#treesitter-query-modeline). E.g., to add queries for `zimbu`, put `highlights.scm` etc. under + ```lua vim.fn.stdpath('data') .. 'site/queries/zimbu' ``` diff --git a/TODO.md b/TODO.md deleted file mode 100644 index 937a8b63b..000000000 --- a/TODO.md +++ /dev/null @@ -1,28 +0,0 @@ -# Roadmap - -This document lists the planned and finished changes in this rewrite towards [Nvim-treesitter 1.0](https://github.com/nvim-treesitter/nvim-treesitter/issues/4767). - -## TODO - -- [ ] **tests:** remove custom crate, plenary dependency -- [ ] **indents:** rewrite (Helix or Zed compatible) -- [ ] **textobjects:** include simple(!) `node`, `scope` (using `locals`) objects - -## DONE - -- [X] remove module framework -- [X] remove extra utilities -- [X] refactor `indent.lua` into standalone -- [X] refactor `locals.lua` into standalone -- [X] refactor commands, predicates, filetypes registration to plugin/ -- [X] support installing tiers of parsers -- [X] install parsers to standard directory by default -- [X] remove bundled queries from runtimepath; copy on parser install -- [X] general refactor and cleanup -- [X] rewrite installation using async module (drop support for sync; use callback instead) -- [X] switch to upstream injection format -- [X] remove locals from highlighting (cf. https://github.com/nvim-treesitter/nvim-treesitter/issues/3944#issuecomment-1458782497) -- [X] drop ensure_install (replace with install) -- [X] **CI:** switch to ts_query_ls, add update readme as check (remove update job) -- [X] **CI:** track versioned releases for tier 1 -- [X] **`install.lua`:** migrate to async v2 -- cgit v1.2.3-70-g09d2