Treesitter Setup Flow#

This page explains how the Treesitter setup resolves parser lists, loads the plugins, and installs parsers during headless bootstrap runs.

High-level structure#

lua/plugins/treesitter/config.lua
|-- get_ensure_installed()
|-- ensure_treesitter_parsers()
`-- setup_treesitter()

lua/vvn/profile_config.lua
`-- get_treesitter_ensure_installed()

High-level flow#

  • vvn.profile resolves the active profile from VVN_NVIM_PROFILE or VVN_DOTFILES_PROFILE.

  • vvn.profile_config returns the parser list for that profile.

  • setup_treesitter() sets up nvim-treesitter, starts Treesitter for loaded buffers, and enables the textobject mappings.

  • Headless bootstrap runs can wait for parser installation with NVIM_TREESITTER_SYNC_INSTALL=1.

Plugin load model#

config.lua#
160local M = {
161  {
162    "nvim-treesitter/nvim-treesitter",
163    branch = "main",
164    lazy = false,
165    build = ":TSUpdate",
166    dependencies = {
167      "nvim-treesitter/nvim-treesitter-textobjects",
168    },
169    config = setup_treesitter,
170  },
171  {
172    "nvim-treesitter/nvim-treesitter-textobjects",
173    branch = "main",
174    lazy = false,
175  },

nvim-treesitter and nvim-treesitter-textobjects both load eagerly, and both use the main branch.

Headless parser install flow#

config.lua#
133---@param languages string[]
134---@param sync_install boolean
135---@return nil
136local ensure_treesitter_parsers = function(languages, sync_install)
137  if #languages == 0 then
138    return
139  end
140
141  local installer = require("nvim-treesitter").install(languages, { summary = true })
142  if not sync_install or not installer then
143    return
144  end
145
146  installer:wait(300000)
147end

The install helper skips empty parser lists, requests the configured parsers, and waits only when the caller set NVIM_TREESITTER_SYNC_INSTALL=1.

Relevant changelogs#