Treesitter

For decades, Vim's syntax highlighting relied on regular expressions -- clever pattern matching that could approximate your code's structure but never truly understand it. Treesitter changes the game by building a real parse tree of your source code, giving Neovim a deep, structural understanding of what you've written. The result is more accurate highlighting, smarter indentation, and powerful text objects that operate on actual language constructs like functions, classes, and arguments.

Treesitter is a parsing library that builds a concrete syntax tree of your code. In Neovim, it powers better syntax highlighting, code navigation, and text objects -- all language-aware.

What you'll learn in this chapter:

• Understand how Treesitter differs from regex-based syntax highlighting

• Install and manage Treesitter parsers for your languages

• Use language-aware text objects to select, change, and delete functions, classes, and parameters

• Navigate code structurally with Treesitter motions

• Inspect the syntax tree to debug queries and understand code structure

Why Treesitter?

Traditional syntax highlighting in Vim is based on regular expressions. This is fast but imprecise — it can't truly "understand" code structure. Treesitter builds a parse tree, giving Neovim actual understanding of your code.

Feature	Regex-based	Treesitter
Syntax highlighting	Pattern matching	Structure-aware
Indentation	Heuristic	Accurate
Text objects	Generic (iw, ip)	Language-aware (if = inner function)
Folding	Manual / indent-based	AST-based
Performance	Fast	Fast (incremental parsing)

Setup

The following plugin spec uses Lua (see Chapter 11: Neovim with Lua for Lua configuration basics):

-- lua/plugins/treesitter.lua
return {
    'nvim-treesitter/nvim-treesitter',
    build = ':TSUpdate',
    event = { 'BufReadPost', 'BufNewFile' },
    dependencies = {
        'nvim-treesitter/nvim-treesitter-textobjects',
    },
    config = function()
        require('nvim-treesitter.configs').setup({
            ensure_installed = {
                'lua', 'vim', 'vimdoc', 'query',
                'python', 'javascript', 'typescript',
                'go', 'rust', 'c', 'cpp',
                'html', 'css', 'json', 'yaml', 'toml',
                'bash', 'markdown', 'markdown_inline',
                'regex', 'diff', 'gitcommit',
            },
            auto_install = true,
            highlight = {
                enable = true,
                additional_vim_regex_highlighting = false,
            },
            indent = {
                enable = true,
            },
            incremental_selection = {
                enable = true,
                keymaps = {
                    init_selection = '<C-space>',
                    node_incremental = '<C-space>',
                    scope_incremental = false,
                    node_decremental = '<bs>',
                },
            },
        })
    end,
}

Managing Parsers

:TSInstall python       " Install a parser
:TSUpdate               " Update all parsers
:TSInstallInfo          " Show installed parsers
:TSModuleInfo           " Show enabled modules
:InspectTree            " Show the syntax tree (great for learning!)

Treesitter Text Objects

This is where Treesitter truly shines. With nvim-treesitter-textobjects, you get language-aware text objects:

-- Add to the treesitter config above:
textobjects = {
    select = {
        enable = true,
        lookahead = true,  -- Jump forward to matching text object
        keymaps = {
            ['af'] = '@function.outer',    -- a function
            ['if'] = '@function.inner',    -- inner function
            ['ac'] = '@class.outer',       -- a class
            ['ic'] = '@class.inner',       -- inner class
            ['aa'] = '@parameter.outer',   -- a argument/parameter
            ['ia'] = '@parameter.inner',   -- inner argument
            ['ai'] = '@conditional.outer', -- a if/conditional
            ['ii'] = '@conditional.inner', -- inner conditional
            ['al'] = '@loop.outer',        -- a loop
            ['il'] = '@loop.inner',        -- inner loop
            ['a/'] = '@comment.outer',     -- a comment
        },
    },
    move = {
        enable = true,
        set_jumps = true,
        goto_next_start = {
            [']f'] = '@function.outer',
            [']c'] = '@class.outer',
            [']a'] = '@parameter.inner',
        },
        goto_next_end = {
            [']F'] = '@function.outer',
            [']C'] = '@class.outer',
        },
        goto_previous_start = {
            ['[f'] = '@function.outer',
            ['[c'] = '@class.outer',
            ['[a'] = '@parameter.inner',
        },
        goto_previous_end = {
            ['[F'] = '@function.outer',
            ['[C'] = '@class.outer',
        },
    },
    swap = {
        enable = true,
        swap_next = {
            ['<leader>sa'] = '@parameter.inner', -- swap argument with next
        },
        swap_previous = {
            ['<leader>sA'] = '@parameter.inner', -- swap argument with prev
        },
    },
},

Example Workflows

With these text objects, you can:

• daf — Delete an entire function

• cif — Change the function body

• vac — Select an entire class

• yia — Yank a function parameter

• ]f — Jump to the next function

• [c — Jump to the previous class

• <leader>sa — Swap a parameter with the next one

Tip: These text objects work across all languages that have Treesitter parsers. Write Python, Go, Rust, JavaScript -- the same keybindings work everywhere.

Incremental Selection

Treesitter can expand your selection based on the syntax tree:

1. Press Ctrl+Space to start selection on the current node

2. Press Ctrl+Space again to expand to the parent node

3. Press Backspace to shrink selection back

This is much smarter than viw → vis → vip because it follows the actual code structure.

Treesitter Playground

To see the syntax tree for your code, use the built-in inspector:

:InspectTree

This opens a split window showing the AST (Abstract Syntax Tree) of your code. As you move your cursor, the corresponding tree node is highlighted. This is invaluable for:

• Understanding how Treesitter sees your code

• Debugging text object queries

• Learning about AST structures

Note: Treesitter handles syntax-level understanding (highlighting, text objects, indentation), while LSP (see Chapter 13: LSP) handles project-level intelligence (go-to-definition, diagnostics, refactoring). They are complementary features and work best when both are enabled.

Summary

Treesitter gives Neovim a structural understanding of your code by building a real parse tree rather than relying on regex patterns. This enables accurate syntax highlighting, smart indentation, and powerful language-aware text objects that let you operate on functions, classes, parameters, and other constructs across any supported language.

Key takeaways:

• Treesitter replaces regex-based syntax highlighting with structure-aware parsing, resulting in more accurate and consistent highlighting.

• The nvim-treesitter-textobjects plugin unlocks text objects like af (a function), ic (inner class), and ia (inner argument) that work uniformly across all languages with Treesitter parsers.

• Incremental selection (Ctrl+Space / Backspace) expands and shrinks selections based on the actual syntax tree, not just word or paragraph boundaries.

• :InspectTree is an essential debugging tool for understanding how Treesitter parses your code and for writing custom queries.

Exercises

1. Install Treesitter parsers -- Add the Treesitter plugin to your configuration and install parsers for at least three languages you use. Verify they are installed by running :TSInstallInfo.

2. Use Treesitter text objects -- Open a source file that contains functions and classes. Practice using daf (delete a function), cif (change inner function), vac (select a class), and yia (yank an inner argument). Observe how they operate on actual language constructs.

3. Navigate with Treesitter motions -- Configure the move module of nvim-treesitter-textobjects. Use ]f to jump to the next function and [c to jump to the previous class in a source file.

4. Explore the syntax tree -- Open a source file and run :InspectTree. Move your cursor through the code and observe how the AST nodes are highlighted. Identify the node types for a function definition, a parameter, and a string literal.

5. Swap function parameters -- Configure the swap module and use <leader>sa to swap a function parameter with the next one. Test it on a function call with multiple arguments.