feat(setup)!: remove ensure_install field

Instead, call `require('nvim-treesitter').install( { ... } )` manually.

This gives users full control over how they want to install parsers
(sync, from grammar, limited concurrency) and obviates the need for
calling `setup` for most users.

.luarc.json

@@ -5,12 +5,13 @@
   },
   "workspace": {
     "library": [
-      "lua",
       "$VIMRUNTIME",
-      "${3rd}/luv/library",
       "${3rd}/busted/library"
     ],
-    "checkThirdParty": false
+    "ignoreDir": [
+      "tests"
+    ],
+    "checkThirdParty": "Disable"
   },
   "diagnostics": {
     "groupFileStatus": {

README.md

@@ -53,17 +53,21 @@ require('lazy').setup(
 
 ```lua
 require'nvim-treesitter'.setup {
-  -- A list of parser names or tiers ('stable', 'unstable')
-  ensure_install = { 'stable' },
-
-  -- List of parsers to ignore when installing tiers
-  ignore_install = { 'rust' },
-
   -- Directory to install parsers and queries to
   install_dir = vim.fn.stdpath('data') .. '/site'
+  -- List of parsers to ignore when installing tiers
+  ignore_install = { },
 }
 ```
 
+Parsers and queries can then be installed with
+
+```lua
+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"), adapt [this script](scripts/install-parsers.lua) to your needs.
+
 Check [`:h nvim-treesitter-commands`](doc/nvim-treesitter.txt) for a list of all available commands.
 
 # Supported languages

TODO.md

@@ -4,7 +4,6 @@ This document lists the planned and finished changes in this rewrite towards [Nv
 
 ## TODO
 
-- [ ] **`config.lua`:** drop ensure_install (replace with install), ignore_install
 - [ ] **`install.lua`:** simply skip Tier 4 parsers (`get_install_info`)
 - [ ] **`parsers.lua`:** allow specifying version in addition to commit hash (for Tier 1)
 - [ ] **`parsers.lua`:** add WASM support (tier 1)
@@ -31,3 +30,4 @@ This document lists the planned and finished changes in this rewrite towards [Nv
 - [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)

doc/nvim-treesitter.txt

@@ -22,34 +22,24 @@ WARNING: This is work in progress and requires the latest commit on Neovim
 ==============================================================================
 QUICK START                                       *nvim-treesitter-quickstart*
 
-Install the parser for your language
+To configure `nvim-treesitter`, put this in your `init.lua` file:
-
->vim
-  :TSInstall {language}
-<
-
-To get a list of supported languages
-
->vim
-  :TSInstall <tab>
-<
-
-To install supported parsers and queries, put this in your `init.lua` file:
-
 >lua
-  require'nvim-treesitter.config'.setup {
+  require'nvim-treesitter'.setup {
     -- A directory to install the parsers and queries to.
     -- Defaults to the `stdpath('data')/site` dir.
     install_dir = "/some/path/to/store/parsers",
-
-    -- A list of parser names, or "stable", "unstable", "unmaintained", "unsupported"
-    ensure_install = { "stable", "rust" },
-
     -- List of parsers to ignore installing (for "stable" etc.)
-    ignore_install = { "javascript" },
+    ignore_install = { "some_parser" },
   }
 
+NOTE: You do not need to call `setup` to use this plugin with the default
+settings!
+
+Parsers and queries can then be installed with >lua
+    require'nvim-treesitter'.install { 'rust', 'javascript', 'zig' }
 <
+(This is a no-op if the parsers are already installed.)
+
 To check installed parsers and queries, use `:checkhealth nvim-treesitter`.
 
 ==============================================================================

lua/nvim-treesitter/config.lua

@@ -3,13 +3,11 @@ local M = {}
 M.tiers = { 'stable', 'unstable', 'unmaintained', 'unsupported' }
 
 ---@class TSConfig
----@field ensure_install string[]
 ---@field ignore_install string[]
 ---@field install_dir string
 
 ---@type TSConfig
 local config = {
-  ensure_install = {},
   ignore_install = {},
   install_dir = vim.fs.joinpath(vim.fn.stdpath('data'), 'site'),
 }
@@ -20,21 +18,10 @@ function M.setup(user_data)
   if user_data then
     if user_data.install_dir then
       user_data.install_dir = vim.fs.normalize(user_data.install_dir)
-      --TODO(clason): leave to user!
       vim.opt.runtimepath:append(user_data.install_dir)
     end
     config = vim.tbl_deep_extend('force', config, user_data)
   end
-
-  if #config.ensure_install > 0 then
-    local to_install = M.norm_languages(
-      config.ensure_install,
-      { ignored = true, installed = true, unsupported = true }
-    )
-    if #to_install > 0 then
-      require('nvim-treesitter.install').install(to_install, { force = true })
-    end
-  end
 end
 
 -- Returns the install path for parsers, parser info, and queries.

lua/nvim-treesitter/init.lua

@@ -4,6 +4,18 @@ function M.setup(...)
   require('nvim-treesitter.config').setup(...)
 end
 
+function M.install(...)
+  require('nvim-treesitter.install').install(...)
+end
+
+function M.uninstall(...)
+  require('nvim-treesitter.install').uninstall(...)
+end
+
+function M.update(...)
+  require('nvim-treesitter.install').update(...)
+end
+
 function M.indentexpr()
   return require('nvim-treesitter.indent').get_indent(vim.v.lnum)
 end

scripts/minimal_init.lua

@@ -1,13 +1,11 @@
 vim.opt.runtimepath:append('.')
 vim.cmd.runtime({ 'plugin/plenary.vim', bang = true })
-vim.cmd.runtime({ 'plugin/nvim-treesitter.lua', bang = true })
 vim.cmd.runtime({ 'plugin/query_predicates.lua', bang = true })
 vim.cmd.runtime({ 'plugin/filetypes.lua', bang = true })
 
 vim.filetype.add({
   extension = {
     conf = 'hocon',
-    hurl = 'hurl',
     ncl = 'nickel',
     tig = 'tiger',
     w = 'wing',
@@ -17,7 +15,6 @@ vim.filetype.add({
 vim.o.swapfile = false
 vim.bo.swapfile = false
 
-require('nvim-treesitter').setup()
 vim.api.nvim_create_autocmd('FileType', {
   callback = function(args)
     pcall(vim.treesitter.start)