From 7eb61f53ae45835c08310b086fb4d55894a7abfa Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sun, 4 Jan 2026 15:18:29 +1100 Subject: [PATCH 001/170] doc(#2934): POC to use gen_vimdoc.lua for decorator meta --- doc/decorator.txt | 66 +++ lua/nvim-tree/_meta/api_decorator.lua | 24 +- scripts/doc.sh | 24 + scripts/gen_vimdoc.decorator.lua | 49 ++ scripts/gen_vimdoc.lua | 823 ++++++++++++++++++++++++++ 5 files changed, 973 insertions(+), 13 deletions(-) create mode 100644 doc/decorator.txt create mode 100755 scripts/doc.sh create mode 100644 scripts/gen_vimdoc.decorator.lua create mode 100755 scripts/gen_vimdoc.lua diff --git a/doc/decorator.txt b/doc/decorator.txt new file mode 100644 index 00000000000..1ddde49ffa0 --- /dev/null +++ b/doc/decorator.txt @@ -0,0 +1,66 @@ +*decorator.txt* nvim-tree decorators + +============================================================================== +============================================================================== +Lua module: nvim_tree.api.decorator *nvim-tree-decorators* + +*nvim_tree.api.decorator.UserDecorator* + Custom decorator, see :help nvim-tree-decorators + + Fields: ~ + • {enabled} (`boolean`) + • {highlight_range} (`nvim_tree.api.decorator.HighlightRange`) + • {icon_placement} (`nvim_tree.api.decorator.IconPlacement`) + • {extend} (`fun(self: nvim_tree.api.decorator.UserDecorator)`) + See |UserDecorator:extend()|. + • {new} (`fun(self: nvim_tree.api.decorator.UserDecorator)`) + See |UserDecorator:new()|. + • {icon_node} (`fun(self: nvim_tree.api.decorator.UserDecorator, node: nvim_tree.api.Node): nvim_tree.api.HighlightedString?`) + See |UserDecorator:icon_node()|. + • {icons} (`fun(self: nvim_tree.api.decorator.UserDecorator, node: nvim_tree.api.Node): nvim_tree.api.HighlightedString[]?`) + See |UserDecorator:icons()|. + • {highlight_group} (`fun(self: nvim_tree.api.decorator.UserDecorator, node: nvim_tree.api.Node): string?`) + See |UserDecorator:highlight_group()|. + + +UserDecorator:extend() *nvim_tree.api.decorator.UserDecorator:extend()* + Create your decorator class + + *nvim_tree.api.decorator.UserDecorator:highlight_group()* +UserDecorator:highlight_group({node}) + Abstract: optionally implement to provide one highlight group to apply to + your highlight_range. + + Parameters: ~ + • {node} (`nvim_tree.api.Node`) + + Return: ~ + (`string?`) highlight_group + + *nvim_tree.api.decorator.UserDecorator:icon_node()* +UserDecorator:icon_node({node}) + Abstract: optionally implement to set the node's icon + + Parameters: ~ + • {node} (`nvim_tree.api.Node`) + + Return: ~ + (`nvim_tree.api.HighlightedString?`) icon_node + + *nvim_tree.api.decorator.UserDecorator:icons()* +UserDecorator:icons({node}) + Abstract: optionally implement to provide icons and the highlight groups + for your icon_placement. + + Parameters: ~ + • {node} (`nvim_tree.api.Node`) + + Return: ~ + (`nvim_tree.api.HighlightedString[]?`) icons + +UserDecorator:new() *nvim_tree.api.decorator.UserDecorator:new()* + Abstract: no-args constructor must be implemented and will be called once + per tree render. Must set all fields. + + + vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: diff --git a/lua/nvim-tree/_meta/api_decorator.lua b/lua/nvim-tree/_meta/api_decorator.lua index d85fe02fff0..f194ca120ee 100644 --- a/lua/nvim-tree/_meta/api_decorator.lua +++ b/lua/nvim-tree/_meta/api_decorator.lua @@ -1,8 +1,6 @@ ---@meta error("Cannot require a meta file") -local nvim_tree = { api = { decorator = {} } } - ---Highlight group range as per nvim-tree.renderer.highlight_* ---@alias nvim_tree.api.decorator.HighlightRange "none" | "icon" | "name" | "all" @@ -14,41 +12,41 @@ local nvim_tree = { api = { decorator = {} } } ---Custom decorator, see :help nvim-tree-decorators --- ----@class (exact) nvim_tree.api.decorator.UserDecorator ----@field protected enabled boolean ----@field protected highlight_range nvim_tree.api.decorator.HighlightRange ----@field protected icon_placement nvim_tree.api.decorator.IconPlacement -nvim_tree.api.decorator.UserDecorator = {} +---@class nvim_tree.api.decorator.UserDecorator +---@field enabled boolean +---@field highlight_range nvim_tree.api.decorator.HighlightRange +---@field icon_placement nvim_tree.api.decorator.IconPlacement +local UserDecorator = {} ---Create your decorator class --- -function nvim_tree.api.decorator.UserDecorator:extend() end +function UserDecorator:extend() end ---Abstract: no-args constructor must be implemented and will be called once per tree render. ---Must set all fields. --- -function nvim_tree.api.decorator.UserDecorator:new() end +function UserDecorator:new() end ---Abstract: optionally implement to set the node's icon --- ---@param node nvim_tree.api.Node ---@return nvim_tree.api.HighlightedString? icon_node -function nvim_tree.api.decorator.UserDecorator:icon_node(node) end +function UserDecorator:icon_node(node) end ---Abstract: optionally implement to provide icons and the highlight groups for your icon_placement. --- ---@param node nvim_tree.api.Node ---@return nvim_tree.api.HighlightedString[]? icons -function nvim_tree.api.decorator.UserDecorator:icons(node) end +function UserDecorator:icons(node) end ---Abstract: optionally implement to provide one highlight group to apply to your highlight_range. --- ---@param node nvim_tree.api.Node ---@return string? highlight_group -function nvim_tree.api.decorator.UserDecorator:highlight_group(node) end +function UserDecorator:highlight_group(node) end ---Define a sign. This should be called in the constructor. --- ---@protected ---@param icon nvim_tree.api.HighlightedString? -function nvim_tree.api.decorator.UserDecorator:define_sign(icon) end +function UserDecorator:define_sign(icon) end diff --git a/scripts/doc.sh b/scripts/doc.sh new file mode 100755 index 00000000000..049bf85ae22 --- /dev/null +++ b/scripts/doc.sh @@ -0,0 +1,24 @@ +#!/usr/bin/env sh + +set -e + +if [ ! -d "${NEOVIM_SRC}" ]; then + echo "\$NEOVIM_SRC not set" + exit 1 +fi + +# runtime/doc is hardcoded, copy it in +mkdir -p runtime/doc +cp "doc/decorator.txt" runtime/doc + +# use luacacts etc. from neovim src +LUA_PATH="${NEOVIM_SRC}/src/?.lua" + +# generate +scripts/gen_vimdoc.lua + +# move the output +mv "runtime/doc/decorator.txt" doc +rmdir runtime/doc +rmdir runtime + diff --git a/scripts/gen_vimdoc.decorator.lua b/scripts/gen_vimdoc.decorator.lua new file mode 100644 index 00000000000..dd9a37681e7 --- /dev/null +++ b/scripts/gen_vimdoc.decorator.lua @@ -0,0 +1,49 @@ +---@diagnostic disable: undefined-doc-name + +--- @param fun nvim.luacats.parser.fun +--- @return string +local function fn_helptag_fmt_common0(fun) + local fn_sfx = fun.table and '' or '()' + if fun.classvar then + return string.format('%s:%s%s', fun.classvar, fun.name, fn_sfx) + end + if fun.module then + return string.format('%s.%s%s', fun.module, fun.name, fn_sfx) + end + return fun.name .. fn_sfx +end + +return { + filename = "decorator.txt", + section_order = { + "api_decorator.lua", + }, + files = { + -- module is derived soley from the file name, first letter capitalised + -- 'runtime/lua/nvim-tree/foo/api_decorator.lua', + "/home/alex/src/nvim-tree/master/lua/nvim-tree/_meta/api_decorator.lua" + }, + section_fmt = function(name) + if name == "Api_decorator" then + return "Lua module: nvim_tree.api.decorator" + end + error(string.format("unknown module %s passed to section_fmt", name)) + end, + helptag_fmt = function(name) + -- used to locate the help section + if name == "Api_decorator" then + return "nvim-tree-decorators" + end + error(string.format("unknown module %s passed to helptag_fmt", name)) + end, + fn_helptag_fmt = function(fun) + -- use the fully qualified class name in the tag for methods + -- this is done everywhere but for classes + local common = fn_helptag_fmt_common0(fun) + local helptag = common + if fun.class then + helptag = common:gsub(fun.classvar, fun.class) + end + return helptag + end, +} diff --git a/scripts/gen_vimdoc.lua b/scripts/gen_vimdoc.lua new file mode 100755 index 00000000000..6b1b5a6fbd8 --- /dev/null +++ b/scripts/gen_vimdoc.lua @@ -0,0 +1,823 @@ +#!/usr/bin/env -S nvim -l + +---@diagnostic disable: assign-type-mismatch, incomplete-signature-doc, param-type-mismatch, undefined-doc-name, inject-field + +--- Generates Nvim :help docs from Lua/C docstrings. +--- +--- Usage: +--- make doc +--- +--- The generated :help text for each function is formatted as follows: +--- - Max width of 78 columns (`TEXT_WIDTH`). +--- - Indent with spaces (not tabs). +--- - Indent of 4 columns for body text (`INDENTATION`). +--- - Function signature and helptag (right-aligned) on the same line. +--- - Signature and helptag must have a minimum of 8 spaces between them. +--- - If the signature is too long, it is placed on the line after the helptag. +--- Signature wraps with subsequent lines indented to the open parenthesis. +--- - Subsection bodies are indented an additional 4 spaces. +--- - Body consists of function description, parameters, return description, and +--- C declaration (`INCLUDE_C_DECL`). +--- - Parameters are omitted for the `void` and `Error *` types, or if the +--- parameter is marked as [out]. +--- - Each function documentation is separated by a single line. + +local luacats_parser = require('gen.luacats_parser') +local cdoc_parser = require('gen.cdoc_parser') +local util = require('gen.util') + +local fmt = string.format + +local wrap = util.wrap +local md_to_vimdoc = util.md_to_vimdoc + +local TEXT_WIDTH = 78 +local INDENTATION = 4 + +--- @class (exact) nvim.gen_vimdoc.Config +--- +--- Generated documentation target, e.g. api.txt +--- @field filename string +--- +--- @field section_order string[] +--- +--- List of files/directories for doxygen to read, relative to `base_dir`. +--- @field files string[] +--- +--- Section name overrides. Key: filename (e.g., vim.c) +--- @field section_name? table +--- +--- @field fn_name_pat? string +--- +--- @field fn_xform? fun(fun: nvim.luacats.parser.fun) +--- +--- For generated section names. +--- @field section_fmt fun(name: string): string +--- +--- @field helptag_fmt fun(name: string): string|string[] +--- +--- Per-function helptag. +--- @field fn_helptag_fmt? fun(fun: nvim.luacats.parser.fun): string +--- +--- @field append_only? string[] + +local function contains(t, xs) + return vim.tbl_contains(xs, t) +end + +--- @type {level:integer, prerelease:boolean}? +local nvim_api_info_ + +--- @return {level: integer, prerelease:boolean} +local function nvim_api_info() + if not nvim_api_info_ then + --- @type integer?, boolean? + local level, prerelease + for l in io.lines('CMakeLists.txt') do + --- @cast l string + if level and prerelease then + break + end + local m1 = l:match('^set%(NVIM_API_LEVEL%s+(%d+)%)') + if m1 then + level = tonumber(m1) --[[@as integer]] + end + local m2 = l:match('^set%(NVIM_API_PRERELEASE%s+(%w+)%)') + if m2 then + prerelease = m2 == 'true' + end + end + nvim_api_info_ = { level = level, prerelease = prerelease } + end + + return nvim_api_info_ +end + +--- @param fun nvim.luacats.parser.fun +--- @return string +local function fn_helptag_fmt_common(fun) + local fn_sfx = fun.table and '' or '()' + if fun.classvar then + return fmt('%s:%s%s', fun.classvar, fun.name, fn_sfx) + end + if fun.module then + return fmt('%s.%s%s', fun.module, fun.name, fn_sfx) + end + return fun.name .. fn_sfx +end + +--- @type table +local config = { + decorator = { + filename = "decorator.txt", + section_order = { + "api_decorator.lua", + }, + files = { + -- module is derived soley from the file name, first letter capitalised + -- 'runtime/lua/nvim-tree/foo/api_decorator.lua', + "/home/alex/src/nvim-tree/master/lua/nvim-tree/_meta/api_decorator.lua" + }, + section_fmt = function(name) + if name == "Api_decorator" then + return "Lua module: nvim_tree.api.decorator" + end + error(string.format("unknown module %s passed to section_fmt", name)) + end, + helptag_fmt = function(name) + -- used to locate the help section + if name == "Api_decorator" then + return "nvim-tree-decorators" + end + error(string.format("unknown module %s passed to helptag_fmt", name)) + end, + fn_helptag_fmt = function(fun) + -- use the fully qualified class name in the tag for methods + -- this is done everywhere but for classes + local common = fn_helptag_fmt_common(fun) + local helptag = common + if fun.class then + helptag = common:gsub(fun.classvar, fun.class) + end + return helptag + end, + } +} + +--- @param ty string +--- @param generics table +--- @return string +local function replace_generics(ty, generics) + if ty:sub(-2) == '[]' then + local ty0 = ty:sub(1, -3) + if generics[ty0] then + return generics[ty0] .. '[]' + end + elseif ty:sub(-1) == '?' then + local ty0 = ty:sub(1, -2) + if generics[ty0] then + return generics[ty0] .. '?' + end + end + + return generics[ty] or ty +end + +--- @param name string +local function fmt_field_name(name) + local name0, opt = name:match('^([^?]*)(%??)$') + return fmt('{%s}%s', name0, opt) +end + +--- @param ty string +--- @param generics? table +--- @param default? string +local function render_type(ty, generics, default) + ty = ty:gsub('vim%.lsp%.protocol%.Method.[%w.]+', 'string') + + if generics then + ty = replace_generics(ty, generics) + end + ty = ty:gsub('%s*|%s*nil', '?') + ty = ty:gsub('nil%s*|%s*(.*)', '%1?') + ty = ty:gsub('%s*|%s*', '|') + if default then + return fmt('(`%s`, default: %s)', ty, default) + end + return fmt('(`%s`)', ty) +end + +--- @param p nvim.luacats.parser.param|nvim.luacats.parser.field +local function should_render_field_or_param(p) + return not p.nodoc + and not p.access + and not contains(p.name, { '_', 'self' }) + and not vim.startswith(p.name, '_') +end + +--- @param desc? string +--- @return string?, string? +local function get_default(desc) + if not desc then + return + end + + local default = desc:match('\n%s*%([dD]efault: ([^)]+)%)') + if default then + desc = desc:gsub('\n%s*%([dD]efault: [^)]+%)', '') + end + + return desc, default +end + +--- @param ty string +--- @param classes? table +--- @return nvim.luacats.parser.class? +local function get_class(ty, classes) + if not classes then + return + end + + local cty = ty:gsub('%s*|%s*nil', '?'):gsub('?$', ''):gsub('%[%]$', '') + + return classes[cty] +end + +--- @param obj nvim.luacats.parser.param|nvim.luacats.parser.return|nvim.luacats.parser.field +--- @param classes? table +local function inline_type(obj, classes) + local ty = obj.type + if not ty then + return + end + + local cls = get_class(ty, classes) + + if not cls or cls.nodoc then + return + end + + if not cls.inlinedoc then + -- Not inlining so just add a: "See |tag|." + local tag = fmt('|%s|', cls.name) + if obj.desc and obj.desc:find(tag) then + -- Tag already there + return + end + + -- TODO(lewis6991): Aim to remove this. Need this to prevent dead + -- references to types defined in runtime/lua/vim/lsp/_meta/protocol.lua + if not vim.startswith(cls.name, 'vim.') then + return + end + + obj.desc = obj.desc or '' + local period = (obj.desc == '' or vim.endswith(obj.desc, '.')) and '' or '.' + obj.desc = obj.desc .. fmt('%s See %s.', period, tag) + return + end + + local ty_isopt = (ty:match('%?$') or ty:match('%s*|%s*nil')) ~= nil + local ty_islist = (ty:match('%[%]$')) ~= nil + ty = ty_isopt and 'table?' or ty_islist and 'table[]' or 'table' + + local desc = obj.desc or '' + if cls.desc then + desc = desc .. cls.desc + elseif desc == '' then + if ty_islist then + desc = desc .. 'A list of objects with the following fields:' + elseif cls.parent then + desc = desc .. fmt('Extends |%s| with the additional fields:', cls.parent) + else + desc = desc .. 'A table with the following fields:' + end + end + + local desc_append = {} + for _, f in ipairs(cls.fields) do + if not f.access then + local fdesc, default = get_default(f.desc) + local fty = render_type(f.type, nil, default) + local fnm = fmt_field_name(f.name) + table.insert(desc_append, table.concat({ '-', fnm, fty, fdesc }, ' ')) + end + end + + desc = desc .. '\n' .. table.concat(desc_append, '\n') + obj.type = ty + obj.desc = desc +end + +--- @param xs (nvim.luacats.parser.param|nvim.luacats.parser.field)[] +--- @param generics? table +--- @param classes? table +--- @param cfg nvim.gen_vimdoc.Config +local function render_fields_or_params(xs, generics, classes, cfg) + local ret = {} --- @type string[] + + xs = vim.tbl_filter(should_render_field_or_param, xs) + + local indent = 0 + for _, p in ipairs(xs) do + if p.type or p.desc then + indent = math.max(indent, #p.name + 3) + end + end + + for _, p in ipairs(xs) do + local pdesc, default = get_default(p.desc) + p.desc = pdesc + + inline_type(p, classes) + local nm, ty = p.name, p.type + + local desc = p.classvar and fmt('See |%s|.', cfg.fn_helptag_fmt(p)) or p.desc + + local fnm = p.kind == 'operator' and fmt('op(%s)', nm) or fmt_field_name(nm) + local pnm = fmt(' • %-' .. indent .. 's', fnm) + + if ty then + local pty = render_type(ty, generics, default) + + if desc then + table.insert(ret, pnm) + if #pty > TEXT_WIDTH - indent then + vim.list_extend(ret, { ' ', pty, '\n' }) + table.insert(ret, md_to_vimdoc(desc, 9 + indent, 9 + indent, TEXT_WIDTH, true)) + else + desc = fmt('%s %s', pty, desc) + table.insert(ret, md_to_vimdoc(desc, 1, 9 + indent, TEXT_WIDTH, true)) + end + else + table.insert(ret, fmt('%s %s\n', pnm, pty)) + end + else + if desc then + table.insert(ret, pnm) + table.insert(ret, md_to_vimdoc(desc, 1, 9 + indent, TEXT_WIDTH, true)) + end + end + end + + return table.concat(ret) +end + +--- @param class nvim.luacats.parser.class +--- @param classes table +--- @param cfg nvim.gen_vimdoc.Config +local function render_class(class, classes, cfg) + if class.access or class.nodoc or class.inlinedoc then + return + end + + local ret = {} --- @type string[] + + table.insert(ret, fmt('*%s*\n', class.name)) + + if class.parent then + local txt = fmt('Extends: |%s|', class.parent) + table.insert(ret, md_to_vimdoc(txt, INDENTATION, INDENTATION, TEXT_WIDTH)) + table.insert(ret, '\n') + end + + if class.desc then + table.insert(ret, md_to_vimdoc(class.desc, INDENTATION, INDENTATION, TEXT_WIDTH)) + end + + local fields_txt = render_fields_or_params(class.fields, nil, classes, cfg) + if not fields_txt:match('^%s*$') then + table.insert(ret, '\n Fields: ~\n') + table.insert(ret, fields_txt) + end + table.insert(ret, '\n') + + return table.concat(ret) +end + +--- @param classes table +--- @param cfg nvim.gen_vimdoc.Config +local function render_classes(classes, cfg) + local ret = {} --- @type string[] + + for _, class in vim.spairs(classes) do + ret[#ret + 1] = render_class(class, classes, cfg) + end + + return table.concat(ret) +end + +--- @param fun nvim.luacats.parser.fun +--- @param cfg nvim.gen_vimdoc.Config +local function render_fun_header(fun, cfg) + local ret = {} --- @type string[] + + local args = {} --- @type string[] + for _, p in ipairs(fun.params or {}) do + if p.name ~= 'self' then + args[#args + 1] = fmt_field_name(p.name) + end + end + + local nm = fun.name + if fun.classvar then + nm = fmt('%s:%s', fun.classvar, nm) + end + if nm == 'vim.bo' then + nm = 'vim.bo[{bufnr}]' + end + if nm == 'vim.wo' then + nm = 'vim.wo[{winid}][{bufnr}]' + end + + local proto = fun.table and nm or nm .. '(' .. table.concat(args, ', ') .. ')' + + local tag = '*' .. cfg.fn_helptag_fmt(fun) .. '*' + + if #proto + #tag > TEXT_WIDTH - 8 then + table.insert(ret, fmt('%78s\n', tag)) + local name, pargs = proto:match('([^(]+%()(.*)') + table.insert(ret, name) + table.insert(ret, wrap(pargs, 0, #name, TEXT_WIDTH)) + else + local pad = TEXT_WIDTH - #proto - #tag + table.insert(ret, proto .. string.rep(' ', pad) .. tag) + end + + return table.concat(ret) +end + +--- @param returns nvim.luacats.parser.return[] +--- @param generics? table +--- @param classes? table +--- @return string? +local function render_returns(returns, generics, classes) + local ret = {} --- @type string[] + + if #returns == 1 and returns[1].type == 'nil' then + return + end + + if #returns > 1 then + table.insert(ret, ' Return (multiple): ~\n') + elseif #returns == 1 and next(returns[1]) then + table.insert(ret, ' Return: ~\n') + end + + for _, p in ipairs(returns) do + inline_type(p, classes) + local rnm, ty, desc = p.name, p.type, p.desc + + local blk = {} --- @type string[] + if ty then + blk[#blk + 1] = render_type(ty, generics) + end + blk[#blk + 1] = rnm + blk[#blk + 1] = desc + + ret[#ret + 1] = md_to_vimdoc(table.concat(blk, ' '), 8, 8, TEXT_WIDTH, true) + end + + return table.concat(ret) +end + +--- @param fun nvim.luacats.parser.fun +--- @param classes table +--- @param cfg nvim.gen_vimdoc.Config +local function render_fun(fun, classes, cfg) + if fun.access or fun.deprecated or fun.nodoc then + return + end + + if cfg.fn_name_pat and not fun.name:match(cfg.fn_name_pat) then + return + end + + if vim.startswith(fun.name, '_') or fun.name:find('[:.]_') then + return + end + + local ret = {} --- @type string[] + + table.insert(ret, render_fun_header(fun, cfg)) + table.insert(ret, '\n') + + if fun.since then + local since = assert(tonumber(fun.since), 'invalid @since on ' .. fun.name) + local info = nvim_api_info() + if since == 0 or (info.prerelease and since == info.level) then + -- Experimental = (since==0 or current prerelease) + local s = 'WARNING: This feature is experimental/unstable.' + table.insert(ret, md_to_vimdoc(s, INDENTATION, INDENTATION, TEXT_WIDTH)) + table.insert(ret, '\n') + else + local v = assert(util.version_level[since], 'invalid @since on ' .. fun.name) + fun.attrs = fun.attrs or {} + table.insert(fun.attrs, fmt('Since: %s', v)) + end + end + + if fun.desc then + table.insert(ret, md_to_vimdoc(fun.desc, INDENTATION, INDENTATION, TEXT_WIDTH)) + end + + if fun.notes then + table.insert(ret, '\n Note: ~\n') + for _, p in ipairs(fun.notes) do + table.insert(ret, ' • ' .. md_to_vimdoc(p.desc, 0, 8, TEXT_WIDTH, true)) + end + end + + if fun.attrs then + table.insert(ret, '\n Attributes: ~\n') + for _, attr in ipairs(fun.attrs) do + local attr_str = ({ + textlock = 'not allowed when |textlock| is active or in the |cmdwin|', + textlock_allow_cmdwin = 'not allowed when |textlock| is active', + fast = '|api-fast|', + remote_only = '|RPC| only', + lua_only = 'Lua |vim.api| only', + })[attr] or attr + table.insert(ret, fmt(' %s\n', attr_str)) + end + end + + if fun.params and #fun.params > 0 then + local param_txt = render_fields_or_params(fun.params, fun.generics, classes, cfg) + if not param_txt:match('^%s*$') then + table.insert(ret, '\n Parameters: ~\n') + ret[#ret + 1] = param_txt + end + end + + if fun.overloads then + table.insert(ret, '\n Overloads: ~\n') + for _, p in ipairs(fun.overloads) do + table.insert(ret, fmt(' • `%s`\n', p)) + end + end + + if fun.returns then + local txt = render_returns(fun.returns, fun.generics, classes) + if txt and not txt:match('^%s*$') then + table.insert(ret, '\n') + ret[#ret + 1] = txt + end + end + + if fun.see then + table.insert(ret, '\n See also: ~\n') + for _, p in ipairs(fun.see) do + table.insert(ret, ' • ' .. md_to_vimdoc(p.desc, 0, 8, TEXT_WIDTH, true)) + end + end + + table.insert(ret, '\n') + return table.concat(ret) +end + +--- @param funs nvim.luacats.parser.fun[] +--- @param classes table +--- @param cfg nvim.gen_vimdoc.Config +local function render_funs(funs, classes, cfg) + local ret = {} --- @type string[] + + for _, f in ipairs(funs) do + if cfg.fn_xform then + cfg.fn_xform(f) + end + ret[#ret + 1] = render_fun(f, classes, cfg) + end + + -- Sort via prototype. Experimental API functions ("nvim__") sort last. + table.sort(ret, function(a, b) + local a1 = ('\n' .. a):match('\n[a-zA-Z_][^\n]+\n') + local b1 = ('\n' .. b):match('\n[a-zA-Z_][^\n]+\n') + + local a1__ = a1:find('^%s*nvim__') and 1 or 0 + local b1__ = b1:find('^%s*nvim__') and 1 or 0 + if a1__ ~= b1__ then + return a1__ < b1__ + end + + return a1:lower() < b1:lower() + end) + + return table.concat(ret) +end + +--- @return string +local function get_script_path() + local str = debug.getinfo(2, 'S').source:gsub('^@', '') + return str:match('(.*[/\\])') or './' +end + +local script_path = get_script_path() +local base_dir = vim.fs.dirname(vim.fs.dirname(vim.fs.dirname(script_path))) + +local function delete_lines_below(doc_file, tokenstr) + local lines = {} --- @type string[] + local found = false + for line in io.lines(doc_file) do + if line:find(vim.pesc(tokenstr)) then + found = true + break + end + lines[#lines + 1] = line + end + if not found then + error(fmt('not found: %s in %s', tokenstr, doc_file)) + end + lines[#lines] = nil + local fp = assert(io.open(doc_file, 'w')) + fp:write(table.concat(lines, '\n')) + fp:write('\n') + fp:close() +end + +--- @param x string +local function mktitle(x) + if x == 'ui' then + return 'UI' + end + return x:sub(1, 1):upper() .. x:sub(2) +end + +--- @class nvim.gen_vimdoc.Section +--- @field name string +--- @field title string +--- @field help_tag string +--- @field funs_txt string +--- @field classes_txt string +--- @field briefs string[] + +--- @param filename string +--- @param cfg nvim.gen_vimdoc.Config +--- @param briefs string[] +--- @param funs_txt string +--- @param classes_txt string +--- @return nvim.gen_vimdoc.Section? +local function make_section(filename, cfg, briefs, funs_txt, classes_txt) + -- filename: e.g., 'autocmd.c' + -- name: e.g. 'autocmd' + local name = filename:match('(.*)%.[a-z]+') + + -- Formatted (this is what's going to be written in the vimdoc) + -- e.g., "Autocmd Functions" + local sectname = cfg.section_name and cfg.section_name[filename] or mktitle(name) + + -- section tag: e.g., "*api-autocmd*" + local help_labels = cfg.helptag_fmt(sectname) + if type(help_labels) == 'table' then + help_labels = table.concat(help_labels, '* *') + end + local help_tags = '*' .. help_labels .. '*' + + if funs_txt == '' and classes_txt == '' and #briefs == 0 then + return + end + + return { + name = sectname, + title = cfg.section_fmt(sectname), + help_tag = help_tags, + funs_txt = funs_txt, + classes_txt = classes_txt, + briefs = briefs, + } +end + +--- @param section nvim.gen_vimdoc.Section +--- @param add_header? boolean +local function render_section(section, add_header) + local doc = {} --- @type string[] + + if add_header ~= false then + vim.list_extend(doc, { + string.rep('=', TEXT_WIDTH), + '\n', + section.title, + fmt('%' .. (TEXT_WIDTH - section.title:len()) .. 's', section.help_tag), + }) + end + + if next(section.briefs) then + local briefs_txt = {} --- @type string[] + for _, b in ipairs(section.briefs) do + briefs_txt[#briefs_txt + 1] = md_to_vimdoc(b, 0, 0, TEXT_WIDTH) + end + + local sdoc = '\n\n' .. table.concat(briefs_txt, '\n') + if sdoc:find('[^%s]') then + doc[#doc + 1] = sdoc + end + end + + if section.classes_txt ~= '' then + table.insert(doc, '\n\n') + table.insert(doc, (section.classes_txt:gsub('\n+$', '\n'))) + end + + if section.funs_txt ~= '' then + table.insert(doc, '\n\n') + table.insert(doc, section.funs_txt) + end + + return table.concat(doc) +end + +local parsers = { + lua = luacats_parser.parse, + c = cdoc_parser.parse, + h = cdoc_parser.parse, +} + +--- @param files string[] +local function expand_files(files) + for k, f in pairs(files) do + if vim.fn.isdirectory(f) == 1 then + table.remove(files, k) + for path, ty in vim.fs.dir(f) do + if ty == 'file' then + table.insert(files, vim.fs.joinpath(f, path)) + end + end + end + end +end + +--- @param classes table +--- @return string? +local function find_module_class(classes, modvar) + for nm, cls in pairs(classes) do + local _, field = next(cls.fields or {}) + if cls.desc and field and field.classvar == modvar then + return nm + end + end +end + +--- @param cfg nvim.gen_vimdoc.Config +local function gen_target(cfg) + cfg.fn_helptag_fmt = cfg.fn_helptag_fmt or fn_helptag_fmt_common + print('Target:', cfg.filename) + local sections = {} --- @type table + + expand_files(cfg.files) + + --- @type table, nvim.luacats.parser.fun[], string[]]> + local file_results = {} + + --- @type table + local all_classes = {} + + --- First pass so we can collect all classes + for _, f in vim.spairs(cfg.files) do + local ext = f:match('%.([^.]+)$') + local parser = parsers[ext] + if parser then + local classes, funs, briefs = parser(f) + file_results[f] = { classes, funs, briefs } + all_classes = vim.tbl_extend('error', all_classes, classes) + end + end + + for f, r in vim.spairs(file_results) do + local classes, funs, briefs = r[1], r[2], r[3] + + local mod_cls_nm = find_module_class(classes, 'M') + if mod_cls_nm then + local mod_cls = classes[mod_cls_nm] + classes[mod_cls_nm] = nil + -- If the module documentation is present, add it to the briefs + -- so it appears at the top of the section. + briefs[#briefs + 1] = mod_cls.desc + end + + print(' Processing file:', f) + + -- FIXME: Using f_base will confuse `_meta/protocol.lua` with `protocol.lua` + local f_base = vim.fs.basename(f) + sections[f_base] = make_section( + f_base, + cfg, + briefs, + render_funs(funs, all_classes, cfg), + render_classes(classes, cfg) + ) + end + + local first_section_tag = sections[cfg.section_order[1]].help_tag + local docs = {} --- @type string[] + for _, f in ipairs(cfg.section_order) do + local section = sections[f] + if section then + print(fmt(" Rendering section: '%s'", section.title)) + local add_sep_and_header = not vim.tbl_contains(cfg.append_only or {}, f) + docs[#docs + 1] = render_section(section, add_sep_and_header) + end + end + + table.insert( + docs, + fmt(' vim:tw=78:ts=8:sw=%d:sts=%d:et:ft=help:norl:\n', INDENTATION, INDENTATION) + ) + + local doc_file = vim.fs.joinpath(base_dir, 'runtime', 'doc', cfg.filename) + + if vim.uv.fs_stat(doc_file) then + delete_lines_below(doc_file, first_section_tag) + end + + local fp = assert(io.open(doc_file, 'a')) + fp:write(table.concat(docs, '\n')) + fp:close() +end + +local function run() + for _, cfg in vim.spairs(config) do + gen_target(cfg) + end +end + +run() From cbfffc6ef64e223698c2d5dcd70579fa56177b82 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sun, 4 Jan 2026 16:25:31 +1100 Subject: [PATCH 002/170] doc(#2934): use injected gen_vimdoc.lua from nvim source, move decorators to main help --- doc/decorator.txt | 66 --- doc/nvim-tree-lua.txt | 68 ++- scripts/doc.sh | 24 - scripts/gen_vimdoc.decorator.lua | 49 -- scripts/gen_vimdoc.lua | 823 ------------------------------- scripts/gen_vimdoc.sh | 31 ++ scripts/gen_vimdoc_config.lua | 44 ++ 7 files changed, 140 insertions(+), 965 deletions(-) delete mode 100644 doc/decorator.txt delete mode 100755 scripts/doc.sh delete mode 100644 scripts/gen_vimdoc.decorator.lua delete mode 100755 scripts/gen_vimdoc.lua create mode 100755 scripts/gen_vimdoc.sh create mode 100644 scripts/gen_vimdoc_config.lua diff --git a/doc/decorator.txt b/doc/decorator.txt deleted file mode 100644 index 1ddde49ffa0..00000000000 --- a/doc/decorator.txt +++ /dev/null @@ -1,66 +0,0 @@ -*decorator.txt* nvim-tree decorators - -============================================================================== -============================================================================== -Lua module: nvim_tree.api.decorator *nvim-tree-decorators* - -*nvim_tree.api.decorator.UserDecorator* - Custom decorator, see :help nvim-tree-decorators - - Fields: ~ - • {enabled} (`boolean`) - • {highlight_range} (`nvim_tree.api.decorator.HighlightRange`) - • {icon_placement} (`nvim_tree.api.decorator.IconPlacement`) - • {extend} (`fun(self: nvim_tree.api.decorator.UserDecorator)`) - See |UserDecorator:extend()|. - • {new} (`fun(self: nvim_tree.api.decorator.UserDecorator)`) - See |UserDecorator:new()|. - • {icon_node} (`fun(self: nvim_tree.api.decorator.UserDecorator, node: nvim_tree.api.Node): nvim_tree.api.HighlightedString?`) - See |UserDecorator:icon_node()|. - • {icons} (`fun(self: nvim_tree.api.decorator.UserDecorator, node: nvim_tree.api.Node): nvim_tree.api.HighlightedString[]?`) - See |UserDecorator:icons()|. - • {highlight_group} (`fun(self: nvim_tree.api.decorator.UserDecorator, node: nvim_tree.api.Node): string?`) - See |UserDecorator:highlight_group()|. - - -UserDecorator:extend() *nvim_tree.api.decorator.UserDecorator:extend()* - Create your decorator class - - *nvim_tree.api.decorator.UserDecorator:highlight_group()* -UserDecorator:highlight_group({node}) - Abstract: optionally implement to provide one highlight group to apply to - your highlight_range. - - Parameters: ~ - • {node} (`nvim_tree.api.Node`) - - Return: ~ - (`string?`) highlight_group - - *nvim_tree.api.decorator.UserDecorator:icon_node()* -UserDecorator:icon_node({node}) - Abstract: optionally implement to set the node's icon - - Parameters: ~ - • {node} (`nvim_tree.api.Node`) - - Return: ~ - (`nvim_tree.api.HighlightedString?`) icon_node - - *nvim_tree.api.decorator.UserDecorator:icons()* -UserDecorator:icons({node}) - Abstract: optionally implement to provide icons and the highlight groups - for your icon_placement. - - Parameters: ~ - • {node} (`nvim_tree.api.Node`) - - Return: ~ - (`nvim_tree.api.HighlightedString[]?`) icons - -UserDecorator:new() *nvim_tree.api.decorator.UserDecorator:new()* - Abstract: no-args constructor must be implemented and will be called once - per tree render. Must set all fields. - - - vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 44206bdc483..058864beefe 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -46,6 +46,7 @@ CONTENTS *nvim-tree* 6.8 API Config |nvim-tree-api.config| 6.9 API Commands |nvim-tree-api.commands| 6.10 API Diagnostics |nvim-tree-api.diagnostics| + 6.11 API Decorator |nvim-tree-api.decorator| 7. Mappings |nvim-tree-mappings| 7.1 Mappings: Default |nvim-tree-mappings-default| 8. Highlight |nvim-tree-highlight| @@ -953,6 +954,7 @@ Whether to show the destination of the symlink. Highlighting and icons for the nodes, in increasing order of precedence. Uses strings to specify builtin decorators otherwise specify your `nvim_tree.api.decorator.UserDecorator` class. +See |nvim-tree-decorators|, |nvim-tree-api.decorator| Type: `nvim_tree.api.decorator.Name[]`, Default: >lua { "Git", @@ -2968,13 +2970,13 @@ Decorators may: - Set highlight group for the name or icons - Override node icon +See |nvim-tree-api.decorator| + Create a `nvim_tree.api.decorator.UserDecorator` class and register it with precedence via |nvim-tree.renderer.decorators| See |nvim-tree-decorator-example| -See `nvim-tree/_meta/api_decorator.lua` for full class documentation. - ============================================================================== 11.1. DECORATOR EXAMPLE *nvim-tree-decorator-example* @@ -3458,5 +3460,65 @@ highlight group is not, hard linking as follows: > |nvim-tree-api.tree.winid()| ============================================================================== + 6.11 API DECORATOR *nvim-tree-api.decorator* + +*nvim_tree.api.decorator.UserDecorator* + Custom decorator, see :help nvim-tree-decorators + + Fields: ~ + • {enabled} (`boolean`) + • {highlight_range} (`nvim_tree.api.decorator.HighlightRange`) + • {icon_placement} (`nvim_tree.api.decorator.IconPlacement`) + • {extend} (`fun(self: nvim_tree.api.decorator.UserDecorator)`) + See |UserDecorator:extend()|. + • {new} (`fun(self: nvim_tree.api.decorator.UserDecorator)`) + See |UserDecorator:new()|. + • {icon_node} (`fun(self: nvim_tree.api.decorator.UserDecorator, node: nvim_tree.api.Node): nvim_tree.api.HighlightedString?`) + See |UserDecorator:icon_node()|. + • {icons} (`fun(self: nvim_tree.api.decorator.UserDecorator, node: nvim_tree.api.Node): nvim_tree.api.HighlightedString[]?`) + See |UserDecorator:icons()|. + • {highlight_group} (`fun(self: nvim_tree.api.decorator.UserDecorator, node: nvim_tree.api.Node): string?`) + See |UserDecorator:highlight_group()|. + + +UserDecorator:extend() *nvim_tree.api.decorator.UserDecorator:extend()* + Create your decorator class + + *nvim_tree.api.decorator.UserDecorator:highlight_group()* +UserDecorator:highlight_group({node}) + Abstract: optionally implement to provide one highlight group to apply to + your highlight_range. + + Parameters: ~ + • {node} (`nvim_tree.api.Node`) + + Return: ~ + (`string?`) highlight_group + + *nvim_tree.api.decorator.UserDecorator:icon_node()* +UserDecorator:icon_node({node}) + Abstract: optionally implement to set the node's icon + + Parameters: ~ + • {node} (`nvim_tree.api.Node`) + + Return: ~ + (`nvim_tree.api.HighlightedString?`) icon_node + + *nvim_tree.api.decorator.UserDecorator:icons()* +UserDecorator:icons({node}) + Abstract: optionally implement to provide icons and the highlight groups + for your icon_placement. + + Parameters: ~ + • {node} (`nvim_tree.api.Node`) + + Return: ~ + (`nvim_tree.api.HighlightedString[]?`) icons + +UserDecorator:new() *nvim_tree.api.decorator.UserDecorator:new()* + Abstract: no-args constructor must be implemented and will be called once + per tree render. Must set all fields. + - vim:tw=78:ts=4:sw=4:et:ft=help:norl: + vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: diff --git a/scripts/doc.sh b/scripts/doc.sh deleted file mode 100755 index 049bf85ae22..00000000000 --- a/scripts/doc.sh +++ /dev/null @@ -1,24 +0,0 @@ -#!/usr/bin/env sh - -set -e - -if [ ! -d "${NEOVIM_SRC}" ]; then - echo "\$NEOVIM_SRC not set" - exit 1 -fi - -# runtime/doc is hardcoded, copy it in -mkdir -p runtime/doc -cp "doc/decorator.txt" runtime/doc - -# use luacacts etc. from neovim src -LUA_PATH="${NEOVIM_SRC}/src/?.lua" - -# generate -scripts/gen_vimdoc.lua - -# move the output -mv "runtime/doc/decorator.txt" doc -rmdir runtime/doc -rmdir runtime - diff --git a/scripts/gen_vimdoc.decorator.lua b/scripts/gen_vimdoc.decorator.lua deleted file mode 100644 index dd9a37681e7..00000000000 --- a/scripts/gen_vimdoc.decorator.lua +++ /dev/null @@ -1,49 +0,0 @@ ----@diagnostic disable: undefined-doc-name - ---- @param fun nvim.luacats.parser.fun ---- @return string -local function fn_helptag_fmt_common0(fun) - local fn_sfx = fun.table and '' or '()' - if fun.classvar then - return string.format('%s:%s%s', fun.classvar, fun.name, fn_sfx) - end - if fun.module then - return string.format('%s.%s%s', fun.module, fun.name, fn_sfx) - end - return fun.name .. fn_sfx -end - -return { - filename = "decorator.txt", - section_order = { - "api_decorator.lua", - }, - files = { - -- module is derived soley from the file name, first letter capitalised - -- 'runtime/lua/nvim-tree/foo/api_decorator.lua', - "/home/alex/src/nvim-tree/master/lua/nvim-tree/_meta/api_decorator.lua" - }, - section_fmt = function(name) - if name == "Api_decorator" then - return "Lua module: nvim_tree.api.decorator" - end - error(string.format("unknown module %s passed to section_fmt", name)) - end, - helptag_fmt = function(name) - -- used to locate the help section - if name == "Api_decorator" then - return "nvim-tree-decorators" - end - error(string.format("unknown module %s passed to helptag_fmt", name)) - end, - fn_helptag_fmt = function(fun) - -- use the fully qualified class name in the tag for methods - -- this is done everywhere but for classes - local common = fn_helptag_fmt_common0(fun) - local helptag = common - if fun.class then - helptag = common:gsub(fun.classvar, fun.class) - end - return helptag - end, -} diff --git a/scripts/gen_vimdoc.lua b/scripts/gen_vimdoc.lua deleted file mode 100755 index 6b1b5a6fbd8..00000000000 --- a/scripts/gen_vimdoc.lua +++ /dev/null @@ -1,823 +0,0 @@ -#!/usr/bin/env -S nvim -l - ----@diagnostic disable: assign-type-mismatch, incomplete-signature-doc, param-type-mismatch, undefined-doc-name, inject-field - ---- Generates Nvim :help docs from Lua/C docstrings. ---- ---- Usage: ---- make doc ---- ---- The generated :help text for each function is formatted as follows: ---- - Max width of 78 columns (`TEXT_WIDTH`). ---- - Indent with spaces (not tabs). ---- - Indent of 4 columns for body text (`INDENTATION`). ---- - Function signature and helptag (right-aligned) on the same line. ---- - Signature and helptag must have a minimum of 8 spaces between them. ---- - If the signature is too long, it is placed on the line after the helptag. ---- Signature wraps with subsequent lines indented to the open parenthesis. ---- - Subsection bodies are indented an additional 4 spaces. ---- - Body consists of function description, parameters, return description, and ---- C declaration (`INCLUDE_C_DECL`). ---- - Parameters are omitted for the `void` and `Error *` types, or if the ---- parameter is marked as [out]. ---- - Each function documentation is separated by a single line. - -local luacats_parser = require('gen.luacats_parser') -local cdoc_parser = require('gen.cdoc_parser') -local util = require('gen.util') - -local fmt = string.format - -local wrap = util.wrap -local md_to_vimdoc = util.md_to_vimdoc - -local TEXT_WIDTH = 78 -local INDENTATION = 4 - ---- @class (exact) nvim.gen_vimdoc.Config ---- ---- Generated documentation target, e.g. api.txt ---- @field filename string ---- ---- @field section_order string[] ---- ---- List of files/directories for doxygen to read, relative to `base_dir`. ---- @field files string[] ---- ---- Section name overrides. Key: filename (e.g., vim.c) ---- @field section_name? table ---- ---- @field fn_name_pat? string ---- ---- @field fn_xform? fun(fun: nvim.luacats.parser.fun) ---- ---- For generated section names. ---- @field section_fmt fun(name: string): string ---- ---- @field helptag_fmt fun(name: string): string|string[] ---- ---- Per-function helptag. ---- @field fn_helptag_fmt? fun(fun: nvim.luacats.parser.fun): string ---- ---- @field append_only? string[] - -local function contains(t, xs) - return vim.tbl_contains(xs, t) -end - ---- @type {level:integer, prerelease:boolean}? -local nvim_api_info_ - ---- @return {level: integer, prerelease:boolean} -local function nvim_api_info() - if not nvim_api_info_ then - --- @type integer?, boolean? - local level, prerelease - for l in io.lines('CMakeLists.txt') do - --- @cast l string - if level and prerelease then - break - end - local m1 = l:match('^set%(NVIM_API_LEVEL%s+(%d+)%)') - if m1 then - level = tonumber(m1) --[[@as integer]] - end - local m2 = l:match('^set%(NVIM_API_PRERELEASE%s+(%w+)%)') - if m2 then - prerelease = m2 == 'true' - end - end - nvim_api_info_ = { level = level, prerelease = prerelease } - end - - return nvim_api_info_ -end - ---- @param fun nvim.luacats.parser.fun ---- @return string -local function fn_helptag_fmt_common(fun) - local fn_sfx = fun.table and '' or '()' - if fun.classvar then - return fmt('%s:%s%s', fun.classvar, fun.name, fn_sfx) - end - if fun.module then - return fmt('%s.%s%s', fun.module, fun.name, fn_sfx) - end - return fun.name .. fn_sfx -end - ---- @type table -local config = { - decorator = { - filename = "decorator.txt", - section_order = { - "api_decorator.lua", - }, - files = { - -- module is derived soley from the file name, first letter capitalised - -- 'runtime/lua/nvim-tree/foo/api_decorator.lua', - "/home/alex/src/nvim-tree/master/lua/nvim-tree/_meta/api_decorator.lua" - }, - section_fmt = function(name) - if name == "Api_decorator" then - return "Lua module: nvim_tree.api.decorator" - end - error(string.format("unknown module %s passed to section_fmt", name)) - end, - helptag_fmt = function(name) - -- used to locate the help section - if name == "Api_decorator" then - return "nvim-tree-decorators" - end - error(string.format("unknown module %s passed to helptag_fmt", name)) - end, - fn_helptag_fmt = function(fun) - -- use the fully qualified class name in the tag for methods - -- this is done everywhere but for classes - local common = fn_helptag_fmt_common(fun) - local helptag = common - if fun.class then - helptag = common:gsub(fun.classvar, fun.class) - end - return helptag - end, - } -} - ---- @param ty string ---- @param generics table ---- @return string -local function replace_generics(ty, generics) - if ty:sub(-2) == '[]' then - local ty0 = ty:sub(1, -3) - if generics[ty0] then - return generics[ty0] .. '[]' - end - elseif ty:sub(-1) == '?' then - local ty0 = ty:sub(1, -2) - if generics[ty0] then - return generics[ty0] .. '?' - end - end - - return generics[ty] or ty -end - ---- @param name string -local function fmt_field_name(name) - local name0, opt = name:match('^([^?]*)(%??)$') - return fmt('{%s}%s', name0, opt) -end - ---- @param ty string ---- @param generics? table ---- @param default? string -local function render_type(ty, generics, default) - ty = ty:gsub('vim%.lsp%.protocol%.Method.[%w.]+', 'string') - - if generics then - ty = replace_generics(ty, generics) - end - ty = ty:gsub('%s*|%s*nil', '?') - ty = ty:gsub('nil%s*|%s*(.*)', '%1?') - ty = ty:gsub('%s*|%s*', '|') - if default then - return fmt('(`%s`, default: %s)', ty, default) - end - return fmt('(`%s`)', ty) -end - ---- @param p nvim.luacats.parser.param|nvim.luacats.parser.field -local function should_render_field_or_param(p) - return not p.nodoc - and not p.access - and not contains(p.name, { '_', 'self' }) - and not vim.startswith(p.name, '_') -end - ---- @param desc? string ---- @return string?, string? -local function get_default(desc) - if not desc then - return - end - - local default = desc:match('\n%s*%([dD]efault: ([^)]+)%)') - if default then - desc = desc:gsub('\n%s*%([dD]efault: [^)]+%)', '') - end - - return desc, default -end - ---- @param ty string ---- @param classes? table ---- @return nvim.luacats.parser.class? -local function get_class(ty, classes) - if not classes then - return - end - - local cty = ty:gsub('%s*|%s*nil', '?'):gsub('?$', ''):gsub('%[%]$', '') - - return classes[cty] -end - ---- @param obj nvim.luacats.parser.param|nvim.luacats.parser.return|nvim.luacats.parser.field ---- @param classes? table -local function inline_type(obj, classes) - local ty = obj.type - if not ty then - return - end - - local cls = get_class(ty, classes) - - if not cls or cls.nodoc then - return - end - - if not cls.inlinedoc then - -- Not inlining so just add a: "See |tag|." - local tag = fmt('|%s|', cls.name) - if obj.desc and obj.desc:find(tag) then - -- Tag already there - return - end - - -- TODO(lewis6991): Aim to remove this. Need this to prevent dead - -- references to types defined in runtime/lua/vim/lsp/_meta/protocol.lua - if not vim.startswith(cls.name, 'vim.') then - return - end - - obj.desc = obj.desc or '' - local period = (obj.desc == '' or vim.endswith(obj.desc, '.')) and '' or '.' - obj.desc = obj.desc .. fmt('%s See %s.', period, tag) - return - end - - local ty_isopt = (ty:match('%?$') or ty:match('%s*|%s*nil')) ~= nil - local ty_islist = (ty:match('%[%]$')) ~= nil - ty = ty_isopt and 'table?' or ty_islist and 'table[]' or 'table' - - local desc = obj.desc or '' - if cls.desc then - desc = desc .. cls.desc - elseif desc == '' then - if ty_islist then - desc = desc .. 'A list of objects with the following fields:' - elseif cls.parent then - desc = desc .. fmt('Extends |%s| with the additional fields:', cls.parent) - else - desc = desc .. 'A table with the following fields:' - end - end - - local desc_append = {} - for _, f in ipairs(cls.fields) do - if not f.access then - local fdesc, default = get_default(f.desc) - local fty = render_type(f.type, nil, default) - local fnm = fmt_field_name(f.name) - table.insert(desc_append, table.concat({ '-', fnm, fty, fdesc }, ' ')) - end - end - - desc = desc .. '\n' .. table.concat(desc_append, '\n') - obj.type = ty - obj.desc = desc -end - ---- @param xs (nvim.luacats.parser.param|nvim.luacats.parser.field)[] ---- @param generics? table ---- @param classes? table ---- @param cfg nvim.gen_vimdoc.Config -local function render_fields_or_params(xs, generics, classes, cfg) - local ret = {} --- @type string[] - - xs = vim.tbl_filter(should_render_field_or_param, xs) - - local indent = 0 - for _, p in ipairs(xs) do - if p.type or p.desc then - indent = math.max(indent, #p.name + 3) - end - end - - for _, p in ipairs(xs) do - local pdesc, default = get_default(p.desc) - p.desc = pdesc - - inline_type(p, classes) - local nm, ty = p.name, p.type - - local desc = p.classvar and fmt('See |%s|.', cfg.fn_helptag_fmt(p)) or p.desc - - local fnm = p.kind == 'operator' and fmt('op(%s)', nm) or fmt_field_name(nm) - local pnm = fmt(' • %-' .. indent .. 's', fnm) - - if ty then - local pty = render_type(ty, generics, default) - - if desc then - table.insert(ret, pnm) - if #pty > TEXT_WIDTH - indent then - vim.list_extend(ret, { ' ', pty, '\n' }) - table.insert(ret, md_to_vimdoc(desc, 9 + indent, 9 + indent, TEXT_WIDTH, true)) - else - desc = fmt('%s %s', pty, desc) - table.insert(ret, md_to_vimdoc(desc, 1, 9 + indent, TEXT_WIDTH, true)) - end - else - table.insert(ret, fmt('%s %s\n', pnm, pty)) - end - else - if desc then - table.insert(ret, pnm) - table.insert(ret, md_to_vimdoc(desc, 1, 9 + indent, TEXT_WIDTH, true)) - end - end - end - - return table.concat(ret) -end - ---- @param class nvim.luacats.parser.class ---- @param classes table ---- @param cfg nvim.gen_vimdoc.Config -local function render_class(class, classes, cfg) - if class.access or class.nodoc or class.inlinedoc then - return - end - - local ret = {} --- @type string[] - - table.insert(ret, fmt('*%s*\n', class.name)) - - if class.parent then - local txt = fmt('Extends: |%s|', class.parent) - table.insert(ret, md_to_vimdoc(txt, INDENTATION, INDENTATION, TEXT_WIDTH)) - table.insert(ret, '\n') - end - - if class.desc then - table.insert(ret, md_to_vimdoc(class.desc, INDENTATION, INDENTATION, TEXT_WIDTH)) - end - - local fields_txt = render_fields_or_params(class.fields, nil, classes, cfg) - if not fields_txt:match('^%s*$') then - table.insert(ret, '\n Fields: ~\n') - table.insert(ret, fields_txt) - end - table.insert(ret, '\n') - - return table.concat(ret) -end - ---- @param classes table ---- @param cfg nvim.gen_vimdoc.Config -local function render_classes(classes, cfg) - local ret = {} --- @type string[] - - for _, class in vim.spairs(classes) do - ret[#ret + 1] = render_class(class, classes, cfg) - end - - return table.concat(ret) -end - ---- @param fun nvim.luacats.parser.fun ---- @param cfg nvim.gen_vimdoc.Config -local function render_fun_header(fun, cfg) - local ret = {} --- @type string[] - - local args = {} --- @type string[] - for _, p in ipairs(fun.params or {}) do - if p.name ~= 'self' then - args[#args + 1] = fmt_field_name(p.name) - end - end - - local nm = fun.name - if fun.classvar then - nm = fmt('%s:%s', fun.classvar, nm) - end - if nm == 'vim.bo' then - nm = 'vim.bo[{bufnr}]' - end - if nm == 'vim.wo' then - nm = 'vim.wo[{winid}][{bufnr}]' - end - - local proto = fun.table and nm or nm .. '(' .. table.concat(args, ', ') .. ')' - - local tag = '*' .. cfg.fn_helptag_fmt(fun) .. '*' - - if #proto + #tag > TEXT_WIDTH - 8 then - table.insert(ret, fmt('%78s\n', tag)) - local name, pargs = proto:match('([^(]+%()(.*)') - table.insert(ret, name) - table.insert(ret, wrap(pargs, 0, #name, TEXT_WIDTH)) - else - local pad = TEXT_WIDTH - #proto - #tag - table.insert(ret, proto .. string.rep(' ', pad) .. tag) - end - - return table.concat(ret) -end - ---- @param returns nvim.luacats.parser.return[] ---- @param generics? table ---- @param classes? table ---- @return string? -local function render_returns(returns, generics, classes) - local ret = {} --- @type string[] - - if #returns == 1 and returns[1].type == 'nil' then - return - end - - if #returns > 1 then - table.insert(ret, ' Return (multiple): ~\n') - elseif #returns == 1 and next(returns[1]) then - table.insert(ret, ' Return: ~\n') - end - - for _, p in ipairs(returns) do - inline_type(p, classes) - local rnm, ty, desc = p.name, p.type, p.desc - - local blk = {} --- @type string[] - if ty then - blk[#blk + 1] = render_type(ty, generics) - end - blk[#blk + 1] = rnm - blk[#blk + 1] = desc - - ret[#ret + 1] = md_to_vimdoc(table.concat(blk, ' '), 8, 8, TEXT_WIDTH, true) - end - - return table.concat(ret) -end - ---- @param fun nvim.luacats.parser.fun ---- @param classes table ---- @param cfg nvim.gen_vimdoc.Config -local function render_fun(fun, classes, cfg) - if fun.access or fun.deprecated or fun.nodoc then - return - end - - if cfg.fn_name_pat and not fun.name:match(cfg.fn_name_pat) then - return - end - - if vim.startswith(fun.name, '_') or fun.name:find('[:.]_') then - return - end - - local ret = {} --- @type string[] - - table.insert(ret, render_fun_header(fun, cfg)) - table.insert(ret, '\n') - - if fun.since then - local since = assert(tonumber(fun.since), 'invalid @since on ' .. fun.name) - local info = nvim_api_info() - if since == 0 or (info.prerelease and since == info.level) then - -- Experimental = (since==0 or current prerelease) - local s = 'WARNING: This feature is experimental/unstable.' - table.insert(ret, md_to_vimdoc(s, INDENTATION, INDENTATION, TEXT_WIDTH)) - table.insert(ret, '\n') - else - local v = assert(util.version_level[since], 'invalid @since on ' .. fun.name) - fun.attrs = fun.attrs or {} - table.insert(fun.attrs, fmt('Since: %s', v)) - end - end - - if fun.desc then - table.insert(ret, md_to_vimdoc(fun.desc, INDENTATION, INDENTATION, TEXT_WIDTH)) - end - - if fun.notes then - table.insert(ret, '\n Note: ~\n') - for _, p in ipairs(fun.notes) do - table.insert(ret, ' • ' .. md_to_vimdoc(p.desc, 0, 8, TEXT_WIDTH, true)) - end - end - - if fun.attrs then - table.insert(ret, '\n Attributes: ~\n') - for _, attr in ipairs(fun.attrs) do - local attr_str = ({ - textlock = 'not allowed when |textlock| is active or in the |cmdwin|', - textlock_allow_cmdwin = 'not allowed when |textlock| is active', - fast = '|api-fast|', - remote_only = '|RPC| only', - lua_only = 'Lua |vim.api| only', - })[attr] or attr - table.insert(ret, fmt(' %s\n', attr_str)) - end - end - - if fun.params and #fun.params > 0 then - local param_txt = render_fields_or_params(fun.params, fun.generics, classes, cfg) - if not param_txt:match('^%s*$') then - table.insert(ret, '\n Parameters: ~\n') - ret[#ret + 1] = param_txt - end - end - - if fun.overloads then - table.insert(ret, '\n Overloads: ~\n') - for _, p in ipairs(fun.overloads) do - table.insert(ret, fmt(' • `%s`\n', p)) - end - end - - if fun.returns then - local txt = render_returns(fun.returns, fun.generics, classes) - if txt and not txt:match('^%s*$') then - table.insert(ret, '\n') - ret[#ret + 1] = txt - end - end - - if fun.see then - table.insert(ret, '\n See also: ~\n') - for _, p in ipairs(fun.see) do - table.insert(ret, ' • ' .. md_to_vimdoc(p.desc, 0, 8, TEXT_WIDTH, true)) - end - end - - table.insert(ret, '\n') - return table.concat(ret) -end - ---- @param funs nvim.luacats.parser.fun[] ---- @param classes table ---- @param cfg nvim.gen_vimdoc.Config -local function render_funs(funs, classes, cfg) - local ret = {} --- @type string[] - - for _, f in ipairs(funs) do - if cfg.fn_xform then - cfg.fn_xform(f) - end - ret[#ret + 1] = render_fun(f, classes, cfg) - end - - -- Sort via prototype. Experimental API functions ("nvim__") sort last. - table.sort(ret, function(a, b) - local a1 = ('\n' .. a):match('\n[a-zA-Z_][^\n]+\n') - local b1 = ('\n' .. b):match('\n[a-zA-Z_][^\n]+\n') - - local a1__ = a1:find('^%s*nvim__') and 1 or 0 - local b1__ = b1:find('^%s*nvim__') and 1 or 0 - if a1__ ~= b1__ then - return a1__ < b1__ - end - - return a1:lower() < b1:lower() - end) - - return table.concat(ret) -end - ---- @return string -local function get_script_path() - local str = debug.getinfo(2, 'S').source:gsub('^@', '') - return str:match('(.*[/\\])') or './' -end - -local script_path = get_script_path() -local base_dir = vim.fs.dirname(vim.fs.dirname(vim.fs.dirname(script_path))) - -local function delete_lines_below(doc_file, tokenstr) - local lines = {} --- @type string[] - local found = false - for line in io.lines(doc_file) do - if line:find(vim.pesc(tokenstr)) then - found = true - break - end - lines[#lines + 1] = line - end - if not found then - error(fmt('not found: %s in %s', tokenstr, doc_file)) - end - lines[#lines] = nil - local fp = assert(io.open(doc_file, 'w')) - fp:write(table.concat(lines, '\n')) - fp:write('\n') - fp:close() -end - ---- @param x string -local function mktitle(x) - if x == 'ui' then - return 'UI' - end - return x:sub(1, 1):upper() .. x:sub(2) -end - ---- @class nvim.gen_vimdoc.Section ---- @field name string ---- @field title string ---- @field help_tag string ---- @field funs_txt string ---- @field classes_txt string ---- @field briefs string[] - ---- @param filename string ---- @param cfg nvim.gen_vimdoc.Config ---- @param briefs string[] ---- @param funs_txt string ---- @param classes_txt string ---- @return nvim.gen_vimdoc.Section? -local function make_section(filename, cfg, briefs, funs_txt, classes_txt) - -- filename: e.g., 'autocmd.c' - -- name: e.g. 'autocmd' - local name = filename:match('(.*)%.[a-z]+') - - -- Formatted (this is what's going to be written in the vimdoc) - -- e.g., "Autocmd Functions" - local sectname = cfg.section_name and cfg.section_name[filename] or mktitle(name) - - -- section tag: e.g., "*api-autocmd*" - local help_labels = cfg.helptag_fmt(sectname) - if type(help_labels) == 'table' then - help_labels = table.concat(help_labels, '* *') - end - local help_tags = '*' .. help_labels .. '*' - - if funs_txt == '' and classes_txt == '' and #briefs == 0 then - return - end - - return { - name = sectname, - title = cfg.section_fmt(sectname), - help_tag = help_tags, - funs_txt = funs_txt, - classes_txt = classes_txt, - briefs = briefs, - } -end - ---- @param section nvim.gen_vimdoc.Section ---- @param add_header? boolean -local function render_section(section, add_header) - local doc = {} --- @type string[] - - if add_header ~= false then - vim.list_extend(doc, { - string.rep('=', TEXT_WIDTH), - '\n', - section.title, - fmt('%' .. (TEXT_WIDTH - section.title:len()) .. 's', section.help_tag), - }) - end - - if next(section.briefs) then - local briefs_txt = {} --- @type string[] - for _, b in ipairs(section.briefs) do - briefs_txt[#briefs_txt + 1] = md_to_vimdoc(b, 0, 0, TEXT_WIDTH) - end - - local sdoc = '\n\n' .. table.concat(briefs_txt, '\n') - if sdoc:find('[^%s]') then - doc[#doc + 1] = sdoc - end - end - - if section.classes_txt ~= '' then - table.insert(doc, '\n\n') - table.insert(doc, (section.classes_txt:gsub('\n+$', '\n'))) - end - - if section.funs_txt ~= '' then - table.insert(doc, '\n\n') - table.insert(doc, section.funs_txt) - end - - return table.concat(doc) -end - -local parsers = { - lua = luacats_parser.parse, - c = cdoc_parser.parse, - h = cdoc_parser.parse, -} - ---- @param files string[] -local function expand_files(files) - for k, f in pairs(files) do - if vim.fn.isdirectory(f) == 1 then - table.remove(files, k) - for path, ty in vim.fs.dir(f) do - if ty == 'file' then - table.insert(files, vim.fs.joinpath(f, path)) - end - end - end - end -end - ---- @param classes table ---- @return string? -local function find_module_class(classes, modvar) - for nm, cls in pairs(classes) do - local _, field = next(cls.fields or {}) - if cls.desc and field and field.classvar == modvar then - return nm - end - end -end - ---- @param cfg nvim.gen_vimdoc.Config -local function gen_target(cfg) - cfg.fn_helptag_fmt = cfg.fn_helptag_fmt or fn_helptag_fmt_common - print('Target:', cfg.filename) - local sections = {} --- @type table - - expand_files(cfg.files) - - --- @type table, nvim.luacats.parser.fun[], string[]]> - local file_results = {} - - --- @type table - local all_classes = {} - - --- First pass so we can collect all classes - for _, f in vim.spairs(cfg.files) do - local ext = f:match('%.([^.]+)$') - local parser = parsers[ext] - if parser then - local classes, funs, briefs = parser(f) - file_results[f] = { classes, funs, briefs } - all_classes = vim.tbl_extend('error', all_classes, classes) - end - end - - for f, r in vim.spairs(file_results) do - local classes, funs, briefs = r[1], r[2], r[3] - - local mod_cls_nm = find_module_class(classes, 'M') - if mod_cls_nm then - local mod_cls = classes[mod_cls_nm] - classes[mod_cls_nm] = nil - -- If the module documentation is present, add it to the briefs - -- so it appears at the top of the section. - briefs[#briefs + 1] = mod_cls.desc - end - - print(' Processing file:', f) - - -- FIXME: Using f_base will confuse `_meta/protocol.lua` with `protocol.lua` - local f_base = vim.fs.basename(f) - sections[f_base] = make_section( - f_base, - cfg, - briefs, - render_funs(funs, all_classes, cfg), - render_classes(classes, cfg) - ) - end - - local first_section_tag = sections[cfg.section_order[1]].help_tag - local docs = {} --- @type string[] - for _, f in ipairs(cfg.section_order) do - local section = sections[f] - if section then - print(fmt(" Rendering section: '%s'", section.title)) - local add_sep_and_header = not vim.tbl_contains(cfg.append_only or {}, f) - docs[#docs + 1] = render_section(section, add_sep_and_header) - end - end - - table.insert( - docs, - fmt(' vim:tw=78:ts=8:sw=%d:sts=%d:et:ft=help:norl:\n', INDENTATION, INDENTATION) - ) - - local doc_file = vim.fs.joinpath(base_dir, 'runtime', 'doc', cfg.filename) - - if vim.uv.fs_stat(doc_file) then - delete_lines_below(doc_file, first_section_tag) - end - - local fp = assert(io.open(doc_file, 'a')) - fp:write(table.concat(docs, '\n')) - fp:close() -end - -local function run() - for _, cfg in vim.spairs(config) do - gen_target(cfg) - end -end - -run() diff --git a/scripts/gen_vimdoc.sh b/scripts/gen_vimdoc.sh new file mode 100755 index 00000000000..9496be31f5e --- /dev/null +++ b/scripts/gen_vimdoc.sh @@ -0,0 +1,31 @@ +#!/usr/bin/env sh + +set -e + +if [ ! -d "${NEOVIM_SRC}" ]; then + echo "\$NEOVIM_SRC not set" + exit 1 +fi + +# runtime/doc is hardcoded, copy the help in +mkdir -pv runtime/doc +cp -v "doc/nvim-tree-lua.txt" runtime/doc + +# modify gen_vimdoc.lua to use our config +cp -v "${NEOVIM_SRC}/src/gen/gen_vimdoc.lua" scripts/gen_vimdoc.lua +sed -i -E 's/spairs\(config\)/spairs\(require("gen_vimdoc_nvim-tree")\)/g' scripts/gen_vimdoc.lua + +# use luacacts etc. from neovim src as well as our specific config +LUA_PATH="${NEOVIM_SRC}/src/?.lua;scripts/gen_vimdoc_config.lua;${LUA_PATH}" + +# generate +scripts/gen_vimdoc.lua + +# move the new help back out +mv -v "runtime/doc/nvim-tree-lua.txt" doc +rmdir -v runtime/doc +rmdir -v runtime + +# clean up +rm -v scripts/gen_vimdoc.lua + diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua new file mode 100644 index 00000000000..8ef1730efee --- /dev/null +++ b/scripts/gen_vimdoc_config.lua @@ -0,0 +1,44 @@ +---@diagnostic disable: undefined-doc-name + +--- @type table +local config = { + decorator = { + filename = "nvim-tree-lua.txt", + -- filename = "decorator.txt", + section_order = { + "api_decorator.lua", + }, + files = { + -- module is derived soley from the file name, first letter capitalised + "lua/nvim-tree/_meta/api_decorator.lua", + }, + section_fmt = function(name) + if name == "Api_decorator" then + return " 6.11 API DECORATOR" + end + error(string.format("unknown module %s passed to section_fmt", name)) + end, + helptag_fmt = function(name) + -- used to locate the help section + if name == "Api_decorator" then + return "nvim-tree-api.decorator" + end + error(string.format("unknown module %s passed to helptag_fmt", name)) + end, + fn_helptag_fmt = function(fun) + -- Modified copy of fn_helptag_fmt_common + -- Uses fully qualified class name in the tag for methods. + -- The module is used everywhere else, however not available for classes. + local fn_sfx = fun.table and "" or "()" + if fun.classvar then + return string.format("%s:%s%s", fun.class or fun.classvar, fun.name, fn_sfx) + end + if fun.module then + return string.format("%s.%s%s", fun.module, fun.name, fn_sfx) + end + return fun.name .. fn_sfx + end, + } +} + +return config From a5a823b8eac22cc81bbb0d1bac30c2b337a21228 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sun, 4 Jan 2026 16:47:10 +1100 Subject: [PATCH 003/170] doc(#2934): tidy and harden scripts --- scripts/gen_vimdoc.sh | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/scripts/gen_vimdoc.sh b/scripts/gen_vimdoc.sh index 9496be31f5e..fa0d28b4265 100755 --- a/scripts/gen_vimdoc.sh +++ b/scripts/gen_vimdoc.sh @@ -12,20 +12,20 @@ mkdir -pv runtime/doc cp -v "doc/nvim-tree-lua.txt" runtime/doc # modify gen_vimdoc.lua to use our config -cp -v "${NEOVIM_SRC}/src/gen/gen_vimdoc.lua" scripts/gen_vimdoc.lua -sed -i -E 's/spairs\(config\)/spairs\(require("gen_vimdoc_nvim-tree")\)/g' scripts/gen_vimdoc.lua +cp -v "${NEOVIM_SRC}/src/gen/gen_vimdoc.lua" gen_vimdoc.lua +sed -i -E 's/spairs\(config\)/spairs\(require("gen_vimdoc_config")\)/g' gen_vimdoc.lua # use luacacts etc. from neovim src as well as our specific config -LUA_PATH="${NEOVIM_SRC}/src/?.lua;scripts/gen_vimdoc_config.lua;${LUA_PATH}" +export LUA_PATH="${NEOVIM_SRC}/src/?.lua;scripts/?.lua" # generate -scripts/gen_vimdoc.lua +./gen_vimdoc.lua -# move the new help back out +# move the generated help out mv -v "runtime/doc/nvim-tree-lua.txt" doc -rmdir -v runtime/doc -rmdir -v runtime # clean up -rm -v scripts/gen_vimdoc.lua +rmdir -v runtime/doc +rmdir -v runtime +rm -v gen_vimdoc.lua From 1960d3a9941c7a67defa95429c324c83ae2cb559 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Mon, 5 Jan 2026 12:15:07 +1100 Subject: [PATCH 004/170] doc(#2934): add nvim_tree.Config meta classes, add nvim_tree.api. meta classes --- lua/nvim-tree.lua | 4 +- lua/nvim-tree/_meta/api.lua | 53 +++ lua/nvim-tree/_meta/config.lua | 405 ++++++++++++++++++ lua/nvim-tree/actions/node/buffer.lua | 6 +- lua/nvim-tree/actions/tree/find-file.lua | 2 +- .../actions/tree/modifiers/collapse.lua | 6 +- .../actions/tree/modifiers/expand.lua | 6 +- lua/nvim-tree/actions/tree/open.lua | 2 +- lua/nvim-tree/actions/tree/resize.lua | 2 +- lua/nvim-tree/actions/tree/toggle.lua | 2 +- lua/nvim-tree/api.lua | 66 +-- lua/nvim-tree/view.lua | 4 +- 12 files changed, 490 insertions(+), 68 deletions(-) create mode 100644 lua/nvim-tree/_meta/config.lua diff --git a/lua/nvim-tree.lua b/lua/nvim-tree.lua index 9fe579ccdfe..25e0e98bc62 100644 --- a/lua/nvim-tree.lua +++ b/lua/nvim-tree.lua @@ -627,7 +627,7 @@ local ACCEPTED_ENUMS = { }, } ----@param conf table|nil +---@param conf? nvim_tree.Config local function validate_options(conf) local msg @@ -732,7 +732,7 @@ function M.purge_all_state() require("nvim-tree.watcher").purge_watchers() end ----@param conf table|nil +---@param conf? nvim_tree.Config function M.setup(conf) if vim.fn.has("nvim-0.9") == 0 then notify.warn("nvim-tree.lua requires Neovim 0.9 or higher") diff --git a/lua/nvim-tree/_meta/api.lua b/lua/nvim-tree/_meta/api.lua index d6847940781..dd5f0c32a93 100644 --- a/lua/nvim-tree/_meta/api.lua +++ b/lua/nvim-tree/_meta/api.lua @@ -1,6 +1,59 @@ ---@meta error("Cannot require a meta file") +-- +-- API Options +-- + +---@class nvim_tree.api.TreeOpenOpts +---@field path? string root directory for the tree +---@field current_window? boolean open the tree in the current window +---@field winid? number open the tree in the specified winid, overrides current_window +---@field find_file? boolean find the current buffer +---@field update_root? boolean requires find_file, see |nvim-tree.update_focused_file.update_root| +---@field focus? boolean focus the tree when opening, default true + +---@class nvim_tree.api.TreeToggleOpts +---@field path? string root directory for the tree +---@field current_window? boolean open the tree in the current window +---@field winid? number open the tree in the specified |winid|, overrides current_window +---@field find_file? boolean find the current buffer +---@field update_root? boolean requires find_file, see |nvim-tree.update_focused_file.update_root| +---@field focus? boolean focus the tree when opening, default true + +---@class nvim_tree.api.TreeResizeOpts +---@field width? string|function|number|table new |nvim-tree.view.width| value +---@field absolute? number set the width +---@field relative? number relative width adjustment + +---@class nvim_tree.api.TreeFindFileOpts +---@field buf? string|number absolute/relative path OR bufnr to find +---@field open? boolean open the tree if necessary +---@field current_window? boolean requires open, open in the current window +---@field winid? number open the tree in the specified |winid|, overrides current_window +---@field update_root? boolean see |nvim-tree.update_focused_file.update_root| +---@field focus? boolean focus the tree + +---@class nvim_tree.api.CollapseOpts +---@field keep_buffers? boolean do not collapse nodes with open buffers + +---@class nvim_tree.api.TreeExpandOpts +---@field expand_until? (fun(expansion_count: integer, node: Node): boolean) Return true if node should be expanded. expansion_count is the total number of folders expanded. + +---@class nvim_tree.api.TreeIsVisibleOpts +---@field tabpage? number as per |nvim_get_current_tabpage()| +---@field any_tabpage? boolean visible on any tab, default false + +---@class nvim_tree.api.TreeWinIdOpts +---@field tabpage? number tabpage, 0 or nil for current, default nil + +---@class nvim_tree.api.NodeEditOpts +---@field quit_on_open? boolean quits the tree when opening the file +---@field focus? boolean keep focus in the tree when opening the file + +---@class nvim_tree.api.NodeBufferOpts +---@field force? boolean delete/wipe even if buffer is modified, default false + -- -- Nodes -- diff --git a/lua/nvim-tree/_meta/config.lua b/lua/nvim-tree/_meta/config.lua new file mode 100644 index 00000000000..f00523978cd --- /dev/null +++ b/lua/nvim-tree/_meta/config.lua @@ -0,0 +1,405 @@ +---@meta +error("Cannot require a meta file") + +-- The nvim_tree global namespace exists at runtime but cannot be declared in meta files. +-- This suppression allows referencing the namespace for type definitions. +---@diagnostic disable: undefined-global + +-- +-- Type Aliases for Enums +-- + +---@alias nvim_tree.PlacementOption "before"|"after"|"signcolumn"|"right_align" +---@alias nvim_tree.HighlightOption "none"|"icon"|"name"|"all" +---@alias nvim_tree.HiddenDisplayOption "none"|"simple"|"all" +---@alias nvim_tree.SortOption "name"|"case_sensitive"|"modification_time"|"extension"|"suffix"|"filetype" +---@alias nvim_tree.HelpSortOption "key"|"desc" + +-- +-- nvim-tree Setup Config +-- + +---@class nvim_tree.Config +---@field on_attach? string|fun(bufnr: integer) +---@field auto_reload_on_write? boolean Reloads the explorer every time a buffer is written to. Default: `true` +---@field disable_netrw? boolean Completely disable netrw Default: `false` +---@field hijack_cursor? boolean Keeps the cursor on the first letter of the filename when moving in the tree. Default: `false` +---@field hijack_netrw? boolean Hijack netrw windows (overridden if |disable_netrw| is `true`) Default: `true` +---@field hijack_unnamed_buffer_when_opening? boolean Opens in place of the unnamed buffer if it's empty. Default: `false` +---@field prefer_startup_root? boolean Prefer startup root directory when updating root directory of the tree. Only relevant when `update_focused_file.update_root` is `true` Default: `false` @see nvim-tree.update_focused_file.update_root +---@field reload_on_bufenter? boolean Automatically reloads the tree on `BufEnter` nvim-tree. Default: `false` +---@field respect_buf_cwd? boolean Will change cwd of nvim-tree to that of new buffer's when opening nvim-tree. Default: `false` +---@field select_prompts? boolean Use |vim.ui.select| style prompts. Necessary when using a UI prompt decorator such as dressing.nvim or telescope-ui-select.nvim Default: `false` +---@field sync_root_with_cwd? boolean Changes the tree root directory on `DirChanged` and refreshes the tree. Default: `false` +---@field root_dirs? string[] Preferred root directories. Only relevant when `update_focused_file.update_root` is `true` Default: `{}` @see nvim-tree.update_focused_file.update_root +---@field experimental? table Experimental features that may become default or optional functionality. In the event of a problem please disable the experiment and raise an issue. +---@field hijack_directories? nvim_tree.Config.HijackDirectories +---@field renderer? nvim_tree.Config.Renderer +---@field modified? nvim_tree.Config.Modified +---@field tab? nvim_tree.Config.Tab +---@field trash? nvim_tree.Config.Trash +---@field live_filter? nvim_tree.Config.LiveFilter +---@field system_open? nvim_tree.Config.SystemOpen +---@field help? nvim_tree.Config.Help +---@field sort? nvim_tree.Config.Sort +---@field filters? nvim_tree.Config.Filters +---@field update_focused_file? nvim_tree.Config.UpdateFocusedFile +---@field git? nvim_tree.Config.Git +---@field diagnostics? nvim_tree.Config.Diagnostics +---@field notify? nvim_tree.Config.Notify +---@field filesystem_watchers? nvim_tree.Config.FilesystemWatchers +---@field log? nvim_tree.Config.Log +---@field ui? nvim_tree.Config.UI +---@field actions? nvim_tree.Config.Actions +---@field view? nvim_tree.Config.View + +-- +-- HijackDirectories +-- + +---@class nvim_tree.Config.HijackDirectories +---@field enable? boolean Enable the feature. Disable this option if you use vim-dirvish or dirbuf.nvim. If `hijack_netrw` and `disable_netrw` are `false`, this feature will be disabled. Default: `true` +---@field auto_open? boolean Opens the tree if the tree was previously closed. Default: `true` + +-- +-- Renderer +-- + +---@class nvim_tree.Config.Renderer +---@field add_trailing? boolean Appends a trailing slash to folder and symlink folder destination names. Default: `false` +---@field group_empty? boolean|fun(relative_path: string): string Compact folders that only contain a single folder into one node. Boolean or function that takes one argument (the relative path of grouped folders) and returns a string to be displayed. Default: `false` +---@field full_name? boolean Display node whose name length is wider than the width of nvim-tree window in floating window. Default: `false` +---@field root_folder_label? string|boolean|fun(root_cwd: string): string In what format to show root folder. See `:help filename-modifiers` for available `string` options. Set to `false` to hide the root folder. or `boolean` or `function(root_cwd)`, Default: `":~:s?$?/..?"` +---@field indent_width? integer Number of spaces for an each tree nesting level. Minimum 1. Default: `2` +---@field special_files? string[] A list of filenames that gets highlighted with `NvimTreeSpecialFile`. Default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }` +---@field hidden_display? fun(hidden_stats: table): string|nil|nvim_tree.HiddenDisplayOption Show a summary of hidden files below the tree using `NvimTreeHiddenDisplay Default: `"none"` +---@field symlink_destination? boolean Whether to show the destination of the symlink. Default: `true` +---@field decorators? (string|nvim_tree.api.decorator.UserDecorator)[] Highlighting and icons for the nodes, in increasing order of precedence. Uses strings to specify builtin decorators otherwise specify your `nvim_tree.api.decorator.UserDecorator` class. Default: > lua { "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", } +---@field highlight_git? nvim_tree.HighlightOption Enable highlight for git attributes using `NvimTreeGit*HL` highlight groups. Requires |nvim-tree.git.enable| Value can be `"none"`, `"icon"`, `"name"` or `"all"`. Default: `"none"` @see nvim-tree.git.enable +---@field highlight_diagnostics? nvim_tree.HighlightOption Enable highlight for diagnostics using `NvimTreeDiagnostic*HL` highlight groups. Requires |nvim-tree.diagnostics.enable| Value can be `"none"`, `"icon"`, `"name"` or `"all"`. Default: `"none"` @see nvim-tree.diagnostics.enable +---@field highlight_opened_files? nvim_tree.HighlightOption Highlight icons and/or names for |bufloaded()| files using the `NvimTreeOpenedHL` highlight group. See |nvim-tree-api.navigate.opened.next()| and |nvim-tree-api.navigate.opened.prev()| Value can be `"none"`, `"icon"`, `"name"` or `"all"`. Default: `"none"` +---@field highlight_modified? nvim_tree.HighlightOption Highlight icons and/or names for modified files using the `NvimTreeModifiedFile` highlight group. Requires |nvim-tree.modified.enable| Value can be `"none"`, `"icon"`, `"name"` or `"all"` Default `"none"` @see nvim-tree.modified.enable +---@field highlight_hidden? nvim_tree.HighlightOption Highlight icons and/or names for hidden files (dotfiles) using the `NvimTreeHiddenFileHL` highlight group. Value can be `"none"`, `"icon"`, `"name"` or `"all"` Default `"none"` +---@field highlight_bookmarks? nvim_tree.HighlightOption Highlight bookmarked using the `NvimTreeBookmarkHL` group. Value can be `"none"`, `"icon"`, `"name"` or `"all"` Default `"none"` +---@field highlight_clipboard? nvim_tree.HighlightOption Enable highlight for clipboard items using the `NvimTreeCutHL` and `NvimTreeCopiedHL` groups. Value can be `"none"`, `"icon"`, `"name"` or `"all"`. Default: `"name"` +---@field indent_markers? nvim_tree.Config.Renderer.IndentMarkers Configuration options for tree indent markers. +---@field icons? nvim_tree.Config.Renderer.Icons Configuration options for icons. + +---@class nvim_tree.Config.Renderer.IndentMarkers +---@field enable? boolean Display indent markers when folders are open Default: `false` +---@field inline_arrows? boolean Display folder arrows in the same column as indent marker when using |renderer.icons.show.folder_arrow| Default: `true` +---@field icons? nvim_tree.Config.Renderer.IndentMarkers.Icons Icons shown before the file/directory. Length 1. Default: > lua { corner = "└", edge = "│", item = "│", bottom = "─", none = " ", } + +---@class nvim_tree.Config.Renderer.IndentMarkers.Icons +---@field corner? string Default: `"└"` +---@field edge? string Default: `"│"` +---@field item? string Default: `"│"` +---@field bottom? string Default: `"─"` +---@field none? string Default: `" "` + +---@class nvim_tree.Config.Renderer.Icons Configuration options for icons. +---@field web_devicons? nvim_tree.Config.Renderer.Icons.WebDevicons Configure optional plugin `"nvim-tree/nvim-web-devicons"` +---@field git_placement? nvim_tree.PlacementOption Git icons placement. Default: `"before"` +---@field diagnostics_placement? nvim_tree.PlacementOption Diganostic icon placement. Default: `"signcolumn"` @see nvim-tree.view.signcolumn @see nvim-tree.renderer.icons.show.diagnostics +---@field modified_placement? nvim_tree.PlacementOption Modified icon placement. Default: `"after"` +---@field hidden_placement? nvim_tree.PlacementOption Hidden icon placement. Default: `"after"` +---@field bookmarks_placement? nvim_tree.PlacementOption Bookmark icon placement. Default: `"signcolumn"` @see nvim-tree.renderer.icons.show.bookmarks +---@field padding? nvim_tree.Config.Renderer.Icons.Padding +---@field symlink_arrow? string Used as a separator between symlinks' source and target. Default: `" ➛ "` +---@field show? nvim_tree.Config.Renderer.Icons.Show Configuration options for showing icon types. Left to right order: file/folder, git, modified, hidden, diagnostics, bookmarked. +---@field glyphs? nvim_tree.Config.Renderer.Icons.Glyphs Configuration options for icon glyphs. NOTE: Do not set any glyphs to more than two characters if it's going to appear in the signcolumn. + +---@class nvim_tree.Config.Renderer.Icons.WebDevicons +---@field file? nvim_tree.Config.Renderer.Icons.WebDevicons.File File icons. +---@field folder? nvim_tree.Config.Renderer.Icons.WebDevicons.Folder Folder icons. + +---@class nvim_tree.Config.Renderer.Icons.WebDevicons.File +---@field enable? boolean Show icons on files. Overrides |nvim-tree.renderer.icons.glyphs.default| Default: `true` +---@field color? boolean Use icon colors for files. Overrides highlight groups. Default: `true` + +---@class nvim_tree.Config.Renderer.Icons.WebDevicons.Folder +---@field enable? boolean Show icons on folders. Overrides |nvim-tree.renderer.icons.glyphs.folder| Default: `false` +---@field color? boolean Use icon colors for folders. Overrides highlight groups. Default: `true` + +---@class nvim_tree.Config.Renderer.Icons.Padding +---@field icon? string Inserted between icon and filename. Default: `" "` +---@field folder_arrow? string Inserted between folder arrow icon and file/folder icon. Default: `" "` + +---@class nvim_tree.Config.Renderer.Icons.Show +---@field file? boolean Show an icon before the file name. Default: `true` +---@field folder? boolean Show an icon before the folder name. Default: `true` +---@field folder_arrow? boolean Show a small arrow before the folder node. Arrow will be a part of the node when using |renderer.indent_markers|. Default: `true` +---@field git? boolean Show a git status icon, see |renderer.icons.git_placement| Requires |git.enable| `= true` Default: `true` @see nvim-tree.renderer.icons.git_placement @see nvim-tree.git.enable +---@field modified? boolean Show a modified icon, see |renderer.icons.modified_placement| Requires |modified.enable| `= true` Default: `true` @see nvim-tree.renderer.icons.modified_placement @see nvim-tree.modified.enable +---@field hidden? boolean Show a hidden icon, see |renderer.icons.hidden_placement| Default: `false` @see nvim-tree.renderer.icons.hidden_placement +---@field diagnostics? boolean Show a diagnostics status icon, see |renderer.icons.diagnostics_placement| Requires |diagnostics.enable| `= true` Default: `true` @see nvim-tree.renderer.icons.diagnostics_placement @see nvim-tree.diagnostics.enable +---@field bookmarks? boolean Show a bookmark icon, see |renderer.icons.bookmarks_placement| Default: `true` @see nvim-tree.renderer.icons.bookmarks_placement + +---@class nvim_tree.Config.Renderer.Icons.Glyphs +---@field default? string Glyph for files. Overridden by |nvim-tree.renderer.icons.web_devicons| if available. Default: `""` +---@field symlink? string Glyph for symlinks to files. Default: `""` +---@field bookmark? string Bookmark icon. Default: `"Ὰ4"` +---@field modified? string Icon to display for modified files. Default: `"●"` +---@field hidden? string Icon to display for hidden files. Default: `"c""` +---@field folder? nvim_tree.Config.Renderer.Icons.Glyphs.Folder Glyphs for directories. Overridden by |nvim-tree.renderer.icons.web_devicons| if available. Default: `{ arrow_closed = "", arrow_open = "", default = "", open = "", empty = "", empty_open = "", symlink = "", symlink_open = "", }` +---@field git? nvim_tree.Config.Renderer.Icons.Glyphs.Git Glyphs for git status. Default: `{ unstaged = "✗", staged = "✓", unmerged = "", renamed = "➜", untracked = "★", deleted = "", ignored = "◌", }` + +---@class nvim_tree.Config.Renderer.Icons.Glyphs.Folder +---@field arrow_closed? string Default: `""` +---@field arrow_open? string Default: `""` +---@field default? string Default: `""` +---@field open? string Default: `""` +---@field empty? string Default: `""` +---@field empty_open? string Default: `""` +---@field symlink? string Default: `""` +---@field symlink_open? string Default: `""` + +---@class nvim_tree.Config.Renderer.Icons.Glyphs.Git +---@field unstaged? string Default: `"✗"` +---@field staged? string Default: `"✓"` +---@field unmerged? string Default: `""` +---@field renamed? string Default: `"➜"` +---@field untracked? string Default: `"★"` +---@field deleted? string Default: `""` +---@field ignored? string Default: `"◌"` + +-- +-- Modified +-- + +---@class nvim_tree.Config.Modified +---@field enable? boolean Enable / disable the feature. Default: `false` +---@field show_on_dirs? boolean Show modified indication on directory whose children are modified. Default: `true` +---@field show_on_open_dirs? boolean Show modified indication on open directories. Only relevant when |modified.show_on_dirs| is `true`. Default: `false` @see nvim-tree.modified.show_on_dirs + +-- +-- Tab +-- + +---@class nvim_tree.Config.Tab +---@field sync? nvim_tree.Config.Tab.Sync Configuration for syncing nvim-tree across tabs. + +---@class nvim_tree.Config.Tab.Sync +---@field open? boolean Opens the tree automatically when switching tabpage or opening a new tabpage if the tree was previously open. Default: `false` +---@field close? boolean Closes the tree across all tabpages when the tree is closed. Default: `false` +---@field ignore? string[] List of filetypes or buffer names on new tab that will prevent |nvim-tree.tab.sync.open| and |nvim-tree.tab.sync.close| Default: `{}` + +-- +-- Trash +-- + +---@class nvim_tree.Config.Trash +---@field cmd? string The command used to trash items (must be installed on your system). Default linux `"gio trash"` from glib2 is a commonly shipped linux package. macOS default `"trash"` requires the homebrew package `trash` Windows default `"trash"` requires `trash-cli` or similar Default: `"gio trash"` or `"trash"` + +-- +-- Live Filter +-- + +---@class nvim_tree.Config.LiveFilter +---@field prefix? string Prefix of the filter displayed in the buffer. Default: `"[FILTER]: "` +---@field always_show_folders? boolean Whether to filter folders or not. Default: `true` + +-- +-- System Open +-- + +---@class nvim_tree.Config.SystemOpen +---@field cmd? string The open command itself. Default: `""` neovim >= 0.10 defaults to |vim.ui.open| neovim < 0.10 defaults to: UNIX: `"xdg-open"` macOS: `"open"` Windows: `"cmd"` +---@field args? string[] Optional argument list. Default: `{}` Leave empty for OS specific default: Windows: `{ "/c", "start", '""' }` + +-- +-- Help +-- + +---@class nvim_tree.Config.Help +---@field sort_by? nvim_tree.HelpSortOption Defines how mappings are sorted in the help window. Can be `"key"` (sort alphabetically by keymap) or `"desc"` (sort alphabetically by description). Default: `"key"` + +-- +-- Sort +-- + +---@class nvim_tree.Config.Sort +---@field sorter? nvim_tree.SortOption|fun(nodes: table): nil Changes how files within the same directory are sorted. Can be one of `"name"`, `"case_sensitive"`, `"modification_time"`, `"extension"`, `"suffix"`, `"filetype"` or a function. `"extension"` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz` `"suffix"` uses the last e.g. `.gz` Default: `"name"` Function may perform a sort or return a string with one of the above methods. It is passed a table of nodes to be sorted, each node containing: - `absolute_path`: `string` - `executable`: `boolean` - `extension`: `string` - `filetype`: `string` - `link_to`: `string` - `name`: `string` - `type`: `"directory"` | `"file"` | `"link"` +---@field folders_first? boolean Sort folders before files. Has no effect when |nvim-tree.sort.sorter| is a function. Default: `true` @see nvim-tree.sort.sorter +---@field files_first? boolean Sort files before folders. Has no effect when |nvim-tree.sort.sorter| is a function. If set to `true` it overrides |nvim-tree.sort.folders_first|. Default: `false` @see nvim-tree.sort.sorter @see nvim-tree.sort.folders_first + +-- +-- Filters +-- + +---@class nvim_tree.Config.Filters +---@field enable? boolean Enable / disable all filters including live filter. Toggle via |nvim-tree-api.tree.toggle_enable_filters()| Default: `true` +---@field git_ignored? boolean Ignore files based on `.gitignore`. Requires |git.enable| `= true` Toggle via |nvim-tree-api.tree.toggle_gitignore_filter()|, default `I` Default: `true` +---@field dotfiles? boolean Do not show dotfiles: files starting with a `.` Toggle via |nvim-tree-api.tree.toggle_hidden_filter()|, default `H` Default: `false` +---@field git_clean? boolean Do not show files with no git status. This will show ignored files when |nvim-tree.filters.git_ignored| is set, as they are effectively dirty. Toggle via |nvim-tree-api.tree.toggle_git_clean_filter()|, default `C` Default: `false` +---@field no_buffer? boolean Do not show files that have no |buflisted()| buffer. Toggle via |nvim-tree-api.tree.toggle_no_buffer_filter()|, default `B` For performance reasons this may not immediately update on buffer delete/wipe. A reload or filesystem event will result in an update. Default: `false` +---@field no_bookmark? boolean Do not show files that are not bookmarked. Toggle via |nvim-tree-api.tree.toggle_no_bookmark_filter()|, default `M` Enabling this is not useful as there is no means yet to persist bookmarks. Default: `false` +---@field custom? string[]|fun(absolute_path: string): boolean Custom list of vim regex for file/directory names that will not be shown. Backslashes must be escaped e.g. "^\\.git". See |string-match|. Toggle via |nvim-tree-api.tree.toggle_custom_filter()|, default `U` Default: `{}` +---@field exclude? string[] List of directories or files to exclude from filtering: always show them. Overrides `filters.git_ignored`, `filters.dotfiles` and `filters.custom`. Default: `{}` + +-- +-- Update Focused File +-- + +---@class nvim_tree.Config.UpdateFocusedFile +---@field enable? boolean Enable this feature. Default: `false` +---@field update_root? nvim_tree.Config.UpdateFocusedFile.UpdateRoot Update the root directory of the tree if the file is not under current root directory. It prefers vim's cwd and `root_dirs`. Otherwise it falls back to the folder containing the file. Only relevant when `update_focused_file.enable` is `true` @see nvim-tree.update_focused_file.enable +---@field exclude? fun(args: vim.api.keyset.create_autocmd.callback_args): boolean A function that returns true if the file should not be focused when opening. Takes the `BufEnter` event as an argument. see |autocmd-events| Default: `false` + +---@class nvim_tree.Config.UpdateFocusedFile.UpdateRoot +---@field enable? boolean Default: `false` +---@field ignore_list? string[] List of buffer names and filetypes that will not update the root dir of the tree if the file isn't found under the current root directory. Only relevant when `update_focused_file.update_root.enable` and `update_focused_file.enable` are `true`. Default: `{}` @see nvim-tree.update_focused_file.update_root.enable @see nvim-tree.update_focused_file.enable + +-- +-- Git +-- + +---@class nvim_tree.Config.Git +---@field enable? boolean Enable / disable the feature. Default: `true` +---@field show_on_dirs? boolean Show status icons of children when directory itself has no status icon. Default: `true` +---@field show_on_open_dirs? boolean Show status icons of children on directories that are open. Only relevant when `git.show_on_dirs` is `true`. Default: `true` @see nvim-tree.git.show_on_dirs +---@field disable_for_dirs? string[]|fun(path: string): boolean Disable git integration when git top-level matches these paths. Strings may be relative, evaluated via |fnamemodify| `:p` Function is passed an absolute path and returns true for disable. Default: `{}` +---@field timeout? integer Kills the git process after some time if it takes too long. Git integration will be disabled after 10 git jobs exceed this timeout. Default: `400` (ms) +---@field cygwin_support? boolean Use `cygpath` if available to resolve paths for git. Default: `false` + +-- +-- Diagnostics +-- + +---@class nvim_tree.Config.Diagnostics +---@field enable? boolean Enable/disable the feature. Default: `false` +---@field debounce_delay? integer Idle milliseconds between diagnostic event and update. Default: `500` (ms) +---@field show_on_dirs? boolean Show diagnostic icons on parent directories. Default: `false` +---@field show_on_open_dirs? boolean Show diagnostics icons on directories that are open. Only relevant when `diagnostics.show_on_dirs` is `true`. Default: `true` @see nvim-tree.diagnostics.show_on_dirs +---@field severity? nvim_tree.Config.Diagnostics.Severity Severity for which the diagnostics will be displayed. See |diagnostic-severity| @see nvim-tree.diagnostics.icons +---@field icons? nvim_tree.Config.Diagnostics.Icons Icons for diagnostic severity. +---@field diagnostic_opts? boolean vim.diagnostic.Opts overrides nvim-tree.diagnostics.severity and nvim-tree.diagnostics.icons Default: `false` + +---@class nvim_tree.Config.Diagnostics.Severity +---@field min? vim.diagnostic.Severity Minimum severity. Default: `vim.diagnostic.severity.HINT` +---@field max? vim.diagnostic.Severity Maximum severity. Default: `vim.diagnostic.severity.ERROR` + +---@class nvim_tree.Config.Diagnostics.Icons +---@field hint? string Default: `""` +---@field info? string Default: `""` +---@field warning? string Default: `""` +---@field error? string Default: `""` + +-- +-- Notify +-- + +---@class nvim_tree.Config.Notify +---@field threshold? vim.log.levels Specify minimum notification level, uses the values from |vim.log.levels| Default: `vim.log.levels.INFO` `ERROR`: hard errors e.g. failure to read from the file system. `WARNING`: non-fatal errors e.g. unable to system open a file. `INFO:` information only e.g. file copy path confirmation. `DEBUG:` information for troubleshooting, e.g. failures in some window closing operations. +---@field absolute_path? boolean Whether to use absolute paths or item names in fs action notifications. Default: `true` + +-- +-- Filesystem Watchers +-- + +---@class nvim_tree.Config.FilesystemWatchers +---@field enable? boolean Enable / disable the feature. Default: `true` +---@field debounce_delay? integer Idle milliseconds between filesystem change and action. Default: `50` (ms) +---@field ignore_dirs? string[]|fun(path: string): boolean List of vim regex for absolute directory paths that will not be watched or function returning whether a path should be ignored. Strings must be backslash escaped e.g. `"my-proj/\\.build$"`. See |string-match|. Function is passed an absolute path. Useful when path is not in `.gitignore` or git integration is disabled. Default: `{ "/.ccls-cache", "/build", "/node_modules", "/target", }` + +-- +-- Log +-- + +---@class nvim_tree.Config.Log +---@field enable? boolean Enable logging to a file `nvim-tree.log` in |stdpath| `"log"`, usually `${XDG_STATE_HOME}/nvim` Default: `false` +---@field truncate? boolean Remove existing log file at startup. Default: `false` +---@field types? nvim_tree.Config.Log.Types Specify which information to log. + +---@class nvim_tree.Config.Log.Types +---@field all? boolean Everything. Default: `false` +---@field profile? boolean Timing of some operations. Default: `false` +---@field config? boolean Options and mappings, at startup. Default: `false` +---@field copy_paste? boolean File copy and paste actions. Default: `false` +---@field dev? boolean Used for local development only. Not useful for users. Default: `false` +---@field diagnostics? boolean LSP and COC processing, verbose. Default: `false` +---@field git? boolean Git processing, verbose. Default: `false` +---@field watcher? boolean nvim-tree.filesystem_watchers processing, verbose. Default: `false` + +-- +-- UI +-- + +---@class nvim_tree.Config.UI +---@field confirm? nvim_tree.Config.UI.Confirm Confirmation prompts. + +---@class nvim_tree.Config.UI.Confirm +---@field remove? boolean Prompt before removing. Default: `true` +---@field trash? boolean Prompt before trashing. Default: `true` +---@field default_yes? boolean If `true` the prompt will be `\"Y/n\"`, otherwise `\"y/N\"`. Default: `false` + +-- +-- Actions +-- + +---@class nvim_tree.Config.Actions +---@field use_system_clipboard? boolean A boolean value that toggle the use of system clipboard when copy/paste function are invoked. When enabled, copied text will be stored in registers '+' (system), otherwise, it will be stored in '1' and '"'. Default: `true` +---@field change_dir? nvim_tree.Config.Actions.ChangeDir vim |current-directory| behaviour. +---@field expand_all? nvim_tree.Config.Actions.ExpandAll Configuration for |nvim-tree-api.tree.expand_all()| and |nvim-tree-api.node.expand()| +---@field file_popup? nvim_tree.Config.Actions.FilePopup Configuration for file_popup behaviour. +---@field open_file? nvim_tree.Config.Actions.OpenFile Configuration options for opening a file from nvim-tree. +---@field remove_file? nvim_tree.Config.Actions.RemoveFile Configuration options for removing a file from nvim-tree. + +---@class nvim_tree.Config.Actions.ChangeDir +---@field enable? boolean Change the working directory when changing directories in the tree. Default: `true` +---@field global? boolean Use `:cd` instead of `:lcd` when changing directories. Default: `false` +---@field restrict_above_cwd? boolean Restrict changing to a directory above the global cwd. Default: `false` + +---@class nvim_tree.Config.Actions.ExpandAll +---@field max_folder_discovery? integer Limit the number of folders being explored when expanding every folders. Avoids hanging neovim when running this action on very large folders. Default: `300` +---@field exclude? string[] A list of directories that should not be expanded automatically. E.g `{ ".git", "target", "build" }` etc. Default: `{}` + +---@class nvim_tree.Config.Actions.FilePopup +---@field open_win_config? table Floating window config for file_popup. See |nvim_open_win| for more details. You shouldn't define `"width"` and `"height"` values here. They will be overridden to fit the file_popup content. Default: `{ col = 1, row = 1, relative = "cursor", border = "shadow", style = "minimal", }` + +---@class nvim_tree.Config.Actions.OpenFile +---@field quit_on_open? boolean Closes the explorer when opening a file. Default: `false` +---@field eject? boolean Prevent a new file opened from within nvim-tree replacing the current nvim-tree window. Default: `true` +---@field resize_window? boolean Resizes the tree when opening a file. Default: `true` +---@field window_picker? nvim_tree.Config.Actions.OpenFile.WindowPicker Window picker configuration. + +---@class nvim_tree.Config.Actions.OpenFile.WindowPicker +---@field enable? boolean Enable the window picker. If this feature is not enabled, files will open in the current window. Default: `true` +---@field picker? string|fun(): integer Change the way in which to pick a window. Default: `"default"` +---@field chars? string A string of chars used for window picker labels. Default: `"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"` +---@field exclude? nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude Floating window config for window selector. + +---@class nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude +---@field filetype? string[] A list of filetypes to exclude from window picker. Default: `{ "notify", "lazy", "qf", "diff", "fugitive", "fugitiveblame", }` +---@field buftype? string[] A list of buftypes to exclude from window picker. Default: `{ "nofile", "terminal", "help", }` + +---@class nvim_tree.Config.Actions.RemoveFile +---@field close_window? boolean Close any window that displays a file when removing that file from the tree. Default: `true` + +-- +-- View +-- + +---@class nvim_tree.Config.View +---@field adaptive_size? boolean Resize the window on each draw based on the longest line. Default: `false` +---@field centralize_selection? boolean When entering nvim-tree, reposition the view so that the current node is initially centralized, see |zz|. Default: `false` +---@field side? nvim_tree.PlacementOption Side of the tree. Default: `"left"` +---@field preserve_window_proportions? boolean Preserves window proportions when opening a file. If `false`, the height and width of windows other than nvim-tree will be equalized. Default: `false` +---@field number? boolean Print the line number in front of each line. Default: `false` +---@field relativenumber? boolean Show the line number relative to the line with the cursor in front of each line. Default: `false` +---@field signcolumn? nvim_tree.HiddenDisplayOption Show |signcolumn|. Default: `"yes"` +---@field width? string|integer|nvim_tree.Config.View.Width|fun(): integer|string Width of the window: can be a `%` string, a number representing columns, a function or a table. A table indicates that the view should be dynamically sized based on the longest line. Default: `30` +---@field float? nvim_tree.Config.View.Float Configuration options for floating window. +---@field cursorline? boolean Enable |cursorline| in nvim-tree window. Default: `true` +---@field debounce_delay? integer Idle milliseconds before some reload / refresh operations. Increase if you experience performance issues around screen refresh. Default: `15` (ms) + +---@class nvim_tree.Config.View.Width +---@field min? string|integer|fun(): integer|string Minimum dynamic width. Default: `30` +---@field max? string|integer|fun(): integer|string Maximum dynamic width, -1 for unbounded. Default: `-1` +---@field lines_excluded? string[] Exclude these lines when computing width. Supported values: `"root"`. Default: `{ "root" }` +---@field padding? integer|fun(): integer|string Extra padding to the right. Default: `1` + +---@class nvim_tree.Config.View.Float +---@field enable? boolean If true, tree window will be floating. Default: `false` +---@field quit_on_focus_loss? boolean Close the floating tree window when it loses focus. Default: `true` +---@field open_win_config? table|fun(): table Floating window config. See |nvim_open_win()| for more details. Default: `{ relative = "editor", border = "rounded", width = 30, height = 30, row = 1, col = 1, }` diff --git a/lua/nvim-tree/actions/node/buffer.lua b/lua/nvim-tree/actions/node/buffer.lua index 425fcfa4ba6..00cd3efdc63 100644 --- a/lua/nvim-tree/actions/node/buffer.lua +++ b/lua/nvim-tree/actions/node/buffer.lua @@ -4,14 +4,14 @@ local notify = require("nvim-tree.notify") local M = {} ---@param node Node ----@param opts ApiNodeDeleteWipeBufferOpts|nil +---@param opts nvim_tree.api.NodeBufferOpts|nil ---@return nil function M.delete(node, opts) M.delete_buffer("delete", node.absolute_path, opts) end ---@param node Node ----@param opts ApiNodeDeleteWipeBufferOpts|nil +---@param opts nvim_tree.api.NodeBufferOpts|nil ---@return nil function M.wipe(node, opts) M.delete_buffer("wipe", node.absolute_path, opts) @@ -21,7 +21,7 @@ end ---@param mode ApiNodeDeleteWipeBufferMode ---@param filename string ----@param opts ApiNodeDeleteWipeBufferOpts|nil +---@param opts nvim_tree.api.NodeBufferOpts|nil ---@return nil function M.delete_buffer(mode, filename, opts) if type(mode) ~= "string" then diff --git a/lua/nvim-tree/actions/tree/find-file.lua b/lua/nvim-tree/actions/tree/find-file.lua index 8a05bf6db45..b0d2834232f 100644 --- a/lua/nvim-tree/actions/tree/find-file.lua +++ b/lua/nvim-tree/actions/tree/find-file.lua @@ -6,7 +6,7 @@ local finders_find_file = require("nvim-tree.actions.finders.find-file") local M = {} --- Find file or buffer ----@param opts ApiTreeFindFileOpts|nil|boolean legacy -> opts.buf +---@param opts nvim_tree.api.TreeFindFileOpts|nil|boolean legacy -> opts.buf function M.fn(opts) -- legacy arguments if type(opts) == "string" then diff --git a/lua/nvim-tree/actions/tree/modifiers/collapse.lua b/lua/nvim-tree/actions/tree/modifiers/collapse.lua index 51a15f3d464..5c46cbdcae3 100644 --- a/lua/nvim-tree/actions/tree/modifiers/collapse.lua +++ b/lua/nvim-tree/actions/tree/modifiers/collapse.lua @@ -26,7 +26,7 @@ end ---Collapse a node, root if nil ---@param node Node? ----@param opts ApiCollapseOpts +---@param opts nvim_tree.api.CollapseOpts local function collapse(node, opts) local explorer = core.get_explorer() if not explorer then @@ -60,7 +60,7 @@ local function collapse(node, opts) end ----@param opts ApiCollapseOpts|boolean|nil legacy -> opts.keep_buffers +---@param opts nvim_tree.api.CollapseOpts|boolean|nil legacy -> opts.keep_buffers function M.all(opts) -- legacy arguments if type(opts) == "boolean" then @@ -73,7 +73,7 @@ function M.all(opts) end ---@param node Node ----@param opts ApiCollapseOpts? +---@param opts nvim_tree.api.CollapseOpts? function M.node(node, opts) collapse(node, opts or {}) end diff --git a/lua/nvim-tree/actions/tree/modifiers/expand.lua b/lua/nvim-tree/actions/tree/modifiers/expand.lua index 44e3fa67baa..c4a1274522b 100644 --- a/lua/nvim-tree/actions/tree/modifiers/expand.lua +++ b/lua/nvim-tree/actions/tree/modifiers/expand.lua @@ -125,7 +125,7 @@ local function gen_iterator(should_descend) end ---@param node Node? ----@param expand_opts ApiTreeExpandOpts? +---@param expand_opts nvim_tree.api.TreeExpandOpts? local function expand_node(node, expand_opts) if not node then return @@ -141,14 +141,14 @@ end ---Expand the directory node or the root ---@param node Node ----@param expand_opts ApiTreeExpandOpts? +---@param expand_opts nvim_tree.api.TreeExpandOpts? function M.all(node, expand_opts) expand_node(node and node:as(DirectoryNode) or core.get_explorer(), expand_opts) end ---Expand the directory node or parent node ---@param node Node ----@param expand_opts ApiTreeExpandOpts? +---@param expand_opts nvim_tree.api.TreeExpandOpts? function M.node(node, expand_opts) if not node then return diff --git a/lua/nvim-tree/actions/tree/open.lua b/lua/nvim-tree/actions/tree/open.lua index ff2da837b87..0c819ef83cb 100644 --- a/lua/nvim-tree/actions/tree/open.lua +++ b/lua/nvim-tree/actions/tree/open.lua @@ -5,7 +5,7 @@ local finders_find_file = require("nvim-tree.actions.finders.find-file") local M = {} ---Open the tree, focusing if already open. ----@param opts ApiTreeOpenOpts|nil|string legacy -> opts.path +---@param opts nvim_tree.api.TreeOpenOpts|nil|string legacy -> opts.path function M.fn(opts) -- legacy arguments if type(opts) == "string" then diff --git a/lua/nvim-tree/actions/tree/resize.lua b/lua/nvim-tree/actions/tree/resize.lua index e8d4e950729..43fba021134 100644 --- a/lua/nvim-tree/actions/tree/resize.lua +++ b/lua/nvim-tree/actions/tree/resize.lua @@ -3,7 +3,7 @@ local view = require("nvim-tree.view") local M = {} ---Resize the tree, persisting the new size. ----@param opts ApiTreeResizeOpts|nil +---@param opts nvim_tree.api.TreeResizeOpts|nil function M.fn(opts) if opts == nil then -- reset to config values diff --git a/lua/nvim-tree/actions/tree/toggle.lua b/lua/nvim-tree/actions/tree/toggle.lua index 10aa978467e..c2c4153a3c7 100644 --- a/lua/nvim-tree/actions/tree/toggle.lua +++ b/lua/nvim-tree/actions/tree/toggle.lua @@ -5,7 +5,7 @@ local finders_find_file = require("nvim-tree.actions.finders.find-file") local M = {} ---Toggle the tree. ----@param opts ApiTreeToggleOpts|nil|boolean legacy -> opts.find_file +---@param opts nvim_tree.api.TreeToggleOpts|nil|boolean legacy -> opts.find_file ---@param no_focus string|nil legacy -> opts.focus ---@param cwd boolean|nil legacy -> opts.path ---@param bang boolean|nil legacy -> opts.update_root diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua index e5a109142f1..75c3483797d 100644 --- a/lua/nvim-tree/api.lua +++ b/lua/nvim-tree/api.lua @@ -14,6 +14,18 @@ local FileLinkNode = require("nvim-tree.node.file-link") local RootNode = require("nvim-tree.node.root") local UserDecorator = require("nvim-tree.renderer.decorator.user") +-- Backwards compatibility aliases for renamed classes +---@alias ApiTreeOpenOpts nvim_tree.api.TreeOpenOpts +---@alias ApiTreeToggleOpts nvim_tree.api.TreeToggleOpts +---@alias ApiTreeResizeOpts nvim_tree.api.TreeResizeOpts +---@alias ApiTreeFindFileOpts nvim_tree.api.TreeFindFileOpts +---@alias ApiCollapseOpts nvim_tree.api.CollapseOpts +---@alias ApiTreeExpandOpts nvim_tree.api.TreeExpandOpts +---@alias ApiTreeIsVisibleOpts nvim_tree.api.TreeIsVisibleOpts +---@alias ApiTreeWinIdOpts nvim_tree.api.TreeWinIdOpts +---@alias NodeEditOpts nvim_tree.api.NodeEditOpts +---@alias ApiNodeDeleteWipeBufferOpts nvim_tree.api.NodeBufferOpts + local Api = { tree = {}, node = { @@ -123,35 +135,15 @@ local function wrap_explorer_member(explorer_member, member_method) end) end ----@class ApiTreeOpenOpts ----@field path string|nil path ----@field current_window boolean|nil default false ----@field winid number|nil ----@field find_file boolean|nil default false ----@field update_root boolean|nil default false - Api.tree.open = wrap(actions.tree.open.fn) Api.tree.focus = Api.tree.open ----@class ApiTreeToggleOpts ----@field path string|nil ----@field current_window boolean|nil default false ----@field winid number|nil ----@field find_file boolean|nil default false ----@field update_root boolean|nil default false ----@field focus boolean|nil default true - Api.tree.toggle = wrap(actions.tree.toggle.fn) Api.tree.close = wrap(view.close) Api.tree.close_in_this_tab = wrap(view.close_this_tab_only) Api.tree.close_in_all_tabs = wrap(view.close_all_tabs) Api.tree.reload = wrap_explorer("reload_explorer") ----@class ApiTreeResizeOpts ----@field width string|function|number|table|nil ----@field absolute number|nil ----@field relative number|nil - Api.tree.resize = wrap(actions.tree.resize.fn) Api.tree.change_root = wrap(function(...) @@ -179,25 +171,11 @@ Api.tree.change_root_to_parent = wrap_node(wrap_explorer("dir_up")) Api.tree.get_node_under_cursor = wrap_explorer("get_node_at_cursor") Api.tree.get_nodes = wrap_explorer("get_nodes") ----@class ApiTreeFindFileOpts ----@field buf string|number|nil ----@field open boolean|nil default false ----@field current_window boolean|nil default false ----@field winid number|nil ----@field update_root boolean|nil default false ----@field focus boolean|nil default false - Api.tree.find_file = wrap(actions.tree.find_file.fn) Api.tree.search_node = wrap(actions.finders.search_node.fn) ----@class ApiCollapseOpts ----@field keep_buffers boolean|nil default false - Api.tree.collapse_all = wrap(actions.tree.modifiers.collapse.all) ----@class ApiTreeExpandOpts ----@field expand_until (fun(expansion_count: integer, node: Node): boolean)|nil - Api.tree.expand_all = wrap_node(actions.tree.modifiers.expand.all) Api.tree.toggle_enable_filters = wrap_explorer_member("filters", "toggle") Api.tree.toggle_gitignore_filter = wrap_explorer_member_args("filters", "toggle", "git_ignored") @@ -209,15 +187,8 @@ Api.tree.toggle_no_bookmark_filter = wrap_explorer_member_args("filters", "toggl Api.tree.toggle_help = wrap(help.toggle) Api.tree.is_tree_buf = wrap(utils.is_nvim_tree_buf) ----@class ApiTreeIsVisibleOpts ----@field tabpage number|nil ----@field any_tabpage boolean|nil default false - Api.tree.is_visible = wrap(view.is_visible) ----@class ApiTreeWinIdOpts ----@field tabpage number|nil default nil - Api.tree.winid = wrap(view.winid) Api.fs.create = wrap_node_or_nil(actions.fs.create_file.fn) @@ -238,13 +209,9 @@ Api.fs.copy.filename = wrap_node(wrap_explorer_member("clipboard", "copy_filenam Api.fs.copy.basename = wrap_node(wrap_explorer_member("clipboard", "copy_basename")) Api.fs.copy.relative_path = wrap_node(wrap_explorer_member("clipboard", "copy_path")) --- ----@class NodeEditOpts ----@field quit_on_open boolean|nil default false ----@field focus boolean|nil default true - ---@param mode string ---@param node Node ----@param edit_opts NodeEditOpts? +---@param edit_opts nvim_tree.api.NodeEditOpts? local function edit(mode, node, edit_opts) local file_link = node:as(FileLinkNode) local path = file_link and file_link.link_to or node.absolute_path @@ -272,10 +239,10 @@ end ---@param mode string ---@param toggle_group boolean? ----@return fun(node: Node, edit_opts: NodeEditOpts?) +---@return fun(node: Node, edit_opts: nvim_tree.api.NodeEditOpts?) local function open_or_expand_or_dir_up(mode, toggle_group) ---@param node Node - ---@param edit_opts NodeEditOpts? + ---@param edit_opts nvim_tree.api.NodeEditOpts? return function(node, edit_opts) local root = node:as(RootNode) local dir = node:as(DirectoryNode) @@ -330,9 +297,6 @@ Api.node.navigate.opened.prev = wrap_node(actions.moves.item.fn({ where = "prev" Api.node.expand = wrap_node(actions.tree.modifiers.expand.node) Api.node.collapse = wrap_node(actions.tree.modifiers.collapse.node) ----@class ApiNodeDeleteWipeBufferOpts ----@field force boolean|nil default false - Api.node.buffer.delete = wrap_node(function(node, opts) actions.node.buffer.delete(node, opts) end) diff --git a/lua/nvim-tree/view.lua b/lua/nvim-tree/view.lua index 275e68635d0..077fe6580c6 100644 --- a/lua/nvim-tree/view.lua +++ b/lua/nvim-tree/view.lua @@ -438,7 +438,7 @@ function M.abandon_all_windows() end end ----@param opts table|nil +---@param opts? nvim_tree.api.TreeIsVisibleOpts ---@return boolean function M.is_visible(opts) if opts and opts.tabpage then @@ -487,7 +487,7 @@ function M.focus(winnr, open_if_closed) end --- Retrieve the winid of the open tree. ----@param opts ApiTreeWinIdOpts|nil +---@param opts nvim_tree.api.TreeWinIdOpts|nil ---@return number|nil winid unlike get_winnr(), this returns nil if the nvim-tree window is not visible function M.winid(opts) local tabpage = opts and opts.tabpage From 02c3ecf691e90abeee6419663daaec51e3af100b Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Mon, 5 Jan 2026 13:04:58 +1100 Subject: [PATCH 005/170] doc(#2934): add nvim_tree.Config to help --- doc/nvim-tree-lua.txt | 821 +++++++++++++++++++++++++++++++++- scripts/gen_vimdoc_config.lua | 16 +- 2 files changed, 830 insertions(+), 7 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 058864beefe..8b379e37b45 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -46,7 +46,6 @@ CONTENTS *nvim-tree* 6.8 API Config |nvim-tree-api.config| 6.9 API Commands |nvim-tree-api.commands| 6.10 API Diagnostics |nvim-tree-api.diagnostics| - 6.11 API Decorator |nvim-tree-api.decorator| 7. Mappings |nvim-tree-mappings| 7.1 Mappings: Default |nvim-tree-mappings-default| 8. Highlight |nvim-tree-highlight| @@ -3460,7 +3459,825 @@ highlight group is not, hard linking as follows: > |nvim-tree-api.tree.winid()| ============================================================================== - 6.11 API DECORATOR *nvim-tree-api.decorator* +Lua module: nvim_tree.Config *nvim-tree-config* + +*nvim_tree.Config* + + Fields: ~ + • {on_attach}? (`string|fun(bufnr: integer)`) + • {auto_reload_on_write}? (`boolean`) Reloads the + explorer every time a buffer is + written to. Default: `true` + • {disable_netrw}? (`boolean`) Completely disable + netrw Default: `false` + • {hijack_cursor}? (`boolean`) Keeps the cursor on + the first letter of the + filename when moving in the + tree. Default: `false` + • {hijack_netrw}? (`boolean`) Hijack netrw + windows (overridden if + |disable_netrw| is `true`) + Default: `true` + • {hijack_unnamed_buffer_when_opening}? (`boolean`) Opens in place of + the unnamed buffer if it's + empty. Default: `false` + • {prefer_startup_root}? (`boolean`) Prefer startup root + directory when updating root + directory of the tree. Only + relevant when + `update_focused_file.update_root` + is `true` Default: `false` @see + nvim-tree.update_focused_file.update_root + • {reload_on_bufenter}? (`boolean`) Automatically + reloads the tree on `BufEnter` + nvim-tree. Default: `false` + • {respect_buf_cwd}? (`boolean`) Will change cwd of + nvim-tree to that of new + buffer's when opening + nvim-tree. Default: `false` + • {select_prompts}? (`boolean`) Use |vim.ui.select| + style prompts. Necessary when + using a UI prompt decorator + such as dressing.nvim or + telescope-ui-select.nvim + Default: `false` + • {sync_root_with_cwd}? (`boolean`) Changes the tree + root directory on `DirChanged` + and refreshes the tree. + Default: `false` + • {root_dirs}? (`string[]`) Preferred root + directories. Only relevant when + `update_focused_file.update_root` + is `true` Default: `{}` @see + nvim-tree.update_focused_file.update_root + • {experimental}? (`table`) Experimental features + that may become default or + optional functionality. In the + event of a problem please + disable the experiment and + raise an issue. + • {hijack_directories}? (`nvim_tree.Config.HijackDirectories`) + • {renderer}? (`nvim_tree.Config.Renderer`) + • {modified}? (`nvim_tree.Config.Modified`) + • {tab}? (`nvim_tree.Config.Tab`) + • {trash}? (`nvim_tree.Config.Trash`) + • {live_filter}? (`nvim_tree.Config.LiveFilter`) + • {system_open}? (`nvim_tree.Config.SystemOpen`) + • {help}? (`nvim_tree.Config.Help`) + • {sort}? (`nvim_tree.Config.Sort`) + • {filters}? (`nvim_tree.Config.Filters`) + • {update_focused_file}? (`nvim_tree.Config.UpdateFocusedFile`) + • {git}? (`nvim_tree.Config.Git`) + • {diagnostics}? (`nvim_tree.Config.Diagnostics`) + • {notify}? (`nvim_tree.Config.Notify`) + • {filesystem_watchers}? (`nvim_tree.Config.FilesystemWatchers`) + • {log}? (`nvim_tree.Config.Log`) + • {ui}? (`nvim_tree.Config.UI`) + • {actions}? (`nvim_tree.Config.Actions`) + • {view}? (`nvim_tree.Config.View`) + +*nvim_tree.Config.Actions* + + Fields: ~ + • {use_system_clipboard}? (`boolean`) A boolean value that toggle the + use of system clipboard when copy/paste + function are invoked. When enabled, copied + text will be stored in registers '+' + (system), otherwise, it will be stored in '1' + and '"'. Default: `true` + • {change_dir}? (`nvim_tree.Config.Actions.ChangeDir`) vim + |current-directory| behaviour. + • {expand_all}? (`nvim_tree.Config.Actions.ExpandAll`) + Configuration for + |nvim-tree-api.tree.expand_all()| and + |nvim-tree-api.node.expand()| + • {file_popup}? (`nvim_tree.Config.Actions.FilePopup`) + Configuration for file_popup behaviour. + • {open_file}? (`nvim_tree.Config.Actions.OpenFile`) + Configuration options for opening a file from + nvim-tree. + • {remove_file}? (`nvim_tree.Config.Actions.RemoveFile`) + Configuration options for removing a file + from nvim-tree. + +*nvim_tree.Config.Actions.ChangeDir* + + Fields: ~ + • {enable}? (`boolean`) Change the working directory when + changing directories in the tree. Default: + `true` + • {global}? (`boolean`) Use `:cd` instead of `:lcd` when + changing directories. Default: `false` + • {restrict_above_cwd}? (`boolean`) Restrict changing to a directory + above the global cwd. Default: `false` + +*nvim_tree.Config.Actions.ExpandAll* + + Fields: ~ + • {max_folder_discovery}? (`integer`) Limit the number of folders being + explored when expanding every folders. Avoids + hanging neovim when running this action on + very large folders. Default: `300` + • {exclude}? (`string[]`) A list of directories that + should not be expanded automatically. E.g + `{ ".git", "target", "build" }` etc. Default: + `{}` + +*nvim_tree.Config.Actions.FilePopup* + + Fields: ~ + • {open_win_config}? (`table`) Floating window config for file_popup. + See |nvim_open_win| for more details. You + shouldn't define `"width"` and `"height"` values + here. They will be overridden to fit the + file_popup content. Default: + `{ col = 1, row = 1, relative = "cursor", border = "shadow", style = "minimal", }` + +*nvim_tree.Config.Actions.OpenFile* + + Fields: ~ + • {quit_on_open}? (`boolean`) Closes the explorer when opening a file. + Default: `false` + • {eject}? (`boolean`) Prevent a new file opened from within + nvim-tree replacing the current nvim-tree window. + Default: `true` + • {resize_window}? (`boolean`) Resizes the tree when opening a file. + Default: `true` + • {window_picker}? (`nvim_tree.Config.Actions.OpenFile.WindowPicker`) + Window picker configuration. + +*nvim_tree.Config.Actions.OpenFile.WindowPicker* + + Fields: ~ + • {enable}? (`boolean`) Enable the window picker. If this feature is + not enabled, files will open in the current window. + Default: `true` + • {picker}? (`string|fun(): integer`) Change the way in which to pick + a window. Default: `"default"` + • {chars}? (`string`) A string of chars used for window picker + labels. Default: `"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"` + • {exclude}? (`nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude`) + Floating window config for window selector. + +*nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude* + + Fields: ~ + • {filetype}? (`string[]`) A list of filetypes to exclude from window + picker. Default: + `{ "notify", "lazy", "qf", "diff", "fugitive", "fugitiveblame", }` + • {buftype}? (`string[]`) A list of buftypes to exclude from window + picker. Default: `{ "nofile", "terminal", "help", }` + +*nvim_tree.Config.Actions.RemoveFile* + + Fields: ~ + • {close_window}? (`boolean`) Close any window that displays a file + when removing that file from the tree. Default: + `true` + +*nvim_tree.Config.Diagnostics* + + Fields: ~ + • {enable}? (`boolean`) Enable/disable the feature. Default: + `false` + • {debounce_delay}? (`integer`) Idle milliseconds between diagnostic + event and update. Default: `500` (ms) + • {show_on_dirs}? (`boolean`) Show diagnostic icons on parent + directories. Default: `false` + • {show_on_open_dirs}? (`boolean`) Show diagnostics icons on + directories that are open. Only relevant when + `diagnostics.show_on_dirs` is `true`. Default: + `true` @see nvim-tree.diagnostics.show_on_dirs + • {severity}? (`nvim_tree.Config.Diagnostics.Severity`) + Severity for which the diagnostics will be + displayed. See |diagnostic-severity| @see + nvim-tree.diagnostics.icons + • {icons}? (`nvim_tree.Config.Diagnostics.Icons`) Icons for + diagnostic severity. + • {diagnostic_opts}? (`boolean`) vim.diagnostic.Opts overrides + nvim-tree.diagnostics.severity and + nvim-tree.diagnostics.icons Default: `false` + +*nvim_tree.Config.Diagnostics.Icons* + + Fields: ~ + • {hint}? (`string`) Default: `""` + • {info}? (`string`) Default: `""` + • {warning}? (`string`) Default: `""` + • {error}? (`string`) Default: `""` + +*nvim_tree.Config.Diagnostics.Severity* + + Fields: ~ + • {min}? (`vim.diagnostic.Severity`) Minimum severity. Default: + `vim.diagnostic.severity.HINT` + • {max}? (`vim.diagnostic.Severity`) Maximum severity. Default: + `vim.diagnostic.severity.ERROR` + +*nvim_tree.Config.FilesystemWatchers* + + Fields: ~ + • {enable}? (`boolean`) Enable / disable the feature. Default: + `true` + • {debounce_delay}? (`integer`) Idle milliseconds between filesystem + change and action. Default: `50` (ms) + • {ignore_dirs}? (`string[]|fun(path: string): boolean`) List of vim + regex for absolute directory paths that will not be + watched or function returning whether a path should + be ignored. Strings must be backslash escaped e.g. + `"my-proj/\\.build$"`. See |string-match|. Function + is passed an absolute path. Useful when path is not + in `.gitignore` or git integration is disabled. + Default: + `{ "/.ccls-cache", "/build", "/node_modules", "/target", }` + +*nvim_tree.Config.Filters* + + Fields: ~ + • {enable}? (`boolean`) Enable / disable all filters including + live filter. Toggle via + |nvim-tree-api.tree.toggle_enable_filters()| Default: + `true` + • {git_ignored}? (`boolean`) Ignore files based on `.gitignore`. + Requires |git.enable| `= true` Toggle via + |nvim-tree-api.tree.toggle_gitignore_filter()|, + default `I` Default: `true` + • {dotfiles}? (`boolean`) Do not show dotfiles: files starting with + a `.` Toggle via + |nvim-tree-api.tree.toggle_hidden_filter()|, default + `H` Default: `false` + • {git_clean}? (`boolean`) Do not show files with no git status. This + will show ignored files when + |nvim-tree.filters.git_ignored| is set, as they are + effectively dirty. Toggle via + |nvim-tree-api.tree.toggle_git_clean_filter()|, + default `C` Default: `false` + • {no_buffer}? (`boolean`) Do not show files that have no + |buflisted()| buffer. Toggle via + |nvim-tree-api.tree.toggle_no_buffer_filter()|, + default `B` For performance reasons this may not + immediately update on buffer delete/wipe. A reload or + filesystem event will result in an update. Default: + `false` + • {no_bookmark}? (`boolean`) Do not show files that are not bookmarked. + Toggle via + |nvim-tree-api.tree.toggle_no_bookmark_filter()|, + default `M` Enabling this is not useful as there is no + means yet to persist bookmarks. Default: `false` + • {custom}? (`string[]|fun(absolute_path: string): boolean`) + Custom list of vim regex for file/directory names that + will not be shown. Backslashes must be escaped e.g. + "^\\.git". See |string-match|. Toggle via + |nvim-tree-api.tree.toggle_custom_filter()|, default + `U` Default: `{}` + • {exclude}? (`string[]`) List of directories or files to exclude + from filtering: always show them. Overrides + `filters.git_ignored`, `filters.dotfiles` and + `filters.custom`. Default: `{}` + +*nvim_tree.Config.Git* + + Fields: ~ + • {enable}? (`boolean`) Enable / disable the feature. + Default: `true` + • {show_on_dirs}? (`boolean`) Show status icons of children when + directory itself has no status icon. Default: + `true` + • {show_on_open_dirs}? (`boolean`) Show status icons of children on + directories that are open. Only relevant when + `git.show_on_dirs` is `true`. Default: `true` + @see nvim-tree.git.show_on_dirs + • {disable_for_dirs}? (`string[]|fun(path: string): boolean`) Disable + git integration when git top-level matches these + paths. Strings may be relative, evaluated via + |fnamemodify| `:p` Function is passed an + absolute path and returns true for disable. + Default: `{}` + • {timeout}? (`integer`) Kills the git process after some + time if it takes too long. Git integration will + be disabled after 10 git jobs exceed this + timeout. Default: `400` (ms) + • {cygwin_support}? (`boolean`) Use `cygpath` if available to + resolve paths for git. Default: `false` + +*nvim_tree.Config.Help* + + Fields: ~ + • {sort_by}? (`nvim_tree.HelpSortOption`) Defines how mappings are + sorted in the help window. Can be `"key"` (sort + alphabetically by keymap) or `"desc"` (sort alphabetically + by description). Default: `"key"` + +*nvim_tree.Config.HijackDirectories* + + Fields: ~ + • {enable}? (`boolean`) Enable the feature. Disable this option if + you use vim-dirvish or dirbuf.nvim. If `hijack_netrw` + and `disable_netrw` are `false`, this feature will be + disabled. Default: `true` + • {auto_open}? (`boolean`) Opens the tree if the tree was previously + closed. Default: `true` + +*nvim_tree.Config.LiveFilter* + + Fields: ~ + • {prefix}? (`string`) Prefix of the filter displayed in + the buffer. Default: `"[FILTER]: "` + • {always_show_folders}? (`boolean`) Whether to filter folders or not. + Default: `true` + +*nvim_tree.Config.Log* + + Fields: ~ + • {enable}? (`boolean`) Enable logging to a file `nvim-tree.log` in + |stdpath| `"log"`, usually `${XDG_STATE_HOME}/nvim` + Default: `false` + • {truncate}? (`boolean`) Remove existing log file at startup. Default: + `false` + • {types}? (`nvim_tree.Config.Log.Types`) Specify which information + to log. + +*nvim_tree.Config.Log.Types* + + Fields: ~ + • {all}? (`boolean`) Everything. Default: `false` + • {profile}? (`boolean`) Timing of some operations. Default: + `false` + • {config}? (`boolean`) Options and mappings, at startup. Default: + `false` + • {copy_paste}? (`boolean`) File copy and paste actions. Default: + `false` + • {dev}? (`boolean`) Used for local development only. Not + useful for users. Default: `false` + • {diagnostics}? (`boolean`) LSP and COC processing, verbose. Default: + `false` + • {git}? (`boolean`) Git processing, verbose. Default: `false` + • {watcher}? (`boolean`) nvim-tree.filesystem_watchers processing, + verbose. Default: `false` + +*nvim_tree.Config.Modified* + + Fields: ~ + • {enable}? (`boolean`) Enable / disable the feature. + Default: `false` + • {show_on_dirs}? (`boolean`) Show modified indication on + directory whose children are modified. Default: + `true` + • {show_on_open_dirs}? (`boolean`) Show modified indication on open + directories. Only relevant when + |modified.show_on_dirs| is `true`. Default: + `false` @see nvim-tree.modified.show_on_dirs + +*nvim_tree.Config.Notify* + + Fields: ~ + • {threshold}? (`vim.log.levels`) Specify minimum notification + level, uses the values from |vim.log.levels| + Default: `vim.log.levels.INFO` `ERROR`: hard errors + e.g. failure to read from the file system. + `WARNING`: non-fatal errors e.g. unable to system + open a file. `INFO:` information only e.g. file copy + path confirmation. `DEBUG:` information for + troubleshooting, e.g. failures in some window + closing operations. + • {absolute_path}? (`boolean`) Whether to use absolute paths or item + names in fs action notifications. Default: `true` + +*nvim_tree.Config.Renderer* + + Fields: ~ + • {add_trailing}? (`boolean`) Appends a trailing slash to + folder and symlink folder destination + names. Default: `false` + • {group_empty}? (`boolean|fun(relative_path: string): string`) + Compact folders that only contain a single + folder into one node. Boolean or function + that takes one argument (the relative path + of grouped folders) and returns a string to + be displayed. Default: `false` + • {full_name}? (`boolean`) Display node whose name length + is wider than the width of nvim-tree window + in floating window. Default: `false` + • {root_folder_label}? (`string|boolean|fun(root_cwd: string): string`) + In what format to show root folder. See + `:help filename-modifiers` for available + `string` options. Set to `false` to hide + the root folder. or `boolean` or + `function(root_cwd)`, Default: + `":~:s?$?/..?"` + • {indent_width}? (`integer`) Number of spaces for an each + tree nesting level. Minimum 1. Default: `2` + • {special_files}? (`string[]`) A list of filenames that gets + highlighted with `NvimTreeSpecialFile`. + Default: + `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }` + • {hidden_display}? (`fun(hidden_stats: table): string?|nvim_tree.HiddenDisplayOption`) + Show a summary of hidden files below the + tree using + `NvimTreeHiddenDisplay Default: `"none"` + • {symlink_destination}? (`boolean`) Whether to show the destination + of the symlink. Default: `true` + • {decorators}? (`(string|nvim_tree.api.decorator.UserDecorator)[]`) + Highlighting and icons for the nodes, in + increasing order of precedence. Uses + strings to specify builtin decorators + otherwise specify your + `nvim_tree.api.decorator.UserDecorator` + class. Default: > lua { "Git", "Open", + "Hidden", "Modified", "Bookmark", + "Diagnostics", "Copied", "Cut", } + • {highlight_git}? (`nvim_tree.HighlightOption`) Enable + highlight for git attributes using + `NvimTreeGit*HL` highlight groups. Requires + |nvim-tree.git.enable| Value can be + `"none"`, `"icon"`, `"name"` or `"all"`. + Default: `"none"` @see nvim-tree.git.enable + • {highlight_diagnostics}? (`nvim_tree.HighlightOption`) Enable + highlight for diagnostics using + `NvimTreeDiagnostic*HL` highlight groups. + Requires |nvim-tree.diagnostics.enable| + Value can be `"none"`, `"icon"`, `"name"` + or `"all"`. Default: `"none"` @see + nvim-tree.diagnostics.enable + • {highlight_opened_files}? (`nvim_tree.HighlightOption`) Highlight + icons and/or names for |bufloaded()| files + using the `NvimTreeOpenedHL` highlight + group. See + |nvim-tree-api.navigate.opened.next()| and + |nvim-tree-api.navigate.opened.prev()| + Value can be `"none"`, `"icon"`, `"name"` + or `"all"`. Default: `"none"` + • {highlight_modified}? (`nvim_tree.HighlightOption`) Highlight + icons and/or names for modified files using + the `NvimTreeModifiedFile` highlight group. + Requires |nvim-tree.modified.enable| Value + can be `"none"`, `"icon"`, `"name"` or + `"all"` Default `"none"` @see + nvim-tree.modified.enable + • {highlight_hidden}? (`nvim_tree.HighlightOption`) Highlight + icons and/or names for hidden files + (dotfiles) using the `NvimTreeHiddenFileHL` + highlight group. Value can be `"none"`, + `"icon"`, `"name"` or `"all"` Default + `"none"` + • {highlight_bookmarks}? (`nvim_tree.HighlightOption`) Highlight + bookmarked using the `NvimTreeBookmarkHL` + group. Value can be `"none"`, `"icon"`, + `"name"` or `"all"` Default `"none"` + • {highlight_clipboard}? (`nvim_tree.HighlightOption`) Enable + highlight for clipboard items using the + `NvimTreeCutHL` and `NvimTreeCopiedHL` + groups. Value can be `"none"`, `"icon"`, + `"name"` or `"all"`. Default: `"name"` + • {indent_markers}? (`nvim_tree.Config.Renderer.IndentMarkers`) + Configuration options for tree indent + markers. + • {icons}? (`nvim_tree.Config.Renderer.Icons`) + Configuration options for icons. + +*nvim_tree.Config.Renderer.Icons* + + Fields: ~ + • {web_devicons}? (`nvim_tree.Config.Renderer.Icons.WebDevicons`) + Configure optional plugin + `"nvim-tree/nvim-web-devicons"` + • {git_placement}? (`nvim_tree.PlacementOption`) Git icons + placement. Default: `"before"` + • {diagnostics_placement}? (`nvim_tree.PlacementOption`) Diganostic + icon placement. Default: `"signcolumn"` @see + nvim-tree.view.signcolumn @see + nvim-tree.renderer.icons.show.diagnostics + • {modified_placement}? (`nvim_tree.PlacementOption`) Modified icon + placement. Default: `"after"` + • {hidden_placement}? (`nvim_tree.PlacementOption`) Hidden icon + placement. Default: `"after"` + • {bookmarks_placement}? (`nvim_tree.PlacementOption`) Bookmark icon + placement. Default: `"signcolumn"` @see + nvim-tree.renderer.icons.show.bookmarks + • {padding}? (`nvim_tree.Config.Renderer.Icons.Padding`) + • {symlink_arrow}? (`string`) Used as a separator between + symlinks' source and target. Default: + `" ➛ "` + • {show}? (`nvim_tree.Config.Renderer.Icons.Show`) + Configuration options for showing icon + types. Left to right order: file/folder, + git, modified, hidden, diagnostics, + bookmarked. + • {glyphs}? (`nvim_tree.Config.Renderer.Icons.Glyphs`) + Configuration options for icon glyphs. NOTE: + Do not set any glyphs to more than two + characters if it's going to appear in the + signcolumn. + +*nvim_tree.Config.Renderer.Icons.Glyphs* + + Fields: ~ + • {default}? (`string`) Glyph for files. Overridden by + |nvim-tree.renderer.icons.web_devicons| if available. + Default: `""` + • {symlink}? (`string`) Glyph for symlinks to files. Default: `""` + • {bookmark}? (`string`) Bookmark icon. Default: `"Ὰ4"` + • {modified}? (`string`) Icon to display for modified files. Default: + `"●"` + • {hidden}? (`string`) Icon to display for hidden files. Default: + `"c""` + • {folder}? (`nvim_tree.Config.Renderer.Icons.Glyphs.Folder`) Glyphs + for directories. Overridden by + |nvim-tree.renderer.icons.web_devicons| if available. + Default: + `{ arrow_closed = "", arrow_open = "", default = "", open = "", empty = "", empty_open = "", symlink = "", symlink_open = "", }` + • {git}? (`nvim_tree.Config.Renderer.Icons.Glyphs.Git`) Glyphs for + git status. Default: + `{ unstaged = "✗", staged = "✓", unmerged = "", renamed = "➜", untracked = "★", deleted = "", ignored = "◌", }` + +*nvim_tree.Config.Renderer.Icons.Glyphs.Folder* + + Fields: ~ + • {arrow_closed}? (`string`) Default: `""` + • {arrow_open}? (`string`) Default: `""` + • {default}? (`string`) Default: `""` + • {open}? (`string`) Default: `""` + • {empty}? (`string`) Default: `""` + • {empty_open}? (`string`) Default: `""` + • {symlink}? (`string`) Default: `""` + • {symlink_open}? (`string`) Default: `""` + +*nvim_tree.Config.Renderer.Icons.Glyphs.Git* + + Fields: ~ + • {unstaged}? (`string`) Default: `"✗"` + • {staged}? (`string`) Default: `"✓"` + • {unmerged}? (`string`) Default: `""` + • {renamed}? (`string`) Default: `"➜"` + • {untracked}? (`string`) Default: `"★"` + • {deleted}? (`string`) Default: `""` + • {ignored}? (`string`) Default: `"◌"` + +*nvim_tree.Config.Renderer.Icons.Padding* + + Fields: ~ + • {icon}? (`string`) Inserted between icon and filename. + Default: `" "` + • {folder_arrow}? (`string`) Inserted between folder arrow icon and + file/folder icon. Default: `" "` + +*nvim_tree.Config.Renderer.Icons.Show* + + Fields: ~ + • {file}? (`boolean`) Show an icon before the file name. + Default: `true` + • {folder}? (`boolean`) Show an icon before the folder name. + Default: `true` + • {folder_arrow}? (`boolean`) Show a small arrow before the folder + node. Arrow will be a part of the node when using + |renderer.indent_markers|. Default: `true` + • {git}? (`boolean`) Show a git status icon, see + |renderer.icons.git_placement| Requires |git.enable| + `= true` Default: `true` @see + nvim-tree.renderer.icons.git_placement @see + nvim-tree.git.enable + • {modified}? (`boolean`) Show a modified icon, see + |renderer.icons.modified_placement| Requires + |modified.enable| `= true` Default: `true` @see + nvim-tree.renderer.icons.modified_placement @see + nvim-tree.modified.enable + • {hidden}? (`boolean`) Show a hidden icon, see + |renderer.icons.hidden_placement| Default: `false` + @see nvim-tree.renderer.icons.hidden_placement + • {diagnostics}? (`boolean`) Show a diagnostics status icon, see + |renderer.icons.diagnostics_placement| Requires + |diagnostics.enable| `= true` Default: `true` @see + nvim-tree.renderer.icons.diagnostics_placement @see + nvim-tree.diagnostics.enable + • {bookmarks}? (`boolean`) Show a bookmark icon, see + |renderer.icons.bookmarks_placement| Default: `true` + @see nvim-tree.renderer.icons.bookmarks_placement + +*nvim_tree.Config.Renderer.Icons.WebDevicons* + + Fields: ~ + • {file}? (`nvim_tree.Config.Renderer.Icons.WebDevicons.File`) File + icons. + • {folder}? (`nvim_tree.Config.Renderer.Icons.WebDevicons.Folder`) + Folder icons. + +*nvim_tree.Config.Renderer.Icons.WebDevicons.File* + + Fields: ~ + • {enable}? (`boolean`) Show icons on files. Overrides + |nvim-tree.renderer.icons.glyphs.default| Default: `true` + • {color}? (`boolean`) Use icon colors for files. Overrides highlight + groups. Default: `true` + +*nvim_tree.Config.Renderer.Icons.WebDevicons.Folder* + + Fields: ~ + • {enable}? (`boolean`) Show icons on folders. Overrides + |nvim-tree.renderer.icons.glyphs.folder| Default: `false` + • {color}? (`boolean`) Use icon colors for folders. Overrides + highlight groups. Default: `true` + +*nvim_tree.Config.Renderer.IndentMarkers* + + Fields: ~ + • {enable}? (`boolean`) Display indent markers when folders are + open Default: `false` + • {inline_arrows}? (`boolean`) Display folder arrows in the same column + as indent marker when using + |renderer.icons.show.folder_arrow| Default: `true` + • {icons}? (`nvim_tree.Config.Renderer.IndentMarkers.Icons`) + Icons shown before the file/directory. Length 1. + Default: > lua { corner = "└", edge = "│", item + = "│", bottom = "─", none = " ", } + +*nvim_tree.Config.Renderer.IndentMarkers.Icons* + + Fields: ~ + • {corner}? (`string`) Default: `"└"` + • {edge}? (`string`) Default: `"│"` + • {item}? (`string`) Default: `"│"` + • {bottom}? (`string`) Default: `"─"` + • {none}? (`string`) Default: `" "` + +*nvim_tree.Config.Sort* + + Fields: ~ + • {sorter}? (`nvim_tree.SortOption|fun(nodes: table): nil`) + Changes how files within the same directory are + sorted. Can be one of `"name"`, `"case_sensitive"`, + `"modification_time"`, `"extension"`, `"suffix"`, + `"filetype"` or a function. `"extension"` uses all + suffixes e.g. `foo.tar.gz` -> `.tar.gz` `"suffix"` + uses the last e.g. `.gz` Default: `"name"` Function + may perform a sort or return a string with one of + the above methods. It is passed a table of nodes to + be sorted, each node containing: - `absolute_path`: + `string` - `executable`: `boolean` - `extension`: + `string` - `filetype`: `string` - `link_to`: + `string` - `name`: `string` - `type`: `"directory"` + | `"file"` | `"link"` + • {folders_first}? (`boolean`) Sort folders before files. Has no effect + when |nvim-tree.sort.sorter| is a function. Default: + `true` @see nvim-tree.sort.sorter + • {files_first}? (`boolean`) Sort files before folders. Has no effect + when |nvim-tree.sort.sorter| is a function. If set + to `true` it overrides + |nvim-tree.sort.folders_first|. Default: `false` + @see nvim-tree.sort.sorter @see + nvim-tree.sort.folders_first + +*nvim_tree.Config.SystemOpen* + + Fields: ~ + • {cmd}? (`string`) The open command itself. Default: `""` neovim >= + 0.10 defaults to |vim.ui.open| neovim < 0.10 defaults to: + UNIX: `"xdg-open"` macOS: `"open"` Windows: `"cmd"` + • {args}? (`string[]`) Optional argument list. Default: `{}` Leave + empty for OS specific default: Windows: + `{ "/c", "start", '""' }` + +*nvim_tree.Config.Tab* + + Fields: ~ + • {sync}? (`nvim_tree.Config.Tab.Sync`) Configuration for syncing + nvim-tree across tabs. + +*nvim_tree.Config.Tab.Sync* + + Fields: ~ + • {open}? (`boolean`) Opens the tree automatically when switching + tabpage or opening a new tabpage if the tree was previously + open. Default: `false` + • {close}? (`boolean`) Closes the tree across all tabpages when the + tree is closed. Default: `false` + • {ignore}? (`string[]`) List of filetypes or buffer names on new tab + that will prevent |nvim-tree.tab.sync.open| and + |nvim-tree.tab.sync.close| Default: `{}` + +*nvim_tree.Config.Trash* + + Fields: ~ + • {cmd}? (`string`) The command used to trash items (must be installed + on your system). Default linux `"gio trash"` from glib2 is a + commonly shipped linux package. macOS default `"trash"` + requires the homebrew package `trash` Windows default + `"trash"` requires `trash-cli` or similar Default: + `"gio trash"` or `"trash"` + +*nvim_tree.Config.UI* + + Fields: ~ + • {confirm}? (`nvim_tree.Config.UI.Confirm`) Confirmation prompts. + +*nvim_tree.Config.UI.Confirm* + + Fields: ~ + • {remove}? (`boolean`) Prompt before removing. Default: `true` + • {trash}? (`boolean`) Prompt before trashing. Default: `true` + • {default_yes}? (`boolean`) If `true` the prompt will be `\"Y/n\"`, + otherwise `\"y/N\"`. Default: `false` + +*nvim_tree.Config.UpdateFocusedFile* + + Fields: ~ + • {enable}? (`boolean`) Enable this feature. Default: `false` + • {update_root}? (`nvim_tree.Config.UpdateFocusedFile.UpdateRoot`) + Update the root directory of the tree if the file is + not under current root directory. It prefers vim's cwd + and `root_dirs`. Otherwise it falls back to the folder + containing the file. Only relevant when + `update_focused_file.enable` is `true` @see + nvim-tree.update_focused_file.enable + • {exclude}? (`fun(args: vim.api.keyset.create_autocmd.callback_args): boolean`) + A function that returns true if the file should not be + focused when opening. Takes the `BufEnter` event as an + argument. see |autocmd-events| Default: `false` + +*nvim_tree.Config.UpdateFocusedFile.UpdateRoot* + + Fields: ~ + • {enable}? (`boolean`) Default: `false` + • {ignore_list}? (`string[]`) List of buffer names and filetypes that + will not update the root dir of the tree if the file + isn't found under the current root directory. Only + relevant when `update_focused_file.update_root.enable` + and `update_focused_file.enable` are `true`. Default: + `{}` @see + nvim-tree.update_focused_file.update_root.enable @see + nvim-tree.update_focused_file.enable + +*nvim_tree.Config.View* + + Fields: ~ + • {adaptive_size}? (`boolean`) Resize the window on each + draw based on the longest line. + Default: `false` + • {centralize_selection}? (`boolean`) When entering nvim-tree, + reposition the view so that the + current node is initially centralized, + see |zz|. Default: `false` + • {side}? (`nvim_tree.PlacementOption`) Side of + the tree. Default: `"left"` + • {preserve_window_proportions}? (`boolean`) Preserves window + proportions when opening a file. If + `false`, the height and width of + windows other than nvim-tree will be + equalized. Default: `false` + • {number}? (`boolean`) Print the line number in + front of each line. Default: `false` + • {relativenumber}? (`boolean`) Show the line number + relative to the line with the cursor + in front of each line. Default: + `false` + • {signcolumn}? (`nvim_tree.HiddenDisplayOption`) Show + |signcolumn|. Default: `"yes"` + • {width}? (`string|integer|nvim_tree.Config.View.Width|fun(): integer|string`) + Width of the window: can be a `%` + string, a number representing columns, + a function or a table. A table + indicates that the view should be + dynamically sized based on the longest + line. Default: `30` + • {float}? (`nvim_tree.Config.View.Float`) + Configuration options for floating + window. + • {cursorline}? (`boolean`) Enable |cursorline| in + nvim-tree window. Default: `true` + • {debounce_delay}? (`integer`) Idle milliseconds before + some reload / refresh operations. + Increase if you experience performance + issues around screen refresh. Default: + `15` (ms) + +*nvim_tree.Config.View.Float* + + Fields: ~ + • {enable}? (`boolean`) If true, tree window will be + floating. Default: `false` + • {quit_on_focus_loss}? (`boolean`) Close the floating tree window when + it loses focus. Default: `true` + • {open_win_config}? (`table|fun(): table`) Floating window config. + See |nvim_open_win()| for more details. + Default: + `{ relative = "editor", border = "rounded", width = 30, height = 30, row = 1, col = 1, }` + +*nvim_tree.Config.View.Width* + + Fields: ~ + • {min}? (`string|integer|fun(): integer|string`) Minimum + dynamic width. Default: `30` + • {max}? (`string|integer|fun(): integer|string`) Maximum + dynamic width, -1 for unbounded. Default: `-1` + • {lines_excluded}? (`string[]`) Exclude these lines when computing + width. Supported values: `"root"`. Default: + `{ "root" }` + • {padding}? (`integer|fun(): integer|string`) Extra padding to + the right. Default: `1` + + + +============================================================================== +Lua module: nvim_tree.api.decorator *nvim-tree-api-decorator* *nvim_tree.api.decorator.UserDecorator* Custom decorator, see :help nvim-tree-decorators diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua index 8ef1730efee..7d901c61a88 100644 --- a/scripts/gen_vimdoc_config.lua +++ b/scripts/gen_vimdoc_config.lua @@ -6,22 +6,28 @@ local config = { filename = "nvim-tree-lua.txt", -- filename = "decorator.txt", section_order = { + "config.lua", "api_decorator.lua", }, files = { -- module is derived soley from the file name, first letter capitalised "lua/nvim-tree/_meta/api_decorator.lua", + "lua/nvim-tree/_meta/config.lua", }, section_fmt = function(name) - if name == "Api_decorator" then - return " 6.11 API DECORATOR" + if name == "Config" then + return "Lua module: nvim_tree.Config" + elseif name == "Api_decorator" then + return "Lua module: nvim_tree.api.decorator" end error(string.format("unknown module %s passed to section_fmt", name)) end, helptag_fmt = function(name) - -- used to locate the help section - if name == "Api_decorator" then - return "nvim-tree-api.decorator" + -- used to locate the first section only, others will be rendered after + if name == "Config" then + return "nvim-tree-config" + elseif name == "Api_decorator" then + return "nvim-tree-api-decorator" end error(string.format("unknown module %s passed to helptag_fmt", name)) end, From d14385f5386416d25bf77ee964e6ac6485db305a Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Mon, 5 Jan 2026 13:58:07 +1100 Subject: [PATCH 006/170] doc(#2934): add nvim_tree.api classes to help --- doc/nvim-tree-lua.txt | 96 +++++++++++++++++++++++++++++++++-- scripts/gen_vimdoc_config.lua | 71 +++++++++++++++++--------- 2 files changed, 141 insertions(+), 26 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 8b379e37b45..e87dbdad411 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -1,9 +1,9 @@ -*nvim-tree.lua* A File Explorer For Neovim Written In Lua +*nvim-tree* A File Explorer For Neovim Written In Lua Author: Yazdani Kiyan ============================================================================== -CONTENTS *nvim-tree* +CONTENTS 1. Introduction |nvim-tree-introduction| 2. Quickstart |nvim-tree-quickstart| @@ -3459,7 +3459,7 @@ highlight group is not, hard linking as follows: > |nvim-tree-api.tree.winid()| ============================================================================== -Lua module: nvim_tree.Config *nvim-tree-config* +Lua module: nvim_tree *nvim-tree-module* *nvim_tree.Config* @@ -4276,6 +4276,96 @@ Lua module: nvim_tree.Config *nvim-tree-config* +============================================================================== +Lua module: nvim_tree.api *nvim-tree-api* + +*nvim_tree.api.CollapseOpts* + + Fields: ~ + • {keep_buffers}? (`boolean`) do not collapse nodes with open buffers + +*nvim_tree.api.NodeBufferOpts* + + Fields: ~ + • {force}? (`boolean`) delete/wipe even if buffer is modified, default + false + +*nvim_tree.api.NodeEditOpts* + + Fields: ~ + • {quit_on_open}? (`boolean`) quits the tree when opening the file + • {focus}? (`boolean`) keep focus in the tree when opening the + file + +*nvim_tree.api.TreeExpandOpts* + + Fields: ~ + • {expand_until}? (`fun(expansion_count: integer, node: Node): boolean`) + Return true if node should be expanded. + expansion_count is the total number of folders + expanded. + +*nvim_tree.api.TreeFindFileOpts* + + Fields: ~ + • {buf}? (`string|number`) absolute/relative path OR bufnr + to find + • {open}? (`boolean`) open the tree if necessary + • {current_window}? (`boolean`) requires open, open in the current + window + • {winid}? (`number`) open the tree in the specified |winid|, + overrides current_window + • {update_root}? (`boolean`) see + |nvim-tree.update_focused_file.update_root| + • {focus}? (`boolean`) focus the tree + +*nvim_tree.api.TreeIsVisibleOpts* + + Fields: ~ + • {tabpage}? (`number`) as per |nvim_get_current_tabpage()| + • {any_tabpage}? (`boolean`) visible on any tab, default false + +*nvim_tree.api.TreeOpenOpts* + + Fields: ~ + • {path}? (`string`) root directory for the tree + • {current_window}? (`boolean`) open the tree in the current window + • {winid}? (`number`) open the tree in the specified winid, + overrides current_window + • {find_file}? (`boolean`) find the current buffer + • {update_root}? (`boolean`) requires find_file, see + |nvim-tree.update_focused_file.update_root| + • {focus}? (`boolean`) focus the tree when opening, default + true + +*nvim_tree.api.TreeResizeOpts* + + Fields: ~ + • {width}? (`string|function|number|table`) new + |nvim-tree.view.width| value + • {absolute}? (`number`) set the width + • {relative}? (`number`) relative width adjustment + +*nvim_tree.api.TreeToggleOpts* + + Fields: ~ + • {path}? (`string`) root directory for the tree + • {current_window}? (`boolean`) open the tree in the current window + • {winid}? (`number`) open the tree in the specified |winid|, + overrides current_window + • {find_file}? (`boolean`) find the current buffer + • {update_root}? (`boolean`) requires find_file, see + |nvim-tree.update_focused_file.update_root| + • {focus}? (`boolean`) focus the tree when opening, default + true + +*nvim_tree.api.TreeWinIdOpts* + + Fields: ~ + • {tabpage}? (`number`) tabpage, 0 or nil for current, default nil + + + ============================================================================== Lua module: nvim_tree.api.decorator *nvim-tree-api-decorator* diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua index 7d901c61a88..7fd7fdf3de0 100644 --- a/scripts/gen_vimdoc_config.lua +++ b/scripts/gen_vimdoc_config.lua @@ -1,36 +1,61 @@ ---@diagnostic disable: undefined-doc-name +-- module name is derived as the file name with the first letter capitalised +local modules = { + Api = { + order = 2, + helptag = "nvim-tree-api", + title = "Lua module: nvim_tree.api", + path = "lua/nvim-tree/_meta/api.lua", + }, + Config = { + order = 1, + helptag = "nvim-tree-module", + title = "Lua module: nvim_tree", + path = "lua/nvim-tree/_meta/config.lua", + }, + Api_decorator = { + order = 3, + helptag = "nvim-tree-api-decorator", + title = "Lua module: nvim_tree.api.decorator", + path = "lua/nvim-tree/_meta/api_decorator.lua", + }, +} + --- @type table local config = { decorator = { filename = "nvim-tree-lua.txt", - -- filename = "decorator.txt", - section_order = { - "config.lua", - "api_decorator.lua", - }, - files = { - -- module is derived soley from the file name, first letter capitalised - "lua/nvim-tree/_meta/api_decorator.lua", - "lua/nvim-tree/_meta/config.lua", - }, - section_fmt = function(name) - if name == "Config" then - return "Lua module: nvim_tree.Config" - elseif name == "Api_decorator" then - return "Lua module: nvim_tree.api.decorator" + + -- file name sets order + section_order = (function() + local ret = {} + for _, c in pairs(modules) do + ret[c.order] = vim.fn.fnamemodify(c.path, ":t") + end + return ret + end)(), + + -- full path, will be ordered by section_order + files = (function() + local ret = {} + for _, c in pairs(modules) do + table.insert(ret, c.path) end - error(string.format("unknown module %s passed to section_fmt", name)) + return ret + end)(), + + -- section title + section_fmt = function(name) + return modules[name] and modules[name].title or error(string.format("unknown module %s passed to section", name)) end, + + -- section's help tag helptag_fmt = function(name) - -- used to locate the first section only, others will be rendered after - if name == "Config" then - return "nvim-tree-config" - elseif name == "Api_decorator" then - return "nvim-tree-api-decorator" - end - error(string.format("unknown module %s passed to helptag_fmt", name)) + return modules[name] and modules[name].helptag or error(string.format("unknown module %s passed to helptag_fmt", name)) end, + + -- class/function's help tag fn_helptag_fmt = function(fun) -- Modified copy of fn_helptag_fmt_common -- Uses fully qualified class name in the tag for methods. From d733127ea12c24f1241ae5d3ee98d4a096158d47 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Mon, 5 Jan 2026 15:30:00 +1100 Subject: [PATCH 007/170] doc(#2934): tidy and correct nvim_tree.Config.UI and nvim_tree.Config.Actions --- doc/nvim-tree-lua.txt | 143 ++++++++++++++------------- lua/nvim-tree/_meta/config.lua | 173 +++++++++++++++++++++++++++------ 2 files changed, 220 insertions(+), 96 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index e87dbdad411..1653c8bd667 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3539,101 +3539,110 @@ Lua module: nvim_tree *nvim-tree-module* *nvim_tree.Config.Actions* Fields: ~ - • {use_system_clipboard}? (`boolean`) A boolean value that toggle the - use of system clipboard when copy/paste - function are invoked. When enabled, copied - text will be stored in registers '+' - (system), otherwise, it will be stored in '1' - and '"'. Default: `true` - • {change_dir}? (`nvim_tree.Config.Actions.ChangeDir`) vim - |current-directory| behaviour. + • {use_system_clipboard}? (`boolean`, default: `true`) A boolean value + that toggle the use of system clipboard when + copy/paste function are invoked. When + enabled, copied text will be stored in + registers `+` (system), otherwise, it will be + stored in `1` and `"` + • {change_dir}? (`nvim_tree.Config.Actions.ChangeDir`) + |nvim_tree.Config.Actions.ChangeDir| • {expand_all}? (`nvim_tree.Config.Actions.ExpandAll`) - Configuration for - |nvim-tree-api.tree.expand_all()| and - |nvim-tree-api.node.expand()| + |nvim_tree.Config.Actions.ExpandAll| • {file_popup}? (`nvim_tree.Config.Actions.FilePopup`) - Configuration for file_popup behaviour. + |nvim_tree.Config.Actions.FilePopup| • {open_file}? (`nvim_tree.Config.Actions.OpenFile`) - Configuration options for opening a file from - nvim-tree. + |nvim_tree.Config.Actions.OpenFile| • {remove_file}? (`nvim_tree.Config.Actions.RemoveFile`) - Configuration options for removing a file - from nvim-tree. + |nvim_tree.Config.Actions.RemoveFile| *nvim_tree.Config.Actions.ChangeDir* + vim |current-directory| behaviour Fields: ~ - • {enable}? (`boolean`) Change the working directory when - changing directories in the tree. Default: - `true` - • {global}? (`boolean`) Use `:cd` instead of `:lcd` when - changing directories. Default: `false` - • {restrict_above_cwd}? (`boolean`) Restrict changing to a directory - above the global cwd. Default: `false` + • {enable}? (`boolean`, default: `true`) Change the working + directory when changing directories in the tree + • {global}? (`boolean`, default: `false`) Use `:cd` instead + of `:lcd` when changing directories. + • {restrict_above_cwd}? (`boolean`, default: `false`) Restrict changing + to a directory above the global cwd. *nvim_tree.Config.Actions.ExpandAll* + Configuration for |nvim-tree-api.tree.expand_all()| and + |nvim-tree-api.node.expand()| Fields: ~ - • {max_folder_discovery}? (`integer`) Limit the number of folders being - explored when expanding every folders. Avoids - hanging neovim when running this action on - very large folders. Default: `300` - • {exclude}? (`string[]`) A list of directories that - should not be expanded automatically. E.g - `{ ".git", "target", "build" }` etc. Default: - `{}` + • {max_folder_discovery}? (`integer`, default: `300`) Limit the number + of folders being explored when expanding + every folders. Avoids hanging neovim when + running this action on very large folders. + • {exclude}? (`string[]`, default: `{}`) A list of + directories that should not be expanded + automatically e.g + `{ ".git", "target", "build" }` *nvim_tree.Config.Actions.FilePopup* + Configuration for file_popup behaviour. Fields: ~ - • {open_win_config}? (`table`) Floating window config for file_popup. - See |nvim_open_win| for more details. You - shouldn't define `"width"` and `"height"` values - here. They will be overridden to fit the - file_popup content. Default: - `{ col = 1, row = 1, relative = "cursor", border = "shadow", style = "minimal", }` + • {open_win_config}? (`vim.api.keyset.win_config`, default: `{ col = 1, row = 1, relative = "cursor", border = "shadow", style = "minimal", }`) + Floating window config for file_popup. See + |nvim_open_win| and |vim.api.keyset.win_config| + for more details. You shouldn't define `width` and + `height` values here. They will be overridden to + fit the file_popup content. *nvim_tree.Config.Actions.OpenFile* + Configuration options for opening a file from nvim-tree. Fields: ~ - • {quit_on_open}? (`boolean`) Closes the explorer when opening a file. - Default: `false` - • {eject}? (`boolean`) Prevent a new file opened from within - nvim-tree replacing the current nvim-tree window. - Default: `true` - • {resize_window}? (`boolean`) Resizes the tree when opening a file. - Default: `true` + • {quit_on_open}? (`boolean`, default: `false`) Closes the explorer + when opening a file + • {eject}? (`boolean`, default: `true`) Prevent new opened file + from opening in the same window as the tree. + • {resize_window}? (`boolean`, default: `true`) Resizes the tree when + opening a file • {window_picker}? (`nvim_tree.Config.Actions.OpenFile.WindowPicker`) - Window picker configuration. + |nvim_tree.Config.Actions.OpenFile.WindowPicker| *nvim_tree.Config.Actions.OpenFile.WindowPicker* + Window picker configuration. Fields: ~ - • {enable}? (`boolean`) Enable the window picker. If this feature is - not enabled, files will open in the current window. - Default: `true` - • {picker}? (`string|fun(): integer`) Change the way in which to pick - a window. Default: `"default"` - • {chars}? (`string`) A string of chars used for window picker - labels. Default: `"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"` + • {enable}? (`boolean`, default: `true`) Enable the feature. If the + feature is not enabled, files will open in window from + which you last opened the tree, obeying + |nvim-tree.actions.open_file.window_picker.exclude| + • {picker}? (`string|fun(): integer`, default: `"default"`) Change the + default window picker: a string `"default"` or a function. + The function should return the window id that will open + the node, or `nil` if an invalid window is picked or user + cancelled the action. The picker may create a new window. + • {chars}? (`string`, default: + `"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"`) A string of + chars used as identifiers by the window picker. • {exclude}? (`nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude`) - Floating window config for window selector. + |nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude| *nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude* + Tables of buffer option names mapped to a list of option values. Windows + containing matching buffers will not be: + • available when using a window picker + • selected when not using a window picker Fields: ~ - • {filetype}? (`string[]`) A list of filetypes to exclude from window - picker. Default: - `{ "notify", "lazy", "qf", "diff", "fugitive", "fugitiveblame", }` - • {buftype}? (`string[]`) A list of buftypes to exclude from window - picker. Default: `{ "nofile", "terminal", "help", }` + • {filetype}? (`string[]`) (default: + `{ "notify", "lazy", "qf", "diff", "fugitive", "fugitiveblame", }`) + • {buftype}? (`string[]`) (default: + `{ "nofile", "terminal", "help", }`) *nvim_tree.Config.Actions.RemoveFile* + Configuration options for removing a file from nvim-tree. Fields: ~ - • {close_window}? (`boolean`) Close any window that displays a file - when removing that file from the tree. Default: - `true` + • {close_window}? (`boolean`, default: `true`) Close any window that + displays a file when removing that file from the + tree. *nvim_tree.Config.Diagnostics* @@ -4167,15 +4176,17 @@ Lua module: nvim_tree *nvim-tree-module* *nvim_tree.Config.UI* Fields: ~ - • {confirm}? (`nvim_tree.Config.UI.Confirm`) Confirmation prompts. + • {confirm}? (`nvim_tree.Config.UI.Confirm`) + |nvim_tree.Config.UI.Confirm| *nvim_tree.Config.UI.Confirm* + Confirmation prompts. Fields: ~ - • {remove}? (`boolean`) Prompt before removing. Default: `true` - • {trash}? (`boolean`) Prompt before trashing. Default: `true` - • {default_yes}? (`boolean`) If `true` the prompt will be `\"Y/n\"`, - otherwise `\"y/N\"`. Default: `false` + • {remove}? (`boolean`, default: `true`) Prompt before removing. + • {trash}? (`boolean`, default: `true`) Prompt before trashing. + • {default_yes}? (`boolean`, default: `false`) If `true` the prompt + will be `Y/n`, otherwise `y/N` *nvim_tree.Config.UpdateFocusedFile* diff --git a/lua/nvim-tree/_meta/config.lua b/lua/nvim-tree/_meta/config.lua index f00523978cd..42f510529e5 100644 --- a/lua/nvim-tree/_meta/config.lua +++ b/lua/nvim-tree/_meta/config.lua @@ -326,55 +326,168 @@ error("Cannot require a meta file") -- ---@class nvim_tree.Config.UI ----@field confirm? nvim_tree.Config.UI.Confirm Confirmation prompts. +--- +---|nvim_tree.Config.UI.Confirm| +---@field confirm? nvim_tree.Config.UI.Confirm +-- +-- UI.Confirm +-- + +---Confirmation prompts. ---@class nvim_tree.Config.UI.Confirm ----@field remove? boolean Prompt before removing. Default: `true` ----@field trash? boolean Prompt before trashing. Default: `true` ----@field default_yes? boolean If `true` the prompt will be `\"Y/n\"`, otherwise `\"y/N\"`. Default: `false` +--- +---Prompt before removing. +---(default: `true`) +---@field remove? boolean +--- +---Prompt before trashing. +---(default: `true`) +---@field trash? boolean +--- +---If `true` the prompt will be `Y/n`, otherwise `y/N` +---(default: `false`) +---@field default_yes? boolean -- -- Actions -- ---@class nvim_tree.Config.Actions ----@field use_system_clipboard? boolean A boolean value that toggle the use of system clipboard when copy/paste function are invoked. When enabled, copied text will be stored in registers '+' (system), otherwise, it will be stored in '1' and '"'. Default: `true` ----@field change_dir? nvim_tree.Config.Actions.ChangeDir vim |current-directory| behaviour. ----@field expand_all? nvim_tree.Config.Actions.ExpandAll Configuration for |nvim-tree-api.tree.expand_all()| and |nvim-tree-api.node.expand()| ----@field file_popup? nvim_tree.Config.Actions.FilePopup Configuration for file_popup behaviour. ----@field open_file? nvim_tree.Config.Actions.OpenFile Configuration options for opening a file from nvim-tree. ----@field remove_file? nvim_tree.Config.Actions.RemoveFile Configuration options for removing a file from nvim-tree. - +--- +---A boolean value that toggle the use of system clipboard when copy/paste function are invoked. When enabled, copied text will be stored in registers `+` (system), otherwise, it will be stored in `1` and `"` +---(default: `true`) +---@field use_system_clipboard? boolean +--- +---|nvim_tree.Config.Actions.ChangeDir| +---@field change_dir? nvim_tree.Config.Actions.ChangeDir +--- +---|nvim_tree.Config.Actions.ExpandAll| +---@field expand_all? nvim_tree.Config.Actions.ExpandAll +--- +---|nvim_tree.Config.Actions.FilePopup| +---@field file_popup? nvim_tree.Config.Actions.FilePopup +--- +---|nvim_tree.Config.Actions.OpenFile| +---@field open_file? nvim_tree.Config.Actions.OpenFile +--- +---|nvim_tree.Config.Actions.RemoveFile| +---@field remove_file? nvim_tree.Config.Actions.RemoveFile + +-- +-- Actions.ChangeDir +-- + +--- vim |current-directory| behaviour ---@class nvim_tree.Config.Actions.ChangeDir ----@field enable? boolean Change the working directory when changing directories in the tree. Default: `true` ----@field global? boolean Use `:cd` instead of `:lcd` when changing directories. Default: `false` ----@field restrict_above_cwd? boolean Restrict changing to a directory above the global cwd. Default: `false` +--- +---Change the working directory when changing directories in the tree +---(default: `true`) +---@field enable? boolean +--- +---Use `:cd` instead of `:lcd` when changing directories. +---(default: `false`) +---@field global? boolean +--- +--- Restrict changing to a directory above the global cwd. +---(default: `false`) +---@field restrict_above_cwd? boolean +-- +-- Actions.ExpandAll +-- + +---Configuration for |nvim-tree-api.tree.expand_all()| and |nvim-tree-api.node.expand()| ---@class nvim_tree.Config.Actions.ExpandAll ----@field max_folder_discovery? integer Limit the number of folders being explored when expanding every folders. Avoids hanging neovim when running this action on very large folders. Default: `300` ----@field exclude? string[] A list of directories that should not be expanded automatically. E.g `{ ".git", "target", "build" }` etc. Default: `{}` +--- +---Limit the number of folders being explored when expanding every folders. Avoids hanging neovim when running this action on very large folders. +---(default: `300`) +---@field max_folder_discovery? integer +--- +---A list of directories that should not be expanded automatically e.g `{ ".git", "target", "build" }` +---(default: `{}`) +---@field exclude? string[] + +-- +-- Actions.FilePopup +-- +---Configuration for file_popup behaviour. ---@class nvim_tree.Config.Actions.FilePopup ----@field open_win_config? table Floating window config for file_popup. See |nvim_open_win| for more details. You shouldn't define `"width"` and `"height"` values here. They will be overridden to fit the file_popup content. Default: `{ col = 1, row = 1, relative = "cursor", border = "shadow", style = "minimal", }` +--- +---Floating window config for file_popup. See |nvim_open_win| and |vim.api.keyset.win_config| for more details. You shouldn't define `width` and `height` values here. They will be overridden to fit the file_popup content. +---(default: `{ col = 1, row = 1, relative = "cursor", border = "shadow", style = "minimal", }`) +---@field open_win_config? vim.api.keyset.win_config ----@class nvim_tree.Config.Actions.OpenFile ----@field quit_on_open? boolean Closes the explorer when opening a file. Default: `false` ----@field eject? boolean Prevent a new file opened from within nvim-tree replacing the current nvim-tree window. Default: `true` ----@field resize_window? boolean Resizes the tree when opening a file. Default: `true` ----@field window_picker? nvim_tree.Config.Actions.OpenFile.WindowPicker Window picker configuration. +-- +-- Actions.OpenFile +-- +---Configuration options for opening a file from nvim-tree. +---@class nvim_tree.Config.Actions.OpenFile +--- +---Closes the explorer when opening a file +---(default: `false`) +---@field quit_on_open? boolean +--- +---Prevent new opened file from opening in the same window as the tree. +---(default: `true`) +---@field eject? boolean +--- +---Resizes the tree when opening a file +---(default: `true`) +---@field resize_window? boolean +--- +---|nvim_tree.Config.Actions.OpenFile.WindowPicker| +---@field window_picker? nvim_tree.Config.Actions.OpenFile.WindowPicker + +-- +-- Actions.OpenFile.WindowPicker +-- + +---Window picker configuration. ---@class nvim_tree.Config.Actions.OpenFile.WindowPicker ----@field enable? boolean Enable the window picker. If this feature is not enabled, files will open in the current window. Default: `true` ----@field picker? string|fun(): integer Change the way in which to pick a window. Default: `"default"` ----@field chars? string A string of chars used for window picker labels. Default: `"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"` ----@field exclude? nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude Floating window config for window selector. - +--- +---Enable the feature. If the feature is not enabled, files will open in window from which you last opened the tree, obeying |nvim-tree.actions.open_file.window_picker.exclude| +---(default: `true`) +---@field enable? boolean +--- +---Change the default window picker: a string `"default"` or a function. The function should return the window id that will open the node, or `nil` if an invalid window is picked or user cancelled the action. The picker may create a new window. +---(default: `"default"`) +---@field picker? string|fun(): integer +--- +---A string of chars used as identifiers by the window picker. +---(default: `"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"`) +---@field chars? string +--- +---|nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude| +---@field exclude? nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude + +-- +-- Actions.OpenFile.WindowPicker.Exclude +-- + +---Tables of buffer option names mapped to a list of option values. Windows containing matching buffers will not be: +--- - available when using a window picker +--- - selected when not using a window picker ---@class nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude ----@field filetype? string[] A list of filetypes to exclude from window picker. Default: `{ "notify", "lazy", "qf", "diff", "fugitive", "fugitiveblame", }` ----@field buftype? string[] A list of buftypes to exclude from window picker. Default: `{ "nofile", "terminal", "help", }` +--- +---(default: `{ "notify", "lazy", "qf", "diff", "fugitive", "fugitiveblame", }`) +---@field filetype? string[] +--- +---(default: `{ "nofile", "terminal", "help", }`) +---@field buftype? string[] + +-- +-- Actions.RemoveFile +-- +---Configuration options for removing a file from nvim-tree. ---@class nvim_tree.Config.Actions.RemoveFile ----@field close_window? boolean Close any window that displays a file when removing that file from the tree. Default: `true` +--- +---Close any window that displays a file when removing that file from the tree. +---(default: `true`) +---@field close_window? boolean -- -- View From 4221d19725fbe29f492ab5ff67011b0963f967f1 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Mon, 5 Jan 2026 15:51:49 +1100 Subject: [PATCH 008/170] doc(#2934): tidy and correct nvim_tree.Config.HijackDirectories, format and order nvim_tree.Config --- doc/nvim-tree-lua.txt | 57 +++++++++++++++++--------- lua/nvim-tree/_meta/config.lua | 74 +++++++++++++++++++++++++++------- 2 files changed, 97 insertions(+), 34 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 1653c8bd667..4ed061c9631 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3516,25 +3516,44 @@ Lua module: nvim_tree *nvim-tree-module* event of a problem please disable the experiment and raise an issue. - • {hijack_directories}? (`nvim_tree.Config.HijackDirectories`) - • {renderer}? (`nvim_tree.Config.Renderer`) - • {modified}? (`nvim_tree.Config.Modified`) - • {tab}? (`nvim_tree.Config.Tab`) - • {trash}? (`nvim_tree.Config.Trash`) - • {live_filter}? (`nvim_tree.Config.LiveFilter`) - • {system_open}? (`nvim_tree.Config.SystemOpen`) - • {help}? (`nvim_tree.Config.Help`) • {sort}? (`nvim_tree.Config.Sort`) - • {filters}? (`nvim_tree.Config.Filters`) + |nvim_tree.Config.Sort| + • {view}? (`nvim_tree.Config.View`) + |nvim_tree.Config.View| + • {renderer}? (`nvim_tree.Config.Renderer`) + |nvim_tree.Config.Renderer| + • {hijack_directories}? (`nvim_tree.Config.HijackDirectories`) + |nvim_tree.Config.HijackDirectories| • {update_focused_file}? (`nvim_tree.Config.UpdateFocusedFile`) + |nvim_tree.Config.UpdateFocusedFile| + • {system_open}? (`nvim_tree.Config.SystemOpen`) + |nvim_tree.Config.SystemOpen| • {git}? (`nvim_tree.Config.Git`) + |nvim_tree.Config.Git| • {diagnostics}? (`nvim_tree.Config.Diagnostics`) - • {notify}? (`nvim_tree.Config.Notify`) + |nvim_tree.Config.Diagnostics| + • {modified}? (`nvim_tree.Config.Modified`) + |nvim_tree.Config.Modified| + • {filters}? (`nvim_tree.Config.Filters`) + |nvim_tree.Config.Filters| + • {live_filter}? (`nvim_tree.Config.LiveFilter`) + |nvim_tree.Config.LiveFilter| • {filesystem_watchers}? (`nvim_tree.Config.FilesystemWatchers`) - • {log}? (`nvim_tree.Config.Log`) - • {ui}? (`nvim_tree.Config.UI`) + |nvim_tree.Config.FilesystemWatchers| • {actions}? (`nvim_tree.Config.Actions`) - • {view}? (`nvim_tree.Config.View`) + |nvim_tree.Config.Actions| + • {trash}? (`nvim_tree.Config.Trash`) + |nvim_tree.Config.Trash| + • {tab}? (`nvim_tree.Config.Tab`) + |nvim_tree.Config.Tab| + • {notify}? (`nvim_tree.Config.Notify`) + |nvim_tree.Config.Notify| + • {help}? (`nvim_tree.Config.Help`) + |nvim_tree.Config.Help| + • {ui}? (`nvim_tree.Config.UI`) + |nvim_tree.Config.UI| + • {log}? (`nvim_tree.Config.Log`) + |nvim_tree.Config.Log| *nvim_tree.Config.Actions* @@ -3780,12 +3799,12 @@ Lua module: nvim_tree *nvim-tree-module* *nvim_tree.Config.HijackDirectories* Fields: ~ - • {enable}? (`boolean`) Enable the feature. Disable this option if - you use vim-dirvish or dirbuf.nvim. If `hijack_netrw` - and `disable_netrw` are `false`, this feature will be - disabled. Default: `true` - • {auto_open}? (`boolean`) Opens the tree if the tree was previously - closed. Default: `true` + • {enable}? (`boolean`, default: `true`) Hijack directory buffers. + Disable this option if you use vim-dirvish or + dirbuf.nvim. If `hijack_netrw` and `disable_netrw` are + `false`, this feature will be disabled. + • {auto_open}? (`boolean`, default: `true`) Opens the tree if the tree + was previously closed. *nvim_tree.Config.LiveFilter* diff --git a/lua/nvim-tree/_meta/config.lua b/lua/nvim-tree/_meta/config.lua index 42f510529e5..1b8d2fc769a 100644 --- a/lua/nvim-tree/_meta/config.lua +++ b/lua/nvim-tree/_meta/config.lua @@ -33,33 +33,77 @@ error("Cannot require a meta file") ---@field sync_root_with_cwd? boolean Changes the tree root directory on `DirChanged` and refreshes the tree. Default: `false` ---@field root_dirs? string[] Preferred root directories. Only relevant when `update_focused_file.update_root` is `true` Default: `{}` @see nvim-tree.update_focused_file.update_root ---@field experimental? table Experimental features that may become default or optional functionality. In the event of a problem please disable the experiment and raise an issue. ----@field hijack_directories? nvim_tree.Config.HijackDirectories ----@field renderer? nvim_tree.Config.Renderer ----@field modified? nvim_tree.Config.Modified ----@field tab? nvim_tree.Config.Tab ----@field trash? nvim_tree.Config.Trash ----@field live_filter? nvim_tree.Config.LiveFilter ----@field system_open? nvim_tree.Config.SystemOpen ----@field help? nvim_tree.Config.Help +--- +---|nvim_tree.Config.Sort| ---@field sort? nvim_tree.Config.Sort ----@field filters? nvim_tree.Config.Filters +--- +---|nvim_tree.Config.View| +---@field view? nvim_tree.Config.View +--- +---|nvim_tree.Config.Renderer| +---@field renderer? nvim_tree.Config.Renderer +--- +---|nvim_tree.Config.HijackDirectories| +---@field hijack_directories? nvim_tree.Config.HijackDirectories +--- +---|nvim_tree.Config.UpdateFocusedFile| ---@field update_focused_file? nvim_tree.Config.UpdateFocusedFile +--- +---|nvim_tree.Config.SystemOpen| +---@field system_open? nvim_tree.Config.SystemOpen +--- +---|nvim_tree.Config.Git| ---@field git? nvim_tree.Config.Git +--- +---|nvim_tree.Config.Diagnostics| ---@field diagnostics? nvim_tree.Config.Diagnostics ----@field notify? nvim_tree.Config.Notify +--- +---|nvim_tree.Config.Modified| +---@field modified? nvim_tree.Config.Modified +--- +---|nvim_tree.Config.Filters| +---@field filters? nvim_tree.Config.Filters +--- +---|nvim_tree.Config.LiveFilter| +---@field live_filter? nvim_tree.Config.LiveFilter +--- +---|nvim_tree.Config.FilesystemWatchers| ---@field filesystem_watchers? nvim_tree.Config.FilesystemWatchers ----@field log? nvim_tree.Config.Log ----@field ui? nvim_tree.Config.UI +--- +---|nvim_tree.Config.Actions| ---@field actions? nvim_tree.Config.Actions ----@field view? nvim_tree.Config.View +--- +---|nvim_tree.Config.Trash| +---@field trash? nvim_tree.Config.Trash +--- +---|nvim_tree.Config.Tab| +---@field tab? nvim_tree.Config.Tab +--- +---|nvim_tree.Config.Notify| +---@field notify? nvim_tree.Config.Notify +--- +---|nvim_tree.Config.Help| +---@field help? nvim_tree.Config.Help +--- +---|nvim_tree.Config.UI| +---@field ui? nvim_tree.Config.UI +--- +---|nvim_tree.Config.Log| +---@field log? nvim_tree.Config.Log -- -- HijackDirectories -- ---@class nvim_tree.Config.HijackDirectories ----@field enable? boolean Enable the feature. Disable this option if you use vim-dirvish or dirbuf.nvim. If `hijack_netrw` and `disable_netrw` are `false`, this feature will be disabled. Default: `true` ----@field auto_open? boolean Opens the tree if the tree was previously closed. Default: `true` +--- +---Hijack directory buffers. Disable this option if you use vim-dirvish or dirbuf.nvim. If `hijack_netrw` and `disable_netrw` are `false`, this feature will be disabled. +---(default: `true`) +---@field enable? boolean +--- +---Opens the tree if the tree was previously closed. +---(default: `true`) +---@field auto_open? boolean -- -- Renderer From d14677db6b16ccc4f9c85bf611caf7fa3143c854 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Mon, 5 Jan 2026 16:23:40 +1100 Subject: [PATCH 009/170] doc(#2934): tidy and nvim_tree.Config top level --- doc/nvim-tree-lua.txt | 172 ++++++++++++++++----------------- lua/nvim-tree/_meta/config.lua | 59 ++++++++--- 2 files changed, 129 insertions(+), 102 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 4ed061c9631..3dde18594d0 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3464,96 +3464,88 @@ Lua module: nvim_tree *nvim-tree-module* *nvim_tree.Config* Fields: ~ - • {on_attach}? (`string|fun(bufnr: integer)`) - • {auto_reload_on_write}? (`boolean`) Reloads the - explorer every time a buffer is - written to. Default: `true` - • {disable_netrw}? (`boolean`) Completely disable - netrw Default: `false` - • {hijack_cursor}? (`boolean`) Keeps the cursor on - the first letter of the - filename when moving in the - tree. Default: `false` - • {hijack_netrw}? (`boolean`) Hijack netrw - windows (overridden if - |disable_netrw| is `true`) - Default: `true` - • {hijack_unnamed_buffer_when_opening}? (`boolean`) Opens in place of - the unnamed buffer if it's - empty. Default: `false` - • {prefer_startup_root}? (`boolean`) Prefer startup root - directory when updating root - directory of the tree. Only - relevant when - `update_focused_file.update_root` - is `true` Default: `false` @see - nvim-tree.update_focused_file.update_root - • {reload_on_bufenter}? (`boolean`) Automatically - reloads the tree on `BufEnter` - nvim-tree. Default: `false` - • {respect_buf_cwd}? (`boolean`) Will change cwd of - nvim-tree to that of new - buffer's when opening - nvim-tree. Default: `false` - • {select_prompts}? (`boolean`) Use |vim.ui.select| - style prompts. Necessary when - using a UI prompt decorator - such as dressing.nvim or - telescope-ui-select.nvim - Default: `false` - • {sync_root_with_cwd}? (`boolean`) Changes the tree - root directory on `DirChanged` - and refreshes the tree. - Default: `false` - • {root_dirs}? (`string[]`) Preferred root - directories. Only relevant when - `update_focused_file.update_root` - is `true` Default: `{}` @see - nvim-tree.update_focused_file.update_root - • {experimental}? (`table`) Experimental features - that may become default or - optional functionality. In the - event of a problem please - disable the experiment and - raise an issue. - • {sort}? (`nvim_tree.Config.Sort`) - |nvim_tree.Config.Sort| - • {view}? (`nvim_tree.Config.View`) - |nvim_tree.Config.View| - • {renderer}? (`nvim_tree.Config.Renderer`) - |nvim_tree.Config.Renderer| - • {hijack_directories}? (`nvim_tree.Config.HijackDirectories`) - |nvim_tree.Config.HijackDirectories| - • {update_focused_file}? (`nvim_tree.Config.UpdateFocusedFile`) - |nvim_tree.Config.UpdateFocusedFile| - • {system_open}? (`nvim_tree.Config.SystemOpen`) - |nvim_tree.Config.SystemOpen| - • {git}? (`nvim_tree.Config.Git`) - |nvim_tree.Config.Git| - • {diagnostics}? (`nvim_tree.Config.Diagnostics`) - |nvim_tree.Config.Diagnostics| - • {modified}? (`nvim_tree.Config.Modified`) - |nvim_tree.Config.Modified| - • {filters}? (`nvim_tree.Config.Filters`) - |nvim_tree.Config.Filters| - • {live_filter}? (`nvim_tree.Config.LiveFilter`) - |nvim_tree.Config.LiveFilter| - • {filesystem_watchers}? (`nvim_tree.Config.FilesystemWatchers`) - |nvim_tree.Config.FilesystemWatchers| - • {actions}? (`nvim_tree.Config.Actions`) - |nvim_tree.Config.Actions| - • {trash}? (`nvim_tree.Config.Trash`) - |nvim_tree.Config.Trash| - • {tab}? (`nvim_tree.Config.Tab`) - |nvim_tree.Config.Tab| - • {notify}? (`nvim_tree.Config.Notify`) - |nvim_tree.Config.Notify| - • {help}? (`nvim_tree.Config.Help`) - |nvim_tree.Config.Help| - • {ui}? (`nvim_tree.Config.UI`) - |nvim_tree.Config.UI| - • {log}? (`nvim_tree.Config.Log`) - |nvim_tree.Config.Log| + • {on_attach}? (`string|fun(bufnr: integer)`) Runs when + creating the nvim-tree buffer. Use this to + set your nvim-tree specific mappings. See + |nvim-tree-mappings|. When `on_attach` is not + a function, |nvim-tree-mappings-default| will + be called. + • {hijack_cursor}? (`boolean`, default: `false`) Keeps the + cursor on the first letter of the filename + when moving in the tree. + • {auto_reload_on_write}? (`boolean`, default: `true`) Reloads the + explorer every time a buffer is written to. + • {disable_netrw}? (`boolean`, default: `false`) Completely + disable |netrw|, see |nvim-tree-netrw| for + details. It is strongly advised to eagerly + disable netrw, due to race conditions at vim + startup. + • {hijack_netrw}? (`boolean`, default: `true`) Hijack netrw + windows, ignored when `disable_netrw` is + `true` + • {hubwo}? (`boolean`, default: `false`) Opens in place + of the unnamed buffer if it's empty. TODO + reinstate this one when formatting is done + #2934 --@field + hijack_unnamed_buffer_when_opening? boolean + • {root_dirs}? (`string[]`) Preferred root directories. Only + relevant when + |nvim_tree.Config.UpdateFocusedFile| + `update_root` is `true` + • {prefer_startup_root}? (`boolean`, default: `false`) Prefer startup + root directory when updating root directory + of the tree. Only relevant when + |nvim_tree.Config.UpdateFocusedFile| + `update_root` is `true` + • {sync_root_with_cwd}? (`boolean`, default: `false`) Changes the + tree root directory on |DirChanged| and + refreshes the tree. + • {reload_on_bufenter}? (`boolean`, default: `false`) Automatically + reloads the tree on |BufEnter| nvim-tree. + • {respect_buf_cwd}? (`boolean`, default: `false`) Change cwd of + nvim-tree to that of new buffer's when + opening nvim-tree. + • {select_prompts}? (`boolean`, default: `false`) Use + |vim.ui.select| style prompts. Necessary when + using a UI prompt decorator such as + dressing.nvim or telescope-ui-select.nvim + • {sort}? (`nvim_tree.Config.Sort`) + |nvim_tree.Config.Sort| + • {view}? (`nvim_tree.Config.View`) + |nvim_tree.Config.View| + • {renderer}? (`nvim_tree.Config.Renderer`) + |nvim_tree.Config.Renderer| + • {hijack_directories}? (`nvim_tree.Config.HijackDirectories`) + |nvim_tree.Config.HijackDirectories| + • {update_focused_file}? (`nvim_tree.Config.UpdateFocusedFile`) + |nvim_tree.Config.UpdateFocusedFile| + • {system_open}? (`nvim_tree.Config.SystemOpen`) + |nvim_tree.Config.SystemOpen| + • {git}? (`nvim_tree.Config.Git`) + |nvim_tree.Config.Git| + • {diagnostics}? (`nvim_tree.Config.Diagnostics`) + |nvim_tree.Config.Diagnostics| + • {modified}? (`nvim_tree.Config.Modified`) + |nvim_tree.Config.Modified| + • {filters}? (`nvim_tree.Config.Filters`) + |nvim_tree.Config.Filters| + • {live_filter}? (`nvim_tree.Config.LiveFilter`) + |nvim_tree.Config.LiveFilter| + • {filesystem_watchers}? (`nvim_tree.Config.FilesystemWatchers`) + |nvim_tree.Config.FilesystemWatchers| + • {actions}? (`nvim_tree.Config.Actions`) + |nvim_tree.Config.Actions| + • {trash}? (`nvim_tree.Config.Trash`) + |nvim_tree.Config.Trash| + • {tab}? (`nvim_tree.Config.Tab`) + |nvim_tree.Config.Tab| + • {notify}? (`nvim_tree.Config.Notify`) + |nvim_tree.Config.Notify| + • {help}? (`nvim_tree.Config.Help`) + |nvim_tree.Config.Help| + • {ui}? (`nvim_tree.Config.UI`) |nvim_tree.Config.UI| + • {log}? (`nvim_tree.Config.Log`) + |nvim_tree.Config.Log| *nvim_tree.Config.Actions* diff --git a/lua/nvim-tree/_meta/config.lua b/lua/nvim-tree/_meta/config.lua index 1b8d2fc769a..89f281e2f78 100644 --- a/lua/nvim-tree/_meta/config.lua +++ b/lua/nvim-tree/_meta/config.lua @@ -20,19 +20,54 @@ error("Cannot require a meta file") -- ---@class nvim_tree.Config +--- +---Runs when creating the nvim-tree buffer. Use this to set your nvim-tree specific mappings. See |nvim-tree-mappings|. When `on_attach` is not a function, |nvim-tree-mappings-default| will be called. ---@field on_attach? string|fun(bufnr: integer) ----@field auto_reload_on_write? boolean Reloads the explorer every time a buffer is written to. Default: `true` ----@field disable_netrw? boolean Completely disable netrw Default: `false` ----@field hijack_cursor? boolean Keeps the cursor on the first letter of the filename when moving in the tree. Default: `false` ----@field hijack_netrw? boolean Hijack netrw windows (overridden if |disable_netrw| is `true`) Default: `true` ----@field hijack_unnamed_buffer_when_opening? boolean Opens in place of the unnamed buffer if it's empty. Default: `false` ----@field prefer_startup_root? boolean Prefer startup root directory when updating root directory of the tree. Only relevant when `update_focused_file.update_root` is `true` Default: `false` @see nvim-tree.update_focused_file.update_root ----@field reload_on_bufenter? boolean Automatically reloads the tree on `BufEnter` nvim-tree. Default: `false` ----@field respect_buf_cwd? boolean Will change cwd of nvim-tree to that of new buffer's when opening nvim-tree. Default: `false` ----@field select_prompts? boolean Use |vim.ui.select| style prompts. Necessary when using a UI prompt decorator such as dressing.nvim or telescope-ui-select.nvim Default: `false` ----@field sync_root_with_cwd? boolean Changes the tree root directory on `DirChanged` and refreshes the tree. Default: `false` ----@field root_dirs? string[] Preferred root directories. Only relevant when `update_focused_file.update_root` is `true` Default: `{}` @see nvim-tree.update_focused_file.update_root ----@field experimental? table Experimental features that may become default or optional functionality. In the event of a problem please disable the experiment and raise an issue. +--- +---Keeps the cursor on the first letter of the filename when moving in the tree. +---(default: `false`) +---@field hijack_cursor? boolean +--- +---Reloads the explorer every time a buffer is written to. +---(default: `true`) +---@field auto_reload_on_write? boolean +--- +---Completely disable |netrw|, see |nvim-tree-netrw| for details. It is strongly advised to eagerly disable netrw, due to race conditions at vim startup. +---(default: `false`) +---@field disable_netrw? boolean +--- +---Hijack netrw windows, ignored when `disable_netrw` is `true` +---(default: `true`) +---@field hijack_netrw? boolean +--- +---Opens in place of the unnamed buffer if it's empty. +---(default: `false`) +---TODO reinstate this one when formatting is done #2934 +-----@field hijack_unnamed_buffer_when_opening? boolean +---@field hubwo? boolean +--- +---Preferred root directories. Only relevant when |nvim_tree.Config.UpdateFocusedFile| `update_root` is `true` +---@field root_dirs? string[] +--- +---Prefer startup root directory when updating root directory of the tree. Only relevant when |nvim_tree.Config.UpdateFocusedFile| `update_root` is `true` +---(default: `false`) +---@field prefer_startup_root? boolean +--- +---Changes the tree root directory on |DirChanged| and refreshes the tree. +---(default: `false`) +---@field sync_root_with_cwd? boolean +--- +---Automatically reloads the tree on |BufEnter| nvim-tree. +---(default: `false`) +---@field reload_on_bufenter? boolean +--- +---Change cwd of nvim-tree to that of new buffer's when opening nvim-tree. +---(default: `false`) +---@field respect_buf_cwd? boolean +--- +---Use |vim.ui.select| style prompts. Necessary when using a UI prompt decorator such as dressing.nvim or telescope-ui-select.nvim +---(default: `false`) +---@field select_prompts? boolean --- ---|nvim_tree.Config.Sort| ---@field sort? nvim_tree.Config.Sort From 86bd8a6d95b613881d33f15c4f827e33089d6dfb Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Mon, 5 Jan 2026 16:48:37 +1100 Subject: [PATCH 010/170] doc(#2934): tidy and format nvim_tree.Config.LiveFilter, Modified, Tab, Trash --- doc/nvim-tree-lua.txt | 62 ++++++++++++++------------- lua/nvim-tree/_meta/config.lua | 78 +++++++++++++++++++++++++++------- 2 files changed, 95 insertions(+), 45 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 3dde18594d0..bf7f91ca3f9 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3799,12 +3799,16 @@ Lua module: nvim_tree *nvim-tree-module* was previously closed. *nvim_tree.Config.LiveFilter* + Configurations for the live_filtering feature. The live filter allows you + to filter the tree nodes dynamically, based on regex matching (see + |vim.regex|). This feature is bound to the `f` key by default. The filter + can be cleared with the `F` key by default. Fields: ~ - • {prefix}? (`string`) Prefix of the filter displayed in - the buffer. Default: `"[FILTER]: "` - • {always_show_folders}? (`boolean`) Whether to filter folders or not. - Default: `true` + • {prefix}? (`string`, default: `[FILTER]: `) Prefix of + the filter displayed in the buffer. + • {always_show_folders}? (`boolean`, default: `true`) Whether to filter + folders or not. *nvim_tree.Config.Log* @@ -3836,17 +3840,19 @@ Lua module: nvim_tree *nvim-tree-module* verbose. Default: `false` *nvim_tree.Config.Modified* + Indicate which file have unsaved modification. To see modified status in + the tree you will need to set: + • |nvim_tree.Config.Renderer.Icons.Show| `modified` to `true` OR + • |nvim_tree.Config.Renderer| `highlight_modified` to `true` Fields: ~ - • {enable}? (`boolean`) Enable / disable the feature. - Default: `false` - • {show_on_dirs}? (`boolean`) Show modified indication on - directory whose children are modified. Default: - `true` - • {show_on_open_dirs}? (`boolean`) Show modified indication on open - directories. Only relevant when - |modified.show_on_dirs| is `true`. Default: - `false` @see nvim-tree.modified.show_on_dirs + • {enable}? (`boolean`, default: `false`) Enable modified. + • {show_on_dirs}? (`boolean`, default: `true`) Show modified + indication on directory whose children are + modified. + • {show_on_open_dirs}? (`boolean`, default: `false`) Show modified + indication on open directories. Only relevant + when `show_on_dirs` is `true`. *nvim_tree.Config.Notify* @@ -4159,30 +4165,28 @@ Lua module: nvim_tree *nvim-tree-module* *nvim_tree.Config.Tab* Fields: ~ - • {sync}? (`nvim_tree.Config.Tab.Sync`) Configuration for syncing - nvim-tree across tabs. + • {sync}? (`nvim_tree.Config.Tab.Sync`) |nvim_tree.Config.Tab.Sync| *nvim_tree.Config.Tab.Sync* + Configuration for syncing nvim-tree across tabs. Fields: ~ - • {open}? (`boolean`) Opens the tree automatically when switching - tabpage or opening a new tabpage if the tree was previously - open. Default: `false` - • {close}? (`boolean`) Closes the tree across all tabpages when the - tree is closed. Default: `false` - • {ignore}? (`string[]`) List of filetypes or buffer names on new tab - that will prevent |nvim-tree.tab.sync.open| and - |nvim-tree.tab.sync.close| Default: `{}` + • {open}? (`boolean`, default: `false`) Opens the tree automatically + when switching tabpage or opening a new tabpage if the tree + was previously open. + • {close}? (`boolean`, default: `false`) Closes the tree across all + tabpages when the tree is closed. + • {ignore}? (`string[]`, default: `{}`) List of filetypes or buffer + names on new tab that will prevent `open` and `close` *nvim_tree.Config.Trash* Fields: ~ - • {cmd}? (`string`) The command used to trash items (must be installed - on your system). Default linux `"gio trash"` from glib2 is a - commonly shipped linux package. macOS default `"trash"` - requires the homebrew package `trash` Windows default - `"trash"` requires `trash-cli` or similar Default: - `"gio trash"` or `"trash"` + • {cmd}? (`string`, default: `gio trash` or `trash`) The command used + to trash items, which must be installed on your system. + • linux: `gio trash`, from linux package `glib2` + • macOS: `trash`, from homebrew package `trash` + • windows: `trash`, requires `trash-cli` or similar *nvim_tree.Config.UI* diff --git a/lua/nvim-tree/_meta/config.lua b/lua/nvim-tree/_meta/config.lua index 89f281e2f78..78c98695815 100644 --- a/lua/nvim-tree/_meta/config.lua +++ b/lua/nvim-tree/_meta/config.lua @@ -26,7 +26,7 @@ error("Cannot require a meta file") --- ---Keeps the cursor on the first letter of the filename when moving in the tree. ---(default: `false`) ----@field hijack_cursor? boolean +---@field hijack_cursor? boolean --- ---Reloads the explorer every time a buffer is written to. ---(default: `true`) @@ -34,11 +34,11 @@ error("Cannot require a meta file") --- ---Completely disable |netrw|, see |nvim-tree-netrw| for details. It is strongly advised to eagerly disable netrw, due to race conditions at vim startup. ---(default: `false`) ----@field disable_netrw? boolean +---@field disable_netrw? boolean --- ---Hijack netrw windows, ignored when `disable_netrw` is `true` ---(default: `true`) ----@field hijack_netrw? boolean +---@field hijack_netrw? boolean --- ---Opens in place of the unnamed buffer if it's empty. ---(default: `false`) @@ -51,7 +51,7 @@ error("Cannot require a meta file") --- ---Prefer startup root directory when updating root directory of the tree. Only relevant when |nvim_tree.Config.UpdateFocusedFile| `update_root` is `true` ---(default: `false`) ----@field prefer_startup_root? boolean +---@field prefer_startup_root? boolean --- ---Changes the tree root directory on |DirChanged| and refreshes the tree. ---(default: `false`) @@ -63,11 +63,11 @@ error("Cannot require a meta file") --- ---Change cwd of nvim-tree to that of new buffer's when opening nvim-tree. ---(default: `false`) ----@field respect_buf_cwd? boolean +---@field respect_buf_cwd? boolean --- ---Use |vim.ui.select| style prompts. Necessary when using a UI prompt decorator such as dressing.nvim or telescope-ui-select.nvim ---(default: `false`) ----@field select_prompts? boolean +---@field select_prompts? boolean --- ---|nvim_tree.Config.Sort| ---@field sort? nvim_tree.Config.Sort @@ -246,37 +246,83 @@ error("Cannot require a meta file") -- Modified -- +---Indicate which file have unsaved modification. +---To see modified status in the tree you will need to set: +--- - |nvim_tree.Config.Renderer.Icons.Show| `modified` to `true` OR +--- - |nvim_tree.Config.Renderer| `highlight_modified` to `true` ---@class nvim_tree.Config.Modified ----@field enable? boolean Enable / disable the feature. Default: `false` ----@field show_on_dirs? boolean Show modified indication on directory whose children are modified. Default: `true` ----@field show_on_open_dirs? boolean Show modified indication on open directories. Only relevant when |modified.show_on_dirs| is `true`. Default: `false` @see nvim-tree.modified.show_on_dirs +--- +---Enable modified. +---(default: `false`) +---@field enable? boolean +--- +---Show modified indication on directory whose children are modified. +---(default: `true`) +---@field show_on_dirs? boolean +--- +---Show modified indication on open directories. Only relevant when `show_on_dirs` is `true`. +---(default: `false`) +---@field show_on_open_dirs? boolean -- -- Tab -- + ---@class nvim_tree.Config.Tab ----@field sync? nvim_tree.Config.Tab.Sync Configuration for syncing nvim-tree across tabs. +--- +---|nvim_tree.Config.Tab.Sync| +---@field sync? nvim_tree.Config.Tab.Sync + +-- +-- Tab.Sync +-- +---Configuration for syncing nvim-tree across tabs. ---@class nvim_tree.Config.Tab.Sync ----@field open? boolean Opens the tree automatically when switching tabpage or opening a new tabpage if the tree was previously open. Default: `false` ----@field close? boolean Closes the tree across all tabpages when the tree is closed. Default: `false` ----@field ignore? string[] List of filetypes or buffer names on new tab that will prevent |nvim-tree.tab.sync.open| and |nvim-tree.tab.sync.close| Default: `{}` +--- +---Opens the tree automatically when switching tabpage or opening a new tabpage if the tree was previously open. +---(default: `false`) +---@field open? boolean +--- +---Closes the tree across all tabpages when the tree is closed. +---(default: `false`) +---@field close? boolean +--- +--- +---List of filetypes or buffer names on new tab that will prevent `open` and `close` +---(default: `{}`) +---@field ignore? string[] -- -- Trash -- ---@class nvim_tree.Config.Trash ----@field cmd? string The command used to trash items (must be installed on your system). Default linux `"gio trash"` from glib2 is a commonly shipped linux package. macOS default `"trash"` requires the homebrew package `trash` Windows default `"trash"` requires `trash-cli` or similar Default: `"gio trash"` or `"trash"` +--- +---The command used to trash items, which must be installed on your system. +--- - linux: `gio trash`, from linux package `glib2` +--- - macOS: `trash`, from homebrew package `trash` +--- - windows: `trash`, requires `trash-cli` or similar +---(default: `gio trash` or `trash`) +---@field cmd? string -- -- Live Filter -- +--- Configurations for the live_filtering feature. The live filter allows you to filter the tree nodes dynamically, based on regex matching (see |vim.regex|). +--- +--- This feature is bound to the `f` key by default. The filter can be cleared with the `F` key by default. ---@class nvim_tree.Config.LiveFilter ----@field prefix? string Prefix of the filter displayed in the buffer. Default: `"[FILTER]: "` ----@field always_show_folders? boolean Whether to filter folders or not. Default: `true` +--- +---Prefix of the filter displayed in the buffer. +---(default: `[FILTER]: `) +---@field prefix? string +--- +---Whether to filter folders or not. +---(default: `true`) +---@field always_show_folders? boolean -- -- System Open From a836f79be89eccc0cba318cc9fb63f13b96703e3 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Mon, 5 Jan 2026 17:31:32 +1100 Subject: [PATCH 011/170] doc(#2934): tidy and format nvim_tree.Config.FilesystemWatchers, Log --- doc/nvim-tree-lua.txt | 82 +++++++++++++++++++--------------- lua/nvim-tree/_meta/config.lua | 74 ++++++++++++++++++++++++------ 2 files changed, 106 insertions(+), 50 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index bf7f91ca3f9..2e1a235efb3 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3695,21 +3695,27 @@ Lua module: nvim_tree *nvim-tree-module* `vim.diagnostic.severity.ERROR` *nvim_tree.Config.FilesystemWatchers* + Use file system watcher (libuv fs_event) to watch the filesystem for + changes. + + Using this will disable |BufEnter| and |BufWritePost| events in nvim-tree + which were used to update the whole tree. + + With this feature, the tree will be updated only for the appropriate + folder change, resulting in better performance. Fields: ~ - • {enable}? (`boolean`) Enable / disable the feature. Default: - `true` - • {debounce_delay}? (`integer`) Idle milliseconds between filesystem - change and action. Default: `50` (ms) - • {ignore_dirs}? (`string[]|fun(path: string): boolean`) List of vim - regex for absolute directory paths that will not be - watched or function returning whether a path should - be ignored. Strings must be backslash escaped e.g. - `"my-proj/\\.build$"`. See |string-match|. Function - is passed an absolute path. Useful when path is not - in `.gitignore` or git integration is disabled. - Default: - `{ "/.ccls-cache", "/build", "/node_modules", "/target", }` + • {enable}? (`boolean`) (default: `true`) + • {debounce_delay}? (`integer`, default: `50`) Idle milliseconds + between filesystem change and action. + • {ignore_dirs}? (`string[]|fun(path: string): boolean`, default: `{ "/.ccls-cache", "/build", "/node_modules", "/target", }`) + List of vim regex for absolute directory paths that + will not be watched or function returning whether a + path should be ignored. Strings must be backslash + escaped e.g. `"my-proj/\\.build$"`. See + |string-match|. Function is passed an absolute + path. Useful when path is not in `.gitignore` or + git integration is disabled. *nvim_tree.Config.Filters* @@ -3801,8 +3807,10 @@ Lua module: nvim_tree *nvim-tree-module* *nvim_tree.Config.LiveFilter* Configurations for the live_filtering feature. The live filter allows you to filter the tree nodes dynamically, based on regex matching (see - |vim.regex|). This feature is bound to the `f` key by default. The filter - can be cleared with the `F` key by default. + |vim.regex|). + + This feature is bound to the `f` key by default. The filter can be cleared + with the `F` key by default. Fields: ~ • {prefix}? (`string`, default: `[FILTER]: `) Prefix of @@ -3811,33 +3819,35 @@ Lua module: nvim_tree *nvim-tree-module* folders or not. *nvim_tree.Config.Log* + Log to a file `nvim-tree.log` in |stdpath|("log"), usually + `${XDG_STATE_HOME}/nvim` Fields: ~ - • {enable}? (`boolean`) Enable logging to a file `nvim-tree.log` in - |stdpath| `"log"`, usually `${XDG_STATE_HOME}/nvim` - Default: `false` - • {truncate}? (`boolean`) Remove existing log file at startup. Default: - `false` - • {types}? (`nvim_tree.Config.Log.Types`) Specify which information - to log. + • {enable}? (`boolean`) (default: `false`) + • {truncate}? (`boolean`, default: `false`) Remove existing log file at + startup. + • {types}? (`nvim_tree.Config.Log.Types`) + |nvim_tree.Config.Log.Types| *nvim_tree.Config.Log.Types* + Specify which information to log. Fields: ~ - • {all}? (`boolean`) Everything. Default: `false` - • {profile}? (`boolean`) Timing of some operations. Default: - `false` - • {config}? (`boolean`) Options and mappings, at startup. Default: - `false` - • {copy_paste}? (`boolean`) File copy and paste actions. Default: - `false` - • {dev}? (`boolean`) Used for local development only. Not - useful for users. Default: `false` - • {diagnostics}? (`boolean`) LSP and COC processing, verbose. Default: - `false` - • {git}? (`boolean`) Git processing, verbose. Default: `false` - • {watcher}? (`boolean`) nvim-tree.filesystem_watchers processing, - verbose. Default: `false` + • {all}? (`boolean`, default: `false`) Everything. + • {profile}? (`boolean`, default: `false`) Timing of some + operations. + • {config}? (`boolean`, default: `false`) Options and mappings, at + startup. + • {copy_paste}? (`boolean`, default: `false`) File copy and paste + actions. + • {dev}? (`boolean`, default: `false`) Used for local + development only. Not useful for users. + • {diagnostics}? (`boolean`, default: `false`) LSP and COC processing, + verbose. + • {git}? (`boolean`, default: `false`) Git processing, verbose. + • {watcher}? (`boolean`, default: `false`) + |nvim_tree.Config.FilesystemWatchers| processing, + verbose. *nvim_tree.Config.Modified* Indicate which file have unsaved modification. To see modified status in diff --git a/lua/nvim-tree/_meta/config.lua b/lua/nvim-tree/_meta/config.lua index 78c98695815..bcc98371b6a 100644 --- a/lua/nvim-tree/_meta/config.lua +++ b/lua/nvim-tree/_meta/config.lua @@ -422,29 +422,75 @@ error("Cannot require a meta file") -- Filesystem Watchers -- +--- Use file system watcher (libuv fs_event) to watch the filesystem for changes. +--- +--- Using this will disable |BufEnter| and |BufWritePost| events in nvim-tree which were used to update the whole tree. +--- +--- With this feature, the tree will be updated only for the appropriate folder change, resulting in better performance. ---@class nvim_tree.Config.FilesystemWatchers ----@field enable? boolean Enable / disable the feature. Default: `true` ----@field debounce_delay? integer Idle milliseconds between filesystem change and action. Default: `50` (ms) ----@field ignore_dirs? string[]|fun(path: string): boolean List of vim regex for absolute directory paths that will not be watched or function returning whether a path should be ignored. Strings must be backslash escaped e.g. `"my-proj/\\.build$"`. See |string-match|. Function is passed an absolute path. Useful when path is not in `.gitignore` or git integration is disabled. Default: `{ "/.ccls-cache", "/build", "/node_modules", "/target", }` +--- +---(default: `true`) +---@field enable? boolean +--- +---Idle milliseconds between filesystem change and action. +---(default: `50`) +---@field debounce_delay? integer +--- +---List of vim regex for absolute directory paths that will not be watched or function returning whether a path should be ignored. Strings must be backslash escaped e.g. `"my-proj/\\.build$"`. See |string-match|. Function is passed an absolute path. Useful when path is not in `.gitignore` or git integration is disabled. +---(default: `{ "/.ccls-cache", "/build", "/node_modules", "/target", }`) +---@field ignore_dirs? string[]|fun(path: string): boolean -- -- Log -- +---Log to a file `nvim-tree.log` in |stdpath|("log"), usually `${XDG_STATE_HOME}/nvim` ---@class nvim_tree.Config.Log ----@field enable? boolean Enable logging to a file `nvim-tree.log` in |stdpath| `"log"`, usually `${XDG_STATE_HOME}/nvim` Default: `false` ----@field truncate? boolean Remove existing log file at startup. Default: `false` ----@field types? nvim_tree.Config.Log.Types Specify which information to log. +--- +---(default: `false`) +---@field enable? boolean +--- +---Remove existing log file at startup. +---(default: `false`) +---@field truncate? boolean +--- +---|nvim_tree.Config.Log.Types| +---@field types? nvim_tree.Config.Log.Types +---Specify which information to log. ---@class nvim_tree.Config.Log.Types ----@field all? boolean Everything. Default: `false` ----@field profile? boolean Timing of some operations. Default: `false` ----@field config? boolean Options and mappings, at startup. Default: `false` ----@field copy_paste? boolean File copy and paste actions. Default: `false` ----@field dev? boolean Used for local development only. Not useful for users. Default: `false` ----@field diagnostics? boolean LSP and COC processing, verbose. Default: `false` ----@field git? boolean Git processing, verbose. Default: `false` ----@field watcher? boolean nvim-tree.filesystem_watchers processing, verbose. Default: `false` +--- +---Everything. +---(default: `false`) +---@field all? boolean +--- +--- Timing of some operations. +---(default: `false`) +---@field profile? boolean +--- +---Options and mappings, at startup. +---(default: `false`) +---@field config? boolean +--- +---File copy and paste actions. +---(default: `false`) +---@field copy_paste? boolean +--- +---Used for local development only. Not useful for users. +---(default: `false`) +---@field dev? boolean +--- +---LSP and COC processing, verbose. +---(default: `false`) +---@field diagnostics? boolean +--- +---Git processing, verbose. +---(default: `false`) +---@field git? boolean +--- +---|nvim_tree.Config.FilesystemWatchers| processing, verbose. +---(default: `false`) +---@field watcher? boolean -- -- UI From b1adfadf0e7fca8568a86ae95fd9579c00853643 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 11:53:34 +1100 Subject: [PATCH 012/170] doc(#2934): split nvim_tree.Config into files, Sort and HijackDirectories populate others placeholder --- doc/nvim-tree-lua.txt | 86 +++++++++++-------- lua/nvim-tree/_meta/config/actions.lua | 2 + lua/nvim-tree/_meta/{ => config}/config.lua | 23 ----- lua/nvim-tree/_meta/config/diagnostics.lua | 2 + .../_meta/config/filesystem_watchers.lua | 2 + lua/nvim-tree/_meta/config/filters.lua | 2 + lua/nvim-tree/_meta/config/git.lua | 3 + lua/nvim-tree/_meta/config/help.lua | 2 + .../_meta/config/hijack_directories.lua | 12 +++ lua/nvim-tree/_meta/config/live_filter.lua | 2 + lua/nvim-tree/_meta/config/log.lua | 2 + lua/nvim-tree/_meta/config/modified.lua | 2 + lua/nvim-tree/_meta/config/notify.lua | 2 + lua/nvim-tree/_meta/config/renderer.lua | 2 + lua/nvim-tree/_meta/config/sort.lua | 8 ++ lua/nvim-tree/_meta/config/system_open.lua | 2 + lua/nvim-tree/_meta/config/tab.lua | 2 + lua/nvim-tree/_meta/config/trash.lua | 2 + lua/nvim-tree/_meta/config/ui.lua | 2 + .../_meta/config/update_focused_file.lua | 2 + lua/nvim-tree/_meta/config/view.lua | 2 + scripts/gen_vimdoc_config.lua | 28 ++++-- 22 files changed, 123 insertions(+), 69 deletions(-) create mode 100644 lua/nvim-tree/_meta/config/actions.lua rename lua/nvim-tree/_meta/{ => config}/config.lua (95%) create mode 100644 lua/nvim-tree/_meta/config/diagnostics.lua create mode 100644 lua/nvim-tree/_meta/config/filesystem_watchers.lua create mode 100644 lua/nvim-tree/_meta/config/filters.lua create mode 100644 lua/nvim-tree/_meta/config/git.lua create mode 100644 lua/nvim-tree/_meta/config/help.lua create mode 100644 lua/nvim-tree/_meta/config/hijack_directories.lua create mode 100644 lua/nvim-tree/_meta/config/live_filter.lua create mode 100644 lua/nvim-tree/_meta/config/log.lua create mode 100644 lua/nvim-tree/_meta/config/modified.lua create mode 100644 lua/nvim-tree/_meta/config/notify.lua create mode 100644 lua/nvim-tree/_meta/config/renderer.lua create mode 100644 lua/nvim-tree/_meta/config/sort.lua create mode 100644 lua/nvim-tree/_meta/config/system_open.lua create mode 100644 lua/nvim-tree/_meta/config/tab.lua create mode 100644 lua/nvim-tree/_meta/config/trash.lua create mode 100644 lua/nvim-tree/_meta/config/ui.lua create mode 100644 lua/nvim-tree/_meta/config/update_focused_file.lua create mode 100644 lua/nvim-tree/_meta/config/view.lua diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 2e1a235efb3..18c94833428 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3459,7 +3459,7 @@ highlight group is not, hard linking as follows: > |nvim-tree-api.tree.winid()| ============================================================================== -Lua module: nvim_tree *nvim-tree-module* +Class: Config *nvim-tree-config* *nvim_tree.Config* @@ -3794,16 +3794,6 @@ Lua module: nvim_tree *nvim-tree-module* alphabetically by keymap) or `"desc"` (sort alphabetically by description). Default: `"key"` -*nvim_tree.Config.HijackDirectories* - - Fields: ~ - • {enable}? (`boolean`, default: `true`) Hijack directory buffers. - Disable this option if you use vim-dirvish or - dirbuf.nvim. If `hijack_netrw` and `disable_netrw` are - `false`, this feature will be disabled. - • {auto_open}? (`boolean`, default: `true`) Opens the tree if the tree - was previously closed. - *nvim_tree.Config.LiveFilter* Configurations for the live_filtering feature. The live filter allows you to filter the tree nodes dynamically, based on regex matching (see @@ -4135,33 +4125,6 @@ Lua module: nvim_tree *nvim-tree-module* • {bottom}? (`string`) Default: `"─"` • {none}? (`string`) Default: `" "` -*nvim_tree.Config.Sort* - - Fields: ~ - • {sorter}? (`nvim_tree.SortOption|fun(nodes: table): nil`) - Changes how files within the same directory are - sorted. Can be one of `"name"`, `"case_sensitive"`, - `"modification_time"`, `"extension"`, `"suffix"`, - `"filetype"` or a function. `"extension"` uses all - suffixes e.g. `foo.tar.gz` -> `.tar.gz` `"suffix"` - uses the last e.g. `.gz` Default: `"name"` Function - may perform a sort or return a string with one of - the above methods. It is passed a table of nodes to - be sorted, each node containing: - `absolute_path`: - `string` - `executable`: `boolean` - `extension`: - `string` - `filetype`: `string` - `link_to`: - `string` - `name`: `string` - `type`: `"directory"` - | `"file"` | `"link"` - • {folders_first}? (`boolean`) Sort folders before files. Has no effect - when |nvim-tree.sort.sorter| is a function. Default: - `true` @see nvim-tree.sort.sorter - • {files_first}? (`boolean`) Sort files before folders. Has no effect - when |nvim-tree.sort.sorter| is a function. If set - to `true` it overrides - |nvim-tree.sort.folders_first|. Default: `false` - @see nvim-tree.sort.sorter @see - nvim-tree.sort.folders_first - *nvim_tree.Config.SystemOpen* Fields: ~ @@ -4312,6 +4275,53 @@ Lua module: nvim_tree *nvim-tree-module* +============================================================================== +Class: Config.Sort *nvim-tree-config-sort* + +*nvim_tree.Config.Sort* + + Fields: ~ + • {sorter}? (`nvim_tree.SortOption|fun(nodes: table): nil`) + Changes how files within the same directory are + sorted. Can be one of `"name"`, `"case_sensitive"`, + `"modification_time"`, `"extension"`, `"suffix"`, + `"filetype"` or a function. `"extension"` uses all + suffixes e.g. `foo.tar.gz` -> `.tar.gz` `"suffix"` + uses the last e.g. `.gz` Default: `"name"` Function + may perform a sort or return a string with one of + the above methods. It is passed a table of nodes to + be sorted, each node containing: - `absolute_path`: + `string` - `executable`: `boolean` - `extension`: + `string` - `filetype`: `string` - `link_to`: + `string` - `name`: `string` - `type`: `"directory"` + | `"file"` | `"link"` + • {folders_first}? (`boolean`) Sort folders before files. Has no effect + when |nvim-tree.sort.sorter| is a function. Default: + `true` @see nvim-tree.sort.sorter + • {files_first}? (`boolean`) Sort files before folders. Has no effect + when |nvim-tree.sort.sorter| is a function. If set + to `true` it overrides + |nvim-tree.sort.folders_first|. Default: `false` + @see nvim-tree.sort.sorter @see + nvim-tree.sort.folders_first + + + +============================================================================== +Class: Config.HijackDirectories *nvim-tree-config-hijack-directories* + +*nvim_tree.Config.HijackDirectories* + + Fields: ~ + • {enable}? (`boolean`, default: `true`) Hijack directory buffers. + Disable this option if you use vim-dirvish or + dirbuf.nvim. If `hijack_netrw` and `disable_netrw` are + `false`, this feature will be disabled. + • {auto_open}? (`boolean`, default: `true`) Opens the tree if the tree + was previously closed. + + + ============================================================================== Lua module: nvim_tree.api *nvim-tree-api* diff --git a/lua/nvim-tree/_meta/config/actions.lua b/lua/nvim-tree/_meta/config/actions.lua new file mode 100644 index 00000000000..e2007a9d9db --- /dev/null +++ b/lua/nvim-tree/_meta/config/actions.lua @@ -0,0 +1,2 @@ +---@meta +error("Cannot require a meta file") diff --git a/lua/nvim-tree/_meta/config.lua b/lua/nvim-tree/_meta/config/config.lua similarity index 95% rename from lua/nvim-tree/_meta/config.lua rename to lua/nvim-tree/_meta/config/config.lua index bcc98371b6a..7195b66c91d 100644 --- a/lua/nvim-tree/_meta/config.lua +++ b/lua/nvim-tree/_meta/config/config.lua @@ -126,20 +126,6 @@ error("Cannot require a meta file") ---|nvim_tree.Config.Log| ---@field log? nvim_tree.Config.Log --- --- HijackDirectories --- - ----@class nvim_tree.Config.HijackDirectories ---- ----Hijack directory buffers. Disable this option if you use vim-dirvish or dirbuf.nvim. If `hijack_netrw` and `disable_netrw` are `false`, this feature will be disabled. ----(default: `true`) ----@field enable? boolean ---- ----Opens the tree if the tree was previously closed. ----(default: `true`) ----@field auto_open? boolean - -- -- Renderer -- @@ -339,15 +325,6 @@ error("Cannot require a meta file") ---@class nvim_tree.Config.Help ---@field sort_by? nvim_tree.HelpSortOption Defines how mappings are sorted in the help window. Can be `"key"` (sort alphabetically by keymap) or `"desc"` (sort alphabetically by description). Default: `"key"` --- --- Sort --- - ----@class nvim_tree.Config.Sort ----@field sorter? nvim_tree.SortOption|fun(nodes: table): nil Changes how files within the same directory are sorted. Can be one of `"name"`, `"case_sensitive"`, `"modification_time"`, `"extension"`, `"suffix"`, `"filetype"` or a function. `"extension"` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz` `"suffix"` uses the last e.g. `.gz` Default: `"name"` Function may perform a sort or return a string with one of the above methods. It is passed a table of nodes to be sorted, each node containing: - `absolute_path`: `string` - `executable`: `boolean` - `extension`: `string` - `filetype`: `string` - `link_to`: `string` - `name`: `string` - `type`: `"directory"` | `"file"` | `"link"` ----@field folders_first? boolean Sort folders before files. Has no effect when |nvim-tree.sort.sorter| is a function. Default: `true` @see nvim-tree.sort.sorter ----@field files_first? boolean Sort files before folders. Has no effect when |nvim-tree.sort.sorter| is a function. If set to `true` it overrides |nvim-tree.sort.folders_first|. Default: `false` @see nvim-tree.sort.sorter @see nvim-tree.sort.folders_first - -- -- Filters -- diff --git a/lua/nvim-tree/_meta/config/diagnostics.lua b/lua/nvim-tree/_meta/config/diagnostics.lua new file mode 100644 index 00000000000..e2007a9d9db --- /dev/null +++ b/lua/nvim-tree/_meta/config/diagnostics.lua @@ -0,0 +1,2 @@ +---@meta +error("Cannot require a meta file") diff --git a/lua/nvim-tree/_meta/config/filesystem_watchers.lua b/lua/nvim-tree/_meta/config/filesystem_watchers.lua new file mode 100644 index 00000000000..e2007a9d9db --- /dev/null +++ b/lua/nvim-tree/_meta/config/filesystem_watchers.lua @@ -0,0 +1,2 @@ +---@meta +error("Cannot require a meta file") diff --git a/lua/nvim-tree/_meta/config/filters.lua b/lua/nvim-tree/_meta/config/filters.lua new file mode 100644 index 00000000000..e2007a9d9db --- /dev/null +++ b/lua/nvim-tree/_meta/config/filters.lua @@ -0,0 +1,2 @@ +---@meta +error("Cannot require a meta file") diff --git a/lua/nvim-tree/_meta/config/git.lua b/lua/nvim-tree/_meta/config/git.lua new file mode 100644 index 00000000000..477a15a72ad --- /dev/null +++ b/lua/nvim-tree/_meta/config/git.lua @@ -0,0 +1,3 @@ +---@meta +error("Cannot require a meta file") + diff --git a/lua/nvim-tree/_meta/config/help.lua b/lua/nvim-tree/_meta/config/help.lua new file mode 100644 index 00000000000..e2007a9d9db --- /dev/null +++ b/lua/nvim-tree/_meta/config/help.lua @@ -0,0 +1,2 @@ +---@meta +error("Cannot require a meta file") diff --git a/lua/nvim-tree/_meta/config/hijack_directories.lua b/lua/nvim-tree/_meta/config/hijack_directories.lua new file mode 100644 index 00000000000..2123d4b78b7 --- /dev/null +++ b/lua/nvim-tree/_meta/config/hijack_directories.lua @@ -0,0 +1,12 @@ +---@meta +error("Cannot require a meta file") + +---@class nvim_tree.Config.HijackDirectories +--- +---Hijack directory buffers. Disable this option if you use vim-dirvish or dirbuf.nvim. If `hijack_netrw` and `disable_netrw` are `false`, this feature will be disabled. +---(default: `true`) +---@field enable? boolean +--- +---Opens the tree if the tree was previously closed. +---(default: `true`) +---@field auto_open? boolean diff --git a/lua/nvim-tree/_meta/config/live_filter.lua b/lua/nvim-tree/_meta/config/live_filter.lua new file mode 100644 index 00000000000..e2007a9d9db --- /dev/null +++ b/lua/nvim-tree/_meta/config/live_filter.lua @@ -0,0 +1,2 @@ +---@meta +error("Cannot require a meta file") diff --git a/lua/nvim-tree/_meta/config/log.lua b/lua/nvim-tree/_meta/config/log.lua new file mode 100644 index 00000000000..e2007a9d9db --- /dev/null +++ b/lua/nvim-tree/_meta/config/log.lua @@ -0,0 +1,2 @@ +---@meta +error("Cannot require a meta file") diff --git a/lua/nvim-tree/_meta/config/modified.lua b/lua/nvim-tree/_meta/config/modified.lua new file mode 100644 index 00000000000..e2007a9d9db --- /dev/null +++ b/lua/nvim-tree/_meta/config/modified.lua @@ -0,0 +1,2 @@ +---@meta +error("Cannot require a meta file") diff --git a/lua/nvim-tree/_meta/config/notify.lua b/lua/nvim-tree/_meta/config/notify.lua new file mode 100644 index 00000000000..e2007a9d9db --- /dev/null +++ b/lua/nvim-tree/_meta/config/notify.lua @@ -0,0 +1,2 @@ +---@meta +error("Cannot require a meta file") diff --git a/lua/nvim-tree/_meta/config/renderer.lua b/lua/nvim-tree/_meta/config/renderer.lua new file mode 100644 index 00000000000..e2007a9d9db --- /dev/null +++ b/lua/nvim-tree/_meta/config/renderer.lua @@ -0,0 +1,2 @@ +---@meta +error("Cannot require a meta file") diff --git a/lua/nvim-tree/_meta/config/sort.lua b/lua/nvim-tree/_meta/config/sort.lua new file mode 100644 index 00000000000..f9f06c547e8 --- /dev/null +++ b/lua/nvim-tree/_meta/config/sort.lua @@ -0,0 +1,8 @@ +---@meta +error("Cannot require a meta file") + +---@class nvim_tree.Config.Sort +---@field sorter? nvim_tree.SortOption|fun(nodes: table): nil Changes how files within the same directory are sorted. Can be one of `"name"`, `"case_sensitive"`, `"modification_time"`, `"extension"`, `"suffix"`, `"filetype"` or a function. `"extension"` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz` `"suffix"` uses the last e.g. `.gz` Default: `"name"` Function may perform a sort or return a string with one of the above methods. It is passed a table of nodes to be sorted, each node containing: - `absolute_path`: `string` - `executable`: `boolean` - `extension`: `string` - `filetype`: `string` - `link_to`: `string` - `name`: `string` - `type`: `"directory"` | `"file"` | `"link"` +---@field folders_first? boolean Sort folders before files. Has no effect when |nvim-tree.sort.sorter| is a function. Default: `true` @see nvim-tree.sort.sorter +---@field files_first? boolean Sort files before folders. Has no effect when |nvim-tree.sort.sorter| is a function. If set to `true` it overrides |nvim-tree.sort.folders_first|. Default: `false` @see nvim-tree.sort.sorter @see nvim-tree.sort.folders_first + diff --git a/lua/nvim-tree/_meta/config/system_open.lua b/lua/nvim-tree/_meta/config/system_open.lua new file mode 100644 index 00000000000..e2007a9d9db --- /dev/null +++ b/lua/nvim-tree/_meta/config/system_open.lua @@ -0,0 +1,2 @@ +---@meta +error("Cannot require a meta file") diff --git a/lua/nvim-tree/_meta/config/tab.lua b/lua/nvim-tree/_meta/config/tab.lua new file mode 100644 index 00000000000..e2007a9d9db --- /dev/null +++ b/lua/nvim-tree/_meta/config/tab.lua @@ -0,0 +1,2 @@ +---@meta +error("Cannot require a meta file") diff --git a/lua/nvim-tree/_meta/config/trash.lua b/lua/nvim-tree/_meta/config/trash.lua new file mode 100644 index 00000000000..e2007a9d9db --- /dev/null +++ b/lua/nvim-tree/_meta/config/trash.lua @@ -0,0 +1,2 @@ +---@meta +error("Cannot require a meta file") diff --git a/lua/nvim-tree/_meta/config/ui.lua b/lua/nvim-tree/_meta/config/ui.lua new file mode 100644 index 00000000000..e2007a9d9db --- /dev/null +++ b/lua/nvim-tree/_meta/config/ui.lua @@ -0,0 +1,2 @@ +---@meta +error("Cannot require a meta file") diff --git a/lua/nvim-tree/_meta/config/update_focused_file.lua b/lua/nvim-tree/_meta/config/update_focused_file.lua new file mode 100644 index 00000000000..e2007a9d9db --- /dev/null +++ b/lua/nvim-tree/_meta/config/update_focused_file.lua @@ -0,0 +1,2 @@ +---@meta +error("Cannot require a meta file") diff --git a/lua/nvim-tree/_meta/config/view.lua b/lua/nvim-tree/_meta/config/view.lua new file mode 100644 index 00000000000..e2007a9d9db --- /dev/null +++ b/lua/nvim-tree/_meta/config/view.lua @@ -0,0 +1,2 @@ +---@meta +error("Cannot require a meta file") diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua index 7fd7fdf3de0..401a1ce2111 100644 --- a/scripts/gen_vimdoc_config.lua +++ b/scripts/gen_vimdoc_config.lua @@ -2,20 +2,32 @@ -- module name is derived as the file name with the first letter capitalised local modules = { - Api = { + Config = { + order = 1, + helptag = "nvim-tree-config", + title = "Class: Config", + path = "lua/nvim-tree/_meta/config/config.lua", + }, + Sort = { order = 2, + helptag = "nvim-tree-config-sort", + title = "Class: Config.Sort", + path = "lua/nvim-tree/_meta/config/sort.lua", + }, + Hijack_directories = { + order = 3, + helptag = "nvim-tree-config-hijack-directories", + title = "Class: Config.HijackDirectories", + path = "lua/nvim-tree/_meta/config/hijack_directories.lua", + }, + Api = { + order = 4, helptag = "nvim-tree-api", title = "Lua module: nvim_tree.api", path = "lua/nvim-tree/_meta/api.lua", }, - Config = { - order = 1, - helptag = "nvim-tree-module", - title = "Lua module: nvim_tree", - path = "lua/nvim-tree/_meta/config.lua", - }, Api_decorator = { - order = 3, + order = 5, helptag = "nvim-tree-api-decorator", title = "Lua module: nvim_tree.api.decorator", path = "lua/nvim-tree/_meta/api_decorator.lua", From 22c1f1b9f8d0d3daa652f617586d2f9114d27904 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 12:45:20 +1100 Subject: [PATCH 013/170] doc(#2934): more generic gen_vimdoc_config module config --- CONTRIBUTING.md | 1 + scripts/gen_vimdoc_config.lua | 106 +++++++++++++++++----------------- 2 files changed, 54 insertions(+), 53 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 07118f01c2d..aa7262123c4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -105,6 +105,7 @@ Suppressions are permitted only in the following cases: - Backwards compatibility shims - neovim API metadata incorrect, awaiting upstream fix - classic class framework +- `gen_vimdoc_config.lua` help generator as it requires neovim source # Backwards Compatibility diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua index 401a1ce2111..70f1758cad7 100644 --- a/scripts/gen_vimdoc_config.lua +++ b/scripts/gen_vimdoc_config.lua @@ -1,70 +1,70 @@ ----@diagnostic disable: undefined-doc-name +---@class (exact) Module +---@field helptag string must be globally unique +---@field title string arbitrary +---@field path string relative to root +---@field file string? generated from path +---@field name string? override generated module name --- module name is derived as the file name with the first letter capitalised +---Generated within help files in this order +---@type Module[] local modules = { - Config = { - order = 1, - helptag = "nvim-tree-config", - title = "Class: Config", - path = "lua/nvim-tree/_meta/config/config.lua", - }, - Sort = { - order = 2, - helptag = "nvim-tree-config-sort", - title = "Class: Config.Sort", - path = "lua/nvim-tree/_meta/config/sort.lua", - }, - Hijack_directories = { - order = 3, - helptag = "nvim-tree-config-hijack-directories", - title = "Class: Config.HijackDirectories", - path = "lua/nvim-tree/_meta/config/hijack_directories.lua", - }, - Api = { - order = 4, - helptag = "nvim-tree-api", - title = "Lua module: nvim_tree.api", - path = "lua/nvim-tree/_meta/api.lua", - }, - Api_decorator = { - order = 5, - helptag = "nvim-tree-api-decorator", - title = "Lua module: nvim_tree.api.decorator", - path = "lua/nvim-tree/_meta/api_decorator.lua", - }, + { helptag = "nvim-tree-config", title = "Class: Config", path = "lua/nvim-tree/_meta/config/config.lua", }, + { helptag = "nvim-tree-config-sort", title = "Class: Config.Sort", path = "lua/nvim-tree/_meta/config/sort.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/view.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/renderer.lua", }, + { helptag = "nvim-tree-config-hijack-directories", title = "Class: Config.HijackDirectories", path = "lua/nvim-tree/_meta/config/hijack_directories.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/update_focused_file.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/system_open.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/git.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/diagnostics.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/modified.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/filters.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/live_filter.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/filesystem_watchers.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/actions.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/trash.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/tab.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/notify.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/help.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/ui.lua", name = "UI", }, + { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/log.lua", }, + + { helptag = "nvim-tree-api", title = "Lua module: nvim_tree.api", path = "lua/nvim-tree/_meta/api.lua", }, + { helptag = "nvim-tree-api-decorator", title = "Lua module: nvim_tree.api.decorator", path = "lua/nvim-tree/_meta/api_decorator.lua", }, } +-- hydrate file names +for _, m in ipairs(modules) do + m.file = vim.fn.fnamemodify(m.path, ":t") +end + +--module name is derived by the generator as the file name with the first letter capitalised +--except for some like UI +---@type table +local modules_by_name = {} +for _, m in ipairs(modules) do + local name = m.name or m.file:gsub(".lua", ""):gsub("^%l", string.upper) + modules_by_name[name] = m +end + +---@diagnostic disable-next-line: undefined-doc-name --- @type table local config = { - decorator = { + all = { filename = "nvim-tree-lua.txt", - -- file name sets order - section_order = (function() - local ret = {} - for _, c in pairs(modules) do - ret[c.order] = vim.fn.fnamemodify(c.path, ":t") - end - return ret - end)(), + -- file is used to set order + section_order = vim.tbl_map(function(m) return m.file end, modules), - -- full path, will be ordered by section_order - files = (function() - local ret = {} - for _, c in pairs(modules) do - table.insert(ret, c.path) - end - return ret - end)(), + -- path + files = vim.tbl_map(function(m) return m.path end, modules), - -- section title section_fmt = function(name) - return modules[name] and modules[name].title or error(string.format("unknown module %s passed to section", name)) + return modules_by_name[name] and modules_by_name[name].title or error(string.format("unknown module %s passed to section_fmt", name)) end, - -- section's help tag helptag_fmt = function(name) - return modules[name] and modules[name].helptag or error(string.format("unknown module %s passed to helptag_fmt", name)) + return modules_by_name[name] and modules_by_name[name].helptag or error(string.format("unknown module %s passed to helptag_fmt", name)) end, -- class/function's help tag From 54dddc38e2c8ac73f0f21ec332e10ac858a304db Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 13:21:45 +1100 Subject: [PATCH 014/170] doc(#2934): tidy Config.HijackDirectories and Actions, move them into place --- doc/nvim-tree-lua.txt | 236 +++++++++--------- lua/nvim-tree/_meta/config/actions.lua | 143 +++++++++++ lua/nvim-tree/_meta/config/config.lua | 143 ----------- lua/nvim-tree/_meta/config/diagnostics.lua | 3 + .../_meta/config/filesystem_watchers.lua | 3 + lua/nvim-tree/_meta/config/filters.lua | 3 + lua/nvim-tree/_meta/config/git.lua | 3 + lua/nvim-tree/_meta/config/help.lua | 3 + .../_meta/config/hijack_directories.lua | 9 +- lua/nvim-tree/_meta/config/live_filter.lua | 3 + lua/nvim-tree/_meta/config/log.lua | 3 + lua/nvim-tree/_meta/config/modified.lua | 3 + lua/nvim-tree/_meta/config/notify.lua | 3 + lua/nvim-tree/_meta/config/renderer.lua | 3 + lua/nvim-tree/_meta/config/sort.lua | 2 + lua/nvim-tree/_meta/config/system_open.lua | 3 + lua/nvim-tree/_meta/config/tab.lua | 3 + lua/nvim-tree/_meta/config/trash.lua | 3 + lua/nvim-tree/_meta/config/ui.lua | 3 + .../_meta/config/update_focused_file.lua | 3 + lua/nvim-tree/_meta/config/view.lua | 3 + scripts/gen_vimdoc_config.lua | 34 +-- 22 files changed, 339 insertions(+), 276 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 18c94833428..e0df13f8184 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3547,114 +3547,6 @@ Class: Config *nvim-tree-config* • {log}? (`nvim_tree.Config.Log`) |nvim_tree.Config.Log| -*nvim_tree.Config.Actions* - - Fields: ~ - • {use_system_clipboard}? (`boolean`, default: `true`) A boolean value - that toggle the use of system clipboard when - copy/paste function are invoked. When - enabled, copied text will be stored in - registers `+` (system), otherwise, it will be - stored in `1` and `"` - • {change_dir}? (`nvim_tree.Config.Actions.ChangeDir`) - |nvim_tree.Config.Actions.ChangeDir| - • {expand_all}? (`nvim_tree.Config.Actions.ExpandAll`) - |nvim_tree.Config.Actions.ExpandAll| - • {file_popup}? (`nvim_tree.Config.Actions.FilePopup`) - |nvim_tree.Config.Actions.FilePopup| - • {open_file}? (`nvim_tree.Config.Actions.OpenFile`) - |nvim_tree.Config.Actions.OpenFile| - • {remove_file}? (`nvim_tree.Config.Actions.RemoveFile`) - |nvim_tree.Config.Actions.RemoveFile| - -*nvim_tree.Config.Actions.ChangeDir* - vim |current-directory| behaviour - - Fields: ~ - • {enable}? (`boolean`, default: `true`) Change the working - directory when changing directories in the tree - • {global}? (`boolean`, default: `false`) Use `:cd` instead - of `:lcd` when changing directories. - • {restrict_above_cwd}? (`boolean`, default: `false`) Restrict changing - to a directory above the global cwd. - -*nvim_tree.Config.Actions.ExpandAll* - Configuration for |nvim-tree-api.tree.expand_all()| and - |nvim-tree-api.node.expand()| - - Fields: ~ - • {max_folder_discovery}? (`integer`, default: `300`) Limit the number - of folders being explored when expanding - every folders. Avoids hanging neovim when - running this action on very large folders. - • {exclude}? (`string[]`, default: `{}`) A list of - directories that should not be expanded - automatically e.g - `{ ".git", "target", "build" }` - -*nvim_tree.Config.Actions.FilePopup* - Configuration for file_popup behaviour. - - Fields: ~ - • {open_win_config}? (`vim.api.keyset.win_config`, default: `{ col = 1, row = 1, relative = "cursor", border = "shadow", style = "minimal", }`) - Floating window config for file_popup. See - |nvim_open_win| and |vim.api.keyset.win_config| - for more details. You shouldn't define `width` and - `height` values here. They will be overridden to - fit the file_popup content. - -*nvim_tree.Config.Actions.OpenFile* - Configuration options for opening a file from nvim-tree. - - Fields: ~ - • {quit_on_open}? (`boolean`, default: `false`) Closes the explorer - when opening a file - • {eject}? (`boolean`, default: `true`) Prevent new opened file - from opening in the same window as the tree. - • {resize_window}? (`boolean`, default: `true`) Resizes the tree when - opening a file - • {window_picker}? (`nvim_tree.Config.Actions.OpenFile.WindowPicker`) - |nvim_tree.Config.Actions.OpenFile.WindowPicker| - -*nvim_tree.Config.Actions.OpenFile.WindowPicker* - Window picker configuration. - - Fields: ~ - • {enable}? (`boolean`, default: `true`) Enable the feature. If the - feature is not enabled, files will open in window from - which you last opened the tree, obeying - |nvim-tree.actions.open_file.window_picker.exclude| - • {picker}? (`string|fun(): integer`, default: `"default"`) Change the - default window picker: a string `"default"` or a function. - The function should return the window id that will open - the node, or `nil` if an invalid window is picked or user - cancelled the action. The picker may create a new window. - • {chars}? (`string`, default: - `"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"`) A string of - chars used as identifiers by the window picker. - • {exclude}? (`nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude`) - |nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude| - -*nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude* - Tables of buffer option names mapped to a list of option values. Windows - containing matching buffers will not be: - • available when using a window picker - • selected when not using a window picker - - Fields: ~ - • {filetype}? (`string[]`) (default: - `{ "notify", "lazy", "qf", "diff", "fugitive", "fugitiveblame", }`) - • {buftype}? (`string[]`) (default: - `{ "nofile", "terminal", "help", }`) - -*nvim_tree.Config.Actions.RemoveFile* - Configuration options for removing a file from nvim-tree. - - Fields: ~ - • {close_window}? (`boolean`, default: `true`) Close any window that - displays a file when removing that file from the - tree. - *nvim_tree.Config.Diagnostics* Fields: ~ @@ -4311,14 +4203,130 @@ Class: Config.Sort *nvim-tree-config-sort* Class: Config.HijackDirectories *nvim-tree-config-hijack-directories* *nvim_tree.Config.HijackDirectories* + Hijack directory buffers by replacing the directory buffer with the tree. + + Disable this option if you use vim-dirvish or dirbuf.nvim. + + If |nvim_tree.Config| {hijack_netrw} and {disable_netrw} are `false` this + feature will be disabled. + + Fields: ~ + • {enable}? (`boolean`) (default: `true`) + • {auto_open}? (`boolean`, default: `true`) Open if the tree was + previously closed. + + + +============================================================================== +Class: Config.Actions *nvim-tree-config-actions* + +*nvim_tree.Config.Actions* + + Fields: ~ + • {use_system_clipboard}? (`boolean`, default: `true`) Use the system + clipboard for copy/paste. Copied text will be + stored in registers `+` (system), otherwise, + it will be stored in `1` and `"` + • {change_dir}? (`nvim_tree.Config.Actions.ChangeDir`) + |nvim_tree.Config.Actions.ChangeDir| + • {expand_all}? (`nvim_tree.Config.Actions.ExpandAll`) + |nvim_tree.Config.Actions.ExpandAll| + • {file_popup}? (`nvim_tree.Config.Actions.FilePopup`) + |nvim_tree.Config.Actions.FilePopup| + • {open_file}? (`nvim_tree.Config.Actions.OpenFile`) + |nvim_tree.Config.Actions.OpenFile| + • {remove_file}? (`nvim_tree.Config.Actions.RemoveFile`) + |nvim_tree.Config.Actions.RemoveFile| + +*nvim_tree.Config.Actions.ChangeDir* + vim |current-directory| behaviour + + Fields: ~ + • {enable}? (`boolean`, default: `true`) Change the working + directory when changing directories in the tree + • {global}? (`boolean`, default: `false`) Use `:cd` instead + of `:lcd` when changing directories. + • {restrict_above_cwd}? (`boolean`, default: `false`) Restrict changing + to a directory above the global cwd. + +*nvim_tree.Config.Actions.ExpandAll* + Configuration for |nvim-tree-api.tree.expand_all()| and + |nvim-tree-api.node.expand()| + + Fields: ~ + • {max_folder_discovery}? (`integer`, default: `300`) Limit the number + of folders being explored when expanding + every folders. Avoids hanging neovim when + running this action on very large folders. + • {exclude}? (`string[]`, default: `{}`) A list of + directories that should not be expanded + automatically e.g + `{ ".git", "target", "build" }` + +*nvim_tree.Config.Actions.FilePopup* + Configuration for file_popup floating window, see |nvim_open_win| + + You shouldn't define |vim.api.keyset.win_config| {width} and {height} + values here. They will be overridden to fit the file_popup content. Fields: ~ - • {enable}? (`boolean`, default: `true`) Hijack directory buffers. - Disable this option if you use vim-dirvish or - dirbuf.nvim. If `hijack_netrw` and `disable_netrw` are - `false`, this feature will be disabled. - • {auto_open}? (`boolean`, default: `true`) Opens the tree if the tree - was previously closed. + • {open_win_config}? (`vim.api.keyset.win_config`, default: `{ col = 1, row = 1, relative = "cursor", border = "shadow", style = "minimal", }`) + Neovim window config. + +*nvim_tree.Config.Actions.OpenFile* + Configuration options for opening a file from nvim-tree. + + Fields: ~ + • {quit_on_open}? (`boolean`, default: `false`) Closes the explorer + when opening a file + • {eject}? (`boolean`, default: `true`) Prevent new opened file + from opening in the same window as the tree. + • {resize_window}? (`boolean`, default: `true`) Resizes the tree when + opening a file + • {window_picker}? (`nvim_tree.Config.Actions.OpenFile.WindowPicker`) + |nvim_tree.Config.Actions.OpenFile.WindowPicker| + +*nvim_tree.Config.Actions.OpenFile.WindowPicker* + A window picker will be shown when there are multiple windows available to + open a file. It will show a single character identifier in each window's + status line. + + When it is not enabled the file will open in the window from which you + last opened the tree, obeying {exclude} + + You may define a function that should return the window id that will open + the node, or `nil` if an invalid window is picked or user cancelled the + action. The picker may create a new window. + + Fields: ~ + • {enable}? (`boolean`) (default: `true`) + • {picker}? (`string|fun(): integer`, default: `"default"`) Change the + default window picker: a string `"default"` or a function. + • {chars}? (`string`, default: + `"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"`) Identifier + characters to use. + • {exclude}? (`nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude`) + |nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude| + +*nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude* + Tables of buffer option names mapped to a list of option values. Windows + containing matching buffers will not be: + • available when using a window picker + • selected when not using a window picker + + Fields: ~ + • {filetype}? (`string[]`) (default: + `{ "notify", "lazy", "qf", "diff", "fugitive", "fugitiveblame", }`) + • {buftype}? (`string[]`) (default: + `{ "nofile", "terminal", "help", }`) + +*nvim_tree.Config.Actions.RemoveFile* + Configuration options for removing a file from nvim-tree. + + Fields: ~ + • {close_window}? (`boolean`, default: `true`) Close any window that + displays a file when removing that file from the + tree. diff --git a/lua/nvim-tree/_meta/config/actions.lua b/lua/nvim-tree/_meta/config/actions.lua index e2007a9d9db..d2de25b7e59 100644 --- a/lua/nvim-tree/_meta/config/actions.lua +++ b/lua/nvim-tree/_meta/config/actions.lua @@ -1,2 +1,145 @@ ---@meta error("Cannot require a meta file") + +---@class nvim_tree.Config.Actions +--- +---Use the system clipboard for copy/paste. Copied text will be stored in registers `+` (system), otherwise, it will be stored in `1` and `"` +---(default: `true`) +---@field use_system_clipboard? boolean +--- +---|nvim_tree.Config.Actions.ChangeDir| +---@field change_dir? nvim_tree.Config.Actions.ChangeDir +--- +---|nvim_tree.Config.Actions.ExpandAll| +---@field expand_all? nvim_tree.Config.Actions.ExpandAll +--- +---|nvim_tree.Config.Actions.FilePopup| +---@field file_popup? nvim_tree.Config.Actions.FilePopup +--- +---|nvim_tree.Config.Actions.OpenFile| +---@field open_file? nvim_tree.Config.Actions.OpenFile +--- +---|nvim_tree.Config.Actions.RemoveFile| +---@field remove_file? nvim_tree.Config.Actions.RemoveFile + +-- +-- Actions.ChangeDir +-- + +--- vim |current-directory| behaviour +---@class nvim_tree.Config.Actions.ChangeDir +--- +---Change the working directory when changing directories in the tree +---(default: `true`) +---@field enable? boolean +--- +---Use `:cd` instead of `:lcd` when changing directories. +---(default: `false`) +---@field global? boolean +--- +--- Restrict changing to a directory above the global cwd. +---(default: `false`) +---@field restrict_above_cwd? boolean + +-- +-- Actions.ExpandAll +-- + +---Configuration for |nvim-tree-api.tree.expand_all()| and |nvim-tree-api.node.expand()| +---@class nvim_tree.Config.Actions.ExpandAll +--- +---Limit the number of folders being explored when expanding every folders. Avoids hanging neovim when running this action on very large folders. +---(default: `300`) +---@field max_folder_discovery? integer +--- +---A list of directories that should not be expanded automatically e.g `{ ".git", "target", "build" }` +---(default: `{}`) +---@field exclude? string[] + +-- +-- Actions.FilePopup +-- + +---Configuration for file_popup floating window, see |nvim_open_win| +--- +---You shouldn't define |vim.api.keyset.win_config| {width} and {height} values here. They will be overridden to fit the file_popup content. +---@class nvim_tree.Config.Actions.FilePopup +--- +---Neovim window config. +---(default: `{ col = 1, row = 1, relative = "cursor", border = "shadow", style = "minimal", }`) +---@field open_win_config? vim.api.keyset.win_config + +-- +-- Actions.OpenFile +-- + +---Configuration options for opening a file from nvim-tree. +---@class nvim_tree.Config.Actions.OpenFile +--- +---Closes the explorer when opening a file +---(default: `false`) +---@field quit_on_open? boolean +--- +---Prevent new opened file from opening in the same window as the tree. +---(default: `true`) +---@field eject? boolean +--- +---Resizes the tree when opening a file +---(default: `true`) +---@field resize_window? boolean +--- +---|nvim_tree.Config.Actions.OpenFile.WindowPicker| +---@field window_picker? nvim_tree.Config.Actions.OpenFile.WindowPicker + +-- +-- Actions.OpenFile.WindowPicker +-- + +---A window picker will be shown when there are multiple windows available to open a file. It will show a single character identifier in each window's status line. +--- +---When it is not enabled the file will open in the window from which you last opened the tree, obeying {exclude} +--- +---You may define a function that should return the window id that will open the node, or `nil` if an invalid window is picked or user cancelled the action. The picker may create a new window. +--- +---@class nvim_tree.Config.Actions.OpenFile.WindowPicker +--- +---(default: `true`) +---@field enable? boolean +--- +---Change the default window picker: a string `"default"` or a function. +---(default: `"default"`) +---@field picker? string|fun(): integer +--- +---Identifier characters to use. +---(default: `"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"`) +---@field chars? string +--- +---|nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude| +---@field exclude? nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude + +-- +-- Actions.OpenFile.WindowPicker.Exclude +-- + +---Tables of buffer option names mapped to a list of option values. Windows containing matching buffers will not be: +--- - available when using a window picker +--- - selected when not using a window picker +---@class nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude +--- +---(default: `{ "notify", "lazy", "qf", "diff", "fugitive", "fugitiveblame", }`) +---@field filetype? string[] +--- +---(default: `{ "nofile", "terminal", "help", }`) +---@field buftype? string[] + +-- +-- Actions.RemoveFile +-- + +---Configuration options for removing a file from nvim-tree. +---@class nvim_tree.Config.Actions.RemoveFile +--- +---Close any window that displays a file when removing that file from the tree. +---(default: `true`) +---@field close_window? boolean + diff --git a/lua/nvim-tree/_meta/config/config.lua b/lua/nvim-tree/_meta/config/config.lua index 7195b66c91d..8dd597e0cf5 100644 --- a/lua/nvim-tree/_meta/config/config.lua +++ b/lua/nvim-tree/_meta/config/config.lua @@ -1,10 +1,6 @@ ---@meta error("Cannot require a meta file") --- The nvim_tree global namespace exists at runtime but cannot be declared in meta files. --- This suppression allows referencing the namespace for type definitions. ----@diagnostic disable: undefined-global - -- -- Type Aliases for Enums -- @@ -497,145 +493,6 @@ error("Cannot require a meta file") ---(default: `false`) ---@field default_yes? boolean --- --- Actions --- - ----@class nvim_tree.Config.Actions ---- ----A boolean value that toggle the use of system clipboard when copy/paste function are invoked. When enabled, copied text will be stored in registers `+` (system), otherwise, it will be stored in `1` and `"` ----(default: `true`) ----@field use_system_clipboard? boolean ---- ----|nvim_tree.Config.Actions.ChangeDir| ----@field change_dir? nvim_tree.Config.Actions.ChangeDir ---- ----|nvim_tree.Config.Actions.ExpandAll| ----@field expand_all? nvim_tree.Config.Actions.ExpandAll ---- ----|nvim_tree.Config.Actions.FilePopup| ----@field file_popup? nvim_tree.Config.Actions.FilePopup ---- ----|nvim_tree.Config.Actions.OpenFile| ----@field open_file? nvim_tree.Config.Actions.OpenFile ---- ----|nvim_tree.Config.Actions.RemoveFile| ----@field remove_file? nvim_tree.Config.Actions.RemoveFile - --- --- Actions.ChangeDir --- - ---- vim |current-directory| behaviour ----@class nvim_tree.Config.Actions.ChangeDir ---- ----Change the working directory when changing directories in the tree ----(default: `true`) ----@field enable? boolean ---- ----Use `:cd` instead of `:lcd` when changing directories. ----(default: `false`) ----@field global? boolean ---- ---- Restrict changing to a directory above the global cwd. ----(default: `false`) ----@field restrict_above_cwd? boolean - --- --- Actions.ExpandAll --- - ----Configuration for |nvim-tree-api.tree.expand_all()| and |nvim-tree-api.node.expand()| ----@class nvim_tree.Config.Actions.ExpandAll ---- ----Limit the number of folders being explored when expanding every folders. Avoids hanging neovim when running this action on very large folders. ----(default: `300`) ----@field max_folder_discovery? integer ---- ----A list of directories that should not be expanded automatically e.g `{ ".git", "target", "build" }` ----(default: `{}`) ----@field exclude? string[] - --- --- Actions.FilePopup --- - ----Configuration for file_popup behaviour. ----@class nvim_tree.Config.Actions.FilePopup ---- ----Floating window config for file_popup. See |nvim_open_win| and |vim.api.keyset.win_config| for more details. You shouldn't define `width` and `height` values here. They will be overridden to fit the file_popup content. ----(default: `{ col = 1, row = 1, relative = "cursor", border = "shadow", style = "minimal", }`) ----@field open_win_config? vim.api.keyset.win_config - --- --- Actions.OpenFile --- - ----Configuration options for opening a file from nvim-tree. ----@class nvim_tree.Config.Actions.OpenFile ---- ----Closes the explorer when opening a file ----(default: `false`) ----@field quit_on_open? boolean ---- ----Prevent new opened file from opening in the same window as the tree. ----(default: `true`) ----@field eject? boolean ---- ----Resizes the tree when opening a file ----(default: `true`) ----@field resize_window? boolean ---- ----|nvim_tree.Config.Actions.OpenFile.WindowPicker| ----@field window_picker? nvim_tree.Config.Actions.OpenFile.WindowPicker - --- --- Actions.OpenFile.WindowPicker --- - ----Window picker configuration. ----@class nvim_tree.Config.Actions.OpenFile.WindowPicker ---- ----Enable the feature. If the feature is not enabled, files will open in window from which you last opened the tree, obeying |nvim-tree.actions.open_file.window_picker.exclude| ----(default: `true`) ----@field enable? boolean ---- ----Change the default window picker: a string `"default"` or a function. The function should return the window id that will open the node, or `nil` if an invalid window is picked or user cancelled the action. The picker may create a new window. ----(default: `"default"`) ----@field picker? string|fun(): integer ---- ----A string of chars used as identifiers by the window picker. ----(default: `"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"`) ----@field chars? string ---- ----|nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude| ----@field exclude? nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude - --- --- Actions.OpenFile.WindowPicker.Exclude --- - ----Tables of buffer option names mapped to a list of option values. Windows containing matching buffers will not be: ---- - available when using a window picker ---- - selected when not using a window picker ----@class nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude ---- ----(default: `{ "notify", "lazy", "qf", "diff", "fugitive", "fugitiveblame", }`) ----@field filetype? string[] ---- ----(default: `{ "nofile", "terminal", "help", }`) ----@field buftype? string[] - --- --- Actions.RemoveFile --- - ----Configuration options for removing a file from nvim-tree. ----@class nvim_tree.Config.Actions.RemoveFile ---- ----Close any window that displays a file when removing that file from the tree. ----(default: `true`) ----@field close_window? boolean -- -- View diff --git a/lua/nvim-tree/_meta/config/diagnostics.lua b/lua/nvim-tree/_meta/config/diagnostics.lua index e2007a9d9db..1b49a5e42fd 100644 --- a/lua/nvim-tree/_meta/config/diagnostics.lua +++ b/lua/nvim-tree/_meta/config/diagnostics.lua @@ -1,2 +1,5 @@ ---@meta error("Cannot require a meta file") + +--- TODO #2934 + diff --git a/lua/nvim-tree/_meta/config/filesystem_watchers.lua b/lua/nvim-tree/_meta/config/filesystem_watchers.lua index e2007a9d9db..1b49a5e42fd 100644 --- a/lua/nvim-tree/_meta/config/filesystem_watchers.lua +++ b/lua/nvim-tree/_meta/config/filesystem_watchers.lua @@ -1,2 +1,5 @@ ---@meta error("Cannot require a meta file") + +--- TODO #2934 + diff --git a/lua/nvim-tree/_meta/config/filters.lua b/lua/nvim-tree/_meta/config/filters.lua index e2007a9d9db..1b49a5e42fd 100644 --- a/lua/nvim-tree/_meta/config/filters.lua +++ b/lua/nvim-tree/_meta/config/filters.lua @@ -1,2 +1,5 @@ ---@meta error("Cannot require a meta file") + +--- TODO #2934 + diff --git a/lua/nvim-tree/_meta/config/git.lua b/lua/nvim-tree/_meta/config/git.lua index 477a15a72ad..f0338f57686 100644 --- a/lua/nvim-tree/_meta/config/git.lua +++ b/lua/nvim-tree/_meta/config/git.lua @@ -1,3 +1,6 @@ ---@meta error("Cannot require a meta file") + +--- TODO #2934 + diff --git a/lua/nvim-tree/_meta/config/help.lua b/lua/nvim-tree/_meta/config/help.lua index e2007a9d9db..1b49a5e42fd 100644 --- a/lua/nvim-tree/_meta/config/help.lua +++ b/lua/nvim-tree/_meta/config/help.lua @@ -1,2 +1,5 @@ ---@meta error("Cannot require a meta file") + +--- TODO #2934 + diff --git a/lua/nvim-tree/_meta/config/hijack_directories.lua b/lua/nvim-tree/_meta/config/hijack_directories.lua index 2123d4b78b7..ce2f3fb8432 100644 --- a/lua/nvim-tree/_meta/config/hijack_directories.lua +++ b/lua/nvim-tree/_meta/config/hijack_directories.lua @@ -1,12 +1,17 @@ ---@meta error("Cannot require a meta file") + +---Hijack directory buffers by replacing the directory buffer with the tree. +--- +---Disable this option if you use vim-dirvish or dirbuf.nvim. +--- +---If |nvim_tree.Config| {hijack_netrw} and {disable_netrw} are `false` this feature will be disabled. ---@class nvim_tree.Config.HijackDirectories --- ----Hijack directory buffers. Disable this option if you use vim-dirvish or dirbuf.nvim. If `hijack_netrw` and `disable_netrw` are `false`, this feature will be disabled. ---(default: `true`) ---@field enable? boolean --- ----Opens the tree if the tree was previously closed. +---Open if the tree was previously closed. ---(default: `true`) ---@field auto_open? boolean diff --git a/lua/nvim-tree/_meta/config/live_filter.lua b/lua/nvim-tree/_meta/config/live_filter.lua index e2007a9d9db..1b49a5e42fd 100644 --- a/lua/nvim-tree/_meta/config/live_filter.lua +++ b/lua/nvim-tree/_meta/config/live_filter.lua @@ -1,2 +1,5 @@ ---@meta error("Cannot require a meta file") + +--- TODO #2934 + diff --git a/lua/nvim-tree/_meta/config/log.lua b/lua/nvim-tree/_meta/config/log.lua index e2007a9d9db..1b49a5e42fd 100644 --- a/lua/nvim-tree/_meta/config/log.lua +++ b/lua/nvim-tree/_meta/config/log.lua @@ -1,2 +1,5 @@ ---@meta error("Cannot require a meta file") + +--- TODO #2934 + diff --git a/lua/nvim-tree/_meta/config/modified.lua b/lua/nvim-tree/_meta/config/modified.lua index e2007a9d9db..1b49a5e42fd 100644 --- a/lua/nvim-tree/_meta/config/modified.lua +++ b/lua/nvim-tree/_meta/config/modified.lua @@ -1,2 +1,5 @@ ---@meta error("Cannot require a meta file") + +--- TODO #2934 + diff --git a/lua/nvim-tree/_meta/config/notify.lua b/lua/nvim-tree/_meta/config/notify.lua index e2007a9d9db..1b49a5e42fd 100644 --- a/lua/nvim-tree/_meta/config/notify.lua +++ b/lua/nvim-tree/_meta/config/notify.lua @@ -1,2 +1,5 @@ ---@meta error("Cannot require a meta file") + +--- TODO #2934 + diff --git a/lua/nvim-tree/_meta/config/renderer.lua b/lua/nvim-tree/_meta/config/renderer.lua index e2007a9d9db..1b49a5e42fd 100644 --- a/lua/nvim-tree/_meta/config/renderer.lua +++ b/lua/nvim-tree/_meta/config/renderer.lua @@ -1,2 +1,5 @@ ---@meta error("Cannot require a meta file") + +--- TODO #2934 + diff --git a/lua/nvim-tree/_meta/config/sort.lua b/lua/nvim-tree/_meta/config/sort.lua index f9f06c547e8..2407add766c 100644 --- a/lua/nvim-tree/_meta/config/sort.lua +++ b/lua/nvim-tree/_meta/config/sort.lua @@ -1,6 +1,8 @@ ---@meta error("Cannot require a meta file") +--- TODO #2934 + ---@class nvim_tree.Config.Sort ---@field sorter? nvim_tree.SortOption|fun(nodes: table): nil Changes how files within the same directory are sorted. Can be one of `"name"`, `"case_sensitive"`, `"modification_time"`, `"extension"`, `"suffix"`, `"filetype"` or a function. `"extension"` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz` `"suffix"` uses the last e.g. `.gz` Default: `"name"` Function may perform a sort or return a string with one of the above methods. It is passed a table of nodes to be sorted, each node containing: - `absolute_path`: `string` - `executable`: `boolean` - `extension`: `string` - `filetype`: `string` - `link_to`: `string` - `name`: `string` - `type`: `"directory"` | `"file"` | `"link"` ---@field folders_first? boolean Sort folders before files. Has no effect when |nvim-tree.sort.sorter| is a function. Default: `true` @see nvim-tree.sort.sorter diff --git a/lua/nvim-tree/_meta/config/system_open.lua b/lua/nvim-tree/_meta/config/system_open.lua index e2007a9d9db..1b49a5e42fd 100644 --- a/lua/nvim-tree/_meta/config/system_open.lua +++ b/lua/nvim-tree/_meta/config/system_open.lua @@ -1,2 +1,5 @@ ---@meta error("Cannot require a meta file") + +--- TODO #2934 + diff --git a/lua/nvim-tree/_meta/config/tab.lua b/lua/nvim-tree/_meta/config/tab.lua index e2007a9d9db..1b49a5e42fd 100644 --- a/lua/nvim-tree/_meta/config/tab.lua +++ b/lua/nvim-tree/_meta/config/tab.lua @@ -1,2 +1,5 @@ ---@meta error("Cannot require a meta file") + +--- TODO #2934 + diff --git a/lua/nvim-tree/_meta/config/trash.lua b/lua/nvim-tree/_meta/config/trash.lua index e2007a9d9db..1b49a5e42fd 100644 --- a/lua/nvim-tree/_meta/config/trash.lua +++ b/lua/nvim-tree/_meta/config/trash.lua @@ -1,2 +1,5 @@ ---@meta error("Cannot require a meta file") + +--- TODO #2934 + diff --git a/lua/nvim-tree/_meta/config/ui.lua b/lua/nvim-tree/_meta/config/ui.lua index e2007a9d9db..1b49a5e42fd 100644 --- a/lua/nvim-tree/_meta/config/ui.lua +++ b/lua/nvim-tree/_meta/config/ui.lua @@ -1,2 +1,5 @@ ---@meta error("Cannot require a meta file") + +--- TODO #2934 + diff --git a/lua/nvim-tree/_meta/config/update_focused_file.lua b/lua/nvim-tree/_meta/config/update_focused_file.lua index e2007a9d9db..1b49a5e42fd 100644 --- a/lua/nvim-tree/_meta/config/update_focused_file.lua +++ b/lua/nvim-tree/_meta/config/update_focused_file.lua @@ -1,2 +1,5 @@ ---@meta error("Cannot require a meta file") + +--- TODO #2934 + diff --git a/lua/nvim-tree/_meta/config/view.lua b/lua/nvim-tree/_meta/config/view.lua index e2007a9d9db..1b49a5e42fd 100644 --- a/lua/nvim-tree/_meta/config/view.lua +++ b/lua/nvim-tree/_meta/config/view.lua @@ -1,2 +1,5 @@ ---@meta error("Cannot require a meta file") + +--- TODO #2934 + diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua index 70f1758cad7..27c7a7c6eac 100644 --- a/scripts/gen_vimdoc_config.lua +++ b/scripts/gen_vimdoc_config.lua @@ -10,24 +10,24 @@ local modules = { { helptag = "nvim-tree-config", title = "Class: Config", path = "lua/nvim-tree/_meta/config/config.lua", }, { helptag = "nvim-tree-config-sort", title = "Class: Config.Sort", path = "lua/nvim-tree/_meta/config/sort.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/view.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/renderer.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/view.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/renderer.lua", }, { helptag = "nvim-tree-config-hijack-directories", title = "Class: Config.HijackDirectories", path = "lua/nvim-tree/_meta/config/hijack_directories.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/update_focused_file.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/system_open.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/git.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/diagnostics.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/modified.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/filters.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/live_filter.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/filesystem_watchers.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/actions.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/trash.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/tab.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/notify.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/help.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/ui.lua", name = "UI", }, - { helptag = "nvim-tree-config-YYY", title = "Class: XXX", path = "lua/nvim-tree/_meta/config/log.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/update_focused_file.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/system_open.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/git.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/diagnostics.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/modified.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/filters.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/live_filter.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/filesystem_watchers.lua", }, + { helptag = "nvim-tree-config-actions", title = "Class: Config.Actions", path = "lua/nvim-tree/_meta/config/actions.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/trash.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/tab.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/notify.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/help.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/ui.lua", name = "UI", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/log.lua", }, { helptag = "nvim-tree-api", title = "Lua module: nvim_tree.api", path = "lua/nvim-tree/_meta/api.lua", }, { helptag = "nvim-tree-api-decorator", title = "Lua module: nvim_tree.api.decorator", path = "lua/nvim-tree/_meta/api_decorator.lua", }, From 8f1f516836d8d4119d526d81859faeee92d2f9e6 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 13:26:52 +1100 Subject: [PATCH 015/170] doc(#2934): tidy Config.Modified, move into place --- doc/nvim-tree-lua.txt | 35 ++++++++++++++----------- lua/nvim-tree/_meta/config/config.lua | 17 ------------ lua/nvim-tree/_meta/config/modified.lua | 18 +++++++++++-- scripts/gen_vimdoc_config.lua | 2 +- 4 files changed, 37 insertions(+), 35 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index e0df13f8184..1927544af46 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3731,21 +3731,6 @@ Class: Config *nvim-tree-config* |nvim_tree.Config.FilesystemWatchers| processing, verbose. -*nvim_tree.Config.Modified* - Indicate which file have unsaved modification. To see modified status in - the tree you will need to set: - • |nvim_tree.Config.Renderer.Icons.Show| `modified` to `true` OR - • |nvim_tree.Config.Renderer| `highlight_modified` to `true` - - Fields: ~ - • {enable}? (`boolean`, default: `false`) Enable modified. - • {show_on_dirs}? (`boolean`, default: `true`) Show modified - indication on directory whose children are - modified. - • {show_on_open_dirs}? (`boolean`, default: `false`) Show modified - indication on open directories. Only relevant - when `show_on_dirs` is `true`. - *nvim_tree.Config.Notify* Fields: ~ @@ -4217,6 +4202,26 @@ Class: Config.HijackDirectories *nvim-tree-config-hijack-directories* +============================================================================== +Class: Config.Modified *nvim-tree-config-modified* + +*nvim_tree.Config.Modified* + Indicate which file have unsaved modification. To see modified status in + the tree you will need to set: + • |nvim_tree.Config.Renderer.Icons.Show| {modified} to `true` OR + • |nvim_tree.Config.Renderer| {highlight_modified} to `true` + + Fields: ~ + • {enable}? (`boolean`) (default: `false`) + • {show_on_dirs}? (`boolean`, default: `true`) Show modified + indication on directory whose children are + modified. + • {show_on_open_dirs}? (`boolean`, default: `false`) Show modified + indication on open directories. Only relevant + when {show_on_dirs} is `true`. + + + ============================================================================== Class: Config.Actions *nvim-tree-config-actions* diff --git a/lua/nvim-tree/_meta/config/config.lua b/lua/nvim-tree/_meta/config/config.lua index 8dd597e0cf5..b0eabb398d2 100644 --- a/lua/nvim-tree/_meta/config/config.lua +++ b/lua/nvim-tree/_meta/config/config.lua @@ -228,23 +228,6 @@ error("Cannot require a meta file") -- Modified -- ----Indicate which file have unsaved modification. ----To see modified status in the tree you will need to set: ---- - |nvim_tree.Config.Renderer.Icons.Show| `modified` to `true` OR ---- - |nvim_tree.Config.Renderer| `highlight_modified` to `true` ----@class nvim_tree.Config.Modified ---- ----Enable modified. ----(default: `false`) ----@field enable? boolean ---- ----Show modified indication on directory whose children are modified. ----(default: `true`) ----@field show_on_dirs? boolean ---- ----Show modified indication on open directories. Only relevant when `show_on_dirs` is `true`. ----(default: `false`) ----@field show_on_open_dirs? boolean -- -- Tab diff --git a/lua/nvim-tree/_meta/config/modified.lua b/lua/nvim-tree/_meta/config/modified.lua index 1b49a5e42fd..0a04fffc922 100644 --- a/lua/nvim-tree/_meta/config/modified.lua +++ b/lua/nvim-tree/_meta/config/modified.lua @@ -1,5 +1,19 @@ ---@meta error("Cannot require a meta file") ---- TODO #2934 - +---Indicate which file have unsaved modification. +---To see modified status in the tree you will need to set: +--- - |nvim_tree.Config.Renderer.Icons.Show| {modified} to `true` OR +--- - |nvim_tree.Config.Renderer| {highlight_modified} to `true` +---@class nvim_tree.Config.Modified +--- +---(default: `false`) +---@field enable? boolean +--- +---Show modified indication on directory whose children are modified. +---(default: `true`) +---@field show_on_dirs? boolean +--- +---Show modified indication on open directories. Only relevant when {show_on_dirs} is `true`. +---(default: `false`) +---@field show_on_open_dirs? boolean diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua index 27c7a7c6eac..380dd769a23 100644 --- a/scripts/gen_vimdoc_config.lua +++ b/scripts/gen_vimdoc_config.lua @@ -17,7 +17,7 @@ local modules = { { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/system_open.lua", }, { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/git.lua", }, { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/diagnostics.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/modified.lua", }, + { helptag = "nvim-tree-config-modified", title = "Class: Config.Modified", path = "lua/nvim-tree/_meta/config/modified.lua", }, { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/filters.lua", }, { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/live_filter.lua", }, { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/filesystem_watchers.lua", }, From b59183a35d7ce023002fb5acdf546fb1b9fa57ca Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 13:28:41 +1100 Subject: [PATCH 016/170] doc(#2934): tidy Config.LiveFilter, move into place --- doc/nvim-tree-lua.txt | 32 ++++++++++++---------- lua/nvim-tree/_meta/config/config.lua | 17 ------------ lua/nvim-tree/_meta/config/live_filter.lua | 13 ++++++++- scripts/gen_vimdoc_config.lua | 2 +- 4 files changed, 31 insertions(+), 33 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 1927544af46..c4a0bf6090e 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3686,20 +3686,6 @@ Class: Config *nvim-tree-config* alphabetically by keymap) or `"desc"` (sort alphabetically by description). Default: `"key"` -*nvim_tree.Config.LiveFilter* - Configurations for the live_filtering feature. The live filter allows you - to filter the tree nodes dynamically, based on regex matching (see - |vim.regex|). - - This feature is bound to the `f` key by default. The filter can be cleared - with the `F` key by default. - - Fields: ~ - • {prefix}? (`string`, default: `[FILTER]: `) Prefix of - the filter displayed in the buffer. - • {always_show_folders}? (`boolean`, default: `true`) Whether to filter - folders or not. - *nvim_tree.Config.Log* Log to a file `nvim-tree.log` in |stdpath|("log"), usually `${XDG_STATE_HOME}/nvim` @@ -4222,6 +4208,24 @@ Class: Config.Modified *nvim-tree-config-modified* +============================================================================== +Class: Config.LiveFilter *nvim-tree-config-live-filter* + +*nvim_tree.Config.LiveFilter* + Live filter allows you to filter the tree nodes dynamically, based on + regex matching, see |vim.regex| + + This feature is bound to the `f` key by default. The filter can be cleared + with the `F` key by default. + + Fields: ~ + • {prefix}? (`string`, default: `[FILTER]: `) Prefix of + the filter displayed in the buffer. + • {always_show_folders}? (`boolean`, default: `true`) Whether to filter + folders or not. + + + ============================================================================== Class: Config.Actions *nvim-tree-config-actions* diff --git a/lua/nvim-tree/_meta/config/config.lua b/lua/nvim-tree/_meta/config/config.lua index b0eabb398d2..11494134b6b 100644 --- a/lua/nvim-tree/_meta/config/config.lua +++ b/lua/nvim-tree/_meta/config/config.lua @@ -272,23 +272,6 @@ error("Cannot require a meta file") ---(default: `gio trash` or `trash`) ---@field cmd? string --- --- Live Filter --- - ---- Configurations for the live_filtering feature. The live filter allows you to filter the tree nodes dynamically, based on regex matching (see |vim.regex|). ---- ---- This feature is bound to the `f` key by default. The filter can be cleared with the `F` key by default. ----@class nvim_tree.Config.LiveFilter ---- ----Prefix of the filter displayed in the buffer. ----(default: `[FILTER]: `) ----@field prefix? string ---- ----Whether to filter folders or not. ----(default: `true`) ----@field always_show_folders? boolean - -- -- System Open -- diff --git a/lua/nvim-tree/_meta/config/live_filter.lua b/lua/nvim-tree/_meta/config/live_filter.lua index 1b49a5e42fd..35c36d17667 100644 --- a/lua/nvim-tree/_meta/config/live_filter.lua +++ b/lua/nvim-tree/_meta/config/live_filter.lua @@ -1,5 +1,16 @@ ---@meta error("Cannot require a meta file") ---- TODO #2934 +--- Live filter allows you to filter the tree nodes dynamically, based on regex matching, see |vim.regex| +--- +--- This feature is bound to the `f` key by default. The filter can be cleared with the `F` key by default. +---@class nvim_tree.Config.LiveFilter +--- +---Prefix of the filter displayed in the buffer. +---(default: `[FILTER]: `) +---@field prefix? string +--- +---Whether to filter folders or not. +---(default: `true`) +---@field always_show_folders? boolean diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua index 380dd769a23..5c4c4c9988b 100644 --- a/scripts/gen_vimdoc_config.lua +++ b/scripts/gen_vimdoc_config.lua @@ -19,7 +19,7 @@ local modules = { { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/diagnostics.lua", }, { helptag = "nvim-tree-config-modified", title = "Class: Config.Modified", path = "lua/nvim-tree/_meta/config/modified.lua", }, { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/filters.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/live_filter.lua", }, + { helptag = "nvim-tree-config-live-filter", title = "Class: Config.LiveFilter", path = "lua/nvim-tree/_meta/config/live_filter.lua", }, { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/filesystem_watchers.lua", }, { helptag = "nvim-tree-config-actions", title = "Class: Config.Actions", path = "lua/nvim-tree/_meta/config/actions.lua", }, { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/trash.lua", }, From 628e9bfd42a0ceb92a0cf0bd2d775a30d1786b99 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 13:39:57 +1100 Subject: [PATCH 017/170] doc(#2934): tidy Config.FilesystemWatchers, move into place --- doc/nvim-tree-lua.txt | 53 +++++++++++-------- lua/nvim-tree/_meta/config/config.lua | 22 -------- .../_meta/config/filesystem_watchers.lua | 23 +++++++- scripts/gen_vimdoc_config.lua | 44 +++++++-------- 4 files changed, 73 insertions(+), 69 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index c4a0bf6090e..1f3f4f0ca17 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3586,29 +3586,6 @@ Class: Config *nvim-tree-config* • {max}? (`vim.diagnostic.Severity`) Maximum severity. Default: `vim.diagnostic.severity.ERROR` -*nvim_tree.Config.FilesystemWatchers* - Use file system watcher (libuv fs_event) to watch the filesystem for - changes. - - Using this will disable |BufEnter| and |BufWritePost| events in nvim-tree - which were used to update the whole tree. - - With this feature, the tree will be updated only for the appropriate - folder change, resulting in better performance. - - Fields: ~ - • {enable}? (`boolean`) (default: `true`) - • {debounce_delay}? (`integer`, default: `50`) Idle milliseconds - between filesystem change and action. - • {ignore_dirs}? (`string[]|fun(path: string): boolean`, default: `{ "/.ccls-cache", "/build", "/node_modules", "/target", }`) - List of vim regex for absolute directory paths that - will not be watched or function returning whether a - path should be ignored. Strings must be backslash - escaped e.g. `"my-proj/\\.build$"`. See - |string-match|. Function is passed an absolute - path. Useful when path is not in `.gitignore` or - git integration is disabled. - *nvim_tree.Config.Filters* Fields: ~ @@ -4226,6 +4203,36 @@ Class: Config.LiveFilter *nvim-tree-config-live-filter* +============================================================================== +Class: Config.FilesystemWatchers *nvim-tree-config-filesystem-watchers* + +*nvim_tree.Config.FilesystemWatchers* + Use file system watchers (libuv fs_event) to monitor the filesystem for + changes and update the tree. + + With this feature, the tree will be updated only for the appropriate + folder change, resulting in better performance. + + Watchers may be disabled for absolute directory paths via {ignore_dirs}. + Useful when path is not in `.gitignore` or git integration is disabled. + + Regex |pattern| strings must be backslash escaped e.g. + `"my-proj/\\.build$"` + + Using this will disable |BufEnter| and |BufWritePost| events in nvim-tree + which were used to update the whole tree. + + Fields: ~ + • {enable}? (`boolean`) (default: `true`) + • {debounce_delay}? (`integer`, default: `50`) Idle milliseconds + between filesystem change and tree update. + • {ignore_dirs}? (`string[]|fun(path: string): boolean`, default: `{ "/.ccls-cache", "/build", "/node_modules", "/target", }`) + Disable for directories via a list of vim regex OR + a function passed the absolute path of the + directory. + + + ============================================================================== Class: Config.Actions *nvim-tree-config-actions* diff --git a/lua/nvim-tree/_meta/config/config.lua b/lua/nvim-tree/_meta/config/config.lua index 11494134b6b..13d85b0e965 100644 --- a/lua/nvim-tree/_meta/config/config.lua +++ b/lua/nvim-tree/_meta/config/config.lua @@ -357,28 +357,6 @@ error("Cannot require a meta file") ---@field threshold? vim.log.levels Specify minimum notification level, uses the values from |vim.log.levels| Default: `vim.log.levels.INFO` `ERROR`: hard errors e.g. failure to read from the file system. `WARNING`: non-fatal errors e.g. unable to system open a file. `INFO:` information only e.g. file copy path confirmation. `DEBUG:` information for troubleshooting, e.g. failures in some window closing operations. ---@field absolute_path? boolean Whether to use absolute paths or item names in fs action notifications. Default: `true` --- --- Filesystem Watchers --- - ---- Use file system watcher (libuv fs_event) to watch the filesystem for changes. ---- ---- Using this will disable |BufEnter| and |BufWritePost| events in nvim-tree which were used to update the whole tree. ---- ---- With this feature, the tree will be updated only for the appropriate folder change, resulting in better performance. ----@class nvim_tree.Config.FilesystemWatchers ---- ----(default: `true`) ----@field enable? boolean ---- ----Idle milliseconds between filesystem change and action. ----(default: `50`) ----@field debounce_delay? integer ---- ----List of vim regex for absolute directory paths that will not be watched or function returning whether a path should be ignored. Strings must be backslash escaped e.g. `"my-proj/\\.build$"`. See |string-match|. Function is passed an absolute path. Useful when path is not in `.gitignore` or git integration is disabled. ----(default: `{ "/.ccls-cache", "/build", "/node_modules", "/target", }`) ----@field ignore_dirs? string[]|fun(path: string): boolean - -- -- Log -- diff --git a/lua/nvim-tree/_meta/config/filesystem_watchers.lua b/lua/nvim-tree/_meta/config/filesystem_watchers.lua index 1b49a5e42fd..e32d99bbfed 100644 --- a/lua/nvim-tree/_meta/config/filesystem_watchers.lua +++ b/lua/nvim-tree/_meta/config/filesystem_watchers.lua @@ -1,5 +1,24 @@ ---@meta error("Cannot require a meta file") ---- TODO #2934 - +---Use file system watchers (libuv fs_event) to monitor the filesystem for changes and update the tree. +--- +---With this feature, the tree will be updated only for the appropriate folder change, resulting in better performance. +--- +---Watchers may be disabled for absolute directory paths via {ignore_dirs}. Useful when path is not in `.gitignore` or git integration is disabled. +--- +---Regex |pattern| strings must be backslash escaped e.g. `"my-proj/\\.build$"` +--- +---Using this will disable |BufEnter| and |BufWritePost| events in nvim-tree which were used to update the whole tree. +---@class nvim_tree.Config.FilesystemWatchers +--- +---(default: `true`) +---@field enable? boolean +--- +---Idle milliseconds between filesystem change and tree update. +---(default: `50`) +---@field debounce_delay? integer +--- +---Disable for directories via a list of vim regex OR a function passed the absolute path of the directory. +---(default: `{ "/.ccls-cache", "/build", "/node_modules", "/target", }`) +---@field ignore_dirs? string[]|fun(path: string): boolean diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua index 5c4c4c9988b..f8d5559f9e0 100644 --- a/scripts/gen_vimdoc_config.lua +++ b/scripts/gen_vimdoc_config.lua @@ -8,29 +8,29 @@ ---Generated within help files in this order ---@type Module[] local modules = { - { helptag = "nvim-tree-config", title = "Class: Config", path = "lua/nvim-tree/_meta/config/config.lua", }, - { helptag = "nvim-tree-config-sort", title = "Class: Config.Sort", path = "lua/nvim-tree/_meta/config/sort.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/view.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/renderer.lua", }, - { helptag = "nvim-tree-config-hijack-directories", title = "Class: Config.HijackDirectories", path = "lua/nvim-tree/_meta/config/hijack_directories.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/update_focused_file.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/system_open.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/git.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/diagnostics.lua", }, - { helptag = "nvim-tree-config-modified", title = "Class: Config.Modified", path = "lua/nvim-tree/_meta/config/modified.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/filters.lua", }, - { helptag = "nvim-tree-config-live-filter", title = "Class: Config.LiveFilter", path = "lua/nvim-tree/_meta/config/live_filter.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/filesystem_watchers.lua", }, - { helptag = "nvim-tree-config-actions", title = "Class: Config.Actions", path = "lua/nvim-tree/_meta/config/actions.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/trash.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/tab.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/notify.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/help.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/ui.lua", name = "UI", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/log.lua", }, + { helptag = "nvim-tree-config", title = "Class: Config", path = "lua/nvim-tree/_meta/config/config.lua", }, + { helptag = "nvim-tree-config-sort", title = "Class: Config.Sort", path = "lua/nvim-tree/_meta/config/sort.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/view.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/renderer.lua", }, + { helptag = "nvim-tree-config-hijack-directories", title = "Class: Config.HijackDirectories", path = "lua/nvim-tree/_meta/config/hijack_directories.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/update_focused_file.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/system_open.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/git.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/diagnostics.lua", }, + { helptag = "nvim-tree-config-modified", title = "Class: Config.Modified", path = "lua/nvim-tree/_meta/config/modified.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/filters.lua", }, + { helptag = "nvim-tree-config-live-filter", title = "Class: Config.LiveFilter", path = "lua/nvim-tree/_meta/config/live_filter.lua", }, + { helptag = "nvim-tree-config-filesystem-watchers", title = "Class: Config.FilesystemWatchers", path = "lua/nvim-tree/_meta/config/filesystem_watchers.lua", }, + { helptag = "nvim-tree-config-actions", title = "Class: Config.Actions", path = "lua/nvim-tree/_meta/config/actions.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/trash.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/tab.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/notify.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/help.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/ui.lua", name = "UI", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/log.lua", }, - { helptag = "nvim-tree-api", title = "Lua module: nvim_tree.api", path = "lua/nvim-tree/_meta/api.lua", }, - { helptag = "nvim-tree-api-decorator", title = "Lua module: nvim_tree.api.decorator", path = "lua/nvim-tree/_meta/api_decorator.lua", }, + { helptag = "nvim-tree-api", title = "Lua module: nvim_tree.api", path = "lua/nvim-tree/_meta/api.lua", }, + { helptag = "nvim-tree-api-decorator", title = "Lua module: nvim_tree.api.decorator", path = "lua/nvim-tree/_meta/api_decorator.lua", }, } -- hydrate file names From a6142a228d42f5ba5808615de4aebe9d15956e30 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 13:44:01 +1100 Subject: [PATCH 018/170] doc(#2934): tidy Config.Trash, move into place --- doc/nvim-tree-lua.txt | 24 +++++++++++++++--------- lua/nvim-tree/_meta/config/config.lua | 13 ------------- lua/nvim-tree/_meta/config/trash.lua | 10 +++++++++- scripts/gen_vimdoc_config.lua | 2 +- 4 files changed, 25 insertions(+), 24 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 1f3f4f0ca17..e86937b1db3 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3992,15 +3992,6 @@ Class: Config *nvim-tree-config* • {ignore}? (`string[]`, default: `{}`) List of filetypes or buffer names on new tab that will prevent `open` and `close` -*nvim_tree.Config.Trash* - - Fields: ~ - • {cmd}? (`string`, default: `gio trash` or `trash`) The command used - to trash items, which must be installed on your system. - • linux: `gio trash`, from linux package `glib2` - • macOS: `trash`, from homebrew package `trash` - • windows: `trash`, requires `trash-cli` or similar - *nvim_tree.Config.UI* Fields: ~ @@ -4346,6 +4337,21 @@ Class: Config.Actions *nvim-tree-config-actions* +============================================================================== +Class: Config.Trash *nvim-tree-config-trash* + +*nvim_tree.Config.Trash* + Files may be trashed via an external command that must be installed on + your system. + • linux: `gio trash`, from linux package `glib2` + • macOS: `trash`, from homebrew package `trash` + • windows: `trash`, requires `trash-cli` or similar + + Fields: ~ + • {cmd}? (`string`, default: `gio trash` or `trash`) External command. + + + ============================================================================== Lua module: nvim_tree.api *nvim-tree-api* diff --git a/lua/nvim-tree/_meta/config/config.lua b/lua/nvim-tree/_meta/config/config.lua index 13d85b0e965..22ca8f3a516 100644 --- a/lua/nvim-tree/_meta/config/config.lua +++ b/lua/nvim-tree/_meta/config/config.lua @@ -259,19 +259,6 @@ error("Cannot require a meta file") ---(default: `{}`) ---@field ignore? string[] --- --- Trash --- - ----@class nvim_tree.Config.Trash ---- ----The command used to trash items, which must be installed on your system. ---- - linux: `gio trash`, from linux package `glib2` ---- - macOS: `trash`, from homebrew package `trash` ---- - windows: `trash`, requires `trash-cli` or similar ----(default: `gio trash` or `trash`) ----@field cmd? string - -- -- System Open -- diff --git a/lua/nvim-tree/_meta/config/trash.lua b/lua/nvim-tree/_meta/config/trash.lua index 1b49a5e42fd..46ef3c15135 100644 --- a/lua/nvim-tree/_meta/config/trash.lua +++ b/lua/nvim-tree/_meta/config/trash.lua @@ -1,5 +1,13 @@ ---@meta error("Cannot require a meta file") ---- TODO #2934 +---Files may be trashed via an external command that must be installed on your system. +--- - linux: `gio trash`, from linux package `glib2` +--- - macOS: `trash`, from homebrew package `trash` +--- - windows: `trash`, requires `trash-cli` or similar +---@class nvim_tree.Config.Trash +--- +---External command. +---(default: `gio trash` or `trash`) +---@field cmd? string diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua index f8d5559f9e0..b24678470a3 100644 --- a/scripts/gen_vimdoc_config.lua +++ b/scripts/gen_vimdoc_config.lua @@ -22,7 +22,7 @@ local modules = { { helptag = "nvim-tree-config-live-filter", title = "Class: Config.LiveFilter", path = "lua/nvim-tree/_meta/config/live_filter.lua", }, { helptag = "nvim-tree-config-filesystem-watchers", title = "Class: Config.FilesystemWatchers", path = "lua/nvim-tree/_meta/config/filesystem_watchers.lua", }, { helptag = "nvim-tree-config-actions", title = "Class: Config.Actions", path = "lua/nvim-tree/_meta/config/actions.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/trash.lua", }, + { helptag = "nvim-tree-config-trash", title = "Class: Config.Trash", path = "lua/nvim-tree/_meta/config/trash.lua", }, { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/tab.lua", }, { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/notify.lua", }, { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/help.lua", }, From d1fd1d4fdb685ffb65f60b714f40144772712faf Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 13:49:14 +1100 Subject: [PATCH 019/170] doc(#2934): tidy Config.Tab, move into place --- doc/nvim-tree-lua.txt | 44 ++++++++++--------- lua/nvim-tree/_meta/config/config.lua | 35 --------------- .../_meta/config/filesystem_watchers.lua | 2 +- lua/nvim-tree/_meta/config/modified.lua | 2 +- lua/nvim-tree/_meta/config/tab.lua | 24 +++++++++- scripts/gen_vimdoc_config.lua | 2 +- 6 files changed, 50 insertions(+), 59 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index e86937b1db3..43cccdbe94e 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3975,23 +3975,6 @@ Class: Config *nvim-tree-config* empty for OS specific default: Windows: `{ "/c", "start", '""' }` -*nvim_tree.Config.Tab* - - Fields: ~ - • {sync}? (`nvim_tree.Config.Tab.Sync`) |nvim_tree.Config.Tab.Sync| - -*nvim_tree.Config.Tab.Sync* - Configuration for syncing nvim-tree across tabs. - - Fields: ~ - • {open}? (`boolean`, default: `false`) Opens the tree automatically - when switching tabpage or opening a new tabpage if the tree - was previously open. - • {close}? (`boolean`, default: `false`) Closes the tree across all - tabpages when the tree is closed. - • {ignore}? (`string[]`, default: `{}`) List of filetypes or buffer - names on new tab that will prevent `open` and `close` - *nvim_tree.Config.UI* Fields: ~ @@ -4160,7 +4143,7 @@ Class: Config.HijackDirectories *nvim-tree-config-hijack-directories* Class: Config.Modified *nvim-tree-config-modified* *nvim_tree.Config.Modified* - Indicate which file have unsaved modification. To see modified status in + Indicate which files have unsaved modification. To see modified status in the tree you will need to set: • |nvim_tree.Config.Renderer.Icons.Show| {modified} to `true` OR • |nvim_tree.Config.Renderer| {highlight_modified} to `true` @@ -4207,8 +4190,7 @@ Class: Config.FilesystemWatchers *nvim-tree-config-filesystem-watchers* Watchers may be disabled for absolute directory paths via {ignore_dirs}. Useful when path is not in `.gitignore` or git integration is disabled. - Regex |pattern| strings must be backslash escaped e.g. - `"my-proj/\\.build$"` + |vim.regex| strings must be backslash escaped e.g. `"my-proj/\\.build$"` Using this will disable |BufEnter| and |BufWritePost| events in nvim-tree which were used to update the whole tree. @@ -4352,6 +4334,28 @@ Class: Config.Trash *nvim-tree-config-trash* +============================================================================== +Class: Config.Tab *nvim-tree-config-tab* + +*nvim_tree.Config.Tab* + + Fields: ~ + • {sync}? (`nvim_tree.Config.Tab.Sync`) |nvim_tree.Config.Tab.Sync| + +*nvim_tree.Config.Tab.Sync* + Configuration for syncing nvim-tree across tabs. + + Fields: ~ + • {open}? (`boolean`, default: `false`) Opens the tree automatically + when switching tabpage or opening a new tabpage if the tree + was previously open. + • {close}? (`boolean`, default: `false`) Closes the tree across all + tabpages when the tree is closed. + • {ignore}? (`string[]`, default: `{}`) List of filetypes or buffer + names on new tab that will prevent `open` and `close` + + + ============================================================================== Lua module: nvim_tree.api *nvim-tree-api* diff --git a/lua/nvim-tree/_meta/config/config.lua b/lua/nvim-tree/_meta/config/config.lua index 22ca8f3a516..c54096905a2 100644 --- a/lua/nvim-tree/_meta/config/config.lua +++ b/lua/nvim-tree/_meta/config/config.lua @@ -224,41 +224,6 @@ error("Cannot require a meta file") ---@field deleted? string Default: `""` ---@field ignored? string Default: `"◌"` --- --- Modified --- - - --- --- Tab --- - - ----@class nvim_tree.Config.Tab ---- ----|nvim_tree.Config.Tab.Sync| ----@field sync? nvim_tree.Config.Tab.Sync - --- --- Tab.Sync --- - ----Configuration for syncing nvim-tree across tabs. ----@class nvim_tree.Config.Tab.Sync ---- ----Opens the tree automatically when switching tabpage or opening a new tabpage if the tree was previously open. ----(default: `false`) ----@field open? boolean ---- ----Closes the tree across all tabpages when the tree is closed. ----(default: `false`) ----@field close? boolean ---- ---- ----List of filetypes or buffer names on new tab that will prevent `open` and `close` ----(default: `{}`) ----@field ignore? string[] - -- -- System Open -- diff --git a/lua/nvim-tree/_meta/config/filesystem_watchers.lua b/lua/nvim-tree/_meta/config/filesystem_watchers.lua index e32d99bbfed..f1fd6095081 100644 --- a/lua/nvim-tree/_meta/config/filesystem_watchers.lua +++ b/lua/nvim-tree/_meta/config/filesystem_watchers.lua @@ -7,7 +7,7 @@ error("Cannot require a meta file") --- ---Watchers may be disabled for absolute directory paths via {ignore_dirs}. Useful when path is not in `.gitignore` or git integration is disabled. --- ----Regex |pattern| strings must be backslash escaped e.g. `"my-proj/\\.build$"` +---|vim.regex| strings must be backslash escaped e.g. `"my-proj/\\.build$"` --- ---Using this will disable |BufEnter| and |BufWritePost| events in nvim-tree which were used to update the whole tree. ---@class nvim_tree.Config.FilesystemWatchers diff --git a/lua/nvim-tree/_meta/config/modified.lua b/lua/nvim-tree/_meta/config/modified.lua index 0a04fffc922..33de15d5514 100644 --- a/lua/nvim-tree/_meta/config/modified.lua +++ b/lua/nvim-tree/_meta/config/modified.lua @@ -1,7 +1,7 @@ ---@meta error("Cannot require a meta file") ----Indicate which file have unsaved modification. +---Indicate which files have unsaved modification. ---To see modified status in the tree you will need to set: --- - |nvim_tree.Config.Renderer.Icons.Show| {modified} to `true` OR --- - |nvim_tree.Config.Renderer| {highlight_modified} to `true` diff --git a/lua/nvim-tree/_meta/config/tab.lua b/lua/nvim-tree/_meta/config/tab.lua index 1b49a5e42fd..e5430bece32 100644 --- a/lua/nvim-tree/_meta/config/tab.lua +++ b/lua/nvim-tree/_meta/config/tab.lua @@ -1,5 +1,27 @@ ---@meta error("Cannot require a meta file") ---- TODO #2934 +---@class nvim_tree.Config.Tab +--- +---|nvim_tree.Config.Tab.Sync| +---@field sync? nvim_tree.Config.Tab.Sync +-- +-- Tab.Sync +-- + +---Configuration for syncing nvim-tree across tabs. +---@class nvim_tree.Config.Tab.Sync +--- +---Opens the tree automatically when switching tabpage or opening a new tabpage if the tree was previously open. +---(default: `false`) +---@field open? boolean +--- +---Closes the tree across all tabpages when the tree is closed. +---(default: `false`) +---@field close? boolean +--- +--- +---List of filetypes or buffer names on new tab that will prevent `open` and `close` +---(default: `{}`) +---@field ignore? string[] diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua index b24678470a3..7eb686a58ec 100644 --- a/scripts/gen_vimdoc_config.lua +++ b/scripts/gen_vimdoc_config.lua @@ -23,7 +23,7 @@ local modules = { { helptag = "nvim-tree-config-filesystem-watchers", title = "Class: Config.FilesystemWatchers", path = "lua/nvim-tree/_meta/config/filesystem_watchers.lua", }, { helptag = "nvim-tree-config-actions", title = "Class: Config.Actions", path = "lua/nvim-tree/_meta/config/actions.lua", }, { helptag = "nvim-tree-config-trash", title = "Class: Config.Trash", path = "lua/nvim-tree/_meta/config/trash.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/tab.lua", }, + { helptag = "nvim-tree-config-tab", title = "Class: Config.Tab", path = "lua/nvim-tree/_meta/config/tab.lua", }, { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/notify.lua", }, { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/help.lua", }, { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/ui.lua", name = "UI", }, From b449929f7c4d69ca85a2493212494bf1c60b5958 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 13:51:36 +1100 Subject: [PATCH 020/170] doc(#2934): tidy Config.UI, move into place --- doc/nvim-tree-lua.txt | 35 +++++++++++++++------------ lua/nvim-tree/_meta/config/config.lua | 29 ---------------------- lua/nvim-tree/_meta/config/ui.lua | 23 +++++++++++++++++- scripts/gen_vimdoc_config.lua | 2 +- 4 files changed, 43 insertions(+), 46 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 43cccdbe94e..a99291c76af 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3975,21 +3975,6 @@ Class: Config *nvim-tree-config* empty for OS specific default: Windows: `{ "/c", "start", '""' }` -*nvim_tree.Config.UI* - - Fields: ~ - • {confirm}? (`nvim_tree.Config.UI.Confirm`) - |nvim_tree.Config.UI.Confirm| - -*nvim_tree.Config.UI.Confirm* - Confirmation prompts. - - Fields: ~ - • {remove}? (`boolean`, default: `true`) Prompt before removing. - • {trash}? (`boolean`, default: `true`) Prompt before trashing. - • {default_yes}? (`boolean`, default: `false`) If `true` the prompt - will be `Y/n`, otherwise `y/N` - *nvim_tree.Config.UpdateFocusedFile* Fields: ~ @@ -4356,6 +4341,26 @@ Class: Config.Tab *nvim-tree-config-tab* +============================================================================== +Class: Config.UI *nvim-tree-config-ui* + +*nvim_tree.Config.UI* + + Fields: ~ + • {confirm}? (`nvim_tree.Config.UI.Confirm`) + |nvim_tree.Config.UI.Confirm| + +*nvim_tree.Config.UI.Confirm* + Confirmation prompts. + + Fields: ~ + • {remove}? (`boolean`, default: `true`) Prompt before removing. + • {trash}? (`boolean`, default: `true`) Prompt before trashing. + • {default_yes}? (`boolean`, default: `false`) If `true` the prompt + will be `Y/n`, otherwise `y/N` + + + ============================================================================== Lua module: nvim_tree.api *nvim-tree-api* diff --git a/lua/nvim-tree/_meta/config/config.lua b/lua/nvim-tree/_meta/config/config.lua index c54096905a2..9a0a0db64b3 100644 --- a/lua/nvim-tree/_meta/config/config.lua +++ b/lua/nvim-tree/_meta/config/config.lua @@ -361,35 +361,6 @@ error("Cannot require a meta file") ---(default: `false`) ---@field watcher? boolean --- --- UI --- - ----@class nvim_tree.Config.UI ---- ----|nvim_tree.Config.UI.Confirm| ----@field confirm? nvim_tree.Config.UI.Confirm - --- --- UI.Confirm --- - ----Confirmation prompts. ----@class nvim_tree.Config.UI.Confirm ---- ----Prompt before removing. ----(default: `true`) ----@field remove? boolean ---- ----Prompt before trashing. ----(default: `true`) ----@field trash? boolean ---- ----If `true` the prompt will be `Y/n`, otherwise `y/N` ----(default: `false`) ----@field default_yes? boolean - - -- -- View -- diff --git a/lua/nvim-tree/_meta/config/ui.lua b/lua/nvim-tree/_meta/config/ui.lua index 1b49a5e42fd..9e9f91b313b 100644 --- a/lua/nvim-tree/_meta/config/ui.lua +++ b/lua/nvim-tree/_meta/config/ui.lua @@ -1,5 +1,26 @@ ---@meta error("Cannot require a meta file") ---- TODO #2934 +---@class nvim_tree.Config.UI +--- +---|nvim_tree.Config.UI.Confirm| +---@field confirm? nvim_tree.Config.UI.Confirm +-- +-- UI.Confirm +-- + +---Confirmation prompts. +---@class nvim_tree.Config.UI.Confirm +--- +---Prompt before removing. +---(default: `true`) +---@field remove? boolean +--- +---Prompt before trashing. +---(default: `true`) +---@field trash? boolean +--- +---If `true` the prompt will be `Y/n`, otherwise `y/N` +---(default: `false`) +---@field default_yes? boolean diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua index 7eb686a58ec..4adeceba164 100644 --- a/scripts/gen_vimdoc_config.lua +++ b/scripts/gen_vimdoc_config.lua @@ -26,7 +26,7 @@ local modules = { { helptag = "nvim-tree-config-tab", title = "Class: Config.Tab", path = "lua/nvim-tree/_meta/config/tab.lua", }, { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/notify.lua", }, { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/help.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/ui.lua", name = "UI", }, + { helptag = "nvim-tree-config-ui", title = "Class: Config.UI", path = "lua/nvim-tree/_meta/config/ui.lua", name = "UI", }, { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/log.lua", }, { helptag = "nvim-tree-api", title = "Lua module: nvim_tree.api", path = "lua/nvim-tree/_meta/api.lua", }, From d64aa2d8eff06b68e7760112fca3f8f586ccf4a3 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 13:53:20 +1100 Subject: [PATCH 021/170] doc(#2934): tidy Config.Log, move into place --- doc/nvim-tree-lua.txt | 67 ++++++++++++++------------- lua/nvim-tree/_meta/config/config.lua | 52 --------------------- lua/nvim-tree/_meta/config/log.lua | 48 ++++++++++++++++++- scripts/gen_vimdoc_config.lua | 2 +- 4 files changed, 84 insertions(+), 85 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index a99291c76af..f485e511a93 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3663,37 +3663,6 @@ Class: Config *nvim-tree-config* alphabetically by keymap) or `"desc"` (sort alphabetically by description). Default: `"key"` -*nvim_tree.Config.Log* - Log to a file `nvim-tree.log` in |stdpath|("log"), usually - `${XDG_STATE_HOME}/nvim` - - Fields: ~ - • {enable}? (`boolean`) (default: `false`) - • {truncate}? (`boolean`, default: `false`) Remove existing log file at - startup. - • {types}? (`nvim_tree.Config.Log.Types`) - |nvim_tree.Config.Log.Types| - -*nvim_tree.Config.Log.Types* - Specify which information to log. - - Fields: ~ - • {all}? (`boolean`, default: `false`) Everything. - • {profile}? (`boolean`, default: `false`) Timing of some - operations. - • {config}? (`boolean`, default: `false`) Options and mappings, at - startup. - • {copy_paste}? (`boolean`, default: `false`) File copy and paste - actions. - • {dev}? (`boolean`, default: `false`) Used for local - development only. Not useful for users. - • {diagnostics}? (`boolean`, default: `false`) LSP and COC processing, - verbose. - • {git}? (`boolean`, default: `false`) Git processing, verbose. - • {watcher}? (`boolean`, default: `false`) - |nvim_tree.Config.FilesystemWatchers| processing, - verbose. - *nvim_tree.Config.Notify* Fields: ~ @@ -4361,6 +4330,42 @@ Class: Config.UI *nvim-tree-config-ui* +============================================================================== +Class: Config.Log *nvim-tree-config-log* + +*nvim_tree.Config.Log* + Log to a file `nvim-tree.log` in |stdpath|("log"), usually + `${XDG_STATE_HOME}/nvim` + + Fields: ~ + • {enable}? (`boolean`) (default: `false`) + • {truncate}? (`boolean`, default: `false`) Remove existing log file at + startup. + • {types}? (`nvim_tree.Config.Log.Types`) + |nvim_tree.Config.Log.Types| + +*nvim_tree.Config.Log.Types* + Specify which information to log. + + Fields: ~ + • {all}? (`boolean`, default: `false`) Everything. + • {profile}? (`boolean`, default: `false`) Timing of some + operations. + • {config}? (`boolean`, default: `false`) Options and mappings, at + startup. + • {copy_paste}? (`boolean`, default: `false`) File copy and paste + actions. + • {dev}? (`boolean`, default: `false`) Used for local + development only. Not useful for users. + • {diagnostics}? (`boolean`, default: `false`) LSP and COC processing, + verbose. + • {git}? (`boolean`, default: `false`) Git processing, verbose. + • {watcher}? (`boolean`, default: `false`) + |nvim_tree.Config.FilesystemWatchers| processing, + verbose. + + + ============================================================================== Lua module: nvim_tree.api *nvim-tree-api* diff --git a/lua/nvim-tree/_meta/config/config.lua b/lua/nvim-tree/_meta/config/config.lua index 9a0a0db64b3..1180ea73e7c 100644 --- a/lua/nvim-tree/_meta/config/config.lua +++ b/lua/nvim-tree/_meta/config/config.lua @@ -309,58 +309,6 @@ error("Cannot require a meta file") ---@field threshold? vim.log.levels Specify minimum notification level, uses the values from |vim.log.levels| Default: `vim.log.levels.INFO` `ERROR`: hard errors e.g. failure to read from the file system. `WARNING`: non-fatal errors e.g. unable to system open a file. `INFO:` information only e.g. file copy path confirmation. `DEBUG:` information for troubleshooting, e.g. failures in some window closing operations. ---@field absolute_path? boolean Whether to use absolute paths or item names in fs action notifications. Default: `true` --- --- Log --- - ----Log to a file `nvim-tree.log` in |stdpath|("log"), usually `${XDG_STATE_HOME}/nvim` ----@class nvim_tree.Config.Log ---- ----(default: `false`) ----@field enable? boolean ---- ----Remove existing log file at startup. ----(default: `false`) ----@field truncate? boolean ---- ----|nvim_tree.Config.Log.Types| ----@field types? nvim_tree.Config.Log.Types - ----Specify which information to log. ----@class nvim_tree.Config.Log.Types ---- ----Everything. ----(default: `false`) ----@field all? boolean ---- ---- Timing of some operations. ----(default: `false`) ----@field profile? boolean ---- ----Options and mappings, at startup. ----(default: `false`) ----@field config? boolean ---- ----File copy and paste actions. ----(default: `false`) ----@field copy_paste? boolean ---- ----Used for local development only. Not useful for users. ----(default: `false`) ----@field dev? boolean ---- ----LSP and COC processing, verbose. ----(default: `false`) ----@field diagnostics? boolean ---- ----Git processing, verbose. ----(default: `false`) ----@field git? boolean ---- ----|nvim_tree.Config.FilesystemWatchers| processing, verbose. ----(default: `false`) ----@field watcher? boolean - -- -- View -- diff --git a/lua/nvim-tree/_meta/config/log.lua b/lua/nvim-tree/_meta/config/log.lua index 1b49a5e42fd..cdb408cc264 100644 --- a/lua/nvim-tree/_meta/config/log.lua +++ b/lua/nvim-tree/_meta/config/log.lua @@ -1,5 +1,51 @@ ---@meta error("Cannot require a meta file") ---- TODO #2934 +---Log to a file `nvim-tree.log` in |stdpath|("log"), usually `${XDG_STATE_HOME}/nvim` +---@class nvim_tree.Config.Log +--- +---(default: `false`) +---@field enable? boolean +--- +---Remove existing log file at startup. +---(default: `false`) +---@field truncate? boolean +--- +---|nvim_tree.Config.Log.Types| +---@field types? nvim_tree.Config.Log.Types + +---Specify which information to log. +---@class nvim_tree.Config.Log.Types +--- +---Everything. +---(default: `false`) +---@field all? boolean +--- +--- Timing of some operations. +---(default: `false`) +---@field profile? boolean +--- +---Options and mappings, at startup. +---(default: `false`) +---@field config? boolean +--- +---File copy and paste actions. +---(default: `false`) +---@field copy_paste? boolean +--- +---Used for local development only. Not useful for users. +---(default: `false`) +---@field dev? boolean +--- +---LSP and COC processing, verbose. +---(default: `false`) +---@field diagnostics? boolean +--- +---Git processing, verbose. +---(default: `false`) +---@field git? boolean +--- +---|nvim_tree.Config.FilesystemWatchers| processing, verbose. +---(default: `false`) +---@field watcher? boolean diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua index 4adeceba164..e43b863922c 100644 --- a/scripts/gen_vimdoc_config.lua +++ b/scripts/gen_vimdoc_config.lua @@ -27,7 +27,7 @@ local modules = { { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/notify.lua", }, { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/help.lua", }, { helptag = "nvim-tree-config-ui", title = "Class: Config.UI", path = "lua/nvim-tree/_meta/config/ui.lua", name = "UI", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/log.lua", }, + { helptag = "nvim-tree-config-log", title = "Class: Config.Log", path = "lua/nvim-tree/_meta/config/log.lua", }, { helptag = "nvim-tree-api", title = "Lua module: nvim_tree.api", path = "lua/nvim-tree/_meta/api.lua", }, { helptag = "nvim-tree-api-decorator", title = "Lua module: nvim_tree.api.decorator", path = "lua/nvim-tree/_meta/api_decorator.lua", }, From 1aad39e44e70eb5abc324b429c8df64c11e126b1 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 14:00:26 +1100 Subject: [PATCH 022/170] doc(#2934): tidy Config.Notify, move into place --- doc/nvim-tree-lua.txt | 34 +++++++++++++++------------ lua/nvim-tree/_meta/config/config.lua | 8 ------- lua/nvim-tree/_meta/config/notify.lua | 17 ++++++++++++-- scripts/gen_vimdoc_config.lua | 2 +- 4 files changed, 35 insertions(+), 26 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index f485e511a93..357fe452120 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3663,21 +3663,6 @@ Class: Config *nvim-tree-config* alphabetically by keymap) or `"desc"` (sort alphabetically by description). Default: `"key"` -*nvim_tree.Config.Notify* - - Fields: ~ - • {threshold}? (`vim.log.levels`) Specify minimum notification - level, uses the values from |vim.log.levels| - Default: `vim.log.levels.INFO` `ERROR`: hard errors - e.g. failure to read from the file system. - `WARNING`: non-fatal errors e.g. unable to system - open a file. `INFO:` information only e.g. file copy - path confirmation. `DEBUG:` information for - troubleshooting, e.g. failures in some window - closing operations. - • {absolute_path}? (`boolean`) Whether to use absolute paths or item - names in fs action notifications. Default: `true` - *nvim_tree.Config.Renderer* Fields: ~ @@ -4310,6 +4295,25 @@ Class: Config.Tab *nvim-tree-config-tab* +============================================================================== +Class: Config.Notify *nvim-tree-config-notify* + +*nvim_tree.Config.Notify* + nvim-tree notifications levels: + • ERROR: hard errors e.g. failure to read from the file system. + • WARN: non-fatal errors e.g. unable to system open a file. + • INFO: information only e.g. file copy path confirmation. + • DEBUG: information for troubleshooting, e.g. failures in some window + closing operations. + + Fields: ~ + • {threshold}? (`vim.log.levels`, default: `vim.log.levels.INFO`) + Specify minimum notification level + • {absolute_path}? (`boolean`, default: `true`) Use absolute paths in + FS action notifications, otherwise item names. + + + ============================================================================== Class: Config.UI *nvim-tree-config-ui* diff --git a/lua/nvim-tree/_meta/config/config.lua b/lua/nvim-tree/_meta/config/config.lua index 1180ea73e7c..8931afd59dd 100644 --- a/lua/nvim-tree/_meta/config/config.lua +++ b/lua/nvim-tree/_meta/config/config.lua @@ -301,14 +301,6 @@ error("Cannot require a meta file") ---@field warning? string Default: `""` ---@field error? string Default: `""` --- --- Notify --- - ----@class nvim_tree.Config.Notify ----@field threshold? vim.log.levels Specify minimum notification level, uses the values from |vim.log.levels| Default: `vim.log.levels.INFO` `ERROR`: hard errors e.g. failure to read from the file system. `WARNING`: non-fatal errors e.g. unable to system open a file. `INFO:` information only e.g. file copy path confirmation. `DEBUG:` information for troubleshooting, e.g. failures in some window closing operations. ----@field absolute_path? boolean Whether to use absolute paths or item names in fs action notifications. Default: `true` - -- -- View -- diff --git a/lua/nvim-tree/_meta/config/notify.lua b/lua/nvim-tree/_meta/config/notify.lua index 1b49a5e42fd..252d478ba93 100644 --- a/lua/nvim-tree/_meta/config/notify.lua +++ b/lua/nvim-tree/_meta/config/notify.lua @@ -1,5 +1,18 @@ ---@meta error("Cannot require a meta file") ---- TODO #2934 - +---nvim-tree notifications levels: +---- ERROR: hard errors e.g. failure to read from the file system. +---- WARN: non-fatal errors e.g. unable to system open a file. +---- INFO: information only e.g. file copy path confirmation. +---- DEBUG: information for troubleshooting, e.g. failures in some window closing operations. +--- +---@class nvim_tree.Config.Notify +--- +---Specify minimum notification level +---(Default: `vim.log.levels.INFO`) +---@field threshold? vim.log.levels +--- +---Use absolute paths in FS action notifications, otherwise item names. +---(default: `true`) +---@field absolute_path? boolean diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua index e43b863922c..ac85f8f8edf 100644 --- a/scripts/gen_vimdoc_config.lua +++ b/scripts/gen_vimdoc_config.lua @@ -24,7 +24,7 @@ local modules = { { helptag = "nvim-tree-config-actions", title = "Class: Config.Actions", path = "lua/nvim-tree/_meta/config/actions.lua", }, { helptag = "nvim-tree-config-trash", title = "Class: Config.Trash", path = "lua/nvim-tree/_meta/config/trash.lua", }, { helptag = "nvim-tree-config-tab", title = "Class: Config.Tab", path = "lua/nvim-tree/_meta/config/tab.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/notify.lua", }, + { helptag = "nvim-tree-config-notify", title = "Class: Config.Notify", path = "lua/nvim-tree/_meta/config/notify.lua", }, { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/help.lua", }, { helptag = "nvim-tree-config-ui", title = "Class: Config.UI", path = "lua/nvim-tree/_meta/config/ui.lua", name = "UI", }, { helptag = "nvim-tree-config-log", title = "Class: Config.Log", path = "lua/nvim-tree/_meta/config/log.lua", }, From 1feb014238705f6c3a8b586c76e07edec760f089 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 14:15:30 +1100 Subject: [PATCH 023/170] doc(#2934): tidy Config.SystemOpen, move into place --- doc/nvim-tree-lua.txt | 32 +++++++++++++------ lua/nvim-tree/_meta/config/actions.lua | 3 +- lua/nvim-tree/_meta/config/config.lua | 8 ----- lua/nvim-tree/_meta/config/diagnostics.lua | 1 - lua/nvim-tree/_meta/config/filters.lua | 1 - lua/nvim-tree/_meta/config/git.lua | 1 - lua/nvim-tree/_meta/config/help.lua | 1 - lua/nvim-tree/_meta/config/live_filter.lua | 1 - lua/nvim-tree/_meta/config/log.lua | 1 - lua/nvim-tree/_meta/config/renderer.lua | 1 - lua/nvim-tree/_meta/config/sort.lua | 1 - lua/nvim-tree/_meta/config/system_open.lua | 20 ++++++++++-- lua/nvim-tree/_meta/config/trash.lua | 1 - .../_meta/config/update_focused_file.lua | 1 - lua/nvim-tree/_meta/config/view.lua | 1 - scripts/gen_vimdoc_config.lua | 2 +- 16 files changed, 42 insertions(+), 34 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 357fe452120..67dfd98e1e1 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3919,16 +3919,6 @@ Class: Config *nvim-tree-config* • {bottom}? (`string`) Default: `"─"` • {none}? (`string`) Default: `" "` -*nvim_tree.Config.SystemOpen* - - Fields: ~ - • {cmd}? (`string`) The open command itself. Default: `""` neovim >= - 0.10 defaults to |vim.ui.open| neovim < 0.10 defaults to: - UNIX: `"xdg-open"` macOS: `"open"` Windows: `"cmd"` - • {args}? (`string[]`) Optional argument list. Default: `{}` Leave - empty for OS specific default: Windows: - `{ "/c", "start", '""' }` - *nvim_tree.Config.UpdateFocusedFile* Fields: ~ @@ -4078,6 +4068,28 @@ Class: Config.HijackDirectories *nvim-tree-config-hijack-directories* +============================================================================== +Class: Config.SystemOpen *nvim-tree-config-system-open* + +*nvim_tree.Config.SystemOpen* + Open files or directories via the OS. + + Neovim: + • `>=` 0.10 uses |vim.ui.open| unless {cmd} is specified + • `<` 0.10 calls external {cmd}: + • UNIX: `xdg-open` + • macOS: `open` + • Windows: `cmd` + + Fields: ~ + • {cmd}? (`string`, default: `xdg-open`, `open` or `cmd`) The open + command itself + • {args}? (`string[]`, default: `{}` or `{ "/c", "start", '""' }` on + windows) Optional argument list. Leave empty for OS specific + default. + + + ============================================================================== Class: Config.Modified *nvim-tree-config-modified* diff --git a/lua/nvim-tree/_meta/config/actions.lua b/lua/nvim-tree/_meta/config/actions.lua index d2de25b7e59..16fe7d78bb9 100644 --- a/lua/nvim-tree/_meta/config/actions.lua +++ b/lua/nvim-tree/_meta/config/actions.lua @@ -65,7 +65,7 @@ error("Cannot require a meta file") ---You shouldn't define |vim.api.keyset.win_config| {width} and {height} values here. They will be overridden to fit the file_popup content. ---@class nvim_tree.Config.Actions.FilePopup --- ----Neovim window config. +---Neovim window config. ---(default: `{ col = 1, row = 1, relative = "cursor", border = "shadow", style = "minimal", }`) ---@field open_win_config? vim.api.keyset.win_config @@ -142,4 +142,3 @@ error("Cannot require a meta file") ---Close any window that displays a file when removing that file from the tree. ---(default: `true`) ---@field close_window? boolean - diff --git a/lua/nvim-tree/_meta/config/config.lua b/lua/nvim-tree/_meta/config/config.lua index 8931afd59dd..5c1043a68e4 100644 --- a/lua/nvim-tree/_meta/config/config.lua +++ b/lua/nvim-tree/_meta/config/config.lua @@ -224,14 +224,6 @@ error("Cannot require a meta file") ---@field deleted? string Default: `""` ---@field ignored? string Default: `"◌"` --- --- System Open --- - ----@class nvim_tree.Config.SystemOpen ----@field cmd? string The open command itself. Default: `""` neovim >= 0.10 defaults to |vim.ui.open| neovim < 0.10 defaults to: UNIX: `"xdg-open"` macOS: `"open"` Windows: `"cmd"` ----@field args? string[] Optional argument list. Default: `{}` Leave empty for OS specific default: Windows: `{ "/c", "start", '""' }` - -- -- Help -- diff --git a/lua/nvim-tree/_meta/config/diagnostics.lua b/lua/nvim-tree/_meta/config/diagnostics.lua index 1b49a5e42fd..4ab716dc93a 100644 --- a/lua/nvim-tree/_meta/config/diagnostics.lua +++ b/lua/nvim-tree/_meta/config/diagnostics.lua @@ -2,4 +2,3 @@ error("Cannot require a meta file") --- TODO #2934 - diff --git a/lua/nvim-tree/_meta/config/filters.lua b/lua/nvim-tree/_meta/config/filters.lua index 1b49a5e42fd..4ab716dc93a 100644 --- a/lua/nvim-tree/_meta/config/filters.lua +++ b/lua/nvim-tree/_meta/config/filters.lua @@ -2,4 +2,3 @@ error("Cannot require a meta file") --- TODO #2934 - diff --git a/lua/nvim-tree/_meta/config/git.lua b/lua/nvim-tree/_meta/config/git.lua index f0338f57686..f64f27300c9 100644 --- a/lua/nvim-tree/_meta/config/git.lua +++ b/lua/nvim-tree/_meta/config/git.lua @@ -3,4 +3,3 @@ error("Cannot require a meta file") --- TODO #2934 - diff --git a/lua/nvim-tree/_meta/config/help.lua b/lua/nvim-tree/_meta/config/help.lua index 1b49a5e42fd..4ab716dc93a 100644 --- a/lua/nvim-tree/_meta/config/help.lua +++ b/lua/nvim-tree/_meta/config/help.lua @@ -2,4 +2,3 @@ error("Cannot require a meta file") --- TODO #2934 - diff --git a/lua/nvim-tree/_meta/config/live_filter.lua b/lua/nvim-tree/_meta/config/live_filter.lua index 35c36d17667..0642bfae4c3 100644 --- a/lua/nvim-tree/_meta/config/live_filter.lua +++ b/lua/nvim-tree/_meta/config/live_filter.lua @@ -13,4 +13,3 @@ error("Cannot require a meta file") ---Whether to filter folders or not. ---(default: `true`) ---@field always_show_folders? boolean - diff --git a/lua/nvim-tree/_meta/config/log.lua b/lua/nvim-tree/_meta/config/log.lua index cdb408cc264..879da5abb09 100644 --- a/lua/nvim-tree/_meta/config/log.lua +++ b/lua/nvim-tree/_meta/config/log.lua @@ -48,4 +48,3 @@ error("Cannot require a meta file") ---|nvim_tree.Config.FilesystemWatchers| processing, verbose. ---(default: `false`) ---@field watcher? boolean - diff --git a/lua/nvim-tree/_meta/config/renderer.lua b/lua/nvim-tree/_meta/config/renderer.lua index 1b49a5e42fd..4ab716dc93a 100644 --- a/lua/nvim-tree/_meta/config/renderer.lua +++ b/lua/nvim-tree/_meta/config/renderer.lua @@ -2,4 +2,3 @@ error("Cannot require a meta file") --- TODO #2934 - diff --git a/lua/nvim-tree/_meta/config/sort.lua b/lua/nvim-tree/_meta/config/sort.lua index 2407add766c..78b20eed746 100644 --- a/lua/nvim-tree/_meta/config/sort.lua +++ b/lua/nvim-tree/_meta/config/sort.lua @@ -7,4 +7,3 @@ error("Cannot require a meta file") ---@field sorter? nvim_tree.SortOption|fun(nodes: table): nil Changes how files within the same directory are sorted. Can be one of `"name"`, `"case_sensitive"`, `"modification_time"`, `"extension"`, `"suffix"`, `"filetype"` or a function. `"extension"` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz` `"suffix"` uses the last e.g. `.gz` Default: `"name"` Function may perform a sort or return a string with one of the above methods. It is passed a table of nodes to be sorted, each node containing: - `absolute_path`: `string` - `executable`: `boolean` - `extension`: `string` - `filetype`: `string` - `link_to`: `string` - `name`: `string` - `type`: `"directory"` | `"file"` | `"link"` ---@field folders_first? boolean Sort folders before files. Has no effect when |nvim-tree.sort.sorter| is a function. Default: `true` @see nvim-tree.sort.sorter ---@field files_first? boolean Sort files before folders. Has no effect when |nvim-tree.sort.sorter| is a function. If set to `true` it overrides |nvim-tree.sort.folders_first|. Default: `false` @see nvim-tree.sort.sorter @see nvim-tree.sort.folders_first - diff --git a/lua/nvim-tree/_meta/config/system_open.lua b/lua/nvim-tree/_meta/config/system_open.lua index 1b49a5e42fd..4774e75ae1d 100644 --- a/lua/nvim-tree/_meta/config/system_open.lua +++ b/lua/nvim-tree/_meta/config/system_open.lua @@ -1,5 +1,21 @@ ---@meta error("Cannot require a meta file") ---- TODO #2934 - +---Open files or directories via the OS. +--- +---Neovim: +---- `>=` 0.10 uses |vim.ui.open| unless {cmd} is specified +---- `<` 0.10 calls external {cmd}: +--- - UNIX: `xdg-open` +--- - macOS: `open` +--- - Windows: `cmd` +--- +---@class nvim_tree.Config.SystemOpen +--- +---The open command itself +---(default: `xdg-open`, `open` or `cmd`) +---@field cmd? string +--- +---Optional argument list. Leave empty for OS specific default. +---(default: `{}` or `{ "/c", "start", '""' }` on windows) +---@field args? string[] diff --git a/lua/nvim-tree/_meta/config/trash.lua b/lua/nvim-tree/_meta/config/trash.lua index 46ef3c15135..37582670249 100644 --- a/lua/nvim-tree/_meta/config/trash.lua +++ b/lua/nvim-tree/_meta/config/trash.lua @@ -10,4 +10,3 @@ error("Cannot require a meta file") ---External command. ---(default: `gio trash` or `trash`) ---@field cmd? string - diff --git a/lua/nvim-tree/_meta/config/update_focused_file.lua b/lua/nvim-tree/_meta/config/update_focused_file.lua index 1b49a5e42fd..4ab716dc93a 100644 --- a/lua/nvim-tree/_meta/config/update_focused_file.lua +++ b/lua/nvim-tree/_meta/config/update_focused_file.lua @@ -2,4 +2,3 @@ error("Cannot require a meta file") --- TODO #2934 - diff --git a/lua/nvim-tree/_meta/config/view.lua b/lua/nvim-tree/_meta/config/view.lua index 1b49a5e42fd..4ab716dc93a 100644 --- a/lua/nvim-tree/_meta/config/view.lua +++ b/lua/nvim-tree/_meta/config/view.lua @@ -2,4 +2,3 @@ error("Cannot require a meta file") --- TODO #2934 - diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua index ac85f8f8edf..4bda0147cc9 100644 --- a/scripts/gen_vimdoc_config.lua +++ b/scripts/gen_vimdoc_config.lua @@ -14,7 +14,7 @@ local modules = { { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/renderer.lua", }, { helptag = "nvim-tree-config-hijack-directories", title = "Class: Config.HijackDirectories", path = "lua/nvim-tree/_meta/config/hijack_directories.lua", }, { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/update_focused_file.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/system_open.lua", }, + { helptag = "nvim-tree-config-system-open", title = "Class: Config.SystemOpen", path = "lua/nvim-tree/_meta/config/system_open.lua", }, { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/git.lua", }, { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/diagnostics.lua", }, { helptag = "nvim-tree-config-modified", title = "Class: Config.Modified", path = "lua/nvim-tree/_meta/config/modified.lua", }, From e6904843665bd1d1d9d04dcc774b7cf5ad6c3ffa Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 14:36:44 +1100 Subject: [PATCH 024/170] doc(#2934): tidy Config.Help, move into place --- doc/nvim-tree-lua.txt | 27 ++++++++++++++++---------- lua/nvim-tree/_meta/config/actions.lua | 4 ++-- lua/nvim-tree/_meta/config/config.lua | 8 -------- lua/nvim-tree/_meta/config/help.lua | 12 +++++++++++- 4 files changed, 30 insertions(+), 21 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 67dfd98e1e1..846f05b1820 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3655,14 +3655,6 @@ Class: Config *nvim-tree-config* • {cygwin_support}? (`boolean`) Use `cygpath` if available to resolve paths for git. Default: `false` -*nvim_tree.Config.Help* - - Fields: ~ - • {sort_by}? (`nvim_tree.HelpSortOption`) Defines how mappings are - sorted in the help window. Can be `"key"` (sort - alphabetically by keymap) or `"desc"` (sort alphabetically - by description). Default: `"key"` - *nvim_tree.Config.Renderer* Fields: ~ @@ -4240,8 +4232,8 @@ Class: Config.Actions *nvim-tree-config-actions* Fields: ~ • {enable}? (`boolean`) (default: `true`) - • {picker}? (`string|fun(): integer`, default: `"default"`) Change the - default window picker: a string `"default"` or a function. + • {picker}? (`string|fun(): integer`, default: `default`) Change the + default window picker: string `default` or a function. • {chars}? (`string`, default: `"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"`) Identifier characters to use. @@ -4326,6 +4318,21 @@ Class: Config.Notify *nvim-tree-config-notify* +============================================================================== +Class: Config. *nvim-tree-config-YYY* + +*nvim_tree.Config.Help* + Configure help window, default mapping `g?` + + Valid {sort_by}: + • `key`: sort alphabetically by keymap + • `desc`: sort alphabetically by description + + Fields: ~ + • {sort_by}? (`nvim_tree.Config.Help.SortBy`) (default: `key`) + + + ============================================================================== Class: Config.UI *nvim-tree-config-ui* diff --git a/lua/nvim-tree/_meta/config/actions.lua b/lua/nvim-tree/_meta/config/actions.lua index 16fe7d78bb9..e4740d5f20f 100644 --- a/lua/nvim-tree/_meta/config/actions.lua +++ b/lua/nvim-tree/_meta/config/actions.lua @@ -106,8 +106,8 @@ error("Cannot require a meta file") ---(default: `true`) ---@field enable? boolean --- ----Change the default window picker: a string `"default"` or a function. ----(default: `"default"`) +---Change the default window picker: string `default` or a function. +---(default: `default`) ---@field picker? string|fun(): integer --- ---Identifier characters to use. diff --git a/lua/nvim-tree/_meta/config/config.lua b/lua/nvim-tree/_meta/config/config.lua index 5c1043a68e4..0ba6195aeb2 100644 --- a/lua/nvim-tree/_meta/config/config.lua +++ b/lua/nvim-tree/_meta/config/config.lua @@ -9,7 +9,6 @@ error("Cannot require a meta file") ---@alias nvim_tree.HighlightOption "none"|"icon"|"name"|"all" ---@alias nvim_tree.HiddenDisplayOption "none"|"simple"|"all" ---@alias nvim_tree.SortOption "name"|"case_sensitive"|"modification_time"|"extension"|"suffix"|"filetype" ----@alias nvim_tree.HelpSortOption "key"|"desc" -- -- nvim-tree Setup Config @@ -224,13 +223,6 @@ error("Cannot require a meta file") ---@field deleted? string Default: `""` ---@field ignored? string Default: `"◌"` --- --- Help --- - ----@class nvim_tree.Config.Help ----@field sort_by? nvim_tree.HelpSortOption Defines how mappings are sorted in the help window. Can be `"key"` (sort alphabetically by keymap) or `"desc"` (sort alphabetically by description). Default: `"key"` - -- -- Filters -- diff --git a/lua/nvim-tree/_meta/config/help.lua b/lua/nvim-tree/_meta/config/help.lua index 4ab716dc93a..b53438eb478 100644 --- a/lua/nvim-tree/_meta/config/help.lua +++ b/lua/nvim-tree/_meta/config/help.lua @@ -1,4 +1,14 @@ ---@meta error("Cannot require a meta file") ---- TODO #2934 +---@alias nvim_tree.Config.Help.SortBy "key"|"desc" + +---Configure help window, default mapping `g?` +--- +---Valid {sort_by}: +---- `key`: sort alphabetically by keymap +---- `desc`: sort alphabetically by description +---@class nvim_tree.Config.Help +--- +---(default: `key`) +---@field sort_by? nvim_tree.Config.Help.SortBy From 4727f9cdb161a46f5046832416c9b8a98075ae05 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 14:37:19 +1100 Subject: [PATCH 025/170] doc(#2934): tidy Config.Help, move into place --- doc/nvim-tree-lua.txt | 2 +- scripts/gen_vimdoc_config.lua | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 846f05b1820..62d0e1575cf 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -4319,7 +4319,7 @@ Class: Config.Notify *nvim-tree-config-notify* ============================================================================== -Class: Config. *nvim-tree-config-YYY* +Class: Config.Help *nvim-tree-config-help* *nvim_tree.Config.Help* Configure help window, default mapping `g?` diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua index 4bda0147cc9..dab9dbed412 100644 --- a/scripts/gen_vimdoc_config.lua +++ b/scripts/gen_vimdoc_config.lua @@ -25,7 +25,7 @@ local modules = { { helptag = "nvim-tree-config-trash", title = "Class: Config.Trash", path = "lua/nvim-tree/_meta/config/trash.lua", }, { helptag = "nvim-tree-config-tab", title = "Class: Config.Tab", path = "lua/nvim-tree/_meta/config/tab.lua", }, { helptag = "nvim-tree-config-notify", title = "Class: Config.Notify", path = "lua/nvim-tree/_meta/config/notify.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/help.lua", }, + { helptag = "nvim-tree-config-help", title = "Class: Config.Help", path = "lua/nvim-tree/_meta/config/help.lua", }, { helptag = "nvim-tree-config-ui", title = "Class: Config.UI", path = "lua/nvim-tree/_meta/config/ui.lua", name = "UI", }, { helptag = "nvim-tree-config-log", title = "Class: Config.Log", path = "lua/nvim-tree/_meta/config/log.lua", }, From 2384e2bd86c522daea4ca2315e6bffcdb2214e8a Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 15:04:44 +1100 Subject: [PATCH 026/170] doc(#2934): tidy Config.Help, move into place --- doc/nvim-tree-lua.txt | 9 +++++---- lua/nvim-tree/_meta/config/help.lua | 8 +++++--- 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 62d0e1575cf..632f40f2a4f 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -4324,12 +4324,13 @@ Class: Config.Help *nvim-tree-config-help* *nvim_tree.Config.Help* Configure help window, default mapping `g?` - Valid {sort_by}: - • `key`: sort alphabetically by keymap - • `desc`: sort alphabetically by description + *nvim_tree.Config.Help.SortBy* + • `key`: alphabetically by keymap + • `desc`: alphabetically by description Fields: ~ - • {sort_by}? (`nvim_tree.Config.Help.SortBy`) (default: `key`) + • {sort_by}? (`nvim_tree.Config.Help.SortBy`, default: `key`) + |nvim_tree.Config.Help.SortBy| diff --git a/lua/nvim-tree/_meta/config/help.lua b/lua/nvim-tree/_meta/config/help.lua index b53438eb478..8e7b8982dea 100644 --- a/lua/nvim-tree/_meta/config/help.lua +++ b/lua/nvim-tree/_meta/config/help.lua @@ -5,10 +5,12 @@ error("Cannot require a meta file") ---Configure help window, default mapping `g?` --- ----Valid {sort_by}: ----- `key`: sort alphabetically by keymap ----- `desc`: sort alphabetically by description +---[nvim_tree.Config.Help.SortBy]() +---- `key`: alphabetically by keymap +---- `desc`: alphabetically by description +--- ---@class nvim_tree.Config.Help --- +---|nvim_tree.Config.Help.SortBy| ---(default: `key`) ---@field sort_by? nvim_tree.Config.Help.SortBy From dbdf8466455cd90b2493f910a59c079292cd9639 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 15:32:19 +1100 Subject: [PATCH 027/170] doc(#2934): tidy Config.Diagnostics, move into place --- doc/nvim-tree-lua.txt | 80 +++++++++++----------- lua/nvim-tree/_meta/api_decorator.lua | 2 + lua/nvim-tree/_meta/config/config.lua | 24 ------- lua/nvim-tree/_meta/config/diagnostics.lua | 53 +++++++++++++- lua/nvim-tree/_meta/config/sort.lua | 2 + scripts/gen_vimdoc_config.lua | 2 +- 6 files changed, 98 insertions(+), 65 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 632f40f2a4f..a82c555b280 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3547,45 +3547,6 @@ Class: Config *nvim-tree-config* • {log}? (`nvim_tree.Config.Log`) |nvim_tree.Config.Log| -*nvim_tree.Config.Diagnostics* - - Fields: ~ - • {enable}? (`boolean`) Enable/disable the feature. Default: - `false` - • {debounce_delay}? (`integer`) Idle milliseconds between diagnostic - event and update. Default: `500` (ms) - • {show_on_dirs}? (`boolean`) Show diagnostic icons on parent - directories. Default: `false` - • {show_on_open_dirs}? (`boolean`) Show diagnostics icons on - directories that are open. Only relevant when - `diagnostics.show_on_dirs` is `true`. Default: - `true` @see nvim-tree.diagnostics.show_on_dirs - • {severity}? (`nvim_tree.Config.Diagnostics.Severity`) - Severity for which the diagnostics will be - displayed. See |diagnostic-severity| @see - nvim-tree.diagnostics.icons - • {icons}? (`nvim_tree.Config.Diagnostics.Icons`) Icons for - diagnostic severity. - • {diagnostic_opts}? (`boolean`) vim.diagnostic.Opts overrides - nvim-tree.diagnostics.severity and - nvim-tree.diagnostics.icons Default: `false` - -*nvim_tree.Config.Diagnostics.Icons* - - Fields: ~ - • {hint}? (`string`) Default: `""` - • {info}? (`string`) Default: `""` - • {warning}? (`string`) Default: `""` - • {error}? (`string`) Default: `""` - -*nvim_tree.Config.Diagnostics.Severity* - - Fields: ~ - • {min}? (`vim.diagnostic.Severity`) Minimum severity. Default: - `vim.diagnostic.severity.HINT` - • {max}? (`vim.diagnostic.Severity`) Maximum severity. Default: - `vim.diagnostic.severity.ERROR` - *nvim_tree.Config.Filters* Fields: ~ @@ -4082,6 +4043,47 @@ Class: Config.SystemOpen *nvim-tree-config-system-open* +============================================================================== +Class: Config.Diagnostics *nvim-tree-config-diagnostics* + +*nvim_tree.Config.Diagnostics* + Integrate with |lsp| or COC diagnostics. + + Fields: ~ + • {enable}? (`boolean`) (default: `false`) + • {debounce_delay}? (`integer`, default: `500`) Idle milliseconds + between diagnostic event and tree update. + • {show_on_dirs}? (`boolean`, default: `false`) Show diagnostic + icons on parent directories. + • {show_on_open_dirs}? (`boolean`, default: `true`) Show diagnostics + icons on directories that are open. Only + relevant when {show_on_dirs} is `true`. + • {diagnostic_opts}? (`boolean`, default: `false`) Global + |vim.diagnostic.Opts| overrides {severity} and + {icons} + • {severity}? (`nvim_tree.Config.Diagnostics.Severity`) + |nvim_tree.Config.Diagnostics.Severity| + • {icons}? (`nvim_tree.Config.Diagnostics.Icons`) + |nvim_tree.Config.Diagnostics.Icons| + +*nvim_tree.Config.Diagnostics.Icons* + + Fields: ~ + • {hint}? (`string`) (default: ) + • {info}? (`string`) (default: ) + • {warning}? (`string`) (default: ) + • {error}? (`string`) (default: ) + +*nvim_tree.Config.Diagnostics.Severity* + + Fields: ~ + • {min}? (`vim.diagnostic.Severity`, default: HINT) + |vim.diagnostic.Severity| + • {max}? (`vim.diagnostic.Severity`, default: ERROR) + |vim.diagnostic.Severity| + + + ============================================================================== Class: Config.Modified *nvim-tree-config-modified* diff --git a/lua/nvim-tree/_meta/api_decorator.lua b/lua/nvim-tree/_meta/api_decorator.lua index f194ca120ee..b56b53b4431 100644 --- a/lua/nvim-tree/_meta/api_decorator.lua +++ b/lua/nvim-tree/_meta/api_decorator.lua @@ -1,6 +1,8 @@ ---@meta error("Cannot require a meta file") +-- TODO #2934 add enum docs + ---Highlight group range as per nvim-tree.renderer.highlight_* ---@alias nvim_tree.api.decorator.HighlightRange "none" | "icon" | "name" | "all" diff --git a/lua/nvim-tree/_meta/config/config.lua b/lua/nvim-tree/_meta/config/config.lua index 0ba6195aeb2..02d5c506751 100644 --- a/lua/nvim-tree/_meta/config/config.lua +++ b/lua/nvim-tree/_meta/config/config.lua @@ -8,7 +8,6 @@ error("Cannot require a meta file") ---@alias nvim_tree.PlacementOption "before"|"after"|"signcolumn"|"right_align" ---@alias nvim_tree.HighlightOption "none"|"icon"|"name"|"all" ---@alias nvim_tree.HiddenDisplayOption "none"|"simple"|"all" ----@alias nvim_tree.SortOption "name"|"case_sensitive"|"modification_time"|"extension"|"suffix"|"filetype" -- -- nvim-tree Setup Config @@ -262,29 +261,6 @@ error("Cannot require a meta file") ---@field timeout? integer Kills the git process after some time if it takes too long. Git integration will be disabled after 10 git jobs exceed this timeout. Default: `400` (ms) ---@field cygwin_support? boolean Use `cygpath` if available to resolve paths for git. Default: `false` --- --- Diagnostics --- - ----@class nvim_tree.Config.Diagnostics ----@field enable? boolean Enable/disable the feature. Default: `false` ----@field debounce_delay? integer Idle milliseconds between diagnostic event and update. Default: `500` (ms) ----@field show_on_dirs? boolean Show diagnostic icons on parent directories. Default: `false` ----@field show_on_open_dirs? boolean Show diagnostics icons on directories that are open. Only relevant when `diagnostics.show_on_dirs` is `true`. Default: `true` @see nvim-tree.diagnostics.show_on_dirs ----@field severity? nvim_tree.Config.Diagnostics.Severity Severity for which the diagnostics will be displayed. See |diagnostic-severity| @see nvim-tree.diagnostics.icons ----@field icons? nvim_tree.Config.Diagnostics.Icons Icons for diagnostic severity. ----@field diagnostic_opts? boolean vim.diagnostic.Opts overrides nvim-tree.diagnostics.severity and nvim-tree.diagnostics.icons Default: `false` - ----@class nvim_tree.Config.Diagnostics.Severity ----@field min? vim.diagnostic.Severity Minimum severity. Default: `vim.diagnostic.severity.HINT` ----@field max? vim.diagnostic.Severity Maximum severity. Default: `vim.diagnostic.severity.ERROR` - ----@class nvim_tree.Config.Diagnostics.Icons ----@field hint? string Default: `""` ----@field info? string Default: `""` ----@field warning? string Default: `""` ----@field error? string Default: `""` - -- -- View -- diff --git a/lua/nvim-tree/_meta/config/diagnostics.lua b/lua/nvim-tree/_meta/config/diagnostics.lua index 4ab716dc93a..ac6ed35c1cb 100644 --- a/lua/nvim-tree/_meta/config/diagnostics.lua +++ b/lua/nvim-tree/_meta/config/diagnostics.lua @@ -1,4 +1,55 @@ ---@meta error("Cannot require a meta file") ---- TODO #2934 +---Integrate with |lsp| or COC diagnostics. +--- +---@class nvim_tree.Config.Diagnostics +--- +---(default: `false`) +---@field enable? boolean +--- +---Idle milliseconds between diagnostic event and tree update. +---(default: `500`) +---@field debounce_delay? integer +--- +---Show diagnostic icons on parent directories. +---(default: `false`) +---@field show_on_dirs? boolean +--- +---Show diagnostics icons on directories that are open. Only relevant when {show_on_dirs} is `true`. +---(default: `true`) +---@field show_on_open_dirs? boolean +--- +---Global |vim.diagnostic.Opts| overrides {severity} and {icons} +---(default: `false`) +---@field diagnostic_opts? boolean +--- +---|nvim_tree.Config.Diagnostics.Severity| +---@field severity? nvim_tree.Config.Diagnostics.Severity +--- +---|nvim_tree.Config.Diagnostics.Icons| +---@field icons? nvim_tree.Config.Diagnostics.Icons + +---@class nvim_tree.Config.Diagnostics.Severity +--- +---|vim.diagnostic.Severity| +---(default: HINT) +---@field min? vim.diagnostic.Severity +--- +---|vim.diagnostic.Severity| +---(default: ERROR) +---@field max? vim.diagnostic.Severity + +---@class nvim_tree.Config.Diagnostics.Icons +--- +---(default: ) +---@field hint? string +--- +---(default: ) +---@field info? string +--- +---(default: ) +---@field warning? string +--- +---(default: ) +---@field error? string diff --git a/lua/nvim-tree/_meta/config/sort.lua b/lua/nvim-tree/_meta/config/sort.lua index 78b20eed746..5268fa96ff5 100644 --- a/lua/nvim-tree/_meta/config/sort.lua +++ b/lua/nvim-tree/_meta/config/sort.lua @@ -3,6 +3,8 @@ error("Cannot require a meta file") --- TODO #2934 +---@alias nvim_tree.SortOption "name"|"case_sensitive"|"modification_time"|"extension"|"suffix"|"filetype" + ---@class nvim_tree.Config.Sort ---@field sorter? nvim_tree.SortOption|fun(nodes: table): nil Changes how files within the same directory are sorted. Can be one of `"name"`, `"case_sensitive"`, `"modification_time"`, `"extension"`, `"suffix"`, `"filetype"` or a function. `"extension"` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz` `"suffix"` uses the last e.g. `.gz` Default: `"name"` Function may perform a sort or return a string with one of the above methods. It is passed a table of nodes to be sorted, each node containing: - `absolute_path`: `string` - `executable`: `boolean` - `extension`: `string` - `filetype`: `string` - `link_to`: `string` - `name`: `string` - `type`: `"directory"` | `"file"` | `"link"` ---@field folders_first? boolean Sort folders before files. Has no effect when |nvim-tree.sort.sorter| is a function. Default: `true` @see nvim-tree.sort.sorter diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua index dab9dbed412..88e534cc371 100644 --- a/scripts/gen_vimdoc_config.lua +++ b/scripts/gen_vimdoc_config.lua @@ -16,7 +16,7 @@ local modules = { { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/update_focused_file.lua", }, { helptag = "nvim-tree-config-system-open", title = "Class: Config.SystemOpen", path = "lua/nvim-tree/_meta/config/system_open.lua", }, { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/git.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/diagnostics.lua", }, + { helptag = "nvim-tree-config-diagnostics", title = "Class: Config.Diagnostics", path = "lua/nvim-tree/_meta/config/diagnostics.lua", }, { helptag = "nvim-tree-config-modified", title = "Class: Config.Modified", path = "lua/nvim-tree/_meta/config/modified.lua", }, { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/filters.lua", }, { helptag = "nvim-tree-config-live-filter", title = "Class: Config.LiveFilter", path = "lua/nvim-tree/_meta/config/live_filter.lua", }, From 6faff066119739f5bb6af009d9f88fa297139765 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 15:39:05 +1100 Subject: [PATCH 028/170] doc(#2934): remove api/decorator as they are out of scope, revert api_decorator.lua changes, retain api opts classes but make them exact --- doc/nvim-tree-lua.txt | 152 -------------------------- lua/nvim-tree/_meta/api.lua | 20 ++-- lua/nvim-tree/_meta/api_decorator.lua | 24 ++-- scripts/gen_vimdoc_config.lua | 4 +- 4 files changed, 24 insertions(+), 176 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index a82c555b280..137361cc260 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -4392,156 +4392,4 @@ Class: Config.Log *nvim-tree-config-log* -============================================================================== -Lua module: nvim_tree.api *nvim-tree-api* - -*nvim_tree.api.CollapseOpts* - - Fields: ~ - • {keep_buffers}? (`boolean`) do not collapse nodes with open buffers - -*nvim_tree.api.NodeBufferOpts* - - Fields: ~ - • {force}? (`boolean`) delete/wipe even if buffer is modified, default - false - -*nvim_tree.api.NodeEditOpts* - - Fields: ~ - • {quit_on_open}? (`boolean`) quits the tree when opening the file - • {focus}? (`boolean`) keep focus in the tree when opening the - file - -*nvim_tree.api.TreeExpandOpts* - - Fields: ~ - • {expand_until}? (`fun(expansion_count: integer, node: Node): boolean`) - Return true if node should be expanded. - expansion_count is the total number of folders - expanded. - -*nvim_tree.api.TreeFindFileOpts* - - Fields: ~ - • {buf}? (`string|number`) absolute/relative path OR bufnr - to find - • {open}? (`boolean`) open the tree if necessary - • {current_window}? (`boolean`) requires open, open in the current - window - • {winid}? (`number`) open the tree in the specified |winid|, - overrides current_window - • {update_root}? (`boolean`) see - |nvim-tree.update_focused_file.update_root| - • {focus}? (`boolean`) focus the tree - -*nvim_tree.api.TreeIsVisibleOpts* - - Fields: ~ - • {tabpage}? (`number`) as per |nvim_get_current_tabpage()| - • {any_tabpage}? (`boolean`) visible on any tab, default false - -*nvim_tree.api.TreeOpenOpts* - - Fields: ~ - • {path}? (`string`) root directory for the tree - • {current_window}? (`boolean`) open the tree in the current window - • {winid}? (`number`) open the tree in the specified winid, - overrides current_window - • {find_file}? (`boolean`) find the current buffer - • {update_root}? (`boolean`) requires find_file, see - |nvim-tree.update_focused_file.update_root| - • {focus}? (`boolean`) focus the tree when opening, default - true - -*nvim_tree.api.TreeResizeOpts* - - Fields: ~ - • {width}? (`string|function|number|table`) new - |nvim-tree.view.width| value - • {absolute}? (`number`) set the width - • {relative}? (`number`) relative width adjustment - -*nvim_tree.api.TreeToggleOpts* - - Fields: ~ - • {path}? (`string`) root directory for the tree - • {current_window}? (`boolean`) open the tree in the current window - • {winid}? (`number`) open the tree in the specified |winid|, - overrides current_window - • {find_file}? (`boolean`) find the current buffer - • {update_root}? (`boolean`) requires find_file, see - |nvim-tree.update_focused_file.update_root| - • {focus}? (`boolean`) focus the tree when opening, default - true - -*nvim_tree.api.TreeWinIdOpts* - - Fields: ~ - • {tabpage}? (`number`) tabpage, 0 or nil for current, default nil - - - -============================================================================== -Lua module: nvim_tree.api.decorator *nvim-tree-api-decorator* - -*nvim_tree.api.decorator.UserDecorator* - Custom decorator, see :help nvim-tree-decorators - - Fields: ~ - • {enabled} (`boolean`) - • {highlight_range} (`nvim_tree.api.decorator.HighlightRange`) - • {icon_placement} (`nvim_tree.api.decorator.IconPlacement`) - • {extend} (`fun(self: nvim_tree.api.decorator.UserDecorator)`) - See |UserDecorator:extend()|. - • {new} (`fun(self: nvim_tree.api.decorator.UserDecorator)`) - See |UserDecorator:new()|. - • {icon_node} (`fun(self: nvim_tree.api.decorator.UserDecorator, node: nvim_tree.api.Node): nvim_tree.api.HighlightedString?`) - See |UserDecorator:icon_node()|. - • {icons} (`fun(self: nvim_tree.api.decorator.UserDecorator, node: nvim_tree.api.Node): nvim_tree.api.HighlightedString[]?`) - See |UserDecorator:icons()|. - • {highlight_group} (`fun(self: nvim_tree.api.decorator.UserDecorator, node: nvim_tree.api.Node): string?`) - See |UserDecorator:highlight_group()|. - - -UserDecorator:extend() *nvim_tree.api.decorator.UserDecorator:extend()* - Create your decorator class - - *nvim_tree.api.decorator.UserDecorator:highlight_group()* -UserDecorator:highlight_group({node}) - Abstract: optionally implement to provide one highlight group to apply to - your highlight_range. - - Parameters: ~ - • {node} (`nvim_tree.api.Node`) - - Return: ~ - (`string?`) highlight_group - - *nvim_tree.api.decorator.UserDecorator:icon_node()* -UserDecorator:icon_node({node}) - Abstract: optionally implement to set the node's icon - - Parameters: ~ - • {node} (`nvim_tree.api.Node`) - - Return: ~ - (`nvim_tree.api.HighlightedString?`) icon_node - - *nvim_tree.api.decorator.UserDecorator:icons()* -UserDecorator:icons({node}) - Abstract: optionally implement to provide icons and the highlight groups - for your icon_placement. - - Parameters: ~ - • {node} (`nvim_tree.api.Node`) - - Return: ~ - (`nvim_tree.api.HighlightedString[]?`) icons - -UserDecorator:new() *nvim_tree.api.decorator.UserDecorator:new()* - Abstract: no-args constructor must be implemented and will be called once - per tree render. Must set all fields. - - vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: diff --git a/lua/nvim-tree/_meta/api.lua b/lua/nvim-tree/_meta/api.lua index dd5f0c32a93..fabd8e0c943 100644 --- a/lua/nvim-tree/_meta/api.lua +++ b/lua/nvim-tree/_meta/api.lua @@ -5,7 +5,7 @@ error("Cannot require a meta file") -- API Options -- ----@class nvim_tree.api.TreeOpenOpts +---@class (exact) nvim_tree.api.TreeOpenOpts ---@field path? string root directory for the tree ---@field current_window? boolean open the tree in the current window ---@field winid? number open the tree in the specified winid, overrides current_window @@ -13,7 +13,7 @@ error("Cannot require a meta file") ---@field update_root? boolean requires find_file, see |nvim-tree.update_focused_file.update_root| ---@field focus? boolean focus the tree when opening, default true ----@class nvim_tree.api.TreeToggleOpts +---@class (exact) nvim_tree.api.TreeToggleOpts ---@field path? string root directory for the tree ---@field current_window? boolean open the tree in the current window ---@field winid? number open the tree in the specified |winid|, overrides current_window @@ -21,12 +21,12 @@ error("Cannot require a meta file") ---@field update_root? boolean requires find_file, see |nvim-tree.update_focused_file.update_root| ---@field focus? boolean focus the tree when opening, default true ----@class nvim_tree.api.TreeResizeOpts +---@class (exact) nvim_tree.api.TreeResizeOpts ---@field width? string|function|number|table new |nvim-tree.view.width| value ---@field absolute? number set the width ---@field relative? number relative width adjustment ----@class nvim_tree.api.TreeFindFileOpts +---@class (exact) nvim_tree.api.TreeFindFileOpts ---@field buf? string|number absolute/relative path OR bufnr to find ---@field open? boolean open the tree if necessary ---@field current_window? boolean requires open, open in the current window @@ -34,24 +34,24 @@ error("Cannot require a meta file") ---@field update_root? boolean see |nvim-tree.update_focused_file.update_root| ---@field focus? boolean focus the tree ----@class nvim_tree.api.CollapseOpts +---@class (exact) nvim_tree.api.CollapseOpts ---@field keep_buffers? boolean do not collapse nodes with open buffers ----@class nvim_tree.api.TreeExpandOpts +---@class (exact) nvim_tree.api.TreeExpandOpts ---@field expand_until? (fun(expansion_count: integer, node: Node): boolean) Return true if node should be expanded. expansion_count is the total number of folders expanded. ----@class nvim_tree.api.TreeIsVisibleOpts +---@class (exact) nvim_tree.api.TreeIsVisibleOpts ---@field tabpage? number as per |nvim_get_current_tabpage()| ---@field any_tabpage? boolean visible on any tab, default false ----@class nvim_tree.api.TreeWinIdOpts +---@class (exact) nvim_tree.api.TreeWinIdOpts ---@field tabpage? number tabpage, 0 or nil for current, default nil ----@class nvim_tree.api.NodeEditOpts +---@class (exact) nvim_tree.api.NodeEditOpts ---@field quit_on_open? boolean quits the tree when opening the file ---@field focus? boolean keep focus in the tree when opening the file ----@class nvim_tree.api.NodeBufferOpts +---@class (exact) nvim_tree.api.NodeBufferOpts ---@field force? boolean delete/wipe even if buffer is modified, default false -- diff --git a/lua/nvim-tree/_meta/api_decorator.lua b/lua/nvim-tree/_meta/api_decorator.lua index b56b53b4431..d85fe02fff0 100644 --- a/lua/nvim-tree/_meta/api_decorator.lua +++ b/lua/nvim-tree/_meta/api_decorator.lua @@ -1,7 +1,7 @@ ---@meta error("Cannot require a meta file") --- TODO #2934 add enum docs +local nvim_tree = { api = { decorator = {} } } ---Highlight group range as per nvim-tree.renderer.highlight_* ---@alias nvim_tree.api.decorator.HighlightRange "none" | "icon" | "name" | "all" @@ -14,41 +14,41 @@ error("Cannot require a meta file") ---Custom decorator, see :help nvim-tree-decorators --- ----@class nvim_tree.api.decorator.UserDecorator ----@field enabled boolean ----@field highlight_range nvim_tree.api.decorator.HighlightRange ----@field icon_placement nvim_tree.api.decorator.IconPlacement -local UserDecorator = {} +---@class (exact) nvim_tree.api.decorator.UserDecorator +---@field protected enabled boolean +---@field protected highlight_range nvim_tree.api.decorator.HighlightRange +---@field protected icon_placement nvim_tree.api.decorator.IconPlacement +nvim_tree.api.decorator.UserDecorator = {} ---Create your decorator class --- -function UserDecorator:extend() end +function nvim_tree.api.decorator.UserDecorator:extend() end ---Abstract: no-args constructor must be implemented and will be called once per tree render. ---Must set all fields. --- -function UserDecorator:new() end +function nvim_tree.api.decorator.UserDecorator:new() end ---Abstract: optionally implement to set the node's icon --- ---@param node nvim_tree.api.Node ---@return nvim_tree.api.HighlightedString? icon_node -function UserDecorator:icon_node(node) end +function nvim_tree.api.decorator.UserDecorator:icon_node(node) end ---Abstract: optionally implement to provide icons and the highlight groups for your icon_placement. --- ---@param node nvim_tree.api.Node ---@return nvim_tree.api.HighlightedString[]? icons -function UserDecorator:icons(node) end +function nvim_tree.api.decorator.UserDecorator:icons(node) end ---Abstract: optionally implement to provide one highlight group to apply to your highlight_range. --- ---@param node nvim_tree.api.Node ---@return string? highlight_group -function UserDecorator:highlight_group(node) end +function nvim_tree.api.decorator.UserDecorator:highlight_group(node) end ---Define a sign. This should be called in the constructor. --- ---@protected ---@param icon nvim_tree.api.HighlightedString? -function UserDecorator:define_sign(icon) end +function nvim_tree.api.decorator.UserDecorator:define_sign(icon) end diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua index 88e534cc371..8e41d793210 100644 --- a/scripts/gen_vimdoc_config.lua +++ b/scripts/gen_vimdoc_config.lua @@ -29,8 +29,8 @@ local modules = { { helptag = "nvim-tree-config-ui", title = "Class: Config.UI", path = "lua/nvim-tree/_meta/config/ui.lua", name = "UI", }, { helptag = "nvim-tree-config-log", title = "Class: Config.Log", path = "lua/nvim-tree/_meta/config/log.lua", }, - { helptag = "nvim-tree-api", title = "Lua module: nvim_tree.api", path = "lua/nvim-tree/_meta/api.lua", }, - { helptag = "nvim-tree-api-decorator", title = "Lua module: nvim_tree.api.decorator", path = "lua/nvim-tree/_meta/api_decorator.lua", }, + -- { helptag = "nvim-tree-api", title = "Lua module: nvim_tree.api", path = "lua/nvim-tree/_meta/api.lua", }, + -- { helptag = "nvim-tree-api-decorator", title = "Lua module: nvim_tree.api.decorator", path = "lua/nvim-tree/_meta/api_decorator.lua", }, } -- hydrate file names From 25545823513be0caad6a2b795926252258cf8af0 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 18:23:45 +1100 Subject: [PATCH 029/170] doc(#2934): tidy Config.Filters, move into place --- doc/nvim-tree-lua.txt | 102 ++++++++++++++----------- lua/nvim-tree/_meta/config/config.lua | 14 ---- lua/nvim-tree/_meta/config/filters.lua | 68 ++++++++++++++++- scripts/gen_vimdoc_config.lua | 40 +++++----- 4 files changed, 145 insertions(+), 79 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 137361cc260..cdbb76fe04a 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3547,50 +3547,6 @@ Class: Config *nvim-tree-config* • {log}? (`nvim_tree.Config.Log`) |nvim_tree.Config.Log| -*nvim_tree.Config.Filters* - - Fields: ~ - • {enable}? (`boolean`) Enable / disable all filters including - live filter. Toggle via - |nvim-tree-api.tree.toggle_enable_filters()| Default: - `true` - • {git_ignored}? (`boolean`) Ignore files based on `.gitignore`. - Requires |git.enable| `= true` Toggle via - |nvim-tree-api.tree.toggle_gitignore_filter()|, - default `I` Default: `true` - • {dotfiles}? (`boolean`) Do not show dotfiles: files starting with - a `.` Toggle via - |nvim-tree-api.tree.toggle_hidden_filter()|, default - `H` Default: `false` - • {git_clean}? (`boolean`) Do not show files with no git status. This - will show ignored files when - |nvim-tree.filters.git_ignored| is set, as they are - effectively dirty. Toggle via - |nvim-tree-api.tree.toggle_git_clean_filter()|, - default `C` Default: `false` - • {no_buffer}? (`boolean`) Do not show files that have no - |buflisted()| buffer. Toggle via - |nvim-tree-api.tree.toggle_no_buffer_filter()|, - default `B` For performance reasons this may not - immediately update on buffer delete/wipe. A reload or - filesystem event will result in an update. Default: - `false` - • {no_bookmark}? (`boolean`) Do not show files that are not bookmarked. - Toggle via - |nvim-tree-api.tree.toggle_no_bookmark_filter()|, - default `M` Enabling this is not useful as there is no - means yet to persist bookmarks. Default: `false` - • {custom}? (`string[]|fun(absolute_path: string): boolean`) - Custom list of vim regex for file/directory names that - will not be shown. Backslashes must be escaped e.g. - "^\\.git". See |string-match|. Toggle via - |nvim-tree-api.tree.toggle_custom_filter()|, default - `U` Default: `{}` - • {exclude}? (`string[]`) List of directories or files to exclude - from filtering: always show them. Overrides - `filters.git_ignored`, `filters.dotfiles` and - `filters.custom`. Default: `{}` - *nvim_tree.Config.Git* Fields: ~ @@ -4104,6 +4060,64 @@ Class: Config.Modified *nvim-tree-config-modified* +============================================================================== +Class: Config.Filters *nvim-tree-config-filters* + + +Filters may be applied to the tree to exlude the display of file and directories. + +Multiple filters may be applied at once. + +Filters can be set at startup and toggled live via API with default keymappings. + +`I` {git_ignored} |nvim-tree-api.tree.toggle_gitignore_filter()| + Ignore files based on `.gitignore`. + Requires |nvim_tree.Config.Git| {enable} + +`H` {dotfiles} |nvim-tree-api.tree.toggle_hidden_filter()| + Filter dotfiles: files starting with a `.` + +`C` {git_clean} |nvim-tree-api.tree.toggle_git_clean_filter()| + Filter files with no git status. + Git ignored files will not be filtered when {git_ignored}, as they are + effectively dirty. + +`B` {no_buffer} |nvim-tree-api.tree.toggle_no_buffer_filter()| + Filter files that have no |buflisted()| buffer. + For performance reasons this may not immediately update on buffer delete/wipe. + A reload or filesystem event will result in an update. + +`M` {no_bookmark} |nvim-tree-api.tree.toggle_no_bookmark_filter()| + Filter files that are not bookmarked. + Enabling this is not useful as there is no means yet to persist bookmarks. + +`U` {custom} |nvim-tree-api.tree.toggle_custom_filter()| + Disable file/directory names via: + a list of backslash escaped |vim.regex| strings e.g. `"^\\.git""` + OR a function passed the absolute path of the directory. + +All filters including live filter may be disabled via {enable} and toggled +with |nvim-tree-api.tree.toggle_enable_filters()| + +Files/directories may be {exclude}d from filtering: they will always be shown, +overriding {git_ignored}, {dotfiles} and {custom} + + +*nvim_tree.Config.Filters* + + Fields: ~ + • {enable}? (`boolean`, default: `true`) Enable all filters. + • {git_ignored}? (`boolean`) (default: `true`) + • {dotfiles}? (`boolean`) (default: `false`) + • {git_clean}? (`boolean`) (default: `false`) + • {no_buffer}? (`boolean`) (default: `false`) + • {no_bookmark}? (`boolean`) (default: `false`) + • {custom}? (`string[]|fun(absolute_path: string): boolean`) + (default: `{}`) + • {exclude}? (`string[]`) (default: `{}`) + + + ============================================================================== Class: Config.LiveFilter *nvim-tree-config-live-filter* diff --git a/lua/nvim-tree/_meta/config/config.lua b/lua/nvim-tree/_meta/config/config.lua index 02d5c506751..ad0da316073 100644 --- a/lua/nvim-tree/_meta/config/config.lua +++ b/lua/nvim-tree/_meta/config/config.lua @@ -222,20 +222,6 @@ error("Cannot require a meta file") ---@field deleted? string Default: `""` ---@field ignored? string Default: `"◌"` --- --- Filters --- - ----@class nvim_tree.Config.Filters ----@field enable? boolean Enable / disable all filters including live filter. Toggle via |nvim-tree-api.tree.toggle_enable_filters()| Default: `true` ----@field git_ignored? boolean Ignore files based on `.gitignore`. Requires |git.enable| `= true` Toggle via |nvim-tree-api.tree.toggle_gitignore_filter()|, default `I` Default: `true` ----@field dotfiles? boolean Do not show dotfiles: files starting with a `.` Toggle via |nvim-tree-api.tree.toggle_hidden_filter()|, default `H` Default: `false` ----@field git_clean? boolean Do not show files with no git status. This will show ignored files when |nvim-tree.filters.git_ignored| is set, as they are effectively dirty. Toggle via |nvim-tree-api.tree.toggle_git_clean_filter()|, default `C` Default: `false` ----@field no_buffer? boolean Do not show files that have no |buflisted()| buffer. Toggle via |nvim-tree-api.tree.toggle_no_buffer_filter()|, default `B` For performance reasons this may not immediately update on buffer delete/wipe. A reload or filesystem event will result in an update. Default: `false` ----@field no_bookmark? boolean Do not show files that are not bookmarked. Toggle via |nvim-tree-api.tree.toggle_no_bookmark_filter()|, default `M` Enabling this is not useful as there is no means yet to persist bookmarks. Default: `false` ----@field custom? string[]|fun(absolute_path: string): boolean Custom list of vim regex for file/directory names that will not be shown. Backslashes must be escaped e.g. "^\\.git". See |string-match|. Toggle via |nvim-tree-api.tree.toggle_custom_filter()|, default `U` Default: `{}` ----@field exclude? string[] List of directories or files to exclude from filtering: always show them. Overrides `filters.git_ignored`, `filters.dotfiles` and `filters.custom`. Default: `{}` - -- -- Update Focused File -- diff --git a/lua/nvim-tree/_meta/config/filters.lua b/lua/nvim-tree/_meta/config/filters.lua index 4ab716dc93a..4e36dad893d 100644 --- a/lua/nvim-tree/_meta/config/filters.lua +++ b/lua/nvim-tree/_meta/config/filters.lua @@ -1,4 +1,70 @@ ---@meta error("Cannot require a meta file") ---- TODO #2934 +---@brief +---
help
+---Filters may be applied to the tree to exlude the display of file and directories.
+---
+---Multiple filters may be applied at once.
+---
+---Filters can be set at startup and toggled live via API with default keymappings.
+---
+---`I`    {git_ignored}    |nvim-tree-api.tree.toggle_gitignore_filter()|
+---   Ignore files based on `.gitignore`.
+---   Requires |nvim_tree.Config.Git| {enable}
+---
+---`H`    {dotfiles}       |nvim-tree-api.tree.toggle_hidden_filter()|
+---   Filter dotfiles: files starting with a `.`
+---
+---`C`    {git_clean}      |nvim-tree-api.tree.toggle_git_clean_filter()|
+---   Filter files with no git status.
+---   Git ignored files will not be filtered when {git_ignored}, as they are
+---   effectively dirty.
+---
+---`B`    {no_buffer}      |nvim-tree-api.tree.toggle_no_buffer_filter()|
+---   Filter files that have no |buflisted()| buffer.
+---   For performance reasons this may not immediately update on buffer delete/wipe.
+---   A reload or filesystem event will result in an update.
+---
+---`M`    {no_bookmark}    |nvim-tree-api.tree.toggle_no_bookmark_filter()|
+---   Filter files that are not bookmarked.
+---   Enabling this is not useful as there is no means yet to persist bookmarks.
+---
+---`U`    {custom}         |nvim-tree-api.tree.toggle_custom_filter()|
+---   Disable file/directory names via:
+---   a list of backslash escaped |vim.regex| strings e.g. `"^\\.git""`
+---   OR a function passed the absolute path of the directory.
+---
+---All filters including live filter may be disabled via {enable} and toggled
+---with |nvim-tree-api.tree.toggle_enable_filters()|
+---
+---Files/directories may be {exclude}d from filtering: they will always be shown,
+---overriding {git_ignored}, {dotfiles} and {custom}
+---
+ +---@class nvim_tree.Config.Filters +--- +---Enable all filters. +---(default: `true`) +---@field enable? boolean +--- +---(default: `true`) +---@field git_ignored? boolean +--- +---(default: `false`) +---@field dotfiles? boolean +--- +---(default: `false`) +---@field git_clean? boolean +--- +---(default: `false`) +---@field no_buffer? boolean +--- +---(default: `false`) +---@field no_bookmark? boolean +--- +---(default: `{}`) +---@field custom? string[]|fun(absolute_path: string): boolean +--- +---(default: `{}`) +---@field exclude? string[] diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua index 8e41d793210..e9aab29c82a 100644 --- a/scripts/gen_vimdoc_config.lua +++ b/scripts/gen_vimdoc_config.lua @@ -8,26 +8,26 @@ ---Generated within help files in this order ---@type Module[] local modules = { - { helptag = "nvim-tree-config", title = "Class: Config", path = "lua/nvim-tree/_meta/config/config.lua", }, - { helptag = "nvim-tree-config-sort", title = "Class: Config.Sort", path = "lua/nvim-tree/_meta/config/sort.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/view.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/renderer.lua", }, - { helptag = "nvim-tree-config-hijack-directories", title = "Class: Config.HijackDirectories", path = "lua/nvim-tree/_meta/config/hijack_directories.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/update_focused_file.lua", }, - { helptag = "nvim-tree-config-system-open", title = "Class: Config.SystemOpen", path = "lua/nvim-tree/_meta/config/system_open.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/git.lua", }, - { helptag = "nvim-tree-config-diagnostics", title = "Class: Config.Diagnostics", path = "lua/nvim-tree/_meta/config/diagnostics.lua", }, - { helptag = "nvim-tree-config-modified", title = "Class: Config.Modified", path = "lua/nvim-tree/_meta/config/modified.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/filters.lua", }, - { helptag = "nvim-tree-config-live-filter", title = "Class: Config.LiveFilter", path = "lua/nvim-tree/_meta/config/live_filter.lua", }, - { helptag = "nvim-tree-config-filesystem-watchers", title = "Class: Config.FilesystemWatchers", path = "lua/nvim-tree/_meta/config/filesystem_watchers.lua", }, - { helptag = "nvim-tree-config-actions", title = "Class: Config.Actions", path = "lua/nvim-tree/_meta/config/actions.lua", }, - { helptag = "nvim-tree-config-trash", title = "Class: Config.Trash", path = "lua/nvim-tree/_meta/config/trash.lua", }, - { helptag = "nvim-tree-config-tab", title = "Class: Config.Tab", path = "lua/nvim-tree/_meta/config/tab.lua", }, - { helptag = "nvim-tree-config-notify", title = "Class: Config.Notify", path = "lua/nvim-tree/_meta/config/notify.lua", }, - { helptag = "nvim-tree-config-help", title = "Class: Config.Help", path = "lua/nvim-tree/_meta/config/help.lua", }, - { helptag = "nvim-tree-config-ui", title = "Class: Config.UI", path = "lua/nvim-tree/_meta/config/ui.lua", name = "UI", }, - { helptag = "nvim-tree-config-log", title = "Class: Config.Log", path = "lua/nvim-tree/_meta/config/log.lua", }, + { helptag = "nvim-tree-config", title = "Class: Config", path = "lua/nvim-tree/_meta/config/config.lua", }, + { helptag = "nvim-tree-config-sort", title = "Class: Config.Sort", path = "lua/nvim-tree/_meta/config/sort.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/view.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/renderer.lua", }, + { helptag = "nvim-tree-config-hijack-directories", title = "Class: Config.HijackDirectories", path = "lua/nvim-tree/_meta/config/hijack_directories.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/update_focused_file.lua", }, + { helptag = "nvim-tree-config-system-open", title = "Class: Config.SystemOpen", path = "lua/nvim-tree/_meta/config/system_open.lua", }, + { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/git.lua", }, + { helptag = "nvim-tree-config-diagnostics", title = "Class: Config.Diagnostics", path = "lua/nvim-tree/_meta/config/diagnostics.lua", }, + { helptag = "nvim-tree-config-modified", title = "Class: Config.Modified", path = "lua/nvim-tree/_meta/config/modified.lua", }, + { helptag = "nvim-tree-config-filters", title = "Class: Config.Filters", path = "lua/nvim-tree/_meta/config/filters.lua", }, + { helptag = "nvim-tree-config-live-filter", title = "Class: Config.LiveFilter", path = "lua/nvim-tree/_meta/config/live_filter.lua", }, + { helptag = "nvim-tree-config-filesystem-watchers", title = "Class: Config.FilesystemWatchers", path = "lua/nvim-tree/_meta/config/filesystem_watchers.lua", }, + { helptag = "nvim-tree-config-actions", title = "Class: Config.Actions", path = "lua/nvim-tree/_meta/config/actions.lua", }, + { helptag = "nvim-tree-config-trash", title = "Class: Config.Trash", path = "lua/nvim-tree/_meta/config/trash.lua", }, + { helptag = "nvim-tree-config-tab", title = "Class: Config.Tab", path = "lua/nvim-tree/_meta/config/tab.lua", }, + { helptag = "nvim-tree-config-notify", title = "Class: Config.Notify", path = "lua/nvim-tree/_meta/config/notify.lua", }, + { helptag = "nvim-tree-config-help", title = "Class: Config.Help", path = "lua/nvim-tree/_meta/config/help.lua", }, + { helptag = "nvim-tree-config-ui", title = "Class: Config.UI", path = "lua/nvim-tree/_meta/config/ui.lua", name = "UI", }, + { helptag = "nvim-tree-config-log", title = "Class: Config.Log", path = "lua/nvim-tree/_meta/config/log.lua", }, -- { helptag = "nvim-tree-api", title = "Lua module: nvim_tree.api", path = "lua/nvim-tree/_meta/api.lua", }, -- { helptag = "nvim-tree-api-decorator", title = "Lua module: nvim_tree.api.decorator", path = "lua/nvim-tree/_meta/api_decorator.lua", }, From 3fea7f4fc98a9f16242c8e05957ca726cfbbf8fc Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 18:29:15 +1100 Subject: [PATCH 030/170] doc(#2934): tidy Config.FilesystemWatchers, move into place --- doc/nvim-tree-lua.txt | 4 ++-- lua/nvim-tree/_meta/config/filesystem_watchers.lua | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index cdbb76fe04a..b5729b7f347 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -4159,8 +4159,8 @@ Class: Config.FilesystemWatchers *nvim-tree-config-filesystem-watchers* • {debounce_delay}? (`integer`, default: `50`) Idle milliseconds between filesystem change and tree update. • {ignore_dirs}? (`string[]|fun(path: string): boolean`, default: `{ "/.ccls-cache", "/build", "/node_modules", "/target", }`) - Disable for directories via a list of vim regex OR - a function passed the absolute path of the + Disable for directories via a list of |vim regex| + OR a function passed the absolute path of the directory. diff --git a/lua/nvim-tree/_meta/config/filesystem_watchers.lua b/lua/nvim-tree/_meta/config/filesystem_watchers.lua index f1fd6095081..ab2bb4c6c2e 100644 --- a/lua/nvim-tree/_meta/config/filesystem_watchers.lua +++ b/lua/nvim-tree/_meta/config/filesystem_watchers.lua @@ -19,6 +19,6 @@ error("Cannot require a meta file") ---(default: `50`) ---@field debounce_delay? integer --- ----Disable for directories via a list of vim regex OR a function passed the absolute path of the directory. +---Disable for directories via a list of |vim regex| OR a function passed the absolute path of the directory. ---(default: `{ "/.ccls-cache", "/build", "/node_modules", "/target", }`) ---@field ignore_dirs? string[]|fun(path: string): boolean From 1988d5e65eaefbadf2f87783f6b9da5d164d68c4 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Fri, 9 Jan 2026 17:28:38 +1100 Subject: [PATCH 031/170] doc(#2934): tidy Config.FilesystemWatchers, Git, move into place --- doc/nvim-tree-lua.txt | 76 ++++++++++--------- lua/nvim-tree/_meta/{config => }/config.lua | 11 --- .../_meta/config/filesystem_watchers.lua | 13 ++-- lua/nvim-tree/_meta/config/git.lua | 34 ++++++++- scripts/gen_vimdoc_config.lua | 4 +- 5 files changed, 80 insertions(+), 58 deletions(-) rename lua/nvim-tree/_meta/{config => }/config.lua (94%) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index b5729b7f347..6b8bd0fec9b 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3547,31 +3547,6 @@ Class: Config *nvim-tree-config* • {log}? (`nvim_tree.Config.Log`) |nvim_tree.Config.Log| -*nvim_tree.Config.Git* - - Fields: ~ - • {enable}? (`boolean`) Enable / disable the feature. - Default: `true` - • {show_on_dirs}? (`boolean`) Show status icons of children when - directory itself has no status icon. Default: - `true` - • {show_on_open_dirs}? (`boolean`) Show status icons of children on - directories that are open. Only relevant when - `git.show_on_dirs` is `true`. Default: `true` - @see nvim-tree.git.show_on_dirs - • {disable_for_dirs}? (`string[]|fun(path: string): boolean`) Disable - git integration when git top-level matches these - paths. Strings may be relative, evaluated via - |fnamemodify| `:p` Function is passed an - absolute path and returns true for disable. - Default: `{}` - • {timeout}? (`integer`) Kills the git process after some - time if it takes too long. Git integration will - be disabled after 10 git jobs exceed this - timeout. Default: `400` (ms) - • {cygwin_support}? (`boolean`) Use `cygpath` if available to - resolve paths for git. Default: `false` - *nvim_tree.Config.Renderer* Fields: ~ @@ -3999,6 +3974,38 @@ Class: Config.SystemOpen *nvim-tree-config-system-open* +============================================================================== +Class: Config.Git *nvim-tree-config-git* + +*nvim_tree.Config.Git* + Git operations are run in the background thus status may not immediately + appear. + + Processes will be killed if they exceed {timeout}ms. Git integration will + be disabled following 5 timeouts and you will be notified. + + Git integration may be disabled for git top-level directories via + {disable_for_dirs}: + • A list of relative paths evaluated with |fnamemodify| `:p` OR + • A function that is passed an absolute path and returns `true` to disable + + Fields: ~ + • {enable}? (`boolean`) (default: `true`) + • {show_on_dirs}? (`boolean`, default: `true`) Show status icons + of children when directory itself has no status + icon + • {show_on_open_dirs}? (`boolean`, default: `true`) Show status icons + of children on directories that are open. Only + relevant when {show_on_dirs} is `true`. + • {disable_for_dirs}? (`string[]|fun(path: string): boolean`, default: + `{}`) Disable for top level paths. + • {timeout}? (`integer`, default: `400`) `git` processes + timeout milliseconds. + • {cygwin_support}? (`boolean`, default: `false`) Use `cygpath` if + available to resolve paths for git. + + + ============================================================================== Class: Config.Diagnostics *nvim-tree-config-diagnostics* @@ -4143,25 +4150,22 @@ Class: Config.FilesystemWatchers *nvim-tree-config-filesystem-watchers* Use file system watchers (libuv fs_event) to monitor the filesystem for changes and update the tree. - With this feature, the tree will be updated only for the appropriate - folder change, resulting in better performance. + With this feature, the tree will be partially updated on specific + directory changes, resulting in better performance. Watchers may be disabled for absolute directory paths via {ignore_dirs}. - Useful when path is not in `.gitignore` or git integration is disabled. - - |vim.regex| strings must be backslash escaped e.g. `"my-proj/\\.build$"` - - Using this will disable |BufEnter| and |BufWritePost| events in nvim-tree - which were used to update the whole tree. + • A list of |vim regex| to match a path, backslash escaped e.g. + `"my-proj/\\.build$"` OR + • A function that is passed an absolute path and returns `true` to disable + This may be useful when a path is not in `.gitignore` or git integration + is disabled. Fields: ~ • {enable}? (`boolean`) (default: `true`) • {debounce_delay}? (`integer`, default: `50`) Idle milliseconds between filesystem change and tree update. • {ignore_dirs}? (`string[]|fun(path: string): boolean`, default: `{ "/.ccls-cache", "/build", "/node_modules", "/target", }`) - Disable for directories via a list of |vim regex| - OR a function passed the absolute path of the - directory. + Disable for directories. diff --git a/lua/nvim-tree/_meta/config/config.lua b/lua/nvim-tree/_meta/config.lua similarity index 94% rename from lua/nvim-tree/_meta/config/config.lua rename to lua/nvim-tree/_meta/config.lua index ad0da316073..56a814a6fbc 100644 --- a/lua/nvim-tree/_meta/config/config.lua +++ b/lua/nvim-tree/_meta/config.lua @@ -235,17 +235,6 @@ error("Cannot require a meta file") ---@field enable? boolean Default: `false` ---@field ignore_list? string[] List of buffer names and filetypes that will not update the root dir of the tree if the file isn't found under the current root directory. Only relevant when `update_focused_file.update_root.enable` and `update_focused_file.enable` are `true`. Default: `{}` @see nvim-tree.update_focused_file.update_root.enable @see nvim-tree.update_focused_file.enable --- --- Git --- - ----@class nvim_tree.Config.Git ----@field enable? boolean Enable / disable the feature. Default: `true` ----@field show_on_dirs? boolean Show status icons of children when directory itself has no status icon. Default: `true` ----@field show_on_open_dirs? boolean Show status icons of children on directories that are open. Only relevant when `git.show_on_dirs` is `true`. Default: `true` @see nvim-tree.git.show_on_dirs ----@field disable_for_dirs? string[]|fun(path: string): boolean Disable git integration when git top-level matches these paths. Strings may be relative, evaluated via |fnamemodify| `:p` Function is passed an absolute path and returns true for disable. Default: `{}` ----@field timeout? integer Kills the git process after some time if it takes too long. Git integration will be disabled after 10 git jobs exceed this timeout. Default: `400` (ms) ----@field cygwin_support? boolean Use `cygpath` if available to resolve paths for git. Default: `false` -- -- View diff --git a/lua/nvim-tree/_meta/config/filesystem_watchers.lua b/lua/nvim-tree/_meta/config/filesystem_watchers.lua index ab2bb4c6c2e..48553261d77 100644 --- a/lua/nvim-tree/_meta/config/filesystem_watchers.lua +++ b/lua/nvim-tree/_meta/config/filesystem_watchers.lua @@ -3,13 +3,12 @@ error("Cannot require a meta file") ---Use file system watchers (libuv fs_event) to monitor the filesystem for changes and update the tree. --- ----With this feature, the tree will be updated only for the appropriate folder change, resulting in better performance. +---With this feature, the tree will be partially updated on specific directory changes, resulting in better performance. --- ----Watchers may be disabled for absolute directory paths via {ignore_dirs}. Useful when path is not in `.gitignore` or git integration is disabled. ---- ----|vim.regex| strings must be backslash escaped e.g. `"my-proj/\\.build$"` ---- ----Using this will disable |BufEnter| and |BufWritePost| events in nvim-tree which were used to update the whole tree. +---Watchers may be disabled for absolute directory paths via {ignore_dirs}. +--- - A list of |vim regex| to match a path, backslash escaped e.g. `"my-proj/\\.build$"` OR +--- - A function that is passed an absolute path and returns `true` to disable +---This may be useful when a path is not in `.gitignore` or git integration is disabled. ---@class nvim_tree.Config.FilesystemWatchers --- ---(default: `true`) @@ -19,6 +18,6 @@ error("Cannot require a meta file") ---(default: `50`) ---@field debounce_delay? integer --- ----Disable for directories via a list of |vim regex| OR a function passed the absolute path of the directory. +---Disable for directories. ---(default: `{ "/.ccls-cache", "/build", "/node_modules", "/target", }`) ---@field ignore_dirs? string[]|fun(path: string): boolean diff --git a/lua/nvim-tree/_meta/config/git.lua b/lua/nvim-tree/_meta/config/git.lua index f64f27300c9..4df33102433 100644 --- a/lua/nvim-tree/_meta/config/git.lua +++ b/lua/nvim-tree/_meta/config/git.lua @@ -1,5 +1,35 @@ ---@meta error("Cannot require a meta file") - ---- TODO #2934 +---Git operations are run in the background thus status may not immediately appear. +--- +---Processes will be killed if they exceed {timeout}ms. Git integration will be disabled following 5 timeouts and you will be notified. +--- +---Git integration may be disabled for git top-level directories via {disable_for_dirs}: +--- - A list of relative paths evaluated with |fnamemodify| `:p` OR +--- - A function that is passed an absolute path and returns `true` to disable +--- +---@class nvim_tree.Config.Git +--- +---(default: `true`) +---@field enable? boolean +--- +---Show status icons of children when directory itself has no status icon +---(default: `true`) +---@field show_on_dirs? boolean +--- +---Show status icons of children on directories that are open. Only relevant when {show_on_dirs} is `true`. +---(default: `true`) +---@field show_on_open_dirs? boolean +--- +---Disable for top level paths. +---(default: `{}`) +---@field disable_for_dirs? string[]|fun(path: string): boolean +--- +---`git` processes timeout milliseconds. +---(default: `400`) +---@field timeout? integer +--- +---Use `cygpath` if available to resolve paths for git. +---(Default: `false`) +---@field cygwin_support? boolean diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua index e9aab29c82a..6c3bed50a7e 100644 --- a/scripts/gen_vimdoc_config.lua +++ b/scripts/gen_vimdoc_config.lua @@ -8,14 +8,14 @@ ---Generated within help files in this order ---@type Module[] local modules = { - { helptag = "nvim-tree-config", title = "Class: Config", path = "lua/nvim-tree/_meta/config/config.lua", }, + { helptag = "nvim-tree-config", title = "Class: Config", path = "lua/nvim-tree/_meta/config.lua", }, { helptag = "nvim-tree-config-sort", title = "Class: Config.Sort", path = "lua/nvim-tree/_meta/config/sort.lua", }, { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/view.lua", }, { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/renderer.lua", }, { helptag = "nvim-tree-config-hijack-directories", title = "Class: Config.HijackDirectories", path = "lua/nvim-tree/_meta/config/hijack_directories.lua", }, { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/update_focused_file.lua", }, { helptag = "nvim-tree-config-system-open", title = "Class: Config.SystemOpen", path = "lua/nvim-tree/_meta/config/system_open.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/git.lua", }, + { helptag = "nvim-tree-config-git", title = "Class: Config.Git", path = "lua/nvim-tree/_meta/config/git.lua", }, { helptag = "nvim-tree-config-diagnostics", title = "Class: Config.Diagnostics", path = "lua/nvim-tree/_meta/config/diagnostics.lua", }, { helptag = "nvim-tree-config-modified", title = "Class: Config.Modified", path = "lua/nvim-tree/_meta/config/modified.lua", }, { helptag = "nvim-tree-config-filters", title = "Class: Config.Filters", path = "lua/nvim-tree/_meta/config/filters.lua", }, From 23295082247f677116bd83da5ff2b129763ade84 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Fri, 9 Jan 2026 17:56:27 +1100 Subject: [PATCH 032/170] doc(#2934): tidy Config.UpdateFocusedFile, move into place --- doc/nvim-tree-lua.txt | 61 ++++++++++--------- lua/nvim-tree/_meta/config.lua | 13 ---- .../_meta/config/update_focused_file.lua | 30 ++++++++- scripts/gen_vimdoc_config.lua | 2 +- 4 files changed, 62 insertions(+), 44 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 6b8bd0fec9b..55037204b4c 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3803,35 +3803,6 @@ Class: Config *nvim-tree-config* • {bottom}? (`string`) Default: `"─"` • {none}? (`string`) Default: `" "` -*nvim_tree.Config.UpdateFocusedFile* - - Fields: ~ - • {enable}? (`boolean`) Enable this feature. Default: `false` - • {update_root}? (`nvim_tree.Config.UpdateFocusedFile.UpdateRoot`) - Update the root directory of the tree if the file is - not under current root directory. It prefers vim's cwd - and `root_dirs`. Otherwise it falls back to the folder - containing the file. Only relevant when - `update_focused_file.enable` is `true` @see - nvim-tree.update_focused_file.enable - • {exclude}? (`fun(args: vim.api.keyset.create_autocmd.callback_args): boolean`) - A function that returns true if the file should not be - focused when opening. Takes the `BufEnter` event as an - argument. see |autocmd-events| Default: `false` - -*nvim_tree.Config.UpdateFocusedFile.UpdateRoot* - - Fields: ~ - • {enable}? (`boolean`) Default: `false` - • {ignore_list}? (`string[]`) List of buffer names and filetypes that - will not update the root dir of the tree if the file - isn't found under the current root directory. Only - relevant when `update_focused_file.update_root.enable` - and `update_focused_file.enable` are `true`. Default: - `{}` @see - nvim-tree.update_focused_file.update_root.enable @see - nvim-tree.update_focused_file.enable - *nvim_tree.Config.View* Fields: ~ @@ -3952,6 +3923,38 @@ Class: Config.HijackDirectories *nvim-tree-config-hijack-directories* +============================================================================== +Class: Config.UpdateFocusedFile *nvim-tree-config-update-focused-file* + +*nvim_tree.Config.UpdateFocusedFile* + Update the focused file on |BufEnter|, uncollapsing folders recursively. + + Fields: ~ + • {enable}? (`boolean`) (default: `false`) + • {update_root}? (`nvim_tree.Config.UpdateFocusedFile.UpdateRoot`) + |nvim_tree.Config.UpdateFocusedFile.UpdateRoot| + • {exclude}? (`fun(args: vim.api.keyset.create_autocmd.callback_args): boolean`, default: `false`) + A function called on |BufEnter| that returns true if + the file should not be focused when opening. + +*nvim_tree.Config.UpdateFocusedFile.UpdateRoot* + Update the root directory of the tree if the file is not under the current + root directory. + + Prefers vim's cwd and |nvim_tree.Config| {root_dirs}, falling back to the + directory containing the file. + + Only relevant when |nvim_tree.Config.UpdateFocusedFile| {enable} is `true` + + Fields: ~ + • {enable}? (`boolean`) (default: `false`) + • {ignore_list}? (`string[]`, default: `{}`) List of buffer names and + filetypes that will not update the root dir of the + tree if the file isn't found under the current root + directory. + + + ============================================================================== Class: Config.SystemOpen *nvim-tree-config-system-open* diff --git a/lua/nvim-tree/_meta/config.lua b/lua/nvim-tree/_meta/config.lua index 56a814a6fbc..3c082b2ee2c 100644 --- a/lua/nvim-tree/_meta/config.lua +++ b/lua/nvim-tree/_meta/config.lua @@ -222,19 +222,6 @@ error("Cannot require a meta file") ---@field deleted? string Default: `""` ---@field ignored? string Default: `"◌"` --- --- Update Focused File --- - ----@class nvim_tree.Config.UpdateFocusedFile ----@field enable? boolean Enable this feature. Default: `false` ----@field update_root? nvim_tree.Config.UpdateFocusedFile.UpdateRoot Update the root directory of the tree if the file is not under current root directory. It prefers vim's cwd and `root_dirs`. Otherwise it falls back to the folder containing the file. Only relevant when `update_focused_file.enable` is `true` @see nvim-tree.update_focused_file.enable ----@field exclude? fun(args: vim.api.keyset.create_autocmd.callback_args): boolean A function that returns true if the file should not be focused when opening. Takes the `BufEnter` event as an argument. see |autocmd-events| Default: `false` - ----@class nvim_tree.Config.UpdateFocusedFile.UpdateRoot ----@field enable? boolean Default: `false` ----@field ignore_list? string[] List of buffer names and filetypes that will not update the root dir of the tree if the file isn't found under the current root directory. Only relevant when `update_focused_file.update_root.enable` and `update_focused_file.enable` are `true`. Default: `{}` @see nvim-tree.update_focused_file.update_root.enable @see nvim-tree.update_focused_file.enable - -- -- View diff --git a/lua/nvim-tree/_meta/config/update_focused_file.lua b/lua/nvim-tree/_meta/config/update_focused_file.lua index 4ab716dc93a..81fea09ad8c 100644 --- a/lua/nvim-tree/_meta/config/update_focused_file.lua +++ b/lua/nvim-tree/_meta/config/update_focused_file.lua @@ -1,4 +1,32 @@ ---@meta error("Cannot require a meta file") ---- TODO #2934 +---Update the focused file on |BufEnter|, uncollapsing folders recursively. +--- +---@class nvim_tree.Config.UpdateFocusedFile +--- +---(default: `false`) +---@field enable? boolean +--- +---|nvim_tree.Config.UpdateFocusedFile.UpdateRoot| +---@field update_root? nvim_tree.Config.UpdateFocusedFile.UpdateRoot +--- +---A function called on |BufEnter| that returns true if the file should not be focused when opening. +---(default: `false`) +---@field exclude? fun(args: vim.api.keyset.create_autocmd.callback_args): boolean + + +---Update the root directory of the tree if the file is not under the current root directory. +--- +---Prefers vim's cwd and |nvim_tree.Config| {root_dirs}, falling back to the directory containing the file. +--- +---Only relevant when |nvim_tree.Config.UpdateFocusedFile| {enable} is `true` +--- +---@class nvim_tree.Config.UpdateFocusedFile.UpdateRoot +--- +---(default: `false`) +---@field enable? boolean +--- +---List of buffer names and filetypes that will not update the root dir of the tree if the file isn't found under the current root directory. +---(default: `{}`) +---@field ignore_list? string[] diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua index 6c3bed50a7e..0e220f85f95 100644 --- a/scripts/gen_vimdoc_config.lua +++ b/scripts/gen_vimdoc_config.lua @@ -13,7 +13,7 @@ local modules = { { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/view.lua", }, { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/renderer.lua", }, { helptag = "nvim-tree-config-hijack-directories", title = "Class: Config.HijackDirectories", path = "lua/nvim-tree/_meta/config/hijack_directories.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/update_focused_file.lua", }, + { helptag = "nvim-tree-config-update-focused-file", title = "Class: Config.UpdateFocusedFile", path = "lua/nvim-tree/_meta/config/update_focused_file.lua", }, { helptag = "nvim-tree-config-system-open", title = "Class: Config.SystemOpen", path = "lua/nvim-tree/_meta/config/system_open.lua", }, { helptag = "nvim-tree-config-git", title = "Class: Config.Git", path = "lua/nvim-tree/_meta/config/git.lua", }, { helptag = "nvim-tree-config-diagnostics", title = "Class: Config.Diagnostics", path = "lua/nvim-tree/_meta/config/diagnostics.lua", }, From c961bd4a2728cf50c4d801ecf26e4d5b768a9581 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sat, 10 Jan 2026 13:34:04 +1100 Subject: [PATCH 033/170] doc(#2934): tidy Config.Sort, move into place --- doc/nvim-tree-lua.txt | 54 +++++++++++++++++------------ lua/nvim-tree/_meta/config/sort.lua | 43 +++++++++++++++++++---- 2 files changed, 68 insertions(+), 29 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 55037204b4c..3289f51b660 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3877,31 +3877,39 @@ Class: Config *nvim-tree-config* Class: Config.Sort *nvim-tree-config-sort* *nvim_tree.Config.Sort* + Sort files within a directory. + + {sorter} builtin |nvim_tree.Config.Sort.Sorter|: + • `name` + • `case_sensitive` name + • `modification_time` + • `extension` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz` + • `suffix` uses the last e.g. `foo.tar.gz` -> `.gz` + • `filetype` |filetype| + + {sorter} may be a function that is passed a list of |nvim_tree.api.Node| + to be sorted in place e.g. >lua + + ---Sort by name length + ---@param nodes nvim_tree.api.Node[] + ---@return nvim_tree.Config.Sort.Sorter? + local sorter = function(nodes) + table.sort(nodes, function(a, b) + return #a.name < #b.name + end) + end +< + + Alternatively, the function may return a |nvim_tree.Config.Sort.Sorter| Fields: ~ - • {sorter}? (`nvim_tree.SortOption|fun(nodes: table): nil`) - Changes how files within the same directory are - sorted. Can be one of `"name"`, `"case_sensitive"`, - `"modification_time"`, `"extension"`, `"suffix"`, - `"filetype"` or a function. `"extension"` uses all - suffixes e.g. `foo.tar.gz` -> `.tar.gz` `"suffix"` - uses the last e.g. `.gz` Default: `"name"` Function - may perform a sort or return a string with one of - the above methods. It is passed a table of nodes to - be sorted, each node containing: - `absolute_path`: - `string` - `executable`: `boolean` - `extension`: - `string` - `filetype`: `string` - `link_to`: - `string` - `name`: `string` - `type`: `"directory"` - | `"file"` | `"link"` - • {folders_first}? (`boolean`) Sort folders before files. Has no effect - when |nvim-tree.sort.sorter| is a function. Default: - `true` @see nvim-tree.sort.sorter - • {files_first}? (`boolean`) Sort files before folders. Has no effect - when |nvim-tree.sort.sorter| is a function. If set - to `true` it overrides - |nvim-tree.sort.folders_first|. Default: `false` - @see nvim-tree.sort.sorter @see - nvim-tree.sort.folders_first + • {sorter}? (`nvim_tree.Config.Sort.Sorter|fun(nodes: nvim_tree.api.Node[]): nvim_tree.Config.Sort.Sorter?`) + (default: `name`) + • {folders_first}? (`boolean`, default: `true`) Sort folders before + files. Has no effect when {sorter} is a function. + • {files_first}? (`boolean`, default: `false`) Sort files before + folders. Has no effect when {sorter} is a function. + Overrides {folders_first}. diff --git a/lua/nvim-tree/_meta/config/sort.lua b/lua/nvim-tree/_meta/config/sort.lua index 5268fa96ff5..a78e2dc833b 100644 --- a/lua/nvim-tree/_meta/config/sort.lua +++ b/lua/nvim-tree/_meta/config/sort.lua @@ -1,11 +1,42 @@ ---@meta error("Cannot require a meta file") ---- TODO #2934 - ----@alias nvim_tree.SortOption "name"|"case_sensitive"|"modification_time"|"extension"|"suffix"|"filetype" +---@alias nvim_tree.Config.Sort.Sorter "name"|"case_sensitive"|"modification_time"|"extension"|"suffix"|"filetype" +---Sort files within a directory. +--- +---{sorter} builtin |nvim_tree.Config.Sort.Sorter|: +---- `name` +---- `case_sensitive` name +---- `modification_time` +---- `extension` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz` +---- `suffix` uses the last e.g. `foo.tar.gz` -> `.gz` +---- `filetype` |filetype| +--- +---{sorter} may be a function that is passed a list of |nvim_tree.api.Node| to be sorted in place e.g. +---```lua +--- +------Sort by name length +------@param nodes nvim_tree.api.Node[] +------@return nvim_tree.Config.Sort.Sorter? +---local sorter = function(nodes) +--- table.sort(nodes, function(a, b) +--- return #a.name < #b.name +--- end) +---end +---``` +---Alternatively, the function may return a |nvim_tree.Config.Sort.Sorter| +--- ---@class nvim_tree.Config.Sort ----@field sorter? nvim_tree.SortOption|fun(nodes: table): nil Changes how files within the same directory are sorted. Can be one of `"name"`, `"case_sensitive"`, `"modification_time"`, `"extension"`, `"suffix"`, `"filetype"` or a function. `"extension"` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz` `"suffix"` uses the last e.g. `.gz` Default: `"name"` Function may perform a sort or return a string with one of the above methods. It is passed a table of nodes to be sorted, each node containing: - `absolute_path`: `string` - `executable`: `boolean` - `extension`: `string` - `filetype`: `string` - `link_to`: `string` - `name`: `string` - `type`: `"directory"` | `"file"` | `"link"` ----@field folders_first? boolean Sort folders before files. Has no effect when |nvim-tree.sort.sorter| is a function. Default: `true` @see nvim-tree.sort.sorter ----@field files_first? boolean Sort files before folders. Has no effect when |nvim-tree.sort.sorter| is a function. If set to `true` it overrides |nvim-tree.sort.folders_first|. Default: `false` @see nvim-tree.sort.sorter @see nvim-tree.sort.folders_first +--- +---(default: `name`) +---@field sorter? nvim_tree.Config.Sort.Sorter|fun(nodes: nvim_tree.api.Node[]): nvim_tree.Config.Sort.Sorter? +--- +---Sort folders before files. Has no effect when {sorter} is a function. +---(default: `true`) +---@field folders_first? boolean +--- +---Sort files before folders. Has no effect when {sorter} is a function. Overrides {folders_first}. +---(default: `false`) +---@field files_first? boolean +--- From 745fc546c4ac6b694c5a2bed50d8a039a2f4f485 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sat, 10 Jan 2026 15:06:54 +1100 Subject: [PATCH 034/170] doc(#2934): tidy Config.View, move into place --- doc/nvim-tree-lua.txt | 170 ++++++++++++++----------- lua/nvim-tree/_meta/config.lua | 41 +----- lua/nvim-tree/_meta/config/actions.lua | 38 ++---- lua/nvim-tree/_meta/config/view.lua | 102 ++++++++++++++- scripts/gen_vimdoc_config.lua | 2 +- 5 files changed, 218 insertions(+), 135 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 3289f51b660..352e4635287 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3462,6 +3462,7 @@ highlight group is not, hard linking as follows: > Class: Config *nvim-tree-config* *nvim_tree.Config* + TODO #2934 brief and some links Fields: ~ • {on_attach}? (`string|fun(bufnr: integer)`) Runs when @@ -3803,74 +3804,6 @@ Class: Config *nvim-tree-config* • {bottom}? (`string`) Default: `"─"` • {none}? (`string`) Default: `" "` -*nvim_tree.Config.View* - - Fields: ~ - • {adaptive_size}? (`boolean`) Resize the window on each - draw based on the longest line. - Default: `false` - • {centralize_selection}? (`boolean`) When entering nvim-tree, - reposition the view so that the - current node is initially centralized, - see |zz|. Default: `false` - • {side}? (`nvim_tree.PlacementOption`) Side of - the tree. Default: `"left"` - • {preserve_window_proportions}? (`boolean`) Preserves window - proportions when opening a file. If - `false`, the height and width of - windows other than nvim-tree will be - equalized. Default: `false` - • {number}? (`boolean`) Print the line number in - front of each line. Default: `false` - • {relativenumber}? (`boolean`) Show the line number - relative to the line with the cursor - in front of each line. Default: - `false` - • {signcolumn}? (`nvim_tree.HiddenDisplayOption`) Show - |signcolumn|. Default: `"yes"` - • {width}? (`string|integer|nvim_tree.Config.View.Width|fun(): integer|string`) - Width of the window: can be a `%` - string, a number representing columns, - a function or a table. A table - indicates that the view should be - dynamically sized based on the longest - line. Default: `30` - • {float}? (`nvim_tree.Config.View.Float`) - Configuration options for floating - window. - • {cursorline}? (`boolean`) Enable |cursorline| in - nvim-tree window. Default: `true` - • {debounce_delay}? (`integer`) Idle milliseconds before - some reload / refresh operations. - Increase if you experience performance - issues around screen refresh. Default: - `15` (ms) - -*nvim_tree.Config.View.Float* - - Fields: ~ - • {enable}? (`boolean`) If true, tree window will be - floating. Default: `false` - • {quit_on_focus_loss}? (`boolean`) Close the floating tree window when - it loses focus. Default: `true` - • {open_win_config}? (`table|fun(): table`) Floating window config. - See |nvim_open_win()| for more details. - Default: - `{ relative = "editor", border = "rounded", width = 30, height = 30, row = 1, col = 1, }` - -*nvim_tree.Config.View.Width* - - Fields: ~ - • {min}? (`string|integer|fun(): integer|string`) Minimum - dynamic width. Default: `30` - • {max}? (`string|integer|fun(): integer|string`) Maximum - dynamic width, -1 for unbounded. Default: `-1` - • {lines_excluded}? (`string[]`) Exclude these lines when computing - width. Supported values: `"root"`. Default: - `{ "root" }` - • {padding}? (`integer|fun(): integer|string`) Extra padding to - the right. Default: `1` - ============================================================================== @@ -3913,6 +3846,91 @@ Class: Config.Sort *nvim-tree-config-sort* +============================================================================== +Class: Config.View *nvim-tree-config-view* + +*nvim_tree.Config.View* + Configures the dimensions and appearance of the nvim-tree window. + + Window widths are generally defined by a |nvim_tree.Config.View.WidthOpt|: + • string: `%` string e.g. `30%` + • integer: number of columns + • function: returns one of the above + + {width} can be a |nvim_tree.Config.View.WidthOpt| for simple static + control or a |nvim_tree.Config.View.Width| for fully dynamic control based + on longest line. + + The window is "docked" at the left by default, however may be configured + to float: |nvim_tree.Config.View.Float| + + Fields: ~ + • {centralize_selection}? (`boolean`, default: `false`) When + entering nvim-tree, reposition the + view so that the current node is + initially centralized, see |zz|. + • {cursorline}? (`boolean`, default: `true`) Set + |cursorline| + • {cursorlineopt}? (`string`, default: `both`) Set + |cursorlineopt| + • {debounce_delay}? (`integer`, default: `15`) Idle + milliseconds before some reload / + refresh operations. Increase if you + experience performance issues around + screen refresh. + • {side}? (`"left"|"right"`) (default: `left`) + • {preserve_window_proportions}? (`boolean`, default: `false`) + Preserves window proportions when + opening a file. If `false`, the height + and width of windows other than + nvim-tree will be equalized. + • {number}? (`boolean`, default: `false`) Set + |number| + • {relativenumber}? (`boolean`, default: `false`) Set + |relativenumber| + • {signcolumn}? (`"yes"|"auto"|"no"`, default: `yes`) + Set |signcolumn|. + • {width}? (`nvim_tree.Config.View.WidthOpt|nvim_tree.Config.View.Width`) + (default: `30`) + • {float}? (`nvim_tree.Config.View.Float`) + |nvim_tree.Config.View.Float| + +*nvim_tree.Config.View.Float* + Configure floating window behaviour + + |vim.api.keyset.win_config| {open_win_config} is passed directly to + |nvim_open_win|, default: >lua + { + relative = "editor", + border = "rounded", + width = 30, + height = 30, + row = 1, + col = 1, + } +< + + Fields: ~ + • {enable}? (`boolean`) (default: `false`) + • {quit_on_focus_loss}? (`boolean`, default: `true`) Close the floating + window when it loses focus. + • {open_win_config}? (`vim.api.keyset.win_config|fun(): vim.api.keyset.win_config`) + (default: above) + +*nvim_tree.Config.View.Width* + Configure dynamic width based on longest line. + + Fields: ~ + • {min}? (`nvim_tree.Config.View.WidthOpt`) (default: `30`) + • {max}? (`nvim_tree.Config.View.WidthOpt`, default: `-1`) + -1 for unbounded. + • {lines_excluded}? (`("root")[]`, default: `{ "root" }`) Exclude these + lines when computing width. + • {padding}? (`nvim_tree.Config.View.WidthOpt`, default: `1`) + Extra padding to the right. + + + ============================================================================== Class: Config.HijackDirectories *nvim-tree-config-hijack-directories* @@ -4227,14 +4245,24 @@ Class: Config.Actions *nvim-tree-config-actions* `{ ".git", "target", "build" }` *nvim_tree.Config.Actions.FilePopup* - Configuration for file_popup floating window, see |nvim_open_win| + Configuration for file_popup floating window. + + |vim.api.keyset.win_config| {open_win_config} is passed directly to + |nvim_open_win|, default: >lua + { + col = 1, + row = 1, + relative = "cursor", + border = "shadow", + style = "minimal", + } +< You shouldn't define |vim.api.keyset.win_config| {width} and {height} values here. They will be overridden to fit the file_popup content. Fields: ~ - • {open_win_config}? (`vim.api.keyset.win_config`, default: `{ col = 1, row = 1, relative = "cursor", border = "shadow", style = "minimal", }`) - Neovim window config. + • {open_win_config}? (`vim.api.keyset.win_config`) (default: above) *nvim_tree.Config.Actions.OpenFile* Configuration options for opening a file from nvim-tree. diff --git a/lua/nvim-tree/_meta/config.lua b/lua/nvim-tree/_meta/config.lua index 3c082b2ee2c..a333ad60bd5 100644 --- a/lua/nvim-tree/_meta/config.lua +++ b/lua/nvim-tree/_meta/config.lua @@ -1,18 +1,14 @@ ---@meta error("Cannot require a meta file") --- --- Type Aliases for Enums --- - +--- TODO #2934 these were not correctly generated, inline or fix ---@alias nvim_tree.PlacementOption "before"|"after"|"signcolumn"|"right_align" ---@alias nvim_tree.HighlightOption "none"|"icon"|"name"|"all" ---@alias nvim_tree.HiddenDisplayOption "none"|"simple"|"all" --- --- nvim-tree Setup Config --- - +--- +--- TODO #2934 brief and some links +--- ---@class nvim_tree.Config --- ---Runs when creating the nvim-tree buffer. Use this to set your nvim-tree specific mappings. See |nvim-tree-mappings|. When `on_attach` is not a function, |nvim-tree-mappings-default| will be called. @@ -221,32 +217,3 @@ error("Cannot require a meta file") ---@field untracked? string Default: `"★"` ---@field deleted? string Default: `""` ---@field ignored? string Default: `"◌"` - - --- --- View --- - ----@class nvim_tree.Config.View ----@field adaptive_size? boolean Resize the window on each draw based on the longest line. Default: `false` ----@field centralize_selection? boolean When entering nvim-tree, reposition the view so that the current node is initially centralized, see |zz|. Default: `false` ----@field side? nvim_tree.PlacementOption Side of the tree. Default: `"left"` ----@field preserve_window_proportions? boolean Preserves window proportions when opening a file. If `false`, the height and width of windows other than nvim-tree will be equalized. Default: `false` ----@field number? boolean Print the line number in front of each line. Default: `false` ----@field relativenumber? boolean Show the line number relative to the line with the cursor in front of each line. Default: `false` ----@field signcolumn? nvim_tree.HiddenDisplayOption Show |signcolumn|. Default: `"yes"` ----@field width? string|integer|nvim_tree.Config.View.Width|fun(): integer|string Width of the window: can be a `%` string, a number representing columns, a function or a table. A table indicates that the view should be dynamically sized based on the longest line. Default: `30` ----@field float? nvim_tree.Config.View.Float Configuration options for floating window. ----@field cursorline? boolean Enable |cursorline| in nvim-tree window. Default: `true` ----@field debounce_delay? integer Idle milliseconds before some reload / refresh operations. Increase if you experience performance issues around screen refresh. Default: `15` (ms) - ----@class nvim_tree.Config.View.Width ----@field min? string|integer|fun(): integer|string Minimum dynamic width. Default: `30` ----@field max? string|integer|fun(): integer|string Maximum dynamic width, -1 for unbounded. Default: `-1` ----@field lines_excluded? string[] Exclude these lines when computing width. Supported values: `"root"`. Default: `{ "root" }` ----@field padding? integer|fun(): integer|string Extra padding to the right. Default: `1` - ----@class nvim_tree.Config.View.Float ----@field enable? boolean If true, tree window will be floating. Default: `false` ----@field quit_on_focus_loss? boolean Close the floating tree window when it loses focus. Default: `true` ----@field open_win_config? table|fun(): table Floating window config. See |nvim_open_win()| for more details. Default: `{ relative = "editor", border = "rounded", width = 30, height = 30, row = 1, col = 1, }` diff --git a/lua/nvim-tree/_meta/config/actions.lua b/lua/nvim-tree/_meta/config/actions.lua index e4740d5f20f..c4aa3a197a5 100644 --- a/lua/nvim-tree/_meta/config/actions.lua +++ b/lua/nvim-tree/_meta/config/actions.lua @@ -22,9 +22,6 @@ error("Cannot require a meta file") ---|nvim_tree.Config.Actions.RemoveFile| ---@field remove_file? nvim_tree.Config.Actions.RemoveFile --- --- Actions.ChangeDir --- --- vim |current-directory| behaviour ---@class nvim_tree.Config.Actions.ChangeDir @@ -41,9 +38,6 @@ error("Cannot require a meta file") ---(default: `false`) ---@field restrict_above_cwd? boolean --- --- Actions.ExpandAll --- ---Configuration for |nvim-tree-api.tree.expand_all()| and |nvim-tree-api.node.expand()| ---@class nvim_tree.Config.Actions.ExpandAll @@ -56,22 +50,25 @@ error("Cannot require a meta file") ---(default: `{}`) ---@field exclude? string[] --- --- Actions.FilePopup --- ----Configuration for file_popup floating window, see |nvim_open_win| ---- +---Configuration for file_popup floating window. +--- +---|vim.api.keyset.win_config| {open_win_config} is passed directly to |nvim_open_win|, default: +---```lua +---{ +--- col = 1, +--- row = 1, +--- relative = "cursor", +--- border = "shadow", +--- style = "minimal", +---} +---``` ---You shouldn't define |vim.api.keyset.win_config| {width} and {height} values here. They will be overridden to fit the file_popup content. ---@class nvim_tree.Config.Actions.FilePopup --- ----Neovim window config. ----(default: `{ col = 1, row = 1, relative = "cursor", border = "shadow", style = "minimal", }`) +---(default: above) ---@field open_win_config? vim.api.keyset.win_config --- --- Actions.OpenFile --- ---Configuration options for opening a file from nvim-tree. ---@class nvim_tree.Config.Actions.OpenFile @@ -91,9 +88,6 @@ error("Cannot require a meta file") ---|nvim_tree.Config.Actions.OpenFile.WindowPicker| ---@field window_picker? nvim_tree.Config.Actions.OpenFile.WindowPicker --- --- Actions.OpenFile.WindowPicker --- ---A window picker will be shown when there are multiple windows available to open a file. It will show a single character identifier in each window's status line. --- @@ -117,9 +111,6 @@ error("Cannot require a meta file") ---|nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude| ---@field exclude? nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude --- --- Actions.OpenFile.WindowPicker.Exclude --- ---Tables of buffer option names mapped to a list of option values. Windows containing matching buffers will not be: --- - available when using a window picker @@ -132,9 +123,6 @@ error("Cannot require a meta file") ---(default: `{ "nofile", "terminal", "help", }`) ---@field buftype? string[] --- --- Actions.RemoveFile --- ---Configuration options for removing a file from nvim-tree. ---@class nvim_tree.Config.Actions.RemoveFile diff --git a/lua/nvim-tree/_meta/config/view.lua b/lua/nvim-tree/_meta/config/view.lua index 4ab716dc93a..e6795a73741 100644 --- a/lua/nvim-tree/_meta/config/view.lua +++ b/lua/nvim-tree/_meta/config/view.lua @@ -1,4 +1,104 @@ ---@meta error("Cannot require a meta file") ---- TODO #2934 +---@alias nvim_tree.Config.View.WidthOpt string|integer|fun(): integer|string + +---Configures the dimensions and appearance of the nvim-tree window. +--- +---Window widths are generally defined by a |nvim_tree.Config.View.WidthOpt|: +---- string: `%` string e.g. `30%` +---- integer: number of columns +---- function: returns one of the above +--- +---{width} can be a |nvim_tree.Config.View.WidthOpt| for simple static control or a |nvim_tree.Config.View.Width| for fully dynamic control based on longest line. +--- +---The window is "docked" at the left by default, however may be configured to float: |nvim_tree.Config.View.Float| +--- +---@class nvim_tree.Config.View +--- +---When entering nvim-tree, reposition the view so that the current node is initially centralized, see |zz|. +---(default: `false`) +---@field centralize_selection? boolean +--- +---Set |cursorline| +---(default: `true`) +---@field cursorline? boolean +--- +---Set |cursorlineopt| +---(default: `both`) +---@field cursorlineopt? string +--- +---Idle milliseconds before some reload / refresh operations. Increase if you experience performance issues around screen refresh. +---(default: `15`) +---@field debounce_delay? integer +--- +---(default: `left`) +---@field side? "left"|"right" +--- +---Preserves window proportions when opening a file. If `false`, the height and width of windows other than nvim-tree will be equalized. +---(default: `false`) +---@field preserve_window_proportions? boolean +--- +---Set |number| +---(default: `false`) +---@field number? boolean +--- +---Set |relativenumber| +---(default: `false`) +---@field relativenumber? boolean +--- +---Set |signcolumn|. +---(default: `yes`) +---@field signcolumn? "yes"|"auto"|"no" +--- +---(default: `30`) +---@field width? nvim_tree.Config.View.WidthOpt|nvim_tree.Config.View.Width +--- +---|nvim_tree.Config.View.Float| +---@field float? nvim_tree.Config.View.Float + + +---Configure dynamic width based on longest line. +--- +---@class nvim_tree.Config.View.Width +--- +---(default: `30`) +---@field min? nvim_tree.Config.View.WidthOpt +--- +----1 for unbounded. +---(default: `-1`) +---@field max? nvim_tree.Config.View.WidthOpt +--- +---Exclude these lines when computing width. +---(default: `{ "root" }`) +---@field lines_excluded? ("root")[] +--- +---Extra padding to the right. +---(default: `1`) +---@field padding? nvim_tree.Config.View.WidthOpt + + +---Configure floating window behaviour +--- +---|vim.api.keyset.win_config| {open_win_config} is passed directly to |nvim_open_win|, default: +---```lua +---{ +--- relative = "editor", +--- border = "rounded", +--- width = 30, +--- height = 30, +--- row = 1, +--- col = 1, +---} +---``` +---@class nvim_tree.Config.View.Float +--- +---(default: `false`) +---@field enable? boolean +--- +---Close the floating window when it loses focus. +---(default: `true`) +---@field quit_on_focus_loss? boolean +--- +---(default: above) +---@field open_win_config? vim.api.keyset.win_config|fun(): vim.api.keyset.win_config diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua index 0e220f85f95..bebf6a761ab 100644 --- a/scripts/gen_vimdoc_config.lua +++ b/scripts/gen_vimdoc_config.lua @@ -10,7 +10,7 @@ local modules = { { helptag = "nvim-tree-config", title = "Class: Config", path = "lua/nvim-tree/_meta/config.lua", }, { helptag = "nvim-tree-config-sort", title = "Class: Config.Sort", path = "lua/nvim-tree/_meta/config/sort.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/view.lua", }, + { helptag = "nvim-tree-config-view", title = "Class: Config.View", path = "lua/nvim-tree/_meta/config/view.lua", }, { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/renderer.lua", }, { helptag = "nvim-tree-config-hijack-directories", title = "Class: Config.HijackDirectories", path = "lua/nvim-tree/_meta/config/hijack_directories.lua", }, { helptag = "nvim-tree-config-update-focused-file", title = "Class: Config.UpdateFocusedFile", path = "lua/nvim-tree/_meta/config/update_focused_file.lua", }, From 6f2744f1f09279fd2b087e3f7704af8b7385434d Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sat, 10 Jan 2026 15:18:23 +1100 Subject: [PATCH 035/170] doc(#2934): tidy Config.View, move into place --- doc/nvim-tree-lua.txt | 22 +++++++++++----------- lua/nvim-tree/_meta/config/view.lua | 22 +++++++++++----------- 2 files changed, 22 insertions(+), 22 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 352e4635287..676f15de4b8 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3852,17 +3852,17 @@ Class: Config.View *nvim-tree-config-view* *nvim_tree.Config.View* Configures the dimensions and appearance of the nvim-tree window. - Window widths are generally defined by a |nvim_tree.Config.View.WidthOpt|: - • string: `%` string e.g. `30%` - • integer: number of columns - • function: returns one of the above + The window is "docked" at the left by default, however may be configured + to float: |nvim_tree.Config.View.Float| - {width} can be a |nvim_tree.Config.View.WidthOpt| for simple static + {width} can be a |nvim_tree.Config.View.WidthSpec| for simple static control or a |nvim_tree.Config.View.Width| for fully dynamic control based on longest line. - The window is "docked" at the left by default, however may be configured - to float: |nvim_tree.Config.View.Float| + *nvim_tree.Config.View.WidthSpec* + • string: `x%` string e.g. `30%` + • integer: number of columns + • function: returns one of the above Fields: ~ • {centralize_selection}? (`boolean`, default: `false`) When @@ -3890,7 +3890,7 @@ Class: Config.View *nvim-tree-config-view* |relativenumber| • {signcolumn}? (`"yes"|"auto"|"no"`, default: `yes`) Set |signcolumn|. - • {width}? (`nvim_tree.Config.View.WidthOpt|nvim_tree.Config.View.Width`) + • {width}? (`nvim_tree.Config.View.WidthSpec|nvim_tree.Config.View.Width`) (default: `30`) • {float}? (`nvim_tree.Config.View.Float`) |nvim_tree.Config.View.Float| @@ -3921,12 +3921,12 @@ Class: Config.View *nvim-tree-config-view* Configure dynamic width based on longest line. Fields: ~ - • {min}? (`nvim_tree.Config.View.WidthOpt`) (default: `30`) - • {max}? (`nvim_tree.Config.View.WidthOpt`, default: `-1`) + • {min}? (`nvim_tree.Config.View.WidthSpec`) (default: `30`) + • {max}? (`nvim_tree.Config.View.WidthSpec`, default: `-1`) -1 for unbounded. • {lines_excluded}? (`("root")[]`, default: `{ "root" }`) Exclude these lines when computing width. - • {padding}? (`nvim_tree.Config.View.WidthOpt`, default: `1`) + • {padding}? (`nvim_tree.Config.View.WidthSpec`, default: `1`) Extra padding to the right. diff --git a/lua/nvim-tree/_meta/config/view.lua b/lua/nvim-tree/_meta/config/view.lua index e6795a73741..b9fb9d6afa9 100644 --- a/lua/nvim-tree/_meta/config/view.lua +++ b/lua/nvim-tree/_meta/config/view.lua @@ -1,18 +1,18 @@ ---@meta error("Cannot require a meta file") ----@alias nvim_tree.Config.View.WidthOpt string|integer|fun(): integer|string +---@alias nvim_tree.Config.View.WidthSpec string|integer|fun(): integer|string ---Configures the dimensions and appearance of the nvim-tree window. --- ----Window widths are generally defined by a |nvim_tree.Config.View.WidthOpt|: ----- string: `%` string e.g. `30%` ----- integer: number of columns ----- function: returns one of the above +---The window is "docked" at the left by default, however may be configured to float: |nvim_tree.Config.View.Float| --- ----{width} can be a |nvim_tree.Config.View.WidthOpt| for simple static control or a |nvim_tree.Config.View.Width| for fully dynamic control based on longest line. +---{width} can be a |nvim_tree.Config.View.WidthSpec| for simple static control or a |nvim_tree.Config.View.Width| for fully dynamic control based on longest line. --- ----The window is "docked" at the left by default, however may be configured to float: |nvim_tree.Config.View.Float| +---[nvim_tree.Config.View.WidthSpec]() +---- string: `x%` string e.g. `30%` +---- integer: number of columns +---- function: returns one of the above --- ---@class nvim_tree.Config.View --- @@ -52,7 +52,7 @@ error("Cannot require a meta file") ---@field signcolumn? "yes"|"auto"|"no" --- ---(default: `30`) ----@field width? nvim_tree.Config.View.WidthOpt|nvim_tree.Config.View.Width +---@field width? nvim_tree.Config.View.WidthSpec|nvim_tree.Config.View.Width --- ---|nvim_tree.Config.View.Float| ---@field float? nvim_tree.Config.View.Float @@ -63,11 +63,11 @@ error("Cannot require a meta file") ---@class nvim_tree.Config.View.Width --- ---(default: `30`) ----@field min? nvim_tree.Config.View.WidthOpt +---@field min? nvim_tree.Config.View.WidthSpec --- ----1 for unbounded. ---(default: `-1`) ----@field max? nvim_tree.Config.View.WidthOpt +---@field max? nvim_tree.Config.View.WidthSpec --- ---Exclude these lines when computing width. ---(default: `{ "root" }`) @@ -75,7 +75,7 @@ error("Cannot require a meta file") --- ---Extra padding to the right. ---(default: `1`) ----@field padding? nvim_tree.Config.View.WidthOpt +---@field padding? nvim_tree.Config.View.WidthSpec ---Configure floating window behaviour From fd9285690744aa782ab9f919dec2432af724dde4 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sat, 10 Jan 2026 16:12:43 +1100 Subject: [PATCH 036/170] docs(#2934): type DEFAULT_OPTS, use bracketed references to keep luals happy --- lua/nvim-tree.lua | 1 + lua/nvim-tree/_meta/config.lua | 56 +++++++++---------- lua/nvim-tree/_meta/config/actions.lua | 22 ++++---- lua/nvim-tree/_meta/config/diagnostics.lua | 12 ++-- .../_meta/config/filesystem_watchers.lua | 2 +- lua/nvim-tree/_meta/config/git.lua | 2 +- lua/nvim-tree/_meta/config/help.lua | 2 +- .../_meta/config/hijack_directories.lua | 2 +- lua/nvim-tree/_meta/config/live_filter.lua | 2 +- lua/nvim-tree/_meta/config/log.lua | 6 +- lua/nvim-tree/_meta/config/modified.lua | 4 +- lua/nvim-tree/_meta/config/sort.lua | 8 +-- lua/nvim-tree/_meta/config/system_open.lua | 2 +- lua/nvim-tree/_meta/config/tab.lua | 2 +- lua/nvim-tree/_meta/config/ui.lua | 2 +- .../_meta/config/update_focused_file.lua | 12 ++-- lua/nvim-tree/_meta/config/view.lua | 20 +++---- 17 files changed, 79 insertions(+), 78 deletions(-) diff --git a/lua/nvim-tree.lua b/lua/nvim-tree.lua index 25e0e98bc62..9d27cee3541 100644 --- a/lua/nvim-tree.lua +++ b/lua/nvim-tree.lua @@ -252,6 +252,7 @@ local function setup_autocommands(opts) }) end +---@type nvim_tree.Config local DEFAULT_OPTS = { -- BEGIN_DEFAULT_OPTS on_attach = "default", hijack_cursor = false, diff --git a/lua/nvim-tree/_meta/config.lua b/lua/nvim-tree/_meta/config.lua index a333ad60bd5..283be552498 100644 --- a/lua/nvim-tree/_meta/config.lua +++ b/lua/nvim-tree/_meta/config.lua @@ -6,12 +6,12 @@ error("Cannot require a meta file") ---@alias nvim_tree.HighlightOption "none"|"icon"|"name"|"all" ---@alias nvim_tree.HiddenDisplayOption "none"|"simple"|"all" ---- --- TODO #2934 brief and some links --- +--- ---@class nvim_tree.Config --- ----Runs when creating the nvim-tree buffer. Use this to set your nvim-tree specific mappings. See |nvim-tree-mappings|. When `on_attach` is not a function, |nvim-tree-mappings-default| will be called. +---Runs when creating the nvim-tree buffer. Use this to set your [nvim-tree-mappings]. When `on_attach` is not a function, [nvim-tree-mappings-default] will be called. ---@field on_attach? string|fun(bufnr: integer) --- ---Keeps the cursor on the first letter of the filename when moving in the tree. @@ -22,7 +22,7 @@ error("Cannot require a meta file") ---(default: `true`) ---@field auto_reload_on_write? boolean --- ----Completely disable |netrw|, see |nvim-tree-netrw| for details. It is strongly advised to eagerly disable netrw, due to race conditions at vim startup. +---Completely disable [netrw], see [nvim-tree-netrw] for details. It is strongly advised to eagerly disable netrw, due to race conditions at vim startup. ---(default: `false`) ---@field disable_netrw? boolean --- @@ -36,18 +36,18 @@ error("Cannot require a meta file") -----@field hijack_unnamed_buffer_when_opening? boolean ---@field hubwo? boolean --- ----Preferred root directories. Only relevant when |nvim_tree.Config.UpdateFocusedFile| `update_root` is `true` +---Preferred root directories. Only relevant when [nvim_tree.Config.UpdateFocusedFile] {update_root} is `true` ---@field root_dirs? string[] --- ----Prefer startup root directory when updating root directory of the tree. Only relevant when |nvim_tree.Config.UpdateFocusedFile| `update_root` is `true` +---Prefer startup root directory when updating root directory of the tree. Only relevant when [nvim_tree.Config.UpdateFocusedFile] {update_root} is `true` ---(default: `false`) ---@field prefer_startup_root? boolean --- ----Changes the tree root directory on |DirChanged| and refreshes the tree. +---Changes the tree root directory on [DirChanged] and refreshes the tree. ---(default: `false`) ---@field sync_root_with_cwd? boolean --- ----Automatically reloads the tree on |BufEnter| nvim-tree. +---Automatically reloads the tree on [BufEnter] nvim-tree. ---(default: `false`) ---@field reload_on_bufenter? boolean --- @@ -55,65 +55,65 @@ error("Cannot require a meta file") ---(default: `false`) ---@field respect_buf_cwd? boolean --- ----Use |vim.ui.select| style prompts. Necessary when using a UI prompt decorator such as dressing.nvim or telescope-ui-select.nvim +---Use [vim.ui.select] style prompts. Necessary when using a UI prompt decorator such as dressing.nvim or telescope-ui-select.nvim ---(default: `false`) ---@field select_prompts? boolean --- ----|nvim_tree.Config.Sort| +---[nvim_tree.Config.Sort] ---@field sort? nvim_tree.Config.Sort --- ----|nvim_tree.Config.View| +---[nvim_tree.Config.View] ---@field view? nvim_tree.Config.View --- ----|nvim_tree.Config.Renderer| +---[nvim_tree.Config.Renderer] ---@field renderer? nvim_tree.Config.Renderer --- ----|nvim_tree.Config.HijackDirectories| +---[nvim_tree.Config.HijackDirectories] ---@field hijack_directories? nvim_tree.Config.HijackDirectories --- ----|nvim_tree.Config.UpdateFocusedFile| +---[nvim_tree.Config.UpdateFocusedFile] ---@field update_focused_file? nvim_tree.Config.UpdateFocusedFile --- ----|nvim_tree.Config.SystemOpen| +---[nvim_tree.Config.SystemOpen] ---@field system_open? nvim_tree.Config.SystemOpen --- ----|nvim_tree.Config.Git| +---[nvim_tree.Config.Git] ---@field git? nvim_tree.Config.Git --- ----|nvim_tree.Config.Diagnostics| +---[nvim_tree.Config.Diagnostics] ---@field diagnostics? nvim_tree.Config.Diagnostics --- ----|nvim_tree.Config.Modified| +---[nvim_tree.Config.Modified] ---@field modified? nvim_tree.Config.Modified --- ----|nvim_tree.Config.Filters| +---[nvim_tree.Config.Filters] ---@field filters? nvim_tree.Config.Filters --- ----|nvim_tree.Config.LiveFilter| +---[nvim_tree.Config.LiveFilter] ---@field live_filter? nvim_tree.Config.LiveFilter --- ----|nvim_tree.Config.FilesystemWatchers| +---[nvim_tree.Config.FilesystemWatchers] ---@field filesystem_watchers? nvim_tree.Config.FilesystemWatchers --- ----|nvim_tree.Config.Actions| +---[nvim_tree.Config.Actions] ---@field actions? nvim_tree.Config.Actions --- ----|nvim_tree.Config.Trash| +---[nvim_tree.Config.Trash] ---@field trash? nvim_tree.Config.Trash --- ----|nvim_tree.Config.Tab| +---[nvim_tree.Config.Tab] ---@field tab? nvim_tree.Config.Tab --- ----|nvim_tree.Config.Notify| +---[nvim_tree.Config.Notify] ---@field notify? nvim_tree.Config.Notify --- ----|nvim_tree.Config.Help| +---[nvim_tree.Config.Help] ---@field help? nvim_tree.Config.Help --- ----|nvim_tree.Config.UI| +---[nvim_tree.Config.UI] ---@field ui? nvim_tree.Config.UI --- ----|nvim_tree.Config.Log| +---[nvim_tree.Config.Log] ---@field log? nvim_tree.Config.Log -- @@ -127,7 +127,7 @@ error("Cannot require a meta file") ---@field root_folder_label? string|boolean|fun(root_cwd: string): string In what format to show root folder. See `:help filename-modifiers` for available `string` options. Set to `false` to hide the root folder. or `boolean` or `function(root_cwd)`, Default: `":~:s?$?/..?"` ---@field indent_width? integer Number of spaces for an each tree nesting level. Minimum 1. Default: `2` ---@field special_files? string[] A list of filenames that gets highlighted with `NvimTreeSpecialFile`. Default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }` ----@field hidden_display? fun(hidden_stats: table): string|nil|nvim_tree.HiddenDisplayOption Show a summary of hidden files below the tree using `NvimTreeHiddenDisplay Default: `"none"` +---@field hidden_display? (fun(hidden_stats: table): string)|nvim_tree.HiddenDisplayOption Show a summary of hidden files below the tree using `NvimTreeHiddenDisplay Default: `"none"` ---@field symlink_destination? boolean Whether to show the destination of the symlink. Default: `true` ---@field decorators? (string|nvim_tree.api.decorator.UserDecorator)[] Highlighting and icons for the nodes, in increasing order of precedence. Uses strings to specify builtin decorators otherwise specify your `nvim_tree.api.decorator.UserDecorator` class. Default: > lua { "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", } ---@field highlight_git? nvim_tree.HighlightOption Enable highlight for git attributes using `NvimTreeGit*HL` highlight groups. Requires |nvim-tree.git.enable| Value can be `"none"`, `"icon"`, `"name"` or `"all"`. Default: `"none"` @see nvim-tree.git.enable diff --git a/lua/nvim-tree/_meta/config/actions.lua b/lua/nvim-tree/_meta/config/actions.lua index c4aa3a197a5..df89c958bbe 100644 --- a/lua/nvim-tree/_meta/config/actions.lua +++ b/lua/nvim-tree/_meta/config/actions.lua @@ -7,23 +7,23 @@ error("Cannot require a meta file") ---(default: `true`) ---@field use_system_clipboard? boolean --- ----|nvim_tree.Config.Actions.ChangeDir| +---[nvim_tree.Config.Actions.ChangeDir] ---@field change_dir? nvim_tree.Config.Actions.ChangeDir --- ----|nvim_tree.Config.Actions.ExpandAll| +---[nvim_tree.Config.Actions.ExpandAll] ---@field expand_all? nvim_tree.Config.Actions.ExpandAll --- ----|nvim_tree.Config.Actions.FilePopup| +---[nvim_tree.Config.Actions.FilePopup] ---@field file_popup? nvim_tree.Config.Actions.FilePopup --- ----|nvim_tree.Config.Actions.OpenFile| +---[nvim_tree.Config.Actions.OpenFile] ---@field open_file? nvim_tree.Config.Actions.OpenFile --- ----|nvim_tree.Config.Actions.RemoveFile| +---[nvim_tree.Config.Actions.RemoveFile] ---@field remove_file? nvim_tree.Config.Actions.RemoveFile ---- vim |current-directory| behaviour +--- vim [current-directory] behaviour ---@class nvim_tree.Config.Actions.ChangeDir --- ---Change the working directory when changing directories in the tree @@ -39,7 +39,7 @@ error("Cannot require a meta file") ---@field restrict_above_cwd? boolean ----Configuration for |nvim-tree-api.tree.expand_all()| and |nvim-tree-api.node.expand()| +---Configuration for [nvim-tree-api.tree.expand_all()] and [nvim-tree-api.node.expand()] ---@class nvim_tree.Config.Actions.ExpandAll --- ---Limit the number of folders being explored when expanding every folders. Avoids hanging neovim when running this action on very large folders. @@ -53,7 +53,7 @@ error("Cannot require a meta file") ---Configuration for file_popup floating window. --- ----|vim.api.keyset.win_config| {open_win_config} is passed directly to |nvim_open_win|, default: +---[vim.api.keyset.win_config] {open_win_config} is passed directly to [nvim_open_win], default: ---```lua ---{ --- col = 1, @@ -63,7 +63,7 @@ error("Cannot require a meta file") --- style = "minimal", ---} ---``` ----You shouldn't define |vim.api.keyset.win_config| {width} and {height} values here. They will be overridden to fit the file_popup content. +---You shouldn't define [vim.api.keyset.win_config] {width} and {height} values here. They will be overridden to fit the file_popup content. ---@class nvim_tree.Config.Actions.FilePopup --- ---(default: above) @@ -85,7 +85,7 @@ error("Cannot require a meta file") ---(default: `true`) ---@field resize_window? boolean --- ----|nvim_tree.Config.Actions.OpenFile.WindowPicker| +---[nvim_tree.Config.Actions.OpenFile.WindowPicker] ---@field window_picker? nvim_tree.Config.Actions.OpenFile.WindowPicker @@ -108,7 +108,7 @@ error("Cannot require a meta file") ---(default: `"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"`) ---@field chars? string --- ----|nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude| +---[nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude] ---@field exclude? nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude diff --git a/lua/nvim-tree/_meta/config/diagnostics.lua b/lua/nvim-tree/_meta/config/diagnostics.lua index ac6ed35c1cb..c2b4a9f9ac3 100644 --- a/lua/nvim-tree/_meta/config/diagnostics.lua +++ b/lua/nvim-tree/_meta/config/diagnostics.lua @@ -1,7 +1,7 @@ ---@meta error("Cannot require a meta file") ----Integrate with |lsp| or COC diagnostics. +---Integrate with [lsp] or COC diagnostics. --- ---@class nvim_tree.Config.Diagnostics --- @@ -20,23 +20,23 @@ error("Cannot require a meta file") ---(default: `true`) ---@field show_on_open_dirs? boolean --- ----Global |vim.diagnostic.Opts| overrides {severity} and {icons} +---Global [vim.diagnostic.Opts] overrides {severity} and {icons} ---(default: `false`) ---@field diagnostic_opts? boolean --- ----|nvim_tree.Config.Diagnostics.Severity| +---[nvim_tree.Config.Diagnostics.Severity] ---@field severity? nvim_tree.Config.Diagnostics.Severity --- ----|nvim_tree.Config.Diagnostics.Icons| +---[nvim_tree.Config.Diagnostics.Icons] ---@field icons? nvim_tree.Config.Diagnostics.Icons ---@class nvim_tree.Config.Diagnostics.Severity --- ----|vim.diagnostic.Severity| +---[vim.diagnostic.Severity] ---(default: HINT) ---@field min? vim.diagnostic.Severity --- ----|vim.diagnostic.Severity| +---[vim.diagnostic.Severity] ---(default: ERROR) ---@field max? vim.diagnostic.Severity diff --git a/lua/nvim-tree/_meta/config/filesystem_watchers.lua b/lua/nvim-tree/_meta/config/filesystem_watchers.lua index 48553261d77..0e8f7e098dd 100644 --- a/lua/nvim-tree/_meta/config/filesystem_watchers.lua +++ b/lua/nvim-tree/_meta/config/filesystem_watchers.lua @@ -6,7 +6,7 @@ error("Cannot require a meta file") ---With this feature, the tree will be partially updated on specific directory changes, resulting in better performance. --- ---Watchers may be disabled for absolute directory paths via {ignore_dirs}. ---- - A list of |vim regex| to match a path, backslash escaped e.g. `"my-proj/\\.build$"` OR +--- - A list of [vim regex] to match a path, backslash escaped e.g. `"my-proj/\\.build$"` OR --- - A function that is passed an absolute path and returns `true` to disable ---This may be useful when a path is not in `.gitignore` or git integration is disabled. ---@class nvim_tree.Config.FilesystemWatchers diff --git a/lua/nvim-tree/_meta/config/git.lua b/lua/nvim-tree/_meta/config/git.lua index 4df33102433..cda11b7656b 100644 --- a/lua/nvim-tree/_meta/config/git.lua +++ b/lua/nvim-tree/_meta/config/git.lua @@ -6,7 +6,7 @@ error("Cannot require a meta file") ---Processes will be killed if they exceed {timeout}ms. Git integration will be disabled following 5 timeouts and you will be notified. --- ---Git integration may be disabled for git top-level directories via {disable_for_dirs}: ---- - A list of relative paths evaluated with |fnamemodify| `:p` OR +--- - A list of relative paths evaluated with [fnamemodify] `:p` OR --- - A function that is passed an absolute path and returns `true` to disable --- ---@class nvim_tree.Config.Git diff --git a/lua/nvim-tree/_meta/config/help.lua b/lua/nvim-tree/_meta/config/help.lua index 8e7b8982dea..51e6a5d2453 100644 --- a/lua/nvim-tree/_meta/config/help.lua +++ b/lua/nvim-tree/_meta/config/help.lua @@ -11,6 +11,6 @@ error("Cannot require a meta file") --- ---@class nvim_tree.Config.Help --- ----|nvim_tree.Config.Help.SortBy| +---[nvim_tree.Config.Help.SortBy] ---(default: `key`) ---@field sort_by? nvim_tree.Config.Help.SortBy diff --git a/lua/nvim-tree/_meta/config/hijack_directories.lua b/lua/nvim-tree/_meta/config/hijack_directories.lua index ce2f3fb8432..0219e858653 100644 --- a/lua/nvim-tree/_meta/config/hijack_directories.lua +++ b/lua/nvim-tree/_meta/config/hijack_directories.lua @@ -6,7 +6,7 @@ error("Cannot require a meta file") --- ---Disable this option if you use vim-dirvish or dirbuf.nvim. --- ----If |nvim_tree.Config| {hijack_netrw} and {disable_netrw} are `false` this feature will be disabled. +---If [nvim_tree.Config] {hijack_netrw} and {disable_netrw} are `false` this feature will be disabled. ---@class nvim_tree.Config.HijackDirectories --- ---(default: `true`) diff --git a/lua/nvim-tree/_meta/config/live_filter.lua b/lua/nvim-tree/_meta/config/live_filter.lua index 0642bfae4c3..156e243855c 100644 --- a/lua/nvim-tree/_meta/config/live_filter.lua +++ b/lua/nvim-tree/_meta/config/live_filter.lua @@ -1,7 +1,7 @@ ---@meta error("Cannot require a meta file") ---- Live filter allows you to filter the tree nodes dynamically, based on regex matching, see |vim.regex| +--- Live filter allows you to filter the tree nodes dynamically, based on regex matching, see [vim.regex] --- --- This feature is bound to the `f` key by default. The filter can be cleared with the `F` key by default. ---@class nvim_tree.Config.LiveFilter diff --git a/lua/nvim-tree/_meta/config/log.lua b/lua/nvim-tree/_meta/config/log.lua index 879da5abb09..ee0358e2919 100644 --- a/lua/nvim-tree/_meta/config/log.lua +++ b/lua/nvim-tree/_meta/config/log.lua @@ -1,7 +1,7 @@ ---@meta error("Cannot require a meta file") ----Log to a file `nvim-tree.log` in |stdpath|("log"), usually `${XDG_STATE_HOME}/nvim` +---Log to a file `nvim-tree.log` in [stdpath] `log`, usually `${XDG_STATE_HOME}/nvim` ---@class nvim_tree.Config.Log --- ---(default: `false`) @@ -11,7 +11,7 @@ error("Cannot require a meta file") ---(default: `false`) ---@field truncate? boolean --- ----|nvim_tree.Config.Log.Types| +---[nvim_tree.Config.Log.Types] ---@field types? nvim_tree.Config.Log.Types ---Specify which information to log. @@ -45,6 +45,6 @@ error("Cannot require a meta file") ---(default: `false`) ---@field git? boolean --- ----|nvim_tree.Config.FilesystemWatchers| processing, verbose. +---[nvim_tree.Config.FilesystemWatchers] processing, verbose. ---(default: `false`) ---@field watcher? boolean diff --git a/lua/nvim-tree/_meta/config/modified.lua b/lua/nvim-tree/_meta/config/modified.lua index 33de15d5514..b9aa02b223c 100644 --- a/lua/nvim-tree/_meta/config/modified.lua +++ b/lua/nvim-tree/_meta/config/modified.lua @@ -3,8 +3,8 @@ error("Cannot require a meta file") ---Indicate which files have unsaved modification. ---To see modified status in the tree you will need to set: ---- - |nvim_tree.Config.Renderer.Icons.Show| {modified} to `true` OR ---- - |nvim_tree.Config.Renderer| {highlight_modified} to `true` +--- - [nvim_tree.Config.Renderer.Icons.Show] {modified} to `true` OR +--- - [nvim_tree.Config.Renderer] {highlight_modified} to `true` ---@class nvim_tree.Config.Modified --- ---(default: `false`) diff --git a/lua/nvim-tree/_meta/config/sort.lua b/lua/nvim-tree/_meta/config/sort.lua index a78e2dc833b..5996453d38a 100644 --- a/lua/nvim-tree/_meta/config/sort.lua +++ b/lua/nvim-tree/_meta/config/sort.lua @@ -5,15 +5,15 @@ error("Cannot require a meta file") ---Sort files within a directory. --- ----{sorter} builtin |nvim_tree.Config.Sort.Sorter|: +---{sorter} [nvim_tree.Config.Sort.Sorter]() ---- `name` ---- `case_sensitive` name ---- `modification_time` ---- `extension` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz` ---- `suffix` uses the last e.g. `foo.tar.gz` -> `.gz` ----- `filetype` |filetype| +---- `filetype` [filetype] --- ----{sorter} may be a function that is passed a list of |nvim_tree.api.Node| to be sorted in place e.g. +---{sorter} may be a function that is passed a list of [nvim_tree.api.Node] to be sorted in place e.g. ---```lua --- ------Sort by name length @@ -25,7 +25,7 @@ error("Cannot require a meta file") --- end) ---end ---``` ----Alternatively, the function may return a |nvim_tree.Config.Sort.Sorter| +---{sorter} may be a function that returns a [nvim_tree.Config.Sort.Sorter] --- ---@class nvim_tree.Config.Sort --- diff --git a/lua/nvim-tree/_meta/config/system_open.lua b/lua/nvim-tree/_meta/config/system_open.lua index 4774e75ae1d..6956b8d592b 100644 --- a/lua/nvim-tree/_meta/config/system_open.lua +++ b/lua/nvim-tree/_meta/config/system_open.lua @@ -4,7 +4,7 @@ error("Cannot require a meta file") ---Open files or directories via the OS. --- ---Neovim: ----- `>=` 0.10 uses |vim.ui.open| unless {cmd} is specified +---- `>=` 0.10 uses [vim.ui.open] unless {cmd} is specified ---- `<` 0.10 calls external {cmd}: --- - UNIX: `xdg-open` --- - macOS: `open` diff --git a/lua/nvim-tree/_meta/config/tab.lua b/lua/nvim-tree/_meta/config/tab.lua index e5430bece32..05f4deb5beb 100644 --- a/lua/nvim-tree/_meta/config/tab.lua +++ b/lua/nvim-tree/_meta/config/tab.lua @@ -3,7 +3,7 @@ error("Cannot require a meta file") ---@class nvim_tree.Config.Tab --- ----|nvim_tree.Config.Tab.Sync| +---[nvim_tree.Config.Tab.Sync] ---@field sync? nvim_tree.Config.Tab.Sync -- diff --git a/lua/nvim-tree/_meta/config/ui.lua b/lua/nvim-tree/_meta/config/ui.lua index 9e9f91b313b..438e46fad17 100644 --- a/lua/nvim-tree/_meta/config/ui.lua +++ b/lua/nvim-tree/_meta/config/ui.lua @@ -3,7 +3,7 @@ error("Cannot require a meta file") ---@class nvim_tree.Config.UI --- ----|nvim_tree.Config.UI.Confirm| +---[nvim_tree.Config.UI.Confirm] ---@field confirm? nvim_tree.Config.UI.Confirm -- diff --git a/lua/nvim-tree/_meta/config/update_focused_file.lua b/lua/nvim-tree/_meta/config/update_focused_file.lua index 81fea09ad8c..f08a987df1b 100644 --- a/lua/nvim-tree/_meta/config/update_focused_file.lua +++ b/lua/nvim-tree/_meta/config/update_focused_file.lua @@ -1,26 +1,26 @@ ---@meta error("Cannot require a meta file") ----Update the focused file on |BufEnter|, uncollapsing folders recursively. +---Update the focused file on [BufEnter], uncollapsing folders recursively. --- ---@class nvim_tree.Config.UpdateFocusedFile --- ---(default: `false`) ---@field enable? boolean --- ----|nvim_tree.Config.UpdateFocusedFile.UpdateRoot| +---[nvim_tree.Config.UpdateFocusedFile.UpdateRoot] ---@field update_root? nvim_tree.Config.UpdateFocusedFile.UpdateRoot --- ----A function called on |BufEnter| that returns true if the file should not be focused when opening. +---A function called on [BufEnter] that returns true if the file should not be focused when opening. ---(default: `false`) ----@field exclude? fun(args: vim.api.keyset.create_autocmd.callback_args): boolean +---@field exclude? boolean|fun(args: vim.api.keyset.create_autocmd.callback_args): boolean ---Update the root directory of the tree if the file is not under the current root directory. --- ----Prefers vim's cwd and |nvim_tree.Config| {root_dirs}, falling back to the directory containing the file. +---Prefers vim's cwd and [nvim_tree.Config] {root_dirs}, falling back to the directory containing the file. --- ----Only relevant when |nvim_tree.Config.UpdateFocusedFile| {enable} is `true` +---Only relevant when [nvim_tree.Config.UpdateFocusedFile] {enable} is `true` --- ---@class nvim_tree.Config.UpdateFocusedFile.UpdateRoot --- diff --git a/lua/nvim-tree/_meta/config/view.lua b/lua/nvim-tree/_meta/config/view.lua index b9fb9d6afa9..291ee708315 100644 --- a/lua/nvim-tree/_meta/config/view.lua +++ b/lua/nvim-tree/_meta/config/view.lua @@ -5,9 +5,9 @@ error("Cannot require a meta file") ---Configures the dimensions and appearance of the nvim-tree window. --- ----The window is "docked" at the left by default, however may be configured to float: |nvim_tree.Config.View.Float| +---The window is "docked" at the left by default, however may be configured to float: [nvim_tree.Config.View.Float] --- ----{width} can be a |nvim_tree.Config.View.WidthSpec| for simple static control or a |nvim_tree.Config.View.Width| for fully dynamic control based on longest line. +---{width} can be a [nvim_tree.Config.View.WidthSpec] for simple static control or a [nvim_tree.Config.View.Width] for fully dynamic control based on longest line. --- ---[nvim_tree.Config.View.WidthSpec]() ---- string: `x%` string e.g. `30%` @@ -16,15 +16,15 @@ error("Cannot require a meta file") --- ---@class nvim_tree.Config.View --- ----When entering nvim-tree, reposition the view so that the current node is initially centralized, see |zz|. +---When entering nvim-tree, reposition the view so that the current node is initially centralized, see [zz]. ---(default: `false`) ---@field centralize_selection? boolean --- ----Set |cursorline| +---[cursorline] ---(default: `true`) ---@field cursorline? boolean --- ----Set |cursorlineopt| +---[cursorlineopt] ---(default: `both`) ---@field cursorlineopt? string --- @@ -39,22 +39,22 @@ error("Cannot require a meta file") ---(default: `false`) ---@field preserve_window_proportions? boolean --- ----Set |number| +---[number] ---(default: `false`) ---@field number? boolean --- ----Set |relativenumber| +---[relativenumber] ---(default: `false`) ---@field relativenumber? boolean --- ----Set |signcolumn|. +---[signcolumn] ---(default: `yes`) ---@field signcolumn? "yes"|"auto"|"no" --- ---(default: `30`) ---@field width? nvim_tree.Config.View.WidthSpec|nvim_tree.Config.View.Width --- ----|nvim_tree.Config.View.Float| +---[nvim_tree.Config.View.Float] ---@field float? nvim_tree.Config.View.Float @@ -80,7 +80,7 @@ error("Cannot require a meta file") ---Configure floating window behaviour --- ----|vim.api.keyset.win_config| {open_win_config} is passed directly to |nvim_open_win|, default: +---[vim.api.keyset.win_config] {open_win_config} is passed directly to [nvim_open_win], default: ---```lua ---{ --- relative = "editor", From 453b31f05f2d5fa679d5b034f81b92caec3abd50 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sat, 10 Jan 2026 16:22:36 +1100 Subject: [PATCH 037/170] docs(#2934): tidy, inline some classes --- doc/nvim-tree-lua.txt | 71 +++++++++------------- lua/nvim-tree/_meta/config/actions.lua | 8 +-- lua/nvim-tree/_meta/config/diagnostics.lua | 2 + lua/nvim-tree/_meta/config/tab.lua | 2 +- 4 files changed, 37 insertions(+), 46 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 676f15de4b8..3423c58bce7 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3467,10 +3467,9 @@ Class: Config *nvim-tree-config* Fields: ~ • {on_attach}? (`string|fun(bufnr: integer)`) Runs when creating the nvim-tree buffer. Use this to - set your nvim-tree specific mappings. See - |nvim-tree-mappings|. When `on_attach` is not - a function, |nvim-tree-mappings-default| will - be called. + set your |nvim-tree-mappings|. When + `on_attach` is not a function, + |nvim-tree-mappings-default| will be called. • {hijack_cursor}? (`boolean`, default: `false`) Keeps the cursor on the first letter of the filename when moving in the tree. @@ -3492,12 +3491,12 @@ Class: Config *nvim-tree-config* • {root_dirs}? (`string[]`) Preferred root directories. Only relevant when |nvim_tree.Config.UpdateFocusedFile| - `update_root` is `true` + {update_root} is `true` • {prefer_startup_root}? (`boolean`, default: `false`) Prefer startup root directory when updating root directory of the tree. Only relevant when |nvim_tree.Config.UpdateFocusedFile| - `update_root` is `true` + {update_root} is `true` • {sync_root_with_cwd}? (`boolean`, default: `false`) Changes the tree root directory on |DirChanged| and refreshes the tree. @@ -3576,7 +3575,7 @@ Class: Config *nvim-tree-config* highlighted with `NvimTreeSpecialFile`. Default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }` - • {hidden_display}? (`fun(hidden_stats: table): string?|nvim_tree.HiddenDisplayOption`) + • {hidden_display}? (`(fun(hidden_stats: table): string)|nvim_tree.HiddenDisplayOption`) Show a summary of hidden files below the tree using `NvimTreeHiddenDisplay Default: `"none"` @@ -3812,7 +3811,7 @@ Class: Config.Sort *nvim-tree-config-sort* *nvim_tree.Config.Sort* Sort files within a directory. - {sorter} builtin |nvim_tree.Config.Sort.Sorter|: + {sorter} *nvim_tree.Config.Sort.Sorter* • `name` • `case_sensitive` name • `modification_time` @@ -3833,7 +3832,7 @@ Class: Config.Sort *nvim-tree-config-sort* end < - Alternatively, the function may return a |nvim_tree.Config.Sort.Sorter| + {sorter} may be a function that returns a |nvim_tree.Config.Sort.Sorter| Fields: ~ • {sorter}? (`nvim_tree.Config.Sort.Sorter|fun(nodes: nvim_tree.api.Node[]): nvim_tree.Config.Sort.Sorter?`) @@ -3869,9 +3868,9 @@ Class: Config.View *nvim-tree-config-view* entering nvim-tree, reposition the view so that the current node is initially centralized, see |zz|. - • {cursorline}? (`boolean`, default: `true`) Set + • {cursorline}? (`boolean`, default: `true`) |cursorline| - • {cursorlineopt}? (`string`, default: `both`) Set + • {cursorlineopt}? (`string`, default: `both`) |cursorlineopt| • {debounce_delay}? (`integer`, default: `15`) Idle milliseconds before some reload / @@ -3884,12 +3883,11 @@ Class: Config.View *nvim-tree-config-view* opening a file. If `false`, the height and width of windows other than nvim-tree will be equalized. - • {number}? (`boolean`, default: `false`) Set - |number| - • {relativenumber}? (`boolean`, default: `false`) Set + • {number}? (`boolean`, default: `false`) |number| + • {relativenumber}? (`boolean`, default: `false`) |relativenumber| • {signcolumn}? (`"yes"|"auto"|"no"`, default: `yes`) - Set |signcolumn|. + |signcolumn| • {width}? (`nvim_tree.Config.View.WidthSpec|nvim_tree.Config.View.Width`) (default: `30`) • {float}? (`nvim_tree.Config.View.Float`) @@ -3959,7 +3957,7 @@ Class: Config.UpdateFocusedFile *nvim-tree-config-update-focused-file* • {enable}? (`boolean`) (default: `false`) • {update_root}? (`nvim_tree.Config.UpdateFocusedFile.UpdateRoot`) |nvim_tree.Config.UpdateFocusedFile.UpdateRoot| - • {exclude}? (`fun(args: vim.api.keyset.create_autocmd.callback_args): boolean`, default: `false`) + • {exclude}? (`boolean|fun(args: vim.api.keyset.create_autocmd.callback_args): boolean`, default: `false`) A function called on |BufEnter| that returns true if the file should not be focused when opening. @@ -4053,26 +4051,17 @@ Class: Config.Diagnostics *nvim-tree-config-diagnostics* • {diagnostic_opts}? (`boolean`, default: `false`) Global |vim.diagnostic.Opts| overrides {severity} and {icons} - • {severity}? (`nvim_tree.Config.Diagnostics.Severity`) + • {severity}? (`table`) |nvim_tree.Config.Diagnostics.Severity| - • {icons}? (`nvim_tree.Config.Diagnostics.Icons`) - |nvim_tree.Config.Diagnostics.Icons| - -*nvim_tree.Config.Diagnostics.Icons* - - Fields: ~ - • {hint}? (`string`) (default: ) - • {info}? (`string`) (default: ) - • {warning}? (`string`) (default: ) - • {error}? (`string`) (default: ) - -*nvim_tree.Config.Diagnostics.Severity* - - Fields: ~ - • {min}? (`vim.diagnostic.Severity`, default: HINT) - |vim.diagnostic.Severity| - • {max}? (`vim.diagnostic.Severity`, default: ERROR) - |vim.diagnostic.Severity| + • {min}? (`vim.diagnostic.Severity`, default: + HINT) |vim.diagnostic.Severity| + • {max}? (`vim.diagnostic.Severity`, default: + ERROR) |vim.diagnostic.Severity| + • {icons}? (`table`) |nvim_tree.Config.Diagnostics.Icons| + • {hint}? (`string`) (default: ) + • {info}? (`string`) (default: ) + • {warning}? (`string`) (default: ) + • {error}? (`string`) (default: ) @@ -4231,7 +4220,7 @@ Class: Config.Actions *nvim-tree-config-actions* to a directory above the global cwd. *nvim_tree.Config.Actions.ExpandAll* - Configuration for |nvim-tree-api.tree.expand_all()| and + Configure |nvim-tree-api.tree.expand_all()| and |nvim-tree-api.node.expand()| Fields: ~ @@ -4245,7 +4234,7 @@ Class: Config.Actions *nvim-tree-config-actions* `{ ".git", "target", "build" }` *nvim_tree.Config.Actions.FilePopup* - Configuration for file_popup floating window. + {file_popup} floating window. |vim.api.keyset.win_config| {open_win_config} is passed directly to |nvim_open_win|, default: >lua @@ -4265,7 +4254,7 @@ Class: Config.Actions *nvim-tree-config-actions* • {open_win_config}? (`vim.api.keyset.win_config`) (default: above) *nvim_tree.Config.Actions.OpenFile* - Configuration options for opening a file from nvim-tree. + Opening files. Fields: ~ • {quit_on_open}? (`boolean`, default: `false`) Closes the explorer @@ -4312,7 +4301,7 @@ Class: Config.Actions *nvim-tree-config-actions* `{ "nofile", "terminal", "help", }`) *nvim_tree.Config.Actions.RemoveFile* - Configuration options for removing a file from nvim-tree. + Removing files. Fields: ~ • {close_window}? (`boolean`, default: `true`) Close any window that @@ -4345,7 +4334,7 @@ Class: Config.Tab *nvim-tree-config-tab* • {sync}? (`nvim_tree.Config.Tab.Sync`) |nvim_tree.Config.Tab.Sync| *nvim_tree.Config.Tab.Sync* - Configuration for syncing nvim-tree across tabs. + Sync nvim-tree across tabs. Fields: ~ • {open}? (`boolean`, default: `false`) Opens the tree automatically @@ -4417,7 +4406,7 @@ Class: Config.UI *nvim-tree-config-ui* Class: Config.Log *nvim-tree-config-log* *nvim_tree.Config.Log* - Log to a file `nvim-tree.log` in |stdpath|("log"), usually + Log to a file `nvim-tree.log` in |stdpath| `log`, usually `${XDG_STATE_HOME}/nvim` Fields: ~ diff --git a/lua/nvim-tree/_meta/config/actions.lua b/lua/nvim-tree/_meta/config/actions.lua index df89c958bbe..5f6dac26103 100644 --- a/lua/nvim-tree/_meta/config/actions.lua +++ b/lua/nvim-tree/_meta/config/actions.lua @@ -39,7 +39,7 @@ error("Cannot require a meta file") ---@field restrict_above_cwd? boolean ----Configuration for [nvim-tree-api.tree.expand_all()] and [nvim-tree-api.node.expand()] +---Configure [nvim-tree-api.tree.expand_all()] and [nvim-tree-api.node.expand()] ---@class nvim_tree.Config.Actions.ExpandAll --- ---Limit the number of folders being explored when expanding every folders. Avoids hanging neovim when running this action on very large folders. @@ -51,7 +51,7 @@ error("Cannot require a meta file") ---@field exclude? string[] ----Configuration for file_popup floating window. +---{file_popup} floating window. --- ---[vim.api.keyset.win_config] {open_win_config} is passed directly to [nvim_open_win], default: ---```lua @@ -70,7 +70,7 @@ error("Cannot require a meta file") ---@field open_win_config? vim.api.keyset.win_config ----Configuration options for opening a file from nvim-tree. +---Opening files. ---@class nvim_tree.Config.Actions.OpenFile --- ---Closes the explorer when opening a file @@ -124,7 +124,7 @@ error("Cannot require a meta file") ---@field buftype? string[] ----Configuration options for removing a file from nvim-tree. +---Removing files. ---@class nvim_tree.Config.Actions.RemoveFile --- ---Close any window that displays a file when removing that file from the tree. diff --git a/lua/nvim-tree/_meta/config/diagnostics.lua b/lua/nvim-tree/_meta/config/diagnostics.lua index c2b4a9f9ac3..0775945603c 100644 --- a/lua/nvim-tree/_meta/config/diagnostics.lua +++ b/lua/nvim-tree/_meta/config/diagnostics.lua @@ -30,6 +30,7 @@ error("Cannot require a meta file") ---[nvim_tree.Config.Diagnostics.Icons] ---@field icons? nvim_tree.Config.Diagnostics.Icons +---@inlinedoc ---@class nvim_tree.Config.Diagnostics.Severity --- ---[vim.diagnostic.Severity] @@ -40,6 +41,7 @@ error("Cannot require a meta file") ---(default: ERROR) ---@field max? vim.diagnostic.Severity +---@inlinedoc ---@class nvim_tree.Config.Diagnostics.Icons --- ---(default: ) diff --git a/lua/nvim-tree/_meta/config/tab.lua b/lua/nvim-tree/_meta/config/tab.lua index 05f4deb5beb..0e56420f51a 100644 --- a/lua/nvim-tree/_meta/config/tab.lua +++ b/lua/nvim-tree/_meta/config/tab.lua @@ -10,7 +10,7 @@ error("Cannot require a meta file") -- Tab.Sync -- ----Configuration for syncing nvim-tree across tabs. +---Sync nvim-tree across tabs. ---@class nvim_tree.Config.Tab.Sync --- ---Opens the tree automatically when switching tabpage or opening a new tabpage if the tree was previously open. From 1b21a08c533d21d6ea801739b897737867b8a473 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sat, 10 Jan 2026 17:20:48 +1100 Subject: [PATCH 038/170] docs(#2934): tidy Config.Renderer --- doc/nvim-tree-lua.txt | 130 +++++++++--------- lua/nvim-tree/_meta/config.lua | 149 ++++++++++++++++----- lua/nvim-tree/_meta/config/diagnostics.lua | 4 +- scripts/gen_vimdoc_config.lua | 2 +- 4 files changed, 182 insertions(+), 103 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 3423c58bce7..5d70d4af394 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3674,48 +3674,37 @@ Class: Config *nvim-tree-config* signcolumn. *nvim_tree.Config.Renderer.Icons.Glyphs* + Glyphs that appear in the sign column must have length <= 2 - Fields: ~ - • {default}? (`string`) Glyph for files. Overridden by - |nvim-tree.renderer.icons.web_devicons| if available. - Default: `""` - • {symlink}? (`string`) Glyph for symlinks to files. Default: `""` - • {bookmark}? (`string`) Bookmark icon. Default: `"Ὰ4"` - • {modified}? (`string`) Icon to display for modified files. Default: - `"●"` - • {hidden}? (`string`) Icon to display for hidden files. Default: - `"c""` - • {folder}? (`nvim_tree.Config.Renderer.Icons.Glyphs.Folder`) Glyphs - for directories. Overridden by - |nvim-tree.renderer.icons.web_devicons| if available. - Default: - `{ arrow_closed = "", arrow_open = "", default = "", open = "", empty = "", empty_open = "", symlink = "", symlink_open = "", }` - • {git}? (`nvim_tree.Config.Renderer.Icons.Glyphs.Git`) Glyphs for - git status. Default: - `{ unstaged = "✗", staged = "✓", unmerged = "", renamed = "➜", untracked = "★", deleted = "", ignored = "◌", }` - -*nvim_tree.Config.Renderer.Icons.Glyphs.Folder* + Glyphs defined elsewhere: + • |nvim_tree.Config.Diagnostics.Icons| + • |nvim_tree.Config.Renderer.IndentMarkers.Icons| Fields: ~ - • {arrow_closed}? (`string`) Default: `""` - • {arrow_open}? (`string`) Default: `""` - • {default}? (`string`) Default: `""` - • {open}? (`string`) Default: `""` - • {empty}? (`string`) Default: `""` - • {empty_open}? (`string`) Default: `""` - • {symlink}? (`string`) Default: `""` - • {symlink_open}? (`string`) Default: `""` - -*nvim_tree.Config.Renderer.Icons.Glyphs.Git* - - Fields: ~ - • {unstaged}? (`string`) Default: `"✗"` - • {staged}? (`string`) Default: `"✓"` - • {unmerged}? (`string`) Default: `""` - • {renamed}? (`string`) Default: `"➜"` - • {untracked}? (`string`) Default: `"★"` - • {deleted}? (`string`) Default: `""` - • {ignored}? (`string`) Default: `"◌"` + • {default}? (`string`, default: ``) Files, overridden by + |nvim_tree.Config.Renderer.Icons| {web_devicons} + • {symlink}? (`string`) (default: ``) + • {bookmark}? (`string`) (default: `󰆤`) + • {modified}? (`string`) (default: `●`) + • {hidden}? (`string`) (default: `󰜌`) + • {folder}? (`table`) Directories, overridden by + |nvim_tree.Config.Renderer.Icons| {web_devicons} + • {arrow_closed}? (`string`) (default: ` `) + • {arrow_open}? (`string`) (default: ``) + • {default}? (`string`) (default: ``) + • {open}? (`string`) (default: ``) + • {empty}? (`string`) (default: ``) + • {empty_open}? (`string`) (default: ``) + • {symlink}? (`string`) (default: ``) + • {symlink_open}? (`string`) (default: ``) + • {git}? (`table`) Git status. + • {unstaged}? (`string`) (default: `✗`) + • {staged}? (`string`) (default: `✓`) + • {unmerged}? (`string`) (default: ``) + • {renamed}? (`string`) (default: `➜`) + • {untracked}? (`string`) (default: `★`) + • {deleted}? (`string`) (default: ``) + • {ignored}? (`string`) (default: `◌`) *nvim_tree.Config.Renderer.Icons.Padding* @@ -3726,36 +3715,43 @@ Class: Config *nvim-tree-config* file/folder icon. Default: `" "` *nvim_tree.Config.Renderer.Icons.Show* + Control which icons are displayed. + + Left to right ordered: + • {file} + • {folder} + • {git} + • {modified} + • {hidden} + • {diagnostics} + • {bookmarks} Fields: ~ - • {file}? (`boolean`) Show an icon before the file name. - Default: `true` - • {folder}? (`boolean`) Show an icon before the folder name. - Default: `true` - • {folder_arrow}? (`boolean`) Show a small arrow before the folder - node. Arrow will be a part of the node when using - |renderer.indent_markers|. Default: `true` - • {git}? (`boolean`) Show a git status icon, see - |renderer.icons.git_placement| Requires |git.enable| - `= true` Default: `true` @see - nvim-tree.renderer.icons.git_placement @see - nvim-tree.git.enable - • {modified}? (`boolean`) Show a modified icon, see - |renderer.icons.modified_placement| Requires - |modified.enable| `= true` Default: `true` @see - nvim-tree.renderer.icons.modified_placement @see - nvim-tree.modified.enable - • {hidden}? (`boolean`) Show a hidden icon, see - |renderer.icons.hidden_placement| Default: `false` - @see nvim-tree.renderer.icons.hidden_placement - • {diagnostics}? (`boolean`) Show a diagnostics status icon, see - |renderer.icons.diagnostics_placement| Requires - |diagnostics.enable| `= true` Default: `true` @see - nvim-tree.renderer.icons.diagnostics_placement @see - nvim-tree.diagnostics.enable - • {bookmarks}? (`boolean`) Show a bookmark icon, see - |renderer.icons.bookmarks_placement| Default: `true` - @see nvim-tree.renderer.icons.bookmarks_placement + • {file}? (`boolean`, default: `true`) Before file name. + • {folder}? (`boolean`, default: `true`) Before folder name. + • {folder_arrow}? (`boolean`, default: `true`) Show a small arrow + before the folder node. Arrow will be a part of the + node when using |nvim_tree.Config.Renderer| + {indent_markers}. + • {git}? (`boolean`, default: `true`) Icons: + |nvim_tree.Config.Renderer.Icons.Glyphs.Git|. + Location: |nvim_tree.Config.Renderer.Icons| + {git_placement}. Requires |nvim_tree.Config.Git| + {enable}. + • {modified}? (`boolean`, default: `true`) Location: + |nvim_tree.Config.Renderer.Icons| + {modified_placement}. Requires + |nvim_tree.Config.Modified| {enable}. + • {hidden}? (`boolean`, default: `false`) Location: + |nvim_tree.Config.Renderer.Icons| {hidden_placement}. + • {diagnostics}? (`boolean`, default: `true`) Icons: + |nvim_tree.Config.Diagnostics.Icons| Location: + |nvim_tree.Config.Renderer.Icons| + {diagnostics_placement}. Requires + |nvim_tree.Config.Diagnostics| {enable}. + • {bookmarks}? (`boolean`, default: `true`) Location: + |nvim_tree.Config.Renderer.Icons| + {bookmarks_placement}. *nvim_tree.Config.Renderer.Icons.WebDevicons* diff --git a/lua/nvim-tree/_meta/config.lua b/lua/nvim-tree/_meta/config.lua index 283be552498..875b4a7df19 100644 --- a/lua/nvim-tree/_meta/config.lua +++ b/lua/nvim-tree/_meta/config.lua @@ -116,9 +116,6 @@ error("Cannot require a meta file") ---[nvim_tree.Config.Log] ---@field log? nvim_tree.Config.Log --- --- Renderer --- ---@class nvim_tree.Config.Renderer ---@field add_trailing? boolean Appends a trailing slash to folder and symlink folder destination names. Default: `false` @@ -140,11 +137,13 @@ error("Cannot require a meta file") ---@field indent_markers? nvim_tree.Config.Renderer.IndentMarkers Configuration options for tree indent markers. ---@field icons? nvim_tree.Config.Renderer.Icons Configuration options for icons. + ---@class nvim_tree.Config.Renderer.IndentMarkers ---@field enable? boolean Display indent markers when folders are open Default: `false` ---@field inline_arrows? boolean Display folder arrows in the same column as indent marker when using |renderer.icons.show.folder_arrow| Default: `true` ---@field icons? nvim_tree.Config.Renderer.IndentMarkers.Icons Icons shown before the file/directory. Length 1. Default: > lua { corner = "└", edge = "│", item = "│", bottom = "─", none = " ", } + ---@class nvim_tree.Config.Renderer.IndentMarkers.Icons ---@field corner? string Default: `"└"` ---@field edge? string Default: `"│"` @@ -152,6 +151,7 @@ error("Cannot require a meta file") ---@field bottom? string Default: `"─"` ---@field none? string Default: `" "` + ---@class nvim_tree.Config.Renderer.Icons Configuration options for icons. ---@field web_devicons? nvim_tree.Config.Renderer.Icons.WebDevicons Configure optional plugin `"nvim-tree/nvim-web-devicons"` ---@field git_placement? nvim_tree.PlacementOption Git icons placement. Default: `"before"` @@ -164,56 +164,139 @@ error("Cannot require a meta file") ---@field show? nvim_tree.Config.Renderer.Icons.Show Configuration options for showing icon types. Left to right order: file/folder, git, modified, hidden, diagnostics, bookmarked. ---@field glyphs? nvim_tree.Config.Renderer.Icons.Glyphs Configuration options for icon glyphs. NOTE: Do not set any glyphs to more than two characters if it's going to appear in the signcolumn. + ---@class nvim_tree.Config.Renderer.Icons.WebDevicons ---@field file? nvim_tree.Config.Renderer.Icons.WebDevicons.File File icons. ---@field folder? nvim_tree.Config.Renderer.Icons.WebDevicons.Folder Folder icons. + ---@class nvim_tree.Config.Renderer.Icons.WebDevicons.File ---@field enable? boolean Show icons on files. Overrides |nvim-tree.renderer.icons.glyphs.default| Default: `true` ---@field color? boolean Use icon colors for files. Overrides highlight groups. Default: `true` + ---@class nvim_tree.Config.Renderer.Icons.WebDevicons.Folder ---@field enable? boolean Show icons on folders. Overrides |nvim-tree.renderer.icons.glyphs.folder| Default: `false` ---@field color? boolean Use icon colors for folders. Overrides highlight groups. Default: `true` + ---@class nvim_tree.Config.Renderer.Icons.Padding ---@field icon? string Inserted between icon and filename. Default: `" "` ---@field folder_arrow? string Inserted between folder arrow icon and file/folder icon. Default: `" "` + +---Control which icons are displayed. +--- +---Left to right ordered: +---- {file} +---- {folder} +---- {git} +---- {modified} +---- {hidden} +---- {diagnostics} +---- {bookmarks} +--- ---@class nvim_tree.Config.Renderer.Icons.Show ----@field file? boolean Show an icon before the file name. Default: `true` ----@field folder? boolean Show an icon before the folder name. Default: `true` ----@field folder_arrow? boolean Show a small arrow before the folder node. Arrow will be a part of the node when using |renderer.indent_markers|. Default: `true` ----@field git? boolean Show a git status icon, see |renderer.icons.git_placement| Requires |git.enable| `= true` Default: `true` @see nvim-tree.renderer.icons.git_placement @see nvim-tree.git.enable ----@field modified? boolean Show a modified icon, see |renderer.icons.modified_placement| Requires |modified.enable| `= true` Default: `true` @see nvim-tree.renderer.icons.modified_placement @see nvim-tree.modified.enable ----@field hidden? boolean Show a hidden icon, see |renderer.icons.hidden_placement| Default: `false` @see nvim-tree.renderer.icons.hidden_placement ----@field diagnostics? boolean Show a diagnostics status icon, see |renderer.icons.diagnostics_placement| Requires |diagnostics.enable| `= true` Default: `true` @see nvim-tree.renderer.icons.diagnostics_placement @see nvim-tree.diagnostics.enable ----@field bookmarks? boolean Show a bookmark icon, see |renderer.icons.bookmarks_placement| Default: `true` @see nvim-tree.renderer.icons.bookmarks_placement +--- +---Before file name. +---(default: `true`) +---@field file? boolean +--- +---Before folder name. +---(default: `true`) +---@field folder? boolean +--- +---Show a small arrow before the folder node. Arrow will be a part of the node when using [nvim_tree.Config.Renderer] {indent_markers}. +---(default: `true`) +---@field folder_arrow? boolean +--- +---Icons: [nvim_tree.Config.Renderer.Icons.Glyphs.Git]. +---Location: [nvim_tree.Config.Renderer.Icons] {git_placement}. +---Requires |nvim_tree.Config.Git| {enable}. +---(default: `true`) +---@field git? boolean +--- +---Location: [nvim_tree.Config.Renderer.Icons] {modified_placement}. +---Requires |nvim_tree.Config.Modified| {enable}. +---(default: `true`) +---@field modified? boolean +--- +---Location: [nvim_tree.Config.Renderer.Icons] {hidden_placement}. +---(default: `false`) +---@field hidden? boolean +--- +---Icons: [nvim_tree.Config.Diagnostics.Icons] +---Location: [nvim_tree.Config.Renderer.Icons] {diagnostics_placement}. +---Requires |nvim_tree.Config.Diagnostics| {enable}. +---(default: `true`) +---@field diagnostics? boolean +--- +---Location: [nvim_tree.Config.Renderer.Icons] {bookmarks_placement}. +---(default: `true`) +---@field bookmarks? boolean + +---Glyphs that appear in the sign column must have length <= 2 +--- +---Glyphs defined elsewhere: +---- [nvim_tree.Config.Diagnostics.Icons] +---- [nvim_tree.Config.Renderer.IndentMarkers.Icons] ---@class nvim_tree.Config.Renderer.Icons.Glyphs ----@field default? string Glyph for files. Overridden by |nvim-tree.renderer.icons.web_devicons| if available. Default: `""` ----@field symlink? string Glyph for symlinks to files. Default: `""` ----@field bookmark? string Bookmark icon. Default: `"Ὰ4"` ----@field modified? string Icon to display for modified files. Default: `"●"` ----@field hidden? string Icon to display for hidden files. Default: `"c""` ----@field folder? nvim_tree.Config.Renderer.Icons.Glyphs.Folder Glyphs for directories. Overridden by |nvim-tree.renderer.icons.web_devicons| if available. Default: `{ arrow_closed = "", arrow_open = "", default = "", open = "", empty = "", empty_open = "", symlink = "", symlink_open = "", }` ----@field git? nvim_tree.Config.Renderer.Icons.Glyphs.Git Glyphs for git status. Default: `{ unstaged = "✗", staged = "✓", unmerged = "", renamed = "➜", untracked = "★", deleted = "", ignored = "◌", }` +--- +---Files, overridden by [nvim_tree.Config.Renderer.Icons] {web_devicons} +---(default: ``) +---@field default? string +--- +---(default: ``) +---@field symlink? string +--- +---(default: `󰆤`) +---@field bookmark? string +--- +---(default: `●`) +---@field modified? string +--- +---(default: `󰜌`) +---@field hidden? string +--- +---Directories, overridden by [nvim_tree.Config.Renderer.Icons] {web_devicons} +---@field folder? nvim_tree.Config.Renderer.Icons.Glyphs.Folder +--- +---Git status. +---@field git? nvim_tree.Config.Renderer.Icons.Glyphs.Git ---@class nvim_tree.Config.Renderer.Icons.Glyphs.Folder ----@field arrow_closed? string Default: `""` ----@field arrow_open? string Default: `""` ----@field default? string Default: `""` ----@field open? string Default: `""` ----@field empty? string Default: `""` ----@field empty_open? string Default: `""` ----@field symlink? string Default: `""` ----@field symlink_open? string Default: `""` +---@inlinedoc +---(default: ``) +---@field arrow_closed? string +---(default: ``) +---@field arrow_open? string +---(default: ``) +---@field default? string +---(default: ``) +---@field open? string +---(default: ``) +---@field empty? string +---(default: ``) +---@field empty_open? string +---(default: ``) +---@field symlink? string +---(default: ``) +---@field symlink_open? string ---@class nvim_tree.Config.Renderer.Icons.Glyphs.Git ----@field unstaged? string Default: `"✗"` ----@field staged? string Default: `"✓"` ----@field unmerged? string Default: `""` ----@field renamed? string Default: `"➜"` ----@field untracked? string Default: `"★"` ----@field deleted? string Default: `""` ----@field ignored? string Default: `"◌"` +---@inlinedoc +---(default: `✗`) +---@field unstaged? string +---(default: `✓`) +---@field staged? string +---(default: ``) +---@field unmerged? string +---(default: `➜`) +---@field renamed? string +---(default: `★`) +---@field untracked? string +---(default: ``) +---@field deleted? string +---(default: `◌`) +---@field ignored? string diff --git a/lua/nvim-tree/_meta/config/diagnostics.lua b/lua/nvim-tree/_meta/config/diagnostics.lua index 0775945603c..4175c3b1d94 100644 --- a/lua/nvim-tree/_meta/config/diagnostics.lua +++ b/lua/nvim-tree/_meta/config/diagnostics.lua @@ -30,8 +30,8 @@ error("Cannot require a meta file") ---[nvim_tree.Config.Diagnostics.Icons] ---@field icons? nvim_tree.Config.Diagnostics.Icons ----@inlinedoc ---@class nvim_tree.Config.Diagnostics.Severity +---@inlinedoc --- ---[vim.diagnostic.Severity] ---(default: HINT) @@ -41,8 +41,8 @@ error("Cannot require a meta file") ---(default: ERROR) ---@field max? vim.diagnostic.Severity ----@inlinedoc ---@class nvim_tree.Config.Diagnostics.Icons +---@inlinedoc --- ---(default: ) ---@field hint? string diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua index bebf6a761ab..a0ce0ee4ea6 100644 --- a/scripts/gen_vimdoc_config.lua +++ b/scripts/gen_vimdoc_config.lua @@ -11,7 +11,7 @@ local modules = { { helptag = "nvim-tree-config", title = "Class: Config", path = "lua/nvim-tree/_meta/config.lua", }, { helptag = "nvim-tree-config-sort", title = "Class: Config.Sort", path = "lua/nvim-tree/_meta/config/sort.lua", }, { helptag = "nvim-tree-config-view", title = "Class: Config.View", path = "lua/nvim-tree/_meta/config/view.lua", }, - { helptag = "nvim-tree-config-YYY", title = "Class: Config.", path = "lua/nvim-tree/_meta/config/renderer.lua", }, + { helptag = "nvim-tree-config-renderer", title = "Class: Config.Renderer", path = "lua/nvim-tree/_meta/config/renderer.lua", }, { helptag = "nvim-tree-config-hijack-directories", title = "Class: Config.HijackDirectories", path = "lua/nvim-tree/_meta/config/hijack_directories.lua", }, { helptag = "nvim-tree-config-update-focused-file", title = "Class: Config.UpdateFocusedFile", path = "lua/nvim-tree/_meta/config/update_focused_file.lua", }, { helptag = "nvim-tree-config-system-open", title = "Class: Config.SystemOpen", path = "lua/nvim-tree/_meta/config/system_open.lua", }, From 93e3122a44f6ede5733fed88e7713a8d8a73865d Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sun, 11 Jan 2026 16:04:00 +1100 Subject: [PATCH 039/170] docs(#2934): remove problematic glyphs, tidy other glyphs --- doc/nvim-tree-lua.txt | 54 +++++++++++----------- lua/nvim-tree/_meta/config.lua | 44 +++++++++--------- lua/nvim-tree/_meta/config/diagnostics.lua | 8 ++-- 3 files changed, 53 insertions(+), 53 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 5d70d4af394..2054af4065f 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3681,30 +3681,30 @@ Class: Config *nvim-tree-config* • |nvim_tree.Config.Renderer.IndentMarkers.Icons| Fields: ~ - • {default}? (`string`, default: ``) Files, overridden by + • {default}? (`string`, default: `` ) Files, overridden by |nvim_tree.Config.Renderer.Icons| {web_devicons} - • {symlink}? (`string`) (default: ``) - • {bookmark}? (`string`) (default: `󰆤`) - • {modified}? (`string`) (default: `●`) - • {hidden}? (`string`) (default: `󰜌`) - • {folder}? (`table`) Directories, overridden by - |nvim_tree.Config.Renderer.Icons| {web_devicons} - • {arrow_closed}? (`string`) (default: ` `) - • {arrow_open}? (`string`) (default: ``) - • {default}? (`string`) (default: ``) - • {open}? (`string`) (default: ``) - • {empty}? (`string`) (default: ``) - • {empty_open}? (`string`) (default: ``) - • {symlink}? (`string`) (default: ``) - • {symlink_open}? (`string`) (default: ``) - • {git}? (`table`) Git status. - • {unstaged}? (`string`) (default: `✗`) - • {staged}? (`string`) (default: `✓`) - • {unmerged}? (`string`) (default: ``) - • {renamed}? (`string`) (default: `➜`) - • {untracked}? (`string`) (default: `★`) - • {deleted}? (`string`) (default: ``) - • {ignored}? (`string`) (default: `◌`) + • {symlink}? (`string`) (default: `` ) + • {bookmark}? (`string`) (default: `󰆤` ) + • {modified}? (`string`) (default: `●` ) + • {hidden}? (`string`) (default: `󰜌` ) + • {folder}? (`table`) Overridden by |nvim_tree.Config.Renderer.Icons| + {web_devicons} + • {arrow_closed}? (`string`) (default: left arrow) + • {arrow_open}? (`string`) (default: down arrow) + • {default}? (`string`) (default: `` ) + • {open}? (`string`) (default: `` ) + • {empty}? (`string`) (default: `` ) + • {empty_open}? (`string`) (default: `` ) + • {symlink}? (`string`) (default: `` ) + • {symlink_open}? (`string`) (default: `` ) + • {git}? (`table`) Git status on files and directories. + • {unstaged}? (`string`) (default: `✗` ) + • {staged}? (`string`) (default: `✓` ) + • {unmerged}? (`string`) (default: `` ) + • {renamed}? (`string`) (default: `➜` ) + • {untracked}? (`string`) (default: `★` ) + • {deleted}? (`string`) (default: `` ) + • {ignored}? (`string`) (default: `◌` ) *nvim_tree.Config.Renderer.Icons.Padding* @@ -4054,10 +4054,10 @@ Class: Config.Diagnostics *nvim-tree-config-diagnostics* • {max}? (`vim.diagnostic.Severity`, default: ERROR) |vim.diagnostic.Severity| • {icons}? (`table`) |nvim_tree.Config.Diagnostics.Icons| - • {hint}? (`string`) (default: ) - • {info}? (`string`) (default: ) - • {warning}? (`string`) (default: ) - • {error}? (`string`) (default: ) + • {hint}? (`string`) (default: `` ) + • {info}? (`string`) (default: `` ) + • {warning}? (`string`) (default: `` ) + • {error}? (`string`) (default: `` ) diff --git a/lua/nvim-tree/_meta/config.lua b/lua/nvim-tree/_meta/config.lua index 875b4a7df19..468178ed2bb 100644 --- a/lua/nvim-tree/_meta/config.lua +++ b/lua/nvim-tree/_meta/config.lua @@ -244,59 +244,59 @@ error("Cannot require a meta file") ---@class nvim_tree.Config.Renderer.Icons.Glyphs --- ---Files, overridden by [nvim_tree.Config.Renderer.Icons] {web_devicons} ----(default: ``) +---(default: `` ) ---@field default? string --- ----(default: ``) +---(default: `` ) ---@field symlink? string --- ----(default: `󰆤`) +---(default: `󰆤` ) ---@field bookmark? string --- ----(default: `●`) +---(default: `●` ) ---@field modified? string --- ----(default: `󰜌`) +---(default: `󰜌` ) ---@field hidden? string --- ----Directories, overridden by [nvim_tree.Config.Renderer.Icons] {web_devicons} +---Overridden by [nvim_tree.Config.Renderer.Icons] {web_devicons} ---@field folder? nvim_tree.Config.Renderer.Icons.Glyphs.Folder --- ----Git status. +---Git status on files and directories. ---@field git? nvim_tree.Config.Renderer.Icons.Glyphs.Git ---@class nvim_tree.Config.Renderer.Icons.Glyphs.Folder ---@inlinedoc ----(default: ``) +---(default: left arrow) ---@field arrow_closed? string ----(default: ``) +---(default: down arrow) ---@field arrow_open? string ----(default: ``) +---(default: `` ) ---@field default? string ----(default: ``) +---(default: `` ) ---@field open? string ----(default: ``) +---(default: `` ) ---@field empty? string ----(default: ``) +---(default: `` ) ---@field empty_open? string ----(default: ``) +---(default: `` ) ---@field symlink? string ----(default: ``) +---(default: `` ) ---@field symlink_open? string ---@class nvim_tree.Config.Renderer.Icons.Glyphs.Git ---@inlinedoc ----(default: `✗`) +---(default: `✗` ) ---@field unstaged? string ----(default: `✓`) +---(default: `✓` ) ---@field staged? string ----(default: ``) +---(default: `` ) ---@field unmerged? string ----(default: `➜`) +---(default: `➜` ) ---@field renamed? string ----(default: `★`) +---(default: `★` ) ---@field untracked? string ----(default: ``) +---(default: `` ) ---@field deleted? string ----(default: `◌`) +---(default: `◌` ) ---@field ignored? string diff --git a/lua/nvim-tree/_meta/config/diagnostics.lua b/lua/nvim-tree/_meta/config/diagnostics.lua index 4175c3b1d94..f15f5baee45 100644 --- a/lua/nvim-tree/_meta/config/diagnostics.lua +++ b/lua/nvim-tree/_meta/config/diagnostics.lua @@ -44,14 +44,14 @@ error("Cannot require a meta file") ---@class nvim_tree.Config.Diagnostics.Icons ---@inlinedoc --- ----(default: ) +---(default: `` ) ---@field hint? string --- ----(default: ) +---(default: `` ) ---@field info? string --- ----(default: ) +---(default: `` ) ---@field warning? string --- ----(default: ) +---(default: `` ) ---@field error? string From 25d57bc2b92e509e8171fd0e28c73ef5a46aaba8 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sun, 11 Jan 2026 16:49:39 +1100 Subject: [PATCH 040/170] docs(#2934): tidy Config.Renderer, ensure functions are parenthesised when necessary --- doc/nvim-tree-lua.txt | 101 ++++++++++-------- lua/nvim-tree/_meta/config.lua | 95 +++++++++++++--- lua/nvim-tree/_meta/config/actions.lua | 2 +- .../_meta/config/filesystem_watchers.lua | 2 +- lua/nvim-tree/_meta/config/filters.lua | 2 +- lua/nvim-tree/_meta/config/git.lua | 2 +- lua/nvim-tree/_meta/config/sort.lua | 2 +- .../_meta/config/update_focused_file.lua | 2 +- lua/nvim-tree/_meta/config/view.lua | 4 +- 9 files changed, 141 insertions(+), 71 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 2054af4065f..f2d428649f7 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3465,7 +3465,7 @@ Class: Config *nvim-tree-config* TODO #2934 brief and some links Fields: ~ - • {on_attach}? (`string|fun(bufnr: integer)`) Runs when + • {on_attach}? (`string|(fun(bufnr: integer))`) Runs when creating the nvim-tree buffer. Use this to set your |nvim-tree-mappings|. When `on_attach` is not a function, @@ -3548,48 +3548,55 @@ Class: Config *nvim-tree-config* |nvim_tree.Config.Log| *nvim_tree.Config.Renderer* + TODO overview + + {root_folder_label} has 3 forms: + • `string`: |filename-modifiers| format string + • `boolean`: `true` to disable + • `fun(root_cwd: string): string`: string from root absolute path e.g. >lua + my_root_folder_label = function(path) + return ".../" .. vim.fn.fnamemodify(path, ":t") + end +< + + TODO: link to hidden display help section + *nvim_tree.Config.Renderer.HiddenDisplay* + + {hidden_display} summary of hidden files below the tree. + • `none`: disabled + • `simple`: show how many hidden files are in a folder + • `all`: show how many hidden and the number of hidden files by reason + • `fun(hidden_stats: table): string`: returns a summary + of hidden stats Fields: ~ - • {add_trailing}? (`boolean`) Appends a trailing slash to - folder and symlink folder destination - names. Default: `false` - • {group_empty}? (`boolean|fun(relative_path: string): string`) + • {add_trailing}? (`boolean`, default: `false`) Appends a + trailing slash to folder and symlink folder + destination names. + • {group_empty}? (`boolean|(fun(relative_path: string): string)`, default: `false`) Compact folders that only contain a single - folder into one node. Boolean or function - that takes one argument (the relative path - of grouped folders) and returns a string to - be displayed. Default: `false` - • {full_name}? (`boolean`) Display node whose name length - is wider than the width of nvim-tree window - in floating window. Default: `false` - • {root_folder_label}? (`string|boolean|fun(root_cwd: string): string`) - In what format to show root folder. See - `:help filename-modifiers` for available - `string` options. Set to `false` to hide - the root folder. or `boolean` or - `function(root_cwd)`, Default: - `":~:s?$?/..?"` - • {indent_width}? (`integer`) Number of spaces for an each - tree nesting level. Minimum 1. Default: `2` - • {special_files}? (`string[]`) A list of filenames that gets - highlighted with `NvimTreeSpecialFile`. - Default: - `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }` - • {hidden_display}? (`(fun(hidden_stats: table): string)|nvim_tree.HiddenDisplayOption`) - Show a summary of hidden files below the - tree using - `NvimTreeHiddenDisplay Default: `"none"` - • {symlink_destination}? (`boolean`) Whether to show the destination - of the symlink. Default: `true` - • {decorators}? (`(string|nvim_tree.api.decorator.UserDecorator)[]`) + folder into one node. Function variant + takes the relative path of grouped folders + and returns a string to be displayed. + • {full_name}? (`boolean`, default: `false`) Display node + whose name length is wider than the width + of nvim-tree window in floating window. + • {root_folder_label}? (`string|boolean|(fun(root_cwd: string): string)`) + (default: `":~:s?$?/..?"`) + • {indent_width}? (`integer`, default: `2`) Number of spaces + for an each tree nesting level. Minimum 1. + • {special_files}? (`string[]`, default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }`) + A list of filenames that gets highlighted + with `NvimTreeSpecialFile`. + • {hidden_display}? (`nvim_tree.Config.Renderer.HiddenDisplay`) + (default: `none`) + • {symlink_destination}? (`boolean`, default: `true`) Appends an + arrow followed by the destination of the + symlink. + • {decorators}? (`(string|nvim_tree.api.decorator.UserDecorator)[]`, default: `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) Highlighting and icons for the nodes, in - increasing order of precedence. Uses - strings to specify builtin decorators - otherwise specify your - `nvim_tree.api.decorator.UserDecorator` - class. Default: > lua { "Git", "Open", - "Hidden", "Modified", "Bookmark", - "Diagnostics", "Copied", "Cut", } + increasing order of precedence. Strings + specify builtin decorators. • {highlight_git}? (`nvim_tree.HighlightOption`) Enable highlight for git attributes using `NvimTreeGit*HL` highlight groups. Requires @@ -3831,7 +3838,7 @@ Class: Config.Sort *nvim-tree-config-sort* {sorter} may be a function that returns a |nvim_tree.Config.Sort.Sorter| Fields: ~ - • {sorter}? (`nvim_tree.Config.Sort.Sorter|fun(nodes: nvim_tree.api.Node[]): nvim_tree.Config.Sort.Sorter?`) + • {sorter}? (`nvim_tree.Config.Sort.Sorter|(fun(nodes: nvim_tree.api.Node[]): nvim_tree.Config.Sort.Sorter?)`) (default: `name`) • {folders_first}? (`boolean`, default: `true`) Sort folders before files. Has no effect when {sorter} is a function. @@ -3908,7 +3915,7 @@ Class: Config.View *nvim-tree-config-view* • {enable}? (`boolean`) (default: `false`) • {quit_on_focus_loss}? (`boolean`, default: `true`) Close the floating window when it loses focus. - • {open_win_config}? (`vim.api.keyset.win_config|fun(): vim.api.keyset.win_config`) + • {open_win_config}? (`vim.api.keyset.win_config|(fun(): vim.api.keyset.win_config)`) (default: above) *nvim_tree.Config.View.Width* @@ -3953,7 +3960,7 @@ Class: Config.UpdateFocusedFile *nvim-tree-config-update-focused-file* • {enable}? (`boolean`) (default: `false`) • {update_root}? (`nvim_tree.Config.UpdateFocusedFile.UpdateRoot`) |nvim_tree.Config.UpdateFocusedFile.UpdateRoot| - • {exclude}? (`boolean|fun(args: vim.api.keyset.create_autocmd.callback_args): boolean`, default: `false`) + • {exclude}? (`boolean|(fun(args: vim.api.keyset.create_autocmd.callback_args): boolean)`, default: `false`) A function called on |BufEnter| that returns true if the file should not be focused when opening. @@ -4020,8 +4027,8 @@ Class: Config.Git *nvim-tree-config-git* • {show_on_open_dirs}? (`boolean`, default: `true`) Show status icons of children on directories that are open. Only relevant when {show_on_dirs} is `true`. - • {disable_for_dirs}? (`string[]|fun(path: string): boolean`, default: - `{}`) Disable for top level paths. + • {disable_for_dirs}? (`string[]|(fun(path: string): boolean)`, + default: `{}`) Disable for top level paths. • {timeout}? (`integer`, default: `400`) `git` processes timeout milliseconds. • {cygwin_support}? (`boolean`, default: `false`) Use `cygpath` if @@ -4133,7 +4140,7 @@ overriding {git_ignored}, {dotfiles} and {custom} • {git_clean}? (`boolean`) (default: `false`) • {no_buffer}? (`boolean`) (default: `false`) • {no_bookmark}? (`boolean`) (default: `false`) - • {custom}? (`string[]|fun(absolute_path: string): boolean`) + • {custom}? (`string[]|(fun(absolute_path: string): boolean)`) (default: `{}`) • {exclude}? (`string[]`) (default: `{}`) @@ -4178,7 +4185,7 @@ Class: Config.FilesystemWatchers *nvim-tree-config-filesystem-watchers* • {enable}? (`boolean`) (default: `true`) • {debounce_delay}? (`integer`, default: `50`) Idle milliseconds between filesystem change and tree update. - • {ignore_dirs}? (`string[]|fun(path: string): boolean`, default: `{ "/.ccls-cache", "/build", "/node_modules", "/target", }`) + • {ignore_dirs}? (`string[]|(fun(path: string): boolean)`, default: `{ "/.ccls-cache", "/build", "/node_modules", "/target", }`) Disable for directories. @@ -4276,7 +4283,7 @@ Class: Config.Actions *nvim-tree-config-actions* Fields: ~ • {enable}? (`boolean`) (default: `true`) - • {picker}? (`string|fun(): integer`, default: `default`) Change the + • {picker}? (`string|(fun(): integer)`, default: `default`) Change the default window picker: string `default` or a function. • {chars}? (`string`, default: `"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"`) Identifier diff --git a/lua/nvim-tree/_meta/config.lua b/lua/nvim-tree/_meta/config.lua index 468178ed2bb..c4132d0292b 100644 --- a/lua/nvim-tree/_meta/config.lua +++ b/lua/nvim-tree/_meta/config.lua @@ -4,7 +4,6 @@ error("Cannot require a meta file") --- TODO #2934 these were not correctly generated, inline or fix ---@alias nvim_tree.PlacementOption "before"|"after"|"signcolumn"|"right_align" ---@alias nvim_tree.HighlightOption "none"|"icon"|"name"|"all" ----@alias nvim_tree.HiddenDisplayOption "none"|"simple"|"all" --- TODO #2934 brief and some links --- @@ -12,7 +11,7 @@ error("Cannot require a meta file") ---@class nvim_tree.Config --- ---Runs when creating the nvim-tree buffer. Use this to set your [nvim-tree-mappings]. When `on_attach` is not a function, [nvim-tree-mappings-default] will be called. ----@field on_attach? string|fun(bufnr: integer) +---@field on_attach? string|(fun(bufnr: integer)) --- ---Keeps the cursor on the first letter of the filename when moving in the tree. ---(default: `false`) @@ -117,24 +116,88 @@ error("Cannot require a meta file") ---@field log? nvim_tree.Config.Log +---@alias nvim_tree.Config.Renderer.HiddenDisplay "none"|"simple"|"all"|(fun(hidden_stats: table): string) + +---TODO overview +--- +---{root_folder_label} has 3 forms: +---- `string`: [filename-modifiers] format string +---- `boolean`: `true` to disable +---- `fun(root_cwd: string): string`: string from root absolute path e.g. +---```lua +---my_root_folder_label = function(path) +--- return ".../" .. vim.fn.fnamemodify(path, ":t") +---end +---``` +--- +---TODO: link to hidden display help section [nvim_tree.Config.Renderer.HiddenDisplay]() +--- +---{hidden_display} summary of hidden files below the tree. +---- `none`: disabled +---- `simple`: show how many hidden files are in a folder +---- `all`: show how many hidden and the number of hidden files by reason +---- `fun(hidden_stats: table): string`: returns a summary of hidden stats +--- ---@class nvim_tree.Config.Renderer ----@field add_trailing? boolean Appends a trailing slash to folder and symlink folder destination names. Default: `false` ----@field group_empty? boolean|fun(relative_path: string): string Compact folders that only contain a single folder into one node. Boolean or function that takes one argument (the relative path of grouped folders) and returns a string to be displayed. Default: `false` ----@field full_name? boolean Display node whose name length is wider than the width of nvim-tree window in floating window. Default: `false` ----@field root_folder_label? string|boolean|fun(root_cwd: string): string In what format to show root folder. See `:help filename-modifiers` for available `string` options. Set to `false` to hide the root folder. or `boolean` or `function(root_cwd)`, Default: `":~:s?$?/..?"` ----@field indent_width? integer Number of spaces for an each tree nesting level. Minimum 1. Default: `2` ----@field special_files? string[] A list of filenames that gets highlighted with `NvimTreeSpecialFile`. Default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }` ----@field hidden_display? (fun(hidden_stats: table): string)|nvim_tree.HiddenDisplayOption Show a summary of hidden files below the tree using `NvimTreeHiddenDisplay Default: `"none"` ----@field symlink_destination? boolean Whether to show the destination of the symlink. Default: `true` ----@field decorators? (string|nvim_tree.api.decorator.UserDecorator)[] Highlighting and icons for the nodes, in increasing order of precedence. Uses strings to specify builtin decorators otherwise specify your `nvim_tree.api.decorator.UserDecorator` class. Default: > lua { "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", } +--- +---Appends a trailing slash to folder and symlink folder destination names. +---(default: `false`) +---@field add_trailing? boolean +--- +---Compact folders that only contain a single folder into one node. Function variant takes the relative path of grouped folders and returns a string to be displayed. +---(default: `false`) +---@field group_empty? boolean|(fun(relative_path: string): string) +--- +---Display node whose name length is wider than the width of nvim-tree window in floating window. +---(default: `false`) +---@field full_name? boolean +--- +---(default: `":~:s?$?/..?"`) +---@field root_folder_label? string|boolean|(fun(root_cwd: string): string) +--- +---Number of spaces for an each tree nesting level. Minimum 1. +---(default: `2`) +---@field indent_width? integer +--- +---A list of filenames that gets highlighted with `NvimTreeSpecialFile`. +---(default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }`) +---@field special_files? string[] +--- +---(default: `none`) +---@field hidden_display? nvim_tree.Config.Renderer.HiddenDisplay +--- +---Appends an arrow followed by the destination of the symlink. +---(default: `true`) +---@field symlink_destination? boolean +--- +---Highlighting and icons for the nodes, in increasing order of precedence. Strings specify builtin decorators. +---(default: `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) +---@field decorators? (string|nvim_tree.api.decorator.UserDecorator)[] +--- ---@field highlight_git? nvim_tree.HighlightOption Enable highlight for git attributes using `NvimTreeGit*HL` highlight groups. Requires |nvim-tree.git.enable| Value can be `"none"`, `"icon"`, `"name"` or `"all"`. Default: `"none"` @see nvim-tree.git.enable +--- +--- ---@field highlight_diagnostics? nvim_tree.HighlightOption Enable highlight for diagnostics using `NvimTreeDiagnostic*HL` highlight groups. Requires |nvim-tree.diagnostics.enable| Value can be `"none"`, `"icon"`, `"name"` or `"all"`. Default: `"none"` @see nvim-tree.diagnostics.enable +--- +--- ---@field highlight_opened_files? nvim_tree.HighlightOption Highlight icons and/or names for |bufloaded()| files using the `NvimTreeOpenedHL` highlight group. See |nvim-tree-api.navigate.opened.next()| and |nvim-tree-api.navigate.opened.prev()| Value can be `"none"`, `"icon"`, `"name"` or `"all"`. Default: `"none"` +--- +--- ---@field highlight_modified? nvim_tree.HighlightOption Highlight icons and/or names for modified files using the `NvimTreeModifiedFile` highlight group. Requires |nvim-tree.modified.enable| Value can be `"none"`, `"icon"`, `"name"` or `"all"` Default `"none"` @see nvim-tree.modified.enable +--- +--- ---@field highlight_hidden? nvim_tree.HighlightOption Highlight icons and/or names for hidden files (dotfiles) using the `NvimTreeHiddenFileHL` highlight group. Value can be `"none"`, `"icon"`, `"name"` or `"all"` Default `"none"` +--- +--- ---@field highlight_bookmarks? nvim_tree.HighlightOption Highlight bookmarked using the `NvimTreeBookmarkHL` group. Value can be `"none"`, `"icon"`, `"name"` or `"all"` Default `"none"` +--- +--- ---@field highlight_clipboard? nvim_tree.HighlightOption Enable highlight for clipboard items using the `NvimTreeCutHL` and `NvimTreeCopiedHL` groups. Value can be `"none"`, `"icon"`, `"name"` or `"all"`. Default: `"name"` +--- +--- ---@field indent_markers? nvim_tree.Config.Renderer.IndentMarkers Configuration options for tree indent markers. +--- +--- ---@field icons? nvim_tree.Config.Renderer.Icons Configuration options for icons. @@ -208,7 +271,7 @@ error("Cannot require a meta file") --- ---Show a small arrow before the folder node. Arrow will be a part of the node when using [nvim_tree.Config.Renderer] {indent_markers}. ---(default: `true`) ----@field folder_arrow? boolean +---@field folder_arrow? boolean --- ---Icons: [nvim_tree.Config.Renderer.Icons.Glyphs.Git]. ---Location: [nvim_tree.Config.Renderer.Icons] {git_placement}. @@ -223,17 +286,17 @@ error("Cannot require a meta file") --- ---Location: [nvim_tree.Config.Renderer.Icons] {hidden_placement}. ---(default: `false`) ----@field hidden? boolean +---@field hidden? boolean --- ---Icons: [nvim_tree.Config.Diagnostics.Icons] ---Location: [nvim_tree.Config.Renderer.Icons] {diagnostics_placement}. ---Requires |nvim_tree.Config.Diagnostics| {enable}. ---(default: `true`) ----@field diagnostics? boolean +---@field diagnostics? boolean --- ---Location: [nvim_tree.Config.Renderer.Icons] {bookmarks_placement}. ---(default: `true`) ----@field bookmarks? boolean +---@field bookmarks? boolean ---Glyphs that appear in the sign column must have length <= 2 @@ -260,7 +323,7 @@ error("Cannot require a meta file") ---@field hidden? string --- ---Overridden by [nvim_tree.Config.Renderer.Icons] {web_devicons} ----@field folder? nvim_tree.Config.Renderer.Icons.Glyphs.Folder +---@field folder? nvim_tree.Config.Renderer.Icons.Glyphs.Folder --- ---Git status on files and directories. ---@field git? nvim_tree.Config.Renderer.Icons.Glyphs.Git diff --git a/lua/nvim-tree/_meta/config/actions.lua b/lua/nvim-tree/_meta/config/actions.lua index 5f6dac26103..3b23fe3f653 100644 --- a/lua/nvim-tree/_meta/config/actions.lua +++ b/lua/nvim-tree/_meta/config/actions.lua @@ -102,7 +102,7 @@ error("Cannot require a meta file") --- ---Change the default window picker: string `default` or a function. ---(default: `default`) ----@field picker? string|fun(): integer +---@field picker? string|(fun(): integer) --- ---Identifier characters to use. ---(default: `"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"`) diff --git a/lua/nvim-tree/_meta/config/filesystem_watchers.lua b/lua/nvim-tree/_meta/config/filesystem_watchers.lua index 0e8f7e098dd..85b4e807c6a 100644 --- a/lua/nvim-tree/_meta/config/filesystem_watchers.lua +++ b/lua/nvim-tree/_meta/config/filesystem_watchers.lua @@ -20,4 +20,4 @@ error("Cannot require a meta file") --- ---Disable for directories. ---(default: `{ "/.ccls-cache", "/build", "/node_modules", "/target", }`) ----@field ignore_dirs? string[]|fun(path: string): boolean +---@field ignore_dirs? string[]|(fun(path: string): boolean) diff --git a/lua/nvim-tree/_meta/config/filters.lua b/lua/nvim-tree/_meta/config/filters.lua index 4e36dad893d..1d028495e56 100644 --- a/lua/nvim-tree/_meta/config/filters.lua +++ b/lua/nvim-tree/_meta/config/filters.lua @@ -64,7 +64,7 @@ error("Cannot require a meta file") ---@field no_bookmark? boolean --- ---(default: `{}`) ----@field custom? string[]|fun(absolute_path: string): boolean +---@field custom? string[]|(fun(absolute_path: string): boolean) --- ---(default: `{}`) ---@field exclude? string[] diff --git a/lua/nvim-tree/_meta/config/git.lua b/lua/nvim-tree/_meta/config/git.lua index cda11b7656b..4251b211f91 100644 --- a/lua/nvim-tree/_meta/config/git.lua +++ b/lua/nvim-tree/_meta/config/git.lua @@ -24,7 +24,7 @@ error("Cannot require a meta file") --- ---Disable for top level paths. ---(default: `{}`) ----@field disable_for_dirs? string[]|fun(path: string): boolean +---@field disable_for_dirs? string[]|(fun(path: string): boolean) --- ---`git` processes timeout milliseconds. ---(default: `400`) diff --git a/lua/nvim-tree/_meta/config/sort.lua b/lua/nvim-tree/_meta/config/sort.lua index 5996453d38a..2a0e0f7bc86 100644 --- a/lua/nvim-tree/_meta/config/sort.lua +++ b/lua/nvim-tree/_meta/config/sort.lua @@ -30,7 +30,7 @@ error("Cannot require a meta file") ---@class nvim_tree.Config.Sort --- ---(default: `name`) ----@field sorter? nvim_tree.Config.Sort.Sorter|fun(nodes: nvim_tree.api.Node[]): nvim_tree.Config.Sort.Sorter? +---@field sorter? nvim_tree.Config.Sort.Sorter|(fun(nodes: nvim_tree.api.Node[]): nvim_tree.Config.Sort.Sorter?) --- ---Sort folders before files. Has no effect when {sorter} is a function. ---(default: `true`) diff --git a/lua/nvim-tree/_meta/config/update_focused_file.lua b/lua/nvim-tree/_meta/config/update_focused_file.lua index f08a987df1b..33a26b7d840 100644 --- a/lua/nvim-tree/_meta/config/update_focused_file.lua +++ b/lua/nvim-tree/_meta/config/update_focused_file.lua @@ -13,7 +13,7 @@ error("Cannot require a meta file") --- ---A function called on [BufEnter] that returns true if the file should not be focused when opening. ---(default: `false`) ----@field exclude? boolean|fun(args: vim.api.keyset.create_autocmd.callback_args): boolean +---@field exclude? boolean|(fun(args: vim.api.keyset.create_autocmd.callback_args): boolean) ---Update the root directory of the tree if the file is not under the current root directory. diff --git a/lua/nvim-tree/_meta/config/view.lua b/lua/nvim-tree/_meta/config/view.lua index 291ee708315..0693a669e1c 100644 --- a/lua/nvim-tree/_meta/config/view.lua +++ b/lua/nvim-tree/_meta/config/view.lua @@ -1,7 +1,7 @@ ---@meta error("Cannot require a meta file") ----@alias nvim_tree.Config.View.WidthSpec string|integer|fun(): integer|string +---@alias nvim_tree.Config.View.WidthSpec string|integer|(fun(): integer|string) ---Configures the dimensions and appearance of the nvim-tree window. --- @@ -101,4 +101,4 @@ error("Cannot require a meta file") ---@field quit_on_focus_loss? boolean --- ---(default: above) ----@field open_win_config? vim.api.keyset.win_config|fun(): vim.api.keyset.win_config +---@field open_win_config? vim.api.keyset.win_config|(fun(): vim.api.keyset.win_config) From 3895114ac114de320a2d3e60ff01ad625a9fb0f6 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Mon, 12 Jan 2026 11:55:18 +1100 Subject: [PATCH 041/170] docs(#2934): tidy Config.Renderer --- doc/nvim-tree-lua.txt | 122 ++++++++++++++------------------- lua/nvim-tree/_meta/api.lua | 14 ++-- lua/nvim-tree/_meta/config.lua | 105 ++++++++++++++++++---------- 3 files changed, 126 insertions(+), 115 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index f2d428649f7..2bb1b428fed 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3548,12 +3548,19 @@ Class: Config *nvim-tree-config* |nvim_tree.Config.Log| *nvim_tree.Config.Renderer* - TODO overview + Appearance of the tree. + + {highlight_} options *nvim_tree.Config.Renderer.HighlightPlacement* + • `none`: no highlighting + • `icon`: icon only + • `name`: name only + • `all`: icon and name {root_folder_label} has 3 forms: • `string`: |filename-modifiers| format string • `boolean`: `true` to disable - • `fun(root_cwd: string): string`: string from root absolute path e.g. >lua + • `fun(root_cwd: string): string`: return a literal string from root's + absolute path e.g. >lua my_root_folder_label = function(path) return ".../" .. vim.fn.fnamemodify(path, ":t") end @@ -3578,16 +3585,13 @@ Class: Config *nvim-tree-config* folder into one node. Function variant takes the relative path of grouped folders and returns a string to be displayed. - • {full_name}? (`boolean`, default: `false`) Display node + • {full_name}? (`boolean`, default: `false`) Display nodes whose name length is wider than the width of nvim-tree window in floating window. • {root_folder_label}? (`string|boolean|(fun(root_cwd: string): string)`) (default: `":~:s?$?/..?"`) • {indent_width}? (`integer`, default: `2`) Number of spaces - for an each tree nesting level. Minimum 1. - • {special_files}? (`string[]`, default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }`) - A list of filenames that gets highlighted - with `NvimTreeSpecialFile`. + for each tree nesting level. Minimum 1. • {hidden_display}? (`nvim_tree.Config.Renderer.HiddenDisplay`) (default: `none`) • {symlink_destination}? (`boolean`, default: `true`) Appends an @@ -3596,55 +3600,35 @@ Class: Config *nvim-tree-config* • {decorators}? (`(string|nvim_tree.api.decorator.UserDecorator)[]`, default: `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) Highlighting and icons for the nodes, in increasing order of precedence. Strings - specify builtin decorators. - • {highlight_git}? (`nvim_tree.HighlightOption`) Enable - highlight for git attributes using - `NvimTreeGit*HL` highlight groups. Requires - |nvim-tree.git.enable| Value can be - `"none"`, `"icon"`, `"name"` or `"all"`. - Default: `"none"` @see nvim-tree.git.enable - • {highlight_diagnostics}? (`nvim_tree.HighlightOption`) Enable - highlight for diagnostics using - `NvimTreeDiagnostic*HL` highlight groups. - Requires |nvim-tree.diagnostics.enable| - Value can be `"none"`, `"icon"`, `"name"` - or `"all"`. Default: `"none"` @see - nvim-tree.diagnostics.enable - • {highlight_opened_files}? (`nvim_tree.HighlightOption`) Highlight - icons and/or names for |bufloaded()| files - using the `NvimTreeOpenedHL` highlight - group. See - |nvim-tree-api.navigate.opened.next()| and - |nvim-tree-api.navigate.opened.prev()| - Value can be `"none"`, `"icon"`, `"name"` - or `"all"`. Default: `"none"` - • {highlight_modified}? (`nvim_tree.HighlightOption`) Highlight - icons and/or names for modified files using - the `NvimTreeModifiedFile` highlight group. - Requires |nvim-tree.modified.enable| Value - can be `"none"`, `"icon"`, `"name"` or - `"all"` Default `"none"` @see - nvim-tree.modified.enable - • {highlight_hidden}? (`nvim_tree.HighlightOption`) Highlight - icons and/or names for hidden files - (dotfiles) using the `NvimTreeHiddenFileHL` - highlight group. Value can be `"none"`, - `"icon"`, `"name"` or `"all"` Default - `"none"` - • {highlight_bookmarks}? (`nvim_tree.HighlightOption`) Highlight - bookmarked using the `NvimTreeBookmarkHL` - group. Value can be `"none"`, `"icon"`, - `"name"` or `"all"` Default `"none"` - • {highlight_clipboard}? (`nvim_tree.HighlightOption`) Enable - highlight for clipboard items using the - `NvimTreeCutHL` and `NvimTreeCopiedHL` - groups. Value can be `"none"`, `"icon"`, - `"name"` or `"all"`. Default: `"name"` + specify builtin decorators. See + |nvim-tree-decorators|, + |nvim-tree-api.decorator| + • {highlight_git}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) + Git status: `NvimTreeGit*HL`. Requires + |nvim_tree.Config.Git| {enable}. + • {highlight_opened_files}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) + |bufloaded()| files: `NvimTreeOpenedHL`. + • {highlight_hidden}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) + Hidden (dotfiles): `NvimTreeHiddenFileHL`. + • {highlight_modified}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) + Modified files: `NvimTreeModifiedFile`. + Requires |nvim_tree.Config.Modified| + {enable}. + • {highlight_bookmarks}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) + Bookmarked: `NvimTreeBookmarkHL`. + • {highlight_diagnostics}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) + Diagnostic status: `NvimTreeDiagnostic*HL`. + Requires |nvim_tree.Config.Diagnostics| + {enable}. + • {highlight_clipboard}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `name`) + Copied: `NvimTreeCopiedHL`, cut: + `NvimTreeCutHL`. + • {special_files}? (`string[]`, default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }`) + Sepcial files: `NvimTreeSpecialFile`. • {indent_markers}? (`nvim_tree.Config.Renderer.IndentMarkers`) - Configuration options for tree indent - markers. + |nvim_tree.Config.Renderer.IndentMarkers| • {icons}? (`nvim_tree.Config.Renderer.Icons`) - Configuration options for icons. + |nvim_tree.Config.Renderer.Icons| *nvim_tree.Config.Renderer.Icons* @@ -3787,24 +3771,18 @@ Class: Config *nvim-tree-config* *nvim_tree.Config.Renderer.IndentMarkers* Fields: ~ - • {enable}? (`boolean`) Display indent markers when folders are - open Default: `false` - • {inline_arrows}? (`boolean`) Display folder arrows in the same column - as indent marker when using - |renderer.icons.show.folder_arrow| Default: `true` - • {icons}? (`nvim_tree.Config.Renderer.IndentMarkers.Icons`) - Icons shown before the file/directory. Length 1. - Default: > lua { corner = "└", edge = "│", item - = "│", bottom = "─", none = " ", } - -*nvim_tree.Config.Renderer.IndentMarkers.Icons* - - Fields: ~ - • {corner}? (`string`) Default: `"└"` - • {edge}? (`string`) Default: `"│"` - • {item}? (`string`) Default: `"│"` - • {bottom}? (`string`) Default: `"─"` - • {none}? (`string`) Default: `" "` + • {enable}? (`boolean`, default: `false`) Display indent markers + when folders are open. + • {inline_arrows}? (`boolean`, default: `true`) Display folder arrows + in the same column as indent marker when using + |nvim_tree.Config.Renderer.Icons.Padding| + {folder_arrow} + • {icons}? (`table`) Before the file/directory, length 1. + • {corner}? (`string`) (default: `└` ) + • {edge}? (`string`) (default: `│` ) + • {item}? (`string`) (default: `│` ) + • {bottom}? (`string`) (default: `─` ) + • {none}? (`string`) (default: ` ` ) diff --git a/lua/nvim-tree/_meta/api.lua b/lua/nvim-tree/_meta/api.lua index fabd8e0c943..39643a11d58 100644 --- a/lua/nvim-tree/_meta/api.lua +++ b/lua/nvim-tree/_meta/api.lua @@ -10,19 +10,19 @@ error("Cannot require a meta file") ---@field current_window? boolean open the tree in the current window ---@field winid? number open the tree in the specified winid, overrides current_window ---@field find_file? boolean find the current buffer ----@field update_root? boolean requires find_file, see |nvim-tree.update_focused_file.update_root| +---@field update_root? boolean requires find_file, see [nvim-tree.update_focused_file.update_root] ---@field focus? boolean focus the tree when opening, default true ---@class (exact) nvim_tree.api.TreeToggleOpts ---@field path? string root directory for the tree ---@field current_window? boolean open the tree in the current window ----@field winid? number open the tree in the specified |winid|, overrides current_window +---@field winid? number open the tree in the specified [winid], overrides current_window ---@field find_file? boolean find the current buffer ----@field update_root? boolean requires find_file, see |nvim-tree.update_focused_file.update_root| +---@field update_root? boolean requires find_file, see [nvim-tree.update_focused_file.update_root] ---@field focus? boolean focus the tree when opening, default true ---@class (exact) nvim_tree.api.TreeResizeOpts ----@field width? string|function|number|table new |nvim-tree.view.width| value +---@field width? string|function|number|table new [nvim-tree.view.width] value ---@field absolute? number set the width ---@field relative? number relative width adjustment @@ -30,8 +30,8 @@ error("Cannot require a meta file") ---@field buf? string|number absolute/relative path OR bufnr to find ---@field open? boolean open the tree if necessary ---@field current_window? boolean requires open, open in the current window ----@field winid? number open the tree in the specified |winid|, overrides current_window ----@field update_root? boolean see |nvim-tree.update_focused_file.update_root| +---@field winid? number open the tree in the specified [winid], overrides current_window +---@field update_root? boolean see [nvim-tree.update_focused_file.update_root] ---@field focus? boolean focus the tree ---@class (exact) nvim_tree.api.CollapseOpts @@ -41,7 +41,7 @@ error("Cannot require a meta file") ---@field expand_until? (fun(expansion_count: integer, node: Node): boolean) Return true if node should be expanded. expansion_count is the total number of folders expanded. ---@class (exact) nvim_tree.api.TreeIsVisibleOpts ----@field tabpage? number as per |nvim_get_current_tabpage()| +---@field tabpage? number as per [nvim_get_current_tabpage()] ---@field any_tabpage? boolean visible on any tab, default false ---@class (exact) nvim_tree.api.TreeWinIdOpts diff --git a/lua/nvim-tree/_meta/config.lua b/lua/nvim-tree/_meta/config.lua index c4132d0292b..bbbeb073289 100644 --- a/lua/nvim-tree/_meta/config.lua +++ b/lua/nvim-tree/_meta/config.lua @@ -3,7 +3,6 @@ error("Cannot require a meta file") --- TODO #2934 these were not correctly generated, inline or fix ---@alias nvim_tree.PlacementOption "before"|"after"|"signcolumn"|"right_align" ----@alias nvim_tree.HighlightOption "none"|"icon"|"name"|"all" --- TODO #2934 brief and some links --- @@ -117,13 +116,20 @@ error("Cannot require a meta file") ---@alias nvim_tree.Config.Renderer.HiddenDisplay "none"|"simple"|"all"|(fun(hidden_stats: table): string) +---@alias nvim_tree.Config.Renderer.HighlightPlacement "none"|"icon"|"name"|"all" ----TODO overview +---Appearance of the tree. +--- +---{highlight_} options [nvim_tree.Config.Renderer.HighlightPlacement]() +---- `none`: no highlighting +---- `icon`: icon only +---- `name`: name only +---- `all`: icon and name --- ---{root_folder_label} has 3 forms: ---- `string`: [filename-modifiers] format string ---- `boolean`: `true` to disable ----- `fun(root_cwd: string): string`: string from root absolute path e.g. +---- `fun(root_cwd: string): string`: return a literal string from root's absolute path e.g. ---```lua ---my_root_folder_label = function(path) --- return ".../" .. vim.fn.fnamemodify(path, ":t") @@ -148,21 +154,17 @@ error("Cannot require a meta file") ---(default: `false`) ---@field group_empty? boolean|(fun(relative_path: string): string) --- ----Display node whose name length is wider than the width of nvim-tree window in floating window. +---Display nodes whose name length is wider than the width of nvim-tree window in floating window. ---(default: `false`) ---@field full_name? boolean --- ---(default: `":~:s?$?/..?"`) ---@field root_folder_label? string|boolean|(fun(root_cwd: string): string) --- ----Number of spaces for an each tree nesting level. Minimum 1. +---Number of spaces for each tree nesting level. Minimum 1. ---(default: `2`) ---@field indent_width? integer --- ----A list of filenames that gets highlighted with `NvimTreeSpecialFile`. ----(default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }`) ----@field special_files? string[] ---- ---(default: `none`) ---@field hidden_display? nvim_tree.Config.Renderer.HiddenDisplay --- @@ -170,49 +172,80 @@ error("Cannot require a meta file") ---(default: `true`) ---@field symlink_destination? boolean --- ----Highlighting and icons for the nodes, in increasing order of precedence. Strings specify builtin decorators. +---Highlighting and icons for the nodes, in increasing order of precedence. Strings specify builtin decorators. See [nvim-tree-decorators], [nvim-tree-api.decorator] ---(default: `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) ---@field decorators? (string|nvim_tree.api.decorator.UserDecorator)[] --- ----@field highlight_git? nvim_tree.HighlightOption Enable highlight for git attributes using `NvimTreeGit*HL` highlight groups. Requires |nvim-tree.git.enable| Value can be `"none"`, `"icon"`, `"name"` or `"all"`. Default: `"none"` @see nvim-tree.git.enable ---- ---- ----@field highlight_diagnostics? nvim_tree.HighlightOption Enable highlight for diagnostics using `NvimTreeDiagnostic*HL` highlight groups. Requires |nvim-tree.diagnostics.enable| Value can be `"none"`, `"icon"`, `"name"` or `"all"`. Default: `"none"` @see nvim-tree.diagnostics.enable ---- +---Git status: `NvimTreeGit*HL`. +---Requires [nvim_tree.Config.Git] {enable}. +---(default: `none`) +---@field highlight_git? nvim_tree.Config.Renderer.HighlightPlacement --- ----@field highlight_opened_files? nvim_tree.HighlightOption Highlight icons and/or names for |bufloaded()| files using the `NvimTreeOpenedHL` highlight group. See |nvim-tree-api.navigate.opened.next()| and |nvim-tree-api.navigate.opened.prev()| Value can be `"none"`, `"icon"`, `"name"` or `"all"`. Default: `"none"` +---[bufloaded()] files: `NvimTreeOpenedHL`. +---(default: `none`) +---@field highlight_opened_files? nvim_tree.Config.Renderer.HighlightPlacement --- +---Hidden (dotfiles): `NvimTreeHiddenFileHL`. +---(default: `none`) +---@field highlight_hidden? nvim_tree.Config.Renderer.HighlightPlacement --- ----@field highlight_modified? nvim_tree.HighlightOption Highlight icons and/or names for modified files using the `NvimTreeModifiedFile` highlight group. Requires |nvim-tree.modified.enable| Value can be `"none"`, `"icon"`, `"name"` or `"all"` Default `"none"` @see nvim-tree.modified.enable +---Modified files: `NvimTreeModifiedFile`. +---Requires [nvim_tree.Config.Modified] {enable}. +---(default: `none`) +---@field highlight_modified? nvim_tree.Config.Renderer.HighlightPlacement --- +---Bookmarked: `NvimTreeBookmarkHL`. +---(default: `none`) +---@field highlight_bookmarks? nvim_tree.Config.Renderer.HighlightPlacement --- ----@field highlight_hidden? nvim_tree.HighlightOption Highlight icons and/or names for hidden files (dotfiles) using the `NvimTreeHiddenFileHL` highlight group. Value can be `"none"`, `"icon"`, `"name"` or `"all"` Default `"none"` +---Diagnostic status: `NvimTreeDiagnostic*HL`. +---Requires [nvim_tree.Config.Diagnostics] {enable}. +---(default: `none`) +---@field highlight_diagnostics? nvim_tree.Config.Renderer.HighlightPlacement --- +---Copied: `NvimTreeCopiedHL`, cut: `NvimTreeCutHL`. +---(default: `name`) +---@field highlight_clipboard? nvim_tree.Config.Renderer.HighlightPlacement --- ----@field highlight_bookmarks? nvim_tree.HighlightOption Highlight bookmarked using the `NvimTreeBookmarkHL` group. Value can be `"none"`, `"icon"`, `"name"` or `"all"` Default `"none"` +---Sepcial files: `NvimTreeSpecialFile`. +---(default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }`) +---@field special_files? string[] --- +---[nvim_tree.Config.Renderer.IndentMarkers] +---@field indent_markers? nvim_tree.Config.Renderer.IndentMarkers --- ----@field highlight_clipboard? nvim_tree.HighlightOption Enable highlight for clipboard items using the `NvimTreeCutHL` and `NvimTreeCopiedHL` groups. Value can be `"none"`, `"icon"`, `"name"` or `"all"`. Default: `"name"` +---[nvim_tree.Config.Renderer.Icons] +---@field icons? nvim_tree.Config.Renderer.Icons + + +---@class nvim_tree.Config.Renderer.IndentMarkers --- +---Display indent markers when folders are open. +---(default: `false`) +---@field enable? boolean --- ----@field indent_markers? nvim_tree.Config.Renderer.IndentMarkers Configuration options for tree indent markers. +---Display folder arrows in the same column as indent marker when using [nvim_tree.Config.Renderer.Icons.Padding] {folder_arrow} +---(default: `true`) +---@field inline_arrows? boolean --- --- ----@field icons? nvim_tree.Config.Renderer.Icons Configuration options for icons. - - ----@class nvim_tree.Config.Renderer.IndentMarkers ----@field enable? boolean Display indent markers when folders are open Default: `false` ----@field inline_arrows? boolean Display folder arrows in the same column as indent marker when using |renderer.icons.show.folder_arrow| Default: `true` ----@field icons? nvim_tree.Config.Renderer.IndentMarkers.Icons Icons shown before the file/directory. Length 1. Default: > lua { corner = "└", edge = "│", item = "│", bottom = "─", none = " ", } +---@field icons? nvim_tree.Config.Renderer.IndentMarkers.Icons +---Before the file/directory, length 1. ---@class nvim_tree.Config.Renderer.IndentMarkers.Icons ----@field corner? string Default: `"└"` ----@field edge? string Default: `"│"` ----@field item? string Default: `"│"` ----@field bottom? string Default: `"─"` ----@field none? string Default: `" "` +---@inlinedoc +--- +---(default: `└` ) +---@field corner? string +---(default: `│` ) +---@field edge? string +---(default: `│` ) +---@field item? string +---(default: `─` ) +---@field bottom? string +---(default: ` ` ) +---@field none? string ---@class nvim_tree.Config.Renderer.Icons Configuration options for icons. @@ -275,12 +308,12 @@ error("Cannot require a meta file") --- ---Icons: [nvim_tree.Config.Renderer.Icons.Glyphs.Git]. ---Location: [nvim_tree.Config.Renderer.Icons] {git_placement}. ----Requires |nvim_tree.Config.Git| {enable}. +---Requires [nvim_tree.Config.Git] {enable}. ---(default: `true`) ---@field git? boolean --- ---Location: [nvim_tree.Config.Renderer.Icons] {modified_placement}. ----Requires |nvim_tree.Config.Modified| {enable}. +---Requires [nvim_tree.Config.Modified] {enable}. ---(default: `true`) ---@field modified? boolean --- @@ -290,7 +323,7 @@ error("Cannot require a meta file") --- ---Icons: [nvim_tree.Config.Diagnostics.Icons] ---Location: [nvim_tree.Config.Renderer.Icons] {diagnostics_placement}. ----Requires |nvim_tree.Config.Diagnostics| {enable}. +---Requires [nvim_tree.Config.Diagnostics] {enable}. ---(default: `true`) ---@field diagnostics? boolean --- From 53db2d0a1243bdf8a5fabe22fdb361066af2aa49 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Mon, 12 Jan 2026 11:59:28 +1100 Subject: [PATCH 042/170] docs(#2934): tidy Config.Renderer, move into place --- doc/nvim-tree-lua.txt | 255 +++++++++++---------- lua/nvim-tree/_meta/config.lua | 288 +----------------------- lua/nvim-tree/_meta/config/renderer.lua | 285 ++++++++++++++++++++++- 3 files changed, 415 insertions(+), 413 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 2bb1b428fed..b24279b526a 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3462,7 +3462,7 @@ highlight group is not, hard linking as follows: > Class: Config *nvim-tree-config* *nvim_tree.Config* - TODO #2934 brief and some links + TODO #2934 brief, some links to setup etc., lsp hint Fields: ~ • {on_attach}? (`string|(fun(bufnr: integer))`) Runs when @@ -3547,6 +3547,135 @@ Class: Config *nvim-tree-config* • {log}? (`nvim_tree.Config.Log`) |nvim_tree.Config.Log| + + +============================================================================== +Class: Config.Sort *nvim-tree-config-sort* + +*nvim_tree.Config.Sort* + Sort files within a directory. + + {sorter} *nvim_tree.Config.Sort.Sorter* + • `name` + • `case_sensitive` name + • `modification_time` + • `extension` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz` + • `suffix` uses the last e.g. `foo.tar.gz` -> `.gz` + • `filetype` |filetype| + + {sorter} may be a function that is passed a list of |nvim_tree.api.Node| + to be sorted in place e.g. >lua + + ---Sort by name length + ---@param nodes nvim_tree.api.Node[] + ---@return nvim_tree.Config.Sort.Sorter? + local sorter = function(nodes) + table.sort(nodes, function(a, b) + return #a.name < #b.name + end) + end +< + + {sorter} may be a function that returns a |nvim_tree.Config.Sort.Sorter| + + Fields: ~ + • {sorter}? (`nvim_tree.Config.Sort.Sorter|(fun(nodes: nvim_tree.api.Node[]): nvim_tree.Config.Sort.Sorter?)`) + (default: `name`) + • {folders_first}? (`boolean`, default: `true`) Sort folders before + files. Has no effect when {sorter} is a function. + • {files_first}? (`boolean`, default: `false`) Sort files before + folders. Has no effect when {sorter} is a function. + Overrides {folders_first}. + + + +============================================================================== +Class: Config.View *nvim-tree-config-view* + +*nvim_tree.Config.View* + Configures the dimensions and appearance of the nvim-tree window. + + The window is "docked" at the left by default, however may be configured + to float: |nvim_tree.Config.View.Float| + + {width} can be a |nvim_tree.Config.View.WidthSpec| for simple static + control or a |nvim_tree.Config.View.Width| for fully dynamic control based + on longest line. + + *nvim_tree.Config.View.WidthSpec* + • string: `x%` string e.g. `30%` + • integer: number of columns + • function: returns one of the above + + Fields: ~ + • {centralize_selection}? (`boolean`, default: `false`) When + entering nvim-tree, reposition the + view so that the current node is + initially centralized, see |zz|. + • {cursorline}? (`boolean`, default: `true`) + |cursorline| + • {cursorlineopt}? (`string`, default: `both`) + |cursorlineopt| + • {debounce_delay}? (`integer`, default: `15`) Idle + milliseconds before some reload / + refresh operations. Increase if you + experience performance issues around + screen refresh. + • {side}? (`"left"|"right"`) (default: `left`) + • {preserve_window_proportions}? (`boolean`, default: `false`) + Preserves window proportions when + opening a file. If `false`, the height + and width of windows other than + nvim-tree will be equalized. + • {number}? (`boolean`, default: `false`) |number| + • {relativenumber}? (`boolean`, default: `false`) + |relativenumber| + • {signcolumn}? (`"yes"|"auto"|"no"`, default: `yes`) + |signcolumn| + • {width}? (`nvim_tree.Config.View.WidthSpec|nvim_tree.Config.View.Width`) + (default: `30`) + • {float}? (`nvim_tree.Config.View.Float`) + |nvim_tree.Config.View.Float| + +*nvim_tree.Config.View.Float* + Configure floating window behaviour + + |vim.api.keyset.win_config| {open_win_config} is passed directly to + |nvim_open_win|, default: >lua + { + relative = "editor", + border = "rounded", + width = 30, + height = 30, + row = 1, + col = 1, + } +< + + Fields: ~ + • {enable}? (`boolean`) (default: `false`) + • {quit_on_focus_loss}? (`boolean`, default: `true`) Close the floating + window when it loses focus. + • {open_win_config}? (`vim.api.keyset.win_config|(fun(): vim.api.keyset.win_config)`) + (default: above) + +*nvim_tree.Config.View.Width* + Configure dynamic width based on longest line. + + Fields: ~ + • {min}? (`nvim_tree.Config.View.WidthSpec`) (default: `30`) + • {max}? (`nvim_tree.Config.View.WidthSpec`, default: `-1`) + -1 for unbounded. + • {lines_excluded}? (`("root")[]`, default: `{ "root" }`) Exclude these + lines when computing width. + • {padding}? (`nvim_tree.Config.View.WidthSpec`, default: `1`) + Extra padding to the right. + + + +============================================================================== +Class: Config.Renderer *nvim-tree-config-renderer* + *nvim_tree.Config.Renderer* Appearance of the tree. @@ -3786,130 +3915,6 @@ Class: Config *nvim-tree-config* -============================================================================== -Class: Config.Sort *nvim-tree-config-sort* - -*nvim_tree.Config.Sort* - Sort files within a directory. - - {sorter} *nvim_tree.Config.Sort.Sorter* - • `name` - • `case_sensitive` name - • `modification_time` - • `extension` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz` - • `suffix` uses the last e.g. `foo.tar.gz` -> `.gz` - • `filetype` |filetype| - - {sorter} may be a function that is passed a list of |nvim_tree.api.Node| - to be sorted in place e.g. >lua - - ---Sort by name length - ---@param nodes nvim_tree.api.Node[] - ---@return nvim_tree.Config.Sort.Sorter? - local sorter = function(nodes) - table.sort(nodes, function(a, b) - return #a.name < #b.name - end) - end -< - - {sorter} may be a function that returns a |nvim_tree.Config.Sort.Sorter| - - Fields: ~ - • {sorter}? (`nvim_tree.Config.Sort.Sorter|(fun(nodes: nvim_tree.api.Node[]): nvim_tree.Config.Sort.Sorter?)`) - (default: `name`) - • {folders_first}? (`boolean`, default: `true`) Sort folders before - files. Has no effect when {sorter} is a function. - • {files_first}? (`boolean`, default: `false`) Sort files before - folders. Has no effect when {sorter} is a function. - Overrides {folders_first}. - - - -============================================================================== -Class: Config.View *nvim-tree-config-view* - -*nvim_tree.Config.View* - Configures the dimensions and appearance of the nvim-tree window. - - The window is "docked" at the left by default, however may be configured - to float: |nvim_tree.Config.View.Float| - - {width} can be a |nvim_tree.Config.View.WidthSpec| for simple static - control or a |nvim_tree.Config.View.Width| for fully dynamic control based - on longest line. - - *nvim_tree.Config.View.WidthSpec* - • string: `x%` string e.g. `30%` - • integer: number of columns - • function: returns one of the above - - Fields: ~ - • {centralize_selection}? (`boolean`, default: `false`) When - entering nvim-tree, reposition the - view so that the current node is - initially centralized, see |zz|. - • {cursorline}? (`boolean`, default: `true`) - |cursorline| - • {cursorlineopt}? (`string`, default: `both`) - |cursorlineopt| - • {debounce_delay}? (`integer`, default: `15`) Idle - milliseconds before some reload / - refresh operations. Increase if you - experience performance issues around - screen refresh. - • {side}? (`"left"|"right"`) (default: `left`) - • {preserve_window_proportions}? (`boolean`, default: `false`) - Preserves window proportions when - opening a file. If `false`, the height - and width of windows other than - nvim-tree will be equalized. - • {number}? (`boolean`, default: `false`) |number| - • {relativenumber}? (`boolean`, default: `false`) - |relativenumber| - • {signcolumn}? (`"yes"|"auto"|"no"`, default: `yes`) - |signcolumn| - • {width}? (`nvim_tree.Config.View.WidthSpec|nvim_tree.Config.View.Width`) - (default: `30`) - • {float}? (`nvim_tree.Config.View.Float`) - |nvim_tree.Config.View.Float| - -*nvim_tree.Config.View.Float* - Configure floating window behaviour - - |vim.api.keyset.win_config| {open_win_config} is passed directly to - |nvim_open_win|, default: >lua - { - relative = "editor", - border = "rounded", - width = 30, - height = 30, - row = 1, - col = 1, - } -< - - Fields: ~ - • {enable}? (`boolean`) (default: `false`) - • {quit_on_focus_loss}? (`boolean`, default: `true`) Close the floating - window when it loses focus. - • {open_win_config}? (`vim.api.keyset.win_config|(fun(): vim.api.keyset.win_config)`) - (default: above) - -*nvim_tree.Config.View.Width* - Configure dynamic width based on longest line. - - Fields: ~ - • {min}? (`nvim_tree.Config.View.WidthSpec`) (default: `30`) - • {max}? (`nvim_tree.Config.View.WidthSpec`, default: `-1`) - -1 for unbounded. - • {lines_excluded}? (`("root")[]`, default: `{ "root" }`) Exclude these - lines when computing width. - • {padding}? (`nvim_tree.Config.View.WidthSpec`, default: `1`) - Extra padding to the right. - - - ============================================================================== Class: Config.HijackDirectories *nvim-tree-config-hijack-directories* diff --git a/lua/nvim-tree/_meta/config.lua b/lua/nvim-tree/_meta/config.lua index bbbeb073289..a5d7595cbc2 100644 --- a/lua/nvim-tree/_meta/config.lua +++ b/lua/nvim-tree/_meta/config.lua @@ -1,10 +1,7 @@ ---@meta error("Cannot require a meta file") ---- TODO #2934 these were not correctly generated, inline or fix ----@alias nvim_tree.PlacementOption "before"|"after"|"signcolumn"|"right_align" - ---- TODO #2934 brief and some links +--- TODO #2934 brief, some links to setup etc., lsp hint --- --- ---@class nvim_tree.Config @@ -113,286 +110,3 @@ error("Cannot require a meta file") --- ---[nvim_tree.Config.Log] ---@field log? nvim_tree.Config.Log - - ----@alias nvim_tree.Config.Renderer.HiddenDisplay "none"|"simple"|"all"|(fun(hidden_stats: table): string) ----@alias nvim_tree.Config.Renderer.HighlightPlacement "none"|"icon"|"name"|"all" - ----Appearance of the tree. ---- ----{highlight_} options [nvim_tree.Config.Renderer.HighlightPlacement]() ----- `none`: no highlighting ----- `icon`: icon only ----- `name`: name only ----- `all`: icon and name ---- ----{root_folder_label} has 3 forms: ----- `string`: [filename-modifiers] format string ----- `boolean`: `true` to disable ----- `fun(root_cwd: string): string`: return a literal string from root's absolute path e.g. ----```lua ----my_root_folder_label = function(path) ---- return ".../" .. vim.fn.fnamemodify(path, ":t") ----end ----``` ---- ----TODO: link to hidden display help section [nvim_tree.Config.Renderer.HiddenDisplay]() ---- ----{hidden_display} summary of hidden files below the tree. ----- `none`: disabled ----- `simple`: show how many hidden files are in a folder ----- `all`: show how many hidden and the number of hidden files by reason ----- `fun(hidden_stats: table): string`: returns a summary of hidden stats ---- ----@class nvim_tree.Config.Renderer ---- ----Appends a trailing slash to folder and symlink folder destination names. ----(default: `false`) ----@field add_trailing? boolean ---- ----Compact folders that only contain a single folder into one node. Function variant takes the relative path of grouped folders and returns a string to be displayed. ----(default: `false`) ----@field group_empty? boolean|(fun(relative_path: string): string) ---- ----Display nodes whose name length is wider than the width of nvim-tree window in floating window. ----(default: `false`) ----@field full_name? boolean ---- ----(default: `":~:s?$?/..?"`) ----@field root_folder_label? string|boolean|(fun(root_cwd: string): string) ---- ----Number of spaces for each tree nesting level. Minimum 1. ----(default: `2`) ----@field indent_width? integer ---- ----(default: `none`) ----@field hidden_display? nvim_tree.Config.Renderer.HiddenDisplay ---- ----Appends an arrow followed by the destination of the symlink. ----(default: `true`) ----@field symlink_destination? boolean ---- ----Highlighting and icons for the nodes, in increasing order of precedence. Strings specify builtin decorators. See [nvim-tree-decorators], [nvim-tree-api.decorator] ----(default: `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) ----@field decorators? (string|nvim_tree.api.decorator.UserDecorator)[] ---- ----Git status: `NvimTreeGit*HL`. ----Requires [nvim_tree.Config.Git] {enable}. ----(default: `none`) ----@field highlight_git? nvim_tree.Config.Renderer.HighlightPlacement ---- ----[bufloaded()] files: `NvimTreeOpenedHL`. ----(default: `none`) ----@field highlight_opened_files? nvim_tree.Config.Renderer.HighlightPlacement ---- ----Hidden (dotfiles): `NvimTreeHiddenFileHL`. ----(default: `none`) ----@field highlight_hidden? nvim_tree.Config.Renderer.HighlightPlacement ---- ----Modified files: `NvimTreeModifiedFile`. ----Requires [nvim_tree.Config.Modified] {enable}. ----(default: `none`) ----@field highlight_modified? nvim_tree.Config.Renderer.HighlightPlacement ---- ----Bookmarked: `NvimTreeBookmarkHL`. ----(default: `none`) ----@field highlight_bookmarks? nvim_tree.Config.Renderer.HighlightPlacement ---- ----Diagnostic status: `NvimTreeDiagnostic*HL`. ----Requires [nvim_tree.Config.Diagnostics] {enable}. ----(default: `none`) ----@field highlight_diagnostics? nvim_tree.Config.Renderer.HighlightPlacement ---- ----Copied: `NvimTreeCopiedHL`, cut: `NvimTreeCutHL`. ----(default: `name`) ----@field highlight_clipboard? nvim_tree.Config.Renderer.HighlightPlacement ---- ----Sepcial files: `NvimTreeSpecialFile`. ----(default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }`) ----@field special_files? string[] ---- ----[nvim_tree.Config.Renderer.IndentMarkers] ----@field indent_markers? nvim_tree.Config.Renderer.IndentMarkers ---- ----[nvim_tree.Config.Renderer.Icons] ----@field icons? nvim_tree.Config.Renderer.Icons - - ----@class nvim_tree.Config.Renderer.IndentMarkers ---- ----Display indent markers when folders are open. ----(default: `false`) ----@field enable? boolean ---- ----Display folder arrows in the same column as indent marker when using [nvim_tree.Config.Renderer.Icons.Padding] {folder_arrow} ----(default: `true`) ----@field inline_arrows? boolean ---- ---- ----@field icons? nvim_tree.Config.Renderer.IndentMarkers.Icons - - ----Before the file/directory, length 1. ----@class nvim_tree.Config.Renderer.IndentMarkers.Icons ----@inlinedoc ---- ----(default: `└` ) ----@field corner? string ----(default: `│` ) ----@field edge? string ----(default: `│` ) ----@field item? string ----(default: `─` ) ----@field bottom? string ----(default: ` ` ) ----@field none? string - - ----@class nvim_tree.Config.Renderer.Icons Configuration options for icons. ----@field web_devicons? nvim_tree.Config.Renderer.Icons.WebDevicons Configure optional plugin `"nvim-tree/nvim-web-devicons"` ----@field git_placement? nvim_tree.PlacementOption Git icons placement. Default: `"before"` ----@field diagnostics_placement? nvim_tree.PlacementOption Diganostic icon placement. Default: `"signcolumn"` @see nvim-tree.view.signcolumn @see nvim-tree.renderer.icons.show.diagnostics ----@field modified_placement? nvim_tree.PlacementOption Modified icon placement. Default: `"after"` ----@field hidden_placement? nvim_tree.PlacementOption Hidden icon placement. Default: `"after"` ----@field bookmarks_placement? nvim_tree.PlacementOption Bookmark icon placement. Default: `"signcolumn"` @see nvim-tree.renderer.icons.show.bookmarks ----@field padding? nvim_tree.Config.Renderer.Icons.Padding ----@field symlink_arrow? string Used as a separator between symlinks' source and target. Default: `" ➛ "` ----@field show? nvim_tree.Config.Renderer.Icons.Show Configuration options for showing icon types. Left to right order: file/folder, git, modified, hidden, diagnostics, bookmarked. ----@field glyphs? nvim_tree.Config.Renderer.Icons.Glyphs Configuration options for icon glyphs. NOTE: Do not set any glyphs to more than two characters if it's going to appear in the signcolumn. - - ----@class nvim_tree.Config.Renderer.Icons.WebDevicons ----@field file? nvim_tree.Config.Renderer.Icons.WebDevicons.File File icons. ----@field folder? nvim_tree.Config.Renderer.Icons.WebDevicons.Folder Folder icons. - - ----@class nvim_tree.Config.Renderer.Icons.WebDevicons.File ----@field enable? boolean Show icons on files. Overrides |nvim-tree.renderer.icons.glyphs.default| Default: `true` ----@field color? boolean Use icon colors for files. Overrides highlight groups. Default: `true` - - ----@class nvim_tree.Config.Renderer.Icons.WebDevicons.Folder ----@field enable? boolean Show icons on folders. Overrides |nvim-tree.renderer.icons.glyphs.folder| Default: `false` ----@field color? boolean Use icon colors for folders. Overrides highlight groups. Default: `true` - - ----@class nvim_tree.Config.Renderer.Icons.Padding ----@field icon? string Inserted between icon and filename. Default: `" "` ----@field folder_arrow? string Inserted between folder arrow icon and file/folder icon. Default: `" "` - - ----Control which icons are displayed. ---- ----Left to right ordered: ----- {file} ----- {folder} ----- {git} ----- {modified} ----- {hidden} ----- {diagnostics} ----- {bookmarks} ---- ----@class nvim_tree.Config.Renderer.Icons.Show ---- ----Before file name. ----(default: `true`) ----@field file? boolean ---- ----Before folder name. ----(default: `true`) ----@field folder? boolean ---- ----Show a small arrow before the folder node. Arrow will be a part of the node when using [nvim_tree.Config.Renderer] {indent_markers}. ----(default: `true`) ----@field folder_arrow? boolean ---- ----Icons: [nvim_tree.Config.Renderer.Icons.Glyphs.Git]. ----Location: [nvim_tree.Config.Renderer.Icons] {git_placement}. ----Requires [nvim_tree.Config.Git] {enable}. ----(default: `true`) ----@field git? boolean ---- ----Location: [nvim_tree.Config.Renderer.Icons] {modified_placement}. ----Requires [nvim_tree.Config.Modified] {enable}. ----(default: `true`) ----@field modified? boolean ---- ----Location: [nvim_tree.Config.Renderer.Icons] {hidden_placement}. ----(default: `false`) ----@field hidden? boolean ---- ----Icons: [nvim_tree.Config.Diagnostics.Icons] ----Location: [nvim_tree.Config.Renderer.Icons] {diagnostics_placement}. ----Requires [nvim_tree.Config.Diagnostics] {enable}. ----(default: `true`) ----@field diagnostics? boolean ---- ----Location: [nvim_tree.Config.Renderer.Icons] {bookmarks_placement}. ----(default: `true`) ----@field bookmarks? boolean - - ----Glyphs that appear in the sign column must have length <= 2 ---- ----Glyphs defined elsewhere: ----- [nvim_tree.Config.Diagnostics.Icons] ----- [nvim_tree.Config.Renderer.IndentMarkers.Icons] ----@class nvim_tree.Config.Renderer.Icons.Glyphs ---- ----Files, overridden by [nvim_tree.Config.Renderer.Icons] {web_devicons} ----(default: `` ) ----@field default? string ---- ----(default: `` ) ----@field symlink? string ---- ----(default: `󰆤` ) ----@field bookmark? string ---- ----(default: `●` ) ----@field modified? string ---- ----(default: `󰜌` ) ----@field hidden? string ---- ----Overridden by [nvim_tree.Config.Renderer.Icons] {web_devicons} ----@field folder? nvim_tree.Config.Renderer.Icons.Glyphs.Folder ---- ----Git status on files and directories. ----@field git? nvim_tree.Config.Renderer.Icons.Glyphs.Git - ----@class nvim_tree.Config.Renderer.Icons.Glyphs.Folder ----@inlinedoc ----(default: left arrow) ----@field arrow_closed? string ----(default: down arrow) ----@field arrow_open? string ----(default: `` ) ----@field default? string ----(default: `` ) ----@field open? string ----(default: `` ) ----@field empty? string ----(default: `` ) ----@field empty_open? string ----(default: `` ) ----@field symlink? string ----(default: `` ) ----@field symlink_open? string - ----@class nvim_tree.Config.Renderer.Icons.Glyphs.Git ----@inlinedoc ----(default: `✗` ) ----@field unstaged? string ----(default: `✓` ) ----@field staged? string ----(default: `` ) ----@field unmerged? string ----(default: `➜` ) ----@field renamed? string ----(default: `★` ) ----@field untracked? string ----(default: `` ) ----@field deleted? string ----(default: `◌` ) ----@field ignored? string diff --git a/lua/nvim-tree/_meta/config/renderer.lua b/lua/nvim-tree/_meta/config/renderer.lua index 4ab716dc93a..95a958be0e5 100644 --- a/lua/nvim-tree/_meta/config/renderer.lua +++ b/lua/nvim-tree/_meta/config/renderer.lua @@ -1,4 +1,287 @@ ---@meta error("Cannot require a meta file") ---- TODO #2934 +---@alias nvim_tree.Config.Renderer.HiddenDisplay "none"|"simple"|"all"|(fun(hidden_stats: table): string) +---@alias nvim_tree.Config.Renderer.HighlightPlacement "none"|"icon"|"name"|"all" + +--- TODO #2934 these were not correctly generated, inline or fix +---@alias nvim_tree.PlacementOption "before"|"after"|"signcolumn"|"right_align" + +---Appearance of the tree. +--- +---{highlight_} options [nvim_tree.Config.Renderer.HighlightPlacement]() +---- `none`: no highlighting +---- `icon`: icon only +---- `name`: name only +---- `all`: icon and name +--- +---{root_folder_label} has 3 forms: +---- `string`: [filename-modifiers] format string +---- `boolean`: `true` to disable +---- `fun(root_cwd: string): string`: return a literal string from root's absolute path e.g. +---```lua +---my_root_folder_label = function(path) +--- return ".../" .. vim.fn.fnamemodify(path, ":t") +---end +---``` +--- +---TODO: link to hidden display help section [nvim_tree.Config.Renderer.HiddenDisplay]() +--- +---{hidden_display} summary of hidden files below the tree. +---- `none`: disabled +---- `simple`: show how many hidden files are in a folder +---- `all`: show how many hidden and the number of hidden files by reason +---- `fun(hidden_stats: table): string`: returns a summary of hidden stats +--- +---@class nvim_tree.Config.Renderer +--- +---Appends a trailing slash to folder and symlink folder destination names. +---(default: `false`) +---@field add_trailing? boolean +--- +---Compact folders that only contain a single folder into one node. Function variant takes the relative path of grouped folders and returns a string to be displayed. +---(default: `false`) +---@field group_empty? boolean|(fun(relative_path: string): string) +--- +---Display nodes whose name length is wider than the width of nvim-tree window in floating window. +---(default: `false`) +---@field full_name? boolean +--- +---(default: `":~:s?$?/..?"`) +---@field root_folder_label? string|boolean|(fun(root_cwd: string): string) +--- +---Number of spaces for each tree nesting level. Minimum 1. +---(default: `2`) +---@field indent_width? integer +--- +---(default: `none`) +---@field hidden_display? nvim_tree.Config.Renderer.HiddenDisplay +--- +---Appends an arrow followed by the destination of the symlink. +---(default: `true`) +---@field symlink_destination? boolean +--- +---Highlighting and icons for the nodes, in increasing order of precedence. Strings specify builtin decorators. See [nvim-tree-decorators], [nvim-tree-api.decorator] +---(default: `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) +---@field decorators? (string|nvim_tree.api.decorator.UserDecorator)[] +--- +---Git status: `NvimTreeGit*HL`. +---Requires [nvim_tree.Config.Git] {enable}. +---(default: `none`) +---@field highlight_git? nvim_tree.Config.Renderer.HighlightPlacement +--- +---[bufloaded()] files: `NvimTreeOpenedHL`. +---(default: `none`) +---@field highlight_opened_files? nvim_tree.Config.Renderer.HighlightPlacement +--- +---Hidden (dotfiles): `NvimTreeHiddenFileHL`. +---(default: `none`) +---@field highlight_hidden? nvim_tree.Config.Renderer.HighlightPlacement +--- +---Modified files: `NvimTreeModifiedFile`. +---Requires [nvim_tree.Config.Modified] {enable}. +---(default: `none`) +---@field highlight_modified? nvim_tree.Config.Renderer.HighlightPlacement +--- +---Bookmarked: `NvimTreeBookmarkHL`. +---(default: `none`) +---@field highlight_bookmarks? nvim_tree.Config.Renderer.HighlightPlacement +--- +---Diagnostic status: `NvimTreeDiagnostic*HL`. +---Requires [nvim_tree.Config.Diagnostics] {enable}. +---(default: `none`) +---@field highlight_diagnostics? nvim_tree.Config.Renderer.HighlightPlacement +--- +---Copied: `NvimTreeCopiedHL`, cut: `NvimTreeCutHL`. +---(default: `name`) +---@field highlight_clipboard? nvim_tree.Config.Renderer.HighlightPlacement +--- +---Sepcial files: `NvimTreeSpecialFile`. +---(default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }`) +---@field special_files? string[] +--- +---[nvim_tree.Config.Renderer.IndentMarkers] +---@field indent_markers? nvim_tree.Config.Renderer.IndentMarkers +--- +---[nvim_tree.Config.Renderer.Icons] +---@field icons? nvim_tree.Config.Renderer.Icons + + +---@class nvim_tree.Config.Renderer.IndentMarkers +--- +---Display indent markers when folders are open. +---(default: `false`) +---@field enable? boolean +--- +---Display folder arrows in the same column as indent marker when using [nvim_tree.Config.Renderer.Icons.Padding] {folder_arrow} +---(default: `true`) +---@field inline_arrows? boolean +--- +--- +---@field icons? nvim_tree.Config.Renderer.IndentMarkers.Icons + + +---Before the file/directory, length 1. +---@class nvim_tree.Config.Renderer.IndentMarkers.Icons +---@inlinedoc +--- +---(default: `└` ) +---@field corner? string +---(default: `│` ) +---@field edge? string +---(default: `│` ) +---@field item? string +---(default: `─` ) +---@field bottom? string +---(default: ` ` ) +---@field none? string + + +---@class nvim_tree.Config.Renderer.Icons Configuration options for icons. +---@field web_devicons? nvim_tree.Config.Renderer.Icons.WebDevicons Configure optional plugin `"nvim-tree/nvim-web-devicons"` +---@field git_placement? nvim_tree.PlacementOption Git icons placement. Default: `"before"` +---@field diagnostics_placement? nvim_tree.PlacementOption Diganostic icon placement. Default: `"signcolumn"` @see nvim-tree.view.signcolumn @see nvim-tree.renderer.icons.show.diagnostics +---@field modified_placement? nvim_tree.PlacementOption Modified icon placement. Default: `"after"` +---@field hidden_placement? nvim_tree.PlacementOption Hidden icon placement. Default: `"after"` +---@field bookmarks_placement? nvim_tree.PlacementOption Bookmark icon placement. Default: `"signcolumn"` @see nvim-tree.renderer.icons.show.bookmarks +---@field padding? nvim_tree.Config.Renderer.Icons.Padding +---@field symlink_arrow? string Used as a separator between symlinks' source and target. Default: `" ➛ "` +---@field show? nvim_tree.Config.Renderer.Icons.Show Configuration options for showing icon types. Left to right order: file/folder, git, modified, hidden, diagnostics, bookmarked. +---@field glyphs? nvim_tree.Config.Renderer.Icons.Glyphs Configuration options for icon glyphs. NOTE: Do not set any glyphs to more than two characters if it's going to appear in the signcolumn. + + +---@class nvim_tree.Config.Renderer.Icons.WebDevicons +---@field file? nvim_tree.Config.Renderer.Icons.WebDevicons.File File icons. +---@field folder? nvim_tree.Config.Renderer.Icons.WebDevicons.Folder Folder icons. + + +---@class nvim_tree.Config.Renderer.Icons.WebDevicons.File +---@field enable? boolean Show icons on files. Overrides |nvim-tree.renderer.icons.glyphs.default| Default: `true` +---@field color? boolean Use icon colors for files. Overrides highlight groups. Default: `true` + + +---@class nvim_tree.Config.Renderer.Icons.WebDevicons.Folder +---@field enable? boolean Show icons on folders. Overrides |nvim-tree.renderer.icons.glyphs.folder| Default: `false` +---@field color? boolean Use icon colors for folders. Overrides highlight groups. Default: `true` + + +---@class nvim_tree.Config.Renderer.Icons.Padding +---@field icon? string Inserted between icon and filename. Default: `" "` +---@field folder_arrow? string Inserted between folder arrow icon and file/folder icon. Default: `" "` + + +---Control which icons are displayed. +--- +---Left to right ordered: +---- {file} +---- {folder} +---- {git} +---- {modified} +---- {hidden} +---- {diagnostics} +---- {bookmarks} +--- +---@class nvim_tree.Config.Renderer.Icons.Show +--- +---Before file name. +---(default: `true`) +---@field file? boolean +--- +---Before folder name. +---(default: `true`) +---@field folder? boolean +--- +---Show a small arrow before the folder node. Arrow will be a part of the node when using [nvim_tree.Config.Renderer] {indent_markers}. +---(default: `true`) +---@field folder_arrow? boolean +--- +---Icons: [nvim_tree.Config.Renderer.Icons.Glyphs.Git]. +---Location: [nvim_tree.Config.Renderer.Icons] {git_placement}. +---Requires [nvim_tree.Config.Git] {enable}. +---(default: `true`) +---@field git? boolean +--- +---Location: [nvim_tree.Config.Renderer.Icons] {modified_placement}. +---Requires [nvim_tree.Config.Modified] {enable}. +---(default: `true`) +---@field modified? boolean +--- +---Location: [nvim_tree.Config.Renderer.Icons] {hidden_placement}. +---(default: `false`) +---@field hidden? boolean +--- +---Icons: [nvim_tree.Config.Diagnostics.Icons] +---Location: [nvim_tree.Config.Renderer.Icons] {diagnostics_placement}. +---Requires [nvim_tree.Config.Diagnostics] {enable}. +---(default: `true`) +---@field diagnostics? boolean +--- +---Location: [nvim_tree.Config.Renderer.Icons] {bookmarks_placement}. +---(default: `true`) +---@field bookmarks? boolean + + +---Glyphs that appear in the sign column must have length <= 2 +--- +---Glyphs defined elsewhere: +---- [nvim_tree.Config.Diagnostics.Icons] +---- [nvim_tree.Config.Renderer.IndentMarkers.Icons] +---@class nvim_tree.Config.Renderer.Icons.Glyphs +--- +---Files, overridden by [nvim_tree.Config.Renderer.Icons] {web_devicons} +---(default: `` ) +---@field default? string +--- +---(default: `` ) +---@field symlink? string +--- +---(default: `󰆤` ) +---@field bookmark? string +--- +---(default: `●` ) +---@field modified? string +--- +---(default: `󰜌` ) +---@field hidden? string +--- +---Overridden by [nvim_tree.Config.Renderer.Icons] {web_devicons} +---@field folder? nvim_tree.Config.Renderer.Icons.Glyphs.Folder +--- +---Git status on files and directories. +---@field git? nvim_tree.Config.Renderer.Icons.Glyphs.Git + +---@class nvim_tree.Config.Renderer.Icons.Glyphs.Folder +---@inlinedoc +---(default: left arrow) +---@field arrow_closed? string +---(default: down arrow) +---@field arrow_open? string +---(default: `` ) +---@field default? string +---(default: `` ) +---@field open? string +---(default: `` ) +---@field empty? string +---(default: `` ) +---@field empty_open? string +---(default: `` ) +---@field symlink? string +---(default: `` ) +---@field symlink_open? string + +---@class nvim_tree.Config.Renderer.Icons.Glyphs.Git +---@inlinedoc +---(default: `✗` ) +---@field unstaged? string +---(default: `✓` ) +---@field staged? string +---(default: `` ) +---@field unmerged? string +---(default: `➜` ) +---@field renamed? string +---(default: `★` ) +---@field untracked? string +---(default: `` ) +---@field deleted? string +---(default: `◌` ) +---@field ignored? string From 795dde75cb99615f74a92f7e71d973668ec54d61 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Mon, 12 Jan 2026 13:04:16 +1100 Subject: [PATCH 043/170] docs(#2934): tidy Config.Renderer --- doc/nvim-tree-lua.txt | 107 ++++++++++------------ lua/nvim-tree/_meta/config/help.lua | 2 +- lua/nvim-tree/_meta/config/renderer.lua | 113 ++++++++++++++++++------ 3 files changed, 136 insertions(+), 86 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index b24279b526a..6d6962f7d1c 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3677,7 +3677,7 @@ Class: Config.View *nvim-tree-config-view* Class: Config.Renderer *nvim-tree-config-renderer* *nvim_tree.Config.Renderer* - Appearance of the tree. + Controls the appearance of the tree. {highlight_} options *nvim_tree.Config.Renderer.HighlightPlacement* • `none`: no highlighting @@ -3695,7 +3695,7 @@ Class: Config.Renderer *nvim-tree-config-renderer* end < - TODO: link to hidden display help section + TODO: link / move to hidden display help section *nvim_tree.Config.Renderer.HiddenDisplay* {hidden_display} summary of hidden files below the tree. @@ -3708,7 +3708,7 @@ Class: Config.Renderer *nvim-tree-config-renderer* Fields: ~ • {add_trailing}? (`boolean`, default: `false`) Appends a trailing slash to folder and symlink folder - destination names. + target names. • {group_empty}? (`boolean|(fun(relative_path: string): string)`, default: `false`) Compact folders that only contain a single folder into one node. Function variant @@ -3724,7 +3724,7 @@ Class: Config.Renderer *nvim-tree-config-renderer* • {hidden_display}? (`nvim_tree.Config.Renderer.HiddenDisplay`) (default: `none`) • {symlink_destination}? (`boolean`, default: `true`) Appends an - arrow followed by the destination of the + arrow followed by the target of the symlink. • {decorators}? (`(string|nvim_tree.api.decorator.UserDecorator)[]`, default: `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) Highlighting and icons for the nodes, in @@ -3760,38 +3760,42 @@ Class: Config.Renderer *nvim-tree-config-renderer* |nvim_tree.Config.Renderer.Icons| *nvim_tree.Config.Renderer.Icons* + Icons and separators. + + {_placement} options *nvim_tree.Config.Renderer.Icons.Placement* + • `before`: before file/folder, after the file/folders icons + • `after`: after file/folder + • `signcolumn`: far left, requires |nvim_tree.Config.View| {signcolumn}. + • `right_align`: far right Fields: ~ • {web_devicons}? (`nvim_tree.Config.Renderer.Icons.WebDevicons`) - Configure optional plugin - `"nvim-tree/nvim-web-devicons"` - • {git_placement}? (`nvim_tree.PlacementOption`) Git icons - placement. Default: `"before"` - • {diagnostics_placement}? (`nvim_tree.PlacementOption`) Diganostic - icon placement. Default: `"signcolumn"` @see - nvim-tree.view.signcolumn @see - nvim-tree.renderer.icons.show.diagnostics - • {modified_placement}? (`nvim_tree.PlacementOption`) Modified icon - placement. Default: `"after"` - • {hidden_placement}? (`nvim_tree.PlacementOption`) Hidden icon - placement. Default: `"after"` - • {bookmarks_placement}? (`nvim_tree.PlacementOption`) Bookmark icon - placement. Default: `"signcolumn"` @see - nvim-tree.renderer.icons.show.bookmarks - • {padding}? (`nvim_tree.Config.Renderer.Icons.Padding`) - • {symlink_arrow}? (`string`) Used as a separator between - symlinks' source and target. Default: - `" ➛ "` + |nvim_tree.Config.Renderer.Icons.WebDevicons| + Use optional plugin + `nvim-tree/nvim-web-devicons` + • {git_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`) + (default: `before`) + • {diagnostics_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`, default: `signcolumn`) + Requires |nvim_tree.Config.Diagnostics| + {enable}. + • {modified_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`, default: `after`) + Requires |nvim_tree.Config.Modified| + {enable}. + • {hidden_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`) + (default: `after`) + • {bookmarks_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`) + (default: `signcolumn`) + • {padding}? (`table`) Padding inserted between + • {icon}? (`string`, default: ` `) icon and + filename. + • {folder_arrow}? (`string`, default: ` `) + folder arrow icon and file/folder icon. + • {symlink_arrow}? (`string`, default: ` ➛ `) Separator + between symlink source and target. • {show}? (`nvim_tree.Config.Renderer.Icons.Show`) - Configuration options for showing icon - types. Left to right order: file/folder, - git, modified, hidden, diagnostics, - bookmarked. + |nvim_tree.Config.Renderer.Icons.Show| • {glyphs}? (`nvim_tree.Config.Renderer.Icons.Glyphs`) - Configuration options for icon glyphs. NOTE: - Do not set any glyphs to more than two - characters if it's going to appear in the - signcolumn. + |nvim_tree.Config.Renderer.Icons.Glyphs| *nvim_tree.Config.Renderer.Icons.Glyphs* Glyphs that appear in the sign column must have length <= 2 @@ -3826,14 +3830,6 @@ Class: Config.Renderer *nvim-tree-config-renderer* • {deleted}? (`string`) (default: `` ) • {ignored}? (`string`) (default: `◌` ) -*nvim_tree.Config.Renderer.Icons.Padding* - - Fields: ~ - • {icon}? (`string`) Inserted between icon and filename. - Default: `" "` - • {folder_arrow}? (`string`) Inserted between folder arrow icon and - file/folder icon. Default: `" "` - *nvim_tree.Config.Renderer.Icons.Show* Control which icons are displayed. @@ -3874,28 +3870,23 @@ Class: Config.Renderer *nvim-tree-config-renderer* {bookmarks_placement}. *nvim_tree.Config.Renderer.Icons.WebDevicons* + Configure optional plugin `nvim-tree/nvim-web-devicons`. - Fields: ~ - • {file}? (`nvim_tree.Config.Renderer.Icons.WebDevicons.File`) File - icons. - • {folder}? (`nvim_tree.Config.Renderer.Icons.WebDevicons.Folder`) - Folder icons. - -*nvim_tree.Config.Renderer.Icons.WebDevicons.File* - - Fields: ~ - • {enable}? (`boolean`) Show icons on files. Overrides - |nvim-tree.renderer.icons.glyphs.default| Default: `true` - • {color}? (`boolean`) Use icon colors for files. Overrides highlight - groups. Default: `true` - -*nvim_tree.Config.Renderer.Icons.WebDevicons.Folder* + Overrides glyphs and highlight groups where noted. Fields: ~ - • {enable}? (`boolean`) Show icons on folders. Overrides - |nvim-tree.renderer.icons.glyphs.folder| Default: `false` - • {color}? (`boolean`) Use icon colors for folders. Overrides - highlight groups. Default: `true` + • {file}? (`table`) Files + • {enable}? (`boolean`, default: `true`) Show icons for + files, overrides |nvim_tree.Config.Renderer.Icons.Glyphs| + {default}. + • {color}? (`boolean`, default: `true`) Apply colours to + files, overrides `NvimTreeFileIcon`. + • {folder}? (`table`) Directories + • {enable}? (`boolean`, default: `false`) Show icons for + directories, overrides + |nvim_tree.Config.Renderer.Icons.Glyphs| {folder}. + • {color}? (`boolean`, default: `true`) Apply colors to + directories, overrides `NvimTree*FolderName`. *nvim_tree.Config.Renderer.IndentMarkers* diff --git a/lua/nvim-tree/_meta/config/help.lua b/lua/nvim-tree/_meta/config/help.lua index 51e6a5d2453..1a2e189a478 100644 --- a/lua/nvim-tree/_meta/config/help.lua +++ b/lua/nvim-tree/_meta/config/help.lua @@ -1,10 +1,10 @@ ---@meta error("Cannot require a meta file") ----@alias nvim_tree.Config.Help.SortBy "key"|"desc" ---Configure help window, default mapping `g?` --- +---@alias nvim_tree.Config.Help.SortBy "key"|"desc" ---[nvim_tree.Config.Help.SortBy]() ---- `key`: alphabetically by keymap ---- `desc`: alphabetically by description diff --git a/lua/nvim-tree/_meta/config/renderer.lua b/lua/nvim-tree/_meta/config/renderer.lua index 95a958be0e5..47b29cfd5c2 100644 --- a/lua/nvim-tree/_meta/config/renderer.lua +++ b/lua/nvim-tree/_meta/config/renderer.lua @@ -1,14 +1,10 @@ ---@meta error("Cannot require a meta file") ----@alias nvim_tree.Config.Renderer.HiddenDisplay "none"|"simple"|"all"|(fun(hidden_stats: table): string) ----@alias nvim_tree.Config.Renderer.HighlightPlacement "none"|"icon"|"name"|"all" - ---- TODO #2934 these were not correctly generated, inline or fix ----@alias nvim_tree.PlacementOption "before"|"after"|"signcolumn"|"right_align" ----Appearance of the tree. +---Controls the appearance of the tree. --- +---@alias nvim_tree.Config.Renderer.HighlightPlacement "none"|"icon"|"name"|"all" ---{highlight_} options [nvim_tree.Config.Renderer.HighlightPlacement]() ---- `none`: no highlighting ---- `icon`: icon only @@ -25,7 +21,8 @@ error("Cannot require a meta file") ---end ---``` --- ----TODO: link to hidden display help section [nvim_tree.Config.Renderer.HiddenDisplay]() +---@alias nvim_tree.Config.Renderer.HiddenDisplay "none"|"simple"|"all"|(fun(hidden_stats: table): string) +---TODO: link / move to hidden display help section [nvim_tree.Config.Renderer.HiddenDisplay]() --- ---{hidden_display} summary of hidden files below the tree. ---- `none`: disabled @@ -35,7 +32,7 @@ error("Cannot require a meta file") --- ---@class nvim_tree.Config.Renderer --- ----Appends a trailing slash to folder and symlink folder destination names. +---Appends a trailing slash to folder and symlink folder target names. ---(default: `false`) ---@field add_trailing? boolean --- @@ -57,7 +54,7 @@ error("Cannot require a meta file") ---(default: `none`) ---@field hidden_display? nvim_tree.Config.Renderer.HiddenDisplay --- ----Appends an arrow followed by the destination of the symlink. +---Appends an arrow followed by the target of the symlink. ---(default: `true`) ---@field symlink_destination? boolean --- @@ -137,37 +134,99 @@ error("Cannot require a meta file") ---@field none? string ----@class nvim_tree.Config.Renderer.Icons Configuration options for icons. ----@field web_devicons? nvim_tree.Config.Renderer.Icons.WebDevicons Configure optional plugin `"nvim-tree/nvim-web-devicons"` ----@field git_placement? nvim_tree.PlacementOption Git icons placement. Default: `"before"` ----@field diagnostics_placement? nvim_tree.PlacementOption Diganostic icon placement. Default: `"signcolumn"` @see nvim-tree.view.signcolumn @see nvim-tree.renderer.icons.show.diagnostics ----@field modified_placement? nvim_tree.PlacementOption Modified icon placement. Default: `"after"` ----@field hidden_placement? nvim_tree.PlacementOption Hidden icon placement. Default: `"after"` ----@field bookmarks_placement? nvim_tree.PlacementOption Bookmark icon placement. Default: `"signcolumn"` @see nvim-tree.renderer.icons.show.bookmarks +---Icons and separators. +--- +---@alias nvim_tree.Config.Renderer.Icons.Placement "before"|"after"|"signcolumn"|"right_align" +---{_placement} options [nvim_tree.Config.Renderer.Icons.Placement]() +---- `before`: before file/folder, after the file/folders icons +---- `after`: after file/folder +---- `signcolumn`: far left, requires [nvim_tree.Config.View] {signcolumn}. +---- `right_align`: far right +--- +---@class nvim_tree.Config.Renderer.Icons +--- +---[nvim_tree.Config.Renderer.Icons.WebDevicons] +---Use optional plugin `nvim-tree/nvim-web-devicons` +---@field web_devicons? nvim_tree.Config.Renderer.Icons.WebDevicons +--- +---(default: `before`) +---@field git_placement? nvim_tree.Config.Renderer.Icons.Placement +--- +---Requires [nvim_tree.Config.Diagnostics] {enable}. +---(default: `signcolumn`) +---@field diagnostics_placement? nvim_tree.Config.Renderer.Icons.Placement +--- +---Requires [nvim_tree.Config.Modified] {enable}. +---(default: `after`) +---@field modified_placement? nvim_tree.Config.Renderer.Icons.Placement +--- +---(default: `after`) +---@field hidden_placement? nvim_tree.Config.Renderer.Icons.Placement +--- +---(default: `signcolumn`) +---@field bookmarks_placement? nvim_tree.Config.Renderer.Icons.Placement +--- +---Padding inserted between ---@field padding? nvim_tree.Config.Renderer.Icons.Padding ----@field symlink_arrow? string Used as a separator between symlinks' source and target. Default: `" ➛ "` ----@field show? nvim_tree.Config.Renderer.Icons.Show Configuration options for showing icon types. Left to right order: file/folder, git, modified, hidden, diagnostics, bookmarked. ----@field glyphs? nvim_tree.Config.Renderer.Icons.Glyphs Configuration options for icon glyphs. NOTE: Do not set any glyphs to more than two characters if it's going to appear in the signcolumn. +--- +---Separator between symlink source and target. +---(default: ` ➛ `) +---@field symlink_arrow? string +--- +---[nvim_tree.Config.Renderer.Icons.Show] +---@field show? nvim_tree.Config.Renderer.Icons.Show +--- +---[nvim_tree.Config.Renderer.Icons.Glyphs] +---@field glyphs? nvim_tree.Config.Renderer.Icons.Glyphs +---Configure optional plugin `nvim-tree/nvim-web-devicons`. +--- +---Overrides glyphs and highlight groups where noted. +--- ---@class nvim_tree.Config.Renderer.Icons.WebDevicons ----@field file? nvim_tree.Config.Renderer.Icons.WebDevicons.File File icons. ----@field folder? nvim_tree.Config.Renderer.Icons.WebDevicons.Folder Folder icons. +--- +---Files +---@field file? nvim_tree.Config.Renderer.Icons.WebDevicons.File +--- +---Directories +---@field folder? nvim_tree.Config.Renderer.Icons.WebDevicons.Folder ---@class nvim_tree.Config.Renderer.Icons.WebDevicons.File ----@field enable? boolean Show icons on files. Overrides |nvim-tree.renderer.icons.glyphs.default| Default: `true` ----@field color? boolean Use icon colors for files. Overrides highlight groups. Default: `true` +---@inlinedoc +--- +---Show icons for files, overrides [nvim_tree.Config.Renderer.Icons.Glyphs] {default}. +---(default: `true`) +---@field enable? boolean +--- +---Apply colours to files, overrides `NvimTreeFileIcon`. +---(default: `true`) +---@field color? boolean ---@class nvim_tree.Config.Renderer.Icons.WebDevicons.Folder ----@field enable? boolean Show icons on folders. Overrides |nvim-tree.renderer.icons.glyphs.folder| Default: `false` ----@field color? boolean Use icon colors for folders. Overrides highlight groups. Default: `true` +---@inlinedoc +--- +---Show icons for directories, overrides [nvim_tree.Config.Renderer.Icons.Glyphs] {folder}. +---(default: `false`) +---@field enable? boolean +--- +---Apply colors to directories, overrides `NvimTree*FolderName`. +---(default: `true`) +---@field color? boolean ---@class nvim_tree.Config.Renderer.Icons.Padding ----@field icon? string Inserted between icon and filename. Default: `" "` ----@field folder_arrow? string Inserted between folder arrow icon and file/folder icon. Default: `" "` +---@inlinedoc +--- +---icon and filename. +---(default: ` `) +---@field icon? string +--- +---folder arrow icon and file/folder icon. +---(default: ` `) +---@field folder_arrow? string ---Control which icons are displayed. From b60fa05d1d4de95d658f593a8c1c297add17436e Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Mon, 12 Jan 2026 14:54:26 +1100 Subject: [PATCH 044/170] docs(#2934): tidy Config.FilesystemWatchers --- doc/nvim-tree-lua.txt | 2 +- lua/nvim-tree/_meta/config/filesystem_watchers.lua | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 6d6962f7d1c..beea1cb1410 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -4149,7 +4149,7 @@ Class: Config.FilesystemWatchers *nvim-tree-config-filesystem-watchers* directory changes, resulting in better performance. Watchers may be disabled for absolute directory paths via {ignore_dirs}. - • A list of |vim regex| to match a path, backslash escaped e.g. + • A list of |vim.regex| to match a path, backslash escaped e.g. `"my-proj/\\.build$"` OR • A function that is passed an absolute path and returns `true` to disable This may be useful when a path is not in `.gitignore` or git integration diff --git a/lua/nvim-tree/_meta/config/filesystem_watchers.lua b/lua/nvim-tree/_meta/config/filesystem_watchers.lua index 85b4e807c6a..dae3ae77810 100644 --- a/lua/nvim-tree/_meta/config/filesystem_watchers.lua +++ b/lua/nvim-tree/_meta/config/filesystem_watchers.lua @@ -6,7 +6,7 @@ error("Cannot require a meta file") ---With this feature, the tree will be partially updated on specific directory changes, resulting in better performance. --- ---Watchers may be disabled for absolute directory paths via {ignore_dirs}. ---- - A list of [vim regex] to match a path, backslash escaped e.g. `"my-proj/\\.build$"` OR +--- - A list of [vim.regex] to match a path, backslash escaped e.g. `"my-proj/\\.build$"` OR --- - A function that is passed an absolute path and returns `true` to disable ---This may be useful when a path is not in `.gitignore` or git integration is disabled. ---@class nvim_tree.Config.FilesystemWatchers From f15aa33439561e4c621a2340869c7808568f36e9 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Mon, 12 Jan 2026 15:05:53 +1100 Subject: [PATCH 045/170] docs(#2934): fix broken links --- doc/nvim-tree-lua.txt | 35 +++++++++++----------- lua/nvim-tree/_meta/config.lua | 2 +- lua/nvim-tree/_meta/config/actions.lua | 4 +-- lua/nvim-tree/_meta/config/diagnostics.lua | 4 +-- lua/nvim-tree/_meta/config/git.lua | 2 +- lua/nvim-tree/_meta/config/log.lua | 2 +- lua/nvim-tree/_meta/config/system_open.lua | 2 +- lua/nvim-tree/_meta/config/view.lua | 12 ++++---- 8 files changed, 31 insertions(+), 32 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index beea1cb1410..5b66f28d59b 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3506,8 +3506,8 @@ Class: Config *nvim-tree-config* nvim-tree to that of new buffer's when opening nvim-tree. • {select_prompts}? (`boolean`, default: `false`) Use - |vim.ui.select| style prompts. Necessary when - using a UI prompt decorator such as + |vim.ui.select()| style prompts. Necessary + when using a UI prompt decorator such as dressing.nvim or telescope-ui-select.nvim • {sort}? (`nvim_tree.Config.Sort`) |nvim_tree.Config.Sort| @@ -3613,9 +3613,9 @@ Class: Config.View *nvim-tree-config-view* view so that the current node is initially centralized, see |zz|. • {cursorline}? (`boolean`, default: `true`) - |cursorline| + |'cursorline'| • {cursorlineopt}? (`string`, default: `both`) - |cursorlineopt| + |'cursorlineopt'| • {debounce_delay}? (`integer`, default: `15`) Idle milliseconds before some reload / refresh operations. Increase if you @@ -3627,11 +3627,12 @@ Class: Config.View *nvim-tree-config-view* opening a file. If `false`, the height and width of windows other than nvim-tree will be equalized. - • {number}? (`boolean`, default: `false`) |number| + • {number}? (`boolean`, default: `false`) + |'number'| • {relativenumber}? (`boolean`, default: `false`) - |relativenumber| + |'relativenumber'| • {signcolumn}? (`"yes"|"auto"|"no"`, default: `yes`) - |signcolumn| + |'signcolumn'| • {width}? (`nvim_tree.Config.View.WidthSpec|nvim_tree.Config.View.Width`) (default: `30`) • {float}? (`nvim_tree.Config.View.Float`) @@ -3640,8 +3641,7 @@ Class: Config.View *nvim-tree-config-view* *nvim_tree.Config.View.Float* Configure floating window behaviour - |vim.api.keyset.win_config| {open_win_config} is passed directly to - |nvim_open_win|, default: >lua + {open_win_config} is passed directly to |nvim_open_win()|, default: >lua { relative = "editor", border = "rounded", @@ -3963,7 +3963,7 @@ Class: Config.SystemOpen *nvim-tree-config-system-open* Open files or directories via the OS. Neovim: - • `>=` 0.10 uses |vim.ui.open| unless {cmd} is specified + • `>=` 0.10 uses |vim.ui.open()| unless {cmd} is specified • `<` 0.10 calls external {cmd}: • UNIX: `xdg-open` • macOS: `open` @@ -3990,7 +3990,7 @@ Class: Config.Git *nvim-tree-config-git* Git integration may be disabled for git top-level directories via {disable_for_dirs}: - • A list of relative paths evaluated with |fnamemodify| `:p` OR + • A list of relative paths evaluated with |fnamemodify()| `:p` OR • A function that is passed an absolute path and returns `true` to disable Fields: ~ @@ -4031,9 +4031,9 @@ Class: Config.Diagnostics *nvim-tree-config-diagnostics* • {severity}? (`table`) |nvim_tree.Config.Diagnostics.Severity| • {min}? (`vim.diagnostic.Severity`, default: - HINT) |vim.diagnostic.Severity| + HINT) |vim.diagnostic.severity| • {max}? (`vim.diagnostic.Severity`, default: - ERROR) |vim.diagnostic.Severity| + ERROR) |vim.diagnostic.severity| • {icons}? (`table`) |nvim_tree.Config.Diagnostics.Icons| • {hint}? (`string`) (default: `` ) • {info}? (`string`) (default: `` ) @@ -4213,8 +4213,7 @@ Class: Config.Actions *nvim-tree-config-actions* *nvim_tree.Config.Actions.FilePopup* {file_popup} floating window. - |vim.api.keyset.win_config| {open_win_config} is passed directly to - |nvim_open_win|, default: >lua + {open_win_config} is passed directly to |nvim_open_win()|, default: >lua { col = 1, row = 1, @@ -4224,8 +4223,8 @@ Class: Config.Actions *nvim-tree-config-actions* } < - You shouldn't define |vim.api.keyset.win_config| {width} and {height} - values here. They will be overridden to fit the file_popup content. + You shouldn't define {width} and {height} values here. They will be + overridden to fit the file_popup content. Fields: ~ • {open_win_config}? (`vim.api.keyset.win_config`) (default: above) @@ -4383,7 +4382,7 @@ Class: Config.UI *nvim-tree-config-ui* Class: Config.Log *nvim-tree-config-log* *nvim_tree.Config.Log* - Log to a file `nvim-tree.log` in |stdpath| `log`, usually + Log to a file `nvim-tree.log` in |stdpath()| `log`, usually `${XDG_STATE_HOME}/nvim` Fields: ~ diff --git a/lua/nvim-tree/_meta/config.lua b/lua/nvim-tree/_meta/config.lua index a5d7595cbc2..1e482795de4 100644 --- a/lua/nvim-tree/_meta/config.lua +++ b/lua/nvim-tree/_meta/config.lua @@ -50,7 +50,7 @@ error("Cannot require a meta file") ---(default: `false`) ---@field respect_buf_cwd? boolean --- ----Use [vim.ui.select] style prompts. Necessary when using a UI prompt decorator such as dressing.nvim or telescope-ui-select.nvim +---Use [vim.ui.select()] style prompts. Necessary when using a UI prompt decorator such as dressing.nvim or telescope-ui-select.nvim ---(default: `false`) ---@field select_prompts? boolean --- diff --git a/lua/nvim-tree/_meta/config/actions.lua b/lua/nvim-tree/_meta/config/actions.lua index 3b23fe3f653..3ce1f64af04 100644 --- a/lua/nvim-tree/_meta/config/actions.lua +++ b/lua/nvim-tree/_meta/config/actions.lua @@ -53,7 +53,7 @@ error("Cannot require a meta file") ---{file_popup} floating window. --- ----[vim.api.keyset.win_config] {open_win_config} is passed directly to [nvim_open_win], default: +---{open_win_config} is passed directly to [nvim_open_win()], default: ---```lua ---{ --- col = 1, @@ -63,7 +63,7 @@ error("Cannot require a meta file") --- style = "minimal", ---} ---``` ----You shouldn't define [vim.api.keyset.win_config] {width} and {height} values here. They will be overridden to fit the file_popup content. +---You shouldn't define {width} and {height} values here. They will be overridden to fit the file_popup content. ---@class nvim_tree.Config.Actions.FilePopup --- ---(default: above) diff --git a/lua/nvim-tree/_meta/config/diagnostics.lua b/lua/nvim-tree/_meta/config/diagnostics.lua index f15f5baee45..d81d0a31d44 100644 --- a/lua/nvim-tree/_meta/config/diagnostics.lua +++ b/lua/nvim-tree/_meta/config/diagnostics.lua @@ -33,11 +33,11 @@ error("Cannot require a meta file") ---@class nvim_tree.Config.Diagnostics.Severity ---@inlinedoc --- ----[vim.diagnostic.Severity] +---[vim.diagnostic.severity] ---(default: HINT) ---@field min? vim.diagnostic.Severity --- ----[vim.diagnostic.Severity] +---[vim.diagnostic.severity] ---(default: ERROR) ---@field max? vim.diagnostic.Severity diff --git a/lua/nvim-tree/_meta/config/git.lua b/lua/nvim-tree/_meta/config/git.lua index 4251b211f91..121a13137c9 100644 --- a/lua/nvim-tree/_meta/config/git.lua +++ b/lua/nvim-tree/_meta/config/git.lua @@ -6,7 +6,7 @@ error("Cannot require a meta file") ---Processes will be killed if they exceed {timeout}ms. Git integration will be disabled following 5 timeouts and you will be notified. --- ---Git integration may be disabled for git top-level directories via {disable_for_dirs}: ---- - A list of relative paths evaluated with [fnamemodify] `:p` OR +--- - A list of relative paths evaluated with [fnamemodify()] `:p` OR --- - A function that is passed an absolute path and returns `true` to disable --- ---@class nvim_tree.Config.Git diff --git a/lua/nvim-tree/_meta/config/log.lua b/lua/nvim-tree/_meta/config/log.lua index ee0358e2919..cc00efe8bdd 100644 --- a/lua/nvim-tree/_meta/config/log.lua +++ b/lua/nvim-tree/_meta/config/log.lua @@ -1,7 +1,7 @@ ---@meta error("Cannot require a meta file") ----Log to a file `nvim-tree.log` in [stdpath] `log`, usually `${XDG_STATE_HOME}/nvim` +---Log to a file `nvim-tree.log` in [stdpath()] `log`, usually `${XDG_STATE_HOME}/nvim` ---@class nvim_tree.Config.Log --- ---(default: `false`) diff --git a/lua/nvim-tree/_meta/config/system_open.lua b/lua/nvim-tree/_meta/config/system_open.lua index 6956b8d592b..6feff7a0117 100644 --- a/lua/nvim-tree/_meta/config/system_open.lua +++ b/lua/nvim-tree/_meta/config/system_open.lua @@ -4,7 +4,7 @@ error("Cannot require a meta file") ---Open files or directories via the OS. --- ---Neovim: ----- `>=` 0.10 uses [vim.ui.open] unless {cmd} is specified +---- `>=` 0.10 uses [vim.ui.open()] unless {cmd} is specified ---- `<` 0.10 calls external {cmd}: --- - UNIX: `xdg-open` --- - macOS: `open` diff --git a/lua/nvim-tree/_meta/config/view.lua b/lua/nvim-tree/_meta/config/view.lua index 0693a669e1c..839f22635fe 100644 --- a/lua/nvim-tree/_meta/config/view.lua +++ b/lua/nvim-tree/_meta/config/view.lua @@ -20,11 +20,11 @@ error("Cannot require a meta file") ---(default: `false`) ---@field centralize_selection? boolean --- ----[cursorline] +---['cursorline'] ---(default: `true`) ---@field cursorline? boolean --- ----[cursorlineopt] +---['cursorlineopt'] ---(default: `both`) ---@field cursorlineopt? string --- @@ -39,15 +39,15 @@ error("Cannot require a meta file") ---(default: `false`) ---@field preserve_window_proportions? boolean --- ----[number] +---['number'] ---(default: `false`) ---@field number? boolean --- ----[relativenumber] +---['relativenumber'] ---(default: `false`) ---@field relativenumber? boolean --- ----[signcolumn] +---['signcolumn'] ---(default: `yes`) ---@field signcolumn? "yes"|"auto"|"no" --- @@ -80,7 +80,7 @@ error("Cannot require a meta file") ---Configure floating window behaviour --- ----[vim.api.keyset.win_config] {open_win_config} is passed directly to [nvim_open_win], default: +---{open_win_config} is passed directly to [nvim_open_win()], default: ---```lua ---{ --- relative = "editor", From 06fcb5e02977dfeb52f6fdc8d89459853fd233b6 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Mon, 12 Jan 2026 15:24:12 +1100 Subject: [PATCH 046/170] docs(#2934): fix broken links --- doc/nvim-tree-lua.txt | 81 ++++++++++++++++++++----------------------- 1 file changed, 38 insertions(+), 43 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 5b66f28d59b..03727090d0c 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -690,7 +690,7 @@ Set the following at the very beginning of your `init.lua` / `init.vim`: >lua vim.g.loaded_netrwPlugin = 1 < *nvim-tree.hijack_netrw* -Hijack netrw windows (overridden if |disable_netrw| is `true`) +Hijack netrw windows (overridden if |nvim-tree.disable_netrw| is `true`) Type: `boolean`, Default: `true` *nvim-tree.hijack_unnamed_buffer_when_opening* @@ -720,7 +720,7 @@ Will change cwd of nvim-tree to that of new buffer's when opening nvim-tree. Type: `boolean`, Default: `false` *nvim-tree.select_prompts* -Use |vim.ui.select| style prompts. Necessary when using a UI prompt decorator +Use |vim.ui.select()| style prompts. Necessary when using a UI prompt decorator such as dressing.nvim or telescope-ui-select.nvim Type: `boolean`, Default: `false` @@ -773,11 +773,11 @@ initially centralized, see |zz|. Type: `boolean`, Default: `false` *nvim-tree.view.cursorline* -Enable |cursorline| in the tree window. +Enable |'cursorline'| in the tree window. Type: `boolean`, Default: `true` *nvim-tree.view.cursorlineopt* -Set |cursorlineopt| in the tree window. +Set |'cursorlineopt'| in the tree window. Type: `string`, Default: `"both"` *nvim-tree.view.debounce_delay* @@ -805,7 +805,7 @@ will be the line number instead of `0`. Type: `boolean`, Default: `false` *nvim-tree.view.signcolumn* -Show |signcolumn|. Value can be `"yes"`, `"auto"`, `"no"`. +Show |'signcolumn'|. Value can be `"yes"`, `"auto"`, `"no"`. Type: `string`, Default: `"yes"` *nvim-tree.view.width* @@ -852,7 +852,7 @@ Use nvim-tree in a floating window. Type: `boolean`, Default: `true` *nvim-tree.view.float.open_win_config* - Floating window config. See |nvim_open_win| for more details. + Floating window config. See |nvim_open_win()| for more details. Type: `table | function` returning a table Default: `{` @@ -953,7 +953,7 @@ Whether to show the destination of the symlink. Highlighting and icons for the nodes, in increasing order of precedence. Uses strings to specify builtin decorators otherwise specify your `nvim_tree.api.decorator.UserDecorator` class. -See |nvim-tree-decorators|, |nvim-tree-api.decorator| +See |nvim-tree-decorators| Type: `nvim_tree.api.decorator.Name[]`, Default: >lua { "Git", @@ -981,7 +981,7 @@ Value can be `"none"`, `"icon"`, `"name"` or `"all"`. *nvim-tree.renderer.highlight_opened_files* Highlight icons and/or names for |bufloaded()| files using the `NvimTreeOpenedHL` highlight group. -See |nvim-tree-api.navigate.opened.next()| and |nvim-tree-api.navigate.opened.prev()| +See |nvim-tree-api.node.navigate.opened.next()| and |nvim-tree-api.node.navigate.opened.prev()| Value can be `"none"`, `"icon"`, `"name"` or `"all"`. Type: `string`, Default: `"none"` @@ -1119,12 +1119,12 @@ Configuration options for icons. *nvim-tree.renderer.icons.show.git* Show a git status icon, see |renderer.icons.git_placement| - Requires |git.enable| `= true` + Requires |nvim-tree.git.enable| `= true` Type: `boolean`, Default: `true` *nvim-tree.renderer.icons.show.modified* Show a modified icon, see |renderer.icons.modified_placement| - Requires |modified.enable| `= true` + Requires |nvim-tree.modified.enable| `= true` Type: `boolean`, Default: `true` *nvim-tree.renderer.icons.show.hidden* @@ -1133,7 +1133,7 @@ Configuration options for icons. *nvim-tree.renderer.icons.show.diagnostics* Show a diagnostics status icon, see |renderer.icons.diagnostics_placement| - Requires |diagnostics.enable| `= true` + Requires |nvim-tree.diagnostics.enable| `= true` Type: `boolean`, Default: `true` *nvim-tree.renderer.icons.show.bookmarks* @@ -1239,7 +1239,7 @@ Takes the `BufEnter` event as an argument. see |autocmd-events| Open a file or directory in your preferred application. -|vim.ui.open| was introduced in neovim 0.10 and is the default. +|vim.ui.open()| was introduced in neovim 0.10 and is the default. Once nvim-tree minimum neovim version is updated to 0.10, these options will no longer be necessary and will be removed. @@ -1248,7 +1248,7 @@ no longer be necessary and will be removed. The open command itself. Type: `string`, Default: `""` -neovim >= 0.10 defaults to |vim.ui.open| +neovim >= 0.10 defaults to |vim.ui.open()| neovim < 0.10 defaults to: UNIX: `"xdg-open"` @@ -1288,7 +1288,7 @@ Only relevant when `git.show_on_dirs` is `true`. *nvim-tree.git.disable_for_dirs* Disable git integration when git top-level matches these paths. -Strings may be relative, evaluated via |fnamemodify| `":p"` +Strings may be relative, evaluated via |fnamemodify()| `":p"` Function is passed an absolute path and returns true for disable. Type: `string[] | fun(path: string): boolean`, Default: `{}` @@ -1367,7 +1367,7 @@ Show modified indication on directory whose children are modified. *nvim-tree.modified.show_on_open_dirs* Show modified indication on open directories. -Only relevant when |modified.show_on_dirs| is `true`. +Only relevant when |nvim-tree.modified.show_on_dirs| is `true`. Type: `boolean`, Default: `true` ============================================================================== @@ -1381,7 +1381,7 @@ Toggle via |nvim-tree-api.tree.toggle_enable_filters()| Type: `boolean`, Default: `true` *nvim-tree.filters.git_ignored* -Ignore files based on `.gitignore`. Requires |git.enable| `= true` +Ignore files based on `.gitignore`. Requires |nvim-tree.git.enable| `= true` Toggle via |nvim-tree-api.tree.toggle_gitignore_filter()|, default `I` Type: `boolean`, Default: `true` @@ -1510,7 +1510,7 @@ Configuration for |nvim-tree-api.tree.expand_all()| and Configuration for file_popup behaviour. *nvim-tree.actions.file_popup.open_win_config* - Floating window config for file_popup. See |nvim_open_win| for more details. + Floating window config for file_popup. See |nvim_open_win()| for more details. You shouldn't define `"width"` and `"height"` values here. They will be overridden to fit the file_popup content. Type: `table`, Default: @@ -1683,7 +1683,7 @@ In the event of a problem please disable the experiment and raise an issue. Configuration for diagnostic logging. *nvim-tree.log.enable* -Enable logging to a file `nvim-tree.log` in |stdpath| `"log"`, usually +Enable logging to a file `nvim-tree.log` in |stdpath()| `"log"`, usually `${XDG_STATE_HOME}/nvim` Type: `boolean`, Default: `false` @@ -1787,7 +1787,7 @@ tree.close_in_all_tabs() *nvim-tree-api.tree.close_in_all_tabs()* tree.focus() *nvim-tree-api.tree.focus()* Focus the tree, opening it if necessary. - Retained for compatibility, use |tree.open()| with no arguments instead. + Retained for compatibility, use |nvim-tree-api.tree.open()| with no arguments instead. tree.reload() *nvim-tree-api.tree.reload()* Refresh the tree. Does nothing if closed. @@ -2069,12 +2069,12 @@ node.open.edit({node}, {opts}) *nvim-tree-api.node.open.e *nvim-tree-api.node.open.replace_tree_buffer()* node.open.replace_tree_buffer({node}) - |nvim-tree-api.node.edit()|, file will be opened in place: in the + |nvim-tree-api.node.open.edit()|, file will be opened in place: in the nvim-tree window. *nvim-tree-api.node.open.no_window_picker()* node.open.no_window_picker({node}, {opts}) - |nvim-tree-api.node.edit()|, window picker will never be used as per + |nvim-tree-api.node.open.edit()|, window picker will never be used as per |nvim-tree.actions.open_file.window_picker.enable| `false` Parameters: ~ @@ -2086,7 +2086,7 @@ node.open.no_window_picker({node}, {opts}) • {focus} (boolean) keep focus in the tree when opening the file node.open.vertical({node}, {opts}) *nvim-tree-api.node.open.vertical()* - |nvim-tree-api.node.edit()|, file will be opened in a new vertical split. + |nvim-tree-api.node.open.edit()|, file will be opened in a new vertical split. Parameters: ~ • {node} (Node|nil) file or folder @@ -2098,7 +2098,7 @@ node.open.vertical({node}, {opts}) *nvim-tree-api.node.open.verti *nvim-tree-api.node.open.vertical_no_picker()* node.open.vertical_no_picker({node}, {opts}) - |nvim-tree-api.node.vertical()|, window picker will never be used as per + |nvim-tree-api.node.open.vertical()|, window picker will never be used as per |nvim-tree.actions.open_file.window_picker.enable| `false` Parameters: ~ @@ -2110,7 +2110,7 @@ node.open.vertical_no_picker({node}, {opts}) • {focus} (boolean) keep focus in the tree when opening the file node.open.horizontal({node}, {opts}) *nvim-tree-api.node.open.horizontal()* - |nvim-tree-api.node.edit()|, file will be opened in a new horizontal split. + |nvim-tree-api.node.open.edit()|, file will be opened in a new horizontal split. Parameters: ~ • {node} (Node|nil) file or folder @@ -2122,7 +2122,7 @@ node.open.horizontal({node}, {opts}) *nvim-tree-api.node.open.horizon *nvim-tree-api.node.open.horizontal_no_picker()* node.open.horizontal_no_picker({node}, {opts}) - |nvim-tree-api.node.horizontal()|, window picker will never be used as per + |nvim-tree-api.node.open.horizontal()|, window picker will never be used as per |nvim-tree.actions.open_file.window_picker.enable| `false` Parameters: ~ @@ -2157,7 +2157,7 @@ node.open.drop({node}) *nvim-tree-api.node.open.drop()* Root: change directory up node.open.tab({node}, {opts}) *nvim-tree-api.node.open.tab()* - |nvim-tree-api.node.edit()|, file will be opened in a new tab. + |nvim-tree-api.node.open.edit()|, file will be opened in a new tab. Parameters: ~ • {node} (Node|nil) file or folder @@ -2177,7 +2177,7 @@ node.open.tab_drop({node}) Root: change directory up node.open.preview({node}, {opts}) *nvim-tree-api.node.open.preview()* - |nvim-tree-api.node.edit()|, file buffer will have |bufhidden| set to `delete`. + |nvim-tree-api.node.open.edit()|, file buffer will have |'bufhidden'| set to `delete`. Parameters: ~ • {node} (Node|nil) file or folder @@ -2189,7 +2189,7 @@ node.open.preview({node}, {opts}) *nvim-tree-api.node.open.prev *nvim-tree-api.node.open.preview_no_picker()* node.open.preview_no_picker({node}, {opts}) - |nvim-tree-api.node.edit()|, file buffer will have |bufhidden| set to `delete`. + |nvim-tree-api.node.open.edit()|, file buffer will have |'bufhidden'| set to `delete`. window picker will never be used as per |nvim-tree.actions.open_file.window_picker.enable| `false` @@ -2212,7 +2212,7 @@ node.navigate.git.next_recursive({node}) *nvim-tree-api.node.navigate.git.next_skip_gitignored()* node.navigate.git.next_skip_gitignored({node}) - Same as |node.navigate.git.next()|, but skips gitignored files. + Same as |nvim-tree-api.node.navigate.git.next()|, but skips gitignored files. node.navigate.git.prev({node}) *nvim-tree-api.node.navigate.git.prev()* Navigate to the previous item showing git status. @@ -2225,7 +2225,7 @@ node.navigate.git.prev_recursive({node}) *nvim-tree-api.node.navigate.git.prev_skip_gitignored()* node.navigate.git.prev_skip_gitignored({node}) - Same as |node.navigate.git.prev()|, but skips gitignored files. + same as |nvim-tree-api.node.navigate.git.prev()|, but skips gitignored files. *nvim-tree-api.node.navigate.diagnostics.next()* node.navigate.diagnostics.next({node}) @@ -2279,7 +2279,7 @@ node.navigate.parent({node}) *nvim-tree-api.node.navigate.parent_close()* node.navigate.parent_close({node}) - |api.node.navigate.parent()|, closing that folder. + |nvim-tree-api.node.navigate.parent()|, closing that folder. node.show_info_popup({node}) *nvim-tree-api.node.show_info_popup()* Open a popup window showing: fullpath, size, accessed, modified, created. @@ -2506,11 +2506,9 @@ The `on_attach` function is passed the `bufnr` of nvim-tree. Use --- }) < -Mouse support is defined in |KeyBindings| - Single left mouse mappings can be achieved via ``. -Single right / middle mouse mappings will require changes to |mousemodel| or |mouse|. +Single right / middle mouse mappings will require changes to |'mousemodel'| or |'mouse'|. |vim.keymap.set()| {rhs} is a `(function|string)` thus it may be necessary to define your own function to map complex functionality e.g. >lua @@ -2624,7 +2622,7 @@ groups. Example |:highlight| >vim :hi NvimTreeSymlink guifg=blue gui=bold,underline < -It is recommended to enable |termguicolors| for the more pleasant 24-bit +It is recommended to enable |'termguicolors'| for the more pleasant 24-bit colours. To view the nvim-tree highlight groups run |:NvimTreeHiTest| @@ -2781,7 +2779,7 @@ See |nvim-tree-legacy-highlight| for old highlight group compatibility. 2024-01-20: significant highlighting changes, some breaking: - Full cterm support. -- Standard vim highlight groups such |DiagnosticUnderlineError| are now the +- Standard vim highlight groups such `DiagnosticUnderlineError` are now the defaults. - Highlight groups named consistently. - All `highlight_xxx` e.g. |nvim-tree.renderer.highlight_git| are granular, @@ -2845,7 +2843,7 @@ e.g. handler for node renamed: >lua - Event.TreePreOpen Invoked before the window and buffer for NvimTree are created - or opened. Before |Event.TreeOpen| event. + or opened. Before `Event.TreeOpen` • Note: Handler takes no parameter. - Event.TreeOpen @@ -2907,7 +2905,7 @@ e.g. handler for node renamed: >lua - Event.TreeRendered Invoked every time the tree is redrawn. Normally this event - happens after |Event.TreeOpen| except that handlers of this + happens after `Event.TreeOpen` except that handlers of this one will have access to the tree buffer populated with the final content. handler parameters: ~ @@ -2936,7 +2934,7 @@ Example subscription: >lua ============================================================================== 10. PROMPTS *nvim-tree-prompts* -Some NvimTree actions use the builtin |vim.ui.select| prompt API for +Some NvimTree actions use the builtin |vim.ui.select()| prompt API for confirmations when the |nvim_tree.select_prompts| option is set. The API accepts the optional `kind` key as part of the {opts} parameter, which @@ -2969,8 +2967,6 @@ Decorators may: - Set highlight group for the name or icons - Override node icon -See |nvim-tree-api.decorator| - Create a `nvim_tree.api.decorator.UserDecorator` class and register it with precedence via |nvim-tree.renderer.decorators| @@ -3730,8 +3726,7 @@ Class: Config.Renderer *nvim-tree-config-renderer* Highlighting and icons for the nodes, in increasing order of precedence. Strings specify builtin decorators. See - |nvim-tree-decorators|, - |nvim-tree-api.decorator| + |nvim-tree-decorators| • {highlight_git}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) Git status: `NvimTreeGit*HL`. Requires |nvim_tree.Config.Git| {enable}. From aa915c4328f661f1efb28dec9ae30d541f07134d Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Mon, 12 Jan 2026 16:26:56 +1100 Subject: [PATCH 047/170] docs(#2934): fix broken links --- doc/nvim-tree-lua.txt | 45 +++++++++++++++++++++---------------------- 1 file changed, 22 insertions(+), 23 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 03727090d0c..a48ce24e16d 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -85,7 +85,7 @@ File Icons  should look like an open folder. - To disable the display of icons see |renderer.icons.show| + To disable the display of icons see |nvim-tree.renderer.icons.show| Colours @@ -1018,7 +1018,7 @@ Configuration options for tree indent markers. *nvim-tree.renderer.indent_markers.inline_arrows* Display folder arrows in the same column as indent marker - when using |renderer.icons.show.folder_arrow| + when using |nvim-tree.renderer.icons.show.folder_arrow| Type: `boolean`, Default: `true` *nvim-tree.renderer.indent_markers.icons* @@ -1114,30 +1114,30 @@ Configuration options for icons. *nvim-tree.renderer.icons.show.folder_arrow* Show a small arrow before the folder node. Arrow will be a part of the - node when using |renderer.indent_markers|. + node when using |nvim-tree.renderer.indent_markers|. Type: `boolean`, Default: `true` *nvim-tree.renderer.icons.show.git* - Show a git status icon, see |renderer.icons.git_placement| + Show a git status icon, see |nvim-tree.renderer.icons.git_placement| Requires |nvim-tree.git.enable| `= true` Type: `boolean`, Default: `true` *nvim-tree.renderer.icons.show.modified* - Show a modified icon, see |renderer.icons.modified_placement| + Show a modified icon, see |nvim-tree.renderer.icons.modified_placement| Requires |nvim-tree.modified.enable| `= true` Type: `boolean`, Default: `true` *nvim-tree.renderer.icons.show.hidden* - Show a hidden icon, see |renderer.icons.hidden_placement| + Show a hidden icon, see |nvim-tree.renderer.icons.hidden_placement| Type: `boolean`, Default: `false` *nvim-tree.renderer.icons.show.diagnostics* - Show a diagnostics status icon, see |renderer.icons.diagnostics_placement| + Show a diagnostics status icon, see |nvim-tree.renderer.icons.diagnostics_placement| Requires |nvim-tree.diagnostics.enable| `= true` Type: `boolean`, Default: `true` *nvim-tree.renderer.icons.show.bookmarks* - Show a bookmark icon, see |renderer.icons.bookmarks_placement| + Show a bookmark icon, see |nvim-tree.renderer.icons.bookmarks_placement| Type: `boolean`, Default: `true` *nvim-tree.renderer.icons.glyphs* @@ -1353,8 +1353,8 @@ Icons for diagnostic severity. Indicate which file have unsaved modification. -You will still need to set |renderer.icons.show.modified| `= true` or -|renderer.highlight_modified| `= true` to be able to see modified status in the +You will still need to set |nvim-tree.renderer.icons.show.modified| `= true` or +|nvim-tree.renderer.highlight_modified| `= true` to be able to see modified status in the tree. *nvim-tree.modified.enable* @@ -1723,7 +1723,7 @@ Specify which information to log. Type: `boolean`, Default: `false` *nvim-tree.log.types.watcher* - |nvim-tree.filesystem_watchers| processing, verbose. + |nvim-tree-opts-filesystem-watchers| processing, verbose. Type: `boolean`, Default: `false` ============================================================================== @@ -1963,7 +1963,7 @@ fs.remove({node}) *nvim-tree-api.fs.remove()* • {node} (Node|nil) file or folder fs.trash({node}) *nvim-tree-api.fs.trash()* - Trash a file or folder as per |nvim-tree.trash| + Trash a file or folder as per |nvim-tree-opts-trash| Parameters: ~ • {node} (Node|nil) file or folder @@ -2289,7 +2289,7 @@ node.run.cmd({node}) *nvim-tree-api.node.run.cmd()* of the line. node.run.system({node}) *nvim-tree-api.node.run.system()* - Execute |nvim-tree.system_open| + Execute |nvim-tree-opts-system-open| node.buffer.delete({node}, {opts}) *nvim-tree-api.node.buffer.delete()* Deletes node's related buffer, if one exists. @@ -2361,11 +2361,11 @@ events.Event *nvim-tree-api.events.Event* 6.6 API LIVE FILTER *nvim-tree-api.live_filter* live_filter.start() *nvim-tree-api.live_filter.start()* - Enter |nvim-tree.live_filter| mode. + Enter |nvim-tree-api.live_filter| mode. Opens an input window with |filetype| `"NvimTreeFilter"` live_filter.clear() *nvim-tree-api.live_filter.clear()* - Exit |nvim-tree.live_filter| mode. + Exit |nvim-tree-api.live_filter| mode. ============================================================================== 6.7 API MARKS *nvim-tree-api.marks* @@ -2403,7 +2403,7 @@ marks.bulk.move() *nvim-tree-api.marks.bulk.move()* marks.navigate.next() *nvim-tree-api.marks.navigate.next()* Navigate to the next marked node, wraps. Opens files as per |nvim-tree.actions.open_file| - Works best with |nvim-tree.update_focused_file| enabled. + Works best with |nvim-tree-opts-update-focused-file| enabled. marks.navigate.prev() *nvim-tree-api.marks.navigate.prev()* As per |nvim-tree-api.marks.navigate.next()| @@ -2811,8 +2811,6 @@ Approximate pre-overhaul values for the `SpellCap` groups may be set via: >lua ============================================================================== 9. EVENTS *nvim-tree-events* -|nvim_tree_events| - nvim-tree will dispatch events whenever an action is made. These events can be subscribed to through handler functions. This allows for even further customization of nvim-tree. @@ -2821,7 +2819,7 @@ A handler for an event is just a function which receives one argument, the payload of the event. The payload is different for each event type. Refer to |nvim_tree_registering_handlers| for more information. -|nvim_tree_registering_handlers| +*nvim_tree_registering_handlers* Handlers are registered by calling |nvim-tree-api.events.subscribe()| function with an |nvim-tree-api.events.Event| @@ -2835,7 +2833,7 @@ e.g. handler for node renamed: >lua print("Node renamed from " .. data.old_name .. " to " .. data.new_name) end) < -|nvim_tree_events_kind| +*nvim_tree_events_kind* - Event.Ready When NvimTree has been initialized. @@ -2912,7 +2910,7 @@ e.g. handler for node renamed: >lua {bufnr} `{number} `API buffer handle (buffer number) {winnr} `{number} `API window handle (window number) -|nvim_tree_events_startup| +*nvim_tree_events_startup* There are two special startup events in the form of User autocommands: @@ -2935,7 +2933,7 @@ Example subscription: >lua 10. PROMPTS *nvim-tree-prompts* Some NvimTree actions use the builtin |vim.ui.select()| prompt API for -confirmations when the |nvim_tree.select_prompts| option is set. +confirmations when the |nvim-tree.select_prompts| option is set. The API accepts the optional `kind` key as part of the {opts} parameter, which can can be used to identify the type of prompt, to allow user side @@ -3726,7 +3724,8 @@ Class: Config.Renderer *nvim-tree-config-renderer* Highlighting and icons for the nodes, in increasing order of precedence. Strings specify builtin decorators. See - |nvim-tree-decorators| + |nvim-tree-decorators|, + |nvim-tree-api.decorator| • {highlight_git}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) Git status: `NvimTreeGit*HL`. Requires |nvim_tree.Config.Git| {enable}. From 5c133d32a92ba76a1c937a58a30ddd33b8e750f2 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Mon, 12 Jan 2026 16:59:56 +1100 Subject: [PATCH 048/170] docs(#2934): fix broken links --- doc/nvim-tree-lua.txt | 32 +++++++++++++--------- lua/nvim-tree/_meta/config/diagnostics.lua | 4 +-- lua/nvim-tree/_meta/config/renderer.lua | 16 ++++++----- 3 files changed, 30 insertions(+), 22 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index a48ce24e16d..4f59786e033 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3724,8 +3724,7 @@ Class: Config.Renderer *nvim-tree-config-renderer* Highlighting and icons for the nodes, in increasing order of precedence. Strings specify builtin decorators. See - |nvim-tree-decorators|, - |nvim-tree-api.decorator| + |nvim-tree-decorators|. • {highlight_git}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) Git status: `NvimTreeGit*HL`. Requires |nvim_tree.Config.Git| {enable}. @@ -3779,11 +3778,13 @@ Class: Config.Renderer *nvim-tree-config-renderer* (default: `after`) • {bookmarks_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`) (default: `signcolumn`) - • {padding}? (`table`) Padding inserted between - • {icon}? (`string`, default: ` `) icon and - filename. + • {padding}? (`table`) + *nvim_tree.Config.Renderer.Icons.Padding* + • {icon}? (`string`, default: ` `) Between + icon and filename. • {folder_arrow}? (`string`, default: ` `) - folder arrow icon and file/folder icon. + Between folder arrow icon and file/folder + icon. • {symlink_arrow}? (`string`, default: ` ➛ `) Separator between symlink source and target. • {show}? (`nvim_tree.Config.Renderer.Icons.Show`) @@ -3806,7 +3807,7 @@ Class: Config.Renderer *nvim-tree-config-renderer* • {modified}? (`string`) (default: `●` ) • {hidden}? (`string`) (default: `󰜌` ) • {folder}? (`table`) Overridden by |nvim_tree.Config.Renderer.Icons| - {web_devicons} + {web_devicons} *nvim_tree.Config.Renderer.Icons.Glyphs.Folder* • {arrow_closed}? (`string`) (default: left arrow) • {arrow_open}? (`string`) (default: down arrow) • {default}? (`string`) (default: `` ) @@ -3815,7 +3816,8 @@ Class: Config.Renderer *nvim-tree-config-renderer* • {empty_open}? (`string`) (default: `` ) • {symlink}? (`string`) (default: `` ) • {symlink_open}? (`string`) (default: `` ) - • {git}? (`table`) Git status on files and directories. + • {git}? (`table`) Git status on files and + directories. *nvim_tree.Config.Renderer.Icons.Glyphs.Git* • {unstaged}? (`string`) (default: `✗` ) • {staged}? (`string`) (default: `✓` ) • {unmerged}? (`string`) (default: `` ) @@ -3869,13 +3871,15 @@ Class: Config.Renderer *nvim-tree-config-renderer* Overrides glyphs and highlight groups where noted. Fields: ~ - • {file}? (`table`) Files + • {file}? (`table`) + *nvim_tree.Config.Renderer.Icons.WebDevicons.File* • {enable}? (`boolean`, default: `true`) Show icons for files, overrides |nvim_tree.Config.Renderer.Icons.Glyphs| {default}. • {color}? (`boolean`, default: `true`) Apply colours to files, overrides `NvimTreeFileIcon`. - • {folder}? (`table`) Directories + • {folder}? (`table`) + *nvim_tree.Config.Renderer.Icons.WebDevicons.Folder* • {enable}? (`boolean`, default: `false`) Show icons for directories, overrides |nvim_tree.Config.Renderer.Icons.Glyphs| {folder}. @@ -3891,7 +3895,9 @@ Class: Config.Renderer *nvim-tree-config-renderer* in the same column as indent marker when using |nvim_tree.Config.Renderer.Icons.Padding| {folder_arrow} - • {icons}? (`table`) Before the file/directory, length 1. + • {icons}? (`table`) + *nvim_tree.Config.Renderer.IndentMarkers.Icons* + Before the file/directory, length 1. • {corner}? (`string`) (default: `└` ) • {edge}? (`string`) (default: `│` ) • {item}? (`string`) (default: `│` ) @@ -4023,12 +4029,12 @@ Class: Config.Diagnostics *nvim-tree-config-diagnostics* |vim.diagnostic.Opts| overrides {severity} and {icons} • {severity}? (`table`) - |nvim_tree.Config.Diagnostics.Severity| + *nvim_tree.Config.Diagnostics.Severity* • {min}? (`vim.diagnostic.Severity`, default: HINT) |vim.diagnostic.severity| • {max}? (`vim.diagnostic.Severity`, default: ERROR) |vim.diagnostic.severity| - • {icons}? (`table`) |nvim_tree.Config.Diagnostics.Icons| + • {icons}? (`table`) *nvim_tree.Config.Diagnostics.Icons* • {hint}? (`string`) (default: `` ) • {info}? (`string`) (default: `` ) • {warning}? (`string`) (default: `` ) diff --git a/lua/nvim-tree/_meta/config/diagnostics.lua b/lua/nvim-tree/_meta/config/diagnostics.lua index d81d0a31d44..37357d17183 100644 --- a/lua/nvim-tree/_meta/config/diagnostics.lua +++ b/lua/nvim-tree/_meta/config/diagnostics.lua @@ -24,12 +24,11 @@ error("Cannot require a meta file") ---(default: `false`) ---@field diagnostic_opts? boolean --- ----[nvim_tree.Config.Diagnostics.Severity] ---@field severity? nvim_tree.Config.Diagnostics.Severity --- ----[nvim_tree.Config.Diagnostics.Icons] ---@field icons? nvim_tree.Config.Diagnostics.Icons +---[nvim_tree.Config.Diagnostics.Severity]() ---@class nvim_tree.Config.Diagnostics.Severity ---@inlinedoc --- @@ -41,6 +40,7 @@ error("Cannot require a meta file") ---(default: ERROR) ---@field max? vim.diagnostic.Severity +---[nvim_tree.Config.Diagnostics.Icons]() ---@class nvim_tree.Config.Diagnostics.Icons ---@inlinedoc --- diff --git a/lua/nvim-tree/_meta/config/renderer.lua b/lua/nvim-tree/_meta/config/renderer.lua index 47b29cfd5c2..0017bd40b37 100644 --- a/lua/nvim-tree/_meta/config/renderer.lua +++ b/lua/nvim-tree/_meta/config/renderer.lua @@ -58,7 +58,7 @@ error("Cannot require a meta file") ---(default: `true`) ---@field symlink_destination? boolean --- ----Highlighting and icons for the nodes, in increasing order of precedence. Strings specify builtin decorators. See [nvim-tree-decorators], [nvim-tree-api.decorator] +---Highlighting and icons for the nodes, in increasing order of precedence. Strings specify builtin decorators. See [nvim-tree-decorators]. ---(default: `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) ---@field decorators? (string|nvim_tree.api.decorator.UserDecorator)[] --- @@ -114,10 +114,10 @@ error("Cannot require a meta file") ---(default: `true`) ---@field inline_arrows? boolean --- ---- ---@field icons? nvim_tree.Config.Renderer.IndentMarkers.Icons +---[nvim_tree.Config.Renderer.IndentMarkers.Icons]() ---Before the file/directory, length 1. ---@class nvim_tree.Config.Renderer.IndentMarkers.Icons ---@inlinedoc @@ -166,7 +166,6 @@ error("Cannot require a meta file") ---(default: `signcolumn`) ---@field bookmarks_placement? nvim_tree.Config.Renderer.Icons.Placement --- ----Padding inserted between ---@field padding? nvim_tree.Config.Renderer.Icons.Padding --- ---Separator between symlink source and target. @@ -186,13 +185,12 @@ error("Cannot require a meta file") --- ---@class nvim_tree.Config.Renderer.Icons.WebDevicons --- ----Files ---@field file? nvim_tree.Config.Renderer.Icons.WebDevicons.File --- ----Directories ---@field folder? nvim_tree.Config.Renderer.Icons.WebDevicons.Folder +---[nvim_tree.Config.Renderer.Icons.WebDevicons.File]() ---@class nvim_tree.Config.Renderer.Icons.WebDevicons.File ---@inlinedoc --- @@ -205,6 +203,7 @@ error("Cannot require a meta file") ---@field color? boolean +---[nvim_tree.Config.Renderer.Icons.WebDevicons.Folder]() ---@class nvim_tree.Config.Renderer.Icons.WebDevicons.Folder ---@inlinedoc --- @@ -217,14 +216,15 @@ error("Cannot require a meta file") ---@field color? boolean +---[nvim_tree.Config.Renderer.Icons.Padding]() ---@class nvim_tree.Config.Renderer.Icons.Padding ---@inlinedoc --- ----icon and filename. +---Between icon and filename. ---(default: ` `) ---@field icon? string --- ----folder arrow icon and file/folder icon. +---Between folder arrow icon and file/folder icon. ---(default: ` `) ---@field folder_arrow? string @@ -309,6 +309,7 @@ error("Cannot require a meta file") ---Git status on files and directories. ---@field git? nvim_tree.Config.Renderer.Icons.Glyphs.Git +---[nvim_tree.Config.Renderer.Icons.Glyphs.Folder]() ---@class nvim_tree.Config.Renderer.Icons.Glyphs.Folder ---@inlinedoc ---(default: left arrow) @@ -328,6 +329,7 @@ error("Cannot require a meta file") ---(default: `` ) ---@field symlink_open? string +---[nvim_tree.Config.Renderer.Icons.Glyphs.Git]() ---@class nvim_tree.Config.Renderer.Icons.Glyphs.Git ---@inlinedoc ---(default: `✗` ) From fd4c17d6ec85f3a73ff43cfab722073377a77498 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Mon, 12 Jan 2026 17:23:34 +1100 Subject: [PATCH 049/170] docs(#2934): refer to nvim in help, not neovim, as this trips the lintdoc spell checker --- doc/nvim-tree-lua.txt | 25 ++++++++++++---------- lua/nvim-tree/_meta/config/actions.lua | 2 +- lua/nvim-tree/_meta/config/sort.lua | 2 +- lua/nvim-tree/_meta/config/system_open.lua | 4 +++- 4 files changed, 19 insertions(+), 14 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 4f59786e033..81828a1d887 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -1,4 +1,4 @@ -*nvim-tree* A File Explorer For Neovim Written In Lua +*nvim-tree* A File Explorer For nvim Author: Yazdani Kiyan @@ -106,7 +106,7 @@ Git Integration Requirements - This file explorer requires `neovim >= 0.9.0` + This file explorer requires nvim >= 0.9 ============================================================================== 2. QUICKSTART *nvim-tree-quickstart* @@ -1239,18 +1239,18 @@ Takes the `BufEnter` event as an argument. see |autocmd-events| Open a file or directory in your preferred application. -|vim.ui.open()| was introduced in neovim 0.10 and is the default. +|vim.ui.open()| was introduced in nvim 0.10 and is the default. -Once nvim-tree minimum neovim version is updated to 0.10, these options will +Once nvim-tree minimum nvim version is updated to 0.10, these options will no longer be necessary and will be removed. *nvim-tree.system_open.cmd* The open command itself. Type: `string`, Default: `""` -neovim >= 0.10 defaults to |vim.ui.open()| +nvim >= 0.10 defaults to |vim.ui.open()| -neovim < 0.10 defaults to: +nvim < 0.10 defaults to: UNIX: `"xdg-open"` macOS: `"open"` Windows: `"cmd"` @@ -1498,7 +1498,7 @@ Configuration for |nvim-tree-api.tree.expand_all()| and *nvim-tree.actions.expand_all.max_folder_discovery* Limit the number of folders being explored when expanding every folders. - Avoids hanging neovim when running this action on very large folders. + Avoids hanging nvim when running this action on very large folders. Type: `number`, Default: `300` *nvim-tree.actions.expand_all.exclude* @@ -3077,7 +3077,7 @@ Windows WSL and PowerShell ============================================================================== 13. NETRW *nvim-tree-netrw* -|netrw| is a standard neovim plugin that is enabled by default. It provides, +|netrw| is a standard nvim plugin that is enabled by default. It provides, amongst other functionality, a file/directory browser. It interferes with nvim-tree and the intended user experience is nvim-tree @@ -3557,7 +3557,7 @@ Class: Config.Sort *nvim-tree-config-sort* • `suffix` uses the last e.g. `foo.tar.gz` -> `.gz` • `filetype` |filetype| - {sorter} may be a function that is passed a list of |nvim_tree.api.Node| + {sorter} may be a function that is passed a list of `nvim_tree.api.Node` to be sorted in place e.g. >lua ---Sort by name length @@ -3962,13 +3962,16 @@ Class: Config.SystemOpen *nvim-tree-config-system-open* *nvim_tree.Config.SystemOpen* Open files or directories via the OS. - Neovim: + nvim: • `>=` 0.10 uses |vim.ui.open()| unless {cmd} is specified • `<` 0.10 calls external {cmd}: • UNIX: `xdg-open` • macOS: `open` • Windows: `cmd` + Once nvim-tree minimum nvim version is updated to 0.10, these options will + no longer be necessary and will be removed. + Fields: ~ • {cmd}? (`string`, default: `xdg-open`, `open` or `cmd`) The open command itself @@ -4203,7 +4206,7 @@ Class: Config.Actions *nvim-tree-config-actions* Fields: ~ • {max_folder_discovery}? (`integer`, default: `300`) Limit the number of folders being explored when expanding - every folders. Avoids hanging neovim when + every folder. Avoids hanging nvim when running this action on very large folders. • {exclude}? (`string[]`, default: `{}`) A list of directories that should not be expanded diff --git a/lua/nvim-tree/_meta/config/actions.lua b/lua/nvim-tree/_meta/config/actions.lua index 3ce1f64af04..09568bd1560 100644 --- a/lua/nvim-tree/_meta/config/actions.lua +++ b/lua/nvim-tree/_meta/config/actions.lua @@ -42,7 +42,7 @@ error("Cannot require a meta file") ---Configure [nvim-tree-api.tree.expand_all()] and [nvim-tree-api.node.expand()] ---@class nvim_tree.Config.Actions.ExpandAll --- ----Limit the number of folders being explored when expanding every folders. Avoids hanging neovim when running this action on very large folders. +---Limit the number of folders being explored when expanding every folder. Avoids hanging nvim when running this action on very large folders. ---(default: `300`) ---@field max_folder_discovery? integer --- diff --git a/lua/nvim-tree/_meta/config/sort.lua b/lua/nvim-tree/_meta/config/sort.lua index 2a0e0f7bc86..e80e16c0c46 100644 --- a/lua/nvim-tree/_meta/config/sort.lua +++ b/lua/nvim-tree/_meta/config/sort.lua @@ -13,7 +13,7 @@ error("Cannot require a meta file") ---- `suffix` uses the last e.g. `foo.tar.gz` -> `.gz` ---- `filetype` [filetype] --- ----{sorter} may be a function that is passed a list of [nvim_tree.api.Node] to be sorted in place e.g. +---{sorter} may be a function that is passed a list of `nvim_tree.api.Node` to be sorted in place e.g. ---```lua --- ------Sort by name length diff --git a/lua/nvim-tree/_meta/config/system_open.lua b/lua/nvim-tree/_meta/config/system_open.lua index 6feff7a0117..74f9c7446ce 100644 --- a/lua/nvim-tree/_meta/config/system_open.lua +++ b/lua/nvim-tree/_meta/config/system_open.lua @@ -3,13 +3,15 @@ error("Cannot require a meta file") ---Open files or directories via the OS. --- ----Neovim: +---nvim: ---- `>=` 0.10 uses [vim.ui.open()] unless {cmd} is specified ---- `<` 0.10 calls external {cmd}: --- - UNIX: `xdg-open` --- - macOS: `open` --- - Windows: `cmd` --- +---Once nvim-tree minimum nvim version is updated to 0.10, these options will no longer be necessary and will be removed. +--- ---@class nvim_tree.Config.SystemOpen --- ---The open command itself From e7ae9f006f729ac860e39f685c8b58bc9c8bf1fa Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Mon, 12 Jan 2026 17:39:27 +1100 Subject: [PATCH 050/170] docs(#2934): fix broken links --- doc/nvim-tree-lua.txt | 83 +++++++++---------- lua/nvim-tree/_meta/config.lua | 4 +- lua/nvim-tree/_meta/config/diagnostics.lua | 2 +- lua/nvim-tree/_meta/config/filters.lua | 2 +- lua/nvim-tree/_meta/config/git.lua | 2 +- lua/nvim-tree/_meta/config/modified.lua | 8 +- lua/nvim-tree/_meta/config/renderer.lua | 30 +++---- .../_meta/config/update_focused_file.lua | 2 +- 8 files changed, 63 insertions(+), 70 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 81828a1d887..cc698eec110 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3482,15 +3482,13 @@ Class: Config *nvim-tree-config* reinstate this one when formatting is done #2934 --@field hijack_unnamed_buffer_when_opening? boolean - • {root_dirs}? (`string[]`) Preferred root directories. Only - relevant when - |nvim_tree.Config.UpdateFocusedFile| - {update_root} is `true` + • {root_dirs}? (`string[]`) Preferred root directories. + Requires + |nvim_tree.Config.UpdateFocusedFile.UpdateRoot|. • {prefer_startup_root}? (`boolean`, default: `false`) Prefer startup root directory when updating root directory - of the tree. Only relevant when - |nvim_tree.Config.UpdateFocusedFile| - {update_root} is `true` + of the tree. Requires + |nvim_tree.Config.UpdateFocusedFile.UpdateRoot|. • {sync_root_with_cwd}? (`boolean`, default: `false`) Changes the tree root directory on |DirChanged| and refreshes the tree. @@ -3727,21 +3725,19 @@ Class: Config.Renderer *nvim-tree-config-renderer* |nvim-tree-decorators|. • {highlight_git}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) Git status: `NvimTreeGit*HL`. Requires - |nvim_tree.Config.Git| {enable}. + |nvim_tree.Config.Git|. • {highlight_opened_files}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) |bufloaded()| files: `NvimTreeOpenedHL`. • {highlight_hidden}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) Hidden (dotfiles): `NvimTreeHiddenFileHL`. • {highlight_modified}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) Modified files: `NvimTreeModifiedFile`. - Requires |nvim_tree.Config.Modified| - {enable}. + Requires |nvim_tree.Config.Modified|. • {highlight_bookmarks}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) Bookmarked: `NvimTreeBookmarkHL`. • {highlight_diagnostics}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) Diagnostic status: `NvimTreeDiagnostic*HL`. - Requires |nvim_tree.Config.Diagnostics| - {enable}. + Requires |nvim_tree.Config.Diagnostics|. • {highlight_clipboard}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `name`) Copied: `NvimTreeCopiedHL`, cut: `NvimTreeCutHL`. @@ -3769,11 +3765,9 @@ Class: Config.Renderer *nvim-tree-config-renderer* • {git_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`) (default: `before`) • {diagnostics_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`, default: `signcolumn`) - Requires |nvim_tree.Config.Diagnostics| - {enable}. + Requires |nvim_tree.Config.Diagnostics|. • {modified_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`, default: `after`) - Requires |nvim_tree.Config.Modified| - {enable}. + Requires |nvim_tree.Config.Modified|. • {hidden_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`) (default: `after`) • {bookmarks_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`) @@ -3801,13 +3795,13 @@ Class: Config.Renderer *nvim-tree-config-renderer* Fields: ~ • {default}? (`string`, default: `` ) Files, overridden by - |nvim_tree.Config.Renderer.Icons| {web_devicons} + |nvim_tree.Config.Renderer.Icons.WebDevicons|. • {symlink}? (`string`) (default: `` ) • {bookmark}? (`string`) (default: `󰆤` ) • {modified}? (`string`) (default: `●` ) • {hidden}? (`string`) (default: `󰜌` ) - • {folder}? (`table`) Overridden by |nvim_tree.Config.Renderer.Icons| - {web_devicons} *nvim_tree.Config.Renderer.Icons.Glyphs.Folder* + • {folder}? (`table`) Overridden by + |nvim_tree.Config.Renderer.Icons.WebDevicons|. *nvim_tree.Config.Renderer.Icons.Glyphs.Folder* • {arrow_closed}? (`string`) (default: left arrow) • {arrow_open}? (`string`) (default: down arrow) • {default}? (`string`) (default: `` ) @@ -3843,24 +3837,23 @@ Class: Config.Renderer *nvim-tree-config-renderer* • {folder}? (`boolean`, default: `true`) Before folder name. • {folder_arrow}? (`boolean`, default: `true`) Show a small arrow before the folder node. Arrow will be a part of the - node when using |nvim_tree.Config.Renderer| - {indent_markers}. - • {git}? (`boolean`, default: `true`) Icons: - |nvim_tree.Config.Renderer.Icons.Glyphs.Git|. - Location: |nvim_tree.Config.Renderer.Icons| - {git_placement}. Requires |nvim_tree.Config.Git| - {enable}. + node when using + |nvim_tree.Config.Renderer.IndentMarkers|. + • {git}? (`boolean`, default: `true`) Location: + |nvim_tree.Config.Renderer.Icons| {git_placement}. + Icons: |nvim_tree.Config.Renderer.Icons.Glyphs.Git|. + Requires |nvim_tree.Config.Git|. • {modified}? (`boolean`, default: `true`) Location: |nvim_tree.Config.Renderer.Icons| {modified_placement}. Requires - |nvim_tree.Config.Modified| {enable}. + |nvim_tree.Config.Modified|. • {hidden}? (`boolean`, default: `false`) Location: |nvim_tree.Config.Renderer.Icons| {hidden_placement}. - • {diagnostics}? (`boolean`, default: `true`) Icons: - |nvim_tree.Config.Diagnostics.Icons| Location: + • {diagnostics}? (`boolean`, default: `true`) Location: |nvim_tree.Config.Renderer.Icons| - {diagnostics_placement}. Requires - |nvim_tree.Config.Diagnostics| {enable}. + {diagnostics_placement}. Icons: + |nvim_tree.Config.Diagnostics.Icons|. Requires + |nvim_tree.Config.Diagnostics|. • {bookmarks}? (`boolean`, default: `true`) Location: |nvim_tree.Config.Renderer.Icons| {bookmarks_placement}. @@ -3874,15 +3867,15 @@ Class: Config.Renderer *nvim-tree-config-renderer* • {file}? (`table`) *nvim_tree.Config.Renderer.Icons.WebDevicons.File* • {enable}? (`boolean`, default: `true`) Show icons for - files, overrides |nvim_tree.Config.Renderer.Icons.Glyphs| - {default}. + files, overrides + |nvim_tree.Config.Renderer.Icons.Glyphs.Git|. • {color}? (`boolean`, default: `true`) Apply colours to files, overrides `NvimTreeFileIcon`. • {folder}? (`table`) *nvim_tree.Config.Renderer.Icons.WebDevicons.Folder* • {enable}? (`boolean`, default: `false`) Show icons for directories, overrides - |nvim_tree.Config.Renderer.Icons.Glyphs| {folder}. + |nvim_tree.Config.Renderer.Icons.Glyphs.Folder|. • {color}? (`boolean`, default: `true`) Apply colors to directories, overrides `NvimTree*FolderName`. @@ -3945,7 +3938,7 @@ Class: Config.UpdateFocusedFile *nvim-tree-config-update-focused-file* Prefers vim's cwd and |nvim_tree.Config| {root_dirs}, falling back to the directory containing the file. - Only relevant when |nvim_tree.Config.UpdateFocusedFile| {enable} is `true` + Requires |nvim_tree.Config.UpdateFocusedFile| Fields: ~ • {enable}? (`boolean`) (default: `false`) @@ -4002,8 +3995,8 @@ Class: Config.Git *nvim-tree-config-git* of children when directory itself has no status icon • {show_on_open_dirs}? (`boolean`, default: `true`) Show status icons - of children on directories that are open. Only - relevant when {show_on_dirs} is `true`. + of children on directories that are open. + Requires {show_on_dirs}. • {disable_for_dirs}? (`string[]|(fun(path: string): boolean)`, default: `{}`) Disable for top level paths. • {timeout}? (`integer`, default: `400`) `git` processes @@ -4026,8 +4019,8 @@ Class: Config.Diagnostics *nvim-tree-config-diagnostics* • {show_on_dirs}? (`boolean`, default: `false`) Show diagnostic icons on parent directories. • {show_on_open_dirs}? (`boolean`, default: `true`) Show diagnostics - icons on directories that are open. Only - relevant when {show_on_dirs} is `true`. + icons on directories that are open. Requires + {show_on_dirs}. • {diagnostic_opts}? (`boolean`, default: `false`) Global |vim.diagnostic.Opts| overrides {severity} and {icons} @@ -4050,9 +4043,9 @@ Class: Config.Modified *nvim-tree-config-modified* *nvim_tree.Config.Modified* Indicate which files have unsaved modification. To see modified status in - the tree you will need to set: - • |nvim_tree.Config.Renderer.Icons.Show| {modified} to `true` OR - • |nvim_tree.Config.Renderer| {highlight_modified} to `true` + the tree you will need: + • |nvim_tree.Config.Renderer.Icons.Show| {modified} OR + • |nvim_tree.Config.Renderer| {highlight_modified} Fields: ~ • {enable}? (`boolean`) (default: `false`) @@ -4060,8 +4053,8 @@ Class: Config.Modified *nvim-tree-config-modified* indication on directory whose children are modified. • {show_on_open_dirs}? (`boolean`, default: `false`) Show modified - indication on open directories. Only relevant - when {show_on_dirs} is `true`. + indication on open directories. Requires + {show_on_dirs}. @@ -4077,7 +4070,7 @@ Filters can be set at startup and toggled live via API with default keymappings. `I` {git_ignored} |nvim-tree-api.tree.toggle_gitignore_filter()| Ignore files based on `.gitignore`. - Requires |nvim_tree.Config.Git| {enable} + Requires |nvim_tree.Config.Git| `H` {dotfiles} |nvim-tree-api.tree.toggle_hidden_filter()| Filter dotfiles: files starting with a `.` diff --git a/lua/nvim-tree/_meta/config.lua b/lua/nvim-tree/_meta/config.lua index 1e482795de4..ca967d620e1 100644 --- a/lua/nvim-tree/_meta/config.lua +++ b/lua/nvim-tree/_meta/config.lua @@ -31,10 +31,10 @@ error("Cannot require a meta file") -----@field hijack_unnamed_buffer_when_opening? boolean ---@field hubwo? boolean --- ----Preferred root directories. Only relevant when [nvim_tree.Config.UpdateFocusedFile] {update_root} is `true` +---Preferred root directories. Requires [nvim_tree.Config.UpdateFocusedFile.UpdateRoot]. ---@field root_dirs? string[] --- ----Prefer startup root directory when updating root directory of the tree. Only relevant when [nvim_tree.Config.UpdateFocusedFile] {update_root} is `true` +---Prefer startup root directory when updating root directory of the tree. Requires [nvim_tree.Config.UpdateFocusedFile.UpdateRoot]. ---(default: `false`) ---@field prefer_startup_root? boolean --- diff --git a/lua/nvim-tree/_meta/config/diagnostics.lua b/lua/nvim-tree/_meta/config/diagnostics.lua index 37357d17183..8c119714dab 100644 --- a/lua/nvim-tree/_meta/config/diagnostics.lua +++ b/lua/nvim-tree/_meta/config/diagnostics.lua @@ -16,7 +16,7 @@ error("Cannot require a meta file") ---(default: `false`) ---@field show_on_dirs? boolean --- ----Show diagnostics icons on directories that are open. Only relevant when {show_on_dirs} is `true`. +---Show diagnostics icons on directories that are open. Requires {show_on_dirs}. ---(default: `true`) ---@field show_on_open_dirs? boolean --- diff --git a/lua/nvim-tree/_meta/config/filters.lua b/lua/nvim-tree/_meta/config/filters.lua index 1d028495e56..e1869db9b22 100644 --- a/lua/nvim-tree/_meta/config/filters.lua +++ b/lua/nvim-tree/_meta/config/filters.lua @@ -11,7 +11,7 @@ error("Cannot require a meta file") --- ---`I` {git_ignored} |nvim-tree-api.tree.toggle_gitignore_filter()| --- Ignore files based on `.gitignore`. ---- Requires |nvim_tree.Config.Git| {enable} +--- Requires |nvim_tree.Config.Git| --- ---`H` {dotfiles} |nvim-tree-api.tree.toggle_hidden_filter()| --- Filter dotfiles: files starting with a `.` diff --git a/lua/nvim-tree/_meta/config/git.lua b/lua/nvim-tree/_meta/config/git.lua index 121a13137c9..cb049a627bd 100644 --- a/lua/nvim-tree/_meta/config/git.lua +++ b/lua/nvim-tree/_meta/config/git.lua @@ -18,7 +18,7 @@ error("Cannot require a meta file") ---(default: `true`) ---@field show_on_dirs? boolean --- ----Show status icons of children on directories that are open. Only relevant when {show_on_dirs} is `true`. +---Show status icons of children on directories that are open. Requires {show_on_dirs}. ---(default: `true`) ---@field show_on_open_dirs? boolean --- diff --git a/lua/nvim-tree/_meta/config/modified.lua b/lua/nvim-tree/_meta/config/modified.lua index b9aa02b223c..7e0f00b91d2 100644 --- a/lua/nvim-tree/_meta/config/modified.lua +++ b/lua/nvim-tree/_meta/config/modified.lua @@ -2,9 +2,9 @@ error("Cannot require a meta file") ---Indicate which files have unsaved modification. ----To see modified status in the tree you will need to set: ---- - [nvim_tree.Config.Renderer.Icons.Show] {modified} to `true` OR ---- - [nvim_tree.Config.Renderer] {highlight_modified} to `true` +---To see modified status in the tree you will need: +--- - [nvim_tree.Config.Renderer.Icons.Show] {modified} OR +--- - [nvim_tree.Config.Renderer] {highlight_modified} ---@class nvim_tree.Config.Modified --- ---(default: `false`) @@ -14,6 +14,6 @@ error("Cannot require a meta file") ---(default: `true`) ---@field show_on_dirs? boolean --- ----Show modified indication on open directories. Only relevant when {show_on_dirs} is `true`. +---Show modified indication on open directories. Requires {show_on_dirs}. ---(default: `false`) ---@field show_on_open_dirs? boolean diff --git a/lua/nvim-tree/_meta/config/renderer.lua b/lua/nvim-tree/_meta/config/renderer.lua index 0017bd40b37..b0e9995fd00 100644 --- a/lua/nvim-tree/_meta/config/renderer.lua +++ b/lua/nvim-tree/_meta/config/renderer.lua @@ -63,7 +63,7 @@ error("Cannot require a meta file") ---@field decorators? (string|nvim_tree.api.decorator.UserDecorator)[] --- ---Git status: `NvimTreeGit*HL`. ----Requires [nvim_tree.Config.Git] {enable}. +---Requires [nvim_tree.Config.Git]. ---(default: `none`) ---@field highlight_git? nvim_tree.Config.Renderer.HighlightPlacement --- @@ -76,7 +76,7 @@ error("Cannot require a meta file") ---@field highlight_hidden? nvim_tree.Config.Renderer.HighlightPlacement --- ---Modified files: `NvimTreeModifiedFile`. ----Requires [nvim_tree.Config.Modified] {enable}. +---Requires [nvim_tree.Config.Modified]. ---(default: `none`) ---@field highlight_modified? nvim_tree.Config.Renderer.HighlightPlacement --- @@ -85,7 +85,7 @@ error("Cannot require a meta file") ---@field highlight_bookmarks? nvim_tree.Config.Renderer.HighlightPlacement --- ---Diagnostic status: `NvimTreeDiagnostic*HL`. ----Requires [nvim_tree.Config.Diagnostics] {enable}. +---Requires [nvim_tree.Config.Diagnostics]. ---(default: `none`) ---@field highlight_diagnostics? nvim_tree.Config.Renderer.HighlightPlacement --- @@ -152,11 +152,11 @@ error("Cannot require a meta file") ---(default: `before`) ---@field git_placement? nvim_tree.Config.Renderer.Icons.Placement --- ----Requires [nvim_tree.Config.Diagnostics] {enable}. +---Requires [nvim_tree.Config.Diagnostics]. ---(default: `signcolumn`) ---@field diagnostics_placement? nvim_tree.Config.Renderer.Icons.Placement --- ----Requires [nvim_tree.Config.Modified] {enable}. +---Requires [nvim_tree.Config.Modified]. ---(default: `after`) ---@field modified_placement? nvim_tree.Config.Renderer.Icons.Placement --- @@ -194,7 +194,7 @@ error("Cannot require a meta file") ---@class nvim_tree.Config.Renderer.Icons.WebDevicons.File ---@inlinedoc --- ----Show icons for files, overrides [nvim_tree.Config.Renderer.Icons.Glyphs] {default}. +---Show icons for files, overrides [nvim_tree.Config.Renderer.Icons.Glyphs.Git]. ---(default: `true`) ---@field enable? boolean --- @@ -207,7 +207,7 @@ error("Cannot require a meta file") ---@class nvim_tree.Config.Renderer.Icons.WebDevicons.Folder ---@inlinedoc --- ----Show icons for directories, overrides [nvim_tree.Config.Renderer.Icons.Glyphs] {folder}. +---Show icons for directories, overrides [nvim_tree.Config.Renderer.Icons.Glyphs.Folder]. ---(default: `false`) ---@field enable? boolean --- @@ -250,18 +250,18 @@ error("Cannot require a meta file") ---(default: `true`) ---@field folder? boolean --- ----Show a small arrow before the folder node. Arrow will be a part of the node when using [nvim_tree.Config.Renderer] {indent_markers}. +---Show a small arrow before the folder node. Arrow will be a part of the node when using [nvim_tree.Config.Renderer.IndentMarkers]. ---(default: `true`) ---@field folder_arrow? boolean --- ----Icons: [nvim_tree.Config.Renderer.Icons.Glyphs.Git]. ---Location: [nvim_tree.Config.Renderer.Icons] {git_placement}. ----Requires [nvim_tree.Config.Git] {enable}. +---Icons: [nvim_tree.Config.Renderer.Icons.Glyphs.Git]. +---Requires [nvim_tree.Config.Git]. ---(default: `true`) ---@field git? boolean --- ---Location: [nvim_tree.Config.Renderer.Icons] {modified_placement}. ----Requires [nvim_tree.Config.Modified] {enable}. +---Requires [nvim_tree.Config.Modified]. ---(default: `true`) ---@field modified? boolean --- @@ -269,9 +269,9 @@ error("Cannot require a meta file") ---(default: `false`) ---@field hidden? boolean --- ----Icons: [nvim_tree.Config.Diagnostics.Icons] ---Location: [nvim_tree.Config.Renderer.Icons] {diagnostics_placement}. ----Requires [nvim_tree.Config.Diagnostics] {enable}. +---Icons: [nvim_tree.Config.Diagnostics.Icons]. +---Requires [nvim_tree.Config.Diagnostics]. ---(default: `true`) ---@field diagnostics? boolean --- @@ -287,7 +287,7 @@ error("Cannot require a meta file") ---- [nvim_tree.Config.Renderer.IndentMarkers.Icons] ---@class nvim_tree.Config.Renderer.Icons.Glyphs --- ----Files, overridden by [nvim_tree.Config.Renderer.Icons] {web_devicons} +---Files, overridden by [nvim_tree.Config.Renderer.Icons.WebDevicons]. ---(default: `` ) ---@field default? string --- @@ -303,7 +303,7 @@ error("Cannot require a meta file") ---(default: `󰜌` ) ---@field hidden? string --- ----Overridden by [nvim_tree.Config.Renderer.Icons] {web_devicons} +---Overridden by [nvim_tree.Config.Renderer.Icons.WebDevicons]. ---@field folder? nvim_tree.Config.Renderer.Icons.Glyphs.Folder --- ---Git status on files and directories. diff --git a/lua/nvim-tree/_meta/config/update_focused_file.lua b/lua/nvim-tree/_meta/config/update_focused_file.lua index 33a26b7d840..2da913d9dd0 100644 --- a/lua/nvim-tree/_meta/config/update_focused_file.lua +++ b/lua/nvim-tree/_meta/config/update_focused_file.lua @@ -20,7 +20,7 @@ error("Cannot require a meta file") --- ---Prefers vim's cwd and [nvim_tree.Config] {root_dirs}, falling back to the directory containing the file. --- ----Only relevant when [nvim_tree.Config.UpdateFocusedFile] {enable} is `true` +---Requires [nvim_tree.Config.UpdateFocusedFile] --- ---@class nvim_tree.Config.UpdateFocusedFile.UpdateRoot --- From 2fcf8a07087d8964223b672c74991f96fafe16a4 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Mon, 12 Jan 2026 18:10:26 +1100 Subject: [PATCH 051/170] docs(#2934): add lintdoc.sh, fix some branding spelling --- doc/nvim-tree-lua.txt | 26 +++++++++--------- lua/nvim-tree/_meta/config/actions.lua | 2 +- lua/nvim-tree/_meta/config/system_open.lua | 4 +-- scripts/gen_vimdoc.sh | 16 ++++++++--- scripts/lintdoc.sh | 32 ++++++++++++++++++++++ 5 files changed, 60 insertions(+), 20 deletions(-) create mode 100755 scripts/lintdoc.sh diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index cc698eec110..256a8ea4ddc 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -1,4 +1,4 @@ -*nvim-tree* A File Explorer For nvim +*nvim-tree* A File Explorer For Nvim Author: Yazdani Kiyan @@ -106,7 +106,7 @@ Git Integration Requirements - This file explorer requires nvim >= 0.9 + This file explorer requires Nvim >= 0.9 ============================================================================== 2. QUICKSTART *nvim-tree-quickstart* @@ -365,7 +365,7 @@ See |nvim-tree-highlight| for details. 4. SETUP *nvim-tree-setup* You must run setup() function once to initialise nvim-tree. It may be called -again to apply a change in configuration without restarting nvim. +again to apply a change in configuration without restarting Nvim. setup() function takes one optional argument: configuration table. If omitted nvim-tree will be initialised with default configuration. @@ -1239,18 +1239,18 @@ Takes the `BufEnter` event as an argument. see |autocmd-events| Open a file or directory in your preferred application. -|vim.ui.open()| was introduced in nvim 0.10 and is the default. +|vim.ui.open()| was introduced in Nvim 0.10 and is the default. -Once nvim-tree minimum nvim version is updated to 0.10, these options will +Once nvim-tree minimum Nvim version is updated to 0.10, these options will no longer be necessary and will be removed. *nvim-tree.system_open.cmd* The open command itself. Type: `string`, Default: `""` -nvim >= 0.10 defaults to |vim.ui.open()| +Nvim >= 0.10 defaults to |vim.ui.open()| -nvim < 0.10 defaults to: +Nvim < 0.10 defaults to: UNIX: `"xdg-open"` macOS: `"open"` Windows: `"cmd"` @@ -1498,7 +1498,7 @@ Configuration for |nvim-tree-api.tree.expand_all()| and *nvim-tree.actions.expand_all.max_folder_discovery* Limit the number of folders being explored when expanding every folders. - Avoids hanging nvim when running this action on very large folders. + Avoids hanging Nvim when running this action on very large folders. Type: `number`, Default: `300` *nvim-tree.actions.expand_all.exclude* @@ -3071,13 +3071,13 @@ Contents of `my-decorator.lua`: Windows WSL and PowerShell - Trash is synchronized - Executable file detection is disabled as this is non-performant and can - freeze nvim + freeze Nvim - Some filesystem watcher error related to permissions will not be reported ============================================================================== 13. NETRW *nvim-tree-netrw* -|netrw| is a standard nvim plugin that is enabled by default. It provides, +|netrw| is a standard Nvim plugin that is enabled by default. It provides, amongst other functionality, a file/directory browser. It interferes with nvim-tree and the intended user experience is nvim-tree @@ -3955,14 +3955,14 @@ Class: Config.SystemOpen *nvim-tree-config-system-open* *nvim_tree.Config.SystemOpen* Open files or directories via the OS. - nvim: + Nvim: • `>=` 0.10 uses |vim.ui.open()| unless {cmd} is specified • `<` 0.10 calls external {cmd}: • UNIX: `xdg-open` • macOS: `open` • Windows: `cmd` - Once nvim-tree minimum nvim version is updated to 0.10, these options will + Once nvim-tree minimum Nvim version is updated to 0.10, these options will no longer be necessary and will be removed. Fields: ~ @@ -4199,7 +4199,7 @@ Class: Config.Actions *nvim-tree-config-actions* Fields: ~ • {max_folder_discovery}? (`integer`, default: `300`) Limit the number of folders being explored when expanding - every folder. Avoids hanging nvim when + every folder. Avoids hanging Nvim when running this action on very large folders. • {exclude}? (`string[]`, default: `{}`) A list of directories that should not be expanded diff --git a/lua/nvim-tree/_meta/config/actions.lua b/lua/nvim-tree/_meta/config/actions.lua index 09568bd1560..8504824e750 100644 --- a/lua/nvim-tree/_meta/config/actions.lua +++ b/lua/nvim-tree/_meta/config/actions.lua @@ -42,7 +42,7 @@ error("Cannot require a meta file") ---Configure [nvim-tree-api.tree.expand_all()] and [nvim-tree-api.node.expand()] ---@class nvim_tree.Config.Actions.ExpandAll --- ----Limit the number of folders being explored when expanding every folder. Avoids hanging nvim when running this action on very large folders. +---Limit the number of folders being explored when expanding every folder. Avoids hanging Nvim when running this action on very large folders. ---(default: `300`) ---@field max_folder_discovery? integer --- diff --git a/lua/nvim-tree/_meta/config/system_open.lua b/lua/nvim-tree/_meta/config/system_open.lua index 74f9c7446ce..648b3863a83 100644 --- a/lua/nvim-tree/_meta/config/system_open.lua +++ b/lua/nvim-tree/_meta/config/system_open.lua @@ -3,14 +3,14 @@ error("Cannot require a meta file") ---Open files or directories via the OS. --- ----nvim: +---Nvim: ---- `>=` 0.10 uses [vim.ui.open()] unless {cmd} is specified ---- `<` 0.10 calls external {cmd}: --- - UNIX: `xdg-open` --- - macOS: `open` --- - Windows: `cmd` --- ----Once nvim-tree minimum nvim version is updated to 0.10, these options will no longer be necessary and will be removed. +---Once nvim-tree minimum Nvim version is updated to 0.10, these options will no longer be necessary and will be removed. --- ---@class nvim_tree.Config.SystemOpen --- diff --git a/scripts/gen_vimdoc.sh b/scripts/gen_vimdoc.sh index fa0d28b4265..03ebf5d89f8 100755 --- a/scripts/gen_vimdoc.sh +++ b/scripts/gen_vimdoc.sh @@ -1,9 +1,17 @@ #!/usr/bin/env sh +# Wrapper around nvim help generator gen_vimdoc.lua, run as part of nvim's make doc target. +# +# Doesn't require nvim to have been built. +# +# Shims our moudules into gen_vimdoc_config.lua, replacing nvim's. +# +# There are some hardcoded expectations which we work around as commented. + set -e -if [ ! -d "${NEOVIM_SRC}" ]; then - echo "\$NEOVIM_SRC not set" +if [ ! -d "${NVIM_SRC}" ]; then + echo "\$NVIM_SRC not set" exit 1 fi @@ -12,11 +20,11 @@ mkdir -pv runtime/doc cp -v "doc/nvim-tree-lua.txt" runtime/doc # modify gen_vimdoc.lua to use our config -cp -v "${NEOVIM_SRC}/src/gen/gen_vimdoc.lua" gen_vimdoc.lua +cp -v "${NVIM_SRC}/src/gen/gen_vimdoc.lua" gen_vimdoc.lua sed -i -E 's/spairs\(config\)/spairs\(require("gen_vimdoc_config")\)/g' gen_vimdoc.lua # use luacacts etc. from neovim src as well as our specific config -export LUA_PATH="${NEOVIM_SRC}/src/?.lua;scripts/?.lua" +export LUA_PATH="${NVIM_SRC}/src/?.lua;scripts/?.lua" # generate ./gen_vimdoc.lua diff --git a/scripts/lintdoc.sh b/scripts/lintdoc.sh new file mode 100755 index 00000000000..978f2d79b54 --- /dev/null +++ b/scripts/lintdoc.sh @@ -0,0 +1,32 @@ +#!/usr/bin/env sh + +# Wrapper around nvim help linter lintdoc.lua, run as part of nvim's make lintdoc target. +# +# Requires nvim to have been built. +# +# Desired: +# - tags valid +# - links valid +# Also: +# - brand spelling, notably Nvim and Lua +# +# There are some hardcoded expectations which we work around as commented. + +set -e + +if [ ! -d "${NVIM_SRC}" ]; then + echo "\$NVIM_SRC not set" + exit 1 +fi + +# runtime/doc in the nvim source is practically hardcoded, copy our help in +cp -v "doc/nvim-tree-lua.txt" "${NVIM_SRC}/runtime/doc" + +# run from within nvim source +cd "${NVIM_SRC}" + +# make nvim +make + +# execute the lint +VIMRUNTIME=runtime scripts/lintdoc.lua From 316f98ba0ed3fcc0f0293e95af19df9b4065e96f Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 13 Jan 2026 10:30:22 +1100 Subject: [PATCH 052/170] docs(#2934): update old config links --- doc/nvim-tree-lua.txt | 176 +++++++++++++++++++++--------------------- 1 file changed, 88 insertions(+), 88 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 256a8ea4ddc..3dff955d95e 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -13,13 +13,13 @@ CONTENTS 2.4 Quickstart: Highlight |nvim-tree-quickstart-highlight| 3. Commands |nvim-tree-commands| 4. Setup |nvim-tree-setup| - 5. Opts |nvim-tree-opts| + 5. Opts |nvim_tree.Config| 5.1 Opts: Sort |nvim-tree-opts-sort| 5.2 Opts: View |nvim-tree-opts-view| - 5.3 Opts: Renderer |nvim-tree-opts-renderer| + 5.3 Opts: Renderer |nvim_tree.Config.Renderer| 5.4 Opts: Hijack Directories |nvim-tree-opts-hijack-directories| - 5.5 Opts: Update Focused File |nvim-tree-opts-update-focused-file| - 5.6 Opts: System Open |nvim-tree-opts-system-open| + 5.5 Opts: Update Focused File |nvim_tree.Config.UpdateFocusedFile| + 5.6 Opts: System Open |nvim_tree.Config.SystemOpen| 5.7 Opts: Git |nvim-tree-opts-git| 5.8 Opts: Diagnostics |nvim-tree-opts-diagnostics| 5.9 Opts: Modified |nvim-tree-opts-modified| @@ -27,7 +27,7 @@ CONTENTS 5.11 Opts: Live Filter |nvim-tree-opts-live-filter| 5.12 Opts: Filesystem Watchers |nvim-tree-opts-filesystem-watchers| 5.13 Opts: Actions |nvim-tree-opts-actions| - 5.14 Opts: Trash |nvim-tree-opts-trash| + 5.14 Opts: Trash |nvim_tree.Config.Trash| 5.15 Opts: Tab |nvim-tree-opts-tab| 5.16 Opts: Notify |nvim-tree-opts-notify| 5.17 Opts: Help |nvim-tree-opts-help| @@ -218,7 +218,7 @@ Show the mappings: `g?` 2.3 QUICKSTART: CUSTOM MAPPINGS *nvim-tree-quickstart-custom-mappings* |nvim-tree-mappings-default| are applied by default however you may customise -via |nvim-tree.on_attach| e.g. >lua +via |nvim_tree.Config| {on_attach} e.g. >lua local function my_on_attach(bufnr) local api = require "nvim-tree.api" @@ -376,7 +376,7 @@ the configuration. Nothing happens until the tree is first opened. Subsequent setup() calls are expensive as they tear down the world before applying configuration. -Following is the default configuration. See |nvim-tree-opts| for details. >lua +Following is the default configuration. See |nvim_tree.Config| for details. >lua require("nvim-tree").setup { -- BEGIN_DEFAULT_OPTS on_attach = "default", @@ -755,12 +755,12 @@ Can be one of `"name"`, `"case_sensitive"`, `"modification_time"`, `"extension"` end < *nvim-tree.sort.folders_first* -Sort folders before files. Has no effect when |nvim-tree.sort.sorter| is a +Sort folders before files. Has no effect when |nvim_tree.Config.Sort| {sorter} is a function. Type: `boolean`, Default: `true` *nvim-tree.sort.files_first* -Sort files before folders. Has no effect when |nvim-tree.sort.sorter| is a +Sort files before folders. Has no effect when |nvim_tree.Config.Sort| {sorter} is a function. If set to `true` it overrides |nvim-tree.sort.folders_first|. Type: `boolean`, Default: `false` @@ -1392,7 +1392,7 @@ Toggle via |nvim-tree-api.tree.toggle_hidden_filter()|, default `H` *nvim-tree.filters.git_clean* Do not show files with no git status. This will show ignored files when -|nvim-tree.filters.git_ignored| is set, as they are effectively dirty. +|nvim_tree.Config.Filters| {git_ignored} is set, as they are effectively dirty. Toggle via |nvim-tree-api.tree.toggle_git_clean_filter()|, default `C` Type: `boolean`, Default: `false` @@ -1614,7 +1614,7 @@ Configuration for syncing nvim-tree across tabs. *nvim-tree.tab.sync.ignore* List of filetypes or buffer names on new tab that will prevent - |nvim-tree.tab.sync.open| and |nvim-tree.tab.sync.close| + |nvim_tree.Config.Tab.Sync| {open} and |nvim_tree.Config.Tab.Sync| {close} Type: {string}, Default: `{}` ============================================================================== @@ -1758,7 +1758,7 @@ tree.open({opts}) *nvim-tree-api.tree.open()* overrides {current_window} • {find_file} (boolean) find the current buffer • {update_root} (boolean) requires {find_file}, see - |nvim-tree.update_focused_file.update_root| + |nvim_tree.Config.UpdateFocusedFile| {update_root} tree.toggle({opts}) *nvim-tree-api.tree.toggle()* Open or close the tree. @@ -1773,11 +1773,11 @@ tree.toggle({opts}) *nvim-tree-api.tree.toggle()* overrides {current_window} • {find_file} (boolean) find the current buffer • {update_root} (boolean) requires {find_file}, see - |nvim-tree.update_focused_file.update_root| + |nvim_tree.Config.UpdateFocusedFile| {update_root} • {focus} (boolean) focus the tree when opening, default true tree.close() *nvim-tree-api.tree.close()* - Close the tree, affecting all tabs as per |nvim-tree.tab.sync.close| + Close the tree, affecting all tabs as per |nvim_tree.Config.Tab.Sync| {close} tree.close_in_this_tab() *nvim-tree-api.tree.close_in_this_tab()* Close the tree in this tab only. @@ -1794,14 +1794,14 @@ tree.reload() *nvim-tree-api.tree.reload()* tree.resize({opts}) *nvim-tree-api.tree.resize()* Resize the tree, persisting the new size. - Resets to |nvim-tree.view.width| when no {opts} provided. + Resets to |nvim_tree.Config.View| {width} when no {opts} provided. See |:NvimTreeResize| Parameters: ~ • {opts} (table) optional parameters Options: ~ - • {width} (table) new |nvim-tree.view.width| value + • {width} (table) new |nvim_tree.Config.View| {width} value • {absolute} (number) set the width • {relative} (number) increase or decrease the width @@ -1854,7 +1854,7 @@ tree.find_file({opts}) *nvim-tree-api.tree.find_file()* • {current_window} (boolean) requires {open}, open in the current window • {winid} (number) open the tree in the specified |winid|, overrides {current_window} - • {update_root} (boolean) see |nvim-tree.update_focused_file.update_root| + • {update_root} (boolean) see |nvim_tree.Config.UpdateFocusedFile| {update_root} • {focus} (boolean) focus the tree tree.search_node() *nvim-tree-api.tree.search_node()* @@ -1883,31 +1883,31 @@ tree.expand_all({node}, {opts}) *nvim-tree-api.tree.expand_all()* *nvim-tree-api.tree.toggle_enable_filters()* tree.toggle_enable_filters() - Toggle |nvim-tree.filters.enable| all filters. + Toggle |nvim_tree.Config.Filters| {enable} all filters. *nvim-tree-api.tree.toggle_gitignore_filter()* tree.toggle_gitignore_filter() - Toggle |nvim-tree.filters.git_ignored| filter. + Toggle |nvim_tree.Config.Filters| {git_ignored} filter. *nvim-tree-api.tree.toggle_git_clean_filter()* tree.toggle_git_clean_filter() - Toggle |nvim-tree.filters.git_clean| filter. + Toggle |nvim_tree.Config.Filters| {git_clean} filter. *nvim-tree-api.tree.toggle_no_buffer_filter()* tree.toggle_no_buffer_filter() - Toggle |nvim-tree.filters.no_buffer| filter. + Toggle |nvim_tree.Config.Filters| {no_buffer} filter. *nvim-tree-api.tree.toggle_no_bookmark_filter()* tree.toggle_no_bookmark_filter() - Toggle |nvim-tree.filters.no_bookmark| filter. + Toggle |nvim_tree.Config.Filters| {no_bookmark} filter. *nvim-tree-api.tree.toggle_custom_filter()* tree.toggle_custom_filter() - Toggle |nvim-tree.filters.custom| filter. + Toggle |nvim_tree.Config.Filters| {custom} filter. *nvim-tree-api.tree.toggle_hidden_filter()* tree.toggle_hidden_filter() - Toggle |nvim-tree.filters.dotfiles| filter. + Toggle |nvim_tree.Config.Filters| {dotfiles} filter. tree.toggle_help() *nvim-tree-api.tree.toggle_help()* Toggle help view. @@ -1963,7 +1963,7 @@ fs.remove({node}) *nvim-tree-api.fs.remove()* • {node} (Node|nil) file or folder fs.trash({node}) *nvim-tree-api.fs.trash()* - Trash a file or folder as per |nvim-tree-opts-trash| + Trash a file or folder as per |nvim_tree.Config.Trash| Parameters: ~ • {node} (Node|nil) file or folder @@ -2055,7 +2055,7 @@ Parameters: ~ • {node} (Node|nil) file or folder node.open.edit({node}, {opts}) *nvim-tree-api.node.open.edit()* - File: open as per |nvim-tree.actions.open_file| + File: open as per |nvim_tree.Config.Actions.OpenFile| Folder: expand or collapse Root: change directory up @@ -2135,9 +2135,9 @@ node.open.horizontal_no_picker({node}, {opts}) *nvim-tree-api.node.open.toggle_group_empty()* node.open.toggle_group_empty({node}, {opts}) - Toggle |nvim-tree.renderer.group_empty| for a specific folder. + Toggle |nvim_tree.Config.Renderer| {group_empty} for a specific folder. Does nothing on files. - Needs |nvim-tree.renderer.group_empty| set. + Needs |nvim_tree.Config.Renderer| {group_empty} set. Parameters: ~ • {node} (Node|nil) file or folder @@ -2208,7 +2208,7 @@ node.navigate.git.next({node}) *nvim-tree-api.node.navigate.git.next()* node.navigate.git.next_recursive({node}) Alternative to |nvim-tree-api.node.navigate.git.next()| that navigates to the next file showing git status, recursively. - Needs |nvim-tree.git.show_on_dirs| set. + Needs |nvim_tree.Config.Git| {show_on_dirs} set. *nvim-tree-api.node.navigate.git.next_skip_gitignored()* node.navigate.git.next_skip_gitignored({node}) @@ -2221,7 +2221,7 @@ node.navigate.git.prev({node}) *nvim-tree-api.node.navigate.git.prev()* node.navigate.git.prev_recursive({node}) Alternative to |nvim-tree-api.node.navigate.git.prev()| that navigates to the previous file showing git status, recursively. - Needs |nvim-tree.git.show_on_dirs| set. + Needs |nvim_tree.Config.Git| {show_on_dirs} set. *nvim-tree-api.node.navigate.git.prev_skip_gitignored()* node.navigate.git.prev_skip_gitignored({node}) @@ -2235,7 +2235,7 @@ node.navigate.diagnostics.next({node}) node.navigate.diagnostics.next_recursive({node}) Alternative to |nvim-tree-api.node.navigate.diagnostics.next()| that navigates to the next file showing diagnostic status, recursively. - Needs |nvim-tree.diagnostics.show_on_dirs| set. + Needs |nvim_tree.Config.Diagnostics| {show_on_dirs} set. *nvim-tree-api.node.navigate.diagnostics.prev()* node.navigate.diagnostics.prev({node}) @@ -2245,17 +2245,17 @@ node.navigate.diagnostics.prev({node}) node.navigate.diagnostics.prev_recursive({node}) Alternative to |nvim-tree-api.node.navigate.diagnostics.prev()| that navigates to the previous file showing diagnostic status, recursively. - Needs |nvim-tree.diagnostics.show_on_dirs| set. + Needs |nvim_tree.Config.Diagnostics| {show_on_dirs} set. *nvim-tree-api.node.navigate.opened.next()* node.navigate.opened.next({node}) Navigate to the next |bufloaded()| item. - See |nvim-tree.renderer.highlight_opened_files| + See |nvim_tree.Config.Renderer| {highlight_opened_files} *nvim-tree-api.node.navigate.opened.prev()* node.navigate.opened.prev({node}) Navigate to the previous |bufloaded()| item. - See |nvim-tree.renderer.highlight_opened_files| + See |nvim_tree.Config.Renderer| {highlight_opened_files} *nvim-tree-api.node.navigate.sibling.next()* node.navigate.sibling.next({node}) @@ -2289,7 +2289,7 @@ node.run.cmd({node}) *nvim-tree-api.node.run.cmd()* of the line. node.run.system({node}) *nvim-tree-api.node.run.system()* - Execute |nvim-tree-opts-system-open| + Execute |nvim_tree.Config.SystemOpen| node.buffer.delete({node}, {opts}) *nvim-tree-api.node.buffer.delete()* Deletes node's related buffer, if one exists. @@ -2402,8 +2402,8 @@ marks.bulk.move() *nvim-tree-api.marks.bulk.move()* marks.navigate.next() *nvim-tree-api.marks.navigate.next()* Navigate to the next marked node, wraps. - Opens files as per |nvim-tree.actions.open_file| - Works best with |nvim-tree-opts-update-focused-file| enabled. + Opens files as per |nvim_tree.Config.Actions.OpenFile| + Works best with |nvim_tree.Config.UpdateFocusedFile| enabled. marks.navigate.prev() *nvim-tree-api.marks.navigate.prev()* As per |nvim-tree-api.marks.navigate.next()| @@ -2417,15 +2417,15 @@ marks.navigate.select() *nvim-tree-api.marks.navigate.select()* *nvim-tree-api.config.mappings.default_on_attach()* config.mappings.default_on_attach({bufnr}) - Set all |nvim-tree-mappings-default|. Call from your |nvim-tree.on_attach| + Set all |nvim-tree-mappings-default|. Call from your |nvim_tree.Config| {on_attach} Parameters: ~ - • {bufnr} (number) nvim-tree buffer number passed to |nvim-tree.on_attach| + • {bufnr} (number) nvim-tree buffer number passed to |nvim_tree.Config| {on_attach} *nvim-tree-api.config.mappings.get_keymap()* config.mappings.get_keymap() Retrieves all buffer local mappings for nvim-tree. - These are the mappings that are applied by |nvim-tree.on_attach|, which + These are the mappings that are applied by |nvim_tree.Config| {on_attach}, which may include default mappings. Return: ~ @@ -2463,7 +2463,7 @@ diagnostics.hi_test() *nvim-tree-api.diagnostics.hi_test()* ============================================================================== 7. MAPPINGS *nvim-tree-mappings* -Mappings are set via the |nvim-tree.on_attach| function, which is run upon +Mappings are set via the |nvim_tree.Config| {on_attach} function, which is run upon creating the nvim-tree buffer. Mappings are usually |nvim-tree-api| functions however may be your own. @@ -2525,10 +2525,10 @@ define your own function to map complex functionality e.g. >lua ============================================================================== 7.1 MAPPINGS: DEFAULT *nvim-tree-mappings-default* -In the absence of an |nvim-tree.on_attach| function, the following defaults +In the absence of an |nvim_tree.Config| {on_attach} function, the following defaults will be applied. -You are encouraged to copy these to your own |nvim-tree.on_attach| function. >lua +You are encouraged to copy these to your own |nvim_tree.Config| {on_attach} function. >lua local api = require("nvim-tree.api") @@ -2597,7 +2597,7 @@ You are encouraged to copy these to your own |nvim-tree.on_attach| function. >lu vim.keymap.set("n", "<2-RightMouse>", api.tree.change_root_to_node, opts("CD")) -- END_DEFAULT_ON_ATTACH < -Alternatively, you may apply these default mappings from your |nvim-tree.on_attach| via +Alternatively, you may apply these default mappings from your |nvim_tree.Config| {on_attach} via |nvim-tree-api.config.mappings.default_on_attach()| e.g. >lua local function my_on_attach(bufnr) @@ -2630,7 +2630,7 @@ To view the nvim-tree highlight groups run |:NvimTreeHiTest| To view all active highlight groups run `:so $VIMRUNTIME/syntax/hitest.vim` as per |:highlight| -The `*HL` groups are additive as per |nvim-tree-opts-renderer| precedence. +The `*HL` groups are additive as per |nvim_tree.Config.Renderer| precedence. Only present attributes will clobber each other. In this example a modified, opened file will have magenta text, with cyan undercurl: >vim @@ -2786,7 +2786,7 @@ See |nvim-tree-legacy-highlight| for old highlight group compatibility. allowing `"none"`, `"icon"`, `"name"` or `"all"` - `highlight_xxx` has highlight groups for both File and Folder - `highlight_xxx` is additive instead of overwriting. See - |nvim-tree-opts-renderer| for precedence. + |nvim_tree.Config.Renderer| for precedence. 2024-01-29: disambiguate default highlights sharing groups: @@ -2897,7 +2897,7 @@ e.g. handler for node renamed: >lua - Event.TreeAttachedPost Invoked after the tree's buffer has been created and mappings - have been applied: |nvim-tree-mappings| or |nvim-tree.on_attach| + have been applied: |nvim-tree-mappings| or |nvim_tree.Config| {on_attach} handler parameters: ~ {buf} `{number} `API buffer handle (buffer number) @@ -2933,7 +2933,7 @@ Example subscription: >lua 10. PROMPTS *nvim-tree-prompts* Some NvimTree actions use the builtin |vim.ui.select()| prompt API for -confirmations when the |nvim-tree.select_prompts| option is set. +confirmations when the |nvim_tree.Config| {select_prompts} option is set. The API accepts the optional `kind` key as part of the {opts} parameter, which can can be used to identify the type of prompt, to allow user side @@ -3093,7 +3093,7 @@ There are many |netrw| features beyond the file browser. If you want to keep using |netrw| without its browser features please ensure: |nvim-tree.disable_netrw| `= false` -|nvim-tree.hijack_netrw| ` = true` +|nvim_tree.Config| {hijack_netrw} ` = true` ============================================================================== 14. LEGACY *nvim-tree-legacy* @@ -3108,18 +3108,18 @@ There are no plans to remove this migration. Legacy options are translated to the current, making type and value changes as needed. -`update_cwd` |nvim-tree.sync_root_with_cwd| -`update_focused_file.update_cwd` |nvim-tree.update_focused_file.update_root| -`open_on_tab` |nvim-tree.tab.sync.open| -`ignore_buf_on_tab_change` |nvim-tree.tab.sync.ignore| -`renderer.root_folder_modifier` |nvim-tree.renderer.root_folder_label| -`update_focused_file.debounce_delay` |nvim-tree.view.debounce_delay| -`trash.require_confirm` |nvim-tree.ui.confirm.trash| -`view.adaptive_size` |nvim-tree.view.width| -`sort_by` |nvim-tree.sort.sorter| -`git.ignore` |nvim-tree.filters.git_ignored| -`renderer.icons.webdev_colors` |nvim-tree.renderer.icons.web_devicons.file.color| -`renderer.icons.padding` |nvim-tree.renderer.icons.padding.icon| +`update_cwd` |nvim_tree.Config| {sync_root_with_cwd} +`update_focused_file.update_cwd` |nvim_tree.Config.UpdateFocusedFile| {update_root} +`open_on_tab` |nvim_tree.Config.Tab.Sync| {open} +`ignore_buf_on_tab_change` |nvim_tree.Config.Tab.Sync| {ignore} +`renderer.root_folder_modifier` |nvim_tree.Config.Renderer| {root_folder_label} +`update_focused_file.debounce_delay` |nvim_tree.Config.View| {debounce_delay} +`trash.require_confirm` |nvim_tree.Config.UI.Confirm| {trash} +`view.adaptive_size` |nvim_tree.Config.View| {width} +`sort_by` |nvim_tree.Config.Sort| {sorter} +`git.ignore` |nvim_tree.Config.Filters| {git_ignored} +`renderer.icons.webdev_colors` |nvim_tree.Config.Renderer.Icons.WebDevicons.File| {color} +`renderer.icons.padding` |nvim_tree.Config.Renderer.Icons.Padding| {icon} ============================================================================== 14.2 LEGACY: HIGHLIGHT *nvim-tree-legacy-highlight* @@ -3185,7 +3185,7 @@ highlight group is not, hard linking as follows: > |nvim-tree.actions.expand_all.max_folder_discovery| |nvim-tree.actions.file_popup| |nvim-tree.actions.file_popup.open_win_config| -|nvim-tree.actions.open_file| +|nvim_tree.Config.Actions.OpenFile| |nvim-tree.actions.open_file.eject| |nvim-tree.actions.open_file.quit_on_open| |nvim-tree.actions.open_file.resize_window| @@ -3205,32 +3205,32 @@ highlight group is not, hard linking as follows: > |nvim-tree.diagnostics.severity| |nvim-tree.diagnostics.severity.max| |nvim-tree.diagnostics.severity.min| -|nvim-tree.diagnostics.show_on_dirs| +|nvim_tree.Config.Diagnostics| {show_on_dirs} |nvim-tree.diagnostics.show_on_open_dirs| |nvim-tree.disable_netrw| |nvim-tree.experimental| |nvim-tree.filesystem_watchers.debounce_delay| |nvim-tree.filesystem_watchers.enable| |nvim-tree.filesystem_watchers.ignore_dirs| -|nvim-tree.filters.custom| -|nvim-tree.filters.dotfiles| -|nvim-tree.filters.enable| +|nvim_tree.Config.Filters| {custom} +|nvim_tree.Config.Filters| {dotfiles} +|nvim_tree.Config.Filters| {enable} |nvim-tree.filters.exclude| -|nvim-tree.filters.git_clean| -|nvim-tree.filters.git_ignored| -|nvim-tree.filters.no_bookmark| -|nvim-tree.filters.no_buffer| +|nvim_tree.Config.Filters| {git_clean} +|nvim_tree.Config.Filters| {git_ignored} +|nvim_tree.Config.Filters| {no_bookmark} +|nvim_tree.Config.Filters| {no_buffer} |nvim-tree.git.cygwin_support| |nvim-tree.git.disable_for_dirs| |nvim-tree.git.enable| -|nvim-tree.git.show_on_dirs| +|nvim_tree.Config.Git| {show_on_dirs} |nvim-tree.git.show_on_open_dirs| |nvim-tree.git.timeout| |nvim-tree.help.sort_by| |nvim-tree.hijack_cursor| |nvim-tree.hijack_directories.auto_open| |nvim-tree.hijack_directories.enable| -|nvim-tree.hijack_netrw| +|nvim_tree.Config| {hijack_netrw} |nvim-tree.hijack_unnamed_buffer_when_opening| |nvim-tree.live_filter.always_show_folders| |nvim-tree.live_filter.prefix| @@ -3249,13 +3249,13 @@ highlight group is not, hard linking as follows: > |nvim-tree.modified.show_on_dirs| |nvim-tree.modified.show_on_open_dirs| |nvim-tree.notify.threshold| -|nvim-tree.on_attach| +|nvim_tree.Config| {on_attach} |nvim-tree.prefer_startup_root| |nvim-tree.reload_on_bufenter| |nvim-tree.renderer.add_trailing| |nvim-tree.renderer.decorators| |nvim-tree.renderer.full_name| -|nvim-tree.renderer.group_empty| +|nvim_tree.Config.Renderer| {group_empty} |nvim-tree.renderer.hidden_display| |nvim-tree.renderer.highlight_bookmarks| |nvim-tree.renderer.highlight_clipboard| @@ -3263,7 +3263,7 @@ highlight group is not, hard linking as follows: > |nvim-tree.renderer.highlight_git| |nvim-tree.renderer.highlight_hidden| |nvim-tree.renderer.highlight_modified| -|nvim-tree.renderer.highlight_opened_files| +|nvim_tree.Config.Renderer| {highlight_opened_files} |nvim-tree.renderer.icons| |nvim-tree.renderer.icons.bookmarks_placement| |nvim-tree.renderer.icons.diagnostics_placement| @@ -3278,7 +3278,7 @@ highlight group is not, hard linking as follows: > |nvim-tree.renderer.icons.hidden_placement| |nvim-tree.renderer.icons.modified_placement| |nvim-tree.renderer.icons.padding.folder_arrow| -|nvim-tree.renderer.icons.padding.icon| +|nvim_tree.Config.Renderer.Icons.Padding| {icon} |nvim-tree.renderer.icons.show| |nvim-tree.renderer.icons.show.bookmarks| |nvim-tree.renderer.icons.show.diagnostics| @@ -3291,7 +3291,7 @@ highlight group is not, hard linking as follows: > |nvim-tree.renderer.icons.symlink_arrow| |nvim-tree.renderer.icons.web_devicons| |nvim-tree.renderer.icons.web_devicons.file| -|nvim-tree.renderer.icons.web_devicons.file.color| +|nvim_tree.Config.Renderer.Icons.WebDevicons.File| {color} |nvim-tree.renderer.icons.web_devicons.file.enable| |nvim-tree.renderer.icons.web_devicons.folder| |nvim-tree.renderer.icons.web_devicons.folder.color| @@ -3301,36 +3301,36 @@ highlight group is not, hard linking as follows: > |nvim-tree.renderer.indent_markers.icons| |nvim-tree.renderer.indent_markers.inline_arrows| |nvim-tree.renderer.indent_width| -|nvim-tree.renderer.root_folder_label| +|nvim_tree.Config.Renderer| {root_folder_label} |nvim-tree.renderer.special_files| |nvim-tree.renderer.symlink_destination| |nvim-tree.respect_buf_cwd| |nvim-tree.root_dirs| -|nvim-tree.select_prompts| +|nvim_tree.Config| {select_prompts} |nvim-tree.sort.files_first| |nvim-tree.sort.folders_first| -|nvim-tree.sort.sorter| -|nvim-tree.sync_root_with_cwd| +|nvim_tree.Config.Sort| {sorter} +|nvim_tree.Config| {sync_root_with_cwd} |nvim-tree.system_open.args| |nvim-tree.system_open.cmd| |nvim-tree.tab.sync| -|nvim-tree.tab.sync.close| -|nvim-tree.tab.sync.ignore| -|nvim-tree.tab.sync.open| +|nvim_tree.Config.Tab.Sync| {close} +|nvim_tree.Config.Tab.Sync| {ignore} +|nvim_tree.Config.Tab.Sync| {open} |nvim-tree.trash.cmd| |nvim-tree.ui.confirm| |nvim-tree.ui.confirm.default_yes| |nvim-tree.ui.confirm.remove| -|nvim-tree.ui.confirm.trash| +|nvim_tree.Config.UI.Confirm| {trash} |nvim-tree.update_focused_file.enable| |nvim-tree.update_focused_file.exclude| -|nvim-tree.update_focused_file.update_root| +|nvim_tree.Config.UpdateFocusedFile| {update_root} |nvim-tree.update_focused_file.update_root.enable| |nvim-tree.update_focused_file.update_root.ignore_list| |nvim-tree.view.centralize_selection| |nvim-tree.view.cursorline| |nvim-tree.view.cursorlineopt| -|nvim-tree.view.debounce_delay| +|nvim_tree.Config.View| {debounce_delay} |nvim-tree.view.float| |nvim-tree.view.float.enable| |nvim-tree.view.float.open_win_config| @@ -3340,7 +3340,7 @@ highlight group is not, hard linking as follows: > |nvim-tree.view.relativenumber| |nvim-tree.view.side| |nvim-tree.view.signcolumn| -|nvim-tree.view.width| +|nvim_tree.Config.View| {width} |nvim-tree.view.width.lines_excluded| |nvim-tree.view.width.max| |nvim-tree.view.width.min| From d6e5d7387f27f7e223bcaf6630ac4f2f2f56c591 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 13 Jan 2026 10:43:42 +1100 Subject: [PATCH 053/170] docs(#2934): remove 5. Opts, 8.2 Highlight: Overhaul, 15.1 Index: Opts, update links as needed --- doc/nvim-tree-lua.txt | 1426 +---------------------------------------- 1 file changed, 8 insertions(+), 1418 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 3dff955d95e..d3f4bb67996 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -13,28 +13,6 @@ CONTENTS 2.4 Quickstart: Highlight |nvim-tree-quickstart-highlight| 3. Commands |nvim-tree-commands| 4. Setup |nvim-tree-setup| - 5. Opts |nvim_tree.Config| - 5.1 Opts: Sort |nvim-tree-opts-sort| - 5.2 Opts: View |nvim-tree-opts-view| - 5.3 Opts: Renderer |nvim_tree.Config.Renderer| - 5.4 Opts: Hijack Directories |nvim-tree-opts-hijack-directories| - 5.5 Opts: Update Focused File |nvim_tree.Config.UpdateFocusedFile| - 5.6 Opts: System Open |nvim_tree.Config.SystemOpen| - 5.7 Opts: Git |nvim-tree-opts-git| - 5.8 Opts: Diagnostics |nvim-tree-opts-diagnostics| - 5.9 Opts: Modified |nvim-tree-opts-modified| - 5.10 Opts: Filters |nvim-tree-opts-filters| - 5.11 Opts: Live Filter |nvim-tree-opts-live-filter| - 5.12 Opts: Filesystem Watchers |nvim-tree-opts-filesystem-watchers| - 5.13 Opts: Actions |nvim-tree-opts-actions| - 5.14 Opts: Trash |nvim_tree.Config.Trash| - 5.15 Opts: Tab |nvim-tree-opts-tab| - 5.16 Opts: Notify |nvim-tree-opts-notify| - 5.17 Opts: Help |nvim-tree-opts-help| - 5.18 Opts: UI |nvim-tree-opts-ui| - 5.19 Opts: Bookmarks |nvim-tree-opts-bookmarks| - 5.20 Opts: Experimental |nvim-tree-opts-experimental| - 5.21 Opts: Log |nvim-tree-opts-log| 6. API |nvim-tree-api| 6.1 API Tree |nvim-tree-api.tree| 6.2 API File System |nvim-tree-api.fs| @@ -50,7 +28,6 @@ CONTENTS 7.1 Mappings: Default |nvim-tree-mappings-default| 8. Highlight |nvim-tree-highlight| 8.1 Highlight: Default |nvim-tree-highlight-default| - 8.2 Highlight: Overhaul |nvim-tree-highlight-overhaul| 9. Events |nvim-tree-events| 10. Prompts |nvim-tree-prompts| 11. Decorators |nvim-tree-decorators| @@ -61,7 +38,6 @@ CONTENTS 14.1 Legacy: Opts |nvim-tree-legacy-opts| 14.2 Legacy: Highlight |nvim-tree-legacy-highlight| 15. Index |nvim-tree-index| - 15.1 Index: Opts |nvim-tree-index-opts| 15.2 Index: API |nvim-tree-index-api| ============================================================================== @@ -85,7 +61,7 @@ File Icons  should look like an open folder. - To disable the display of icons see |nvim-tree.renderer.icons.show| + Disable the display of icons with |nvim_tree.Config.Renderer.Icons.Show| Colours @@ -662,1070 +638,6 @@ Following is the default configuration. See |nvim_tree.Config| for details. >lua } -- END_DEFAULT_OPTS < -============================================================================== - 5. OPTS *nvim-tree-opts* - -*nvim-tree.on_attach* -Runs when creating the nvim-tree buffer. Use this to set your nvim-tree -specific mappings. See |nvim-tree-mappings|. -When on_attach is not a function, |nvim-tree-mappings-default| will be called. - Type: `function(bufnr) | string`, Default: `"default"` - -*nvim-tree.hijack_cursor* -Keeps the cursor on the first letter of the filename when moving in the tree. - Type: `boolean`, Default: `false` - -*nvim-tree.auto_reload_on_write* -Reloads the explorer every time a buffer is written to. - Type: `boolean`, Default: `true` - -*nvim-tree.disable_netrw* -Completely disable netrw - Type: `boolean`, Default: `false` - -It is strongly advised to eagerly disable netrw, due to race conditions at vim -startup. -Set the following at the very beginning of your `init.lua` / `init.vim`: >lua - vim.g.loaded_netrw = 1 - vim.g.loaded_netrwPlugin = 1 -< -*nvim-tree.hijack_netrw* -Hijack netrw windows (overridden if |nvim-tree.disable_netrw| is `true`) - Type: `boolean`, Default: `true` - -*nvim-tree.hijack_unnamed_buffer_when_opening* -Opens in place of the unnamed buffer if it's empty. - Type: `boolean`, Default: `false` - -*nvim-tree.root_dirs* -Preferred root directories. -Only relevant when `update_focused_file.update_root` is `true` - Type: `{string}`, Default: `{}` - -*nvim-tree.prefer_startup_root* -Prefer startup root directory when updating root directory of the tree. -Only relevant when `update_focused_file.update_root` is `true` - Type: `boolean`, Default: `false` - -*nvim-tree.sync_root_with_cwd* -Changes the tree root directory on `DirChanged` and refreshes the tree. - Type: `boolean`, Default: `false` - -*nvim-tree.reload_on_bufenter* -Automatically reloads the tree on `BufEnter` nvim-tree. - Type: `boolean`, Default: `false` - -*nvim-tree.respect_buf_cwd* -Will change cwd of nvim-tree to that of new buffer's when opening nvim-tree. - Type: `boolean`, Default: `false` - -*nvim-tree.select_prompts* -Use |vim.ui.select()| style prompts. Necessary when using a UI prompt decorator -such as dressing.nvim or telescope-ui-select.nvim -Type: `boolean`, Default: `false` - -============================================================================== - 5.1 OPTS: SORT *nvim-tree-opts-sort* - -File and folder sorting options. - -*nvim-tree.sort.sorter* -Changes how files within the same directory are sorted. -Can be one of `"name"`, `"case_sensitive"`, `"modification_time"`, `"extension"`, -`"suffix"`, `"filetype"` or a function. -`"extension"` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz` -`"suffix"` uses the last e.g. `.gz` - Type: `string` | `function(nodes)`, Default: `"name"` - - Function may perform a sort or return a string with one of the above - methods. It is passed a table of nodes to be sorted, each node containing: - - `absolute_path`: `string` - - `executable`: `boolean` - - `extension`: `string` - - `filetype`: `string` - - `link_to`: `string` - - `name`: `string` - - `type`: `"directory"` | `"file"` | `"link"` - - Example: sort by name length: >lua - local sorter = function(nodes) - table.sort(nodes, function(a, b) - return #a.name < #b.name - end) - end -< -*nvim-tree.sort.folders_first* -Sort folders before files. Has no effect when |nvim_tree.Config.Sort| {sorter} is a -function. - Type: `boolean`, Default: `true` - -*nvim-tree.sort.files_first* -Sort files before folders. Has no effect when |nvim_tree.Config.Sort| {sorter} is a -function. If set to `true` it overrides |nvim-tree.sort.folders_first|. - Type: `boolean`, Default: `false` - -============================================================================== - 5.2 OPTS: VIEW *nvim-tree-opts-view* - -*nvim-tree.view.centralize_selection* -When entering nvim-tree, reposition the view so that the current node is -initially centralized, see |zz|. - Type: `boolean`, Default: `false` - -*nvim-tree.view.cursorline* -Enable |'cursorline'| in the tree window. - Type: `boolean`, Default: `true` - -*nvim-tree.view.cursorlineopt* -Set |'cursorlineopt'| in the tree window. - Type: `string`, Default: `"both"` - -*nvim-tree.view.debounce_delay* -Idle milliseconds before some reload / refresh operations. -Increase if you experience performance issues around screen refresh. - Type: `number`, Default: `15` (ms) - -*nvim-tree.view.side* -Side of the tree, can be `"left"`, `"right"`. - Type: `string`, Default: `"left"` - -*nvim-tree.view.preserve_window_proportions* -Preserves window proportions when opening a file. -If `false`, the height and width of windows other than nvim-tree will be equalized. - Type: `boolean`, Default: `false` - -*nvim-tree.view.number* -Print the line number in front of each line. - Type: `boolean`, Default: `false` - -*nvim-tree.view.relativenumber* -Show the line number relative to the line with the cursor in front of each line. -If the option `view.number` is also `true`, the number on the cursor line -will be the line number instead of `0`. - Type: `boolean`, Default: `false` - -*nvim-tree.view.signcolumn* -Show |'signcolumn'|. Value can be `"yes"`, `"auto"`, `"no"`. - Type: `string`, Default: `"yes"` - -*nvim-tree.view.width* -Width of the window: can be a `%` string, a number representing columns, a -function or a table. -A table indicates that the view should be dynamically sized based on the -longest line. - Type: `string | number | table | fun(): number|string` - Default: `30` - - *nvim-tree.view.width.min* - Minimum dynamic width. - Type: `string | number | fun(): number|string` - Default: `30` - - *nvim-tree.view.width.max* - Maximum dynamic width, -1 for unbounded. - Type: `string | number | fun(): number|string` - Default: `-1` - - *nvim-tree.view.width.lines_excluded* - Exclude these lines when computing width. - Supported values: `"root". - Type: `table` - Default: - `{` - `"root"` - `}` - - *nvim-tree.view.width.padding* - Extra padding to the right. - Type: `number | fun(): number|string` - Default: `1` - -*nvim-tree.view.float* -Use nvim-tree in a floating window. - - *nvim-tree.view.float.enable* - Tree window will be floating. - Type: `boolean`, Default: `false` - - *nvim-tree.view.float.quit_on_focus_loss* - Close the floating tree window when it loses focus. - Type: `boolean`, Default: `true` - - *nvim-tree.view.float.open_win_config* - Floating window config. See |nvim_open_win()| for more details. - Type: `table | function` returning a table - Default: - `{` - `relative = "editor",` - `border = "rounded",` - `width = 30,` - `height = 30,` - `row = 1,` - `col = 1,` - `}` - -============================================================================== - 5.3 OPTS: RENDERER *nvim-tree-opts-renderer* - -*nvim-tree.renderer.add_trailing* -Appends a trailing slash to folder and symlink folder destination names. - Type: `boolean`, Default: `false` - -*nvim-tree.renderer.group_empty* -Compact folders that only contain a single folder into one node. -Boolean or function that takes one argument (the relative path -of grouped folders) and returns a string to be displayed. - Type: `boolean | function(relative_path):string`, Default: `false` - -*nvim-tree.renderer.full_name* -Display node whose name length is wider than the width of nvim-tree window in -floating window. - Type: `boolean`, Default: `false` - -*nvim-tree.renderer.root_folder_label* -In what format to show root folder. See `:help filename-modifiers` for -available `string` options. -Set to `false` to hide the root folder. - Type: `string` or `boolean` or `function(root_cwd)`, Default: `":~:s?$?/..?"` - - Function is passed the absolute path of the root folder and should - return a string. e.g. >lua - my_root_folder_label = function(path) - return ".../" .. vim.fn.fnamemodify(path, ":t") - end -< -*nvim-tree.renderer.indent_width* -Number of spaces for an each tree nesting level. Minimum 1. - Type: `number`, Default: `2` - -*nvim-tree.renderer.special_files* -A list of filenames that gets highlighted with `NvimTreeSpecialFile`. - Type: `table`, Default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }` - -*nvim-tree.renderer.hidden_display* -Show a summary of hidden files below the tree using `NvimTreeHiddenDisplay - Type: `function | string`, Default: `"none"` - - Possible string values are: - - `"none"`: Doesn't inform anything about hidden files. - - `"simple"`: Shows how many hidden files are in a folder. - - `"all"`: Shows how many files are hidden and the number of hidden - files per reason why they're hidden. - - Example `"all"`: - If a folder has 14 hidden items for various reasons, the display might - show: > - (14 total git: 5, dotfile: 9) -< - If a function is provided, it receives a table `hidden_stats` where keys are - reasons and values are the count of hidden files for that reason. - - The `hidden_stats` argument is structured as follows, where is the - number of hidden files related to the field: >lua - hidden_stats = { - bookmark = , - buf = , - custom = , - dotfile = , - git = , - live_filter = , - } -< - Example of function that can be passed: >lua - function(hidden_stats) - local total_count = 0 - for reason, count in pairs(hidden_stats) do - total_count = total_count + count - end - - if total_count > 0 then - return "(" .. tostring(total_count) .. " hidden)" - end - return nil - end -< - -*nvim-tree.renderer.symlink_destination* -Whether to show the destination of the symlink. - Type: `boolean`, Default: `true` - -*nvim-tree.renderer.decorators* -Highlighting and icons for the nodes, in increasing order of precedence. -Uses strings to specify builtin decorators otherwise specify your -`nvim_tree.api.decorator.UserDecorator` class. -See |nvim-tree-decorators| - Type: `nvim_tree.api.decorator.Name[]`, Default: >lua - { - "Git", - "Open", - "Hidden", - "Modified", - "Bookmark", - "Diagnostics", - "Copied", - "Cut", - } -< -*nvim-tree.renderer.highlight_git* -Enable highlight for git attributes using `NvimTreeGit*HL` highlight groups. -Requires |nvim-tree.git.enable| -Value can be `"none"`, `"icon"`, `"name"` or `"all"`. - Type: `string`, Default: `"none"` - -*nvim-tree.renderer.highlight_diagnostics* -Enable highlight for diagnostics using `NvimTreeDiagnostic*HL` highlight groups. -Requires |nvim-tree.diagnostics.enable| -Value can be `"none"`, `"icon"`, `"name"` or `"all"`. - Type: `string`, Default: `"none"` - -*nvim-tree.renderer.highlight_opened_files* -Highlight icons and/or names for |bufloaded()| files using the -`NvimTreeOpenedHL` highlight group. -See |nvim-tree-api.node.navigate.opened.next()| and |nvim-tree-api.node.navigate.opened.prev()| -Value can be `"none"`, `"icon"`, `"name"` or `"all"`. - Type: `string`, Default: `"none"` - -*nvim-tree.renderer.highlight_modified* -Highlight icons and/or names for modified files using the -`NvimTreeModifiedFile` highlight group. -Requires |nvim-tree.modified.enable| -Value can be `"none"`, `"icon"`, `"name"` or `"all"` - Type: `string`, Default `"none"` - -*nvim-tree.renderer.highlight_hidden* -Highlight icons and/or names for hidden files (dotfiles) using the -`NvimTreeHiddenFileHL` highlight group. -Value can be `"none"`, `"icon"`, `"name"` or `"all"` - Type: `string`, Default `"none"` - -*nvim-tree.renderer.highlight_bookmarks* -Highlight bookmarked using the `NvimTreeBookmarkHL` group. -Value can be `"none"`, `"icon"`, `"name"` or `"all"` - Type: `string`, Default `"none"` - -*nvim-tree.renderer.highlight_clipboard* -Enable highlight for clipboard items using the `NvimTreeCutHL` and -`NvimTreeCopiedHL` groups. -Value can be `"none"`, `"icon"`, `"name"` or `"all"`. - Type: `string`, Default: `"name"` - -*nvim-tree.renderer.indent_markers* -Configuration options for tree indent markers. - - *nvim-tree.renderer.indent_markers.enable* - Display indent markers when folders are open - Type: `boolean`, Default: `false` - - *nvim-tree.renderer.indent_markers.inline_arrows* - Display folder arrows in the same column as indent marker - when using |nvim-tree.renderer.icons.show.folder_arrow| - Type: `boolean`, Default: `true` - - *nvim-tree.renderer.indent_markers.icons* - Icons shown before the file/directory. Length 1. - Type: `table`, Default: >lua - { - corner = "└", - edge = "│", - item = "│", - bottom = "─", - none = " ", - } -< -*nvim-tree.renderer.icons* -Configuration options for icons. - -`renderer.icons.*_placement` options may be: -- `"before"` : before file/folder, after the file/folders icons -- `"after"` : after file/folder -- `"signcolumn"` : far left, requires |nvim-tree.view.signcolumn| enabled -- `"right_align"` : far right - - *nvim-tree.renderer.icons.web_devicons* - Configure optional plugin `"nvim-tree/nvim-web-devicons"` - - *nvim-tree.renderer.icons.web_devicons.file* - File icons. - - *nvim-tree.renderer.icons.web_devicons.file.enable* - Show icons on files. - Overrides |nvim-tree.renderer.icons.glyphs.default| - Type: `boolean`, Default: `true` - - *nvim-tree.renderer.icons.web_devicons.file.color* - Use icon colors for files. Overrides highlight groups. - Type: `boolean`, Default: `true` - - *nvim-tree.renderer.icons.web_devicons.folder* - Folder icons. - - *nvim-tree.renderer.icons.web_devicons.folder.enable* - Show icons on folders. - Overrides |nvim-tree.renderer.icons.glyphs.folder| - Type: `boolean`, Default: `false` - - *nvim-tree.renderer.icons.web_devicons.folder.color* - Use icon colors for folders. Overrides highlight groups. - Type: `boolean`, Default: `true` - - *nvim-tree.renderer.icons.git_placement* - Git icons placement. - Type: `string`, Default: `"before"` - - *nvim-tree.renderer.icons.diagnostics_placement* - Diganostic icon placement. - Type: `string`, Default: `"signcolumn"` - - *nvim-tree.renderer.icons.modified_placement* - Modified icon placement. - Type: `string`, Default: `"after"` - - *nvim-tree.renderer.icons.hidden_placement* - Hidden icon placement. - Type: `string`, Default: `"after"` - - *nvim-tree.renderer.icons.bookmarks_placement* - Bookmark icon placement. - Type: `string`, Default: `"signcolumn"` - - *nvim-tree.renderer.icons.padding.icon* - Inserted between icon and filename. - Type: `string`, Default: `" "` - - *nvim-tree.renderer.icons.padding.folder_arrow* - Inserted between folder arrow icon and file/folder icon. - Type: `string`, Default: `" "` - - *nvim-tree.renderer.icons.symlink_arrow* - Used as a separator between symlinks' source and target. - Type: `string`, Default: `" ➛ "` - - *nvim-tree.renderer.icons.show* - Configuration options for showing icon types. - Left to right order: file/folder, git, modified, hidden, diagnostics, bookmarked. - - *nvim-tree.renderer.icons.show.file* - Show an icon before the file name. - Type: `boolean`, Default: `true` - - *nvim-tree.renderer.icons.show.folder* - Show an icon before the folder name. - Type: `boolean`, Default: `true` - - *nvim-tree.renderer.icons.show.folder_arrow* - Show a small arrow before the folder node. Arrow will be a part of the - node when using |nvim-tree.renderer.indent_markers|. - Type: `boolean`, Default: `true` - - *nvim-tree.renderer.icons.show.git* - Show a git status icon, see |nvim-tree.renderer.icons.git_placement| - Requires |nvim-tree.git.enable| `= true` - Type: `boolean`, Default: `true` - - *nvim-tree.renderer.icons.show.modified* - Show a modified icon, see |nvim-tree.renderer.icons.modified_placement| - Requires |nvim-tree.modified.enable| `= true` - Type: `boolean`, Default: `true` - - *nvim-tree.renderer.icons.show.hidden* - Show a hidden icon, see |nvim-tree.renderer.icons.hidden_placement| - Type: `boolean`, Default: `false` - - *nvim-tree.renderer.icons.show.diagnostics* - Show a diagnostics status icon, see |nvim-tree.renderer.icons.diagnostics_placement| - Requires |nvim-tree.diagnostics.enable| `= true` - Type: `boolean`, Default: `true` - - *nvim-tree.renderer.icons.show.bookmarks* - Show a bookmark icon, see |nvim-tree.renderer.icons.bookmarks_placement| - Type: `boolean`, Default: `true` - - *nvim-tree.renderer.icons.glyphs* - Configuration options for icon glyphs. - NOTE: Do not set any glyphs to more than two characters if it's going - to appear in the signcolumn. - - *nvim-tree.renderer.icons.glyphs.default* - Glyph for files. - Overridden by |nvim-tree.renderer.icons.web_devicons| if available. - Type: `string`, Default: `""` - - *nvim-tree.renderer.icons.glyphs.symlink* - Glyph for symlinks to files. - Type: `string`, Default: `""` - - *nvim-tree.renderer.icons.glyphs.modified* - Icon to display for modified files. - Type: `string`, Default: `"●"` - - *nvim-tree.renderer.icons.glyphs.hidden* - Icon to display for hidden files. - Type: `string`, Default: `"󰜌""` - - *nvim-tree.renderer.icons.glyphs.folder* - Glyphs for directories. - Overridden by |nvim-tree.renderer.icons.web_devicons| if available. - Type: `table`, Default: - `{` - `arrow_closed = "",` - `arrow_open = "",` - `default = "",` - `open = "",` - `empty = "",` - `empty_open = "",` - `symlink = "",` - `symlink_open = "",` - `}` - - *nvim-tree.renderer.icons.glyphs.git* - Glyphs for git status. - Type: `table`, Default: - `{` - `unstaged = "✗",` - `staged = "✓",` - `unmerged = "",` - `renamed = "➜",` - `untracked = "★",` - `deleted = "",` - `ignored = "◌",` - `}` - -============================================================================== - 5.4 OPTS: HIJACK DIRECTORIES *nvim-tree-opts-hijack-directories* - -*nvim-tree.hijack_directories.enable* -Enable the feature. -Disable this option if you use vim-dirvish or dirbuf.nvim. -If `hijack_netrw` and `disable_netrw` are `false`, this feature will be disabled. - Type: `boolean`, Default: `true` - -*nvim-tree.hijack_directories.auto_open* -Opens the tree if the tree was previously closed. - Type: `boolean`, Default: `true` - -============================================================================== - 5.5 OPTS: UPDATE FOCUSED FILE *nvim-tree-opts-update-focused-file* - -Update the focused file on `BufEnter`, un-collapses the folders recursively -until it finds the file. - -*nvim-tree.update_focused_file.enable* -Enable this feature. - Type: `boolean`, Default: `false` - -*nvim-tree.update_focused_file.update_root* -Update the root directory of the tree if the file is not under current -root directory. It prefers vim's cwd and `root_dirs`. -Otherwise it falls back to the folder containing the file. -Only relevant when `update_focused_file.enable` is `true` - - *nvim-tree.update_focused_file.update_root.enable* - Type: `boolean`, Default: `false` - - *nvim-tree.update_focused_file.update_root.ignore_list* - List of buffer names and filetypes that will not update the root dir - of the tree if the file isn't found under the current root directory. - Only relevant when `update_focused_file.update_root.enable` and - `update_focused_file.enable` are `true`. - Type: {string}, Default: `{}` - -*nvim-tree.update_focused_file.exclude* -A function that returns true if the file should not be focused when opening. -Takes the `BufEnter` event as an argument. see |autocmd-events| - Type: {function}, Default: `false` - -============================================================================== - 5.6 OPTS: SYSTEM OPEN *nvim-tree-opts-system-open* - -Open a file or directory in your preferred application. - -|vim.ui.open()| was introduced in Nvim 0.10 and is the default. - -Once nvim-tree minimum Nvim version is updated to 0.10, these options will -no longer be necessary and will be removed. - -*nvim-tree.system_open.cmd* -The open command itself. - Type: `string`, Default: `""` - -Nvim >= 0.10 defaults to |vim.ui.open()| - -Nvim < 0.10 defaults to: - UNIX: `"xdg-open"` - macOS: `"open"` - Windows: `"cmd"` - -*nvim-tree.system_open.args* -Optional argument list. - Type: {string}, Default: `{}` - -Leave empty for OS specific default: - Windows: `{ "/c", "start", '""' }` - -============================================================================== - 5.7 OPTS: GIT *nvim-tree-opts-git* - -Git operations are run in the background thus status may not immediately -appear. - -Processes will be killed if they exceed |nvim-tree.git.timeout| - -Git integration will be disabled following 5 timeouts and you will be -notified. - -*nvim-tree.git.enable* -Enable / disable the feature. - Type: `boolean`, Default: `true` - -*nvim-tree.git.show_on_dirs* -Show status icons of children when directory itself has no status icon. - Type: `boolean`, Default: `true` - -*nvim-tree.git.show_on_open_dirs* -Show status icons of children on directories that are open. -Only relevant when `git.show_on_dirs` is `true`. - Type: `boolean`, Default: `true` - -*nvim-tree.git.disable_for_dirs* -Disable git integration when git top-level matches these paths. -Strings may be relative, evaluated via |fnamemodify()| `":p"` -Function is passed an absolute path and returns true for disable. - Type: `string[] | fun(path: string): boolean`, Default: `{}` - -*nvim-tree.git.timeout* -Kills the git process after some time if it takes too long. -Git integration will be disabled after 10 git jobs exceed this timeout. - Type: `number`, Default: `400` (ms) - -*nvim-tree.git.cygwin_support* -Use `cygpath` if available to resolve paths for git. - Type: `boolean`, Default: `false` - -============================================================================== - 5.8 OPTS: DIAGNOSTICS *nvim-tree-opts-diagnostics* - -LSP and COC diagnostics. - -*nvim-tree.diagnostics.enable* -Enable/disable the feature. - Type: `boolean`, Default: `false` - -*nvim-tree.diagnostics.debounce_delay* -Idle milliseconds between diagnostic event and update. - Type: `number`, Default: `500` (ms) - -*nvim-tree.diagnostics.show_on_dirs* -Show diagnostic icons on parent directories. - Type: `boolean`, Default: `false` - -*nvim-tree.diagnostics.show_on_open_dirs* -Show diagnostics icons on directories that are open. -Only relevant when `diagnostics.show_on_dirs` is `true`. - Type: `boolean`, Default: `true` - -*nvim-tree.diagnostics.severity* -Severity for which the diagnostics will be displayed. See |diagnostic-severity| - - *nvim-tree.diagnostics.severity.min* - Minimum severity. - Type: |vim.diagnostic.severity|, Default: `vim.diagnostic.severity.HINT` - - *nvim-tree.diagnostics.severity.max* - Maximum severity. - Type: |vim.diagnostic.severity|, Default: `vim.diagnostic.severity.ERROR` - -*nvim-tree.diagnostics.icons* -Icons for diagnostic severity. - Type: `table`, Default: >lua - { - hint = "", - info = "", - warning = "", - error = "" - } -< -*nvim-tree.diagnostics.diagnostic_opts* -|vim.diagnostic.Opts| overrides |nvim-tree.diagnostics.severity| and -|nvim-tree.diagnostics.icons| - Type: `boolean`, Default: `false` -============================================================================== - 5.9 OPTS: MODIFIED *nvim-tree-opts-modified* - -Indicate which file have unsaved modification. - -You will still need to set |nvim-tree.renderer.icons.show.modified| `= true` or -|nvim-tree.renderer.highlight_modified| `= true` to be able to see modified status in the -tree. - -*nvim-tree.modified.enable* -Enable / disable the feature. - Type: `boolean`, Default: `false` - -*nvim-tree.modified.show_on_dirs* -Show modified indication on directory whose children are modified. - Type: `boolean`, Default: `true` - -*nvim-tree.modified.show_on_open_dirs* -Show modified indication on open directories. -Only relevant when |nvim-tree.modified.show_on_dirs| is `true`. - Type: `boolean`, Default: `true` - -============================================================================== - 5.10 OPTS: FILTERS *nvim-tree-opts-filters* - -File / folder filters that may be toggled. - -*nvim-tree.filters.enable* -Enable / disable all filters including live filter. -Toggle via |nvim-tree-api.tree.toggle_enable_filters()| - Type: `boolean`, Default: `true` - -*nvim-tree.filters.git_ignored* -Ignore files based on `.gitignore`. Requires |nvim-tree.git.enable| `= true` -Toggle via |nvim-tree-api.tree.toggle_gitignore_filter()|, default `I` - Type: `boolean`, Default: `true` - -*nvim-tree.filters.dotfiles* -Do not show dotfiles: files starting with a `.` -Toggle via |nvim-tree-api.tree.toggle_hidden_filter()|, default `H` - Type: `boolean`, Default: `false` - -*nvim-tree.filters.git_clean* -Do not show files with no git status. This will show ignored files when -|nvim_tree.Config.Filters| {git_ignored} is set, as they are effectively dirty. -Toggle via |nvim-tree-api.tree.toggle_git_clean_filter()|, default `C` - Type: `boolean`, Default: `false` - -*nvim-tree.filters.no_buffer* -Do not show files that have no |buflisted()| buffer. -Toggle via |nvim-tree-api.tree.toggle_no_buffer_filter()|, default `B` -For performance reasons this may not immediately update on buffer -delete/wipe. A reload or filesystem event will result in an update. - Type: `boolean`, Default: `false` - -*nvim-tree.filters.no_bookmark* -Do not show files that are not bookmarked. -Toggle via |nvim-tree-api.tree.toggle_no_bookmark_filter()|, default `M` - Type: `boolean`, Default: `false` - -*nvim-tree.filters.custom* -Custom list of vim regex for file/directory names that will not be shown. -Backslashes must be escaped e.g. "^\\.git". See |string-match|. -Toggle via |nvim-tree-api.tree.toggle_custom_filter()|, default `U` - Type: {string} | `function(absolute_path)`, Default: `{}` - -*nvim-tree.filters.exclude* -List of directories or files to exclude from filtering: always show them. -Overrides `filters.git_ignored`, `filters.dotfiles` and `filters.custom`. - Type: {string}, Default: `{}` - -============================================================================== - 5.11 OPTS: LIVE FILTER *nvim-tree-opts-live-filter* - -Configurations for the live_filtering feature. -The live filter allows you to filter the tree nodes dynamically, based on -regex matching (see |vim.regex|). -This feature is bound to the `f` key by default. -The filter can be cleared with the `F` key by default. - -*nvim-tree.live_filter.prefix* -Prefix of the filter displayed in the buffer. - Type: `string`, Default: `"[FILTER]: "` - -*nvim-tree.live_filter.always_show_folders* -Whether to filter folders or not. - Type: `boolean`, Default: `true` - -============================================================================== - 5.12 OPTS: FILESYSTEM WATCHERS *nvim-tree-opts-filesystem-watchers* - -Will use file system watcher (libuv fs_event) to watch the filesystem for -changes. -Using this will disable BufEnter / BufWritePost events in nvim-tree which -were used to update the whole tree. With this feature, the tree will be -updated only for the appropriate folder change, resulting in better -performance. - -*nvim-tree.filesystem_watchers.enable* -Enable / disable the feature. - Type: `boolean`, Default: `true` - -*nvim-tree.filesystem_watchers.debounce_delay* -Idle milliseconds between filesystem change and action. - Type: `number`, Default: `50` (ms) - -*nvim-tree.filesystem_watchers.ignore_dirs* -List of vim regex for absolute directory paths that will not be watched or -function returning whether a path should be ignored. -Strings must be backslash escaped e.g. `"my-proj/\\.build$"`. See |string-match|. -Function is passed an absolute path. -Useful when path is not in `.gitignore` or git integration is disabled. - Type: `string[] | fun(path: string): boolean`, Default: >lua - { - "/.ccls-cache", - "/build", - "/node_modules", - "/target", - } -< -============================================================================== - 5.13 OPTS: ACTIONS *nvim-tree-opts-actions* - -*nvim-tree.actions.use_system_clipboard* -A boolean value that toggle the use of system clipboard when copy/paste -function are invoked. When enabled, copied text will be stored in registers -'+' (system), otherwise, it will be stored in '1' and '"'. - Type: `boolean`, Default: `true` - -*nvim-tree.actions.change_dir* -vim |current-directory| behaviour. - - *nvim-tree.actions.change_dir.enable* - Change the working directory when changing directories in the tree. - Type: `boolean`, Default: `true` - - *nvim-tree.actions.change_dir.global* - Use `:cd` instead of `:lcd` when changing directories. - Type: `boolean`, Default: `false` - - *nvim-tree.actions.change_dir.restrict_above_cwd* - Restrict changing to a directory above the global cwd. - Type: `boolean`, Default: `false` - -*nvim-tree.actions.expand_all* -Configuration for |nvim-tree-api.tree.expand_all()| and -|nvim-tree-api.node.expand()| - - *nvim-tree.actions.expand_all.max_folder_discovery* - Limit the number of folders being explored when expanding every folders. - Avoids hanging Nvim when running this action on very large folders. - Type: `number`, Default: `300` - - *nvim-tree.actions.expand_all.exclude* - A list of directories that should not be expanded automatically. - E.g `{ ".git", "target", "build" }` etc. - Type: `table`, Default: `{}` - -*nvim-tree.actions.file_popup* -Configuration for file_popup behaviour. - - *nvim-tree.actions.file_popup.open_win_config* - Floating window config for file_popup. See |nvim_open_win()| for more details. - You shouldn't define `"width"` and `"height"` values here. They will be - overridden to fit the file_popup content. - Type: `table`, Default: - `{` - `col = 1,` - `row = 1,` - `relative = "cursor",` - `border = "shadow",` - `style = "minimal",` - `}` - -*nvim-tree.actions.open_file* -Configuration options for opening a file from nvim-tree. - - *nvim-tree.actions.open_file.quit_on_open* - Closes the explorer when opening a file. - Type: `boolean`, Default: `false` - - *nvim-tree.actions.open_file.eject* - Prevent new opened file from opening in the same window as the tree. - Type: `boolean`, Default: `true` - - *nvim-tree.actions.open_file.resize_window* - Resizes the tree when opening a file. - Type: `boolean`, Default: `true` - - *nvim-tree.actions.open_file.window_picker* - Window picker configuration. - - *nvim-tree.actions.open_file.window_picker.enable* - Enable the feature. If the feature is not enabled, files will open in - window from which you last opened the tree, obeying - |nvim-tree.actions.open_file.window_picker.exclude| - Type: `boolean`, Default: `true` - - *nvim-tree.actions.open_file.window_picker.picker* - Change the default window picker: a string `"default"` or a function. - The function should return the window id that will open the node, - or `nil` if an invalid window is picked or user cancelled the action. - The picker may create a new window. - Type: `string` | `function`, Default: `"default"` - e.g. s1n7ax/nvim-window-picker plugin: >lua - window_picker = { - enable = true, - picker = require("window-picker").pick_window, -< - *nvim-tree.actions.open_file.window_picker.chars* - A string of chars used as identifiers by the window picker. - Type: `string`, Default: `"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"` - - *nvim-tree.actions.open_file.window_picker.exclude* - Table of buffer option names mapped to a list of option values. - Windows containing matching buffers will not be: - - available when using a window picker - - selected when not using a window picker - Type: `table`, Default: >lua - { - filetype = { - "notify", - "packer", - "qf", - "diff", - "fugitive", - "fugitiveblame", - }, - buftype = { - "nofile", - "terminal", - "help", - }, - } -< -*nvim-tree.actions.remove_file.close_window* -Close any window displaying a file when removing the file from the tree. - Type: `boolean`, Default: `true` - -============================================================================== - 5.14 OPTS: TRASH *nvim-tree-opts-trash* - -*nvim-tree.trash.cmd* -The command used to trash items (must be installed on your system). -Default `"gio trash"` from glib2 is a commonly shipped linux package. -macOS default `"trash"` requires the homebrew package `trash` -Windows default `"trash"` requires `trash-cli` or similar - Type: `string`, Default: `"gio trash"` or `"trash"` - -============================================================================== - 5.15 OPTS: TAB *nvim-tree-opts-tab* - -*nvim-tree.tab.sync* -Configuration for syncing nvim-tree across tabs. - - *nvim-tree.tab.sync.open* - Opens the tree automatically when switching tabpage or opening a new - tabpage if the tree was previously open. - Type: `boolean`, Default: `false` - - *nvim-tree.tab.sync.close* - Closes the tree across all tabpages when the tree is closed. - Type: `boolean`, Default: `false` - - *nvim-tree.tab.sync.ignore* - List of filetypes or buffer names on new tab that will prevent - |nvim_tree.Config.Tab.Sync| {open} and |nvim_tree.Config.Tab.Sync| {close} - Type: {string}, Default: `{}` - -============================================================================== - 5.16 OPTS: NOTIFY *nvim-tree-opts-notify* - -*nvim-tree.notify.threshold* -Specify minimum notification level, uses the values from |vim.log.levels| - Type: `enum`, Default: `vim.log.levels.INFO` - -`ERROR`: hard errors e.g. failure to read from the file system. -`WARNING`: non-fatal errors e.g. unable to system open a file. -`INFO:` information only e.g. file copy path confirmation. -`DEBUG:` information for troubleshooting, e.g. failures in some window closing operations. - -*nvim-tree.notify.absolute_path* -Whether to use absolute paths or item names in fs action notifications. - Type: `boolean`, Default: `true` - -============================================================================== - 5.17 OPTS: HELP *nvim-tree-opts-help* - -*nvim-tree.help.sort_by* -Defines how mappings are sorted in the help window. -Can be `"key"` (sort alphabetically by keymap) -or `"desc"` (sort alphabetically by description). - Type: `string`, Default: `"key"` - -============================================================================== - 5.18 OPTS: UI *nvim-tree-opts-ui* - -*nvim-tree.ui.confirm* -Confirmation prompts. - - *nvim-tree.ui.confirm.remove* - Prompt before removing. - Type: `boolean`, Default: `true` - - *nvim-tree.ui.confirm.trash* - Prompt before trashing. - Type: `boolean`, Default: `true` - - *nvim-tree.ui.confirm.default_yes* - If `true` the prompt will be `"Y/n"`, otherwise `"y/N"`. - Type: `boolean`, Default: `false` - -============================================================================== - 5.19 OPTS: BOOKMARKS *nvim-tree-opts-bookmarks* - -*nvim-tree.bookmarks.persist* -Persist bookmarks to a json file containing a list of absolute paths. -Type: `boolean` | `string`, Default: `false` - -`true`: use default: `stdpath("data") .. "/nvim-tree-bookmarks.json"` -`string`: absolute path of your choice. - -============================================================================== - 5.20 OPTS: EXPERIMENTAL *nvim-tree-opts-experimental* - -*nvim-tree.experimental* -Experimental features that may become default or optional functionality. -In the event of a problem please disable the experiment and raise an issue. - -============================================================================== - 5.21 OPTS: LOG *nvim-tree-opts-log* - -Configuration for diagnostic logging. - -*nvim-tree.log.enable* -Enable logging to a file `nvim-tree.log` in |stdpath()| `"log"`, usually -`${XDG_STATE_HOME}/nvim` - Type: `boolean`, Default: `false` - -*nvim-tree.log.truncate* -Remove existing log file at startup. - Type: `boolean`, Default: `false` - -*nvim-tree.log.types* -Specify which information to log. - - *nvim-tree.log.types.all* - Everything. - Type: `boolean`, Default: `false` - - *nvim-tree.log.types.profile* - Timing of some operations. - Type: `boolean`, Default: `false` - - *nvim-tree.log.types.config* - Options and mappings, at startup. - Type: `boolean`, Default: `false` - - *nvim-tree.log.types.copy_paste* - File copy and paste actions. - Type: `boolean`, Default: `false` - - *nvim-tree.log.types.dev* - Used for local development only. Not useful for users. - Type: `boolean`, Default: `false` - - *nvim-tree.log.types.diagnostics* - LSP and COC processing, verbose. - Type: `boolean`, Default: `false` - - *nvim-tree.log.types.git* - Git processing, verbose. - Type: `boolean`, Default: `false` - - *nvim-tree.log.types.watcher* - |nvim-tree-opts-filesystem-watchers| processing, verbose. - Type: `boolean`, Default: `false` - ============================================================================== 6. API *nvim-tree-api* @@ -2074,8 +986,7 @@ node.open.replace_tree_buffer({node}) *nvim-tree-api.node.open.no_window_picker()* node.open.no_window_picker({node}, {opts}) - |nvim-tree-api.node.open.edit()|, window picker will never be used as per - |nvim-tree.actions.open_file.window_picker.enable| `false` + |nvim-tree-api.node.open.edit()|, window picker will be bypassed. Parameters: ~ • {node} (Node|nil) file or folder @@ -2098,8 +1009,7 @@ node.open.vertical({node}, {opts}) *nvim-tree-api.node.open.verti *nvim-tree-api.node.open.vertical_no_picker()* node.open.vertical_no_picker({node}, {opts}) - |nvim-tree-api.node.open.vertical()|, window picker will never be used as per - |nvim-tree.actions.open_file.window_picker.enable| `false` + |nvim-tree-api.node.open.vertical()|, window picker will be bypassed. Parameters: ~ • {node} (Node|nil) file or folder @@ -2122,8 +1032,7 @@ node.open.horizontal({node}, {opts}) *nvim-tree-api.node.open.horizon *nvim-tree-api.node.open.horizontal_no_picker()* node.open.horizontal_no_picker({node}, {opts}) - |nvim-tree-api.node.open.horizontal()|, window picker will never be used as per - |nvim-tree.actions.open_file.window_picker.enable| `false` + |nvim-tree-api.node.open.horizontal()|, window picker will be bypassed. Parameters: ~ • {node} (Node|nil) file or folder @@ -2190,8 +1099,7 @@ node.open.preview({node}, {opts}) *nvim-tree-api.node.open.prev *nvim-tree-api.node.open.preview_no_picker()* node.open.preview_no_picker({node}, {opts}) |nvim-tree-api.node.open.edit()|, file buffer will have |'bufhidden'| set to `delete`. - window picker will never be used as per - |nvim-tree.actions.open_file.window_picker.enable| `false` + window picker will be bypassed. Parameters: ~ • {node} (Node|nil) file or folder @@ -2771,43 +1679,6 @@ Diagnostics Folder Highlight: > NvimTreeDiagnosticInfoFolderHL NvimTreeDiagnosticInfoFileHL NvimTreeDiagnosticHintFolderHL NvimTreeDiagnosticHintFileHL < -============================================================================== - 8.2 HIGHLIGHT: OVERHAUL *nvim-tree-highlight-overhaul* - -See |nvim-tree-legacy-highlight| for old highlight group compatibility. - -2024-01-20: significant highlighting changes, some breaking: - -- Full cterm support. -- Standard vim highlight groups such `DiagnosticUnderlineError` are now the - defaults. -- Highlight groups named consistently. -- All `highlight_xxx` e.g. |nvim-tree.renderer.highlight_git| are granular, - allowing `"none"`, `"icon"`, `"name"` or `"all"` -- `highlight_xxx` has highlight groups for both File and Folder -- `highlight_xxx` is additive instead of overwriting. See - |nvim_tree.Config.Renderer| for precedence. - -2024-01-29: disambiguate default highlights sharing groups: - -- NvimTreeRootFolder PreProc -> Title -- NvimTreeModified* Constant -> Type -- NvimTreeOpenedHL Constant -> Special -- NvimTreeBookmarkIcon Constant -> NvimTreeFolderIcon -- NvimTreeExecFile Constant -> SpellCap -- NvimTreeImageFile PreProc -> SpellCap -- NvimTreeSpecialFile PreProc -> SpellCap -- NvimTreeSymlink Statement -> SpellCap - -Approximate pre-overhaul values for the `SpellCap` groups may be set via: >lua - - vim.cmd([[ - :hi NvimTreeExecFile gui=bold guifg=#ffa0a0 - :hi NvimTreeSymlink gui=bold guifg=#ffff60 - :hi NvimTreeSpecialFile gui=bold,underline guifg=#ff80ff - :hi NvimTreeImageFile gui=bold guifg=#ff80ff - ]]) -< ============================================================================== 9. EVENTS *nvim-tree-events* @@ -2966,7 +1837,7 @@ Decorators may: - Override node icon Create a `nvim_tree.api.decorator.UserDecorator` class and register it with -precedence via |nvim-tree.renderer.decorators| +precedence via |nvim_tree.Config.Renderer| {decorators} See |nvim-tree-decorator-example| @@ -3092,8 +1963,8 @@ must be disabled manually at the start of your `init.lua` as per |netrw-noload|: There are many |netrw| features beyond the file browser. If you want to keep using |netrw| without its browser features please ensure: -|nvim-tree.disable_netrw| `= false` -|nvim_tree.Config| {hijack_netrw} ` = true` +|nvim_tree.Config| {disable_netrw}` = false` +|nvim_tree.Config| {hijack_netrw}` = true` ============================================================================== 14. LEGACY *nvim-tree-legacy* @@ -3170,287 +2041,6 @@ highlight group is not, hard linking as follows: > NvimTreeLspDiagnosticsInformationFolderText NvimTreeDiagnosticInfoFolderHL NvimTreeLspDiagnosticsHintFolderText NvimTreeDiagnosticHintFolderHL < -============================================================================== - 15 INDEX *nvim-tree-index* - -============================================================================== - 15.1 INDEX: OPTS *nvim-tree-index-opts* - -|nvim-tree.actions.change_dir| -|nvim-tree.actions.change_dir.enable| -|nvim-tree.actions.change_dir.global| -|nvim-tree.actions.change_dir.restrict_above_cwd| -|nvim-tree.actions.expand_all| -|nvim-tree.actions.expand_all.exclude| -|nvim-tree.actions.expand_all.max_folder_discovery| -|nvim-tree.actions.file_popup| -|nvim-tree.actions.file_popup.open_win_config| -|nvim_tree.Config.Actions.OpenFile| -|nvim-tree.actions.open_file.eject| -|nvim-tree.actions.open_file.quit_on_open| -|nvim-tree.actions.open_file.resize_window| -|nvim-tree.actions.open_file.window_picker| -|nvim-tree.actions.open_file.window_picker.chars| -|nvim-tree.actions.open_file.window_picker.enable| -|nvim-tree.actions.open_file.window_picker.exclude| -|nvim-tree.actions.open_file.window_picker.picker| -|nvim-tree.actions.remove_file.close_window| -|nvim-tree.actions.use_system_clipboard| -|nvim-tree.auto_reload_on_write| -|nvim-tree.bookmarks.persist| -|nvim-tree.diagnostics.debounce_delay| -|nvim-tree.diagnostics.diagnostic_opts| -|nvim-tree.diagnostics.enable| -|nvim-tree.diagnostics.icons| -|nvim-tree.diagnostics.severity| -|nvim-tree.diagnostics.severity.max| -|nvim-tree.diagnostics.severity.min| -|nvim_tree.Config.Diagnostics| {show_on_dirs} -|nvim-tree.diagnostics.show_on_open_dirs| -|nvim-tree.disable_netrw| -|nvim-tree.experimental| -|nvim-tree.filesystem_watchers.debounce_delay| -|nvim-tree.filesystem_watchers.enable| -|nvim-tree.filesystem_watchers.ignore_dirs| -|nvim_tree.Config.Filters| {custom} -|nvim_tree.Config.Filters| {dotfiles} -|nvim_tree.Config.Filters| {enable} -|nvim-tree.filters.exclude| -|nvim_tree.Config.Filters| {git_clean} -|nvim_tree.Config.Filters| {git_ignored} -|nvim_tree.Config.Filters| {no_bookmark} -|nvim_tree.Config.Filters| {no_buffer} -|nvim-tree.git.cygwin_support| -|nvim-tree.git.disable_for_dirs| -|nvim-tree.git.enable| -|nvim_tree.Config.Git| {show_on_dirs} -|nvim-tree.git.show_on_open_dirs| -|nvim-tree.git.timeout| -|nvim-tree.help.sort_by| -|nvim-tree.hijack_cursor| -|nvim-tree.hijack_directories.auto_open| -|nvim-tree.hijack_directories.enable| -|nvim_tree.Config| {hijack_netrw} -|nvim-tree.hijack_unnamed_buffer_when_opening| -|nvim-tree.live_filter.always_show_folders| -|nvim-tree.live_filter.prefix| -|nvim-tree.log.enable| -|nvim-tree.log.truncate| -|nvim-tree.log.types| -|nvim-tree.log.types.all| -|nvim-tree.log.types.config| -|nvim-tree.log.types.copy_paste| -|nvim-tree.log.types.dev| -|nvim-tree.log.types.diagnostics| -|nvim-tree.log.types.git| -|nvim-tree.log.types.profile| -|nvim-tree.log.types.watcher| -|nvim-tree.modified.enable| -|nvim-tree.modified.show_on_dirs| -|nvim-tree.modified.show_on_open_dirs| -|nvim-tree.notify.threshold| -|nvim_tree.Config| {on_attach} -|nvim-tree.prefer_startup_root| -|nvim-tree.reload_on_bufenter| -|nvim-tree.renderer.add_trailing| -|nvim-tree.renderer.decorators| -|nvim-tree.renderer.full_name| -|nvim_tree.Config.Renderer| {group_empty} -|nvim-tree.renderer.hidden_display| -|nvim-tree.renderer.highlight_bookmarks| -|nvim-tree.renderer.highlight_clipboard| -|nvim-tree.renderer.highlight_diagnostics| -|nvim-tree.renderer.highlight_git| -|nvim-tree.renderer.highlight_hidden| -|nvim-tree.renderer.highlight_modified| -|nvim_tree.Config.Renderer| {highlight_opened_files} -|nvim-tree.renderer.icons| -|nvim-tree.renderer.icons.bookmarks_placement| -|nvim-tree.renderer.icons.diagnostics_placement| -|nvim-tree.renderer.icons.git_placement| -|nvim-tree.renderer.icons.glyphs| -|nvim-tree.renderer.icons.glyphs.default| -|nvim-tree.renderer.icons.glyphs.folder| -|nvim-tree.renderer.icons.glyphs.git| -|nvim-tree.renderer.icons.glyphs.hidden| -|nvim-tree.renderer.icons.glyphs.modified| -|nvim-tree.renderer.icons.glyphs.symlink| -|nvim-tree.renderer.icons.hidden_placement| -|nvim-tree.renderer.icons.modified_placement| -|nvim-tree.renderer.icons.padding.folder_arrow| -|nvim_tree.Config.Renderer.Icons.Padding| {icon} -|nvim-tree.renderer.icons.show| -|nvim-tree.renderer.icons.show.bookmarks| -|nvim-tree.renderer.icons.show.diagnostics| -|nvim-tree.renderer.icons.show.file| -|nvim-tree.renderer.icons.show.folder| -|nvim-tree.renderer.icons.show.folder_arrow| -|nvim-tree.renderer.icons.show.git| -|nvim-tree.renderer.icons.show.hidden| -|nvim-tree.renderer.icons.show.modified| -|nvim-tree.renderer.icons.symlink_arrow| -|nvim-tree.renderer.icons.web_devicons| -|nvim-tree.renderer.icons.web_devicons.file| -|nvim_tree.Config.Renderer.Icons.WebDevicons.File| {color} -|nvim-tree.renderer.icons.web_devicons.file.enable| -|nvim-tree.renderer.icons.web_devicons.folder| -|nvim-tree.renderer.icons.web_devicons.folder.color| -|nvim-tree.renderer.icons.web_devicons.folder.enable| -|nvim-tree.renderer.indent_markers| -|nvim-tree.renderer.indent_markers.enable| -|nvim-tree.renderer.indent_markers.icons| -|nvim-tree.renderer.indent_markers.inline_arrows| -|nvim-tree.renderer.indent_width| -|nvim_tree.Config.Renderer| {root_folder_label} -|nvim-tree.renderer.special_files| -|nvim-tree.renderer.symlink_destination| -|nvim-tree.respect_buf_cwd| -|nvim-tree.root_dirs| -|nvim_tree.Config| {select_prompts} -|nvim-tree.sort.files_first| -|nvim-tree.sort.folders_first| -|nvim_tree.Config.Sort| {sorter} -|nvim_tree.Config| {sync_root_with_cwd} -|nvim-tree.system_open.args| -|nvim-tree.system_open.cmd| -|nvim-tree.tab.sync| -|nvim_tree.Config.Tab.Sync| {close} -|nvim_tree.Config.Tab.Sync| {ignore} -|nvim_tree.Config.Tab.Sync| {open} -|nvim-tree.trash.cmd| -|nvim-tree.ui.confirm| -|nvim-tree.ui.confirm.default_yes| -|nvim-tree.ui.confirm.remove| -|nvim_tree.Config.UI.Confirm| {trash} -|nvim-tree.update_focused_file.enable| -|nvim-tree.update_focused_file.exclude| -|nvim_tree.Config.UpdateFocusedFile| {update_root} -|nvim-tree.update_focused_file.update_root.enable| -|nvim-tree.update_focused_file.update_root.ignore_list| -|nvim-tree.view.centralize_selection| -|nvim-tree.view.cursorline| -|nvim-tree.view.cursorlineopt| -|nvim_tree.Config.View| {debounce_delay} -|nvim-tree.view.float| -|nvim-tree.view.float.enable| -|nvim-tree.view.float.open_win_config| -|nvim-tree.view.float.quit_on_focus_loss| -|nvim-tree.view.number| -|nvim-tree.view.preserve_window_proportions| -|nvim-tree.view.relativenumber| -|nvim-tree.view.side| -|nvim-tree.view.signcolumn| -|nvim_tree.Config.View| {width} -|nvim-tree.view.width.lines_excluded| -|nvim-tree.view.width.max| -|nvim-tree.view.width.min| -|nvim-tree.view.width.padding| - -============================================================================== - 15.2 INDEX: API *nvim-tree-index-api* - -|nvim-tree-api.commands.get()| -|nvim-tree-api.config.mappings.default_on_attach()| -|nvim-tree-api.config.mappings.get_keymap()| -|nvim-tree-api.config.mappings.get_keymap_default()| -|nvim-tree-api.diagnostics.hi_test()| -|nvim-tree-api.events.subscribe()| -|nvim-tree-api.fs.clear_clipboard()| -|nvim-tree-api.fs.copy.absolute_path()| -|nvim-tree-api.fs.copy.basename()| -|nvim-tree-api.fs.copy.filename()| -|nvim-tree-api.fs.copy.node()| -|nvim-tree-api.fs.copy.relative_path()| -|nvim-tree-api.fs.create()| -|nvim-tree-api.fs.cut()| -|nvim-tree-api.fs.paste()| -|nvim-tree-api.fs.print_clipboard()| -|nvim-tree-api.fs.remove()| -|nvim-tree-api.fs.rename()| -|nvim-tree-api.fs.rename_basename()| -|nvim-tree-api.fs.rename_full()| -|nvim-tree-api.fs.rename_node()| -|nvim-tree-api.fs.rename_sub()| -|nvim-tree-api.fs.trash()| -|nvim-tree-api.git.reload()| -|nvim-tree-api.live_filter.clear()| -|nvim-tree-api.live_filter.start()| -|nvim-tree-api.marks.bulk.delete()| -|nvim-tree-api.marks.bulk.move()| -|nvim-tree-api.marks.bulk.trash()| -|nvim-tree-api.marks.clear()| -|nvim-tree-api.marks.get()| -|nvim-tree-api.marks.list()| -|nvim-tree-api.marks.navigate.next()| -|nvim-tree-api.marks.navigate.prev()| -|nvim-tree-api.marks.navigate.select()| -|nvim-tree-api.marks.toggle()| -|nvim-tree-api.node.buffer.delete()| -|nvim-tree-api.node.buffer.wipe()| -|nvim-tree-api.node.collapse()| -|nvim-tree-api.node.expand()| -|nvim-tree-api.node.navigate.diagnostics.next()| -|nvim-tree-api.node.navigate.diagnostics.next_recursive()| -|nvim-tree-api.node.navigate.diagnostics.prev()| -|nvim-tree-api.node.navigate.diagnostics.prev_recursive()| -|nvim-tree-api.node.navigate.git.next()| -|nvim-tree-api.node.navigate.git.next_recursive()| -|nvim-tree-api.node.navigate.git.next_skip_gitignored()| -|nvim-tree-api.node.navigate.git.prev()| -|nvim-tree-api.node.navigate.git.prev_recursive()| -|nvim-tree-api.node.navigate.git.prev_skip_gitignored()| -|nvim-tree-api.node.navigate.opened.next()| -|nvim-tree-api.node.navigate.opened.prev()| -|nvim-tree-api.node.navigate.parent()| -|nvim-tree-api.node.navigate.parent_close()| -|nvim-tree-api.node.navigate.sibling.first()| -|nvim-tree-api.node.navigate.sibling.last()| -|nvim-tree-api.node.navigate.sibling.next()| -|nvim-tree-api.node.navigate.sibling.prev()| -|nvim-tree-api.node.open.drop()| -|nvim-tree-api.node.open.edit()| -|nvim-tree-api.node.open.horizontal()| -|nvim-tree-api.node.open.horizontal_no_picker()| -|nvim-tree-api.node.open.no_window_picker()| -|nvim-tree-api.node.open.preview()| -|nvim-tree-api.node.open.preview_no_picker()| -|nvim-tree-api.node.open.replace_tree_buffer()| -|nvim-tree-api.node.open.tab()| -|nvim-tree-api.node.open.tab_drop()| -|nvim-tree-api.node.open.toggle_group_empty()| -|nvim-tree-api.node.open.vertical()| -|nvim-tree-api.node.open.vertical_no_picker()| -|nvim-tree-api.node.run.cmd()| -|nvim-tree-api.node.run.system()| -|nvim-tree-api.node.show_info_popup()| -|nvim-tree-api.tree.change_root()| -|nvim-tree-api.tree.change_root_to_node()| -|nvim-tree-api.tree.change_root_to_parent()| -|nvim-tree-api.tree.close()| -|nvim-tree-api.tree.close_in_all_tabs()| -|nvim-tree-api.tree.close_in_this_tab()| -|nvim-tree-api.tree.collapse_all()| -|nvim-tree-api.tree.expand_all()| -|nvim-tree-api.tree.find_file()| -|nvim-tree-api.tree.focus()| -|nvim-tree-api.tree.get_nodes()| -|nvim-tree-api.tree.get_node_under_cursor()| -|nvim-tree-api.tree.is_tree_buf()| -|nvim-tree-api.tree.is_visible()| -|nvim-tree-api.tree.open()| -|nvim-tree-api.tree.reload()| -|nvim-tree-api.tree.resize()| -|nvim-tree-api.tree.search_node()| -|nvim-tree-api.tree.toggle()| -|nvim-tree-api.tree.toggle_custom_filter()| -|nvim-tree-api.tree.toggle_enable_filters()| -|nvim-tree-api.tree.toggle_git_clean_filter()| -|nvim-tree-api.tree.toggle_gitignore_filter()| -|nvim-tree-api.tree.toggle_help()| -|nvim-tree-api.tree.toggle_hidden_filter()| -|nvim-tree-api.tree.toggle_no_bookmark_filter()| -|nvim-tree-api.tree.toggle_no_buffer_filter()| -|nvim-tree-api.tree.winid()| ============================================================================== Class: Config *nvim-tree-config* From 2c27f24844fa68dea63c677aabc766a19c73974d Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 13 Jan 2026 11:00:55 +1100 Subject: [PATCH 054/170] docs(#2934): remove indices --- doc/nvim-tree-lua.txt | 2 -- scripts/help-update.sh | 33 --------------------------------- 2 files changed, 35 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index d3f4bb67996..0e1121d0ab8 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -37,8 +37,6 @@ CONTENTS 14. Legacy |nvim-tree-legacy| 14.1 Legacy: Opts |nvim-tree-legacy-opts| 14.2 Legacy: Highlight |nvim-tree-legacy-highlight| - 15. Index |nvim-tree-index| - 15.2 Index: API |nvim-tree-index-api| ============================================================================== 1. INTRODUCTION *nvim-tree-introduction* diff --git a/scripts/help-update.sh b/scripts/help-update.sh index b888e61cd33..7fe52a263f2 100755 --- a/scripts/help-update.sh +++ b/scripts/help-update.sh @@ -21,39 +21,6 @@ sed -e "s/^ / /" /tmp/DEFAULT_OPTS.2.lua > /tmp/DEFAULT_OPTS.6.lua sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/DEFAULT_OPTS.6.lua }; /${end}/p; d; }" doc/nvim-tree-lua.txt - -# -# opts index -# -begin="nvim-tree-index-opts\*" -end="=====================" - -printf '\n' > /tmp/index-opts.txt -sed -E " -/^ *\*(nvim-tree\..*)\*$/! d ; -s/^.*\*(.*)\*/|\1|/g -" doc/nvim-tree-lua.txt | sort -d >> /tmp/index-opts.txt -printf '\n' >> /tmp/index-opts.txt - -sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/index-opts.txt - }; /${end}/p; d; }" doc/nvim-tree-lua.txt - -# -# api index -# -begin="nvim-tree-index-api\*" -end="=====================" - -printf '\n' > /tmp/index-api.txt -sed -E " -/\*(nvim-tree-api.*\(\))\*/! d ; -s/^.*\*(.*)\*/|\1|/g -" doc/nvim-tree-lua.txt | sort -d >> /tmp/index-api.txt -printf '\n' >> /tmp/index-api.txt - -sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/index-api.txt - }; /${end}/p; d; }" doc/nvim-tree-lua.txt - # # DEFAULT_ON_ATTACH # From 8bfd76f0e2e1a9b41d5f162cfafbc0b66ae7ab25 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 13 Jan 2026 11:46:50 +1100 Subject: [PATCH 055/170] docs(#2934): add bookmarks, put long descriptions into @brief --- doc/nvim-tree-lua.txt | 291 ++++++++++-------- lua/nvim-tree/_meta/config.lua | 3 + lua/nvim-tree/_meta/config/actions.lua | 8 + lua/nvim-tree/_meta/config/bookmarks.lua | 16 + lua/nvim-tree/_meta/config/diagnostics.lua | 11 +- .../_meta/config/filesystem_watchers.lua | 8 +- lua/nvim-tree/_meta/config/filters.lua | 4 + lua/nvim-tree/_meta/config/git.lua | 9 +- lua/nvim-tree/_meta/config/help.lua | 11 +- .../_meta/config/hijack_directories.lua | 5 + lua/nvim-tree/_meta/config/live_filter.lua | 6 + lua/nvim-tree/_meta/config/log.lua | 6 + lua/nvim-tree/_meta/config/modified.lua | 6 + lua/nvim-tree/_meta/config/notify.lua | 19 +- lua/nvim-tree/_meta/config/renderer.lua | 28 +- lua/nvim-tree/_meta/config/sort.lua | 11 +- lua/nvim-tree/_meta/config/system_open.lua | 7 +- lua/nvim-tree/_meta/config/tab.lua | 7 +- lua/nvim-tree/_meta/config/trash.lua | 6 + lua/nvim-tree/_meta/config/ui.lua | 6 +- .../_meta/config/update_focused_file.lua | 8 +- lua/nvim-tree/_meta/config/view.lua | 17 +- scripts/gen_vimdoc_config.lua | 1 + 23 files changed, 340 insertions(+), 154 deletions(-) create mode 100644 lua/nvim-tree/_meta/config/bookmarks.lua diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 0e1121d0ab8..f815a00bc08 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -2119,6 +2119,8 @@ Class: Config *nvim-tree-config* |nvim_tree.Config.Trash| • {tab}? (`nvim_tree.Config.Tab`) |nvim_tree.Config.Tab| + • {bookmarks}? (`nvim_tree.Config.Bookmarks`) + |nvim_tree.Config.Bookmarks| • {notify}? (`nvim_tree.Config.Notify`) |nvim_tree.Config.Notify| • {help}? (`nvim_tree.Config.Help`) @@ -2132,31 +2134,33 @@ Class: Config *nvim-tree-config* ============================================================================== Class: Config.Sort *nvim-tree-config-sort* -*nvim_tree.Config.Sort* - Sort files within a directory. - - {sorter} *nvim_tree.Config.Sort.Sorter* - • `name` - • `case_sensitive` name - • `modification_time` - • `extension` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz` - • `suffix` uses the last e.g. `foo.tar.gz` -> `.gz` - • `filetype` |filetype| - - {sorter} may be a function that is passed a list of `nvim_tree.api.Node` - to be sorted in place e.g. >lua - - ---Sort by name length - ---@param nodes nvim_tree.api.Node[] - ---@return nvim_tree.Config.Sort.Sorter? - local sorter = function(nodes) - table.sort(nodes, function(a, b) - return #a.name < #b.name - end) - end +Sort files within a directory. + +{sorter} presets *nvim_tree.Config.Sort.Sorter* +• `name` +• `case_sensitive` name +• `modification_time` +• `extension` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz` +• `suffix` uses the last e.g. `foo.tar.gz` -> `.gz` +• `filetype` |filetype| + +{sorter} may be a function that is passed a list of `nvim_tree.api.Node` to be +sorted in place e.g. >lua + + ---Sort by name length + ---@param nodes nvim_tree.api.Node[] + ---@return nvim_tree.Config.Sort.Sorter? + local sorter = function(nodes) + table.sort(nodes, function(a, b) + return #a.name < #b.name + end) + end < - {sorter} may be a function that returns a |nvim_tree.Config.Sort.Sorter| +{sorter} may be a function that returns a |nvim_tree.Config.Sort.Sorter| + + +*nvim_tree.Config.Sort* Fields: ~ • {sorter}? (`nvim_tree.Config.Sort.Sorter|(fun(nodes: nvim_tree.api.Node[]): nvim_tree.Config.Sort.Sorter?)`) @@ -2172,20 +2176,22 @@ Class: Config.Sort *nvim-tree-config-sort* ============================================================================== Class: Config.View *nvim-tree-config-view* -*nvim_tree.Config.View* - Configures the dimensions and appearance of the nvim-tree window. +Configures the dimensions and appearance of the nvim-tree window. - The window is "docked" at the left by default, however may be configured - to float: |nvim_tree.Config.View.Float| +The window is "docked" at the left by default, however may be configured to +float: |nvim_tree.Config.View.Float| - {width} can be a |nvim_tree.Config.View.WidthSpec| for simple static - control or a |nvim_tree.Config.View.Width| for fully dynamic control based - on longest line. +{width} can be a |nvim_tree.Config.View.WidthSpec| for simple static control +or a |nvim_tree.Config.View.Width| for fully dynamic control based on longest +line. *nvim_tree.Config.View.WidthSpec* - • string: `x%` string e.g. `30%` - • integer: number of columns - • function: returns one of the above +• `string`: `x%` string e.g. `30%` +• `integer`: number of columns +• `function`: returns one of the above + + +*nvim_tree.Config.View* Fields: ~ • {centralize_selection}? (`boolean`, default: `false`) When @@ -2256,34 +2262,36 @@ Class: Config.View *nvim-tree-config-view* ============================================================================== Class: Config.Renderer *nvim-tree-config-renderer* -*nvim_tree.Config.Renderer* - Controls the appearance of the tree. - - {highlight_} options *nvim_tree.Config.Renderer.HighlightPlacement* - • `none`: no highlighting - • `icon`: icon only - • `name`: name only - • `all`: icon and name - - {root_folder_label} has 3 forms: - • `string`: |filename-modifiers| format string - • `boolean`: `true` to disable - • `fun(root_cwd: string): string`: return a literal string from root's - absolute path e.g. >lua - my_root_folder_label = function(path) - return ".../" .. vim.fn.fnamemodify(path, ":t") - end +Controls the appearance of the tree. + +{highlight_} options *nvim_tree.Config.Renderer.HighlightPlacement* +• `none`: no highlighting +• `icon`: icon only +• `name`: name only +• `all`: icon and name + +{root_folder_label} has 3 forms: +• `string`: |filename-modifiers| format string +• `boolean`: `true` to disable +• `fun(root_cwd: string): string`: return a literal string from root's + absolute path e.g. >lua + my_root_folder_label = function(path) + return ".../" .. vim.fn.fnamemodify(path, ":t") + end < - TODO: link / move to hidden display help section +TODO: link / move to hidden display help section *nvim_tree.Config.Renderer.HiddenDisplay* - {hidden_display} summary of hidden files below the tree. - • `none`: disabled - • `simple`: show how many hidden files are in a folder - • `all`: show how many hidden and the number of hidden files by reason - • `fun(hidden_stats: table): string`: returns a summary - of hidden stats +{hidden_display} summary of hidden files below the tree. +• `none`: disabled +• `simple`: show how many hidden files are in a folder +• `all`: show how many hidden and the number of hidden files by reason +• `fun(hidden_stats: table): string`: returns a summary of + hidden stats + + +*nvim_tree.Config.Renderer* Fields: ~ • {add_trailing}? (`boolean`, default: `false`) Appends a @@ -2490,13 +2498,15 @@ Class: Config.Renderer *nvim-tree-config-renderer* ============================================================================== Class: Config.HijackDirectories *nvim-tree-config-hijack-directories* -*nvim_tree.Config.HijackDirectories* - Hijack directory buffers by replacing the directory buffer with the tree. +Hijack directory buffers by replacing the directory buffer with the tree. - Disable this option if you use vim-dirvish or dirbuf.nvim. +Disable this option if you use vim-dirvish or dirbuf.nvim. - If |nvim_tree.Config| {hijack_netrw} and {disable_netrw} are `false` this - feature will be disabled. +If |nvim_tree.Config| {hijack_netrw} and {disable_netrw} are `false` this +feature will be disabled. + + +*nvim_tree.Config.HijackDirectories* Fields: ~ • {enable}? (`boolean`) (default: `true`) @@ -2508,8 +2518,10 @@ Class: Config.HijackDirectories *nvim-tree-config-hijack-directories* ============================================================================== Class: Config.UpdateFocusedFile *nvim-tree-config-update-focused-file* +Update the focused file on |BufEnter|, uncollapsing folders recursively. + + *nvim_tree.Config.UpdateFocusedFile* - Update the focused file on |BufEnter|, uncollapsing folders recursively. Fields: ~ • {enable}? (`boolean`) (default: `false`) @@ -2540,18 +2552,20 @@ Class: Config.UpdateFocusedFile *nvim-tree-config-update-focused-file* ============================================================================== Class: Config.SystemOpen *nvim-tree-config-system-open* -*nvim_tree.Config.SystemOpen* - Open files or directories via the OS. +Open files or directories via the OS. - Nvim: - • `>=` 0.10 uses |vim.ui.open()| unless {cmd} is specified - • `<` 0.10 calls external {cmd}: - • UNIX: `xdg-open` - • macOS: `open` - • Windows: `cmd` +Nvim: +• `>=` 0.10 uses |vim.ui.open()| unless {cmd} is specified +• `<` 0.10 calls external {cmd}: + • UNIX: `xdg-open` + • macOS: `open` + • Windows: `cmd` - Once nvim-tree minimum Nvim version is updated to 0.10, these options will - no longer be necessary and will be removed. +Once nvim-tree minimum Nvim version is updated to 0.10, these options will no +longer be necessary and will be removed. + + +*nvim_tree.Config.SystemOpen* Fields: ~ • {cmd}? (`string`, default: `xdg-open`, `open` or `cmd`) The open @@ -2565,17 +2579,19 @@ Class: Config.SystemOpen *nvim-tree-config-system-open* ============================================================================== Class: Config.Git *nvim-tree-config-git* -*nvim_tree.Config.Git* - Git operations are run in the background thus status may not immediately - appear. +Git operations are run in the background thus status may not immediately +appear. - Processes will be killed if they exceed {timeout}ms. Git integration will - be disabled following 5 timeouts and you will be notified. +Processes will be killed if they exceed {timeout} ms. Git integration will be +disabled following 5 timeouts and you will be notified. - Git integration may be disabled for git top-level directories via - {disable_for_dirs}: - • A list of relative paths evaluated with |fnamemodify()| `:p` OR - • A function that is passed an absolute path and returns `true` to disable +Git integration may be disabled for git top-level directories via +{disable_for_dirs}: +• A list of relative paths evaluated with |fnamemodify()| `:p` OR +• A function that is passed an absolute path and returns `true` to disable + + +*nvim_tree.Config.Git* Fields: ~ • {enable}? (`boolean`) (default: `true`) @@ -2597,8 +2613,10 @@ Class: Config.Git *nvim-tree-config-git* ============================================================================== Class: Config.Diagnostics *nvim-tree-config-diagnostics* +Integrate with |lsp| or COC diagnostics. + + *nvim_tree.Config.Diagnostics* - Integrate with |lsp| or COC diagnostics. Fields: ~ • {enable}? (`boolean`) (default: `false`) @@ -2629,11 +2647,13 @@ Class: Config.Diagnostics *nvim-tree-config-diagnostics* ============================================================================== Class: Config.Modified *nvim-tree-config-modified* +Indicate which files have unsaved modification. To see modified status in the +tree you will need: +• |nvim_tree.Config.Renderer.Icons.Show| {modified} OR +• |nvim_tree.Config.Renderer| {highlight_modified} + + *nvim_tree.Config.Modified* - Indicate which files have unsaved modification. To see modified status in - the tree you will need: - • |nvim_tree.Config.Renderer.Icons.Show| {modified} OR - • |nvim_tree.Config.Renderer| {highlight_modified} Fields: ~ • {enable}? (`boolean`) (default: `false`) @@ -2707,12 +2727,14 @@ overriding {git_ignored}, {dotfiles} and {custom} ============================================================================== Class: Config.LiveFilter *nvim-tree-config-live-filter* -*nvim_tree.Config.LiveFilter* - Live filter allows you to filter the tree nodes dynamically, based on - regex matching, see |vim.regex| +Live filter allows you to filter the tree nodes dynamically, based on regex +matching, see |vim.regex| + +This feature is bound to the `f` key by default. The filter can be cleared +with the `F` key by default. - This feature is bound to the `f` key by default. The filter can be cleared - with the `F` key by default. + +*nvim_tree.Config.LiveFilter* Fields: ~ • {prefix}? (`string`, default: `[FILTER]: `) Prefix of @@ -2725,19 +2747,21 @@ Class: Config.LiveFilter *nvim-tree-config-live-filter* ============================================================================== Class: Config.FilesystemWatchers *nvim-tree-config-filesystem-watchers* -*nvim_tree.Config.FilesystemWatchers* - Use file system watchers (libuv fs_event) to monitor the filesystem for - changes and update the tree. +Use file system watchers (libuv `uv_fs_event_t`) to monitor the filesystem for +changes and update the tree. + +With this feature, the tree will be partially updated on specific directory +changes, resulting in better performance. - With this feature, the tree will be partially updated on specific - directory changes, resulting in better performance. +Watchers may be disabled for absolute directory paths via {ignore_dirs}. +• A list of |vim.regex| to match a path, backslash escaped e.g. + `"my-proj/\\.build$"` OR +• A function that is passed an absolute path and returns `true` to disable + This may be useful when a path is not in `.gitignore` or git integration is + disabled. - Watchers may be disabled for absolute directory paths via {ignore_dirs}. - • A list of |vim.regex| to match a path, backslash escaped e.g. - `"my-proj/\\.build$"` OR - • A function that is passed an absolute path and returns `true` to disable - This may be useful when a path is not in `.gitignore` or git integration - is disabled. + +*nvim_tree.Config.FilesystemWatchers* Fields: ~ • {enable}? (`boolean`) (default: `true`) @@ -2873,12 +2897,14 @@ Class: Config.Actions *nvim-tree-config-actions* ============================================================================== Class: Config.Trash *nvim-tree-config-trash* +Files may be trashed via an external command that must be installed on your +system. +• linux: `gio trash`, from linux package `glib2` +• macOS: `trash`, from homebrew package `trash` +• windows: `trash`, requires `trash-cli` or similar + + *nvim_tree.Config.Trash* - Files may be trashed via an external command that must be installed on - your system. - • linux: `gio trash`, from linux package `glib2` - • macOS: `trash`, from homebrew package `trash` - • windows: `trash`, requires `trash-cli` or similar Fields: ~ • {cmd}? (`string`, default: `gio trash` or `trash`) External command. @@ -2894,7 +2920,6 @@ Class: Config.Tab *nvim-tree-config-tab* • {sync}? (`nvim_tree.Config.Tab.Sync`) |nvim_tree.Config.Tab.Sync| *nvim_tree.Config.Tab.Sync* - Sync nvim-tree across tabs. Fields: ~ • {open}? (`boolean`, default: `false`) Opens the tree automatically @@ -2910,31 +2935,51 @@ Class: Config.Tab *nvim-tree-config-tab* ============================================================================== Class: Config.Notify *nvim-tree-config-notify* +nvim-tree |vim.log.levels| +• `ERROR`: hard errors e.g. failure to read from the file system. +• `WARN`: non-fatal errors e.g. unable to system open a file. +• `INFO`: information only e.g. file copy path confirmation. +• `DEBUG`: information for troubleshooting, e.g. failures in some window + closing operations. + + *nvim_tree.Config.Notify* - nvim-tree notifications levels: - • ERROR: hard errors e.g. failure to read from the file system. - • WARN: non-fatal errors e.g. unable to system open a file. - • INFO: information only e.g. file copy path confirmation. - • DEBUG: information for troubleshooting, e.g. failures in some window - closing operations. Fields: ~ • {threshold}? (`vim.log.levels`, default: `vim.log.levels.INFO`) - Specify minimum notification level + Specify minimum notification |vim.log.levels| • {absolute_path}? (`boolean`, default: `true`) Use absolute paths in FS action notifications, otherwise item names. +============================================================================== +Class: Config.Bookmarks *nvim-tree-config-bookmarks* + +Optionally {persist} bookmarks to a json file: +• `true` use default: `stdpath("data") .. "/nvim-tree-bookmarks.json"` +• `false` do not persist +• `string` absolute path of your choice + + +*nvim_tree.Config.Bookmarks* + + Fields: ~ + • {persist}? (`boolean|string`) (default: `false`) + + + ============================================================================== Class: Config.Help *nvim-tree-config-help* -*nvim_tree.Config.Help* - Configure help window, default mapping `g?` +Configure help window, default mapping `g?` *nvim_tree.Config.Help.SortBy* - • `key`: alphabetically by keymap - • `desc`: alphabetically by description +• `key`: alphabetically by keymap +• `desc`: alphabetically by description + + +*nvim_tree.Config.Help* Fields: ~ • {sort_by}? (`nvim_tree.Config.Help.SortBy`, default: `key`) @@ -2965,9 +3010,11 @@ Class: Config.UI *nvim-tree-config-ui* ============================================================================== Class: Config.Log *nvim-tree-config-log* +Log to a file `nvim-tree.log` in |stdpath()| `log`, usually +`${XDG_STATE_HOME}/nvim` + + *nvim_tree.Config.Log* - Log to a file `nvim-tree.log` in |stdpath()| `log`, usually - `${XDG_STATE_HOME}/nvim` Fields: ~ • {enable}? (`boolean`) (default: `false`) diff --git a/lua/nvim-tree/_meta/config.lua b/lua/nvim-tree/_meta/config.lua index ca967d620e1..2986059493a 100644 --- a/lua/nvim-tree/_meta/config.lua +++ b/lua/nvim-tree/_meta/config.lua @@ -99,6 +99,9 @@ error("Cannot require a meta file") ---[nvim_tree.Config.Tab] ---@field tab? nvim_tree.Config.Tab --- +---[nvim_tree.Config.Bookmarks] +---@field bookmarks? nvim_tree.Config.Bookmarks +--- ---[nvim_tree.Config.Notify] ---@field notify? nvim_tree.Config.Notify --- diff --git a/lua/nvim-tree/_meta/config/actions.lua b/lua/nvim-tree/_meta/config/actions.lua index 8504824e750..75aed0891ac 100644 --- a/lua/nvim-tree/_meta/config/actions.lua +++ b/lua/nvim-tree/_meta/config/actions.lua @@ -1,6 +1,8 @@ ---@meta error("Cannot require a meta file") + + ---@class nvim_tree.Config.Actions --- ---Use the system clipboard for copy/paste. Copied text will be stored in registers `+` (system), otherwise, it will be stored in `1` and `"` @@ -23,6 +25,7 @@ error("Cannot require a meta file") ---@field remove_file? nvim_tree.Config.Actions.RemoveFile + --- vim [current-directory] behaviour ---@class nvim_tree.Config.Actions.ChangeDir --- @@ -39,6 +42,7 @@ error("Cannot require a meta file") ---@field restrict_above_cwd? boolean + ---Configure [nvim-tree-api.tree.expand_all()] and [nvim-tree-api.node.expand()] ---@class nvim_tree.Config.Actions.ExpandAll --- @@ -51,6 +55,7 @@ error("Cannot require a meta file") ---@field exclude? string[] + ---{file_popup} floating window. --- ---{open_win_config} is passed directly to [nvim_open_win()], default: @@ -70,6 +75,7 @@ error("Cannot require a meta file") ---@field open_win_config? vim.api.keyset.win_config + ---Opening files. ---@class nvim_tree.Config.Actions.OpenFile --- @@ -89,6 +95,7 @@ error("Cannot require a meta file") ---@field window_picker? nvim_tree.Config.Actions.OpenFile.WindowPicker + ---A window picker will be shown when there are multiple windows available to open a file. It will show a single character identifier in each window's status line. --- ---When it is not enabled the file will open in the window from which you last opened the tree, obeying {exclude} @@ -112,6 +119,7 @@ error("Cannot require a meta file") ---@field exclude? nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude + ---Tables of buffer option names mapped to a list of option values. Windows containing matching buffers will not be: --- - available when using a window picker --- - selected when not using a window picker diff --git a/lua/nvim-tree/_meta/config/bookmarks.lua b/lua/nvim-tree/_meta/config/bookmarks.lua new file mode 100644 index 00000000000..c174097b2d7 --- /dev/null +++ b/lua/nvim-tree/_meta/config/bookmarks.lua @@ -0,0 +1,16 @@ +---@meta +error("Cannot require a meta file") + + +---@brief +---Optionally {persist} bookmarks to a json file: +---- `true` use default: `stdpath("data") .. "/nvim-tree-bookmarks.json"` +---- `false` do not persist +---- `string` absolute path of your choice + + + +---@class nvim_tree.Config.Bookmarks +--- +---(default: `false`) +---@field persist? boolean|string diff --git a/lua/nvim-tree/_meta/config/diagnostics.lua b/lua/nvim-tree/_meta/config/diagnostics.lua index 8c119714dab..1368be54570 100644 --- a/lua/nvim-tree/_meta/config/diagnostics.lua +++ b/lua/nvim-tree/_meta/config/diagnostics.lua @@ -1,8 +1,13 @@ ---@meta error("Cannot require a meta file") + + +---@brief ---Integrate with [lsp] or COC diagnostics. ---- + + + ---@class nvim_tree.Config.Diagnostics --- ---(default: `false`) @@ -28,6 +33,8 @@ error("Cannot require a meta file") --- ---@field icons? nvim_tree.Config.Diagnostics.Icons + + ---[nvim_tree.Config.Diagnostics.Severity]() ---@class nvim_tree.Config.Diagnostics.Severity ---@inlinedoc @@ -40,6 +47,8 @@ error("Cannot require a meta file") ---(default: ERROR) ---@field max? vim.diagnostic.Severity + + ---[nvim_tree.Config.Diagnostics.Icons]() ---@class nvim_tree.Config.Diagnostics.Icons ---@inlinedoc diff --git a/lua/nvim-tree/_meta/config/filesystem_watchers.lua b/lua/nvim-tree/_meta/config/filesystem_watchers.lua index dae3ae77810..fc66ab220e7 100644 --- a/lua/nvim-tree/_meta/config/filesystem_watchers.lua +++ b/lua/nvim-tree/_meta/config/filesystem_watchers.lua @@ -1,7 +1,10 @@ ---@meta error("Cannot require a meta file") ----Use file system watchers (libuv fs_event) to monitor the filesystem for changes and update the tree. + + +---@brief +---Use file system watchers (libuv `uv_fs_event_t`) to monitor the filesystem for changes and update the tree. --- ---With this feature, the tree will be partially updated on specific directory changes, resulting in better performance. --- @@ -9,6 +12,9 @@ error("Cannot require a meta file") --- - A list of [vim.regex] to match a path, backslash escaped e.g. `"my-proj/\\.build$"` OR --- - A function that is passed an absolute path and returns `true` to disable ---This may be useful when a path is not in `.gitignore` or git integration is disabled. + + + ---@class nvim_tree.Config.FilesystemWatchers --- ---(default: `true`) diff --git a/lua/nvim-tree/_meta/config/filters.lua b/lua/nvim-tree/_meta/config/filters.lua index e1869db9b22..decfa9094bd 100644 --- a/lua/nvim-tree/_meta/config/filters.lua +++ b/lua/nvim-tree/_meta/config/filters.lua @@ -1,6 +1,8 @@ ---@meta error("Cannot require a meta file") + + ---@brief ---
help
 ---Filters may be applied to the tree to exlude the display of file and directories.
@@ -42,6 +44,8 @@ error("Cannot require a meta file")
 ---overriding {git_ignored}, {dotfiles} and {custom}
 ---
+ + ---@class nvim_tree.Config.Filters --- ---Enable all filters. diff --git a/lua/nvim-tree/_meta/config/git.lua b/lua/nvim-tree/_meta/config/git.lua index cb049a627bd..9e1705ff6ea 100644 --- a/lua/nvim-tree/_meta/config/git.lua +++ b/lua/nvim-tree/_meta/config/git.lua @@ -1,14 +1,19 @@ ---@meta error("Cannot require a meta file") + + +---@brief ---Git operations are run in the background thus status may not immediately appear. --- ----Processes will be killed if they exceed {timeout}ms. Git integration will be disabled following 5 timeouts and you will be notified. +---Processes will be killed if they exceed {timeout} ms. Git integration will be disabled following 5 timeouts and you will be notified. --- ---Git integration may be disabled for git top-level directories via {disable_for_dirs}: --- - A list of relative paths evaluated with [fnamemodify()] `:p` OR --- - A function that is passed an absolute path and returns `true` to disable ---- + + + ---@class nvim_tree.Config.Git --- ---(default: `true`) diff --git a/lua/nvim-tree/_meta/config/help.lua b/lua/nvim-tree/_meta/config/help.lua index 1a2e189a478..c8b6f79deb7 100644 --- a/lua/nvim-tree/_meta/config/help.lua +++ b/lua/nvim-tree/_meta/config/help.lua @@ -2,13 +2,20 @@ error("Cannot require a meta file") + +---@alias nvim_tree.Config.Help.SortBy "key"|"desc" + + + +---@brief ---Configure help window, default mapping `g?` --- ----@alias nvim_tree.Config.Help.SortBy "key"|"desc" ---[nvim_tree.Config.Help.SortBy]() ---- `key`: alphabetically by keymap ---- `desc`: alphabetically by description ---- + + + ---@class nvim_tree.Config.Help --- ---[nvim_tree.Config.Help.SortBy] diff --git a/lua/nvim-tree/_meta/config/hijack_directories.lua b/lua/nvim-tree/_meta/config/hijack_directories.lua index 0219e858653..872ae6bc17e 100644 --- a/lua/nvim-tree/_meta/config/hijack_directories.lua +++ b/lua/nvim-tree/_meta/config/hijack_directories.lua @@ -2,11 +2,16 @@ error("Cannot require a meta file") + +---@brief ---Hijack directory buffers by replacing the directory buffer with the tree. --- ---Disable this option if you use vim-dirvish or dirbuf.nvim. --- ---If [nvim_tree.Config] {hijack_netrw} and {disable_netrw} are `false` this feature will be disabled. + + + ---@class nvim_tree.Config.HijackDirectories --- ---(default: `true`) diff --git a/lua/nvim-tree/_meta/config/live_filter.lua b/lua/nvim-tree/_meta/config/live_filter.lua index 156e243855c..60b52f172e4 100644 --- a/lua/nvim-tree/_meta/config/live_filter.lua +++ b/lua/nvim-tree/_meta/config/live_filter.lua @@ -1,9 +1,15 @@ ---@meta error("Cannot require a meta file") + + +---@brief --- Live filter allows you to filter the tree nodes dynamically, based on regex matching, see [vim.regex] --- --- This feature is bound to the `f` key by default. The filter can be cleared with the `F` key by default. + + + ---@class nvim_tree.Config.LiveFilter --- ---Prefix of the filter displayed in the buffer. diff --git a/lua/nvim-tree/_meta/config/log.lua b/lua/nvim-tree/_meta/config/log.lua index cc00efe8bdd..e3808a16fa0 100644 --- a/lua/nvim-tree/_meta/config/log.lua +++ b/lua/nvim-tree/_meta/config/log.lua @@ -1,7 +1,13 @@ ---@meta error("Cannot require a meta file") + + +---@brief ---Log to a file `nvim-tree.log` in [stdpath()] `log`, usually `${XDG_STATE_HOME}/nvim` + + + ---@class nvim_tree.Config.Log --- ---(default: `false`) diff --git a/lua/nvim-tree/_meta/config/modified.lua b/lua/nvim-tree/_meta/config/modified.lua index 7e0f00b91d2..bd5a8f4dc6a 100644 --- a/lua/nvim-tree/_meta/config/modified.lua +++ b/lua/nvim-tree/_meta/config/modified.lua @@ -1,10 +1,16 @@ ---@meta error("Cannot require a meta file") + + +---@brief ---Indicate which files have unsaved modification. ---To see modified status in the tree you will need: --- - [nvim_tree.Config.Renderer.Icons.Show] {modified} OR --- - [nvim_tree.Config.Renderer] {highlight_modified} + + + ---@class nvim_tree.Config.Modified --- ---(default: `false`) diff --git a/lua/nvim-tree/_meta/config/notify.lua b/lua/nvim-tree/_meta/config/notify.lua index 252d478ba93..fd1165d9e93 100644 --- a/lua/nvim-tree/_meta/config/notify.lua +++ b/lua/nvim-tree/_meta/config/notify.lua @@ -1,15 +1,20 @@ ---@meta error("Cannot require a meta file") ----nvim-tree notifications levels: ----- ERROR: hard errors e.g. failure to read from the file system. ----- WARN: non-fatal errors e.g. unable to system open a file. ----- INFO: information only e.g. file copy path confirmation. ----- DEBUG: information for troubleshooting, e.g. failures in some window closing operations. ---- + + +---@brief +---nvim-tree |vim.log.levels| +---- `ERROR`: hard errors e.g. failure to read from the file system. +---- `WARN`: non-fatal errors e.g. unable to system open a file. +---- `INFO`: information only e.g. file copy path confirmation. +---- `DEBUG`: information for troubleshooting, e.g. failures in some window closing operations. + + + ---@class nvim_tree.Config.Notify --- ----Specify minimum notification level +---Specify minimum notification |vim.log.levels| ---(Default: `vim.log.levels.INFO`) ---@field threshold? vim.log.levels --- diff --git a/lua/nvim-tree/_meta/config/renderer.lua b/lua/nvim-tree/_meta/config/renderer.lua index b0e9995fd00..049fd219a59 100644 --- a/lua/nvim-tree/_meta/config/renderer.lua +++ b/lua/nvim-tree/_meta/config/renderer.lua @@ -2,9 +2,18 @@ error("Cannot require a meta file") + +---@alias nvim_tree.Config.Renderer.HighlightPlacement "none"|"icon"|"name"|"all" + +---@alias nvim_tree.Config.Renderer.HiddenDisplay "none"|"simple"|"all"|(fun(hidden_stats: table): string) + +---@alias nvim_tree.Config.Renderer.Icons.Placement "before"|"after"|"signcolumn"|"right_align" + + + +---@brief ---Controls the appearance of the tree. --- ----@alias nvim_tree.Config.Renderer.HighlightPlacement "none"|"icon"|"name"|"all" ---{highlight_} options [nvim_tree.Config.Renderer.HighlightPlacement]() ---- `none`: no highlighting ---- `icon`: icon only @@ -21,7 +30,6 @@ error("Cannot require a meta file") ---end ---``` --- ----@alias nvim_tree.Config.Renderer.HiddenDisplay "none"|"simple"|"all"|(fun(hidden_stats: table): string) ---TODO: link / move to hidden display help section [nvim_tree.Config.Renderer.HiddenDisplay]() --- ---{hidden_display} summary of hidden files below the tree. @@ -29,7 +37,9 @@ error("Cannot require a meta file") ---- `simple`: show how many hidden files are in a folder ---- `all`: show how many hidden and the number of hidden files by reason ---- `fun(hidden_stats: table): string`: returns a summary of hidden stats ---- + + + ---@class nvim_tree.Config.Renderer --- ---Appends a trailing slash to folder and symlink folder target names. @@ -117,6 +127,7 @@ error("Cannot require a meta file") ---@field icons? nvim_tree.Config.Renderer.IndentMarkers.Icons + ---[nvim_tree.Config.Renderer.IndentMarkers.Icons]() ---Before the file/directory, length 1. ---@class nvim_tree.Config.Renderer.IndentMarkers.Icons @@ -134,9 +145,9 @@ error("Cannot require a meta file") ---@field none? string + ---Icons and separators. --- ----@alias nvim_tree.Config.Renderer.Icons.Placement "before"|"after"|"signcolumn"|"right_align" ---{_placement} options [nvim_tree.Config.Renderer.Icons.Placement]() ---- `before`: before file/folder, after the file/folders icons ---- `after`: after file/folder @@ -179,6 +190,7 @@ error("Cannot require a meta file") ---@field glyphs? nvim_tree.Config.Renderer.Icons.Glyphs + ---Configure optional plugin `nvim-tree/nvim-web-devicons`. --- ---Overrides glyphs and highlight groups where noted. @@ -190,6 +202,7 @@ error("Cannot require a meta file") ---@field folder? nvim_tree.Config.Renderer.Icons.WebDevicons.Folder + ---[nvim_tree.Config.Renderer.Icons.WebDevicons.File]() ---@class nvim_tree.Config.Renderer.Icons.WebDevicons.File ---@inlinedoc @@ -216,6 +229,7 @@ error("Cannot require a meta file") ---@field color? boolean + ---[nvim_tree.Config.Renderer.Icons.Padding]() ---@class nvim_tree.Config.Renderer.Icons.Padding ---@inlinedoc @@ -229,6 +243,7 @@ error("Cannot require a meta file") ---@field folder_arrow? string + ---Control which icons are displayed. --- ---Left to right ordered: @@ -280,6 +295,7 @@ error("Cannot require a meta file") ---@field bookmarks? boolean + ---Glyphs that appear in the sign column must have length <= 2 --- ---Glyphs defined elsewhere: @@ -309,6 +325,8 @@ error("Cannot require a meta file") ---Git status on files and directories. ---@field git? nvim_tree.Config.Renderer.Icons.Glyphs.Git + + ---[nvim_tree.Config.Renderer.Icons.Glyphs.Folder]() ---@class nvim_tree.Config.Renderer.Icons.Glyphs.Folder ---@inlinedoc @@ -329,6 +347,8 @@ error("Cannot require a meta file") ---(default: `` ) ---@field symlink_open? string + + ---[nvim_tree.Config.Renderer.Icons.Glyphs.Git]() ---@class nvim_tree.Config.Renderer.Icons.Glyphs.Git ---@inlinedoc diff --git a/lua/nvim-tree/_meta/config/sort.lua b/lua/nvim-tree/_meta/config/sort.lua index e80e16c0c46..e1e7bb3e4cc 100644 --- a/lua/nvim-tree/_meta/config/sort.lua +++ b/lua/nvim-tree/_meta/config/sort.lua @@ -1,11 +1,16 @@ ---@meta error("Cannot require a meta file") + + ---@alias nvim_tree.Config.Sort.Sorter "name"|"case_sensitive"|"modification_time"|"extension"|"suffix"|"filetype" + + +---@brief ---Sort files within a directory. --- ----{sorter} [nvim_tree.Config.Sort.Sorter]() +---{sorter} presets [nvim_tree.Config.Sort.Sorter]() ---- `name` ---- `case_sensitive` name ---- `modification_time` @@ -26,7 +31,9 @@ error("Cannot require a meta file") ---end ---``` ---{sorter} may be a function that returns a [nvim_tree.Config.Sort.Sorter] ---- + + + ---@class nvim_tree.Config.Sort --- ---(default: `name`) diff --git a/lua/nvim-tree/_meta/config/system_open.lua b/lua/nvim-tree/_meta/config/system_open.lua index 648b3863a83..dffd5eaea77 100644 --- a/lua/nvim-tree/_meta/config/system_open.lua +++ b/lua/nvim-tree/_meta/config/system_open.lua @@ -1,6 +1,9 @@ ---@meta error("Cannot require a meta file") + + +---@brief ---Open files or directories via the OS. --- ---Nvim: @@ -11,7 +14,9 @@ error("Cannot require a meta file") --- - Windows: `cmd` --- ---Once nvim-tree minimum Nvim version is updated to 0.10, these options will no longer be necessary and will be removed. ---- + + + ---@class nvim_tree.Config.SystemOpen --- ---The open command itself diff --git a/lua/nvim-tree/_meta/config/tab.lua b/lua/nvim-tree/_meta/config/tab.lua index 0e56420f51a..7fc5f9f2146 100644 --- a/lua/nvim-tree/_meta/config/tab.lua +++ b/lua/nvim-tree/_meta/config/tab.lua @@ -1,16 +1,15 @@ ---@meta error("Cannot require a meta file") + + ---@class nvim_tree.Config.Tab --- ---[nvim_tree.Config.Tab.Sync] ---@field sync? nvim_tree.Config.Tab.Sync --- --- Tab.Sync --- ----Sync nvim-tree across tabs. + ---@class nvim_tree.Config.Tab.Sync --- ---Opens the tree automatically when switching tabpage or opening a new tabpage if the tree was previously open. diff --git a/lua/nvim-tree/_meta/config/trash.lua b/lua/nvim-tree/_meta/config/trash.lua index 37582670249..4724caa956d 100644 --- a/lua/nvim-tree/_meta/config/trash.lua +++ b/lua/nvim-tree/_meta/config/trash.lua @@ -1,10 +1,16 @@ ---@meta error("Cannot require a meta file") + + +---@brief ---Files may be trashed via an external command that must be installed on your system. --- - linux: `gio trash`, from linux package `glib2` --- - macOS: `trash`, from homebrew package `trash` --- - windows: `trash`, requires `trash-cli` or similar + + + ---@class nvim_tree.Config.Trash --- ---External command. diff --git a/lua/nvim-tree/_meta/config/ui.lua b/lua/nvim-tree/_meta/config/ui.lua index 438e46fad17..b1b50905359 100644 --- a/lua/nvim-tree/_meta/config/ui.lua +++ b/lua/nvim-tree/_meta/config/ui.lua @@ -1,14 +1,14 @@ ---@meta error("Cannot require a meta file") + + ---@class nvim_tree.Config.UI --- ---[nvim_tree.Config.UI.Confirm] ---@field confirm? nvim_tree.Config.UI.Confirm --- --- UI.Confirm --- + ---Confirmation prompts. ---@class nvim_tree.Config.UI.Confirm diff --git a/lua/nvim-tree/_meta/config/update_focused_file.lua b/lua/nvim-tree/_meta/config/update_focused_file.lua index 2da913d9dd0..0f0b5b571df 100644 --- a/lua/nvim-tree/_meta/config/update_focused_file.lua +++ b/lua/nvim-tree/_meta/config/update_focused_file.lua @@ -1,8 +1,13 @@ ---@meta error("Cannot require a meta file") + + +---@brief ---Update the focused file on [BufEnter], uncollapsing folders recursively. ---- + + + ---@class nvim_tree.Config.UpdateFocusedFile --- ---(default: `false`) @@ -16,6 +21,7 @@ error("Cannot require a meta file") ---@field exclude? boolean|(fun(args: vim.api.keyset.create_autocmd.callback_args): boolean) + ---Update the root directory of the tree if the file is not under the current root directory. --- ---Prefers vim's cwd and [nvim_tree.Config] {root_dirs}, falling back to the directory containing the file. diff --git a/lua/nvim-tree/_meta/config/view.lua b/lua/nvim-tree/_meta/config/view.lua index 839f22635fe..dfcddaa0449 100644 --- a/lua/nvim-tree/_meta/config/view.lua +++ b/lua/nvim-tree/_meta/config/view.lua @@ -1,8 +1,13 @@ ---@meta error("Cannot require a meta file") + + ---@alias nvim_tree.Config.View.WidthSpec string|integer|(fun(): integer|string) + + +---@brief ---Configures the dimensions and appearance of the nvim-tree window. --- ---The window is "docked" at the left by default, however may be configured to float: [nvim_tree.Config.View.Float] @@ -10,10 +15,12 @@ error("Cannot require a meta file") ---{width} can be a [nvim_tree.Config.View.WidthSpec] for simple static control or a [nvim_tree.Config.View.Width] for fully dynamic control based on longest line. --- ---[nvim_tree.Config.View.WidthSpec]() ----- string: `x%` string e.g. `30%` ----- integer: number of columns ----- function: returns one of the above ---- +---- `string`: `x%` string e.g. `30%` +---- `integer`: number of columns +---- `function`: returns one of the above + + + ---@class nvim_tree.Config.View --- ---When entering nvim-tree, reposition the view so that the current node is initially centralized, see [zz]. @@ -58,6 +65,7 @@ error("Cannot require a meta file") ---@field float? nvim_tree.Config.View.Float + ---Configure dynamic width based on longest line. --- ---@class nvim_tree.Config.View.Width @@ -78,6 +86,7 @@ error("Cannot require a meta file") ---@field padding? nvim_tree.Config.View.WidthSpec + ---Configure floating window behaviour --- ---{open_win_config} is passed directly to [nvim_open_win()], default: diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua index a0ce0ee4ea6..72271a4be63 100644 --- a/scripts/gen_vimdoc_config.lua +++ b/scripts/gen_vimdoc_config.lua @@ -25,6 +25,7 @@ local modules = { { helptag = "nvim-tree-config-trash", title = "Class: Config.Trash", path = "lua/nvim-tree/_meta/config/trash.lua", }, { helptag = "nvim-tree-config-tab", title = "Class: Config.Tab", path = "lua/nvim-tree/_meta/config/tab.lua", }, { helptag = "nvim-tree-config-notify", title = "Class: Config.Notify", path = "lua/nvim-tree/_meta/config/notify.lua", }, + { helptag = "nvim-tree-config-bookmarks", title = "Class: Config.Bookmarks", path = "lua/nvim-tree/_meta/config/bookmarks.lua", }, { helptag = "nvim-tree-config-help", title = "Class: Config.Help", path = "lua/nvim-tree/_meta/config/help.lua", }, { helptag = "nvim-tree-config-ui", title = "Class: Config.UI", path = "lua/nvim-tree/_meta/config/ui.lua", name = "UI", }, { helptag = "nvim-tree-config-log", title = "Class: Config.Log", path = "lua/nvim-tree/_meta/config/log.lua", }, From bb53ccd62b0ac171f27d567e9aaed118cfe042a6 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 13 Jan 2026 12:06:41 +1100 Subject: [PATCH 056/170] docs(#2934): move hidden display to verbatim new section --- doc/nvim-tree-lua.txt | 60 ++++++++++++++++++++----- lua/nvim-tree/_meta/config/renderer.lua | 9 +--- 2 files changed, 49 insertions(+), 20 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index f815a00bc08..e28401ed142 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -37,6 +37,7 @@ CONTENTS 14. Legacy |nvim-tree-legacy| 14.1 Legacy: Opts |nvim-tree-legacy-opts| 14.2 Legacy: Highlight |nvim-tree-legacy-highlight| + 15. Hidden Display |nvim-tree-hidden-display| ============================================================================== 1. INTRODUCTION *nvim-tree-introduction* @@ -2040,6 +2041,51 @@ highlight group is not, hard linking as follows: > NvimTreeLspDiagnosticsHintFolderText NvimTreeDiagnosticHintFolderHL < +============================================================================== + 15. HIDDEN DISPLAY *nvim-tree-hidden-display* + +Show a summary of hidden files below the tree highlighted with `NvimTreeHiddenDisplay + +Configure via |nvim_tree.Config.Renderer| {hidden_display} + + *nvim_tree.Config.Renderer.HiddenDisplay* + • `none`: disabled + • `simple`: show how many hidden files are in a folder + • `all`: show how many hidden and the number of hidden files by reason + • `fun(hidden_stats: table): string`: returns a summary of hidden stats + +Example `"all"`: +If a folder has 14 hidden items for various reasons, the display might show: > + (14 total git: 5, dotfile: 9) +< +If a function is provided, it receives a table `hidden_stats` where keys are +reasons and values are the count of hidden files for that reason. + +The `hidden_stats` argument is structured as follows, where is the number +of hidden files related to the field: > + hidden_stats = { + bookmark = , + buf = , + custom = , + dotfile = , + git = , + live_filter = , + } +< +Example of function that can be passed: >lua + function(hidden_stats) + local total_count = 0 + for reason, count in pairs(hidden_stats) do + total_count = total_count + count + end + + if total_count > 0 then + return "(" .. tostring(total_count) .. " hidden)" + end + return nil + end +< + ============================================================================== Class: Config *nvim-tree-config* @@ -2280,16 +2326,6 @@ Controls the appearance of the tree. end < -TODO: link / move to hidden display help section - *nvim_tree.Config.Renderer.HiddenDisplay* - -{hidden_display} summary of hidden files below the tree. -• `none`: disabled -• `simple`: show how many hidden files are in a folder -• `all`: show how many hidden and the number of hidden files by reason -• `fun(hidden_stats: table): string`: returns a summary of - hidden stats - *nvim_tree.Config.Renderer* @@ -2309,8 +2345,8 @@ TODO: link / move to hidden display help section (default: `":~:s?$?/..?"`) • {indent_width}? (`integer`, default: `2`) Number of spaces for each tree nesting level. Minimum 1. - • {hidden_display}? (`nvim_tree.Config.Renderer.HiddenDisplay`) - (default: `none`) + • {hidden_display}? (`nvim_tree.Config.Renderer.HiddenDisplay`, default: `none`) + |nvim-tree-hidden-display| • {symlink_destination}? (`boolean`, default: `true`) Appends an arrow followed by the target of the symlink. diff --git a/lua/nvim-tree/_meta/config/renderer.lua b/lua/nvim-tree/_meta/config/renderer.lua index 049fd219a59..f3174865dd6 100644 --- a/lua/nvim-tree/_meta/config/renderer.lua +++ b/lua/nvim-tree/_meta/config/renderer.lua @@ -29,14 +29,6 @@ error("Cannot require a meta file") --- return ".../" .. vim.fn.fnamemodify(path, ":t") ---end ---``` ---- ----TODO: link / move to hidden display help section [nvim_tree.Config.Renderer.HiddenDisplay]() ---- ----{hidden_display} summary of hidden files below the tree. ----- `none`: disabled ----- `simple`: show how many hidden files are in a folder ----- `all`: show how many hidden and the number of hidden files by reason ----- `fun(hidden_stats: table): string`: returns a summary of hidden stats @@ -61,6 +53,7 @@ error("Cannot require a meta file") ---(default: `2`) ---@field indent_width? integer --- +---[nvim-tree-hidden-display] ---(default: `none`) ---@field hidden_display? nvim_tree.Config.Renderer.HiddenDisplay --- From 59d69462e14d5c48f6f3f6aea8551afa33c7ef5b Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 13 Jan 2026 12:30:38 +1100 Subject: [PATCH 057/170] docs(#2934): add config lsp examples, link setup --- doc/nvim-tree-lua.txt | 23 +++++++++++++++++++++-- lua/nvim-tree/_meta/config.lua | 28 +++++++++++++++++++++++++--- 2 files changed, 46 insertions(+), 5 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index e28401ed142..287950ef4be 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -95,7 +95,8 @@ Disabling |netrw| is strongly advised, see |nvim-tree-netrw| ============================================================================== 2.1 QUICKSTART: SETUP *nvim-tree-quickstart-setup* -Setup the plugin in your `init.lua` e.g. >lua +Setup the plugin in your `init.lua`, passing |nvim_tree.Config| +e.g. >lua -- disable netrw at the very start of your init.lua vim.g.loaded_netrw = 1 @@ -2089,8 +2090,26 @@ Example of function that can be passed: >lua ============================================================================== Class: Config *nvim-tree-config* +Arguments to pass to |nvim-tree-setup|. + +They can be validated by |lsp| when passed directly e.g. >lua + require("nvim-tree").setup({ + hijack_cursor = true, + }) +< + +or as a typed variable e.g. >lua + ---@type nvim_tree.Config + local config = { + hijack_cursor = true, + } + require("nvim-tree").setup(config) +< + +When a value is not present/nil, the default will be used. + + *nvim_tree.Config* - TODO #2934 brief, some links to setup etc., lsp hint Fields: ~ • {on_attach}? (`string|(fun(bufnr: integer))`) Runs when diff --git a/lua/nvim-tree/_meta/config.lua b/lua/nvim-tree/_meta/config.lua index 2986059493a..01741b079c7 100644 --- a/lua/nvim-tree/_meta/config.lua +++ b/lua/nvim-tree/_meta/config.lua @@ -1,9 +1,31 @@ ---@meta error("Cannot require a meta file") ---- TODO #2934 brief, some links to setup etc., lsp hint ---- ---- + +---@brief +--- +---Arguments to pass to [nvim-tree-setup]. +--- +---They can be validated by |lsp| when passed directly e.g. +---```lua +--- require("nvim-tree").setup({ +--- hijack_cursor = true, +--- }) +---``` +--- +---or as a typed variable e.g. +---```lua +--- ---@type nvim_tree.Config +--- local config = { +--- hijack_cursor = true, +--- } +--- require("nvim-tree").setup(config) +---``` +--- +---When a value is not present/nil, the default will be used. + + + ---@class nvim_tree.Config --- ---Runs when creating the nvim-tree buffer. Use this to set your [nvim-tree-mappings]. When `on_attach` is not a function, [nvim-tree-mappings-default] will be called. From a66e30a092a157300709aa8fba40c12afc417f84 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 13 Jan 2026 16:42:18 +1100 Subject: [PATCH 058/170] docs(#2934): normalise heading formatting, remove TOC --- doc/nvim-tree-lua.txt | 114 ++++++++++++++---------------------------- 1 file changed, 38 insertions(+), 76 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 287950ef4be..1d792adbd99 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -1,46 +1,11 @@ -*nvim-tree* A File Explorer For Nvim +*nvim-tree-lua.txt* A File Explorer For Nvim *nvim-tree* Author: Yazdani Kiyan -============================================================================== -CONTENTS - - 1. Introduction |nvim-tree-introduction| - 2. Quickstart |nvim-tree-quickstart| - 2.1 Quickstart: Setup |nvim-tree-quickstart-setup| - 2.2 Quickstart: Help |nvim-tree-quickstart-help| - 2.3 Quickstart: Custom Mappings |nvim-tree-quickstart-custom-mappings| - 2.4 Quickstart: Highlight |nvim-tree-quickstart-highlight| - 3. Commands |nvim-tree-commands| - 4. Setup |nvim-tree-setup| - 6. API |nvim-tree-api| - 6.1 API Tree |nvim-tree-api.tree| - 6.2 API File System |nvim-tree-api.fs| - 6.3 API Node |nvim-tree-api.node| - 6.4 API Git |nvim-tree-api.git| - 6.5 API Events |nvim-tree-api.events| - 6.6 API Live Filter |nvim-tree-api.live_filter| - 6.7 API Marks |nvim-tree-api.marks| - 6.8 API Config |nvim-tree-api.config| - 6.9 API Commands |nvim-tree-api.commands| - 6.10 API Diagnostics |nvim-tree-api.diagnostics| - 7. Mappings |nvim-tree-mappings| - 7.1 Mappings: Default |nvim-tree-mappings-default| - 8. Highlight |nvim-tree-highlight| - 8.1 Highlight: Default |nvim-tree-highlight-default| - 9. Events |nvim-tree-events| - 10. Prompts |nvim-tree-prompts| - 11. Decorators |nvim-tree-decorators| - 11.1 Decorator Example |nvim-tree-decorator-example| - 12. OS Specific Restrictions |nvim-tree-os-specific| - 13. Netrw |nvim-tree-netrw| - 14. Legacy |nvim-tree-legacy| - 14.1 Legacy: Opts |nvim-tree-legacy-opts| - 14.2 Legacy: Highlight |nvim-tree-legacy-highlight| - 15. Hidden Display |nvim-tree-hidden-display| + Type |gO| to see the table of contents. ============================================================================== - 1. INTRODUCTION *nvim-tree-introduction* +Introduction *nvim-tree-introduction* Features @@ -81,10 +46,10 @@ Git Integration Requirements - This file explorer requires Nvim >= 0.9 + Nvim >= 0.9 ============================================================================== - 2. QUICKSTART *nvim-tree-quickstart* +Quickstart *nvim-tree-quickstart* Install the plugins via your package manager: `"nvim-tree/nvim-tree.lua"` @@ -93,7 +58,7 @@ Install the plugins via your package manager: Disabling |netrw| is strongly advised, see |nvim-tree-netrw| ============================================================================== - 2.1 QUICKSTART: SETUP *nvim-tree-quickstart-setup* +Quickstart: Setup *nvim-tree-quickstart-setup* Setup the plugin in your `init.lua`, passing |nvim_tree.Config| e.g. >lua @@ -125,7 +90,7 @@ e.g. >lua }) < ============================================================================== - 2.2 QUICKSTART: HELP *nvim-tree-quickstart-help* +Quickstart: Help *nvim-tree-quickstart-help* Open the tree: `:NvimTreeOpen` @@ -191,7 +156,7 @@ Show the mappings: `g?` `<2-RightMouse>` CD |nvim-tree-api.tree.change_root_to_node()| ============================================================================== - 2.3 QUICKSTART: CUSTOM MAPPINGS *nvim-tree-quickstart-custom-mappings* +Quickstart: Custom Mappings *nvim-tree-quickstart-custom-mappings* |nvim-tree-mappings-default| are applied by default however you may customise via |nvim_tree.Config| {on_attach} e.g. >lua @@ -219,7 +184,7 @@ via |nvim_tree.Config| {on_attach} e.g. >lua } < ============================================================================== - 2.4 QUICKSTART: HIGHLIGHT *nvim-tree-quickstart-highlight* +Quickstart: Highlight *nvim-tree-quickstart-highlight* Run |:NvimTreeHiTest| to show all the highlights that nvim-tree uses. @@ -236,7 +201,7 @@ applied at runtime. e.g. >lua See |nvim-tree-highlight| for details. ============================================================================== - 3. COMMANDS *nvim-tree-commands* +Commands *nvim-tree-commands* *:NvimTreeOpen* @@ -338,7 +303,7 @@ See |nvim-tree-highlight| for details. Calls: `api.diagnostics.hi_test()` ============================================================================== - 4. SETUP *nvim-tree-setup* +Setup *nvim-tree-setup* You must run setup() function once to initialise nvim-tree. It may be called again to apply a change in configuration without restarting Nvim. @@ -639,7 +604,7 @@ Following is the default configuration. See |nvim_tree.Config| for details. >lua < ============================================================================== - 6. API *nvim-tree-api* +API *nvim-tree-api* Nvim-tree's public API can be used to access features. e.g. >lua local api = require("nvim-tree.api") @@ -655,7 +620,7 @@ Functions accepting {node} as their first argument will use the node under the cursor when that argument is not present or nil. ============================================================================== - 6.1 API TREE *nvim-tree-api.tree* +API: Tree *nvim-tree-api.tree* tree.open({opts}) *nvim-tree-api.tree.open()* Open the tree, focusing it if already open. @@ -859,7 +824,7 @@ tree.winid({opts}) *nvim-tree-api.tree.winid()* (number) winid or nil if tree is not visible ============================================================================== - 6.2 API FILE SYSTEM *nvim-tree-api.fs* +API: File System *nvim-tree-api.fs* fs.create({node}) *nvim-tree-api.fs.create()* Prompt to create a file or directory. Use a trailing `/` for a directory. @@ -961,12 +926,9 @@ fs.print_clipboard() *nvim-tree-api.fs.print_clipboard()* Print the contents of the nvim-tree clipboard. ============================================================================== - 6.3 API NODE *nvim-tree-api.node* - -Parameters: ~ - • {node} (Node|nil) file or folder +API: Node *nvim-tree-api.node* -node.open.edit({node}, {opts}) *nvim-tree-api.node.open.edit()* +node.open.edit({node}, {opts}) *nvim-tree-api.node.open.edit()* File: open as per |nvim_tree.Config.Actions.OpenFile| Folder: expand or collapse Root: change directory up @@ -1245,13 +1207,13 @@ node.collapse({node}, {opts}) *nvim-tree-api.node.collapse()* • {keep_buffers} (boolean) do not collapse nodes with open buffers. ============================================================================== - 6.4 API GIT *nvim-tree-api.git* +API: Git *nvim-tree-api.git* git.reload() *nvim-tree-api.git.reload()* Update the git status of the entire tree. ============================================================================== - 6.5 API EVENTS *nvim-tree-api.events* +API: Events *nvim-tree-api.events* *nvim-tree-api.events.subscribe()* events.subscribe({event_type}, {callback}) @@ -1266,7 +1228,7 @@ events.Event *nvim-tree-api.events.Event* ============================================================================== - 6.6 API LIVE FILTER *nvim-tree-api.live_filter* +API: Live Filter *nvim-tree-api.live_filter* live_filter.start() *nvim-tree-api.live_filter.start()* Enter |nvim-tree-api.live_filter| mode. @@ -1276,7 +1238,7 @@ live_filter.clear() *nvim-tree-api.live_filter.clear()* Exit |nvim-tree-api.live_filter| mode. ============================================================================== - 6.7 API MARKS *nvim-tree-api.marks* +API: Marks *nvim-tree-api.marks* marks.get({node}) *nvim-tree-api.marks.get()* Return the node if it is marked. @@ -1321,7 +1283,7 @@ marks.navigate.select() *nvim-tree-api.marks.navigate.select()* A folder will be focused, a file will be opened. ============================================================================== - 6.8 API CONFIG *nvim-tree-api.config* +API: Config *nvim-tree-api.config* *nvim-tree-api.config.mappings.default_on_attach()* config.mappings.default_on_attach({bufnr}) @@ -1348,7 +1310,7 @@ config.mappings.get_keymap_default() (table) as per |nvim_buf_get_keymap()| ============================================================================== - 6.9 API COMMANDS *nvim-tree-api.commands* +API: Commands *nvim-tree-api.commands* commands.get() *nvim-tree-api.commands.get()* Retrieve all commands, see |nvim-tree-commands| @@ -1360,7 +1322,7 @@ commands.get() *nvim-tree-api.commands.get()* • {opts} (table) ============================================================================== - 6.10 DIAGNOSTICS *nvim-tree-api.diagnostics* +API: Diagnostics *nvim-tree-api.diagnostics* diagnostics.hi_test() *nvim-tree-api.diagnostics.hi_test()* Open a new buffer displaying all nvim-tree highlight groups, their link @@ -1369,7 +1331,7 @@ diagnostics.hi_test() *nvim-tree-api.diagnostics.hi_test()* Similar to `:so $VIMRUNTIME/syntax/hitest.vim` as per |:highlight| ============================================================================== - 7. MAPPINGS *nvim-tree-mappings* +Mappings *nvim-tree-mappings* Mappings are set via the |nvim_tree.Config| {on_attach} function, which is run upon creating the nvim-tree buffer. Mappings are usually |nvim-tree-api| functions @@ -1431,7 +1393,7 @@ define your own function to map complex functionality e.g. >lua vim.keymap.set("n", "", print_node_path, opts("Print Path")) < ============================================================================== - 7.1 MAPPINGS: DEFAULT *nvim-tree-mappings-default* +Mappings: Default *nvim-tree-mappings-default* In the absence of an |nvim_tree.Config| {on_attach} function, the following defaults will be applied. @@ -1521,7 +1483,7 @@ Alternatively, you may apply these default mappings from your |nvim_tree.Config| end < ============================================================================== - 8. HIGHLIGHT *nvim-tree-highlight* +Highlight *nvim-tree-highlight* All the following highlight groups can be configured by hand. Aside from `NvimTreeWindowPicker`, it is not advised to colorize the background of these @@ -1554,7 +1516,7 @@ To prevent usage of a highlight: :hi! link NvimTreeExecFile NONE < ============================================================================== - 8.1 HIGHLIGHT: DEFAULT *nvim-tree-highlight-default* +Highlight: Default *nvim-tree-highlight-default* |:highlight-link| `default` or |:highlight-default| define the groups on setup: @@ -1680,7 +1642,7 @@ Diagnostics Folder Highlight: > NvimTreeDiagnosticHintFolderHL NvimTreeDiagnosticHintFileHL < ============================================================================== - 9. EVENTS *nvim-tree-events* +Events *nvim-tree-events* nvim-tree will dispatch events whenever an action is made. These events can be subscribed to through handler functions. This allows for even further @@ -1801,7 +1763,7 @@ Example subscription: >lua }) < ============================================================================== - 10. PROMPTS *nvim-tree-prompts* +Prompts *nvim-tree-prompts* Some NvimTree actions use the builtin |vim.ui.select()| prompt API for confirmations when the |nvim_tree.Config| {select_prompts} option is set. @@ -1826,7 +1788,7 @@ configurations for different types of prompts. send all bookmarked to trash during |nvim-tree-api.marks.bulk.trash()| ============================================================================== - 11. DECORATORS *nvim-tree-decorators* +Decorators *nvim-tree-decorators* Highlighting and icons for nodes are provided by Decorators. You may provide your own in addition to the builtin decorators. @@ -1842,7 +1804,7 @@ precedence via |nvim_tree.Config.Renderer| {decorators} See |nvim-tree-decorator-example| ============================================================================== - 11.1. DECORATOR EXAMPLE *nvim-tree-decorator-example* +Decorators: Example *nvim-tree-decorator-example* A decorator class for nodes named "example", overridind all builtin decorators except for Cut. @@ -1937,7 +1899,7 @@ Contents of `my-decorator.lua`: return MyDecorator < ============================================================================== - 12. OS SPECIFIC RESTRICTIONS *nvim-tree-os-specific* +OS Specific Restrictions *nvim-tree-os-specific* Windows WSL and PowerShell - Trash is synchronized @@ -1946,7 +1908,7 @@ Windows WSL and PowerShell - Some filesystem watcher error related to permissions will not be reported ============================================================================== - 13. NETRW *nvim-tree-netrw* +netrw *nvim-tree-netrw* |netrw| is a standard Nvim plugin that is enabled by default. It provides, amongst other functionality, a file/directory browser. @@ -1967,16 +1929,16 @@ keep using |netrw| without its browser features please ensure: |nvim_tree.Config| {hijack_netrw}` = true` ============================================================================== - 14. LEGACY *nvim-tree-legacy* +Legacy *nvim-tree-legacy* Breaking refactors have been made however the legacy versions will be silently migrated and used. There are no plans to remove this migration. ============================================================================== - 14.1 LEGACY: OPTS *nvim-tree-legacy-opts* +Legacy: Config *nvim-tree-legacy-opts* -Legacy options are translated to the current, making type and value changes as +Legacy config is translated to the current, making type and value changes as needed. `update_cwd` |nvim_tree.Config| {sync_root_with_cwd} @@ -1993,7 +1955,7 @@ needed. `renderer.icons.padding` |nvim_tree.Config.Renderer.Icons.Padding| {icon} ============================================================================== - 14.2 LEGACY: HIGHLIGHT *nvim-tree-legacy-highlight* +Legacy: Highlight *nvim-tree-legacy-highlight* Legacy highlight group are still obeyed when they are defined and the current highlight group is not, hard linking as follows: > @@ -2043,7 +2005,7 @@ highlight group is not, hard linking as follows: > < ============================================================================== - 15. HIDDEN DISPLAY *nvim-tree-hidden-display* +Hidden Display *nvim-tree-hidden-display* Show a summary of hidden files below the tree highlighted with `NvimTreeHiddenDisplay From 71c7ed4ec50cf6bd5665280c47e23991471b41c7 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Wed, 14 Jan 2026 12:55:25 +1100 Subject: [PATCH 059/170] docs(#2934): move all icon and highlight info into a table --- doc/nvim-tree-lua.txt | 103 +++++++++--------------- lua/nvim-tree/_meta/config/renderer.lua | 100 +++++++++-------------- lua/nvim-tree/_meta/config/sort.lua | 1 - 3 files changed, 79 insertions(+), 125 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 1d792adbd99..09f7337438c 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -2291,6 +2291,21 @@ Class: Config.Renderer *nvim-tree-config-renderer* Controls the appearance of the tree. + +Icons and highlighting in ascending order of precedence: + +|nvim_tree.Config.Renderer.Icons.Show| Requires |nvim_tree.Config.Renderer.Icons| |nvim_tree.Config.Renderer| Devicons? Highlight Icon(s) +{file} - - - yes `NvimTreeNo*`, `NvimTreeFile*` |nvim_tree.Config.Renderer.Icons.Glyphs| {default} +{folder} - - - yes `NvimTree*Folder*` |nvim_tree.Config.Renderer.Icons.Glyphs.Folder| +{git} |nvim_tree.Config.Git| {git_placement} {highlight_git} yes `NvimTreeGit*` |nvim_tree.Config.Renderer.Icons.Glyphs.Git| + - - - {highlight_opened_files} no `NvimTreeOpened*` - +{hidden} - {hidden_placement} {highlight_hidden} no `NvimTreeHidden*` |nvim_tree.Config.Renderer.Icons.Glyphs| {hidden} +{modified} |nvim_tree.Config.Modified| {modified_placement} {highlight_modified} no `NvimTreeModified*` |nvim_tree.Config.Renderer.Icons.Glyphs| {modified} +{bookmarks} - {bookmarks_placement} {highlight_bookmarks} no `NvimTreeBookmark*` |nvim_tree.Config.Renderer.Icons.Glyphs| {bookmark} +{diagnostics} |nvim_tree.Config.Diagnostics| {diagnostics_placement} {highlight_diagnostics} no `NvimTreeDiagnostic*` |nvim_tree.Config.Diagnostics.Icons| + - - - {highlight_clipboard} no `NvimTreeC*HL` - + + {highlight_} options *nvim_tree.Config.Renderer.HighlightPlacement* • `none`: no highlighting • `icon`: icon only @@ -2298,7 +2313,7 @@ Controls the appearance of the tree. • `all`: icon and name {root_folder_label} has 3 forms: -• `string`: |filename-modifiers| format string +• `string`: |filename-modifiers| format string, default `":~:s?$?/..?"` • `boolean`: `true` to disable • `fun(root_cwd: string): string`: return a literal string from root's absolute path e.g. >lua @@ -2337,25 +2352,22 @@ Controls the appearance of the tree. specify builtin decorators. See |nvim-tree-decorators|. • {highlight_git}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) - Git status: `NvimTreeGit*HL`. Requires - |nvim_tree.Config.Git|. + Git status. • {highlight_opened_files}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) - |bufloaded()| files: `NvimTreeOpenedHL`. + |bufloaded()| files. • {highlight_hidden}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) - Hidden (dotfiles): `NvimTreeHiddenFileHL`. + Hidden (dotfiles) files and directories. • {highlight_modified}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) - Modified files: `NvimTreeModifiedFile`. - Requires |nvim_tree.Config.Modified|. + Modified files. • {highlight_bookmarks}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) - Bookmarked: `NvimTreeBookmarkHL`. + Bookmarked files and directories. • {highlight_diagnostics}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) - Diagnostic status: `NvimTreeDiagnostic*HL`. - Requires |nvim_tree.Config.Diagnostics|. + Diagnostic status. • {highlight_clipboard}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `name`) - Copied: `NvimTreeCopiedHL`, cut: - `NvimTreeCutHL`. + Copied and cut. • {special_files}? (`string[]`, default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }`) - Sepcial files: `NvimTreeSpecialFile`. + Highlight special files and directories + with `NvimTreeSpecial*`. • {indent_markers}? (`nvim_tree.Config.Renderer.IndentMarkers`) |nvim_tree.Config.Renderer.IndentMarkers| • {icons}? (`nvim_tree.Config.Renderer.Icons`) @@ -2402,19 +2414,13 @@ Controls the appearance of the tree. *nvim_tree.Config.Renderer.Icons.Glyphs* Glyphs that appear in the sign column must have length <= 2 - Glyphs defined elsewhere: - • |nvim_tree.Config.Diagnostics.Icons| - • |nvim_tree.Config.Renderer.IndentMarkers.Icons| - Fields: ~ - • {default}? (`string`, default: `` ) Files, overridden by - |nvim_tree.Config.Renderer.Icons.WebDevicons|. + • {default}? (`string`, default: `` ) Files • {symlink}? (`string`) (default: `` ) • {bookmark}? (`string`) (default: `󰆤` ) • {modified}? (`string`) (default: `●` ) • {hidden}? (`string`) (default: `󰜌` ) - • {folder}? (`table`) Overridden by - |nvim_tree.Config.Renderer.Icons.WebDevicons|. *nvim_tree.Config.Renderer.Icons.Glyphs.Folder* + • {folder}? (`table`) *nvim_tree.Config.Renderer.Icons.Glyphs.Folder* • {arrow_closed}? (`string`) (default: left arrow) • {arrow_open}? (`string`) (default: down arrow) • {default}? (`string`) (default: `` ) @@ -2423,8 +2429,7 @@ Controls the appearance of the tree. • {empty_open}? (`string`) (default: `` ) • {symlink}? (`string`) (default: `` ) • {symlink_open}? (`string`) (default: `` ) - • {git}? (`table`) Git status on files and - directories. *nvim_tree.Config.Renderer.Icons.Glyphs.Git* + • {git}? (`table`) *nvim_tree.Config.Renderer.Icons.Glyphs.Git* • {unstaged}? (`string`) (default: `✗` ) • {staged}? (`string`) (default: `✓` ) • {unmerged}? (`string`) (default: `` ) @@ -2436,61 +2441,31 @@ Controls the appearance of the tree. *nvim_tree.Config.Renderer.Icons.Show* Control which icons are displayed. - Left to right ordered: - • {file} - • {folder} - • {git} - • {modified} - • {hidden} - • {diagnostics} - • {bookmarks} - Fields: ~ - • {file}? (`boolean`, default: `true`) Before file name. - • {folder}? (`boolean`, default: `true`) Before folder name. + • {file}? (`boolean`) (default: `true`) + • {folder}? (`boolean`) (default: `true`) + • {git}? (`boolean`) (default: `true`) + • {modified}? (`boolean`) (default: `true`) + • {hidden}? (`boolean`) (default: `false`) + • {diagnostics}? (`boolean`) (default: `true`) + • {bookmarks}? (`boolean`) (default: `true`) • {folder_arrow}? (`boolean`, default: `true`) Show a small arrow before the folder node. Arrow will be a part of the node when using |nvim_tree.Config.Renderer.IndentMarkers|. - • {git}? (`boolean`, default: `true`) Location: - |nvim_tree.Config.Renderer.Icons| {git_placement}. - Icons: |nvim_tree.Config.Renderer.Icons.Glyphs.Git|. - Requires |nvim_tree.Config.Git|. - • {modified}? (`boolean`, default: `true`) Location: - |nvim_tree.Config.Renderer.Icons| - {modified_placement}. Requires - |nvim_tree.Config.Modified|. - • {hidden}? (`boolean`, default: `false`) Location: - |nvim_tree.Config.Renderer.Icons| {hidden_placement}. - • {diagnostics}? (`boolean`, default: `true`) Location: - |nvim_tree.Config.Renderer.Icons| - {diagnostics_placement}. Icons: - |nvim_tree.Config.Diagnostics.Icons|. Requires - |nvim_tree.Config.Diagnostics|. - • {bookmarks}? (`boolean`, default: `true`) Location: - |nvim_tree.Config.Renderer.Icons| - {bookmarks_placement}. *nvim_tree.Config.Renderer.Icons.WebDevicons* Configure optional plugin `nvim-tree/nvim-web-devicons`. - Overrides glyphs and highlight groups where noted. - Fields: ~ • {file}? (`table`) *nvim_tree.Config.Renderer.Icons.WebDevicons.File* - • {enable}? (`boolean`, default: `true`) Show icons for - files, overrides - |nvim_tree.Config.Renderer.Icons.Glyphs.Git|. - • {color}? (`boolean`, default: `true`) Apply colours to - files, overrides `NvimTreeFileIcon`. + • {enable}? (`boolean`) (default: `true`) + • {color}? (`boolean`) (default: `true`) • {folder}? (`table`) *nvim_tree.Config.Renderer.Icons.WebDevicons.Folder* - • {enable}? (`boolean`, default: `false`) Show icons for - directories, overrides - |nvim_tree.Config.Renderer.Icons.Glyphs.Folder|. - • {color}? (`boolean`, default: `true`) Apply colors to - directories, overrides `NvimTree*FolderName`. + • {enable}? (`boolean`) (default: `false`) + • {color}? (`boolean`) (default: `true`) *nvim_tree.Config.Renderer.IndentMarkers* diff --git a/lua/nvim-tree/_meta/config/renderer.lua b/lua/nvim-tree/_meta/config/renderer.lua index f3174865dd6..9bf6522e057 100644 --- a/lua/nvim-tree/_meta/config/renderer.lua +++ b/lua/nvim-tree/_meta/config/renderer.lua @@ -14,6 +14,22 @@ error("Cannot require a meta file") ---@brief ---Controls the appearance of the tree. --- +---
help
+---Icons and highlighting in ascending order of precedence:
+---
+--- |nvim_tree.Config.Renderer.Icons.Show|  Requires                      |nvim_tree.Config.Renderer.Icons|  |nvim_tree.Config.Renderer|  Devicons?  Highlight                   Icon(s)
+--- {file}                                 -                             -                                -                         yes        `NvimTreeNo*`, `NvimTreeFile*`  |nvim_tree.Config.Renderer.Icons.Glyphs| {default}
+--- {folder}                               -                             -                                -                         yes        `NvimTree*Folder*`            |nvim_tree.Config.Renderer.Icons.Glyphs.Folder|
+--- {git}                                 |nvim_tree.Config.Git|          {git_placement}                  {highlight_git}            yes        `NvimTreeGit*`                |nvim_tree.Config.Renderer.Icons.Glyphs.Git|
+---  -                                     -                             -                               {highlight_opened_files}   no         `NvimTreeOpened*`              -
+--- {hidden}                               -                            {hidden_placement}               {highlight_hidden}         no         `NvimTreeHidden*`             |nvim_tree.Config.Renderer.Icons.Glyphs| {hidden}
+--- {modified}                            |nvim_tree.Config.Modified|     {modified_placement}             {highlight_modified}       no         `NvimTreeModified*`           |nvim_tree.Config.Renderer.Icons.Glyphs| {modified}
+--- {bookmarks}                            -                            {bookmarks_placement}            {highlight_bookmarks}      no         `NvimTreeBookmark*`           |nvim_tree.Config.Renderer.Icons.Glyphs| {bookmark}
+--- {diagnostics}                         |nvim_tree.Config.Diagnostics|  {diagnostics_placement}          {highlight_diagnostics}    no         `NvimTreeDiagnostic*`         |nvim_tree.Config.Diagnostics.Icons|
+---  -                                     -                             -                               {highlight_clipboard}      no         `NvimTreeC*HL`                 -
+---
+---
+--- ---{highlight_} options [nvim_tree.Config.Renderer.HighlightPlacement]() ---- `none`: no highlighting ---- `icon`: icon only @@ -21,7 +37,7 @@ error("Cannot require a meta file") ---- `all`: icon and name --- ---{root_folder_label} has 3 forms: ----- `string`: [filename-modifiers] format string +---- `string`: [filename-modifiers] format string, default `":~:s?$?/..?"` ---- `boolean`: `true` to disable ---- `fun(root_cwd: string): string`: return a literal string from root's absolute path e.g. ---```lua @@ -65,38 +81,35 @@ error("Cannot require a meta file") ---(default: `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) ---@field decorators? (string|nvim_tree.api.decorator.UserDecorator)[] --- ----Git status: `NvimTreeGit*HL`. ----Requires [nvim_tree.Config.Git]. +---Git status. ---(default: `none`) ---@field highlight_git? nvim_tree.Config.Renderer.HighlightPlacement --- ----[bufloaded()] files: `NvimTreeOpenedHL`. +---[bufloaded()] files. ---(default: `none`) ---@field highlight_opened_files? nvim_tree.Config.Renderer.HighlightPlacement --- ----Hidden (dotfiles): `NvimTreeHiddenFileHL`. +---Hidden (dotfiles) files and directories. ---(default: `none`) ----@field highlight_hidden? nvim_tree.Config.Renderer.HighlightPlacement +---@field highlight_hidden? nvim_tree.Config.Renderer.HighlightPlacement --- ----Modified files: `NvimTreeModifiedFile`. ----Requires [nvim_tree.Config.Modified]. +---Modified files. ---(default: `none`) ---@field highlight_modified? nvim_tree.Config.Renderer.HighlightPlacement --- ----Bookmarked: `NvimTreeBookmarkHL`. +---Bookmarked files and directories. ---(default: `none`) ---@field highlight_bookmarks? nvim_tree.Config.Renderer.HighlightPlacement --- ----Diagnostic status: `NvimTreeDiagnostic*HL`. ----Requires [nvim_tree.Config.Diagnostics]. +---Diagnostic status. ---(default: `none`) ---@field highlight_diagnostics? nvim_tree.Config.Renderer.HighlightPlacement --- ----Copied: `NvimTreeCopiedHL`, cut: `NvimTreeCutHL`. +---Copied and cut. ---(default: `name`) ---@field highlight_clipboard? nvim_tree.Config.Renderer.HighlightPlacement --- ----Sepcial files: `NvimTreeSpecialFile`. +---Highlight special files and directories with `NvimTreeSpecial*`. ---(default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }`) ---@field special_files? string[] --- @@ -111,13 +124,13 @@ error("Cannot require a meta file") --- ---Display indent markers when folders are open. ---(default: `false`) ----@field enable? boolean +---@field enable? boolean --- ---Display folder arrows in the same column as indent marker when using [nvim_tree.Config.Renderer.Icons.Padding] {folder_arrow} ---(default: `true`) ----@field inline_arrows? boolean +---@field inline_arrows? boolean --- ----@field icons? nvim_tree.Config.Renderer.IndentMarkers.Icons +---@field icons? nvim_tree.Config.Renderer.IndentMarkers.Icons @@ -127,7 +140,7 @@ error("Cannot require a meta file") ---@inlinedoc --- ---(default: `└` ) ----@field corner? string +---@field corner? string ---(default: `│` ) ---@field edge? string ---(default: `│` ) @@ -174,10 +187,10 @@ error("Cannot require a meta file") --- ---Separator between symlink source and target. ---(default: ` ➛ `) ----@field symlink_arrow? string +---@field symlink_arrow? string --- ---[nvim_tree.Config.Renderer.Icons.Show] ----@field show? nvim_tree.Config.Renderer.Icons.Show +---@field show? nvim_tree.Config.Renderer.Icons.Show --- ---[nvim_tree.Config.Renderer.Icons.Glyphs] ---@field glyphs? nvim_tree.Config.Renderer.Icons.Glyphs @@ -186,8 +199,6 @@ error("Cannot require a meta file") ---Configure optional plugin `nvim-tree/nvim-web-devicons`. --- ----Overrides glyphs and highlight groups where noted. ---- ---@class nvim_tree.Config.Renderer.Icons.WebDevicons --- ---@field file? nvim_tree.Config.Renderer.Icons.WebDevicons.File @@ -200,11 +211,9 @@ error("Cannot require a meta file") ---@class nvim_tree.Config.Renderer.Icons.WebDevicons.File ---@inlinedoc --- ----Show icons for files, overrides [nvim_tree.Config.Renderer.Icons.Glyphs.Git]. ---(default: `true`) ----@field enable? boolean +---@field enable? boolean --- ----Apply colours to files, overrides `NvimTreeFileIcon`. ---(default: `true`) ---@field color? boolean @@ -213,11 +222,9 @@ error("Cannot require a meta file") ---@class nvim_tree.Config.Renderer.Icons.WebDevicons.Folder ---@inlinedoc --- ----Show icons for directories, overrides [nvim_tree.Config.Renderer.Icons.Glyphs.Folder]. ---(default: `false`) ---@field enable? boolean --- ----Apply colors to directories, overrides `NvimTree*FolderName`. ---(default: `true`) ---@field color? boolean @@ -229,74 +236,49 @@ error("Cannot require a meta file") --- ---Between icon and filename. ---(default: ` `) ----@field icon? string +---@field icon? string --- ---Between folder arrow icon and file/folder icon. ---(default: ` `) ----@field folder_arrow? string +---@field folder_arrow? string ---Control which icons are displayed. ---- ----Left to right ordered: ----- {file} ----- {folder} ----- {git} ----- {modified} ----- {hidden} ----- {diagnostics} ----- {bookmarks} ---- ---@class nvim_tree.Config.Renderer.Icons.Show --- ----Before file name. ---(default: `true`) ---@field file? boolean --- ----Before folder name. ---(default: `true`) ---@field folder? boolean --- ----Show a small arrow before the folder node. Arrow will be a part of the node when using [nvim_tree.Config.Renderer.IndentMarkers]. ----(default: `true`) ----@field folder_arrow? boolean ---- ----Location: [nvim_tree.Config.Renderer.Icons] {git_placement}. ----Icons: [nvim_tree.Config.Renderer.Icons.Glyphs.Git]. ----Requires [nvim_tree.Config.Git]. ---(default: `true`) ---@field git? boolean --- ----Location: [nvim_tree.Config.Renderer.Icons] {modified_placement}. ----Requires [nvim_tree.Config.Modified]. ---(default: `true`) ---@field modified? boolean --- ----Location: [nvim_tree.Config.Renderer.Icons] {hidden_placement}. ---(default: `false`) ---@field hidden? boolean --- ----Location: [nvim_tree.Config.Renderer.Icons] {diagnostics_placement}. ----Icons: [nvim_tree.Config.Diagnostics.Icons]. ----Requires [nvim_tree.Config.Diagnostics]. ---(default: `true`) ---@field diagnostics? boolean --- ----Location: [nvim_tree.Config.Renderer.Icons] {bookmarks_placement}. ---(default: `true`) ---@field bookmarks? boolean +--- +---Show a small arrow before the folder node. Arrow will be a part of the node when using [nvim_tree.Config.Renderer.IndentMarkers]. +---(default: `true`) +---@field folder_arrow? boolean ---Glyphs that appear in the sign column must have length <= 2 --- ----Glyphs defined elsewhere: ----- [nvim_tree.Config.Diagnostics.Icons] ----- [nvim_tree.Config.Renderer.IndentMarkers.Icons] ---@class nvim_tree.Config.Renderer.Icons.Glyphs --- ----Files, overridden by [nvim_tree.Config.Renderer.Icons.WebDevicons]. +---Files ---(default: `` ) ---@field default? string --- @@ -312,10 +294,8 @@ error("Cannot require a meta file") ---(default: `󰜌` ) ---@field hidden? string --- ----Overridden by [nvim_tree.Config.Renderer.Icons.WebDevicons]. ---@field folder? nvim_tree.Config.Renderer.Icons.Glyphs.Folder --- ----Git status on files and directories. ---@field git? nvim_tree.Config.Renderer.Icons.Glyphs.Git diff --git a/lua/nvim-tree/_meta/config/sort.lua b/lua/nvim-tree/_meta/config/sort.lua index e1e7bb3e4cc..e33ec0f29dc 100644 --- a/lua/nvim-tree/_meta/config/sort.lua +++ b/lua/nvim-tree/_meta/config/sort.lua @@ -46,4 +46,3 @@ error("Cannot require a meta file") ---Sort files before folders. Has no effect when {sorter} is a function. Overrides {folders_first}. ---(default: `false`) ---@field files_first? boolean ---- From 531fb943c0af495342edeefd134faf43c090bead Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Wed, 14 Jan 2026 14:23:54 +1100 Subject: [PATCH 060/170] docs(#2934): move all icon and highlight info into a new section --- doc/nvim-tree-lua.txt | 131 +++++++++++++++--------- lua/nvim-tree/_meta/config/renderer.lua | 49 ++------- 2 files changed, 88 insertions(+), 92 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 09f7337438c..58e842ec99d 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -184,7 +184,7 @@ via |nvim_tree.Config| {on_attach} e.g. >lua } < ============================================================================== -Quickstart: Highlight *nvim-tree-quickstart-highlight* +Quickstart: Highlight Groups *nvim-tree-quickstart-highlight* Run |:NvimTreeHiTest| to show all the highlights that nvim-tree uses. @@ -198,7 +198,7 @@ applied at runtime. e.g. >lua :hi link NvimTreeImageFile Title ]]) < -See |nvim-tree-highlight| for details. +See |nvim-tree-highlight-groups| for details. ============================================================================== Commands *nvim-tree-commands* @@ -1482,8 +1482,66 @@ Alternatively, you may apply these default mappings from your |nvim_tree.Config| -- your removals and mappings go here end < + +============================================================================== +Icons And Highlighting *nvim-tree-icons-highlighting* + +Icons may be displayed before files and directories. + +Icons and highlighting may be displayed to indicate various states for files +and directories. + +Highlighting is additive, with higher precedence overriding lower. + + +ICON + Enable via |nvim_tree.Config.Renderer.Icons.Show + +REQUIRES + Feature must be enabled to show icons and highlighting. + +PLACEMENT *nvim_tree.Config.Renderer.Icons.Placement* + Where to place the icon: |nvim_tree.Config.Renderer.Icons| {_placement} + • `before`: before file/folder, after the file/folders icons + • `after`: after file/folder + • `signcolumn`: far left, requires |nvim_tree.Config.View| {signcolumn}. + • `right_align`: far right + +HIGHLIGHT *nvim_tree.Config.Renderer.Highlight* + What should be highlighted: |nvim_tree.Config.Renderer| {highlight_} + • `none`: no highlighting + • `icon`: icon only + • `name`: name only + • `all`: icon and name + +DEVICONS + Glyphs and their colors will be overridden by optional plugin: + `nvim-tree/nvim-web-devicons` |nvim_tree.Config.Renderer.Icons.WebDevicons| + +GLYPHS + Icon glyphs definitions. + +GROUPS + Applicable highlight groups: |nvim-tree-highlight-groups| + + +All icons and highlighting, in ascending order of highlight precedence, +some defaults noted: + +ICON REQUIRES PLACEMENT HIGHLIGHT DEVICONS GLYPHS GROUPS +{file} `Y` - - - `Y` |nvim_tree.Config.Renderer.Icons.Glyphs| {default} `NvimTreeNormal` `NvimTreeFileIcon` +{folder} `Y` - - - `Y` |nvim_tree.Config.Renderer.Icons.Glyphs.Folder| `NvimTree*FolderName` `NvimTree*FolderIcon` +{git} `Y` |nvim_tree.Config.Git| {git_placement} `before` {highlight_git} `none` `Y` |nvim_tree.Config.Renderer.Icons.Glyphs.Git| `NvimTreeGit* + - - - {highlight_opened_files} `none` `N` - `NvimTreeOpened* +{hidden} `N` - {hidden_placement} `after` {highlight_hidden} `none` `N` |nvim_tree.Config.Renderer.Icons.Glyphs| {hidden} `NvimTreeHidden*` +{modified} `Y` |nvim_tree.Config.Modified| {modified_placement} `after` {highlight_modified} `none` `N` |nvim_tree.Config.Renderer.Icons.Glyphs| {modified} `NvimTreeModified*` +{bookmarks} `Y` - {bookmarks_placement} `signcolumn` {highlight_bookmarks} `none` `N` |nvim_tree.Config.Renderer.Icons.Glyphs| {bookmark} `NvimTreeBookmark*` +{diagnostics} `Y` |nvim_tree.Config.Diagnostics| {diagnostics_placement} `signcolumn` {highlight_diagnostics} `none` `N` |nvim_tree.Config.Diagnostics.Icons| `NvimTreeDiagnostic*` + - - - {highlight_clipboard} `name` `N` - `NvimTreeCutHL` `NvimTreeCopiedHL` + + ============================================================================== -Highlight *nvim-tree-highlight* +Highlight Groups *nvim-tree-highlight-groups* All the following highlight groups can be configured by hand. Aside from `NvimTreeWindowPicker`, it is not advised to colorize the background of these @@ -1516,7 +1574,7 @@ To prevent usage of a highlight: :hi! link NvimTreeExecFile NONE < ============================================================================== -Highlight: Default *nvim-tree-highlight-default* +Highlight Groups: Default *nvim-tree-highlight-groups-default* |:highlight-link| `default` or |:highlight-default| define the groups on setup: @@ -2289,41 +2347,18 @@ line. ============================================================================== Class: Config.Renderer *nvim-tree-config-renderer* -Controls the appearance of the tree. - - -Icons and highlighting in ascending order of precedence: - -|nvim_tree.Config.Renderer.Icons.Show| Requires |nvim_tree.Config.Renderer.Icons| |nvim_tree.Config.Renderer| Devicons? Highlight Icon(s) -{file} - - - yes `NvimTreeNo*`, `NvimTreeFile*` |nvim_tree.Config.Renderer.Icons.Glyphs| {default} -{folder} - - - yes `NvimTree*Folder*` |nvim_tree.Config.Renderer.Icons.Glyphs.Folder| -{git} |nvim_tree.Config.Git| {git_placement} {highlight_git} yes `NvimTreeGit*` |nvim_tree.Config.Renderer.Icons.Glyphs.Git| - - - - {highlight_opened_files} no `NvimTreeOpened*` - -{hidden} - {hidden_placement} {highlight_hidden} no `NvimTreeHidden*` |nvim_tree.Config.Renderer.Icons.Glyphs| {hidden} -{modified} |nvim_tree.Config.Modified| {modified_placement} {highlight_modified} no `NvimTreeModified*` |nvim_tree.Config.Renderer.Icons.Glyphs| {modified} -{bookmarks} - {bookmarks_placement} {highlight_bookmarks} no `NvimTreeBookmark*` |nvim_tree.Config.Renderer.Icons.Glyphs| {bookmark} -{diagnostics} |nvim_tree.Config.Diagnostics| {diagnostics_placement} {highlight_diagnostics} no `NvimTreeDiagnostic*` |nvim_tree.Config.Diagnostics.Icons| - - - - {highlight_clipboard} no `NvimTreeC*HL` - - - -{highlight_} options *nvim_tree.Config.Renderer.HighlightPlacement* -• `none`: no highlighting -• `icon`: icon only -• `name`: name only -• `all`: icon and name - -{root_folder_label} has 3 forms: -• `string`: |filename-modifiers| format string, default `":~:s?$?/..?"` -• `boolean`: `true` to disable -• `fun(root_cwd: string): string`: return a literal string from root's - absolute path e.g. >lua - my_root_folder_label = function(path) - return ".../" .. vim.fn.fnamemodify(path, ":t") - end -< - - *nvim_tree.Config.Renderer* + Controls the appearance of the tree. + + {root_folder_label} has 3 forms: + • `string`: |filename-modifiers| format string, default `":~:s?$?/..?"` + • `boolean`: `true` to disable + • `fun(root_cwd: string): string`: return a literal string from root's + absolute path e.g. >lua + my_root_folder_label = function(path) + return ".../" .. vim.fn.fnamemodify(path, ":t") + end +< Fields: ~ • {add_trailing}? (`boolean`, default: `false`) Appends a @@ -2351,19 +2386,19 @@ Icons and highlighting in ascending order of precedence: increasing order of precedence. Strings specify builtin decorators. See |nvim-tree-decorators|. - • {highlight_git}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) + • {highlight_git}? (`nvim_tree.Config.Renderer.Highlight`, default: `none`) Git status. - • {highlight_opened_files}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) + • {highlight_opened_files}? (`nvim_tree.Config.Renderer.Highlight`, default: `none`) |bufloaded()| files. - • {highlight_hidden}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) + • {highlight_hidden}? (`nvim_tree.Config.Renderer.Highlight`, default: `none`) Hidden (dotfiles) files and directories. - • {highlight_modified}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) + • {highlight_modified}? (`nvim_tree.Config.Renderer.Highlight`, default: `none`) Modified files. - • {highlight_bookmarks}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) + • {highlight_bookmarks}? (`nvim_tree.Config.Renderer.Highlight`, default: `none`) Bookmarked files and directories. - • {highlight_diagnostics}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) + • {highlight_diagnostics}? (`nvim_tree.Config.Renderer.Highlight`, default: `none`) Diagnostic status. - • {highlight_clipboard}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `name`) + • {highlight_clipboard}? (`nvim_tree.Config.Renderer.Highlight`, default: `name`) Copied and cut. • {special_files}? (`string[]`, default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }`) Highlight special files and directories @@ -2376,12 +2411,6 @@ Icons and highlighting in ascending order of precedence: *nvim_tree.Config.Renderer.Icons* Icons and separators. - {_placement} options *nvim_tree.Config.Renderer.Icons.Placement* - • `before`: before file/folder, after the file/folders icons - • `after`: after file/folder - • `signcolumn`: far left, requires |nvim_tree.Config.View| {signcolumn}. - • `right_align`: far right - Fields: ~ • {web_devicons}? (`nvim_tree.Config.Renderer.Icons.WebDevicons`) |nvim_tree.Config.Renderer.Icons.WebDevicons| diff --git a/lua/nvim-tree/_meta/config/renderer.lua b/lua/nvim-tree/_meta/config/renderer.lua index 9bf6522e057..3ccbc27089d 100644 --- a/lua/nvim-tree/_meta/config/renderer.lua +++ b/lua/nvim-tree/_meta/config/renderer.lua @@ -3,7 +3,7 @@ error("Cannot require a meta file") ----@alias nvim_tree.Config.Renderer.HighlightPlacement "none"|"icon"|"name"|"all" +---@alias nvim_tree.Config.Renderer.Highlight "none"|"icon"|"name"|"all" ---@alias nvim_tree.Config.Renderer.HiddenDisplay "none"|"simple"|"all"|(fun(hidden_stats: table): string) @@ -11,31 +11,8 @@ error("Cannot require a meta file") ----@brief ---Controls the appearance of the tree. --- ----
help
----Icons and highlighting in ascending order of precedence:
----
---- |nvim_tree.Config.Renderer.Icons.Show|  Requires                      |nvim_tree.Config.Renderer.Icons|  |nvim_tree.Config.Renderer|  Devicons?  Highlight                   Icon(s)
---- {file}                                 -                             -                                -                         yes        `NvimTreeNo*`, `NvimTreeFile*`  |nvim_tree.Config.Renderer.Icons.Glyphs| {default}
---- {folder}                               -                             -                                -                         yes        `NvimTree*Folder*`            |nvim_tree.Config.Renderer.Icons.Glyphs.Folder|
---- {git}                                 |nvim_tree.Config.Git|          {git_placement}                  {highlight_git}            yes        `NvimTreeGit*`                |nvim_tree.Config.Renderer.Icons.Glyphs.Git|
----  -                                     -                             -                               {highlight_opened_files}   no         `NvimTreeOpened*`              -
---- {hidden}                               -                            {hidden_placement}               {highlight_hidden}         no         `NvimTreeHidden*`             |nvim_tree.Config.Renderer.Icons.Glyphs| {hidden}
---- {modified}                            |nvim_tree.Config.Modified|     {modified_placement}             {highlight_modified}       no         `NvimTreeModified*`           |nvim_tree.Config.Renderer.Icons.Glyphs| {modified}
---- {bookmarks}                            -                            {bookmarks_placement}            {highlight_bookmarks}      no         `NvimTreeBookmark*`           |nvim_tree.Config.Renderer.Icons.Glyphs| {bookmark}
---- {diagnostics}                         |nvim_tree.Config.Diagnostics|  {diagnostics_placement}          {highlight_diagnostics}    no         `NvimTreeDiagnostic*`         |nvim_tree.Config.Diagnostics.Icons|
----  -                                     -                             -                               {highlight_clipboard}      no         `NvimTreeC*HL`                 -
----
----
---- ----{highlight_} options [nvim_tree.Config.Renderer.HighlightPlacement]() ----- `none`: no highlighting ----- `icon`: icon only ----- `name`: name only ----- `all`: icon and name ---- ---{root_folder_label} has 3 forms: ---- `string`: [filename-modifiers] format string, default `":~:s?$?/..?"` ---- `boolean`: `true` to disable @@ -45,9 +22,6 @@ error("Cannot require a meta file") --- return ".../" .. vim.fn.fnamemodify(path, ":t") ---end ---``` - - - ---@class nvim_tree.Config.Renderer --- ---Appends a trailing slash to folder and symlink folder target names. @@ -83,31 +57,31 @@ error("Cannot require a meta file") --- ---Git status. ---(default: `none`) ----@field highlight_git? nvim_tree.Config.Renderer.HighlightPlacement +---@field highlight_git? nvim_tree.Config.Renderer.Highlight --- ---[bufloaded()] files. ---(default: `none`) ----@field highlight_opened_files? nvim_tree.Config.Renderer.HighlightPlacement +---@field highlight_opened_files? nvim_tree.Config.Renderer.Highlight --- ---Hidden (dotfiles) files and directories. ---(default: `none`) ----@field highlight_hidden? nvim_tree.Config.Renderer.HighlightPlacement +---@field highlight_hidden? nvim_tree.Config.Renderer.Highlight --- ---Modified files. ---(default: `none`) ----@field highlight_modified? nvim_tree.Config.Renderer.HighlightPlacement +---@field highlight_modified? nvim_tree.Config.Renderer.Highlight --- ---Bookmarked files and directories. ---(default: `none`) ----@field highlight_bookmarks? nvim_tree.Config.Renderer.HighlightPlacement +---@field highlight_bookmarks? nvim_tree.Config.Renderer.Highlight --- ---Diagnostic status. ---(default: `none`) ----@field highlight_diagnostics? nvim_tree.Config.Renderer.HighlightPlacement +---@field highlight_diagnostics? nvim_tree.Config.Renderer.Highlight --- ---Copied and cut. ---(default: `name`) ----@field highlight_clipboard? nvim_tree.Config.Renderer.HighlightPlacement +---@field highlight_clipboard? nvim_tree.Config.Renderer.Highlight --- ---Highlight special files and directories with `NvimTreeSpecial*`. ---(default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }`) @@ -153,13 +127,6 @@ error("Cannot require a meta file") ---Icons and separators. ---- ----{_placement} options [nvim_tree.Config.Renderer.Icons.Placement]() ----- `before`: before file/folder, after the file/folders icons ----- `after`: after file/folder ----- `signcolumn`: far left, requires [nvim_tree.Config.View] {signcolumn}. ----- `right_align`: far right ---- ---@class nvim_tree.Config.Renderer.Icons --- ---[nvim_tree.Config.Renderer.Icons.WebDevicons] From 5538e01d579b8649e5850538a12c746be445a055 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Wed, 14 Jan 2026 15:23:24 +1100 Subject: [PATCH 061/170] docs(#2934): normalise all icon and highlight --- doc/nvim-tree-lua.txt | 103 ++++++++++++--------- lua/nvim-tree/_meta/config/diagnostics.lua | 2 + lua/nvim-tree/_meta/config/git.lua | 2 + lua/nvim-tree/_meta/config/modified.lua | 2 + lua/nvim-tree/_meta/config/renderer.lua | 41 ++++---- 5 files changed, 81 insertions(+), 69 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 58e842ec99d..671a9e470a9 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -1488,12 +1488,15 @@ Icons And Highlighting *nvim-tree-icons-highlighting* Icons may be displayed before files and directories. -Icons and highlighting may be displayed to indicate various states for files -and directories. +Additional icons and highlighting may be displayed to indicate various states +for files and and directories. Highlighting is additive, with higher precedence overriding lower. - +|nvim_tree.Config.Renderer| {decorators} controls which highlighting is +applied and its precedence. See |nvim-tree-decorators| for information on +creating custom decorators. +< ICON Enable via |nvim_tree.Config.Renderer.Icons.Show @@ -1524,20 +1527,18 @@ GLYPHS GROUPS Applicable highlight groups: |nvim-tree-highlight-groups| +Some defaults noted. In ascending order of default highlight precedence: -All icons and highlighting, in ascending order of highlight precedence, -some defaults noted: - -ICON REQUIRES PLACEMENT HIGHLIGHT DEVICONS GLYPHS GROUPS -{file} `Y` - - - `Y` |nvim_tree.Config.Renderer.Icons.Glyphs| {default} `NvimTreeNormal` `NvimTreeFileIcon` -{folder} `Y` - - - `Y` |nvim_tree.Config.Renderer.Icons.Glyphs.Folder| `NvimTree*FolderName` `NvimTree*FolderIcon` -{git} `Y` |nvim_tree.Config.Git| {git_placement} `before` {highlight_git} `none` `Y` |nvim_tree.Config.Renderer.Icons.Glyphs.Git| `NvimTreeGit* - - - - {highlight_opened_files} `none` `N` - `NvimTreeOpened* -{hidden} `N` - {hidden_placement} `after` {highlight_hidden} `none` `N` |nvim_tree.Config.Renderer.Icons.Glyphs| {hidden} `NvimTreeHidden*` -{modified} `Y` |nvim_tree.Config.Modified| {modified_placement} `after` {highlight_modified} `none` `N` |nvim_tree.Config.Renderer.Icons.Glyphs| {modified} `NvimTreeModified*` -{bookmarks} `Y` - {bookmarks_placement} `signcolumn` {highlight_bookmarks} `none` `N` |nvim_tree.Config.Renderer.Icons.Glyphs| {bookmark} `NvimTreeBookmark*` -{diagnostics} `Y` |nvim_tree.Config.Diagnostics| {diagnostics_placement} `signcolumn` {highlight_diagnostics} `none` `N` |nvim_tree.Config.Diagnostics.Icons| `NvimTreeDiagnostic*` - - - - {highlight_clipboard} `name` `N` - `NvimTreeCutHL` `NvimTreeCopiedHL` +WHAT ICON REQUIRES PLACEMENT HIGHLIGHT DEVICONS GLYPHS GROUPS +File Icon {file} `Y` - - - `Y` |nvim_tree.Config.Renderer.Icons.Glyphs| {default} `NvimTreeNormal` `NvimTreeFileIcon` +Folder Icon {folder} `Y` - - - `Y` |nvim_tree.Config.Renderer.Icons.Glyphs.Folder| `NvimTree*FolderName` `NvimTree*FolderIcon` +Git Status {git} `Y` |nvim_tree.Config.Git| {git_placement} `before` {highlight_git} `none` `Y` |nvim_tree.Config.Renderer.Icons.Glyphs.Git| `NvimTreeGit* +|bufloaded()| - - - {highlight_opened_files} `none` `N` - `NvimTreeOpened* +Dotfiles {hidden} `N` - {hidden_placement} `after` {highlight_hidden} `none` `N` |nvim_tree.Config.Renderer.Icons.Glyphs| {hidden} `NvimTreeHidden*` +|'modified'| {modified} `Y` |nvim_tree.Config.Modified| {modified_placement} `after` {highlight_modified} `none` `N` |nvim_tree.Config.Renderer.Icons.Glyphs| {modified} `NvimTreeModified*` +Bookmarked {bookmarks} `Y` - {bookmarks_placement} `signcolumn` {highlight_bookmarks} `none` `N` |nvim_tree.Config.Renderer.Icons.Glyphs| {bookmark} `NvimTreeBookmark*` +Diag Status {diagnostics} `Y` |nvim_tree.Config.Diagnostics| {diagnostics_placement} `signcolumn` {highlight_diagnostics} `none` `N` |nvim_tree.Config.Diagnostics.Icons| `NvimTreeDiagnostic*` +Cut/Copied - - - {highlight_clipboard} `name` `N` - `NvimTreeCutHL` `NvimTreeCopiedHL` ============================================================================== @@ -2350,6 +2351,9 @@ Class: Config.Renderer *nvim-tree-config-renderer* *nvim_tree.Config.Renderer* Controls the appearance of the tree. + See |nvim-tree-icons-highlighting| for {highlight_} and {decorators} + fields. + {root_folder_label} has 3 forms: • `string`: |filename-modifiers| format string, default `":~:s?$?/..?"` • `boolean`: `true` to disable @@ -2381,25 +2385,23 @@ Class: Config.Renderer *nvim-tree-config-renderer* • {symlink_destination}? (`boolean`, default: `true`) Appends an arrow followed by the target of the symlink. - • {decorators}? (`(string|nvim_tree.api.decorator.UserDecorator)[]`, default: `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) - Highlighting and icons for the nodes, in - increasing order of precedence. Strings - specify builtin decorators. See - |nvim-tree-decorators|. - • {highlight_git}? (`nvim_tree.Config.Renderer.Highlight`, default: `none`) - Git status. - • {highlight_opened_files}? (`nvim_tree.Config.Renderer.Highlight`, default: `none`) - |bufloaded()| files. - • {highlight_hidden}? (`nvim_tree.Config.Renderer.Highlight`, default: `none`) - Hidden (dotfiles) files and directories. - • {highlight_modified}? (`nvim_tree.Config.Renderer.Highlight`, default: `none`) - Modified files. - • {highlight_bookmarks}? (`nvim_tree.Config.Renderer.Highlight`, default: `none`) - Bookmarked files and directories. - • {highlight_diagnostics}? (`nvim_tree.Config.Renderer.Highlight`, default: `none`) - Diagnostic status. - • {highlight_clipboard}? (`nvim_tree.Config.Renderer.Highlight`, default: `name`) - Copied and cut. + • {decorators}? (`(string|nvim_tree.api.decorator.UserDecorator)[]`) + (default: + `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) + • {highlight_git}? (`nvim_tree.Config.Renderer.Highlight`) + (default: `none`) + • {highlight_opened_files}? (`nvim_tree.Config.Renderer.Highlight`) + (default: `none`) + • {highlight_hidden}? (`nvim_tree.Config.Renderer.Highlight`) + (default: `none`) + • {highlight_modified}? (`nvim_tree.Config.Renderer.Highlight`) + (default: `none`) + • {highlight_bookmarks}? (`nvim_tree.Config.Renderer.Highlight`) + (default: `none`) + • {highlight_diagnostics}? (`nvim_tree.Config.Renderer.Highlight`) + (default: `none`) + • {highlight_clipboard}? (`nvim_tree.Config.Renderer.Highlight`) + (default: `name`) • {special_files}? (`string[]`, default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }`) Highlight special files and directories with `NvimTreeSpecial*`. @@ -2409,23 +2411,21 @@ Class: Config.Renderer *nvim-tree-config-renderer* |nvim_tree.Config.Renderer.Icons| *nvim_tree.Config.Renderer.Icons* - Icons and separators. + Icons and separators + + See |nvim-tree-icons-highlighting| for: {_placement} fields. Fields: ~ - • {web_devicons}? (`nvim_tree.Config.Renderer.Icons.WebDevicons`) - |nvim_tree.Config.Renderer.Icons.WebDevicons| - Use optional plugin - `nvim-tree/nvim-web-devicons` • {git_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`) (default: `before`) - • {diagnostics_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`, default: `signcolumn`) - Requires |nvim_tree.Config.Diagnostics|. - • {modified_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`, default: `after`) - Requires |nvim_tree.Config.Modified|. • {hidden_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`) (default: `after`) + • {modified_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`) + (default: `after`) • {bookmarks_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`) (default: `signcolumn`) + • {diagnostics_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`) + (default: `signcolumn`) • {padding}? (`table`) *nvim_tree.Config.Renderer.Icons.Padding* • {icon}? (`string`, default: ` `) Between @@ -2439,8 +2439,12 @@ Class: Config.Renderer *nvim-tree-config-renderer* |nvim_tree.Config.Renderer.Icons.Show| • {glyphs}? (`nvim_tree.Config.Renderer.Icons.Glyphs`) |nvim_tree.Config.Renderer.Icons.Glyphs| + • {web_devicons}? (`nvim_tree.Config.Renderer.Icons.WebDevicons`) + |nvim_tree.Config.Renderer.Icons.WebDevicons| *nvim_tree.Config.Renderer.Icons.Glyphs* + See |nvim-tree-icons-highlighting|. + Glyphs that appear in the sign column must have length <= 2 Fields: ~ @@ -2468,7 +2472,7 @@ Class: Config.Renderer *nvim-tree-config-renderer* • {ignored}? (`string`) (default: `◌` ) *nvim_tree.Config.Renderer.Icons.Show* - Control which icons are displayed. + See |nvim-tree-icons-highlighting|. Fields: ~ • {file}? (`boolean`) (default: `true`) @@ -2484,7 +2488,8 @@ Class: Config.Renderer *nvim-tree-config-renderer* |nvim_tree.Config.Renderer.IndentMarkers|. *nvim_tree.Config.Renderer.Icons.WebDevicons* - Configure optional plugin `nvim-tree/nvim-web-devicons`. + Configure optional plugin `nvim-tree/nvim-web-devicons`, see + |nvim-tree-icons-highlighting|. Fields: ~ • {file}? (`table`) @@ -2611,6 +2616,8 @@ Git integration may be disabled for git top-level directories via • A list of relative paths evaluated with |fnamemodify()| `:p` OR • A function that is passed an absolute path and returns `true` to disable +See |nvim-tree-icons-highlighting|. + *nvim_tree.Config.Git* @@ -2636,6 +2643,8 @@ Class: Config.Diagnostics *nvim-tree-config-diagnostics* Integrate with |lsp| or COC diagnostics. +See |nvim-tree-icons-highlighting|. + *nvim_tree.Config.Diagnostics* @@ -2673,6 +2682,8 @@ tree you will need: • |nvim_tree.Config.Renderer.Icons.Show| {modified} OR • |nvim_tree.Config.Renderer| {highlight_modified} +See |nvim-tree-icons-highlighting|. + *nvim_tree.Config.Modified* diff --git a/lua/nvim-tree/_meta/config/diagnostics.lua b/lua/nvim-tree/_meta/config/diagnostics.lua index 1368be54570..8cf69f4604d 100644 --- a/lua/nvim-tree/_meta/config/diagnostics.lua +++ b/lua/nvim-tree/_meta/config/diagnostics.lua @@ -5,6 +5,8 @@ error("Cannot require a meta file") ---@brief ---Integrate with [lsp] or COC diagnostics. +--- +---See [nvim-tree-icons-highlighting]. diff --git a/lua/nvim-tree/_meta/config/git.lua b/lua/nvim-tree/_meta/config/git.lua index 9e1705ff6ea..ca04a044e82 100644 --- a/lua/nvim-tree/_meta/config/git.lua +++ b/lua/nvim-tree/_meta/config/git.lua @@ -11,6 +11,8 @@ error("Cannot require a meta file") ---Git integration may be disabled for git top-level directories via {disable_for_dirs}: --- - A list of relative paths evaluated with [fnamemodify()] `:p` OR --- - A function that is passed an absolute path and returns `true` to disable +--- +---See [nvim-tree-icons-highlighting]. diff --git a/lua/nvim-tree/_meta/config/modified.lua b/lua/nvim-tree/_meta/config/modified.lua index bd5a8f4dc6a..db59474f3a9 100644 --- a/lua/nvim-tree/_meta/config/modified.lua +++ b/lua/nvim-tree/_meta/config/modified.lua @@ -8,6 +8,8 @@ error("Cannot require a meta file") ---To see modified status in the tree you will need: --- - [nvim_tree.Config.Renderer.Icons.Show] {modified} OR --- - [nvim_tree.Config.Renderer] {highlight_modified} +--- +---See [nvim-tree-icons-highlighting]. diff --git a/lua/nvim-tree/_meta/config/renderer.lua b/lua/nvim-tree/_meta/config/renderer.lua index 3ccbc27089d..1656d4baf89 100644 --- a/lua/nvim-tree/_meta/config/renderer.lua +++ b/lua/nvim-tree/_meta/config/renderer.lua @@ -13,6 +13,8 @@ error("Cannot require a meta file") ---Controls the appearance of the tree. --- +---See [nvim-tree-icons-highlighting] for {highlight_} and {decorators} fields. +--- ---{root_folder_label} has 3 forms: ---- `string`: [filename-modifiers] format string, default `":~:s?$?/..?"` ---- `boolean`: `true` to disable @@ -51,35 +53,27 @@ error("Cannot require a meta file") ---(default: `true`) ---@field symlink_destination? boolean --- ----Highlighting and icons for the nodes, in increasing order of precedence. Strings specify builtin decorators. See [nvim-tree-decorators]. ---(default: `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) ---@field decorators? (string|nvim_tree.api.decorator.UserDecorator)[] --- ----Git status. ---(default: `none`) ---@field highlight_git? nvim_tree.Config.Renderer.Highlight --- ----[bufloaded()] files. ---(default: `none`) ---@field highlight_opened_files? nvim_tree.Config.Renderer.Highlight --- ----Hidden (dotfiles) files and directories. ---(default: `none`) ---@field highlight_hidden? nvim_tree.Config.Renderer.Highlight --- ----Modified files. ---(default: `none`) ---@field highlight_modified? nvim_tree.Config.Renderer.Highlight --- ----Bookmarked files and directories. ---(default: `none`) ---@field highlight_bookmarks? nvim_tree.Config.Renderer.Highlight --- ----Diagnostic status. ---(default: `none`) ---@field highlight_diagnostics? nvim_tree.Config.Renderer.Highlight --- ----Copied and cut. ---(default: `name`) ---@field highlight_clipboard? nvim_tree.Config.Renderer.Highlight --- @@ -94,6 +88,7 @@ error("Cannot require a meta file") ---@field icons? nvim_tree.Config.Renderer.Icons + ---@class nvim_tree.Config.Renderer.IndentMarkers --- ---Display indent markers when folders are open. @@ -126,30 +121,26 @@ error("Cannot require a meta file") ----Icons and separators. ----@class nvim_tree.Config.Renderer.Icons +---Icons and separators --- ----[nvim_tree.Config.Renderer.Icons.WebDevicons] ----Use optional plugin `nvim-tree/nvim-web-devicons` ----@field web_devicons? nvim_tree.Config.Renderer.Icons.WebDevicons +---See [nvim-tree-icons-highlighting] for: {_placement} fields. +---@class nvim_tree.Config.Renderer.Icons --- ---(default: `before`) ---@field git_placement? nvim_tree.Config.Renderer.Icons.Placement --- ----Requires [nvim_tree.Config.Diagnostics]. ----(default: `signcolumn`) ----@field diagnostics_placement? nvim_tree.Config.Renderer.Icons.Placement ---- ----Requires [nvim_tree.Config.Modified]. ---(default: `after`) ----@field modified_placement? nvim_tree.Config.Renderer.Icons.Placement +---@field hidden_placement? nvim_tree.Config.Renderer.Icons.Placement --- ---(default: `after`) ----@field hidden_placement? nvim_tree.Config.Renderer.Icons.Placement +---@field modified_placement? nvim_tree.Config.Renderer.Icons.Placement --- ---(default: `signcolumn`) ---@field bookmarks_placement? nvim_tree.Config.Renderer.Icons.Placement --- +---(default: `signcolumn`) +---@field diagnostics_placement? nvim_tree.Config.Renderer.Icons.Placement +--- ---@field padding? nvim_tree.Config.Renderer.Icons.Padding --- ---Separator between symlink source and target. @@ -161,10 +152,13 @@ error("Cannot require a meta file") --- ---[nvim_tree.Config.Renderer.Icons.Glyphs] ---@field glyphs? nvim_tree.Config.Renderer.Icons.Glyphs +--- +---[nvim_tree.Config.Renderer.Icons.WebDevicons] +---@field web_devicons? nvim_tree.Config.Renderer.Icons.WebDevicons ----Configure optional plugin `nvim-tree/nvim-web-devicons`. +---Configure optional plugin `nvim-tree/nvim-web-devicons`, see [nvim-tree-icons-highlighting]. --- ---@class nvim_tree.Config.Renderer.Icons.WebDevicons --- @@ -211,7 +205,7 @@ error("Cannot require a meta file") ----Control which icons are displayed. +---See [nvim-tree-icons-highlighting]. ---@class nvim_tree.Config.Renderer.Icons.Show --- ---(default: `true`) @@ -241,8 +235,9 @@ error("Cannot require a meta file") ----Glyphs that appear in the sign column must have length <= 2 +---See [nvim-tree-icons-highlighting]. --- +---Glyphs that appear in the sign column must have length <= 2 ---@class nvim_tree.Config.Renderer.Icons.Glyphs --- ---Files From 3713b69679e298075d427d398297c7034e7236d9 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Wed, 14 Jan 2026 18:15:58 +1100 Subject: [PATCH 062/170] docs(#2934): extract nvim_tree.Config field descriptions to class overview --- doc/nvim-tree-lua.txt | 187 +++++++++++++++++---------------- lua/nvim-tree/_meta/config.lua | 49 ++++++--- 2 files changed, 130 insertions(+), 106 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 671a9e470a9..7d48a60394b 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -1,7 +1,6 @@ -*nvim-tree-lua.txt* A File Explorer For Nvim *nvim-tree* +*nvim-tree-lua.txt* A File Explorer For Nvim *nvim_tree* *nvim-tree* Author: Yazdani Kiyan - Type |gO| to see the table of contents. ============================================================================== @@ -1337,7 +1336,7 @@ Mappings are set via the |nvim_tree.Config| {on_attach} function, which is run u creating the nvim-tree buffer. Mappings are usually |nvim-tree-api| functions however may be your own. -When on_attach is not a function, |nvim-tree-mappings-default| will be used. +When {on_attach} is not a function, |nvim-tree-mappings-default| will be used. Active mappings may be viewed via HELP, default `g?`. The mapping's description is used when displaying HELP. @@ -1395,10 +1394,10 @@ define your own function to map complex functionality e.g. >lua ============================================================================== Mappings: Default *nvim-tree-mappings-default* -In the absence of an |nvim_tree.Config| {on_attach} function, the following defaults -will be applied. +In the absence of an |nvim_tree.Config| {on_attach} function, the following +defaults will be applied. -You are encouraged to copy these to your own |nvim_tree.Config| {on_attach} function. >lua +You are encouraged to copy these to your {on_attach} function. >lua local api = require("nvim-tree.api") @@ -2113,6 +2112,8 @@ Class: Config *nvim-tree-config* Arguments to pass to |nvim-tree-setup|. +When a value is not present/nil, the default will be used. + They can be validated by |lsp| when passed directly e.g. >lua require("nvim-tree").setup({ hijack_cursor = true, @@ -2127,93 +2128,101 @@ or as a typed variable e.g. >lua require("nvim-tree").setup(config) < -When a value is not present/nil, the default will be used. - *nvim_tree.Config* + {on_attach} Runs when creating the nvim-tree buffer. Use this to set your + |nvim-tree-mappings|. When not a function, |nvim-tree-mappings-default| + will be used. + + {hijack_cursor} keep the cursor on the first letter of the filename when + moving in the tree. + + {auto_reload_on_write} reload the explorer every time a buffer is written + to. + + {disable_netrw} completely disables |netrw|, see |nvim-tree-netrw| for + details. It is strongly advised to eagerly disable netrw, due to race + conditions at vim startup. + + {hijack_netrw} hijacks netrw windows, ignored when {disable_netrw}. + + {hijack_unnamed_buffer_when_opening} opens in place of the unnamed buffer + if it's empty. + + {root_dirs} preferred root directories, requires + |nvim_tree.Config.UpdateFocusedFile.UpdateRoot|. + + {prefer_startup_root} prefer startup root directory when updating root + directory of the tree. Requires + |nvim_tree.Config.UpdateFocusedFile.UpdateRoot|. + + {sync_root_with_cwd} changes the tree root directory on |DirChanged| and + refreshes the tree. + + {reload_on_bufenter} automatically reloads the tree on |BufEnter| + nvim-tree. + + {respect_buf_cwd} changes the |current-directory| of nvim-tree to that of + new buffer's when opening nvim-tree. + + {select_prompts} uses |vim.ui.select()| style prompts. Necessary when + using a UI prompt decorator such as dressing.nvim or + telescope-ui-select.nvim Fields: ~ - • {on_attach}? (`string|(fun(bufnr: integer))`) Runs when - creating the nvim-tree buffer. Use this to - set your |nvim-tree-mappings|. When - `on_attach` is not a function, - |nvim-tree-mappings-default| will be called. - • {hijack_cursor}? (`boolean`, default: `false`) Keeps the - cursor on the first letter of the filename - when moving in the tree. - • {auto_reload_on_write}? (`boolean`, default: `true`) Reloads the - explorer every time a buffer is written to. - • {disable_netrw}? (`boolean`, default: `false`) Completely - disable |netrw|, see |nvim-tree-netrw| for - details. It is strongly advised to eagerly - disable netrw, due to race conditions at vim - startup. - • {hijack_netrw}? (`boolean`, default: `true`) Hijack netrw - windows, ignored when `disable_netrw` is - `true` - • {hubwo}? (`boolean`, default: `false`) Opens in place - of the unnamed buffer if it's empty. TODO - reinstate this one when formatting is done - #2934 --@field - hijack_unnamed_buffer_when_opening? boolean - • {root_dirs}? (`string[]`) Preferred root directories. - Requires - |nvim_tree.Config.UpdateFocusedFile.UpdateRoot|. - • {prefer_startup_root}? (`boolean`, default: `false`) Prefer startup - root directory when updating root directory - of the tree. Requires - |nvim_tree.Config.UpdateFocusedFile.UpdateRoot|. - • {sync_root_with_cwd}? (`boolean`, default: `false`) Changes the - tree root directory on |DirChanged| and - refreshes the tree. - • {reload_on_bufenter}? (`boolean`, default: `false`) Automatically - reloads the tree on |BufEnter| nvim-tree. - • {respect_buf_cwd}? (`boolean`, default: `false`) Change cwd of - nvim-tree to that of new buffer's when - opening nvim-tree. - • {select_prompts}? (`boolean`, default: `false`) Use - |vim.ui.select()| style prompts. Necessary - when using a UI prompt decorator such as - dressing.nvim or telescope-ui-select.nvim - • {sort}? (`nvim_tree.Config.Sort`) - |nvim_tree.Config.Sort| - • {view}? (`nvim_tree.Config.View`) - |nvim_tree.Config.View| - • {renderer}? (`nvim_tree.Config.Renderer`) - |nvim_tree.Config.Renderer| - • {hijack_directories}? (`nvim_tree.Config.HijackDirectories`) - |nvim_tree.Config.HijackDirectories| - • {update_focused_file}? (`nvim_tree.Config.UpdateFocusedFile`) - |nvim_tree.Config.UpdateFocusedFile| - • {system_open}? (`nvim_tree.Config.SystemOpen`) - |nvim_tree.Config.SystemOpen| - • {git}? (`nvim_tree.Config.Git`) - |nvim_tree.Config.Git| - • {diagnostics}? (`nvim_tree.Config.Diagnostics`) - |nvim_tree.Config.Diagnostics| - • {modified}? (`nvim_tree.Config.Modified`) - |nvim_tree.Config.Modified| - • {filters}? (`nvim_tree.Config.Filters`) - |nvim_tree.Config.Filters| - • {live_filter}? (`nvim_tree.Config.LiveFilter`) - |nvim_tree.Config.LiveFilter| - • {filesystem_watchers}? (`nvim_tree.Config.FilesystemWatchers`) - |nvim_tree.Config.FilesystemWatchers| - • {actions}? (`nvim_tree.Config.Actions`) - |nvim_tree.Config.Actions| - • {trash}? (`nvim_tree.Config.Trash`) - |nvim_tree.Config.Trash| - • {tab}? (`nvim_tree.Config.Tab`) - |nvim_tree.Config.Tab| - • {bookmarks}? (`nvim_tree.Config.Bookmarks`) - |nvim_tree.Config.Bookmarks| - • {notify}? (`nvim_tree.Config.Notify`) - |nvim_tree.Config.Notify| - • {help}? (`nvim_tree.Config.Help`) - |nvim_tree.Config.Help| - • {ui}? (`nvim_tree.Config.UI`) |nvim_tree.Config.UI| - • {log}? (`nvim_tree.Config.Log`) - |nvim_tree.Config.Log| + • {on_attach}? (`string|(fun(bufnr: integer))`) + (default: `default`) + • {hijack_cursor}? (`boolean`) (default: `false`) + • {auto_reload_on_write}? (`boolean`) (default: `true`) + • {disable_netrw}? (`boolean`) (default: `false`) + • {hijack_netrw}? (`boolean`) (default: `true`) + • {hijack_unnamed_buffer_when_opening}? (`boolean`) (default: `false`) + • {root_dirs}? (`string[]`) (default: `{}`) + • {prefer_startup_root}? (`boolean`) (default: `false`) + • {sync_root_with_cwd}? (`boolean`) (default: `false`) + • {reload_on_bufenter}? (`boolean`) (default: `false`) + • {respect_buf_cwd}? (`boolean`) (default: `false`) + • {select_prompts}? (`boolean`) (default: `false`) + • {sort}? (`nvim_tree.Config.Sort`) + |nvim_tree.Config.Sort| + • {view}? (`nvim_tree.Config.View`) + |nvim_tree.Config.View| + • {renderer}? (`nvim_tree.Config.Renderer`) + |nvim_tree.Config.Renderer| + • {hijack_directories}? (`nvim_tree.Config.HijackDirectories`) + |nvim_tree.Config.HijackDirectories| + • {update_focused_file}? (`nvim_tree.Config.UpdateFocusedFile`) + |nvim_tree.Config.UpdateFocusedFile| + • {system_open}? (`nvim_tree.Config.SystemOpen`) + |nvim_tree.Config.SystemOpen| + • {git}? (`nvim_tree.Config.Git`) + |nvim_tree.Config.Git| + • {diagnostics}? (`nvim_tree.Config.Diagnostics`) + |nvim_tree.Config.Diagnostics| + • {modified}? (`nvim_tree.Config.Modified`) + |nvim_tree.Config.Modified| + • {filters}? (`nvim_tree.Config.Filters`) + |nvim_tree.Config.Filters| + • {live_filter}? (`nvim_tree.Config.LiveFilter`) + |nvim_tree.Config.LiveFilter| + • {filesystem_watchers}? (`nvim_tree.Config.FilesystemWatchers`) + |nvim_tree.Config.FilesystemWatchers| + • {actions}? (`nvim_tree.Config.Actions`) + |nvim_tree.Config.Actions| + • {trash}? (`nvim_tree.Config.Trash`) + |nvim_tree.Config.Trash| + • {tab}? (`nvim_tree.Config.Tab`) + |nvim_tree.Config.Tab| + • {bookmarks}? (`nvim_tree.Config.Bookmarks`) + |nvim_tree.Config.Bookmarks| + • {notify}? (`nvim_tree.Config.Notify`) + |nvim_tree.Config.Notify| + • {help}? (`nvim_tree.Config.Help`) + |nvim_tree.Config.Help| + • {ui}? (`nvim_tree.Config.UI`) + |nvim_tree.Config.UI| + • {log}? (`nvim_tree.Config.Log`) + |nvim_tree.Config.Log| diff --git a/lua/nvim-tree/_meta/config.lua b/lua/nvim-tree/_meta/config.lua index 01741b079c7..34e36d8b44c 100644 --- a/lua/nvim-tree/_meta/config.lua +++ b/lua/nvim-tree/_meta/config.lua @@ -6,6 +6,8 @@ error("Cannot require a meta file") --- ---Arguments to pass to [nvim-tree-setup]. --- +---When a value is not present/nil, the default will be used. +--- ---They can be validated by |lsp| when passed directly e.g. ---```lua --- require("nvim-tree").setup({ @@ -21,58 +23,71 @@ error("Cannot require a meta file") --- } --- require("nvim-tree").setup(config) ---``` ---- ----When a value is not present/nil, the default will be used. +-- Root class {field}s are documented manually above "Fields:" as there is insufficent room for them in the column. + + + +---{on_attach} Runs when creating the nvim-tree buffer. Use this to set your [nvim-tree-mappings]. When not a function, [nvim-tree-mappings-default] will be used. +--- +---{hijack_cursor} keep the cursor on the first letter of the filename when moving in the tree. +--- +---{auto_reload_on_write} reload the explorer every time a buffer is written to. +--- +---{disable_netrw} completely disables [netrw], see [nvim-tree-netrw] for details. It is strongly advised to eagerly disable netrw, due to race conditions at vim startup. +--- +---{hijack_netrw} hijacks netrw windows, ignored when {disable_netrw}. +--- +---{hijack_unnamed_buffer_when_opening} opens in place of the unnamed buffer if it's empty. +--- +---{root_dirs} preferred root directories, requires [nvim_tree.Config.UpdateFocusedFile.UpdateRoot]. +--- +---{prefer_startup_root} prefer startup root directory when updating root directory of the tree. Requires [nvim_tree.Config.UpdateFocusedFile.UpdateRoot]. +--- +---{sync_root_with_cwd} changes the tree root directory on [DirChanged] and refreshes the tree. +--- +---{reload_on_bufenter} automatically reloads the tree on [BufEnter] nvim-tree. +--- +---{respect_buf_cwd} changes the [current-directory] of nvim-tree to that of new buffer's when opening nvim-tree. +--- +---{select_prompts} uses [vim.ui.select()] style prompts. Necessary when using a UI prompt decorator such as dressing.nvim or telescope-ui-select.nvim ---@class nvim_tree.Config --- ----Runs when creating the nvim-tree buffer. Use this to set your [nvim-tree-mappings]. When `on_attach` is not a function, [nvim-tree-mappings-default] will be called. +---(default: `default`) ---@field on_attach? string|(fun(bufnr: integer)) --- ----Keeps the cursor on the first letter of the filename when moving in the tree. ---(default: `false`) ---@field hijack_cursor? boolean --- ----Reloads the explorer every time a buffer is written to. ---(default: `true`) ---@field auto_reload_on_write? boolean --- ----Completely disable [netrw], see [nvim-tree-netrw] for details. It is strongly advised to eagerly disable netrw, due to race conditions at vim startup. ---(default: `false`) ---@field disable_netrw? boolean --- ----Hijack netrw windows, ignored when `disable_netrw` is `true` ---(default: `true`) ---@field hijack_netrw? boolean --- ----Opens in place of the unnamed buffer if it's empty. ---(default: `false`) ----TODO reinstate this one when formatting is done #2934 ------@field hijack_unnamed_buffer_when_opening? boolean ----@field hubwo? boolean +---@field hijack_unnamed_buffer_when_opening? boolean --- ----Preferred root directories. Requires [nvim_tree.Config.UpdateFocusedFile.UpdateRoot]. +---(default: `{}`) ---@field root_dirs? string[] --- ----Prefer startup root directory when updating root directory of the tree. Requires [nvim_tree.Config.UpdateFocusedFile.UpdateRoot]. ---(default: `false`) ---@field prefer_startup_root? boolean --- ----Changes the tree root directory on [DirChanged] and refreshes the tree. ---(default: `false`) ---@field sync_root_with_cwd? boolean --- ----Automatically reloads the tree on [BufEnter] nvim-tree. ---(default: `false`) ---@field reload_on_bufenter? boolean --- ----Change cwd of nvim-tree to that of new buffer's when opening nvim-tree. ---(default: `false`) ---@field respect_buf_cwd? boolean --- ----Use [vim.ui.select()] style prompts. Necessary when using a UI prompt decorator such as dressing.nvim or telescope-ui-select.nvim ---(default: `false`) ---@field select_prompts? boolean --- From 0a8b2cab0deabafc94c3d03e8f0a5b4f4f10dd62 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Wed, 14 Jan 2026 18:44:42 +1100 Subject: [PATCH 063/170] docs(#2934): consistent string formatting --- doc/nvim-tree-lua.txt | 129 +++++++++++---------- lua/nvim-tree/_meta/config.lua | 2 +- lua/nvim-tree/_meta/config/actions.lua | 12 +- lua/nvim-tree/_meta/config/diagnostics.lua | 8 +- lua/nvim-tree/_meta/config/help.lua | 6 +- lua/nvim-tree/_meta/config/live_filter.lua | 2 +- lua/nvim-tree/_meta/config/renderer.lua | 66 +++++------ lua/nvim-tree/_meta/config/sort.lua | 14 +-- lua/nvim-tree/_meta/config/system_open.lua | 1 - lua/nvim-tree/_meta/config/trash.lua | 3 +- lua/nvim-tree/_meta/config/view.lua | 8 +- 11 files changed, 125 insertions(+), 126 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 7d48a60394b..4c97e2153f9 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -2170,7 +2170,7 @@ or as a typed variable e.g. >lua telescope-ui-select.nvim Fields: ~ - • {on_attach}? (`string|(fun(bufnr: integer))`) + • {on_attach}? (`"default"|(fun(bufnr: integer))`) (default: `default`) • {hijack_cursor}? (`boolean`) (default: `false`) • {auto_reload_on_write}? (`boolean`) (default: `true`) @@ -2232,12 +2232,12 @@ Class: Config.Sort *nvim-tree-config-sort* Sort files within a directory. {sorter} presets *nvim_tree.Config.Sort.Sorter* -• `name` -• `case_sensitive` name -• `modification_time` -• `extension` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz` -• `suffix` uses the last e.g. `foo.tar.gz` -> `.gz` -• `filetype` |filetype| +• `"name"` +• `"case_sensitive"` name +• `"modification_time"` +• `"extension"` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz` +• `"suffix"` uses the last e.g. `foo.tar.gz` -> `.gz` +• `"filetype"` |filetype| {sorter} may be a function that is passed a list of `nvim_tree.api.Node` to be sorted in place e.g. >lua @@ -2259,7 +2259,7 @@ sorted in place e.g. >lua Fields: ~ • {sorter}? (`nvim_tree.Config.Sort.Sorter|(fun(nodes: nvim_tree.api.Node[]): nvim_tree.Config.Sort.Sorter?)`) - (default: `name`) + (default: `"name"`) • {folders_first}? (`boolean`, default: `true`) Sort folders before files. Has no effect when {sorter} is a function. • {files_first}? (`boolean`, default: `false`) Sort files before @@ -2302,7 +2302,7 @@ line. refresh operations. Increase if you experience performance issues around screen refresh. - • {side}? (`"left"|"right"`) (default: `left`) + • {side}? (`"left"|"right"`) (default: `"left"`) • {preserve_window_proportions}? (`boolean`, default: `false`) Preserves window proportions when opening a file. If `false`, the height @@ -2312,8 +2312,8 @@ line. |'number'| • {relativenumber}? (`boolean`, default: `false`) |'relativenumber'| - • {signcolumn}? (`"yes"|"auto"|"no"`, default: `yes`) - |'signcolumn'| + • {signcolumn}? (`"yes"|"auto"|"no"`, default: + `"yes"`) |'signcolumn'| • {width}? (`nvim_tree.Config.View.WidthSpec|nvim_tree.Config.View.Width`) (default: `30`) • {float}? (`nvim_tree.Config.View.Float`) @@ -2322,7 +2322,7 @@ line. *nvim_tree.Config.View.Float* Configure floating window behaviour - {open_win_config} is passed directly to |nvim_open_win()|, default: >lua + {open_win_config} is passed to |nvim_open_win()|, default: >lua { relative = "editor", border = "rounded", @@ -2338,7 +2338,8 @@ line. • {quit_on_focus_loss}? (`boolean`, default: `true`) Close the floating window when it loses focus. • {open_win_config}? (`vim.api.keyset.win_config|(fun(): vim.api.keyset.win_config)`) - (default: above) + (default: + `{ relative = "editor", border = "rounded", width = 30, height = 30, row = 1, col = 1, }`) *nvim_tree.Config.View.Width* Configure dynamic width based on longest line. @@ -2398,19 +2399,19 @@ Class: Config.Renderer *nvim-tree-config-renderer* (default: `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) • {highlight_git}? (`nvim_tree.Config.Renderer.Highlight`) - (default: `none`) + (default: `"none"`) • {highlight_opened_files}? (`nvim_tree.Config.Renderer.Highlight`) - (default: `none`) + (default: `"none"`) • {highlight_hidden}? (`nvim_tree.Config.Renderer.Highlight`) - (default: `none`) + (default: `"none"`) • {highlight_modified}? (`nvim_tree.Config.Renderer.Highlight`) - (default: `none`) + (default: `"none"`) • {highlight_bookmarks}? (`nvim_tree.Config.Renderer.Highlight`) - (default: `none`) + (default: `"none"`) • {highlight_diagnostics}? (`nvim_tree.Config.Renderer.Highlight`) - (default: `none`) + (default: `"none"`) • {highlight_clipboard}? (`nvim_tree.Config.Renderer.Highlight`) - (default: `name`) + (default: `"name"`) • {special_files}? (`string[]`, default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }`) Highlight special files and directories with `NvimTreeSpecial*`. @@ -2437,12 +2438,12 @@ Class: Config.Renderer *nvim-tree-config-renderer* (default: `signcolumn`) • {padding}? (`table`) *nvim_tree.Config.Renderer.Icons.Padding* - • {icon}? (`string`, default: ` `) Between + • {icon}? (`string`, default: `" "`) Between icon and filename. - • {folder_arrow}? (`string`, default: ` `) + • {folder_arrow}? (`string`, default: `" "`) Between folder arrow icon and file/folder icon. - • {symlink_arrow}? (`string`, default: ` ➛ `) Separator + • {symlink_arrow}? (`string`, default: `" ➛ "`) Separator between symlink source and target. • {show}? (`nvim_tree.Config.Renderer.Icons.Show`) |nvim_tree.Config.Renderer.Icons.Show| @@ -2457,28 +2458,28 @@ Class: Config.Renderer *nvim-tree-config-renderer* Glyphs that appear in the sign column must have length <= 2 Fields: ~ - • {default}? (`string`, default: `` ) Files - • {symlink}? (`string`) (default: `` ) - • {bookmark}? (`string`) (default: `󰆤` ) - • {modified}? (`string`) (default: `●` ) - • {hidden}? (`string`) (default: `󰜌` ) + • {default}? (`string`, default: `""`) Files + • {symlink}? (`string`) (default: `""`) + • {bookmark}? (`string`) (default: `"󰆤"`) + • {modified}? (`string`) (default: `"●"`) + • {hidden}? (`string`) (default: `"󰜌"`) • {folder}? (`table`) *nvim_tree.Config.Renderer.Icons.Glyphs.Folder* • {arrow_closed}? (`string`) (default: left arrow) • {arrow_open}? (`string`) (default: down arrow) - • {default}? (`string`) (default: `` ) - • {open}? (`string`) (default: `` ) - • {empty}? (`string`) (default: `` ) - • {empty_open}? (`string`) (default: `` ) - • {symlink}? (`string`) (default: `` ) - • {symlink_open}? (`string`) (default: `` ) + • {default}? (`string`) (default: `""`) + • {open}? (`string`) (default: `""`) + • {empty}? (`string`) (default: `""`) + • {empty_open}? (`string`) (default: `""`) + • {symlink}? (`string`) (default: `""`) + • {symlink_open}? (`string`) (default: `""`) • {git}? (`table`) *nvim_tree.Config.Renderer.Icons.Glyphs.Git* - • {unstaged}? (`string`) (default: `✗` ) - • {staged}? (`string`) (default: `✓` ) - • {unmerged}? (`string`) (default: `` ) - • {renamed}? (`string`) (default: `➜` ) - • {untracked}? (`string`) (default: `★` ) - • {deleted}? (`string`) (default: `` ) - • {ignored}? (`string`) (default: `◌` ) + • {unstaged}? (`string`) (default: `"✗"`) + • {staged}? (`string`) (default: `"✓"`) + • {unmerged}? (`string`) (default: `""`) + • {renamed}? (`string`) (default: `"➜"`) + • {untracked}? (`string`) (default: `"★"`) + • {deleted}? (`string`) (default: `""`) + • {ignored}? (`string`) (default: `"◌"`) *nvim_tree.Config.Renderer.Icons.Show* See |nvim-tree-icons-highlighting|. @@ -2522,11 +2523,11 @@ Class: Config.Renderer *nvim-tree-config-renderer* • {icons}? (`table`) *nvim_tree.Config.Renderer.IndentMarkers.Icons* Before the file/directory, length 1. - • {corner}? (`string`) (default: `└` ) - • {edge}? (`string`) (default: `│` ) - • {item}? (`string`) (default: `│` ) - • {bottom}? (`string`) (default: `─` ) - • {none}? (`string`) (default: ` ` ) + • {corner}? (`string`) (default: `"└"`) + • {edge}? (`string`) (default: `"│"`) + • {item}? (`string`) (default: `"│"`) + • {bottom}? (`string`) (default: `"─"`) + • {none}? (`string`) (default: `" "`) @@ -2603,8 +2604,7 @@ longer be necessary and will be removed. *nvim_tree.Config.SystemOpen* Fields: ~ - • {cmd}? (`string`, default: `xdg-open`, `open` or `cmd`) The open - command itself + • {cmd}? (`string`) The open command itself • {args}? (`string[]`, default: `{}` or `{ "/c", "start", '""' }` on windows) Optional argument list. Leave empty for OS specific default. @@ -2676,10 +2676,10 @@ See |nvim-tree-icons-highlighting|. • {max}? (`vim.diagnostic.Severity`, default: ERROR) |vim.diagnostic.severity| • {icons}? (`table`) *nvim_tree.Config.Diagnostics.Icons* - • {hint}? (`string`) (default: `` ) - • {info}? (`string`) (default: `` ) - • {warning}? (`string`) (default: `` ) - • {error}? (`string`) (default: `` ) + • {hint}? (`string`) (default: `""` ) + • {info}? (`string`) (default: `""` ) + • {warning}? (`string`) (default: `""` ) + • {error}? (`string`) (default: `""` ) @@ -2778,7 +2778,7 @@ with the `F` key by default. *nvim_tree.Config.LiveFilter* Fields: ~ - • {prefix}? (`string`, default: `[FILTER]: `) Prefix of + • {prefix}? (`string`, default: `"[FILTER]: "`) Prefix of the filter displayed in the buffer. • {always_show_folders}? (`boolean`, default: `true`) Whether to filter folders or not. @@ -2862,7 +2862,7 @@ Class: Config.Actions *nvim-tree-config-actions* *nvim_tree.Config.Actions.FilePopup* {file_popup} floating window. - {open_win_config} is passed directly to |nvim_open_win()|, default: >lua + {open_win_config} is passed to |nvim_open_win()|, default: >lua { col = 1, row = 1, @@ -2876,7 +2876,8 @@ Class: Config.Actions *nvim-tree-config-actions* overridden to fit the file_popup content. Fields: ~ - • {open_win_config}? (`vim.api.keyset.win_config`) (default: above) + • {open_win_config}? (`vim.api.keyset.win_config`) (default: + `{ col = 1, row = 1, relative = "cursor", border = "shadow", style = "minimal", }`) *nvim_tree.Config.Actions.OpenFile* Opening files. @@ -2899,14 +2900,14 @@ Class: Config.Actions *nvim-tree-config-actions* When it is not enabled the file will open in the window from which you last opened the tree, obeying {exclude} - You may define a function that should return the window id that will open - the node, or `nil` if an invalid window is picked or user cancelled the - action. The picker may create a new window. + You may define a {picker} function that should return the window id that + will open the node, or `nil` if an invalid window is picked or user + cancelled the action. The picker may create a new window. Fields: ~ • {enable}? (`boolean`) (default: `true`) - • {picker}? (`string|(fun(): integer)`, default: `default`) Change the - default window picker: string `default` or a function. + • {picker}? (`"default"|(fun(): integer)`, default: `"default"`) + Change the default window picker or define your own. • {chars}? (`string`, default: `"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"`) Identifier characters to use. @@ -2948,7 +2949,7 @@ system. *nvim_tree.Config.Trash* Fields: ~ - • {cmd}? (`string`, default: `gio trash` or `trash`) External command. + • {cmd}? (`string`) (default: `"gio trash"` or `"trash"`) @@ -3016,14 +3017,14 @@ Class: Config.Help *nvim-tree-config-help* Configure help window, default mapping `g?` *nvim_tree.Config.Help.SortBy* -• `key`: alphabetically by keymap -• `desc`: alphabetically by description +• `"key"`: alphabetically by keymap +• `"desc"`: alphabetically by description *nvim_tree.Config.Help* Fields: ~ - • {sort_by}? (`nvim_tree.Config.Help.SortBy`, default: `key`) + • {sort_by}? (`nvim_tree.Config.Help.SortBy`, default: `"key"`) |nvim_tree.Config.Help.SortBy| diff --git a/lua/nvim-tree/_meta/config.lua b/lua/nvim-tree/_meta/config.lua index 34e36d8b44c..3c40236630b 100644 --- a/lua/nvim-tree/_meta/config.lua +++ b/lua/nvim-tree/_meta/config.lua @@ -56,7 +56,7 @@ error("Cannot require a meta file") ---@class nvim_tree.Config --- ---(default: `default`) ----@field on_attach? string|(fun(bufnr: integer)) +---@field on_attach? "default"|(fun(bufnr: integer)) --- ---(default: `false`) ---@field hijack_cursor? boolean diff --git a/lua/nvim-tree/_meta/config/actions.lua b/lua/nvim-tree/_meta/config/actions.lua index 75aed0891ac..e65fe4d79c4 100644 --- a/lua/nvim-tree/_meta/config/actions.lua +++ b/lua/nvim-tree/_meta/config/actions.lua @@ -58,7 +58,7 @@ error("Cannot require a meta file") ---{file_popup} floating window. --- ----{open_win_config} is passed directly to [nvim_open_win()], default: +---{open_win_config} is passed to [nvim_open_win()], default: ---```lua ---{ --- col = 1, @@ -71,7 +71,7 @@ error("Cannot require a meta file") ---You shouldn't define {width} and {height} values here. They will be overridden to fit the file_popup content. ---@class nvim_tree.Config.Actions.FilePopup --- ----(default: above) +---(default: `{ col = 1, row = 1, relative = "cursor", border = "shadow", style = "minimal", }`) ---@field open_win_config? vim.api.keyset.win_config @@ -100,16 +100,16 @@ error("Cannot require a meta file") --- ---When it is not enabled the file will open in the window from which you last opened the tree, obeying {exclude} --- ----You may define a function that should return the window id that will open the node, or `nil` if an invalid window is picked or user cancelled the action. The picker may create a new window. +---You may define a {picker} function that should return the window id that will open the node, or `nil` if an invalid window is picked or user cancelled the action. The picker may create a new window. --- ---@class nvim_tree.Config.Actions.OpenFile.WindowPicker --- ---(default: `true`) ---@field enable? boolean --- ----Change the default window picker: string `default` or a function. ----(default: `default`) ----@field picker? string|(fun(): integer) +---Change the default window picker or define your own. +---(default: `"default"`) +---@field picker? "default"|(fun(): integer) --- ---Identifier characters to use. ---(default: `"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"`) diff --git a/lua/nvim-tree/_meta/config/diagnostics.lua b/lua/nvim-tree/_meta/config/diagnostics.lua index 8cf69f4604d..ea0dad8b707 100644 --- a/lua/nvim-tree/_meta/config/diagnostics.lua +++ b/lua/nvim-tree/_meta/config/diagnostics.lua @@ -55,14 +55,14 @@ error("Cannot require a meta file") ---@class nvim_tree.Config.Diagnostics.Icons ---@inlinedoc --- ----(default: `` ) +---(default: `""` ) ---@field hint? string --- ----(default: `` ) +---(default: `""` ) ---@field info? string --- ----(default: `` ) +---(default: `""` ) ---@field warning? string --- ----(default: `` ) +---(default: `""` ) ---@field error? string diff --git a/lua/nvim-tree/_meta/config/help.lua b/lua/nvim-tree/_meta/config/help.lua index c8b6f79deb7..5e8c5750178 100644 --- a/lua/nvim-tree/_meta/config/help.lua +++ b/lua/nvim-tree/_meta/config/help.lua @@ -11,13 +11,13 @@ error("Cannot require a meta file") ---Configure help window, default mapping `g?` --- ---[nvim_tree.Config.Help.SortBy]() ----- `key`: alphabetically by keymap ----- `desc`: alphabetically by description +---- `"key"`: alphabetically by keymap +---- `"desc"`: alphabetically by description ---@class nvim_tree.Config.Help --- ---[nvim_tree.Config.Help.SortBy] ----(default: `key`) +---(default: `"key"`) ---@field sort_by? nvim_tree.Config.Help.SortBy diff --git a/lua/nvim-tree/_meta/config/live_filter.lua b/lua/nvim-tree/_meta/config/live_filter.lua index 60b52f172e4..5064b38991f 100644 --- a/lua/nvim-tree/_meta/config/live_filter.lua +++ b/lua/nvim-tree/_meta/config/live_filter.lua @@ -13,7 +13,7 @@ error("Cannot require a meta file") ---@class nvim_tree.Config.LiveFilter --- ---Prefix of the filter displayed in the buffer. ----(default: `[FILTER]: `) +---(default: `"[FILTER]: "`) ---@field prefix? string --- ---Whether to filter folders or not. diff --git a/lua/nvim-tree/_meta/config/renderer.lua b/lua/nvim-tree/_meta/config/renderer.lua index 1656d4baf89..08f052b8393 100644 --- a/lua/nvim-tree/_meta/config/renderer.lua +++ b/lua/nvim-tree/_meta/config/renderer.lua @@ -56,25 +56,25 @@ error("Cannot require a meta file") ---(default: `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) ---@field decorators? (string|nvim_tree.api.decorator.UserDecorator)[] --- ----(default: `none`) +---(default: `"none"`) ---@field highlight_git? nvim_tree.Config.Renderer.Highlight --- ----(default: `none`) +---(default: `"none"`) ---@field highlight_opened_files? nvim_tree.Config.Renderer.Highlight --- ----(default: `none`) +---(default: `"none"`) ---@field highlight_hidden? nvim_tree.Config.Renderer.Highlight --- ----(default: `none`) +---(default: `"none"`) ---@field highlight_modified? nvim_tree.Config.Renderer.Highlight --- ----(default: `none`) +---(default: `"none"`) ---@field highlight_bookmarks? nvim_tree.Config.Renderer.Highlight --- ----(default: `none`) +---(default: `"none"`) ---@field highlight_diagnostics? nvim_tree.Config.Renderer.Highlight --- ----(default: `name`) +---(default: `"name"`) ---@field highlight_clipboard? nvim_tree.Config.Renderer.Highlight --- ---Highlight special files and directories with `NvimTreeSpecial*`. @@ -108,15 +108,15 @@ error("Cannot require a meta file") ---@class nvim_tree.Config.Renderer.IndentMarkers.Icons ---@inlinedoc --- ----(default: `└` ) +---(default: `"└"`) ---@field corner? string ----(default: `│` ) +---(default: `"│"`) ---@field edge? string ----(default: `│` ) +---(default: `"│"`) ---@field item? string ----(default: `─` ) +---(default: `"─"`) ---@field bottom? string ----(default: ` ` ) +---(default: `" "`) ---@field none? string @@ -144,7 +144,7 @@ error("Cannot require a meta file") ---@field padding? nvim_tree.Config.Renderer.Icons.Padding --- ---Separator between symlink source and target. ----(default: ` ➛ `) +---(default: `" ➛ "`) ---@field symlink_arrow? string --- ---[nvim_tree.Config.Renderer.Icons.Show] @@ -196,11 +196,11 @@ error("Cannot require a meta file") ---@inlinedoc --- ---Between icon and filename. ----(default: ` `) +---(default: `" "`) ---@field icon? string --- ---Between folder arrow icon and file/folder icon. ----(default: ` `) +---(default: `" "`) ---@field folder_arrow? string @@ -241,19 +241,19 @@ error("Cannot require a meta file") ---@class nvim_tree.Config.Renderer.Icons.Glyphs --- ---Files ----(default: `` ) +---(default: `""`) ---@field default? string --- ----(default: `` ) +---(default: `""`) ---@field symlink? string --- ----(default: `󰆤` ) +---(default: `"󰆤"`) ---@field bookmark? string --- ----(default: `●` ) +---(default: `"●"`) ---@field modified? string --- ----(default: `󰜌` ) +---(default: `"󰜌"`) ---@field hidden? string --- ---@field folder? nvim_tree.Config.Renderer.Icons.Glyphs.Folder @@ -269,17 +269,17 @@ error("Cannot require a meta file") ---@field arrow_closed? string ---(default: down arrow) ---@field arrow_open? string ----(default: `` ) +---(default: `""`) ---@field default? string ----(default: `` ) +---(default: `""`) ---@field open? string ----(default: `` ) +---(default: `""`) ---@field empty? string ----(default: `` ) +---(default: `""`) ---@field empty_open? string ----(default: `` ) +---(default: `""`) ---@field symlink? string ----(default: `` ) +---(default: `""`) ---@field symlink_open? string @@ -287,17 +287,17 @@ error("Cannot require a meta file") ---[nvim_tree.Config.Renderer.Icons.Glyphs.Git]() ---@class nvim_tree.Config.Renderer.Icons.Glyphs.Git ---@inlinedoc ----(default: `✗` ) +---(default: `"✗"`) ---@field unstaged? string ----(default: `✓` ) +---(default: `"✓"`) ---@field staged? string ----(default: `` ) +---(default: `""`) ---@field unmerged? string ----(default: `➜` ) +---(default: `"➜"`) ---@field renamed? string ----(default: `★` ) +---(default: `"★"`) ---@field untracked? string ----(default: `` ) +---(default: `""`) ---@field deleted? string ----(default: `◌` ) +---(default: `"◌"`) ---@field ignored? string diff --git a/lua/nvim-tree/_meta/config/sort.lua b/lua/nvim-tree/_meta/config/sort.lua index e33ec0f29dc..1e50b256178 100644 --- a/lua/nvim-tree/_meta/config/sort.lua +++ b/lua/nvim-tree/_meta/config/sort.lua @@ -11,12 +11,12 @@ error("Cannot require a meta file") ---Sort files within a directory. --- ---{sorter} presets [nvim_tree.Config.Sort.Sorter]() ----- `name` ----- `case_sensitive` name ----- `modification_time` ----- `extension` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz` ----- `suffix` uses the last e.g. `foo.tar.gz` -> `.gz` ----- `filetype` [filetype] +---- `"name"` +---- `"case_sensitive"` name +---- `"modification_time"` +---- `"extension"` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz` +---- `"suffix"` uses the last e.g. `foo.tar.gz` -> `.gz` +---- `"filetype"` [filetype] --- ---{sorter} may be a function that is passed a list of `nvim_tree.api.Node` to be sorted in place e.g. ---```lua @@ -36,7 +36,7 @@ error("Cannot require a meta file") ---@class nvim_tree.Config.Sort --- ----(default: `name`) +---(default: `"name"`) ---@field sorter? nvim_tree.Config.Sort.Sorter|(fun(nodes: nvim_tree.api.Node[]): nvim_tree.Config.Sort.Sorter?) --- ---Sort folders before files. Has no effect when {sorter} is a function. diff --git a/lua/nvim-tree/_meta/config/system_open.lua b/lua/nvim-tree/_meta/config/system_open.lua index dffd5eaea77..e24c81b082f 100644 --- a/lua/nvim-tree/_meta/config/system_open.lua +++ b/lua/nvim-tree/_meta/config/system_open.lua @@ -20,7 +20,6 @@ error("Cannot require a meta file") ---@class nvim_tree.Config.SystemOpen --- ---The open command itself ----(default: `xdg-open`, `open` or `cmd`) ---@field cmd? string --- ---Optional argument list. Leave empty for OS specific default. diff --git a/lua/nvim-tree/_meta/config/trash.lua b/lua/nvim-tree/_meta/config/trash.lua index 4724caa956d..594222ad258 100644 --- a/lua/nvim-tree/_meta/config/trash.lua +++ b/lua/nvim-tree/_meta/config/trash.lua @@ -13,6 +13,5 @@ error("Cannot require a meta file") ---@class nvim_tree.Config.Trash --- ----External command. ----(default: `gio trash` or `trash`) +---(default: `"gio trash"` or `"trash"`) ---@field cmd? string diff --git a/lua/nvim-tree/_meta/config/view.lua b/lua/nvim-tree/_meta/config/view.lua index dfcddaa0449..7a2036c4666 100644 --- a/lua/nvim-tree/_meta/config/view.lua +++ b/lua/nvim-tree/_meta/config/view.lua @@ -39,7 +39,7 @@ error("Cannot require a meta file") ---(default: `15`) ---@field debounce_delay? integer --- ----(default: `left`) +---(default: `"left"`) ---@field side? "left"|"right" --- ---Preserves window proportions when opening a file. If `false`, the height and width of windows other than nvim-tree will be equalized. @@ -55,7 +55,7 @@ error("Cannot require a meta file") ---@field relativenumber? boolean --- ---['signcolumn'] ----(default: `yes`) +---(default: `"yes"`) ---@field signcolumn? "yes"|"auto"|"no" --- ---(default: `30`) @@ -89,7 +89,7 @@ error("Cannot require a meta file") ---Configure floating window behaviour --- ----{open_win_config} is passed directly to [nvim_open_win()], default: +---{open_win_config} is passed to [nvim_open_win()], default: ---```lua ---{ --- relative = "editor", @@ -109,5 +109,5 @@ error("Cannot require a meta file") ---(default: `true`) ---@field quit_on_focus_loss? boolean --- ----(default: above) +---(default: `{ relative = "editor", border = "rounded", width = 30, height = 30, row = 1, col = 1, }`) ---@field open_win_config? vim.api.keyset.win_config|(fun(): vim.api.keyset.win_config) From e5f0c6f1ee151dcb82fb83cc7dab6d6a92981564 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Wed, 14 Jan 2026 19:04:38 +1100 Subject: [PATCH 064/170] docs(#2934): normalise all icon and highlight --- doc/nvim-tree-lua.txt | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 4c97e2153f9..67b891bb8ef 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -1496,48 +1496,48 @@ Highlighting is additive, with higher precedence overriding lower. applied and its precedence. See |nvim-tree-decorators| for information on creating custom decorators. < -ICON +`ICON` Enable via |nvim_tree.Config.Renderer.Icons.Show -REQUIRES +`REQUIRES` Feature must be enabled to show icons and highlighting. -PLACEMENT *nvim_tree.Config.Renderer.Icons.Placement* +`PLACEMENT` *nvim_tree.Config.Renderer.Icons.Placement* Where to place the icon: |nvim_tree.Config.Renderer.Icons| {_placement} • `before`: before file/folder, after the file/folders icons • `after`: after file/folder • `signcolumn`: far left, requires |nvim_tree.Config.View| {signcolumn}. • `right_align`: far right -HIGHLIGHT *nvim_tree.Config.Renderer.Highlight* +`HIGHLIGHT` *nvim_tree.Config.Renderer.Highlight* What should be highlighted: |nvim_tree.Config.Renderer| {highlight_} • `none`: no highlighting • `icon`: icon only • `name`: name only • `all`: icon and name -DEVICONS +`DEVICONS` Glyphs and their colors will be overridden by optional plugin: `nvim-tree/nvim-web-devicons` |nvim_tree.Config.Renderer.Icons.WebDevicons| -GLYPHS +`GLYPHS` Icon glyphs definitions. -GROUPS +`GROUPS` Applicable highlight groups: |nvim-tree-highlight-groups| Some defaults noted. In ascending order of default highlight precedence: -WHAT ICON REQUIRES PLACEMENT HIGHLIGHT DEVICONS GLYPHS GROUPS -File Icon {file} `Y` - - - `Y` |nvim_tree.Config.Renderer.Icons.Glyphs| {default} `NvimTreeNormal` `NvimTreeFileIcon` -Folder Icon {folder} `Y` - - - `Y` |nvim_tree.Config.Renderer.Icons.Glyphs.Folder| `NvimTree*FolderName` `NvimTree*FolderIcon` -Git Status {git} `Y` |nvim_tree.Config.Git| {git_placement} `before` {highlight_git} `none` `Y` |nvim_tree.Config.Renderer.Icons.Glyphs.Git| `NvimTreeGit* -|bufloaded()| - - - {highlight_opened_files} `none` `N` - `NvimTreeOpened* -Dotfiles {hidden} `N` - {hidden_placement} `after` {highlight_hidden} `none` `N` |nvim_tree.Config.Renderer.Icons.Glyphs| {hidden} `NvimTreeHidden*` -|'modified'| {modified} `Y` |nvim_tree.Config.Modified| {modified_placement} `after` {highlight_modified} `none` `N` |nvim_tree.Config.Renderer.Icons.Glyphs| {modified} `NvimTreeModified*` -Bookmarked {bookmarks} `Y` - {bookmarks_placement} `signcolumn` {highlight_bookmarks} `none` `N` |nvim_tree.Config.Renderer.Icons.Glyphs| {bookmark} `NvimTreeBookmark*` -Diag Status {diagnostics} `Y` |nvim_tree.Config.Diagnostics| {diagnostics_placement} `signcolumn` {highlight_diagnostics} `none` `N` |nvim_tree.Config.Diagnostics.Icons| `NvimTreeDiagnostic*` -Cut/Copied - - - {highlight_clipboard} `name` `N` - `NvimTreeCutHL` `NvimTreeCopiedHL` +`WHAT ICON REQUIRES PLACEMENT HIGHLIGHT GLYPHS DEVICONS GROUPS` +File Icon {file} Y - - - |nvim_tree.Config.Renderer.Icons.Glyphs| {default} Y `NvimTreeNormal`, `NvimTreeFileIcon` +Folder Icon {folder} Y - - - |nvim_tree.Config.Renderer.Icons.Glyphs.Folder| Y `NvimTree*FolderName`, `NvimTree*FolderIcon` +Git Status {git} Y |nvim_tree.Config.Git| {git_placement} `"before"` {highlight_git} `"none"` |nvim_tree.Config.Renderer.Icons.Glyphs.Git| N `NvimTreeGit*` +|bufloaded()| - - - {highlight_opened_files}`"none"` - N ` NvimTreeOpened*` +Dotfiles {hidden} N - {hidden_placement} `"after"` {highlight_hidden} `"none"` |nvim_tree.Config.Renderer.Icons.Glyphs| {hidden} N `NvimTreeHidden*` +|'modified'| {modified} Y |nvim_tree.Config.Modified| {modified_placement} `"after"` {highlight_modified} `"none"` |nvim_tree.Config.Renderer.Icons.Glyphs| {modified} N `NvimTreeModified*` +Bookmarked {bookmarks} Y - {bookmarks_placement} `"signcolumn"` {highlight_bookmarks} `"none"` |nvim_tree.Config.Renderer.Icons.Glyphs| {bookmark} N `NvimTreeBookmark*` +Diag Status {diagnostics}Y |nvim_tree.Config.Diagnostics| {diagnostics_placement}`"signcolumn"` {highlight_diagnostics} `"none" ` |nvim_tree.Config.Diagnostics.Icons| N `NvimTreeDiagnostic*` +Cut/Copied - - - {highlight_clipboard} `"name"` - N `NvimTreeCutHL`, `NvimTreeCopiedHL` ============================================================================== From e470cd1881969a5178226c0107a654aff4dc5593 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Thu, 15 Jan 2026 10:09:52 +1100 Subject: [PATCH 065/170] docs(#2934): remove @briefs as they are shown above the class tag --- doc/nvim-tree-lua.txt | 294 ++++++++---------- lua/nvim-tree/_meta/config.lua | 17 +- lua/nvim-tree/_meta/config/bookmarks.lua | 5 +- lua/nvim-tree/_meta/config/diagnostics.lua | 5 +- lua/nvim-tree/_meta/config/experimental.lua | 10 + .../_meta/config/filesystem_watchers.lua | 5 +- lua/nvim-tree/_meta/config/filters.lua | 16 +- lua/nvim-tree/_meta/config/git.lua | 5 +- lua/nvim-tree/_meta/config/help.lua | 5 +- .../_meta/config/hijack_directories.lua | 5 +- lua/nvim-tree/_meta/config/live_filter.lua | 5 +- lua/nvim-tree/_meta/config/log.lua | 5 +- lua/nvim-tree/_meta/config/modified.lua | 5 +- lua/nvim-tree/_meta/config/notify.lua | 5 +- lua/nvim-tree/_meta/config/sort.lua | 5 +- lua/nvim-tree/_meta/config/system_open.lua | 5 +- lua/nvim-tree/_meta/config/trash.lua | 5 +- .../_meta/config/update_focused_file.lua | 5 +- lua/nvim-tree/_meta/config/view.lua | 5 +- scripts/gen_vimdoc_config.lua | 1 + 20 files changed, 177 insertions(+), 236 deletions(-) create mode 100644 lua/nvim-tree/_meta/config/experimental.lua diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 67b891bb8ef..a4570997365 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -2110,26 +2110,25 @@ Example of function that can be passed: >lua ============================================================================== Class: Config *nvim-tree-config* -Arguments to pass to |nvim-tree-setup|. +*nvim_tree.Config* + Arguments to pass to |nvim-tree-setup|. -When a value is not present/nil, the default will be used. + When a value is not present/nil, the default will be used. -They can be validated by |lsp| when passed directly e.g. >lua - require("nvim-tree").setup({ - hijack_cursor = true, - }) + They can be validated by |lsp| when passed directly e.g. >lua + require("nvim-tree").setup({ + hijack_cursor = true, + }) < -or as a typed variable e.g. >lua - ---@type nvim_tree.Config - local config = { - hijack_cursor = true, - } - require("nvim-tree").setup(config) + or as a typed variable e.g. >lua + ---@type nvim_tree.Config + local config = { + hijack_cursor = true, + } + require("nvim-tree").setup(config) < - -*nvim_tree.Config* {on_attach} Runs when creating the nvim-tree buffer. Use this to set your |nvim-tree-mappings|. When not a function, |nvim-tree-mappings-default| will be used. @@ -2221,6 +2220,8 @@ or as a typed variable e.g. >lua |nvim_tree.Config.Help| • {ui}? (`nvim_tree.Config.UI`) |nvim_tree.Config.UI| + • {experimental}? (`nvim_tree.Config.Experimental`) + |nvim_tree.Config.Experimental| • {log}? (`nvim_tree.Config.Log`) |nvim_tree.Config.Log| @@ -2229,33 +2230,31 @@ or as a typed variable e.g. >lua ============================================================================== Class: Config.Sort *nvim-tree-config-sort* -Sort files within a directory. - -{sorter} presets *nvim_tree.Config.Sort.Sorter* -• `"name"` -• `"case_sensitive"` name -• `"modification_time"` -• `"extension"` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz` -• `"suffix"` uses the last e.g. `foo.tar.gz` -> `.gz` -• `"filetype"` |filetype| - -{sorter} may be a function that is passed a list of `nvim_tree.api.Node` to be -sorted in place e.g. >lua - - ---Sort by name length - ---@param nodes nvim_tree.api.Node[] - ---@return nvim_tree.Config.Sort.Sorter? - local sorter = function(nodes) - table.sort(nodes, function(a, b) - return #a.name < #b.name - end) - end +*nvim_tree.Config.Sort* + Sort files within a directory. + + {sorter} presets *nvim_tree.Config.Sort.Sorter* + • `"name"` + • `"case_sensitive"` name + • `"modification_time"` + • `"extension"` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz` + • `"suffix"` uses the last e.g. `foo.tar.gz` -> `.gz` + • `"filetype"` |filetype| + + {sorter} may be a function that is passed a list of `nvim_tree.api.Node` + to be sorted in place e.g. >lua + + ---Sort by name length + ---@param nodes nvim_tree.api.Node[] + ---@return nvim_tree.Config.Sort.Sorter? + local sorter = function(nodes) + table.sort(nodes, function(a, b) + return #a.name < #b.name + end) + end < -{sorter} may be a function that returns a |nvim_tree.Config.Sort.Sorter| - - -*nvim_tree.Config.Sort* + {sorter} may be a function that returns a |nvim_tree.Config.Sort.Sorter| Fields: ~ • {sorter}? (`nvim_tree.Config.Sort.Sorter|(fun(nodes: nvim_tree.api.Node[]): nvim_tree.Config.Sort.Sorter?)`) @@ -2271,22 +2270,20 @@ sorted in place e.g. >lua ============================================================================== Class: Config.View *nvim-tree-config-view* -Configures the dimensions and appearance of the nvim-tree window. +*nvim_tree.Config.View* + Configures the dimensions and appearance of the nvim-tree window. -The window is "docked" at the left by default, however may be configured to -float: |nvim_tree.Config.View.Float| + The window is "docked" at the left by default, however may be configured + to float: |nvim_tree.Config.View.Float| -{width} can be a |nvim_tree.Config.View.WidthSpec| for simple static control -or a |nvim_tree.Config.View.Width| for fully dynamic control based on longest -line. + {width} can be a |nvim_tree.Config.View.WidthSpec| for simple static + control or a |nvim_tree.Config.View.Width| for fully dynamic control based + on longest line. *nvim_tree.Config.View.WidthSpec* -• `string`: `x%` string e.g. `30%` -• `integer`: number of columns -• `function`: returns one of the above - - -*nvim_tree.Config.View* + • `string`: `x%` string e.g. `30%` + • `integer`: number of columns + • `function`: returns one of the above Fields: ~ • {centralize_selection}? (`boolean`, default: `false`) When @@ -2534,15 +2531,13 @@ Class: Config.Renderer *nvim-tree-config-renderer* ============================================================================== Class: Config.HijackDirectories *nvim-tree-config-hijack-directories* -Hijack directory buffers by replacing the directory buffer with the tree. - -Disable this option if you use vim-dirvish or dirbuf.nvim. - -If |nvim_tree.Config| {hijack_netrw} and {disable_netrw} are `false` this -feature will be disabled. +*nvim_tree.Config.HijackDirectories* + Hijack directory buffers by replacing the directory buffer with the tree. + Disable this option if you use vim-dirvish or dirbuf.nvim. -*nvim_tree.Config.HijackDirectories* + If |nvim_tree.Config| {hijack_netrw} and {disable_netrw} are `false` this + feature will be disabled. Fields: ~ • {enable}? (`boolean`) (default: `true`) @@ -2554,10 +2549,8 @@ feature will be disabled. ============================================================================== Class: Config.UpdateFocusedFile *nvim-tree-config-update-focused-file* -Update the focused file on |BufEnter|, uncollapsing folders recursively. - - *nvim_tree.Config.UpdateFocusedFile* + Update the focused file on |BufEnter|, uncollapsing folders recursively. Fields: ~ • {enable}? (`boolean`) (default: `false`) @@ -2588,20 +2581,18 @@ Update the focused file on |BufEnter|, uncollapsing folders recursively. ============================================================================== Class: Config.SystemOpen *nvim-tree-config-system-open* -Open files or directories via the OS. - -Nvim: -• `>=` 0.10 uses |vim.ui.open()| unless {cmd} is specified -• `<` 0.10 calls external {cmd}: - • UNIX: `xdg-open` - • macOS: `open` - • Windows: `cmd` - -Once nvim-tree minimum Nvim version is updated to 0.10, these options will no -longer be necessary and will be removed. +*nvim_tree.Config.SystemOpen* + Open files or directories via the OS. + Nvim: + • `>=` 0.10 uses |vim.ui.open()| unless {cmd} is specified + • `<` 0.10 calls external {cmd}: + • UNIX: `xdg-open` + • macOS: `open` + • Windows: `cmd` -*nvim_tree.Config.SystemOpen* + Once nvim-tree minimum Nvim version is updated to 0.10, these options will + no longer be necessary and will be removed. Fields: ~ • {cmd}? (`string`) The open command itself @@ -2614,21 +2605,19 @@ longer be necessary and will be removed. ============================================================================== Class: Config.Git *nvim-tree-config-git* -Git operations are run in the background thus status may not immediately -appear. - -Processes will be killed if they exceed {timeout} ms. Git integration will be -disabled following 5 timeouts and you will be notified. - -Git integration may be disabled for git top-level directories via -{disable_for_dirs}: -• A list of relative paths evaluated with |fnamemodify()| `:p` OR -• A function that is passed an absolute path and returns `true` to disable +*nvim_tree.Config.Git* + Git operations are run in the background thus status may not immediately + appear. -See |nvim-tree-icons-highlighting|. + Processes will be killed if they exceed {timeout} ms. Git integration will + be disabled following 5 timeouts and you will be notified. + Git integration may be disabled for git top-level directories via + {disable_for_dirs}: + • A list of relative paths evaluated with |fnamemodify()| `:p` OR + • A function that is passed an absolute path and returns `true` to disable -*nvim_tree.Config.Git* + See |nvim-tree-icons-highlighting|. Fields: ~ • {enable}? (`boolean`) (default: `true`) @@ -2650,12 +2639,10 @@ See |nvim-tree-icons-highlighting|. ============================================================================== Class: Config.Diagnostics *nvim-tree-config-diagnostics* -Integrate with |lsp| or COC diagnostics. - -See |nvim-tree-icons-highlighting|. - - *nvim_tree.Config.Diagnostics* + Integrate with |lsp| or COC diagnostics. + + See |nvim-tree-icons-highlighting|. Fields: ~ • {enable}? (`boolean`) (default: `false`) @@ -2686,15 +2673,13 @@ See |nvim-tree-icons-highlighting|. ============================================================================== Class: Config.Modified *nvim-tree-config-modified* -Indicate which files have unsaved modification. To see modified status in the -tree you will need: -• |nvim_tree.Config.Renderer.Icons.Show| {modified} OR -• |nvim_tree.Config.Renderer| {highlight_modified} - -See |nvim-tree-icons-highlighting|. - - *nvim_tree.Config.Modified* + Indicate which files have unsaved modification. To see modified status in + the tree you will need: + • |nvim_tree.Config.Renderer.Icons.Show| {modified} OR + • |nvim_tree.Config.Renderer| {highlight_modified} + + See |nvim-tree-icons-highlighting|. Fields: ~ • {enable}? (`boolean`) (default: `false`) @@ -2710,12 +2695,13 @@ See |nvim-tree-icons-highlighting|. ============================================================================== Class: Config.Filters *nvim-tree-config-filters* +*nvim_tree.Config.Filters* -Filters may be applied to the tree to exlude the display of file and directories. +Filters may be applied to the tree to exlude the display of file/directories. Multiple filters may be applied at once. -Filters can be set at startup and toggled live via API with default keymappings. +Filters can be set at startup or toggled live via API with default mappings. `I` {git_ignored} |nvim-tree-api.tree.toggle_gitignore_filter()| Ignore files based on `.gitignore`. @@ -2731,8 +2717,8 @@ Filters can be set at startup and toggled live via API with default keymappings. `B` {no_buffer} |nvim-tree-api.tree.toggle_no_buffer_filter()| Filter files that have no |buflisted()| buffer. - For performance reasons this may not immediately update on buffer delete/wipe. - A reload or filesystem event will result in an update. + For performance reasons buffer delete/wipe may not be immediately shown. + A reload or filesystem event will always result in an update. `M` {no_bookmark} |nvim-tree-api.tree.toggle_no_bookmark_filter()| Filter files that are not bookmarked. @@ -2746,11 +2732,8 @@ Filters can be set at startup and toggled live via API with default keymappings. All filters including live filter may be disabled via {enable} and toggled with |nvim-tree-api.tree.toggle_enable_filters()| -Files/directories may be {exclude}d from filtering: they will always be shown, -overriding {git_ignored}, {dotfiles} and {custom} - - -*nvim_tree.Config.Filters* +Files/directories may be {exclude}d from filtering: they will always be +shown, overriding {git_ignored}, {dotfiles} and {custom}. Fields: ~ • {enable}? (`boolean`, default: `true`) Enable all filters. @@ -2768,14 +2751,12 @@ overriding {git_ignored}, {dotfiles} and {custom} ============================================================================== Class: Config.LiveFilter *nvim-tree-config-live-filter* -Live filter allows you to filter the tree nodes dynamically, based on regex -matching, see |vim.regex| - -This feature is bound to the `f` key by default. The filter can be cleared -with the `F` key by default. - - *nvim_tree.Config.LiveFilter* + Live filter allows you to filter the tree nodes dynamically, based on + regex matching, see |vim.regex| + + This feature is bound to the `f` key by default. The filter can be cleared + with the `F` key by default. Fields: ~ • {prefix}? (`string`, default: `"[FILTER]: "`) Prefix of @@ -2788,21 +2769,19 @@ with the `F` key by default. ============================================================================== Class: Config.FilesystemWatchers *nvim-tree-config-filesystem-watchers* -Use file system watchers (libuv `uv_fs_event_t`) to monitor the filesystem for -changes and update the tree. - -With this feature, the tree will be partially updated on specific directory -changes, resulting in better performance. - -Watchers may be disabled for absolute directory paths via {ignore_dirs}. -• A list of |vim.regex| to match a path, backslash escaped e.g. - `"my-proj/\\.build$"` OR -• A function that is passed an absolute path and returns `true` to disable - This may be useful when a path is not in `.gitignore` or git integration is - disabled. +*nvim_tree.Config.FilesystemWatchers* + Use file system watchers (libuv `uv_fs_event_t`) to monitor the filesystem + for changes and update the tree. + With this feature, the tree will be partially updated on specific + directory changes, resulting in better performance. -*nvim_tree.Config.FilesystemWatchers* + Watchers may be disabled for absolute directory paths via {ignore_dirs}. + • A list of |vim.regex| to match a path, backslash escaped e.g. + `"my-proj/\\.build$"` OR + • A function that is passed an absolute path and returns `true` to disable + This may be useful when a path is not in `.gitignore` or git integration + is disabled. Fields: ~ • {enable}? (`boolean`) (default: `true`) @@ -2939,14 +2918,12 @@ Class: Config.Actions *nvim-tree-config-actions* ============================================================================== Class: Config.Trash *nvim-tree-config-trash* -Files may be trashed via an external command that must be installed on your -system. -• linux: `gio trash`, from linux package `glib2` -• macOS: `trash`, from homebrew package `trash` -• windows: `trash`, requires `trash-cli` or similar - - *nvim_tree.Config.Trash* + Files may be trashed via an external command that must be installed on + your system. + • linux: `gio trash`, from linux package `glib2` + • macOS: `trash`, from homebrew package `trash` + • windows: `trash`, requires `trash-cli` or similar Fields: ~ • {cmd}? (`string`) (default: `"gio trash"` or `"trash"`) @@ -2977,15 +2954,13 @@ Class: Config.Tab *nvim-tree-config-tab* ============================================================================== Class: Config.Notify *nvim-tree-config-notify* -nvim-tree |vim.log.levels| -• `ERROR`: hard errors e.g. failure to read from the file system. -• `WARN`: non-fatal errors e.g. unable to system open a file. -• `INFO`: information only e.g. file copy path confirmation. -• `DEBUG`: information for troubleshooting, e.g. failures in some window - closing operations. - - *nvim_tree.Config.Notify* + nvim-tree |vim.log.levels| + • `ERROR`: hard errors e.g. failure to read from the file system. + • `WARN`: non-fatal errors e.g. unable to system open a file. + • `INFO`: information only e.g. file copy path confirmation. + • `DEBUG`: information for troubleshooting, e.g. failures in some window + closing operations. Fields: ~ • {threshold}? (`vim.log.levels`, default: `vim.log.levels.INFO`) @@ -2998,13 +2973,11 @@ nvim-tree |vim.log.levels| ============================================================================== Class: Config.Bookmarks *nvim-tree-config-bookmarks* -Optionally {persist} bookmarks to a json file: -• `true` use default: `stdpath("data") .. "/nvim-tree-bookmarks.json"` -• `false` do not persist -• `string` absolute path of your choice - - *nvim_tree.Config.Bookmarks* + Optionally {persist} bookmarks to a json file: + • `true` use default: `stdpath("data") .. "/nvim-tree-bookmarks.json"` + • `false` do not persist + • `string` absolute path of your choice Fields: ~ • {persist}? (`boolean|string`) (default: `false`) @@ -3014,14 +2987,12 @@ Optionally {persist} bookmarks to a json file: ============================================================================== Class: Config.Help *nvim-tree-config-help* -Configure help window, default mapping `g?` +*nvim_tree.Config.Help* + Configure help window, default mapping `g?` *nvim_tree.Config.Help.SortBy* -• `"key"`: alphabetically by keymap -• `"desc"`: alphabetically by description - - -*nvim_tree.Config.Help* + • `"key"`: alphabetically by keymap + • `"desc"`: alphabetically by description Fields: ~ • {sort_by}? (`nvim_tree.Config.Help.SortBy`, default: `"key"`) @@ -3050,13 +3021,22 @@ Class: Config.UI *nvim-tree-config-ui* ============================================================================== -Class: Config.Log *nvim-tree-config-log* +Class: Config.Experimental *nvim-tree-config-experimental* + +*nvim_tree.Config.Experimental* + Experimental features that may become default or optional functionality. -Log to a file `nvim-tree.log` in |stdpath()| `log`, usually -`${XDG_STATE_HOME}/nvim` + In the event of a problem please disable the experiment and raise an + issue. + +============================================================================== +Class: Config.Log *nvim-tree-config-log* + *nvim_tree.Config.Log* + Log to a file `nvim-tree.log` in |stdpath()| `log`, usually + `${XDG_STATE_HOME}/nvim` Fields: ~ • {enable}? (`boolean`) (default: `false`) diff --git a/lua/nvim-tree/_meta/config.lua b/lua/nvim-tree/_meta/config.lua index 3c40236630b..aa3f7aa1b1f 100644 --- a/lua/nvim-tree/_meta/config.lua +++ b/lua/nvim-tree/_meta/config.lua @@ -2,8 +2,11 @@ error("Cannot require a meta file") ----@brief ---- + +-- Root class {field}s are documented manually above "Fields:" as there is insufficent room for them in the column. + + + ---Arguments to pass to [nvim-tree-setup]. --- ---When a value is not present/nil, the default will be used. @@ -23,13 +26,6 @@ error("Cannot require a meta file") --- } --- require("nvim-tree").setup(config) ---``` - - - --- Root class {field}s are documented manually above "Fields:" as there is insufficent room for them in the column. - - - ---{on_attach} Runs when creating the nvim-tree buffer. Use this to set your [nvim-tree-mappings]. When not a function, [nvim-tree-mappings-default] will be used. --- ---{hijack_cursor} keep the cursor on the first letter of the filename when moving in the tree. @@ -148,5 +144,8 @@ error("Cannot require a meta file") ---[nvim_tree.Config.UI] ---@field ui? nvim_tree.Config.UI --- +---[nvim_tree.Config.Experimental] +---@field experimental? nvim_tree.Config.Experimental +--- ---[nvim_tree.Config.Log] ---@field log? nvim_tree.Config.Log diff --git a/lua/nvim-tree/_meta/config/bookmarks.lua b/lua/nvim-tree/_meta/config/bookmarks.lua index c174097b2d7..83a3c3d0ac3 100644 --- a/lua/nvim-tree/_meta/config/bookmarks.lua +++ b/lua/nvim-tree/_meta/config/bookmarks.lua @@ -2,14 +2,11 @@ error("Cannot require a meta file") ----@brief ---Optionally {persist} bookmarks to a json file: ---- `true` use default: `stdpath("data") .. "/nvim-tree-bookmarks.json"` ---- `false` do not persist ---- `string` absolute path of your choice - - - +--- ---@class nvim_tree.Config.Bookmarks --- ---(default: `false`) diff --git a/lua/nvim-tree/_meta/config/diagnostics.lua b/lua/nvim-tree/_meta/config/diagnostics.lua index ea0dad8b707..44b0d6d4f8c 100644 --- a/lua/nvim-tree/_meta/config/diagnostics.lua +++ b/lua/nvim-tree/_meta/config/diagnostics.lua @@ -3,13 +3,10 @@ error("Cannot require a meta file") ----@brief ---Integrate with [lsp] or COC diagnostics. --- ---See [nvim-tree-icons-highlighting]. - - - +--- ---@class nvim_tree.Config.Diagnostics --- ---(default: `false`) diff --git a/lua/nvim-tree/_meta/config/experimental.lua b/lua/nvim-tree/_meta/config/experimental.lua new file mode 100644 index 00000000000..7d967866fd9 --- /dev/null +++ b/lua/nvim-tree/_meta/config/experimental.lua @@ -0,0 +1,10 @@ +---@meta +error("Cannot require a meta file") + + + +---Experimental features that may become default or optional functionality. +--- +---In the event of a problem please disable the experiment and raise an issue. +--- +---@class nvim_tree.Config.Experimental diff --git a/lua/nvim-tree/_meta/config/filesystem_watchers.lua b/lua/nvim-tree/_meta/config/filesystem_watchers.lua index fc66ab220e7..959d70017ac 100644 --- a/lua/nvim-tree/_meta/config/filesystem_watchers.lua +++ b/lua/nvim-tree/_meta/config/filesystem_watchers.lua @@ -3,7 +3,6 @@ error("Cannot require a meta file") ----@brief ---Use file system watchers (libuv `uv_fs_event_t`) to monitor the filesystem for changes and update the tree. --- ---With this feature, the tree will be partially updated on specific directory changes, resulting in better performance. @@ -12,9 +11,7 @@ error("Cannot require a meta file") --- - A list of [vim.regex] to match a path, backslash escaped e.g. `"my-proj/\\.build$"` OR --- - A function that is passed an absolute path and returns `true` to disable ---This may be useful when a path is not in `.gitignore` or git integration is disabled. - - - +--- ---@class nvim_tree.Config.FilesystemWatchers --- ---(default: `true`) diff --git a/lua/nvim-tree/_meta/config/filters.lua b/lua/nvim-tree/_meta/config/filters.lua index decfa9094bd..2c4182bb427 100644 --- a/lua/nvim-tree/_meta/config/filters.lua +++ b/lua/nvim-tree/_meta/config/filters.lua @@ -3,13 +3,12 @@ error("Cannot require a meta file") ----@brief ---
help
----Filters may be applied to the tree to exlude the display of file and directories.
+---Filters may be applied to the tree to exlude the display of file/directories.
 ---
 ---Multiple filters may be applied at once.
 ---
----Filters can be set at startup and toggled live via API with default keymappings.
+---Filters can be set at startup or toggled live via API with default mappings.
 ---
 ---`I`    {git_ignored}    |nvim-tree-api.tree.toggle_gitignore_filter()|
 ---   Ignore files based on `.gitignore`.
@@ -25,8 +24,8 @@ error("Cannot require a meta file")
 ---
 ---`B`    {no_buffer}      |nvim-tree-api.tree.toggle_no_buffer_filter()|
 ---   Filter files that have no |buflisted()| buffer.
----   For performance reasons this may not immediately update on buffer delete/wipe.
----   A reload or filesystem event will result in an update.
+---   For performance reasons buffer delete/wipe may not be immediately shown.
+---   A reload or filesystem event will always result in an update.
 ---
 ---`M`    {no_bookmark}    |nvim-tree-api.tree.toggle_no_bookmark_filter()|
 ---   Filter files that are not bookmarked.
@@ -40,12 +39,9 @@ error("Cannot require a meta file")
 ---All filters including live filter may be disabled via {enable} and toggled
 ---with |nvim-tree-api.tree.toggle_enable_filters()|
 ---
----Files/directories may be {exclude}d from filtering: they will always be shown,
----overriding {git_ignored}, {dotfiles} and {custom}
+---Files/directories may be {exclude}d from filtering: they will always be
+---shown, overriding {git_ignored}, {dotfiles} and {custom}.
 ---
- - - ---@class nvim_tree.Config.Filters --- ---Enable all filters. diff --git a/lua/nvim-tree/_meta/config/git.lua b/lua/nvim-tree/_meta/config/git.lua index ca04a044e82..318fec0aed1 100644 --- a/lua/nvim-tree/_meta/config/git.lua +++ b/lua/nvim-tree/_meta/config/git.lua @@ -3,7 +3,6 @@ error("Cannot require a meta file") ----@brief ---Git operations are run in the background thus status may not immediately appear. --- ---Processes will be killed if they exceed {timeout} ms. Git integration will be disabled following 5 timeouts and you will be notified. @@ -13,9 +12,7 @@ error("Cannot require a meta file") --- - A function that is passed an absolute path and returns `true` to disable --- ---See [nvim-tree-icons-highlighting]. - - - +--- ---@class nvim_tree.Config.Git --- ---(default: `true`) diff --git a/lua/nvim-tree/_meta/config/help.lua b/lua/nvim-tree/_meta/config/help.lua index 5e8c5750178..8724b397c6f 100644 --- a/lua/nvim-tree/_meta/config/help.lua +++ b/lua/nvim-tree/_meta/config/help.lua @@ -7,15 +7,12 @@ error("Cannot require a meta file") ----@brief ---Configure help window, default mapping `g?` --- ---[nvim_tree.Config.Help.SortBy]() ---- `"key"`: alphabetically by keymap ---- `"desc"`: alphabetically by description - - - +--- ---@class nvim_tree.Config.Help --- ---[nvim_tree.Config.Help.SortBy] diff --git a/lua/nvim-tree/_meta/config/hijack_directories.lua b/lua/nvim-tree/_meta/config/hijack_directories.lua index 872ae6bc17e..af601f4ac1e 100644 --- a/lua/nvim-tree/_meta/config/hijack_directories.lua +++ b/lua/nvim-tree/_meta/config/hijack_directories.lua @@ -3,15 +3,12 @@ error("Cannot require a meta file") ----@brief ---Hijack directory buffers by replacing the directory buffer with the tree. --- ---Disable this option if you use vim-dirvish or dirbuf.nvim. --- ---If [nvim_tree.Config] {hijack_netrw} and {disable_netrw} are `false` this feature will be disabled. - - - +--- ---@class nvim_tree.Config.HijackDirectories --- ---(default: `true`) diff --git a/lua/nvim-tree/_meta/config/live_filter.lua b/lua/nvim-tree/_meta/config/live_filter.lua index 5064b38991f..b5569a68d93 100644 --- a/lua/nvim-tree/_meta/config/live_filter.lua +++ b/lua/nvim-tree/_meta/config/live_filter.lua @@ -3,13 +3,10 @@ error("Cannot require a meta file") ----@brief --- Live filter allows you to filter the tree nodes dynamically, based on regex matching, see [vim.regex] --- --- This feature is bound to the `f` key by default. The filter can be cleared with the `F` key by default. - - - +--- ---@class nvim_tree.Config.LiveFilter --- ---Prefix of the filter displayed in the buffer. diff --git a/lua/nvim-tree/_meta/config/log.lua b/lua/nvim-tree/_meta/config/log.lua index e3808a16fa0..3f43101f2f8 100644 --- a/lua/nvim-tree/_meta/config/log.lua +++ b/lua/nvim-tree/_meta/config/log.lua @@ -3,11 +3,8 @@ error("Cannot require a meta file") ----@brief ---Log to a file `nvim-tree.log` in [stdpath()] `log`, usually `${XDG_STATE_HOME}/nvim` - - - +--- ---@class nvim_tree.Config.Log --- ---(default: `false`) diff --git a/lua/nvim-tree/_meta/config/modified.lua b/lua/nvim-tree/_meta/config/modified.lua index db59474f3a9..e527d6ee62e 100644 --- a/lua/nvim-tree/_meta/config/modified.lua +++ b/lua/nvim-tree/_meta/config/modified.lua @@ -3,16 +3,13 @@ error("Cannot require a meta file") ----@brief ---Indicate which files have unsaved modification. ---To see modified status in the tree you will need: --- - [nvim_tree.Config.Renderer.Icons.Show] {modified} OR --- - [nvim_tree.Config.Renderer] {highlight_modified} --- ---See [nvim-tree-icons-highlighting]. - - - +--- ---@class nvim_tree.Config.Modified --- ---(default: `false`) diff --git a/lua/nvim-tree/_meta/config/notify.lua b/lua/nvim-tree/_meta/config/notify.lua index fd1165d9e93..bf6b9493005 100644 --- a/lua/nvim-tree/_meta/config/notify.lua +++ b/lua/nvim-tree/_meta/config/notify.lua @@ -3,15 +3,12 @@ error("Cannot require a meta file") ----@brief ---nvim-tree |vim.log.levels| ---- `ERROR`: hard errors e.g. failure to read from the file system. ---- `WARN`: non-fatal errors e.g. unable to system open a file. ---- `INFO`: information only e.g. file copy path confirmation. ---- `DEBUG`: information for troubleshooting, e.g. failures in some window closing operations. - - - +--- ---@class nvim_tree.Config.Notify --- ---Specify minimum notification |vim.log.levels| diff --git a/lua/nvim-tree/_meta/config/sort.lua b/lua/nvim-tree/_meta/config/sort.lua index 1e50b256178..0646ab587a2 100644 --- a/lua/nvim-tree/_meta/config/sort.lua +++ b/lua/nvim-tree/_meta/config/sort.lua @@ -7,7 +7,6 @@ error("Cannot require a meta file") ----@brief ---Sort files within a directory. --- ---{sorter} presets [nvim_tree.Config.Sort.Sorter]() @@ -31,9 +30,7 @@ error("Cannot require a meta file") ---end ---``` ---{sorter} may be a function that returns a [nvim_tree.Config.Sort.Sorter] - - - +--- ---@class nvim_tree.Config.Sort --- ---(default: `"name"`) diff --git a/lua/nvim-tree/_meta/config/system_open.lua b/lua/nvim-tree/_meta/config/system_open.lua index e24c81b082f..00ea263e11a 100644 --- a/lua/nvim-tree/_meta/config/system_open.lua +++ b/lua/nvim-tree/_meta/config/system_open.lua @@ -3,7 +3,6 @@ error("Cannot require a meta file") ----@brief ---Open files or directories via the OS. --- ---Nvim: @@ -14,9 +13,7 @@ error("Cannot require a meta file") --- - Windows: `cmd` --- ---Once nvim-tree minimum Nvim version is updated to 0.10, these options will no longer be necessary and will be removed. - - - +--- ---@class nvim_tree.Config.SystemOpen --- ---The open command itself diff --git a/lua/nvim-tree/_meta/config/trash.lua b/lua/nvim-tree/_meta/config/trash.lua index 594222ad258..ad7a6f48cfc 100644 --- a/lua/nvim-tree/_meta/config/trash.lua +++ b/lua/nvim-tree/_meta/config/trash.lua @@ -3,14 +3,11 @@ error("Cannot require a meta file") ----@brief ---Files may be trashed via an external command that must be installed on your system. --- - linux: `gio trash`, from linux package `glib2` --- - macOS: `trash`, from homebrew package `trash` --- - windows: `trash`, requires `trash-cli` or similar - - - +--- ---@class nvim_tree.Config.Trash --- ---(default: `"gio trash"` or `"trash"`) diff --git a/lua/nvim-tree/_meta/config/update_focused_file.lua b/lua/nvim-tree/_meta/config/update_focused_file.lua index 0f0b5b571df..a193cddc0bc 100644 --- a/lua/nvim-tree/_meta/config/update_focused_file.lua +++ b/lua/nvim-tree/_meta/config/update_focused_file.lua @@ -3,11 +3,8 @@ error("Cannot require a meta file") ----@brief ---Update the focused file on [BufEnter], uncollapsing folders recursively. - - - +--- ---@class nvim_tree.Config.UpdateFocusedFile --- ---(default: `false`) diff --git a/lua/nvim-tree/_meta/config/view.lua b/lua/nvim-tree/_meta/config/view.lua index 7a2036c4666..1a9d24d78a0 100644 --- a/lua/nvim-tree/_meta/config/view.lua +++ b/lua/nvim-tree/_meta/config/view.lua @@ -7,7 +7,6 @@ error("Cannot require a meta file") ----@brief ---Configures the dimensions and appearance of the nvim-tree window. --- ---The window is "docked" at the left by default, however may be configured to float: [nvim_tree.Config.View.Float] @@ -18,9 +17,7 @@ error("Cannot require a meta file") ---- `string`: `x%` string e.g. `30%` ---- `integer`: number of columns ---- `function`: returns one of the above - - - +--- ---@class nvim_tree.Config.View --- ---When entering nvim-tree, reposition the view so that the current node is initially centralized, see [zz]. diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua index 72271a4be63..d65b887de45 100644 --- a/scripts/gen_vimdoc_config.lua +++ b/scripts/gen_vimdoc_config.lua @@ -28,6 +28,7 @@ local modules = { { helptag = "nvim-tree-config-bookmarks", title = "Class: Config.Bookmarks", path = "lua/nvim-tree/_meta/config/bookmarks.lua", }, { helptag = "nvim-tree-config-help", title = "Class: Config.Help", path = "lua/nvim-tree/_meta/config/help.lua", }, { helptag = "nvim-tree-config-ui", title = "Class: Config.UI", path = "lua/nvim-tree/_meta/config/ui.lua", name = "UI", }, + { helptag = "nvim-tree-config-experimental", title = "Class: Config.Experimental", path = "lua/nvim-tree/_meta/config/experimental.lua", }, { helptag = "nvim-tree-config-log", title = "Class: Config.Log", path = "lua/nvim-tree/_meta/config/log.lua", }, -- { helptag = "nvim-tree-api", title = "Lua module: nvim_tree.api", path = "lua/nvim-tree/_meta/api.lua", }, From 6c0e683fac41ad7cce779fb91a7245d67e8db3c0 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Thu, 15 Jan 2026 10:51:20 +1100 Subject: [PATCH 066/170] docs(#2934): don't 
 filters

---
 doc/nvim-tree-lua.txt                  | 55 +++++++++++++-------------
 lua/nvim-tree/_meta/config/filters.lua | 42 ++++++++------------
 2 files changed, 43 insertions(+), 54 deletions(-)

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index a4570997365..46b0f67c8a0 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -2696,44 +2696,43 @@ Class: Config.Modified                             *nvim-tree-config-modified*
 Class: Config.Filters                               *nvim-tree-config-filters*
 
 *nvim_tree.Config.Filters*
+    Filters may be applied to the tree to exlude the display of
+    file/directories.
 
-Filters may be applied to the tree to exlude the display of file/directories.
+    Multiple filters may be applied at once.
 
-Multiple filters may be applied at once.
+    Filters can be set at startup or toggled live via API with default
+    mappings.
 
-Filters can be set at startup or toggled live via API with default mappings.
+    `I     `{git_ignored}`         `|nvim-tree-api.tree.toggle_gitignore_filter()|
+    Ignore files based on `.gitignore`. Requires |nvim_tree.Config.Git|
 
-`I`    {git_ignored}    |nvim-tree-api.tree.toggle_gitignore_filter()|
-  Ignore files based on `.gitignore`.
-  Requires |nvim_tree.Config.Git|
+    `H     `{dotfiles}`            `|nvim-tree-api.tree.toggle_hidden_filter()|
+    Filter dotfiles: files/directories starting with a `.`
 
-`H`    {dotfiles}       |nvim-tree-api.tree.toggle_hidden_filter()|
-  Filter dotfiles: files starting with a `.`
+    `C     `{git_clean}`           `|nvim-tree-api.tree.toggle_git_clean_filter()|
+    Filter files with no git status. `.gitignore` files will not be filtered
+    when {git_ignored}, as they are effectively dirty.
 
-`C`    {git_clean}      |nvim-tree-api.tree.toggle_git_clean_filter()|
-  Filter files with no git status.
-  Git ignored files will not be filtered when {git_ignored}, as they are
-  effectively dirty.
+    `B     `{no_buffer}`           `|nvim-tree-api.tree.toggle_no_buffer_filter()|
+    Filter files that have no |buflisted()| buffer. For performance reasons
+    buffer delete/wipe may not be immediately shown. A reload or filesystem
+    event will always result in an update.
 
-`B`    {no_buffer}      |nvim-tree-api.tree.toggle_no_buffer_filter()|
-  Filter files that have no |buflisted()| buffer.
-  For performance reasons buffer delete/wipe may not be immediately shown.
-  A reload or filesystem event will always result in an update.
+    `M     `{no_bookmark}`         `|nvim-tree-api.tree.toggle_no_bookmark_filter()|
+    Filter files that are not bookmarked. Enabling this is not useful as there
+    is no means yet to persist bookmarks.
 
-`M`    {no_bookmark}    |nvim-tree-api.tree.toggle_no_bookmark_filter()|
-  Filter files that are not bookmarked.
-  Enabling this is not useful as there is no means yet to persist bookmarks.
+    `U     `{custom}`              `|nvim-tree-api.tree.toggle_custom_filter()|
+    Disable specific file/directory names via:
+    • a list of backslash escaped |vim.regex| strings e.g. `"^\\.git""`
+    • a function passed the absolute path of the directory.
 
-`U`    {custom}         |nvim-tree-api.tree.toggle_custom_filter()|
-  Disable file/directory names via:
-  a list of backslash escaped |vim.regex| strings e.g. `"^\\.git""`
-  OR a function passed the absolute path of the directory.
+    All filters including live filter may be disabled via {enable} and toggled
+    with |nvim-tree-api.tree.toggle_enable_filters()|
 
-All filters including live filter may be disabled via {enable} and toggled
-with |nvim-tree-api.tree.toggle_enable_filters()|
-
-Files/directories may be {exclude}d from filtering: they will always be
-shown, overriding {git_ignored}, {dotfiles} and {custom}.
+    Files/directories may be {exclude}d from filtering: they will always be
+    shown, overriding {git_ignored}, {dotfiles} and {custom}.
 
     Fields: ~
       • {enable}?       (`boolean`, default: `true`) Enable all filters.
diff --git a/lua/nvim-tree/_meta/config/filters.lua b/lua/nvim-tree/_meta/config/filters.lua
index 2c4182bb427..93de5d64733 100644
--- a/lua/nvim-tree/_meta/config/filters.lua
+++ b/lua/nvim-tree/_meta/config/filters.lua
@@ -3,45 +3,35 @@ error("Cannot require a meta file")
 
 
 
----
help
 ---Filters may be applied to the tree to exlude the display of file/directories.
 ---
 ---Multiple filters may be applied at once.
 ---
 ---Filters can be set at startup or toggled live via API with default mappings.
 ---
----`I`    {git_ignored}    |nvim-tree-api.tree.toggle_gitignore_filter()|
----   Ignore files based on `.gitignore`.
----   Requires |nvim_tree.Config.Git|
+---`I     `{git_ignored}`         `|nvim-tree-api.tree.toggle_gitignore_filter()|
+---Ignore files based on `.gitignore`. Requires |nvim_tree.Config.Git|
 ---
----`H`    {dotfiles}       |nvim-tree-api.tree.toggle_hidden_filter()|
----   Filter dotfiles: files starting with a `.`
+---`H     `{dotfiles}`            `|nvim-tree-api.tree.toggle_hidden_filter()|
+---Filter dotfiles: files/directories starting with a `.`
 ---
----`C`    {git_clean}      |nvim-tree-api.tree.toggle_git_clean_filter()|
----   Filter files with no git status.
----   Git ignored files will not be filtered when {git_ignored}, as they are
----   effectively dirty.
+---`C     `{git_clean}`           `|nvim-tree-api.tree.toggle_git_clean_filter()|
+---Filter files with no git status. `.gitignore` files will not be filtered when {git_ignored}, as they are effectively dirty.
 ---
----`B`    {no_buffer}      |nvim-tree-api.tree.toggle_no_buffer_filter()|
----   Filter files that have no |buflisted()| buffer.
----   For performance reasons buffer delete/wipe may not be immediately shown.
----   A reload or filesystem event will always result in an update.
+---`B     `{no_buffer}`           `|nvim-tree-api.tree.toggle_no_buffer_filter()|
+---Filter files that have no |buflisted()| buffer. For performance reasons buffer delete/wipe may not be immediately shown. A reload or filesystem event will always result in an update.
 ---
----`M`    {no_bookmark}    |nvim-tree-api.tree.toggle_no_bookmark_filter()|
----   Filter files that are not bookmarked.
----   Enabling this is not useful as there is no means yet to persist bookmarks.
+---`M     `{no_bookmark}`         `|nvim-tree-api.tree.toggle_no_bookmark_filter()|
+---Filter files that are not bookmarked. Enabling this is not useful as there is no means yet to persist bookmarks.
 ---
----`U`    {custom}         |nvim-tree-api.tree.toggle_custom_filter()|
----   Disable file/directory names via:
----   a list of backslash escaped |vim.regex| strings e.g. `"^\\.git""`
----   OR a function passed the absolute path of the directory.
+---`U     `{custom}`              `|nvim-tree-api.tree.toggle_custom_filter()|
+---Disable specific file/directory names via:
+---- a list of backslash escaped |vim.regex| strings e.g. `"^\\.git""`
+---- a function passed the absolute path of the directory.
 ---
----All filters including live filter may be disabled via {enable} and toggled
----with |nvim-tree-api.tree.toggle_enable_filters()|
+---All filters including live filter may be disabled via {enable} and toggled with |nvim-tree-api.tree.toggle_enable_filters()|
 ---
----Files/directories may be {exclude}d from filtering: they will always be
----shown, overriding {git_ignored}, {dotfiles} and {custom}.
----

+---Files/directories may be {exclude}d from filtering: they will always be shown, overriding {git_ignored}, {dotfiles} and {custom}.
 ---@class nvim_tree.Config.Filters
 ---
 ---Enable all filters.

From 20b2be17bf8116a6a0b2c053254caeaca6313b7b Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 15 Jan 2026 10:55:23 +1100
Subject: [PATCH 067/170] docs(#2934): add experimental example

---
 lua/nvim-tree/_meta/config/experimental.lua | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/lua/nvim-tree/_meta/config/experimental.lua b/lua/nvim-tree/_meta/config/experimental.lua
index 7d967866fd9..ce2afeeb1c8 100644
--- a/lua/nvim-tree/_meta/config/experimental.lua
+++ b/lua/nvim-tree/_meta/config/experimental.lua
@@ -8,3 +8,10 @@ error("Cannot require a meta file")
 ---In the event of a problem please disable the experiment and raise an issue.
 ---
 ---@class nvim_tree.Config.Experimental
+---
+--Example below for future reference:
+--
+--Buffers opened by nvim-tree will use with relative paths instead of absolute.
+--(default: false)
+--@field relative_path? boolean
+

From 4b654dbec78795d50225bef78f0e1d23616f0c1e Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 15 Jan 2026 11:23:20 +1100
Subject: [PATCH 068/170] docs(#2934): add gen_vimdoc.sh to CI

---
 .github/workflows/ci.yml |  6 ++++++
 .gitignore               |  1 +
 Makefile                 |  1 +
 scripts/gen_vimdoc.sh    | 20 +++++++++++++++-----
 4 files changed, 23 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 385b33b5b07..bf3a47ada62 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -70,6 +70,12 @@ jobs:
           curl -L "https://github.com/LuaLS/lua-language-server/releases/download/${{ matrix.luals_version }}/lua-language-server-${{ matrix.luals_version }}-linux-x64.tar.gz" | tar zx --directory luals
           echo "luals/bin" >> "$GITHUB_PATH"
 
+      - name: get Nvim source
+        run: |
+          mkdir -p src
+          curl -L 'https://github.com/neovim/neovim/archive/refs/tags/${{ nvim_version }}.tar.gz' | tar zx --directory src
+          echo "src/neovim-stable" >> "$NVIM_SRC"
+
       - run: make check
 
       - run: make help-check
diff --git a/.gitignore b/.gitignore
index faee0c43dd9..97422fc2180 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,5 @@
 /luals-out/
 /luals/
+/src/
 # backup vim files
 *~
diff --git a/Makefile b/Makefile
index 72326964a79..14d27d9e429 100644
--- a/Makefile
+++ b/Makefile
@@ -36,6 +36,7 @@ style-fix:
 #
 help-update:
 	scripts/help-update.sh
+	scripts/gen_vimdoc.sh
 
 #
 # CI
diff --git a/scripts/gen_vimdoc.sh b/scripts/gen_vimdoc.sh
index 03ebf5d89f8..3bde45e67c9 100755
--- a/scripts/gen_vimdoc.sh
+++ b/scripts/gen_vimdoc.sh
@@ -1,18 +1,28 @@
 #!/usr/bin/env sh
 
-# Wrapper around nvim help generator gen_vimdoc.lua, run as part of nvim's make doc target.
+# Wrapper around Nvim help generator gen_vimdoc.lua, run as part of Nvim's make doc target.
 #
-# Doesn't require nvim to have been built.
+# Doesn't require Nvim to have been built.
 #
-# Shims our moudules into gen_vimdoc_config.lua, replacing nvim's.
+# Shims our moudules into gen_vimdoc_config.lua, replacing Nvim's.
 #
 # There are some hardcoded expectations which we work around as commented.
 
 set -e
 
 if [ ! -d "${NVIM_SRC}" ]; then
-	echo "\$NVIM_SRC not set"
-	exit 1
+	cat << EOM
+
+\$NVIM_SRC not set
+
+Nvim source is required to run src/gen/gen_vimdoc.lua
+
+Please:
+  mkdir -p src
+  curl -L 'https://github.com/neovim/neovim/archive/refs/tags/stable.tar.gz' | tar zx --directory src
+  NVIM_SRC=src/neovim-stable ${0}
+EOM
+exit 1
 fi
 
 # runtime/doc is hardcoded, copy the help in

From 0a3df5e52fc3ce4a13033f5c94b568a3f36db85c Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 15 Jan 2026 11:25:42 +1100
Subject: [PATCH 069/170] docs(#2934): add gen_vimdoc.sh to CI

---
 .github/workflows/ci.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index bf3a47ada62..f93f3b080b5 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -73,7 +73,7 @@ jobs:
       - name: get Nvim source
         run: |
           mkdir -p src
-          curl -L 'https://github.com/neovim/neovim/archive/refs/tags/${{ nvim_version }}.tar.gz' | tar zx --directory src
+          curl -L 'https://github.com/neovim/neovim/archive/refs/tags/${{ matrix.nvim_version }}.tar.gz' | tar zx --directory src
           echo "src/neovim-stable" >> "$NVIM_SRC"
 
       - run: make check

From 385cfb0e8b0c5002d6f34a3777d1be6574fbff3c Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 15 Jan 2026 11:28:44 +1100
Subject: [PATCH 070/170] docs(#2934): add gen_vimdoc.sh to CI

---
 .github/workflows/ci.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index f93f3b080b5..56bc7e66e98 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -53,6 +53,7 @@ jobs:
 
     env:
       VIMRUNTIME: /home/runner/nvim-${{ matrix.nvim_version }}/share/nvim/runtime
+      NVIM_SRC: src/neovim-${{ matrix.nvim_version }}
 
     steps:
       - name: checkout
@@ -73,8 +74,7 @@ jobs:
       - name: get Nvim source
         run: |
           mkdir -p src
-          curl -L 'https://github.com/neovim/neovim/archive/refs/tags/${{ matrix.nvim_version }}.tar.gz' | tar zx --directory src
-          echo "src/neovim-stable" >> "$NVIM_SRC"
+          curl -L "https://github.com/neovim/neovim/archive/refs/tags/${{ matrix.nvim_version }}.tar.gz" | tar zx --directory src
 
       - run: make check
 

From 350b5909cebe348918ab924f66ba713e02cca626 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 15 Jan 2026 11:38:59 +1100
Subject: [PATCH 071/170] docs(#2934): temporarily --ignore-blank-lines during
 help check

---
 Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index 14d27d9e429..3750c61d584 100644
--- a/Makefile
+++ b/Makefile
@@ -42,7 +42,7 @@ help-update:
 # CI
 #
 help-check: help-update
-	git diff --exit-code doc/nvim-tree-lua.txt
+	git diff --ignore-blank-lines --exit-code doc/nvim-tree-lua.txt
 
 
 .PHONY: all lint style check luacheck style-check style-doc luals style-fix help-update help-check

From b39bb2b65771c60bdcce89fb214541ff58ebef18 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 15 Jan 2026 11:44:30 +1100
Subject: [PATCH 072/170] docs(#2934): add lintdoc.sh to CI

---
 Makefile           |  2 ++
 scripts/lintdoc.sh | 14 ++++++++++++--
 2 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/Makefile b/Makefile
index 3750c61d584..9b3b00cc71a 100644
--- a/Makefile
+++ b/Makefile
@@ -40,9 +40,11 @@ help-update:
 
 #
 # CI
+# --ignore-blank-lines is used as nightly has removed unnecessary blank lines that stable (0.11.5) currently inserts
 #
 help-check: help-update
 	git diff --ignore-blank-lines --exit-code doc/nvim-tree-lua.txt
+	@scripts/lintdoc.sh
 
 
 .PHONY: all lint style check luacheck style-check style-doc luals style-fix help-update help-check
diff --git a/scripts/lintdoc.sh b/scripts/lintdoc.sh
index 978f2d79b54..095bcf31723 100755
--- a/scripts/lintdoc.sh
+++ b/scripts/lintdoc.sh
@@ -15,8 +15,18 @@
 set -e
 
 if [ ! -d "${NVIM_SRC}" ]; then
-	echo "\$NVIM_SRC not set"
-	exit 1
+	cat << EOM
+
+\$NVIM_SRC not set
+
+Compiled Nvim source is required to run src/gen/gen_vimdoc.lua
+
+Please:
+  mkdir -p src
+  curl -L 'https://github.com/neovim/neovim/archive/refs/tags/stable.tar.gz' | tar zx --directory src
+  NVIM_SRC=src/neovim-stable ${0}
+EOM
+exit 1
 fi
 
 # runtime/doc in the nvim source is practically hardcoded, copy our help in

From c2b08fd3aafcd96767edcfa26d997abafc923c22 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 15 Jan 2026 11:47:11 +1100
Subject: [PATCH 073/170] docs(#2934): add lintdoc.sh to CI

---
 .github/workflows/ci.yml | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 56bc7e66e98..d8b0f4acf78 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -71,10 +71,12 @@ jobs:
           curl -L "https://github.com/LuaLS/lua-language-server/releases/download/${{ matrix.luals_version }}/lua-language-server-${{ matrix.luals_version }}-linux-x64.tar.gz" | tar zx --directory luals
           echo "luals/bin" >> "$GITHUB_PATH"
 
-      - name: get Nvim source
+      - name: build Nvim from source
         run: |
           mkdir -p src
           curl -L "https://github.com/neovim/neovim/archive/refs/tags/${{ matrix.nvim_version }}.tar.gz" | tar zx --directory src
+          cd src/${{ matrix.nvim_version }}
+          make
 
       - run: make check
 

From f0490bc063a229a819d828755888156844000693 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 15 Jan 2026 11:48:29 +1100
Subject: [PATCH 074/170] docs(#2934): add lintdoc.sh to CI

---
 .github/workflows/ci.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index d8b0f4acf78..4f1447de283 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -75,7 +75,7 @@ jobs:
         run: |
           mkdir -p src
           curl -L "https://github.com/neovim/neovim/archive/refs/tags/${{ matrix.nvim_version }}.tar.gz" | tar zx --directory src
-          cd src/${{ matrix.nvim_version }}
+          cd "${NVIM_SRC}"
           make
 
       - run: make check

From 4be6efc91d18495084876ddf5bd80e0b39c21c1d Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 15 Jan 2026 11:50:35 +1100
Subject: [PATCH 075/170] docs(#2934): move Nvim build and help-check to the
 end for faster turnaround

---
 .github/workflows/ci.yml | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 4f1447de283..c7832fc8e2f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -71,6 +71,12 @@ jobs:
           curl -L "https://github.com/LuaLS/lua-language-server/releases/download/${{ matrix.luals_version }}/lua-language-server-${{ matrix.luals_version }}-linux-x64.tar.gz" | tar zx --directory luals
           echo "luals/bin" >> "$GITHUB_PATH"
 
+      - run: make check
+
+      - run: make style
+
+      - run: make style-doc
+
       - name: build Nvim from source
         run: |
           mkdir -p src
@@ -78,10 +84,4 @@ jobs:
           cd "${NVIM_SRC}"
           make
 
-      - run: make check
-
       - run: make help-check
-
-      - run: make style
-
-      - run: make style-doc

From 56f486a864f51e7607a54bb0cc04e9fae68d15fd Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 15 Jan 2026 12:05:54 +1100
Subject: [PATCH 076/170] docs(#2934): use make lintdoc target directly

---
 scripts/gen_vimdoc.sh |  5 ++++-
 scripts/lintdoc.sh    | 20 ++++++++++----------
 2 files changed, 14 insertions(+), 11 deletions(-)

diff --git a/scripts/gen_vimdoc.sh b/scripts/gen_vimdoc.sh
index 3bde45e67c9..98899cd030a 100755
--- a/scripts/gen_vimdoc.sh
+++ b/scripts/gen_vimdoc.sh
@@ -20,11 +20,14 @@ Nvim source is required to run src/gen/gen_vimdoc.lua
 Please:
   mkdir -p src
   curl -L 'https://github.com/neovim/neovim/archive/refs/tags/stable.tar.gz' | tar zx --directory src
-  NVIM_SRC=src/neovim-stable ${0}
+  export NVIM_SRC=src/neovim-stable
 EOM
 exit 1
 fi
 
+# unset to ensure no collisions with system installs etc.
+unset VIMRUNTIME
+
 # runtime/doc is hardcoded, copy the help in
 mkdir -pv runtime/doc
 cp -v "doc/nvim-tree-lua.txt" runtime/doc
diff --git a/scripts/lintdoc.sh b/scripts/lintdoc.sh
index 095bcf31723..8f39bb7fe28 100755
--- a/scripts/lintdoc.sh
+++ b/scripts/lintdoc.sh
@@ -1,8 +1,8 @@
 #!/usr/bin/env sh
 
-# Wrapper around nvim help linter lintdoc.lua, run as part of nvim's make lintdoc target.
+# Wrapper around Nvim help linter lintdoc.lua, run as part of Nvim's make lintdoc target.
 #
-# Requires nvim to have been built.
+# Requires Nvim to have been built.
 #
 # Desired:
 # - tags valid
@@ -24,19 +24,19 @@ Compiled Nvim source is required to run src/gen/gen_vimdoc.lua
 Please:
   mkdir -p src
   curl -L 'https://github.com/neovim/neovim/archive/refs/tags/stable.tar.gz' | tar zx --directory src
-  NVIM_SRC=src/neovim-stable ${0}
+  export NVIM_SRC=src/neovim-stable
 EOM
 exit 1
 fi
 
-# runtime/doc in the nvim source is practically hardcoded, copy our help in
+# unset to ensure no collisions with system installs etc.
+unset VIMRUNTIME
+
+# runtime/doc in the Nvim source is practically hardcoded, copy our help in
 cp -v "doc/nvim-tree-lua.txt" "${NVIM_SRC}/runtime/doc"
 
-# run from within nvim source
+# run from within Nvim source
 cd "${NVIM_SRC}"
 
-# make nvim 
-make
-
-# execute the lint
-VIMRUNTIME=runtime scripts/lintdoc.lua
+# make nvim and execute the lint
+make lintdoc

From ada718b36ea5bd27b2015e2cbf0ae1bcad94be50 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 15 Jan 2026 12:18:34 +1100
Subject: [PATCH 077/170] docs(#2934): CONTRIBUTING.md updates for help
 generation and lint

---
 CONTRIBUTING.md | 27 ++++++++++++++++++++-------
 1 file changed, 20 insertions(+), 7 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index aa7262123c4..50bff754ea3 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -121,19 +121,32 @@ else
 end
 ```
 
-# Adding New Actions
+# Documentation
 
-To add a new action, add a file in `actions/name-of-the-action.lua`. You should export a `setup` function if some configuration is needed.
+## Config And Mappings
 
-Once you did, you should run `make help-update`
+When adding to or changing:
+1. `DEFAULT_OPTS`
+2. `Config` classes
+3. `on_attach` default mappings
 
-# Documentation
+You must generate help documentation. This requires neovim stable sources. You will be promted with instructions on fetching and referencing the source.
 
-## Opts
+```sh
+make help-update
+```
 
-When adding new options, you should declare the defaults in the main `nvim-tree.lua` file.
+This will:
+1. Update config defaults in `*nvim-tree-setup*`
+2. Regenerate from `*nvim-tree-config*` to the end of the file, see `gen_vimdoc.sh`
+3. Update default mappings in `*nvim-tree-mappings-default*` and `*nvim-tree-quickstart-help*`
+
+Commit your changes then run:
+```sh
+make help-check
+```
 
-Documentation for options should also be added to `nvim-tree-opts` in `doc/nvim-tree-lua.txt`
+This will re-run `help-update` and check that there are no diffs. It will also lint the documentation, see `lintdoc.sh`
 
 ## API
 

From cdb730d4bee367217bec05dc339245bb468c6633 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 15 Jan 2026 12:34:21 +1100
Subject: [PATCH 078/170] docs(#2934): revert API opts classes changes

---
 lua/nvim-tree/_meta/api.lua                   | 53 ---------------
 lua/nvim-tree/actions/node/buffer.lua         |  6 +-
 lua/nvim-tree/actions/tree/find-file.lua      |  2 +-
 .../actions/tree/modifiers/collapse.lua       |  6 +-
 .../actions/tree/modifiers/expand.lua         |  6 +-
 lua/nvim-tree/actions/tree/open.lua           |  2 +-
 lua/nvim-tree/actions/tree/resize.lua         |  2 +-
 lua/nvim-tree/actions/tree/toggle.lua         |  2 +-
 lua/nvim-tree/api.lua                         | 66 ++++++++++++++-----
 lua/nvim-tree/view.lua                        |  4 +-
 10 files changed, 66 insertions(+), 83 deletions(-)

diff --git a/lua/nvim-tree/_meta/api.lua b/lua/nvim-tree/_meta/api.lua
index 39643a11d58..d6847940781 100644
--- a/lua/nvim-tree/_meta/api.lua
+++ b/lua/nvim-tree/_meta/api.lua
@@ -1,59 +1,6 @@
 ---@meta
 error("Cannot require a meta file")
 
---
--- API Options
---
-
----@class (exact) nvim_tree.api.TreeOpenOpts
----@field path? string root directory for the tree
----@field current_window? boolean open the tree in the current window
----@field winid? number open the tree in the specified winid, overrides current_window
----@field find_file? boolean find the current buffer
----@field update_root? boolean requires find_file, see [nvim-tree.update_focused_file.update_root]
----@field focus? boolean focus the tree when opening, default true
-
----@class (exact) nvim_tree.api.TreeToggleOpts
----@field path? string root directory for the tree
----@field current_window? boolean open the tree in the current window
----@field winid? number open the tree in the specified [winid], overrides current_window
----@field find_file? boolean find the current buffer
----@field update_root? boolean requires find_file, see [nvim-tree.update_focused_file.update_root]
----@field focus? boolean focus the tree when opening, default true
-
----@class (exact) nvim_tree.api.TreeResizeOpts
----@field width? string|function|number|table new [nvim-tree.view.width] value
----@field absolute? number set the width
----@field relative? number relative width adjustment
-
----@class (exact) nvim_tree.api.TreeFindFileOpts
----@field buf? string|number absolute/relative path OR bufnr to find
----@field open? boolean open the tree if necessary
----@field current_window? boolean requires open, open in the current window
----@field winid? number open the tree in the specified [winid], overrides current_window
----@field update_root? boolean see [nvim-tree.update_focused_file.update_root]
----@field focus? boolean focus the tree
-
----@class (exact) nvim_tree.api.CollapseOpts
----@field keep_buffers? boolean do not collapse nodes with open buffers
-
----@class (exact) nvim_tree.api.TreeExpandOpts
----@field expand_until? (fun(expansion_count: integer, node: Node): boolean) Return true if node should be expanded. expansion_count is the total number of folders expanded.
-
----@class (exact) nvim_tree.api.TreeIsVisibleOpts
----@field tabpage? number as per [nvim_get_current_tabpage()]
----@field any_tabpage? boolean visible on any tab, default false
-
----@class (exact) nvim_tree.api.TreeWinIdOpts
----@field tabpage? number tabpage, 0 or nil for current, default nil
-
----@class (exact) nvim_tree.api.NodeEditOpts
----@field quit_on_open? boolean quits the tree when opening the file
----@field focus? boolean keep focus in the tree when opening the file
-
----@class (exact) nvim_tree.api.NodeBufferOpts
----@field force? boolean delete/wipe even if buffer is modified, default false
-
 --
 -- Nodes
 --
diff --git a/lua/nvim-tree/actions/node/buffer.lua b/lua/nvim-tree/actions/node/buffer.lua
index 00cd3efdc63..425fcfa4ba6 100644
--- a/lua/nvim-tree/actions/node/buffer.lua
+++ b/lua/nvim-tree/actions/node/buffer.lua
@@ -4,14 +4,14 @@ local notify = require("nvim-tree.notify")
 local M = {}
 
 ---@param node Node
----@param opts nvim_tree.api.NodeBufferOpts|nil
+---@param opts ApiNodeDeleteWipeBufferOpts|nil
 ---@return nil
 function M.delete(node, opts)
   M.delete_buffer("delete", node.absolute_path, opts)
 end
 
 ---@param node Node
----@param opts nvim_tree.api.NodeBufferOpts|nil
+---@param opts ApiNodeDeleteWipeBufferOpts|nil
 ---@return nil
 function M.wipe(node, opts)
   M.delete_buffer("wipe", node.absolute_path, opts)
@@ -21,7 +21,7 @@ end
 
 ---@param mode ApiNodeDeleteWipeBufferMode
 ---@param filename string
----@param opts nvim_tree.api.NodeBufferOpts|nil
+---@param opts ApiNodeDeleteWipeBufferOpts|nil
 ---@return nil
 function M.delete_buffer(mode, filename, opts)
   if type(mode) ~= "string" then
diff --git a/lua/nvim-tree/actions/tree/find-file.lua b/lua/nvim-tree/actions/tree/find-file.lua
index b0d2834232f..8a05bf6db45 100644
--- a/lua/nvim-tree/actions/tree/find-file.lua
+++ b/lua/nvim-tree/actions/tree/find-file.lua
@@ -6,7 +6,7 @@ local finders_find_file = require("nvim-tree.actions.finders.find-file")
 local M = {}
 
 --- Find file or buffer
----@param opts nvim_tree.api.TreeFindFileOpts|nil|boolean legacy -> opts.buf
+---@param opts ApiTreeFindFileOpts|nil|boolean legacy -> opts.buf
 function M.fn(opts)
   -- legacy arguments
   if type(opts) == "string" then
diff --git a/lua/nvim-tree/actions/tree/modifiers/collapse.lua b/lua/nvim-tree/actions/tree/modifiers/collapse.lua
index 5c46cbdcae3..51a15f3d464 100644
--- a/lua/nvim-tree/actions/tree/modifiers/collapse.lua
+++ b/lua/nvim-tree/actions/tree/modifiers/collapse.lua
@@ -26,7 +26,7 @@ end
 
 ---Collapse a node, root if nil
 ---@param node Node?
----@param opts nvim_tree.api.CollapseOpts
+---@param opts ApiCollapseOpts
 local function collapse(node, opts)
   local explorer = core.get_explorer()
   if not explorer then
@@ -60,7 +60,7 @@ local function collapse(node, opts)
 end
 
 
----@param opts nvim_tree.api.CollapseOpts|boolean|nil legacy -> opts.keep_buffers
+---@param opts ApiCollapseOpts|boolean|nil legacy -> opts.keep_buffers
 function M.all(opts)
   -- legacy arguments
   if type(opts) == "boolean" then
@@ -73,7 +73,7 @@ function M.all(opts)
 end
 
 ---@param node Node
----@param opts nvim_tree.api.CollapseOpts?
+---@param opts ApiCollapseOpts?
 function M.node(node, opts)
   collapse(node, opts or {})
 end
diff --git a/lua/nvim-tree/actions/tree/modifiers/expand.lua b/lua/nvim-tree/actions/tree/modifiers/expand.lua
index c4a1274522b..44e3fa67baa 100644
--- a/lua/nvim-tree/actions/tree/modifiers/expand.lua
+++ b/lua/nvim-tree/actions/tree/modifiers/expand.lua
@@ -125,7 +125,7 @@ local function gen_iterator(should_descend)
 end
 
 ---@param node Node?
----@param expand_opts nvim_tree.api.TreeExpandOpts?
+---@param expand_opts ApiTreeExpandOpts?
 local function expand_node(node, expand_opts)
   if not node then
     return
@@ -141,14 +141,14 @@ end
 
 ---Expand the directory node or the root
 ---@param node Node
----@param expand_opts nvim_tree.api.TreeExpandOpts?
+---@param expand_opts ApiTreeExpandOpts?
 function M.all(node, expand_opts)
   expand_node(node and node:as(DirectoryNode) or core.get_explorer(), expand_opts)
 end
 
 ---Expand the directory node or parent node
 ---@param node Node
----@param expand_opts nvim_tree.api.TreeExpandOpts?
+---@param expand_opts ApiTreeExpandOpts?
 function M.node(node, expand_opts)
   if not node then
     return
diff --git a/lua/nvim-tree/actions/tree/open.lua b/lua/nvim-tree/actions/tree/open.lua
index 0c819ef83cb..ff2da837b87 100644
--- a/lua/nvim-tree/actions/tree/open.lua
+++ b/lua/nvim-tree/actions/tree/open.lua
@@ -5,7 +5,7 @@ local finders_find_file = require("nvim-tree.actions.finders.find-file")
 local M = {}
 
 ---Open the tree, focusing if already open.
----@param opts nvim_tree.api.TreeOpenOpts|nil|string legacy -> opts.path
+---@param opts ApiTreeOpenOpts|nil|string legacy -> opts.path
 function M.fn(opts)
   -- legacy arguments
   if type(opts) == "string" then
diff --git a/lua/nvim-tree/actions/tree/resize.lua b/lua/nvim-tree/actions/tree/resize.lua
index 43fba021134..e8d4e950729 100644
--- a/lua/nvim-tree/actions/tree/resize.lua
+++ b/lua/nvim-tree/actions/tree/resize.lua
@@ -3,7 +3,7 @@ local view = require("nvim-tree.view")
 local M = {}
 
 ---Resize the tree, persisting the new size.
----@param opts nvim_tree.api.TreeResizeOpts|nil
+---@param opts ApiTreeResizeOpts|nil
 function M.fn(opts)
   if opts == nil then
     -- reset to config values
diff --git a/lua/nvim-tree/actions/tree/toggle.lua b/lua/nvim-tree/actions/tree/toggle.lua
index c2c4153a3c7..10aa978467e 100644
--- a/lua/nvim-tree/actions/tree/toggle.lua
+++ b/lua/nvim-tree/actions/tree/toggle.lua
@@ -5,7 +5,7 @@ local finders_find_file = require("nvim-tree.actions.finders.find-file")
 local M = {}
 
 ---Toggle the tree.
----@param opts nvim_tree.api.TreeToggleOpts|nil|boolean legacy -> opts.find_file
+---@param opts ApiTreeToggleOpts|nil|boolean legacy -> opts.find_file
 ---@param no_focus string|nil legacy -> opts.focus
 ---@param cwd boolean|nil legacy -> opts.path
 ---@param bang boolean|nil legacy -> opts.update_root
diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index 75c3483797d..e5a109142f1 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -14,18 +14,6 @@ local FileLinkNode = require("nvim-tree.node.file-link")
 local RootNode = require("nvim-tree.node.root")
 local UserDecorator = require("nvim-tree.renderer.decorator.user")
 
--- Backwards compatibility aliases for renamed classes
----@alias ApiTreeOpenOpts nvim_tree.api.TreeOpenOpts
----@alias ApiTreeToggleOpts nvim_tree.api.TreeToggleOpts
----@alias ApiTreeResizeOpts nvim_tree.api.TreeResizeOpts
----@alias ApiTreeFindFileOpts nvim_tree.api.TreeFindFileOpts
----@alias ApiCollapseOpts nvim_tree.api.CollapseOpts
----@alias ApiTreeExpandOpts nvim_tree.api.TreeExpandOpts
----@alias ApiTreeIsVisibleOpts nvim_tree.api.TreeIsVisibleOpts
----@alias ApiTreeWinIdOpts nvim_tree.api.TreeWinIdOpts
----@alias NodeEditOpts nvim_tree.api.NodeEditOpts
----@alias ApiNodeDeleteWipeBufferOpts nvim_tree.api.NodeBufferOpts
-
 local Api = {
   tree = {},
   node = {
@@ -135,15 +123,35 @@ local function wrap_explorer_member(explorer_member, member_method)
   end)
 end
 
+---@class ApiTreeOpenOpts
+---@field path string|nil path
+---@field current_window boolean|nil default false
+---@field winid number|nil
+---@field find_file boolean|nil default false
+---@field update_root boolean|nil default false
+
 Api.tree.open = wrap(actions.tree.open.fn)
 Api.tree.focus = Api.tree.open
 
+---@class ApiTreeToggleOpts
+---@field path string|nil
+---@field current_window boolean|nil default false
+---@field winid number|nil
+---@field find_file boolean|nil default false
+---@field update_root boolean|nil default false
+---@field focus boolean|nil default true
+
 Api.tree.toggle = wrap(actions.tree.toggle.fn)
 Api.tree.close = wrap(view.close)
 Api.tree.close_in_this_tab = wrap(view.close_this_tab_only)
 Api.tree.close_in_all_tabs = wrap(view.close_all_tabs)
 Api.tree.reload = wrap_explorer("reload_explorer")
 
+---@class ApiTreeResizeOpts
+---@field width string|function|number|table|nil
+---@field absolute number|nil
+---@field relative number|nil
+
 Api.tree.resize = wrap(actions.tree.resize.fn)
 
 Api.tree.change_root = wrap(function(...)
@@ -171,11 +179,25 @@ Api.tree.change_root_to_parent = wrap_node(wrap_explorer("dir_up"))
 Api.tree.get_node_under_cursor = wrap_explorer("get_node_at_cursor")
 Api.tree.get_nodes = wrap_explorer("get_nodes")
 
+---@class ApiTreeFindFileOpts
+---@field buf string|number|nil
+---@field open boolean|nil default false
+---@field current_window boolean|nil default false
+---@field winid number|nil
+---@field update_root boolean|nil default false
+---@field focus boolean|nil default false
+
 Api.tree.find_file = wrap(actions.tree.find_file.fn)
 Api.tree.search_node = wrap(actions.finders.search_node.fn)
 
+---@class ApiCollapseOpts
+---@field keep_buffers boolean|nil default false
+
 Api.tree.collapse_all = wrap(actions.tree.modifiers.collapse.all)
 
+---@class ApiTreeExpandOpts
+---@field expand_until (fun(expansion_count: integer, node: Node): boolean)|nil
+
 Api.tree.expand_all = wrap_node(actions.tree.modifiers.expand.all)
 Api.tree.toggle_enable_filters = wrap_explorer_member("filters", "toggle")
 Api.tree.toggle_gitignore_filter = wrap_explorer_member_args("filters", "toggle", "git_ignored")
@@ -187,8 +209,15 @@ Api.tree.toggle_no_bookmark_filter = wrap_explorer_member_args("filters", "toggl
 Api.tree.toggle_help = wrap(help.toggle)
 Api.tree.is_tree_buf = wrap(utils.is_nvim_tree_buf)
 
+---@class ApiTreeIsVisibleOpts
+---@field tabpage number|nil
+---@field any_tabpage boolean|nil default false
+
 Api.tree.is_visible = wrap(view.is_visible)
 
+---@class ApiTreeWinIdOpts
+---@field tabpage number|nil default nil
+
 Api.tree.winid = wrap(view.winid)
 
 Api.fs.create = wrap_node_or_nil(actions.fs.create_file.fn)
@@ -209,9 +238,13 @@ Api.fs.copy.filename = wrap_node(wrap_explorer_member("clipboard", "copy_filenam
 Api.fs.copy.basename = wrap_node(wrap_explorer_member("clipboard", "copy_basename"))
 Api.fs.copy.relative_path = wrap_node(wrap_explorer_member("clipboard", "copy_path"))
 ---
+---@class NodeEditOpts
+---@field quit_on_open boolean|nil default false
+---@field focus boolean|nil default true
+
 ---@param mode string
 ---@param node Node
----@param edit_opts nvim_tree.api.NodeEditOpts?
+---@param edit_opts NodeEditOpts?
 local function edit(mode, node, edit_opts)
   local file_link = node:as(FileLinkNode)
   local path = file_link and file_link.link_to or node.absolute_path
@@ -239,10 +272,10 @@ end
 
 ---@param mode string
 ---@param toggle_group boolean?
----@return fun(node: Node, edit_opts: nvim_tree.api.NodeEditOpts?)
+---@return fun(node: Node, edit_opts: NodeEditOpts?)
 local function open_or_expand_or_dir_up(mode, toggle_group)
   ---@param node Node
-  ---@param edit_opts nvim_tree.api.NodeEditOpts?
+  ---@param edit_opts NodeEditOpts?
   return function(node, edit_opts)
     local root = node:as(RootNode)
     local dir = node:as(DirectoryNode)
@@ -297,6 +330,9 @@ Api.node.navigate.opened.prev = wrap_node(actions.moves.item.fn({ where = "prev"
 Api.node.expand = wrap_node(actions.tree.modifiers.expand.node)
 Api.node.collapse = wrap_node(actions.tree.modifiers.collapse.node)
 
+---@class ApiNodeDeleteWipeBufferOpts
+---@field force boolean|nil default false
+
 Api.node.buffer.delete = wrap_node(function(node, opts)
   actions.node.buffer.delete(node, opts)
 end)
diff --git a/lua/nvim-tree/view.lua b/lua/nvim-tree/view.lua
index 077fe6580c6..275e68635d0 100644
--- a/lua/nvim-tree/view.lua
+++ b/lua/nvim-tree/view.lua
@@ -438,7 +438,7 @@ function M.abandon_all_windows()
   end
 end
 
----@param opts? nvim_tree.api.TreeIsVisibleOpts
+---@param opts table|nil
 ---@return boolean
 function M.is_visible(opts)
   if opts and opts.tabpage then
@@ -487,7 +487,7 @@ function M.focus(winnr, open_if_closed)
 end
 
 --- Retrieve the winid of the open tree.
----@param opts nvim_tree.api.TreeWinIdOpts|nil
+---@param opts ApiTreeWinIdOpts|nil
 ---@return number|nil winid unlike get_winnr(), this returns nil if the nvim-tree window is not visible
 function M.winid(opts)
   local tabpage = opts and opts.tabpage

From cddb56fda6256164fe61a5c83bd27e9f915af35f Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sat, 17 Jan 2026 13:51:40 +1100
Subject: [PATCH 079/170] docs(#2934): harden gen and lint scripts, moving
 things out of nvim-tree source to prevent luals upset

---
 .github/workflows/ci.yml      |  4 +--
 scripts/gen_vimdoc.sh         | 61 +++++++++++++++++++++++------------
 scripts/gen_vimdoc_config.lua | 47 +++++++++++++--------------
 scripts/lintdoc.sh            | 39 +++++++++++++++-------
 4 files changed, 91 insertions(+), 60 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c7832fc8e2f..ca0cb4074f1 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -53,7 +53,7 @@ jobs:
 
     env:
       VIMRUNTIME: /home/runner/nvim-${{ matrix.nvim_version }}/share/nvim/runtime
-      NVIM_SRC: src/neovim-${{ matrix.nvim_version }}
+      DIR_NVIM_SRC: /home/runner/src/neovim-${{ matrix.nvim_version }}
 
     steps:
       - name: checkout
@@ -81,7 +81,7 @@ jobs:
         run: |
           mkdir -p src
           curl -L "https://github.com/neovim/neovim/archive/refs/tags/${{ matrix.nvim_version }}.tar.gz" | tar zx --directory src
-          cd "${NVIM_SRC}"
+          cd "${DIR_NVIM_SRC}"
           make
 
       - run: make help-check
diff --git a/scripts/gen_vimdoc.sh b/scripts/gen_vimdoc.sh
index 98899cd030a..8af3aa0b49a 100755
--- a/scripts/gen_vimdoc.sh
+++ b/scripts/gen_vimdoc.sh
@@ -10,43 +10,62 @@
 
 set -e
 
-if [ ! -d "${NVIM_SRC}" ]; then
+# unset to ensure no collisions with system installs etc.
+unset VIMRUNTIME
+
+# Use a directory outside of nvim_tree source. Adding lua files inside will (rightly) upset luals.
+DIR_NVT="${PWD}"
+DIR_WORK="/tmp/nvim-tree-gen_vimdoc"
+DIR_NVIM_SRC_DEF="/tmp/src/neovim-stable"
+
+if [ ! -f "${DIR_NVT}/scripts/gen_vimdoc.sh" ]; then
+	echo "Must be run from nvim-tree root"
+	exit 1
+fi
+
+if [ -z "${DIR_NVIM_SRC}" ] && [ -d "${DIR_NVIM_SRC_DEF}" ]; then
+	export DIR_NVIM_SRC="${DIR_NVIM_SRC_DEF}"
+	echo "Assumed DIR_NVIM_SRC=${DIR_NVIM_SRC}"
+fi
+
+if [ ! -d "${DIR_NVIM_SRC}" ]; then
 	cat << EOM
 
-\$NVIM_SRC not set
+\$DIR_NVIM_SRC=${DIR_NVIM_SRC} not set or missing.
 
-Nvim source is required to run src/gen/gen_vimdoc.lua
+Nvim source is required to run ${0}
 
 Please:
-  mkdir -p src
-  curl -L 'https://github.com/neovim/neovim/archive/refs/tags/stable.tar.gz' | tar zx --directory src
-  export NVIM_SRC=src/neovim-stable
+  mkdir -p ${DIR_NVIM_SRC_DEF}
+  curl -L 'https://github.com/neovim/neovim/archive/refs/tags/stable.tar.gz' | tar zx --directory $(dirname "${DIR_NVIM_SRC_DEF}")
+  export DIR_NVIM_SRC=/tmp/src/neovim-stable
 EOM
 exit 1
 fi
 
-# unset to ensure no collisions with system installs etc.
-unset VIMRUNTIME
+# clean up previous
+rm -rfv "${DIR_WORK}"
 
 # runtime/doc is hardcoded, copy the help in
-mkdir -pv runtime/doc
-cp -v "doc/nvim-tree-lua.txt" runtime/doc
+mkdir -pv "${DIR_WORK}/runtime/doc"
+cp -v "${DIR_NVT}/doc/nvim-tree-lua.txt" "${DIR_WORK}/runtime/doc"
 
 # modify gen_vimdoc.lua to use our config
-cp -v "${NVIM_SRC}/src/gen/gen_vimdoc.lua" gen_vimdoc.lua
-sed -i -E 's/spairs\(config\)/spairs\(require("gen_vimdoc_config")\)/g' gen_vimdoc.lua
+cp -v "${DIR_NVIM_SRC}/src/gen/gen_vimdoc.lua" "${DIR_WORK}/gen_vimdoc.lua"
+sed -i -E 's/spairs\(config\)/spairs\(require("gen_vimdoc_config")\)/g' "${DIR_WORK}/gen_vimdoc.lua"
 
 # use luacacts etc. from neovim src as well as our specific config
-export LUA_PATH="${NVIM_SRC}/src/?.lua;scripts/?.lua"
+export LUA_PATH="${DIR_NVIM_SRC}/src/?.lua;${DIR_NVT}/scripts/?.lua"
+
+# gen_vimdoc.lua doesn't like dashes in lua module names
+#   -> use nvim_tree instead of nvim-tree
+mkdir -pv "${DIR_WORK}/lua"
+ln -sv "${DIR_NVT}/lua/nvim-tree" "${DIR_WORK}/lua/nvim_tree"
 
 # generate
+cd "${DIR_WORK}" && pwd
 ./gen_vimdoc.lua
+cd -
 
-# move the generated help out
-mv -v "runtime/doc/nvim-tree-lua.txt" doc
-
-# clean up
-rmdir -v runtime/doc
-rmdir -v runtime
-rm -v gen_vimdoc.lua
-
+# copy the generated help out
+cp -v "${DIR_WORK}/runtime/doc/nvim-tree-lua.txt" "${DIR_NVT}/doc"
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index d65b887de45..e8dda6f50e1 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -8,31 +8,28 @@
 ---Generated within help files in this order
 ---@type Module[]
 local modules = {
-  { helptag = "nvim-tree-config",                     title = "Class: Config",                    path = "lua/nvim-tree/_meta/config.lua", },
-  { helptag = "nvim-tree-config-sort",                title = "Class: Config.Sort",               path = "lua/nvim-tree/_meta/config/sort.lua", },
-  { helptag = "nvim-tree-config-view",                title = "Class: Config.View",               path = "lua/nvim-tree/_meta/config/view.lua", },
-  { helptag = "nvim-tree-config-renderer",            title = "Class: Config.Renderer",           path = "lua/nvim-tree/_meta/config/renderer.lua", },
-  { helptag = "nvim-tree-config-hijack-directories",  title = "Class: Config.HijackDirectories",  path = "lua/nvim-tree/_meta/config/hijack_directories.lua", },
-  { helptag = "nvim-tree-config-update-focused-file", title = "Class: Config.UpdateFocusedFile",  path = "lua/nvim-tree/_meta/config/update_focused_file.lua", },
-  { helptag = "nvim-tree-config-system-open",         title = "Class: Config.SystemOpen",         path = "lua/nvim-tree/_meta/config/system_open.lua", },
-  { helptag = "nvim-tree-config-git",                 title = "Class: Config.Git",                path = "lua/nvim-tree/_meta/config/git.lua", },
-  { helptag = "nvim-tree-config-diagnostics",         title = "Class: Config.Diagnostics",        path = "lua/nvim-tree/_meta/config/diagnostics.lua", },
-  { helptag = "nvim-tree-config-modified",            title = "Class: Config.Modified",           path = "lua/nvim-tree/_meta/config/modified.lua", },
-  { helptag = "nvim-tree-config-filters",             title = "Class: Config.Filters",            path = "lua/nvim-tree/_meta/config/filters.lua", },
-  { helptag = "nvim-tree-config-live-filter",         title = "Class: Config.LiveFilter",         path = "lua/nvim-tree/_meta/config/live_filter.lua", },
-  { helptag = "nvim-tree-config-filesystem-watchers", title = "Class: Config.FilesystemWatchers", path = "lua/nvim-tree/_meta/config/filesystem_watchers.lua", },
-  { helptag = "nvim-tree-config-actions",             title = "Class: Config.Actions",            path = "lua/nvim-tree/_meta/config/actions.lua", },
-  { helptag = "nvim-tree-config-trash",               title = "Class: Config.Trash",              path = "lua/nvim-tree/_meta/config/trash.lua", },
-  { helptag = "nvim-tree-config-tab",                 title = "Class: Config.Tab",                path = "lua/nvim-tree/_meta/config/tab.lua", },
-  { helptag = "nvim-tree-config-notify",              title = "Class: Config.Notify",             path = "lua/nvim-tree/_meta/config/notify.lua", },
-  { helptag = "nvim-tree-config-bookmarks",           title = "Class: Config.Bookmarks",          path = "lua/nvim-tree/_meta/config/bookmarks.lua", },
-  { helptag = "nvim-tree-config-help",                title = "Class: Config.Help",               path = "lua/nvim-tree/_meta/config/help.lua", },
-  { helptag = "nvim-tree-config-ui",                  title = "Class: Config.UI",                 path = "lua/nvim-tree/_meta/config/ui.lua",                  name = "UI", },
-  { helptag = "nvim-tree-config-experimental",        title = "Class: Config.Experimental",       path = "lua/nvim-tree/_meta/config/experimental.lua", },
-  { helptag = "nvim-tree-config-log",                 title = "Class: Config.Log",                path = "lua/nvim-tree/_meta/config/log.lua", },
-
-  -- { helptag = "nvim-tree-api",                        title = "Lua module: nvim_tree.api",           path = "lua/nvim-tree/_meta/api.lua", },
-  -- { helptag = "nvim-tree-api-decorator",              title = "Lua module: nvim_tree.api.decorator", path = "lua/nvim-tree/_meta/api_decorator.lua", },
+  { helptag = "nvim-tree-config",                     title = "Class: Config",                    path = "./lua/nvim_tree/_meta/config.lua", },
+  { helptag = "nvim-tree-config-sort",                title = "Class: Config.Sort",               path = "./lua/nvim_tree/_meta/config/sort.lua", },
+  { helptag = "nvim-tree-config-view",                title = "Class: Config.View",               path = "./lua/nvim_tree/_meta/config/view.lua", },
+  { helptag = "nvim-tree-config-renderer",            title = "Class: Config.Renderer",           path = "./lua/nvim_tree/_meta/config/renderer.lua", },
+  { helptag = "nvim-tree-config-hijack-directories",  title = "Class: Config.HijackDirectories",  path = "./lua/nvim_tree/_meta/config/hijack_directories.lua", },
+  { helptag = "nvim-tree-config-update-focused-file", title = "Class: Config.UpdateFocusedFile",  path = "./lua/nvim_tree/_meta/config/update_focused_file.lua", },
+  { helptag = "nvim-tree-config-system-open",         title = "Class: Config.SystemOpen",         path = "./lua/nvim_tree/_meta/config/system_open.lua", },
+  { helptag = "nvim-tree-config-git",                 title = "Class: Config.Git",                path = "./lua/nvim_tree/_meta/config/git.lua", },
+  { helptag = "nvim-tree-config-diagnostics",         title = "Class: Config.Diagnostics",        path = "./lua/nvim_tree/_meta/config/diagnostics.lua", },
+  { helptag = "nvim-tree-config-modified",            title = "Class: Config.Modified",           path = "./lua/nvim_tree/_meta/config/modified.lua", },
+  { helptag = "nvim-tree-config-filters",             title = "Class: Config.Filters",            path = "./lua/nvim_tree/_meta/config/filters.lua", },
+  { helptag = "nvim-tree-config-live-filter",         title = "Class: Config.LiveFilter",         path = "./lua/nvim_tree/_meta/config/live_filter.lua", },
+  { helptag = "nvim-tree-config-filesystem-watchers", title = "Class: Config.FilesystemWatchers", path = "./lua/nvim_tree/_meta/config/filesystem_watchers.lua", },
+  { helptag = "nvim-tree-config-actions",             title = "Class: Config.Actions",            path = "./lua/nvim_tree/_meta/config/actions.lua", },
+  { helptag = "nvim-tree-config-trash",               title = "Class: Config.Trash",              path = "./lua/nvim_tree/_meta/config/trash.lua", },
+  { helptag = "nvim-tree-config-tab",                 title = "Class: Config.Tab",                path = "./lua/nvim_tree/_meta/config/tab.lua", },
+  { helptag = "nvim-tree-config-notify",              title = "Class: Config.Notify",             path = "./lua/nvim_tree/_meta/config/notify.lua", },
+  { helptag = "nvim-tree-config-bookmarks",           title = "Class: Config.Bookmarks",          path = "./lua/nvim_tree/_meta/config/bookmarks.lua", },
+  { helptag = "nvim-tree-config-help",                title = "Class: Config.Help",               path = "./lua/nvim_tree/_meta/config/help.lua", },
+  { helptag = "nvim-tree-config-ui",                  title = "Class: Config.UI",                 path = "./lua/nvim_tree/_meta/config/ui.lua",                  name = "UI", },
+  { helptag = "nvim-tree-config-experimental",        title = "Class: Config.Experimental",       path = "./lua/nvim_tree/_meta/config/experimental.lua", },
+  { helptag = "nvim-tree-config-log",                 title = "Class: Config.Log",                path = "./lua/nvim_tree/_meta/config/log.lua", },
 }
 
 -- hydrate file names
diff --git a/scripts/lintdoc.sh b/scripts/lintdoc.sh
index 8f39bb7fe28..55bd77d4388 100755
--- a/scripts/lintdoc.sh
+++ b/scripts/lintdoc.sh
@@ -14,29 +14,44 @@
 
 set -e
 
-if [ ! -d "${NVIM_SRC}" ]; then
+# unset to ensure no collisions with system installs etc.
+unset VIMRUNTIME
+
+# Use a directory outside of nvim_tree source. Adding lua files inside will (rightly) upset luals.
+DIR_NVT="${PWD}"
+DIR_WORK="/tmp/nvim-tree-lintdoc"
+DIR_NVIM_SRC_DEF="/tmp/src/neovim-stable"
+
+if [ ! -f "${DIR_NVT}/scripts/lintdoc.sh" ]; then
+	echo "Must be run from nvim-tree root"
+	exit 1
+fi
+
+if [ -z "${DIR_NVIM_SRC}" ] && [ -d "${DIR_NVIM_SRC_DEF}" ]; then
+	export DIR_NVIM_SRC="${DIR_NVIM_SRC_DEF}"
+	echo "Assumed DIR_NVIM_SRC=${DIR_NVIM_SRC}"
+fi
+
+if [ ! -d "${DIR_NVIM_SRC}" ]; then
 	cat << EOM
 
-\$NVIM_SRC not set
+\$DIR_NVIM_SRC=${DIR_NVIM_SRC} not set or missing.
 
-Compiled Nvim source is required to run src/gen/gen_vimdoc.lua
+Nvim source is required to run ${0}
 
 Please:
-  mkdir -p src
-  curl -L 'https://github.com/neovim/neovim/archive/refs/tags/stable.tar.gz' | tar zx --directory src
-  export NVIM_SRC=src/neovim-stable
+  mkdir -p ${DIR_NVIM_SRC_DEF}
+  curl -L 'https://github.com/neovim/neovim/archive/refs/tags/stable.tar.gz' | tar zx --directory $(dirname "${DIR_NVIM_SRC_DEF}")
+  export DIR_NVIM_SRC=/tmp/src/neovim-stable
 EOM
 exit 1
 fi
 
-# unset to ensure no collisions with system installs etc.
-unset VIMRUNTIME
-
 # runtime/doc in the Nvim source is practically hardcoded, copy our help in
-cp -v "doc/nvim-tree-lua.txt" "${NVIM_SRC}/runtime/doc"
+cp -v "${DIR_NVT}/doc/nvim-tree-lua.txt" "${DIR_NVIM_SRC}/runtime/doc"
 
 # run from within Nvim source
-cd "${NVIM_SRC}"
+cd "${DIR_NVIM_SRC}"
 
 # make nvim and execute the lint
-make lintdoc
+make 

From 9627fb88eedb6c02e06ab5af4778ebb04f5a7404 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sat, 17 Jan 2026 13:57:11 +1100
Subject: [PATCH 080/170] docs(#2934): harden gen and lint scripts, moving
 things out of nvim-tree source to prevent luals upset

---
 .github/workflows/ci.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index ca0cb4074f1..86b0b49d32e 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -79,8 +79,8 @@ jobs:
 
       - name: build Nvim from source
         run: |
-          mkdir -p src
-          curl -L "https://github.com/neovim/neovim/archive/refs/tags/${{ matrix.nvim_version }}.tar.gz" | tar zx --directory src
+          mkdir -p "${DIR_NVIM_SRC}"
+          curl -L "https://github.com/neovim/neovim/archive/refs/tags/${{ matrix.nvim_version }}.tar.gz" | tar zx --directory "${DIR_NVIM_SRC}/.."
           cd "${DIR_NVIM_SRC}"
           make
 

From de9c62cd71f7dcd1c2b17776c73bca7b41a22afe Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sat, 17 Jan 2026 18:00:29 +1100
Subject: [PATCH 081/170] docs(#2934): fix lintdoc make target

---
 scripts/lintdoc.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/lintdoc.sh b/scripts/lintdoc.sh
index 55bd77d4388..6b5b0a88d77 100755
--- a/scripts/lintdoc.sh
+++ b/scripts/lintdoc.sh
@@ -54,4 +54,4 @@ cp -v "${DIR_NVT}/doc/nvim-tree-lua.txt" "${DIR_NVIM_SRC}/runtime/doc"
 cd "${DIR_NVIM_SRC}"
 
 # make nvim and execute the lint
-make 
+make lintdoc

From 2061b9351bc6fe4fdf5359fad215addd8a32466d Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sat, 17 Jan 2026 15:52:16 +1100
Subject: [PATCH 082/170] docs(#3088): extract api/tree.lua

---
 doc/nvim-tree-lua.txt         |  81 ++++++++++++++++++++++++
 lua/nvim-tree.lua             |   3 +
 lua/nvim-tree/api.lua         |   5 ++
 lua/nvim-tree/api/init.lua    |   3 +
 lua/nvim-tree/api/tree.lua    | 113 ++++++++++++++++++++++++++++++++++
 scripts/gen_vimdoc_config.lua |  41 ++++++++----
 6 files changed, 234 insertions(+), 12 deletions(-)
 create mode 100644 lua/nvim-tree/api/init.lua
 create mode 100644 lua/nvim-tree/api/tree.lua

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index b055e7dabac..5595b9a13b5 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -3068,4 +3068,85 @@ Class: Config.Log                                       *nvim-tree-config-log*
 
 
 
+==============================================================================
+Lua module: nvim_tree.api.tree                            *nvim-tree-api-tree*
+
+focus()                                           *nvim_tree.api.tree.focus()*
+    TODO #3088 descriptions are needed to properly format the functions
+
+nvim_tree.api.tree.change_root()            *nvim_tree.api.tree.change_root()*
+
+                                    *nvim_tree.api.tree.change_root_to_node()*
+nvim_tree.api.tree.change_root_to_node()
+
+                                  *nvim_tree.api.tree.change_root_to_parent()*
+nvim_tree.api.tree.change_root_to_parent()
+
+nvim_tree.api.tree.close()                        *nvim_tree.api.tree.close()*
+
+                                      *nvim_tree.api.tree.close_in_all_tabs()*
+nvim_tree.api.tree.close_in_all_tabs()
+
+                                      *nvim_tree.api.tree.close_in_this_tab()*
+nvim_tree.api.tree.close_in_this_tab()
+
+nvim_tree.api.tree.collapse_all()          *nvim_tree.api.tree.collapse_all()*
+
+nvim_tree.api.tree.expand_all()              *nvim_tree.api.tree.expand_all()*
+
+nvim_tree.api.tree.find_file()                *nvim_tree.api.tree.find_file()*
+
+                                  *nvim_tree.api.tree.get_node_under_cursor()*
+nvim_tree.api.tree.get_node_under_cursor()
+
+nvim_tree.api.tree.get_nodes()                *nvim_tree.api.tree.get_nodes()*
+
+nvim_tree.api.tree.is_tree_buf()            *nvim_tree.api.tree.is_tree_buf()*
+
+nvim_tree.api.tree.is_visible()              *nvim_tree.api.tree.is_visible()*
+
+nvim_tree.api.tree.reload()                      *nvim_tree.api.tree.reload()*
+
+nvim_tree.api.tree.resize()                      *nvim_tree.api.tree.resize()*
+
+nvim_tree.api.tree.search_node()            *nvim_tree.api.tree.search_node()*
+
+nvim_tree.api.tree.toggle()                      *nvim_tree.api.tree.toggle()*
+
+                                   *nvim_tree.api.tree.toggle_custom_filter()*
+nvim_tree.api.tree.toggle_custom_filter()
+
+                                  *nvim_tree.api.tree.toggle_enable_filters()*
+nvim_tree.api.tree.toggle_enable_filters()
+
+                                *nvim_tree.api.tree.toggle_git_clean_filter()*
+nvim_tree.api.tree.toggle_git_clean_filter()
+
+                                *nvim_tree.api.tree.toggle_gitignore_filter()*
+nvim_tree.api.tree.toggle_gitignore_filter()
+
+nvim_tree.api.tree.toggle_help()            *nvim_tree.api.tree.toggle_help()*
+
+                                   *nvim_tree.api.tree.toggle_hidden_filter()*
+nvim_tree.api.tree.toggle_hidden_filter()
+
+                              *nvim_tree.api.tree.toggle_no_bookmark_filter()*
+nvim_tree.api.tree.toggle_no_bookmark_filter()
+
+                                *nvim_tree.api.tree.toggle_no_buffer_filter()*
+nvim_tree.api.tree.toggle_no_buffer_filter()
+
+nvim_tree.api.tree.winid()                        *nvim_tree.api.tree.winid()*
+
+open({opts})                                       *nvim_tree.api.tree.open()*
+
+    Parameters: ~
+      • {opts}  (`table?`) A table with the following fields:
+                • {path} (`string?`) path
+                • {current_window} (`boolean?`) default false
+                • {winid} (`number?`)
+                • {find_file} (`boolean?`) default false
+                • {update_root} (`boolean?`) default false
+
+
  vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:
diff --git a/lua/nvim-tree.lua b/lua/nvim-tree.lua
index 9d27cee3541..351b2993bd7 100644
--- a/lua/nvim-tree.lua
+++ b/lua/nvim-tree.lua
@@ -793,6 +793,9 @@ function M.setup(conf)
 
   vim.g.NvimTreeSetup = 1
   vim.api.nvim_exec_autocmds("User", { pattern = "NvimTreeSetup" })
+
+  -- TODO #3088 remove this bootstrap once api/init.lua replaces old api.lua
+  require("nvim-tree.api.init")
 end
 
 vim.g.NvimTreeRequired = 1
diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index e5a109142f1..789d6bdbf34 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -123,6 +123,9 @@ local function wrap_explorer_member(explorer_member, member_method)
   end)
 end
 
+function Api.hydrate_tree(tree)
+  Api.tree = tree
+
 ---@class ApiTreeOpenOpts
 ---@field path string|nil path
 ---@field current_window boolean|nil default false
@@ -220,6 +223,8 @@ Api.tree.is_visible = wrap(view.is_visible)
 
 Api.tree.winid = wrap(view.winid)
 
+end
+
 Api.fs.create = wrap_node_or_nil(actions.fs.create_file.fn)
 Api.fs.remove = wrap_node(actions.fs.remove_file.fn)
 Api.fs.trash = wrap_node(actions.fs.trash.fn)
diff --git a/lua/nvim-tree/api/init.lua b/lua/nvim-tree/api/init.lua
new file mode 100644
index 00000000000..206faf24f91
--- /dev/null
+++ b/lua/nvim-tree/api/init.lua
@@ -0,0 +1,3 @@
+return {
+  tree = require("nvim-tree.api.tree")
+}
diff --git a/lua/nvim-tree/api/tree.lua b/lua/nvim-tree/api/tree.lua
new file mode 100644
index 00000000000..432aeb8cdd0
--- /dev/null
+++ b/lua/nvim-tree/api/tree.lua
@@ -0,0 +1,113 @@
+---@meta
+local nvim_tree = { api = { tree = {} } }
+
+---@class nvim_tree.api.tree.open.Opts
+---@inlinedoc
+---@field path string|nil path
+---@field current_window boolean|nil default false
+---@field winid number|nil
+---@field find_file boolean|nil default false
+---@field update_root boolean|nil default false
+
+---@param opts? nvim_tree.api.tree.open.Opts
+function nvim_tree.api.tree.open(opts) end
+
+---TODO #3088 descriptions are needed to properly format the functions
+function nvim_tree.api.tree.focus() end
+
+---@class nvim_tree.api.tree.toggle.Opts
+---@inlinedoc
+---@field path string|nil
+---@field current_window boolean|nil default false
+---@field winid number|nil
+---@field find_file boolean|nil default false
+---@field update_root boolean|nil default false
+---@field focus boolean|nil default true
+
+function nvim_tree.api.tree.toggle(opts) end
+
+function nvim_tree.api.tree.close() end
+
+function nvim_tree.api.tree.close_in_this_tab() end
+
+function nvim_tree.api.tree.close_in_all_tabs() end
+
+function nvim_tree.api.tree.reload() end
+
+---@class nvim_tree.api.tree.resize.Opts
+---@inlinedoc
+---@field width string|function|number|table|nil
+---@field absolute number|nil
+---@field relative number|nil
+
+function nvim_tree.api.tree.resize(opts) end
+
+function nvim_tree.api.tree.change_root() end
+
+function nvim_tree.api.tree.change_root_to_node() end
+
+function nvim_tree.api.tree.change_root_to_parent() end
+
+function nvim_tree.api.tree.get_node_under_cursor() end
+
+function nvim_tree.api.tree.get_nodes() end
+
+---@class nvim_tree.api.tree.find_file.Opts
+---@inlinedoc
+---@field buf string|number|nil
+---@field open boolean|nil default false
+---@field current_window boolean|nil default false
+---@field winid number|nil
+---@field update_root boolean|nil default false
+---@field focus boolean|nil default false
+
+function nvim_tree.api.tree.find_file(opts) end
+
+function nvim_tree.api.tree.search_node() end
+
+---@class nvim_tree.api.tree.collapse.Opts
+---@inlinedoc
+---@field keep_buffers boolean|nil default false
+
+function nvim_tree.api.tree.collapse_all(opts) end
+
+---@class nvim_tree.api.tree.expand.Opts
+---@inlinedoc
+---@field expand_until (fun(expansion_count: integer, node: Node): boolean)|nil
+
+function nvim_tree.api.tree.expand_all(opts) end
+
+function nvim_tree.api.tree.toggle_enable_filters() end
+
+function nvim_tree.api.tree.toggle_gitignore_filter() end
+
+function nvim_tree.api.tree.toggle_git_clean_filter() end
+
+function nvim_tree.api.tree.toggle_no_buffer_filter() end
+
+function nvim_tree.api.tree.toggle_custom_filter() end
+
+function nvim_tree.api.tree.toggle_hidden_filter() end
+
+function nvim_tree.api.tree.toggle_no_bookmark_filter() end
+
+function nvim_tree.api.tree.toggle_help() end
+
+function nvim_tree.api.tree.is_tree_buf() end
+
+---@class nvim_tree.api.tree.is_visible.Opts
+---@inlinedoc
+---@field tabpage number|nil
+---@field any_tabpage boolean|nil default false
+
+function nvim_tree.api.tree.is_visible(opts) end
+
+---@class nvim_tree.api.tree.winid.Opts
+---@inlinedoc
+---@field tabpage number|nil default nil
+
+function nvim_tree.api.tree.winid(opts) end
+
+require("nvim-tree.api").hydrate_tree(nvim_tree.api.tree)
+
+return nvim_tree.api.tree
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index e8dda6f50e1..d568f4ab598 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -30,6 +30,8 @@ local modules = {
   { helptag = "nvim-tree-config-ui",                  title = "Class: Config.UI",                 path = "./lua/nvim_tree/_meta/config/ui.lua",                  name = "UI", },
   { helptag = "nvim-tree-config-experimental",        title = "Class: Config.Experimental",       path = "./lua/nvim_tree/_meta/config/experimental.lua", },
   { helptag = "nvim-tree-config-log",                 title = "Class: Config.Log",                path = "./lua/nvim_tree/_meta/config/log.lua", },
+
+  { helptag = "nvim-tree-api-tree",                   title = "Lua module: nvim_tree.api.tree",   path = "./lua/nvim_tree/api/tree.lua", },
 }
 
 -- hydrate file names
@@ -59,26 +61,41 @@ local config = {
     files = vim.tbl_map(function(m) return m.path end, modules),
 
     section_fmt = function(name)
+      print(string.format("section_fmt name=%s", name))
       return modules_by_name[name] and modules_by_name[name].title or error(string.format("unknown module %s passed to section_fmt", name))
     end,
 
     helptag_fmt = function(name)
+      print(string.format("helptag_fmt name=%s", name))
       return modules_by_name[name] and modules_by_name[name].helptag or error(string.format("unknown module %s passed to helptag_fmt", name))
     end,
 
-    -- class/function's help tag
-    fn_helptag_fmt = function(fun)
-      -- Modified copy of fn_helptag_fmt_common
-      -- Uses fully qualified class name in the tag for methods.
-      -- The module is used everywhere else, however not available for classes.
-      local fn_sfx = fun.table and "" or "()"
-      if fun.classvar then
-        return string.format("%s:%s%s", fun.class or fun.classvar, fun.name, fn_sfx)
-      end
-      if fun.module then
-        return string.format("%s.%s%s", fun.module, fun.name, fn_sfx)
+    -- optional, no default xform
+    fn_xform = function(fun)
+      print(string.format("fn_xform fun=%s", vim.inspect(fun)))
+
+      if (fun.module) then
+        -- generator doesn't strip meta
+        -- also cascades into fn_helptag_fmt
+        local module = fun.module:gsub("._meta", "", 1)
+
+        if module ~= fun.module then
+          error("unexpected _meta in module")
+          print(string.format("fn_xform module: %s -> %s", fun.module, module))
+        end
+
+        -- remove the API prefix from the left aligned function name
+        -- this will cascade into fn_helptag_fmt, which will apply the module prefix anyway
+        local name, replaced = fun.name:gsub("^" .. module .. "%.", "", 1)
+        if (replaced ~= 1) then
+          error(string.format("function name does not start with module: %s", vim.inspect(fun)))
+        end
+
+        print(string.format("fn_xform name: %s -> %s", fun.name, name))
+
+        fun.module = module
+        fun.name = name
       end
-      return fun.name .. fn_sfx
     end,
   }
 }

From c6890083aec6f4ac1dfb6808879d99775f70d3f3 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sat, 17 Jan 2026 17:50:46 +1100
Subject: [PATCH 083/170] docs(#3088): extract api/tree.lua

---
 .luacheckrc                |   1 +
 doc/nvim-tree-lua.txt      | 205 ++++++++++++++++++++++------
 lua/nvim-tree/api/tree.lua | 264 +++++++++++++++++++++++++++++++------
 scripts/lintdoc.sh         |   4 +
 scripts/luals-check.sh     |   2 +
 5 files changed, 391 insertions(+), 85 deletions(-)

diff --git a/.luacheckrc b/.luacheckrc
index 267d0ce54ce..9155f6f4386 100644
--- a/.luacheckrc
+++ b/.luacheckrc
@@ -5,6 +5,7 @@ M.self = false
 
 M.ignore = {
   "631",  -- max_line_length
+  "212", -- TODO #3088 make luacheck understand @meta
 }
 
 -- Global objects defined by the C code
diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 5595b9a13b5..637e5ca6971 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -3071,82 +3071,201 @@ Class: Config.Log                                       *nvim-tree-config-log*
 ==============================================================================
 Lua module: nvim_tree.api.tree                            *nvim-tree-api-tree*
 
-focus()                                           *nvim_tree.api.tree.focus()*
-    TODO #3088 descriptions are needed to properly format the functions
+change_root({path})                         *nvim_tree.api.tree.change_root()*
+    Change the tree's root to a path.
+
+    Parameters: ~
+      • {path}  (`string?`) absolute or relative path.
 
-nvim_tree.api.tree.change_root()            *nvim_tree.api.tree.change_root()*
+change_root_to_node({node})         *nvim_tree.api.tree.change_root_to_node()*
+    Change the tree's root to a folder node or the parent of a file node.
 
-                                    *nvim_tree.api.tree.change_root_to_node()*
-nvim_tree.api.tree.change_root_to_node()
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node`) directory or file
 
                                   *nvim_tree.api.tree.change_root_to_parent()*
-nvim_tree.api.tree.change_root_to_parent()
+change_root_to_parent({node})
+    Change the tree's root to the parent of a node.
 
-nvim_tree.api.tree.close()                        *nvim_tree.api.tree.close()*
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node`) directory or file
 
-                                      *nvim_tree.api.tree.close_in_all_tabs()*
-nvim_tree.api.tree.close_in_all_tabs()
+close()                                           *nvim_tree.api.tree.close()*
+    Close the tree, affecting all tabs as per |nvim_tree.Config.Tab.Sync|
+    {close}
 
-                                      *nvim_tree.api.tree.close_in_this_tab()*
-nvim_tree.api.tree.close_in_this_tab()
+close_in_all_tabs()                   *nvim_tree.api.tree.close_in_all_tabs()*
+    Close the tree in all tabs.
 
-nvim_tree.api.tree.collapse_all()          *nvim_tree.api.tree.collapse_all()*
+close_in_this_tab()                   *nvim_tree.api.tree.close_in_this_tab()*
+    Close the tree in this tab only.
 
-nvim_tree.api.tree.expand_all()              *nvim_tree.api.tree.expand_all()*
+collapse_all({opts})                       *nvim_tree.api.tree.collapse_all()*
+    Collapse the tree.
 
-nvim_tree.api.tree.find_file()                *nvim_tree.api.tree.find_file()*
+    Parameters: ~
+      • {opts}  (`table?`) optional
+                • {keep_buffers}? (`boolean`, default: false) Do not collapse
+                  nodes with open buffers.
 
-                                  *nvim_tree.api.tree.get_node_under_cursor()*
-nvim_tree.api.tree.get_node_under_cursor()
+expand_all({node}, {opts})                   *nvim_tree.api.tree.expand_all()*
+    Recursively expand all nodes under the tree root or specified folder.
 
-nvim_tree.api.tree.get_nodes()                *nvim_tree.api.tree.get_nodes()*
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory
+      • {opts}  (`table?`) optional
+                • {expand_until}?
+                  (`fun(expansion_count: integer, node: Node): boolean`)
+                  Return `true` if `node` should be expanded.
+                  `expansion_count` is the total number of folders expanded.
+
+find_file({opts})                             *nvim_tree.api.tree.find_file()*
+    Find and focus a file or folder in the tree. Finds current buffer unless
+    otherwise specified.
 
-nvim_tree.api.tree.is_tree_buf()            *nvim_tree.api.tree.is_tree_buf()*
+    Parameters: ~
+      • {opts}  (`table?`) optional
+                • {buf}? (`string|number`) Absolute/relative path OR |bufnr()|
+                  to find.
+                • {open}? (`boolean`, default: false) Open the tree if
+                  necessary.
+                • {current_window}? (`boolean`, default: false) Requires
+                  {open}: open in the current window.
+                • {winid}? (`number`) Open the tree in the specified |winid|,
+                  overrides {current_window}
+                • {update_root}? (`boolean`, default: false) Update root after
+                  find, see |nvim_tree.Config.UpdateFocusedFile| {update_root}
+                • {focus}? (`boolean`, default: false) Focus the tree window.
+
+focus()                                           *nvim_tree.api.tree.focus()*
+    Focus the tree, opening it if necessary. Retained for compatibility, use
+    |nvim_tree.api.tree.open()| with no arguments instead.
 
-nvim_tree.api.tree.is_visible()              *nvim_tree.api.tree.is_visible()*
+get_node_under_cursor()           *nvim_tree.api.tree.get_node_under_cursor()*
+    Retrieve the currently focused node.
 
-nvim_tree.api.tree.reload()                      *nvim_tree.api.tree.reload()*
+    Return: ~
+        (`nvim_tree.api.Node?`) nil if tree is not visible.
 
-nvim_tree.api.tree.resize()                      *nvim_tree.api.tree.resize()*
+get_nodes()                                   *nvim_tree.api.tree.get_nodes()*
+    Retrieve a hierarchical list of all the nodes.
 
-nvim_tree.api.tree.search_node()            *nvim_tree.api.tree.search_node()*
+    Return: ~
+        (`nvim_tree.api.Node[]`)
 
-nvim_tree.api.tree.toggle()                      *nvim_tree.api.tree.toggle()*
+is_tree_buf({bufnr})                        *nvim_tree.api.tree.is_tree_buf()*
+    Checks if a buffer is an nvim-tree.
 
-                                   *nvim_tree.api.tree.toggle_custom_filter()*
-nvim_tree.api.tree.toggle_custom_filter()
+    Parameters: ~
+      • {bufnr}  (`number?`) 0 or nil for current buffer.
 
-                                  *nvim_tree.api.tree.toggle_enable_filters()*
-nvim_tree.api.tree.toggle_enable_filters()
+    Return: ~
+        (`boolean`)
+
+is_visible({opts})                           *nvim_tree.api.tree.is_visible()*
+    Checks if nvim-tree is visible on the current, specified or any tab.
+
+    Parameters: ~
+      • {opts}  (`table?`) optional
+                • {tabpage}? (`integer`) |tab-ID| 0 or nil for current.
+                • {any_tabpage}? (`boolean`, default: false) Visible on any
+                  tab.
+
+    Return: ~
+        (`boolean`)
+
+open({opts})                                       *nvim_tree.api.tree.open()*
+    Open the tree, focusing it if already open.
+
+    Parameters: ~
+      • {opts}  (`table?`) optional
+                • {path}? (`string`) Root directory for the tree
+                • {current_window}? (`boolean`, default: false) Open the tree
+                  in the current window
+                • {winid}? (`number`) Open the tree in the specified |winid|,
+                  overrides {current_window}
+                • {find_file}? (`boolean`, default: false) Find the current
+                  buffer.
+                • {update_root}? (`boolean`, default: false) Update root
+                  following {find_file}, see
+                  |nvim_tree.Config.UpdateFocusedFile| {update_root}
+
+reload()                                         *nvim_tree.api.tree.reload()*
+    Refresh the tree. Does nothing if closed.
+
+resize({opts})                                   *nvim_tree.api.tree.resize()*
+    Resize the tree, persisting the new size. Resets to
+    |nvim_tree.Config.View| {width} when no {opts} provided.
+
+    Only one option is supported, priority order: {width}, {absolute},
+    {relative}.
+
+    {absolute} and {relative} do nothing when |nvim_tree.Config.View| {width}
+    is a function.
+
+    Parameters: ~
+      • {opts}  (`table?`) optional
+                • {width}
+                  (`nvim_tree.Config.View.WidthSpec|nvim_tree.Config.View.Width`)
+                  New |nvim_tree.Config.View| {width} value.
+                • {absolute} (`number`) Set the width.
+                • {relative} (`number`) Increase or decrease the width.
+
+search_node()                               *nvim_tree.api.tree.search_node()*
+    Open the search dialogue.
+
+toggle({opts})                                   *nvim_tree.api.tree.toggle()*
+    Open or close the tree.
+
+    Parameters: ~
+      • {opts}  (`table?`) optional
+                • {path}? (`string`) Root directory for the tree
+                • {current_window}? (`boolean`, default: false) Open the tree
+                  in the current window
+                • {winid}? (`number`) Open the tree in the specified |winid|,
+                  overrides {current_window}
+                • {find_file}? (`boolean`, default: false) Find the current
+                  buffer.
+                • {focus}? (`boolean`, default: true) Focus the tree when
+                  opening.
+
+toggle_custom_filter()             *nvim_tree.api.tree.toggle_custom_filter()*
+    Toggle |nvim_tree.Config.Filters| {custom} filter.
+
+toggle_enable_filters()           *nvim_tree.api.tree.toggle_enable_filters()*
+    Toggle |nvim_tree.Config.Filters| {enable} all filters.
 
                                 *nvim_tree.api.tree.toggle_git_clean_filter()*
-nvim_tree.api.tree.toggle_git_clean_filter()
+toggle_git_clean_filter()
+    Toggle |nvim_tree.Config.Filters| {git_clean} filter.
 
                                 *nvim_tree.api.tree.toggle_gitignore_filter()*
-nvim_tree.api.tree.toggle_gitignore_filter()
+toggle_gitignore_filter()
+    Toggle |nvim_tree.Config.Filters| {git_ignored} filter.
 
-nvim_tree.api.tree.toggle_help()            *nvim_tree.api.tree.toggle_help()*
+toggle_help()                               *nvim_tree.api.tree.toggle_help()*
+    Toggle help view.
 
-                                   *nvim_tree.api.tree.toggle_hidden_filter()*
-nvim_tree.api.tree.toggle_hidden_filter()
+toggle_hidden_filter()             *nvim_tree.api.tree.toggle_hidden_filter()*
+    Toggle |nvim_tree.Config.Filters| {dotfiles} filter.
 
                               *nvim_tree.api.tree.toggle_no_bookmark_filter()*
-nvim_tree.api.tree.toggle_no_bookmark_filter()
+toggle_no_bookmark_filter()
+    Toggle |nvim_tree.Config.Filters| {no_bookmark} filter.
 
                                 *nvim_tree.api.tree.toggle_no_buffer_filter()*
-nvim_tree.api.tree.toggle_no_buffer_filter()
-
-nvim_tree.api.tree.winid()                        *nvim_tree.api.tree.winid()*
+toggle_no_buffer_filter()
+    Toggle |nvim_tree.Config.Filters| {no_buffer} filter.
 
-open({opts})                                       *nvim_tree.api.tree.open()*
+winid({opts})                                     *nvim_tree.api.tree.winid()*
+    Retrieve the winid of the open tree.
 
     Parameters: ~
-      • {opts}  (`table?`) A table with the following fields:
-                • {path} (`string?`) path
-                • {current_window} (`boolean?`) default false
-                • {winid} (`number?`)
-                • {find_file} (`boolean?`) default false
-                • {update_root} (`boolean?`) default false
+      • {opts}  (`table?`) optional
+                • {tabpage}? (`integer`) |tab-ID| 0 or nil for current.
+
+    Return: ~
+        (`integer?`) |winid|, nil if tree is not visible.
 
 
  vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:
diff --git a/lua/nvim-tree/api/tree.lua b/lua/nvim-tree/api/tree.lua
index 432aeb8cdd0..c0d8dad2095 100644
--- a/lua/nvim-tree/api/tree.lua
+++ b/lua/nvim-tree/api/tree.lua
@@ -1,113 +1,293 @@
 ---@meta
 local nvim_tree = { api = { tree = {} } }
 
+
+
 ---@class nvim_tree.api.tree.open.Opts
 ---@inlinedoc
----@field path string|nil path
----@field current_window boolean|nil default false
----@field winid number|nil
----@field find_file boolean|nil default false
----@field update_root boolean|nil default false
-
----@param opts? nvim_tree.api.tree.open.Opts
+---
+---Root directory for the tree
+---@field path? string
+---
+---Open the tree in the current window
+---(default: false)
+---@field current_window? boolean
+---
+---Open the tree in the specified [winid], overrides {current_window}
+---@field winid? number
+---
+---Find the current buffer.
+---(default: false)
+---@field find_file? boolean
+---
+---Update root following {find_file}, see [nvim_tree.Config.UpdateFocusedFile] {update_root}
+---(default: false)
+---@field update_root? boolean
+
+---Open the tree, focusing it if already open.
+---
+---@param opts? nvim_tree.api.tree.open.Opts optional
 function nvim_tree.api.tree.open(opts) end
 
----TODO #3088 descriptions are needed to properly format the functions
-function nvim_tree.api.tree.focus() end
+
 
 ---@class nvim_tree.api.tree.toggle.Opts
 ---@inlinedoc
----@field path string|nil
----@field current_window boolean|nil default false
----@field winid number|nil
----@field find_file boolean|nil default false
----@field update_root boolean|nil default false
----@field focus boolean|nil default true
-
+---
+---Root directory for the tree
+---@field path? string
+---
+---Open the tree in the current window
+---(default: false)
+---@field current_window? boolean
+---
+---Open the tree in the specified [winid], overrides {current_window}
+---@field winid? number
+---
+---Find the current buffer.
+---(default: false)
+---@field find_file? boolean
+---
+---Focus the tree when opening.
+---(default: true)
+---@field focus? boolean
+
+---Open or close the tree.
+---
+---@param opts? nvim_tree.api.tree.toggle.Opts optional
 function nvim_tree.api.tree.toggle(opts) end
 
+
+
+---Close the tree, affecting all tabs as per [nvim_tree.Config.Tab.Sync] {close}
+---
 function nvim_tree.api.tree.close() end
 
+
+---Close the tree in this tab only.
+---
 function nvim_tree.api.tree.close_in_this_tab() end
 
+
+---Close the tree in all tabs.
+---
 function nvim_tree.api.tree.close_in_all_tabs() end
 
+
+
+---Focus the tree, opening it if necessary. Retained for compatibility, use [nvim_tree.api.tree.open()] with no arguments instead.
+---
+function nvim_tree.api.tree.focus() end
+
+
+---Refresh the tree. Does nothing if closed.
+---
 function nvim_tree.api.tree.reload() end
 
+
+
 ---@class nvim_tree.api.tree.resize.Opts
 ---@inlinedoc
----@field width string|function|number|table|nil
----@field absolute number|nil
----@field relative number|nil
-
+---
+---New [nvim_tree.Config.View] {width} value.
+---@field width nvim_tree.Config.View.WidthSpec|nvim_tree.Config.View.Width
+---
+---Set the width.
+---@field absolute number
+---
+---Increase or decrease the width.
+---@field relative number
+
+---Resize the tree, persisting the new size. Resets to [nvim_tree.Config.View] {width} when no {opts} provided.
+---
+---Only one option is supported, priority order: {width}, {absolute}, {relative}.
+---
+---{absolute} and {relative} do nothing when [nvim_tree.Config.View] {width} is a function.
+---@param opts? nvim_tree.api.tree.resize.Opts optional
 function nvim_tree.api.tree.resize(opts) end
 
-function nvim_tree.api.tree.change_root() end
 
-function nvim_tree.api.tree.change_root_to_node() end
 
-function nvim_tree.api.tree.change_root_to_parent() end
+---Change the tree's root to a path.
+---
+---@param path? string absolute or relative path.
+function nvim_tree.api.tree.change_root(path) end
+
+
+
+---Change the tree's root to a folder node or the parent of a file node.
+---
+---@param node nvim_tree.api.Node directory or file
+function nvim_tree.api.tree.change_root_to_node(node) end
+
 
+---Change the tree's root to the parent of a node.
+---
+---@param node nvim_tree.api.Node directory or file
+function nvim_tree.api.tree.change_root_to_parent(node) end
+
+
+---Retrieve the currently focused node.
+---
+---@return nvim_tree.api.Node? nil if tree is not visible.
 function nvim_tree.api.tree.get_node_under_cursor() end
 
+
+---Retrieve a hierarchical list of all the nodes.
+---
+---@return nvim_tree.api.Node[]
 function nvim_tree.api.tree.get_nodes() end
 
+
+
 ---@class nvim_tree.api.tree.find_file.Opts
 ---@inlinedoc
----@field buf string|number|nil
----@field open boolean|nil default false
----@field current_window boolean|nil default false
----@field winid number|nil
----@field update_root boolean|nil default false
----@field focus boolean|nil default false
-
+---
+---Absolute/relative path OR [bufnr()] to find.
+---@field buf? string|number
+---
+---Open the tree if necessary.
+---(default: false)
+---@field open? boolean
+---
+---Requires {open}: open in the current window.
+---(default: false)
+---@field current_window? boolean
+---
+---Open the tree in the specified [winid], overrides {current_window}
+---@field winid? number
+---
+---Update root after find, see [nvim_tree.Config.UpdateFocusedFile] {update_root}
+---(default: false)
+---@field update_root? boolean
+---
+---Focus the tree window.
+---(default: false)
+---@field focus? boolean
+
+---Find and focus a file or folder in the tree. Finds current buffer unless otherwise specified.
+---
+---@param opts? nvim_tree.api.tree.find_file.Opts optional
 function nvim_tree.api.tree.find_file(opts) end
 
+
+
+---Open the search dialogue.
+---
 function nvim_tree.api.tree.search_node() end
 
+
+
 ---@class nvim_tree.api.tree.collapse.Opts
 ---@inlinedoc
----@field keep_buffers boolean|nil default false
-
+---
+---Do not collapse nodes with open buffers.
+---(default: false)
+---@field keep_buffers? boolean
+
+---Collapse the tree.
+---
+---@param opts? nvim_tree.api.tree.collapse.Opts optional
 function nvim_tree.api.tree.collapse_all(opts) end
 
+
+
+--- TODO #3088 move expand/collapse into api.node
+
 ---@class nvim_tree.api.tree.expand.Opts
 ---@inlinedoc
----@field expand_until (fun(expansion_count: integer, node: Node): boolean)|nil
+---
+---Return `true` if `node` should be expanded. `expansion_count` is the total number of folders expanded.
+---@field expand_until? fun(expansion_count: integer, node: Node): boolean
+
+---Recursively expand all nodes under the tree root or specified folder.
+---@param node? nvim_tree.api.Node directory
+---@param opts? nvim_tree.api.tree.expand.Opts optional
+function nvim_tree.api.tree.expand_all(node, opts) end
 
-function nvim_tree.api.tree.expand_all(opts) end
 
+
+---Toggle [nvim_tree.Config.Filters] {enable} all filters.
 function nvim_tree.api.tree.toggle_enable_filters() end
 
+
+
+---Toggle [nvim_tree.Config.Filters] {git_ignored} filter.
 function nvim_tree.api.tree.toggle_gitignore_filter() end
 
+
+
+---Toggle [nvim_tree.Config.Filters] {dotfiles} filter.
+function nvim_tree.api.tree.toggle_hidden_filter() end
+
+
+
+---Toggle [nvim_tree.Config.Filters] {git_clean} filter.
 function nvim_tree.api.tree.toggle_git_clean_filter() end
 
+
+
+---Toggle [nvim_tree.Config.Filters] {no_buffer} filter.
 function nvim_tree.api.tree.toggle_no_buffer_filter() end
 
-function nvim_tree.api.tree.toggle_custom_filter() end
 
-function nvim_tree.api.tree.toggle_hidden_filter() end
 
+---Toggle [nvim_tree.Config.Filters] {no_bookmark} filter.
 function nvim_tree.api.tree.toggle_no_bookmark_filter() end
 
+
+
+---Toggle [nvim_tree.Config.Filters] {custom} filter.
+function nvim_tree.api.tree.toggle_custom_filter() end
+
+
+
+
+---Toggle help view.
 function nvim_tree.api.tree.toggle_help() end
 
-function nvim_tree.api.tree.is_tree_buf() end
+
+
+---Checks if a buffer is an nvim-tree.
+---
+---@param bufnr? number 0 or nil for current buffer.
+---@return boolean
+function nvim_tree.api.tree.is_tree_buf(bufnr) end
+
+
 
 ---@class nvim_tree.api.tree.is_visible.Opts
 ---@inlinedoc
----@field tabpage number|nil
----@field any_tabpage boolean|nil default false
-
+---
+--- [tab-ID] 0 or nil for current.
+---@field tabpage? integer
+---
+---Visible on any tab.
+---(default: false)
+---@field any_tabpage? boolean
+
+---Checks if nvim-tree is visible on the current, specified or any tab.
+---
+---@param opts? nvim_tree.api.tree.is_visible.Opts optional
+---@return boolean
 function nvim_tree.api.tree.is_visible(opts) end
 
+
+
 ---@class nvim_tree.api.tree.winid.Opts
 ---@inlinedoc
----@field tabpage number|nil default nil
-
+---
+---[tab-ID] 0 or nil for current.
+---@field tabpage? integer
+
+---Retrieve the winid of the open tree.
+---
+---@param opts? nvim_tree.api.tree.winid.Opts optional
+---@return integer? [winid], nil if tree is not visible.
 function nvim_tree.api.tree.winid(opts) end
 
+
+
 require("nvim-tree.api").hydrate_tree(nvim_tree.api.tree)
 
 return nvim_tree.api.tree
diff --git a/scripts/lintdoc.sh b/scripts/lintdoc.sh
index 6b5b0a88d77..061b2194ef0 100755
--- a/scripts/lintdoc.sh
+++ b/scripts/lintdoc.sh
@@ -1,5 +1,9 @@
 #!/usr/bin/env sh
 
+
+# TODO #3088 this is not picking up invalid links
+
+
 # Wrapper around Nvim help linter lintdoc.lua, run as part of Nvim's make lintdoc target.
 #
 # Requires Nvim to have been built.
diff --git a/scripts/luals-check.sh b/scripts/luals-check.sh
index 5c611b18b98..d145beb046a 100755
--- a/scripts/luals-check.sh
+++ b/scripts/luals-check.sh
@@ -21,6 +21,8 @@ mkdir "${DIR_OUT}"
 
 case "${1}" in
 	"codestyle-check")
+		echo "TODO #3088 skipping codestyle-check until api.lua refactor is complete"
+		exit 0
 		jq \
 			'.diagnostics.neededFileStatus[] = "None" | .diagnostics.neededFileStatus."codestyle-check" = "Any"' \
 			"${PWD}/.luarc.json" > "${FILE_LUARC}"

From 521e467517d06dea8698c210575f79cc63fd5f68 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sat, 17 Jan 2026 18:09:19 +1100
Subject: [PATCH 084/170] docs(#2934): move help diff check after lint

---
 Makefile           | 2 +-
 scripts/lintdoc.sh | 3 ---
 2 files changed, 1 insertion(+), 4 deletions(-)

diff --git a/Makefile b/Makefile
index 9b3b00cc71a..f8feb7fa15d 100644
--- a/Makefile
+++ b/Makefile
@@ -43,8 +43,8 @@ help-update:
 # --ignore-blank-lines is used as nightly has removed unnecessary blank lines that stable (0.11.5) currently inserts
 #
 help-check: help-update
-	git diff --ignore-blank-lines --exit-code doc/nvim-tree-lua.txt
 	@scripts/lintdoc.sh
+	git diff --ignore-blank-lines --exit-code doc/nvim-tree-lua.txt
 
 
 .PHONY: all lint style check luacheck style-check style-doc luals style-fix help-update help-check
diff --git a/scripts/lintdoc.sh b/scripts/lintdoc.sh
index 061b2194ef0..89a3b623467 100755
--- a/scripts/lintdoc.sh
+++ b/scripts/lintdoc.sh
@@ -1,9 +1,6 @@
 #!/usr/bin/env sh
 
 
-# TODO #3088 this is not picking up invalid links
-
-
 # Wrapper around Nvim help linter lintdoc.lua, run as part of Nvim's make lintdoc target.
 #
 # Requires Nvim to have been built.

From 10be08b11adef5f3e93c95d9eaea5f211f403602 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sun, 18 Jan 2026 09:07:02 +1100
Subject: [PATCH 085/170] docs(#3088): update api.tree references, remove old
 doc

---
 doc/nvim-tree-lua.txt                  | 267 +++----------------------
 lua/nvim-tree/_meta/config/actions.lua |   2 +-
 lua/nvim-tree/_meta/config/filters.lua |  14 +-
 scripts/help-update.sh                 |   3 +
 4 files changed, 43 insertions(+), 243 deletions(-)

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 637e5ca6971..02fcfc712f5 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -95,7 +95,7 @@ Open the tree:  `:NvimTreeOpen`
 
 Show the mappings:  `g?`
 
-``           CD                         |nvim-tree-api.tree.change_root_to_node()|
+``           CD                         |nvim_tree.api.tree.change_root_to_node()|
 ``           Open: In Place             |nvim-tree-api.node.open.replace_tree_buffer()|
 ``           Info                       |nvim-tree-api.node.show_info_popup()|
 ``           Rename: Omit Filename      |nvim-tree-api.fs.rename_sub()|
@@ -109,51 +109,51 @@ Show the mappings:  `g?`
 `>`               Next Sibling               |nvim-tree-api.node.navigate.sibling.next()|
 `<`               Previous Sibling           |nvim-tree-api.node.navigate.sibling.prev()|
 `.`               Run Command                |nvim-tree-api.node.run.cmd()|
-`-`               Up                         |nvim-tree-api.tree.change_root_to_parent()|
+`-`               Up                         |nvim_tree.api.tree.change_root_to_parent()|
 `a`               Create File Or Directory   |nvim-tree-api.fs.create()|
 `bd`              Delete Bookmarked          |nvim-tree-api.marks.bulk.delete()|
 `bt`              Trash Bookmarked           |nvim-tree-api.marks.bulk.trash()|
 `bmv`             Move Bookmarked            |nvim-tree-api.marks.bulk.move()|
-`B`               Toggle Filter: No Buffer   |nvim-tree-api.tree.toggle_no_buffer_filter()|
+`B`               Toggle Filter: No Buffer   |nvim_tree.api.tree.toggle_no_buffer_filter()|
 `c`               Copy                       |nvim-tree-api.fs.copy.node()|
-`C`               Toggle Filter: Git Clean   |nvim-tree-api.tree.toggle_git_clean_filter()|
+`C`               Toggle Filter: Git Clean   |nvim_tree.api.tree.toggle_git_clean_filter()|
 `[c`              Prev Git                   |nvim-tree-api.node.navigate.git.prev()|
 `]c`              Next Git                   |nvim-tree-api.node.navigate.git.next()|
 `d`               Delete                     |nvim-tree-api.fs.remove()|
 `D`               Trash                      |nvim-tree-api.fs.trash()|
-`E`               Expand All                 |nvim-tree-api.tree.expand_all()|
+`E`               Expand All                 |nvim_tree.api.tree.expand_all()|
 `e`               Rename: Basename           |nvim-tree-api.fs.rename_basename()|
 `]e`              Next Diagnostic            |nvim-tree-api.node.navigate.diagnostics.next()|
 `[e`              Prev Diagnostic            |nvim-tree-api.node.navigate.diagnostics.prev()|
 `F`               Live Filter: Clear         |nvim-tree-api.live_filter.clear()|
 `f`               Live Filter: Start         |nvim-tree-api.live_filter.start()|
-`g?`              Help                       |nvim-tree-api.tree.toggle_help()|
+`g?`              Help                       |nvim_tree.api.tree.toggle_help()|
 `gy`              Copy Absolute Path         |nvim-tree-api.fs.copy.absolute_path()|
 `ge`              Copy Basename              |nvim-tree-api.fs.copy.basename()|
-`H`               Toggle Filter: Dotfiles    |nvim-tree-api.tree.toggle_hidden_filter()|
-`I`               Toggle Filter: Git Ignore  |nvim-tree-api.tree.toggle_gitignore_filter()|
+`H`               Toggle Filter: Dotfiles    |nvim_tree.api.tree.toggle_hidden_filter()|
+`I`               Toggle Filter: Git Ignore  |nvim_tree.api.tree.toggle_gitignore_filter()|
 `J`               Last Sibling               |nvim-tree-api.node.navigate.sibling.last()|
 `K`               First Sibling              |nvim-tree-api.node.navigate.sibling.first()|
 `L`               Toggle Group Empty         |nvim-tree-api.node.open.toggle_group_empty()|
-`M`               Toggle Filter: No Bookmark |nvim-tree-api.tree.toggle_no_bookmark_filter()|
+`M`               Toggle Filter: No Bookmark |nvim_tree.api.tree.toggle_no_bookmark_filter()|
 `m`               Toggle Bookmark            |nvim-tree-api.marks.toggle()|
 `o`               Open                       |nvim-tree-api.node.open.edit()|
 `O`               Open: No Window Picker     |nvim-tree-api.node.open.no_window_picker()|
 `p`               Paste                      |nvim-tree-api.fs.paste()|
 `P`               Parent Directory           |nvim-tree-api.node.navigate.parent()|
-`q`               Close                      |nvim-tree-api.tree.close()|
+`q`               Close                      |nvim_tree.api.tree.close()|
 `r`               Rename                     |nvim-tree-api.fs.rename()|
-`R`               Refresh                    |nvim-tree-api.tree.reload()|
+`R`               Refresh                    |nvim_tree.api.tree.reload()|
 `s`               Run System                 |nvim-tree-api.node.run.system()|
-`S`               Search                     |nvim-tree-api.tree.search_node()|
+`S`               Search                     |nvim_tree.api.tree.search_node()|
 `u`               Rename: Full Path          |nvim-tree-api.fs.rename_full()|
-`U`               Toggle Filter: Hidden      |nvim-tree-api.tree.toggle_custom_filter()|
-`W`               Collapse All               |nvim-tree-api.tree.collapse_all()|
+`U`               Toggle Filter: Hidden      |nvim_tree.api.tree.toggle_custom_filter()|
+`W`               Collapse All               |nvim_tree.api.tree.collapse_all()|
 `x`               Cut                        |nvim-tree-api.fs.cut()|
 `y`               Copy Name                  |nvim-tree-api.fs.copy.filename()|
 `Y`               Copy Relative Path         |nvim-tree-api.fs.copy.relative_path()|
 `<2-LeftMouse>`   Open                       |nvim-tree-api.node.open.edit()|
-`<2-RightMouse>`  CD                         |nvim-tree-api.tree.change_root_to_node()|
+`<2-RightMouse>`  CD                         |nvim_tree.api.tree.change_root_to_node()|
 
 ==============================================================================
 Quickstart: Custom Mappings             *nvim-tree-quickstart-custom-mappings*
@@ -205,19 +205,19 @@ Commands                                                  *nvim-tree-commands*
 
 *:NvimTreeOpen*
 
-    Opens the tree. See |nvim-tree-api.tree.open()|
+    Opens the tree. See |nvim_tree.api.tree.open()|
 
     Calls: `api.tree.open({ path = "" })`
 
 *:NvimTreeClose*
 
-    Closes the tree. See |nvim-tree-api.tree.close()|
+    Closes the tree. See |nvim_tree.api.tree.close()|
 
     Calls: `api.tree.close()`
 
 *:NvimTreeToggle*
 
-    Open or close the tree. See |nvim-tree-api.tree.toggle()|
+    Open or close the tree. See |nvim_tree.api.tree.toggle()|
 
     Calls: `api.tree.toggle({ path = "", find_file = false, update_root = false, focus = true, })`
 
@@ -225,13 +225,13 @@ Commands                                                  *nvim-tree-commands*
 
     Open the tree if it is closed, and then focus on the tree.
 
-    See |nvim-tree-api.tree.open()|
+    See |nvim_tree.api.tree.open()|
 
     Calls: `api.tree.open()`
 
 *:NvimTreeRefresh*
 
-    Refresh the tree. See |nvim-tree-api.tree.reload()|
+    Refresh the tree. See |nvim_tree.api.tree.reload()|
 
     Calls: `api.tree.reload()`
 
@@ -245,7 +245,7 @@ Commands                                                  *nvim-tree-commands*
 
     Invoke with a bang `:NvimTreeFindFile!` to update the root.
 
-    See |nvim-tree-api.tree.find_file()|
+    See |nvim_tree.api.tree.find_file()|
 
     Calls: `api.tree.find_file({ update_root = , open = true, focus = true, })`
 
@@ -257,7 +257,7 @@ Commands                                                  *nvim-tree-commands*
 
     Invoke with a bang `:NvimTreeFindFileToggle!` to update the root.
 
-    See |nvim-tree-api.tree.toggle()|
+    See |nvim_tree.api.tree.toggle()|
 
     Calls: `api.tree.toggle({ path = "", update_root = , find_file = true, focus = true, })`
 
@@ -281,7 +281,7 @@ Commands                                                  *nvim-tree-commands*
 
     Collapses the nvim-tree recursively.
 
-    See |nvim-tree-api.tree.collapse_all()|
+    See |nvim_tree.api.tree.collapse_all()|
 
     Calls: `api.tree.collapse_all({ keep_buffers = false })`
 
@@ -290,7 +290,7 @@ Commands                                                  *nvim-tree-commands*
     Collapses the nvim-tree recursively, but keep the directories open, which are
     used in an open buffer.
 
-    See |nvim-tree-api.tree.collapse_all()|
+    See |nvim_tree.api.tree.collapse_all()|
 
     Calls: `api.tree.collapse_all({ keep_buffers = true })`
 
@@ -619,209 +619,6 @@ The api is separated in multiple modules, which can be accessed with
 Functions accepting {node} as their first argument will use the node under the
 cursor when that argument is not present or nil.
 
-==============================================================================
-API: Tree                                                 *nvim-tree-api.tree*
-
-tree.open({opts})                                  *nvim-tree-api.tree.open()*
-    Open the tree, focusing it if already open.
-
-    Parameters: ~
-      • {opts} (table) optional parameters
-
-    Options: ~
-      • {path}           (string)  root directory for the tree
-      • {current_window} (boolean) open the tree in the current window
-      • {winid}          (number)  open the tree in the specified |winid|,
-                                   overrides {current_window}
-      • {find_file}      (boolean) find the current buffer
-      • {update_root}    (boolean) requires {find_file}, see
-                                   |nvim_tree.Config.UpdateFocusedFile| {update_root}
-
-tree.toggle({opts})                              *nvim-tree-api.tree.toggle()*
-    Open or close the tree.
-
-    Parameters: ~
-      • {opts} (table) optional parameters
-
-    Options: ~
-      • {path}           (string)  root directory for the tree
-      • {current_window} (boolean) open the tree in the current window
-      • {winid}          (number)  open the tree in the specified |winid|,
-                                   overrides {current_window}
-      • {find_file}      (boolean) find the current buffer
-      • {update_root}    (boolean) requires {find_file}, see
-                                   |nvim_tree.Config.UpdateFocusedFile| {update_root}
-      • {focus}          (boolean) focus the tree when opening, default true
-
-tree.close()                                      *nvim-tree-api.tree.close()*
-    Close the tree, affecting all tabs as per |nvim_tree.Config.Tab.Sync| {close}
-
-tree.close_in_this_tab()              *nvim-tree-api.tree.close_in_this_tab()*
-    Close the tree in this tab only.
-
-tree.close_in_all_tabs()              *nvim-tree-api.tree.close_in_all_tabs()*
-    Close the tree in all tabs.
-
-tree.focus()                                      *nvim-tree-api.tree.focus()*
-    Focus the tree, opening it if necessary.
-    Retained for compatibility, use |nvim-tree-api.tree.open()| with no arguments instead.
-
-tree.reload()                                    *nvim-tree-api.tree.reload()*
-    Refresh the tree. Does nothing if closed.
-
-tree.resize({opts})                              *nvim-tree-api.tree.resize()*
-    Resize the tree, persisting the new size.
-    Resets to |nvim_tree.Config.View| {width} when no {opts} provided.
-    See |:NvimTreeResize|
-
-    Parameters: ~
-      • {opts} (table) optional parameters
-
-    Options: ~
-      • {width}    (table)  new |nvim_tree.Config.View| {width} value
-      • {absolute} (number) set the width
-      • {relative} (number) increase or decrease the width
-
-    Only one option is supported, in the priority order above.
-    {absolute} and {relative} do nothing when {width} is a function.
-
-tree.change_root({path})                    *nvim-tree-api.tree.change_root()*
-    Change the tree's root to a path.
-
-    Parameters: ~
-      • {path} (string) absolute or relative path
-
-                                    *nvim-tree-api.tree.change_root_to_node()*
-tree.change_root_to_node({node})
-    Change the tree's root to a folder node or the parent of a file node.
-
-    Parameters: ~
-      • {node} (Node) folder or file
-
-                                  *nvim-tree-api.tree.change_root_to_parent()*
-tree.change_root_to_parent({node})
-    Change the tree's root to the parent of a node.
-
-    Parameters: ~
-      • {node} (Node) folder or file
-
-tree.get_node_under_cursor()      *nvim-tree-api.tree.get_node_under_cursor()*
-    Retrieve the currently focused node.
-
-    Return: ~
-      node or nil if tree is not visible
-
-tree.get_nodes()                              *nvim-tree-api.tree.get_nodes()*
-    Retrieve a hierarchical list of all the nodes. This is a cloned list for
-    reference purposes only and should not be passed into other API functions.
-
-    Return: ~
-      table of nodes
-
-tree.find_file({opts})                        *nvim-tree-api.tree.find_file()*
-    Find and focus a file or folder in the tree. Finds current buffer unless
-    otherwise specified.
-
-    Parameters: ~
-      • {opts} (table) optional parameters
-
-    Options: ~
-      • {buf}            (string|number)  absolute/relative path OR bufnr to find
-      • {open}           (boolean)        open the tree if necessary
-      • {current_window} (boolean)        requires {open}, open in the current window
-      • {winid}          (number)         open the tree in the specified |winid|,
-                                          overrides {current_window}
-      • {update_root}    (boolean)        see |nvim_tree.Config.UpdateFocusedFile| {update_root}
-      • {focus}          (boolean)        focus the tree
-
-tree.search_node()                          *nvim-tree-api.tree.search_node()*
-    Open the search dialogue as per the search_node action.
-
-tree.collapse_all({opts})                  *nvim-tree-api.tree.collapse_all()*
-    Collapse the tree.
-
-    Parameters: ~
-      • {opts} (table) optional parameters
-
-    Options: ~
-      • {keep_buffers} (boolean) do not collapse nodes with open buffers.
-
-tree.expand_all({node}, {opts})              *nvim-tree-api.tree.expand_all()*
-    Recursively expand all nodes under the tree root or specified folder.
-
-    Parameters: ~
-      • {node} (Node|nil) folder
-      • {opts} (ApiTreeExpandOpts) optional parameters
-
-    Options: ~
-      • {expand_until} ((fun(expansion_count: integer, node: Node?): boolean)?)
-            Return true if {node} should be expanded.
-            {expansion_count} is the total number of folders expanded.
-
-                                  *nvim-tree-api.tree.toggle_enable_filters()*
-tree.toggle_enable_filters()
-    Toggle |nvim_tree.Config.Filters| {enable} all filters.
-
-                                *nvim-tree-api.tree.toggle_gitignore_filter()*
-tree.toggle_gitignore_filter()
-    Toggle |nvim_tree.Config.Filters| {git_ignored} filter.
-
-                                *nvim-tree-api.tree.toggle_git_clean_filter()*
-tree.toggle_git_clean_filter()
-    Toggle |nvim_tree.Config.Filters| {git_clean} filter.
-
-                                *nvim-tree-api.tree.toggle_no_buffer_filter()*
-tree.toggle_no_buffer_filter()
-    Toggle |nvim_tree.Config.Filters| {no_buffer} filter.
-
-                              *nvim-tree-api.tree.toggle_no_bookmark_filter()*
-tree.toggle_no_bookmark_filter()
-    Toggle |nvim_tree.Config.Filters| {no_bookmark} filter.
-
-                                   *nvim-tree-api.tree.toggle_custom_filter()*
-tree.toggle_custom_filter()
-    Toggle |nvim_tree.Config.Filters| {custom} filter.
-
-                                   *nvim-tree-api.tree.toggle_hidden_filter()*
-tree.toggle_hidden_filter()
-    Toggle |nvim_tree.Config.Filters| {dotfiles} filter.
-
-tree.toggle_help()                          *nvim-tree-api.tree.toggle_help()*
-    Toggle help view.
-
-tree.is_tree_buf({bufnr})                   *nvim-tree-api.tree.is_tree_buf()*
-    Checks if a buffer is an nvim-tree.
-
-    Parameters: ~
-      • {bufnr} (number|nil) buffer handle, 0 or nil for current buffer
-
-    Return: ~
-      (boolean) buffer is an nvim-tree buffer
-
-tree.is_visible({opts})                      *nvim-tree-api.tree.is_visible()*
-    Checks if nvim-tree is visible on the current, specified or any tab.
-
-    Parameters: ~
-      • {opts} (table) optional parameters
-
-    Options: ~
-      • {tabpage}     (number)  as per |nvim_get_current_tabpage()|
-      • {any_tabpage} (boolean) visible on any tab, default false
-
-    Return: ~
-      (boolean) nvim-tree is visible
-
-tree.winid({opts})                              *nvim-tree-api.tree.winid()*
-    Retrieve the winid of the open tree.
-
-    Parameters: ~
-      • {opts} (table) optional parameters
-
-    Options: ~
-      • {tabpage} (number|nil)  tabpage, 0 or nil for current, default nil
-
-    Return: ~
-      (number) winid or nil if tree is not visible
 
 ==============================================================================
 API: File System                                            *nvim-tree-api.fs*
@@ -2706,32 +2503,32 @@ Class: Config.Filters                               *nvim-tree-config-filters*
     Filters can be set at startup or toggled live via API with default
     mappings.
 
-    `I     `{git_ignored}`         `|nvim-tree-api.tree.toggle_gitignore_filter()|
+    `I     `{git_ignored}`         `|nvim_tree.api.tree.toggle_gitignore_filter()|
     Ignore files based on `.gitignore`. Requires |nvim_tree.Config.Git|
 
-    `H     `{dotfiles}`            `|nvim-tree-api.tree.toggle_hidden_filter()|
+    `H     `{dotfiles}`            `|nvim_tree.api.tree.toggle_hidden_filter()|
     Filter dotfiles: files/directories starting with a `.`
 
-    `C     `{git_clean}`           `|nvim-tree-api.tree.toggle_git_clean_filter()|
+    `C     `{git_clean}`           `|nvim_tree.api.tree.toggle_git_clean_filter()|
     Filter files with no git status. `.gitignore` files will not be filtered
     when {git_ignored}, as they are effectively dirty.
 
-    `B     `{no_buffer}`           `|nvim-tree-api.tree.toggle_no_buffer_filter()|
+    `B     `{no_buffer}`           `|nvim_tree.api.tree.toggle_no_buffer_filter()|
     Filter files that have no |buflisted()| buffer. For performance reasons
     buffer delete/wipe may not be immediately shown. A reload or filesystem
     event will always result in an update.
 
-    `M     `{no_bookmark}`         `|nvim-tree-api.tree.toggle_no_bookmark_filter()|
+    `M     `{no_bookmark}`         `|nvim_tree.api.tree.toggle_no_bookmark_filter()|
     Filter files that are not bookmarked. Enabling this is not useful as there
     is no means yet to persist bookmarks.
 
-    `U     `{custom}`              `|nvim-tree-api.tree.toggle_custom_filter()|
+    `U     `{custom}`              `|nvim_tree.api.tree.toggle_custom_filter()|
     Disable specific file/directory names via:
     • a list of backslash escaped |vim.regex| strings e.g. `"^\\.git""`
     • a function passed the absolute path of the directory.
 
     All filters including live filter may be disabled via {enable} and toggled
-    with |nvim-tree-api.tree.toggle_enable_filters()|
+    with |nvim_tree.api.tree.toggle_enable_filters()|
 
     Files/directories may be {exclude}d from filtering: they will always be
     shown, overriding {git_ignored}, {dotfiles} and {custom}.
@@ -2826,7 +2623,7 @@ Class: Config.Actions                               *nvim-tree-config-actions*
                                to a directory above the global cwd.
 
 *nvim_tree.Config.Actions.ExpandAll*
-    Configure |nvim-tree-api.tree.expand_all()| and
+    Configure |nvim_tree.api.tree.expand_all()| and
     |nvim-tree-api.node.expand()|
 
     Fields: ~
diff --git a/lua/nvim-tree/_meta/config/actions.lua b/lua/nvim-tree/_meta/config/actions.lua
index e65fe4d79c4..5e46edfa133 100644
--- a/lua/nvim-tree/_meta/config/actions.lua
+++ b/lua/nvim-tree/_meta/config/actions.lua
@@ -43,7 +43,7 @@ error("Cannot require a meta file")
 
 
 
----Configure [nvim-tree-api.tree.expand_all()] and [nvim-tree-api.node.expand()]
+---Configure [nvim_tree.api.tree.expand_all()] and [nvim-tree-api.node.expand()]
 ---@class nvim_tree.Config.Actions.ExpandAll
 ---
 ---Limit the number of folders being explored when expanding every folder. Avoids hanging Nvim when running this action on very large folders.
diff --git a/lua/nvim-tree/_meta/config/filters.lua b/lua/nvim-tree/_meta/config/filters.lua
index 93de5d64733..35e17d40469 100644
--- a/lua/nvim-tree/_meta/config/filters.lua
+++ b/lua/nvim-tree/_meta/config/filters.lua
@@ -9,27 +9,27 @@ error("Cannot require a meta file")
 ---
 ---Filters can be set at startup or toggled live via API with default mappings.
 ---
----`I     `{git_ignored}`         `|nvim-tree-api.tree.toggle_gitignore_filter()|
+---`I     `{git_ignored}`         `|nvim_tree.api.tree.toggle_gitignore_filter()|
 ---Ignore files based on `.gitignore`. Requires |nvim_tree.Config.Git|
 ---
----`H     `{dotfiles}`            `|nvim-tree-api.tree.toggle_hidden_filter()|
+---`H     `{dotfiles}`            `|nvim_tree.api.tree.toggle_hidden_filter()|
 ---Filter dotfiles: files/directories starting with a `.`
 ---
----`C     `{git_clean}`           `|nvim-tree-api.tree.toggle_git_clean_filter()|
+---`C     `{git_clean}`           `|nvim_tree.api.tree.toggle_git_clean_filter()|
 ---Filter files with no git status. `.gitignore` files will not be filtered when {git_ignored}, as they are effectively dirty.
 ---
----`B     `{no_buffer}`           `|nvim-tree-api.tree.toggle_no_buffer_filter()|
+---`B     `{no_buffer}`           `|nvim_tree.api.tree.toggle_no_buffer_filter()|
 ---Filter files that have no |buflisted()| buffer. For performance reasons buffer delete/wipe may not be immediately shown. A reload or filesystem event will always result in an update.
 ---
----`M     `{no_bookmark}`         `|nvim-tree-api.tree.toggle_no_bookmark_filter()|
+---`M     `{no_bookmark}`         `|nvim_tree.api.tree.toggle_no_bookmark_filter()|
 ---Filter files that are not bookmarked. Enabling this is not useful as there is no means yet to persist bookmarks.
 ---
----`U     `{custom}`              `|nvim-tree-api.tree.toggle_custom_filter()|
+---`U     `{custom}`              `|nvim_tree.api.tree.toggle_custom_filter()|
 ---Disable specific file/directory names via:
 ---- a list of backslash escaped |vim.regex| strings e.g. `"^\\.git""`
 ---- a function passed the absolute path of the directory.
 ---
----All filters including live filter may be disabled via {enable} and toggled with |nvim-tree-api.tree.toggle_enable_filters()|
+---All filters including live filter may be disabled via {enable} and toggled with |nvim_tree.api.tree.toggle_enable_filters()|
 ---
 ---Files/directories may be {exclude}d from filtering: they will always be shown, overriding {git_ignored}, {dotfiles} and {custom}.
 ---@class nvim_tree.Config.Filters
diff --git a/scripts/help-update.sh b/scripts/help-update.sh
index 7fe52a263f2..ceeca2e661f 100755
--- a/scripts/help-update.sh
+++ b/scripts/help-update.sh
@@ -47,3 +47,6 @@ begin="Show the mappings:"
 end="======"
 sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/DEFAULT_ON_ATTACH.help
            }; /${end}/p; d; }" doc/nvim-tree-lua.txt
+
+# TODO #3088 remove once all api references have been updated
+sed -i -e "s/nvim-tree-api.tree/nvim_tree.api.tree/g" doc/nvim-tree-lua.txt

From 060455e143a8a8a273344f0bb2be6b859dbd4f9a Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sun, 18 Jan 2026 10:39:37 +1100
Subject: [PATCH 086/170] docs(#3088): extract api/config/mappings.lua

---
 doc/nvim-tree-lua.txt                 | 80 ++++++++++++++-------------
 lua/nvim-tree/api.lua                 |  5 ++
 lua/nvim-tree/api/config/mappings.lua | 34 ++++++++++++
 lua/nvim-tree/api/init.lua            |  3 +-
 lua/nvim-tree/api/tree.lua            | 27 ++++-----
 scripts/gen_vimdoc_config.lua         | 13 +++--
 scripts/help-update.sh                |  2 +-
 scripts/lintdoc.sh                    |  1 -
 8 files changed, 104 insertions(+), 61 deletions(-)
 create mode 100644 lua/nvim-tree/api/config/mappings.lua

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 02fcfc712f5..329c1af73a4 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -1079,32 +1079,6 @@ marks.navigate.select()                *nvim-tree-api.marks.navigate.select()*
     Prompts for selection of a marked node, sorted by absolute paths.
     A folder will be focused, a file will be opened.
 
-==============================================================================
-API: Config                                             *nvim-tree-api.config*
-
-                           *nvim-tree-api.config.mappings.default_on_attach()*
-config.mappings.default_on_attach({bufnr})
-    Set all |nvim-tree-mappings-default|. Call from your |nvim_tree.Config| {on_attach}
-
-    Parameters: ~
-      • {bufnr} (number) nvim-tree buffer number passed to |nvim_tree.Config| {on_attach}
-
-                                  *nvim-tree-api.config.mappings.get_keymap()*
-config.mappings.get_keymap()
-    Retrieves all buffer local mappings for nvim-tree.
-    These are the mappings that are applied by |nvim_tree.Config| {on_attach}, which
-    may include default mappings.
-
-    Return: ~
-        (table) as per |nvim_buf_get_keymap()|
-
-                          *nvim-tree-api.config.mappings.get_keymap_default()*
-config.mappings.get_keymap_default()
-    Retrieves the buffer local mappings for nvim-tree that are applied by
-    |nvim-tree-api.config.mappings.default_on_attach()|
-
-    Return: ~
-        (table) as per |nvim_buf_get_keymap()|
 
 ==============================================================================
 API: Commands                                         *nvim-tree-api.commands*
@@ -1266,7 +1240,7 @@ You are encouraged to copy these to your {on_attach} function. >lua
   -- END_DEFAULT_ON_ATTACH
 <
 Alternatively, you may apply these default mappings from your |nvim_tree.Config| {on_attach} via
-|nvim-tree-api.config.mappings.default_on_attach()| e.g. >lua
+|nvim_tree.api.config.mappings.default_on_attach()| e.g. >lua
 
   local function my_on_attach(bufnr)
     local api = require("nvim-tree.api")
@@ -2865,6 +2839,34 @@ Class: Config.Log                                       *nvim-tree-config-log*
 
 
 
+==============================================================================
+Lua module: nvim_tree.api.config                        *nvim-tree-api-config*
+
+                           *nvim_tree.api.config.mappings.default_on_attach()*
+default_on_attach({bufnr})
+    Apply all |nvim-tree-mappings-default|. Call from your |nvim_tree.Config|
+    {on_attach}.
+
+    Parameters: ~
+      • {bufnr}  (`integer`) use the `bufnr` passed to {on_attach}
+
+get_keymap()                      *nvim_tree.api.config.mappings.get_keymap()*
+    Retrieve all buffer local mappings for nvim-tree. These are the mappings
+    that are applied by |nvim_tree.Config| {on_attach}, which may include
+    default mappings.
+
+    Return: ~
+        (`vim.api.keyset.get_keymap[]`)
+
+                          *nvim_tree.api.config.mappings.get_keymap_default()*
+get_keymap_default()
+    Retrieves the buffer local mappings for nvim-tree that are applied by
+    |nvim_tree.api.config.mappings.default_on_attach()|
+
+    Return: ~
+        (`vim.api.keyset.get_keymap[]`)
+
+
 ==============================================================================
 Lua module: nvim_tree.api.tree                            *nvim-tree-api-tree*
 
@@ -2922,14 +2924,14 @@ find_file({opts})                             *nvim_tree.api.tree.find_file()*
 
     Parameters: ~
       • {opts}  (`table?`) optional
-                • {buf}? (`string|number`) Absolute/relative path OR |bufnr()|
+                • {buf}? (`string|integer`) Absolute/relative path OR `bufnr`
                   to find.
                 • {open}? (`boolean`, default: false) Open the tree if
                   necessary.
                 • {current_window}? (`boolean`, default: false) Requires
                   {open}: open in the current window.
-                • {winid}? (`number`) Open the tree in the specified |winid|,
-                  overrides {current_window}
+                • {winid}? (`integer`) Open the tree in the specified
+                  |window-ID|, overrides {current_window}
                 • {update_root}? (`boolean`, default: false) Update root after
                   find, see |nvim_tree.Config.UpdateFocusedFile| {update_root}
                 • {focus}? (`boolean`, default: false) Focus the tree window.
@@ -2954,7 +2956,7 @@ is_tree_buf({bufnr})                        *nvim_tree.api.tree.is_tree_buf()*
     Checks if a buffer is an nvim-tree.
 
     Parameters: ~
-      • {bufnr}  (`number?`) 0 or nil for current buffer.
+      • {bufnr}  (`integer?`) 0 or nil for current buffer.
 
     Return: ~
         (`boolean`)
@@ -2979,8 +2981,8 @@ open({opts})                                       *nvim_tree.api.tree.open()*
                 • {path}? (`string`) Root directory for the tree
                 • {current_window}? (`boolean`, default: false) Open the tree
                   in the current window
-                • {winid}? (`number`) Open the tree in the specified |winid|,
-                  overrides {current_window}
+                • {winid}? (`integer`) Open the tree in the specified
+                  |window-ID|, overrides {current_window}
                 • {find_file}? (`boolean`, default: false) Find the current
                   buffer.
                 • {update_root}? (`boolean`, default: false) Update root
@@ -3005,8 +3007,8 @@ resize({opts})                                   *nvim_tree.api.tree.resize()*
                 • {width}
                   (`nvim_tree.Config.View.WidthSpec|nvim_tree.Config.View.Width`)
                   New |nvim_tree.Config.View| {width} value.
-                • {absolute} (`number`) Set the width.
-                • {relative} (`number`) Increase or decrease the width.
+                • {absolute} (`integer`) Set the width.
+                • {relative} (`integer`) Increase or decrease the width.
 
 search_node()                               *nvim_tree.api.tree.search_node()*
     Open the search dialogue.
@@ -3019,8 +3021,8 @@ toggle({opts})                                   *nvim_tree.api.tree.toggle()*
                 • {path}? (`string`) Root directory for the tree
                 • {current_window}? (`boolean`, default: false) Open the tree
                   in the current window
-                • {winid}? (`number`) Open the tree in the specified |winid|,
-                  overrides {current_window}
+                • {winid}? (`integer`) Open the tree in the specified
+                  |window-ID|, overrides {current_window}
                 • {find_file}? (`boolean`, default: false) Find the current
                   buffer.
                 • {focus}? (`boolean`, default: true) Focus the tree when
@@ -3055,14 +3057,14 @@ toggle_no_buffer_filter()
     Toggle |nvim_tree.Config.Filters| {no_buffer} filter.
 
 winid({opts})                                     *nvim_tree.api.tree.winid()*
-    Retrieve the winid of the open tree.
+    Retrieve the window of the open tree.
 
     Parameters: ~
       • {opts}  (`table?`) optional
                 • {tabpage}? (`integer`) |tab-ID| 0 or nil for current.
 
     Return: ~
-        (`integer?`) |winid|, nil if tree is not visible.
+        (`integer?`) |window-ID|, nil if tree is not visible.
 
 
  vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:
diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index 789d6bdbf34..d41c035a5cb 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -364,10 +364,15 @@ Api.marks.navigate.next = wrap_explorer_member("marks", "navigate_next")
 Api.marks.navigate.prev = wrap_explorer_member("marks", "navigate_prev")
 Api.marks.navigate.select = wrap_explorer_member("marks", "navigate_select")
 
+function Api.hydrate_config(tree)
+  Api.tree = tree
+
 Api.config.mappings.get_keymap = wrap(keymap.get_keymap)
 Api.config.mappings.get_keymap_default = wrap(keymap.get_keymap_default)
 Api.config.mappings.default_on_attach = keymap.default_on_attach
 
+end
+
 Api.diagnostics.hi_test = wrap(appearance_hi_test)
 
 Api.commands.get = wrap(function()
diff --git a/lua/nvim-tree/api/config/mappings.lua b/lua/nvim-tree/api/config/mappings.lua
new file mode 100644
index 00000000000..305850961ab
--- /dev/null
+++ b/lua/nvim-tree/api/config/mappings.lua
@@ -0,0 +1,34 @@
+---@meta
+
+
+-- # TODO #3088 this should be api/config.lua however that results in a filename clash in gen_vimdoc_config.lua
+
+
+local nvim_tree = { api = { config = { mappings = {} } } }
+
+
+
+---Retrieve all buffer local mappings for nvim-tree. These are the mappings that are applied by [nvim_tree.Config] {on_attach}, which may include default mappings.
+---
+---@return vim.api.keyset.get_keymap[]
+function nvim_tree.api.config.mappings.get_keymap() end
+
+
+
+--- Retrieves the buffer local mappings for nvim-tree that are applied by [nvim_tree.api.config.mappings.default_on_attach()]
+---
+---@return vim.api.keyset.get_keymap[]
+function nvim_tree.api.config.mappings.get_keymap_default() end
+
+
+
+---Apply all [nvim-tree-mappings-default]. Call from your [nvim_tree.Config] {on_attach}.
+---
+---@param bufnr integer use the `bufnr` passed to {on_attach}
+function nvim_tree.api.config.mappings.default_on_attach(bufnr) end
+
+
+
+require("nvim-tree.api").hydrate_config(nvim_tree.api.config)
+
+return nvim_tree.api.tree
diff --git a/lua/nvim-tree/api/init.lua b/lua/nvim-tree/api/init.lua
index 206faf24f91..1d7c12bc74d 100644
--- a/lua/nvim-tree/api/init.lua
+++ b/lua/nvim-tree/api/init.lua
@@ -1,3 +1,4 @@
 return {
-  tree = require("nvim-tree.api.tree")
+  config = require("nvim-tree.api.config.mappings"),
+  tree = require("nvim-tree.api.tree"),
 }
diff --git a/lua/nvim-tree/api/tree.lua b/lua/nvim-tree/api/tree.lua
index c0d8dad2095..77da44931cc 100644
--- a/lua/nvim-tree/api/tree.lua
+++ b/lua/nvim-tree/api/tree.lua
@@ -13,8 +13,8 @@ local nvim_tree = { api = { tree = {} } }
 ---(default: false)
 ---@field current_window? boolean
 ---
----Open the tree in the specified [winid], overrides {current_window}
----@field winid? number
+---Open the tree in the specified  [window-ID], overrides {current_window}
+---@field winid? integer
 ---
 ---Find the current buffer.
 ---(default: false)
@@ -41,8 +41,8 @@ function nvim_tree.api.tree.open(opts) end
 ---(default: false)
 ---@field current_window? boolean
 ---
----Open the tree in the specified [winid], overrides {current_window}
----@field winid? number
+---Open the tree in the specified [window-ID], overrides {current_window}
+---@field winid? integer
 ---
 ---Find the current buffer.
 ---(default: false)
@@ -93,10 +93,10 @@ function nvim_tree.api.tree.reload() end
 ---@field width nvim_tree.Config.View.WidthSpec|nvim_tree.Config.View.Width
 ---
 ---Set the width.
----@field absolute number
+---@field absolute integer
 ---
 ---Increase or decrease the width.
----@field relative number
+---@field relative integer
 
 ---Resize the tree, persisting the new size. Resets to [nvim_tree.Config.View] {width} when no {opts} provided.
 ---
@@ -143,8 +143,8 @@ function nvim_tree.api.tree.get_nodes() end
 ---@class nvim_tree.api.tree.find_file.Opts
 ---@inlinedoc
 ---
----Absolute/relative path OR [bufnr()] to find.
----@field buf? string|number
+---Absolute/relative path OR `bufnr` to find.
+---@field buf? string|integer
 ---
 ---Open the tree if necessary.
 ---(default: false)
@@ -154,8 +154,8 @@ function nvim_tree.api.tree.get_nodes() end
 ---(default: false)
 ---@field current_window? boolean
 ---
----Open the tree in the specified [winid], overrides {current_window}
----@field winid? number
+---Open the tree in the specified [window-ID], overrides {current_window}
+---@field winid? integer
 ---
 ---Update root after find, see [nvim_tree.Config.UpdateFocusedFile] {update_root}
 ---(default: false)
@@ -250,7 +250,8 @@ function nvim_tree.api.tree.toggle_help() end
 
 ---Checks if a buffer is an nvim-tree.
 ---
----@param bufnr? number 0 or nil for current buffer.
+---@param bufnr? integer 0 or nil for current buffer.
+---
 ---@return boolean
 function nvim_tree.api.tree.is_tree_buf(bufnr) end
 
@@ -280,10 +281,10 @@ function nvim_tree.api.tree.is_visible(opts) end
 ---[tab-ID] 0 or nil for current.
 ---@field tabpage? integer
 
----Retrieve the winid of the open tree.
+---Retrieve the window of the open tree.
 ---
 ---@param opts? nvim_tree.api.tree.winid.Opts optional
----@return integer? [winid], nil if tree is not visible.
+---@return integer? [window-ID], nil if tree is not visible.
 function nvim_tree.api.tree.winid(opts) end
 
 
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index d568f4ab598..4738829abef 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -31,6 +31,7 @@ local modules = {
   { helptag = "nvim-tree-config-experimental",        title = "Class: Config.Experimental",       path = "./lua/nvim_tree/_meta/config/experimental.lua", },
   { helptag = "nvim-tree-config-log",                 title = "Class: Config.Log",                path = "./lua/nvim_tree/_meta/config/log.lua", },
 
+  { helptag = "nvim-tree-api-config",                 title = "Lua module: nvim_tree.api.config", path = "./lua/nvim_tree/api/config/mappings.lua", },
   { helptag = "nvim-tree-api-tree",                   title = "Lua module: nvim_tree.api.tree",   path = "./lua/nvim_tree/api/tree.lua", },
 }
 
@@ -39,13 +40,13 @@ for _, m in ipairs(modules) do
   m.file = vim.fn.fnamemodify(m.path, ":t")
 end
 
---module name is derived by the generator as the file name with the first letter capitalised
+--section name is derived by the generator as the file name with the first letter capitalised
 --except for some like UI
 ---@type table
-local modules_by_name = {}
+local modules_by_section = {}
 for _, m in ipairs(modules) do
   local name = m.name or m.file:gsub(".lua", ""):gsub("^%l", string.upper)
-  modules_by_name[name] = m
+  modules_by_section[name] = m
 end
 
 ---@diagnostic disable-next-line: undefined-doc-name
@@ -62,17 +63,17 @@ local config = {
 
     section_fmt = function(name)
       print(string.format("section_fmt name=%s", name))
-      return modules_by_name[name] and modules_by_name[name].title or error(string.format("unknown module %s passed to section_fmt", name))
+      return modules_by_section[name] and modules_by_section[name].title or error(string.format("unknown module %s passed to section_fmt", name))
     end,
 
     helptag_fmt = function(name)
       print(string.format("helptag_fmt name=%s", name))
-      return modules_by_name[name] and modules_by_name[name].helptag or error(string.format("unknown module %s passed to helptag_fmt", name))
+      return modules_by_section[name] and modules_by_section[name].helptag or error(string.format("unknown module %s passed to helptag_fmt", name))
     end,
 
     -- optional, no default xform
     fn_xform = function(fun)
-      print(string.format("fn_xform fun=%s", vim.inspect(fun)))
+      -- print(string.format("fn_xform fun=%s", vim.inspect(fun)))
 
       if (fun.module) then
         -- generator doesn't strip meta
diff --git a/scripts/help-update.sh b/scripts/help-update.sh
index ceeca2e661f..a2d223817ed 100755
--- a/scripts/help-update.sh
+++ b/scripts/help-update.sh
@@ -49,4 +49,4 @@ sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/DEFAULT_ON_ATTACH.help
            }; /${end}/p; d; }" doc/nvim-tree-lua.txt
 
 # TODO #3088 remove once all api references have been updated
-sed -i -e "s/nvim-tree-api.tree/nvim_tree.api.tree/g" doc/nvim-tree-lua.txt
+sed -i -e "s/nvim\-tree\-api\.tree\./nvim_tree.api.tree./g" doc/nvim-tree-lua.txt
diff --git a/scripts/lintdoc.sh b/scripts/lintdoc.sh
index 89a3b623467..6b5b0a88d77 100755
--- a/scripts/lintdoc.sh
+++ b/scripts/lintdoc.sh
@@ -1,6 +1,5 @@
 #!/usr/bin/env sh
 
-
 # Wrapper around Nvim help linter lintdoc.lua, run as part of Nvim's make lintdoc target.
 #
 # Requires Nvim to have been built.

From 4292f975afa201b54d2d1f040b27df5a52e3f32d Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sun, 18 Jan 2026 11:16:38 +1100
Subject: [PATCH 087/170] docs(#3088): api.config.mappings -> api.map

---
 README.md                             |  2 +-
 doc/nvim-tree-lua.txt                 | 32 +++++++++++++++----------
 lua/nvim-tree/api.lua                 | 26 +++++++++++++-------
 lua/nvim-tree/api/config/mappings.lua | 34 ---------------------------
 lua/nvim-tree/api/init.lua            |  2 +-
 lua/nvim-tree/api/map.lua             | 29 +++++++++++++++++++++++
 scripts/gen_vimdoc_config.lua         |  8 ++++---
 7 files changed, 73 insertions(+), 60 deletions(-)
 delete mode 100644 lua/nvim-tree/api/config/mappings.lua
 create mode 100644 lua/nvim-tree/api/map.lua

diff --git a/README.md b/README.md
index 057ebf9db96..2a9e68813d6 100644
--- a/README.md
+++ b/README.md
@@ -97,7 +97,7 @@ local function my_on_attach(bufnr)
   end
 
   -- default mappings
-  api.config.mappings.default_on_attach(bufnr)
+  api.map.default_on_attach(bufnr)
 
   -- custom mappings
   vim.keymap.set('n', '', api.tree.change_root_to_parent,        opts('Up'))
diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 329c1af73a4..cba1a76f7e5 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -169,7 +169,7 @@ via |nvim_tree.Config| {on_attach} e.g. >lua
     end
 
     -- default mappings
-    api.config.mappings.default_on_attach(bufnr)
+    api.map.default_on_attach(bufnr)
 
     -- custom mappings
     vim.keymap.set("n", "", api.tree.change_root_to_parent,        opts("Up"))
@@ -1128,7 +1128,7 @@ The `on_attach` function is passed the `bufnr` of nvim-tree. Use
     vim.keymap.set("n", "", api.node.open.replace_tree_buffer,     opts("Open: In Place"))
     ---
     -- OR use all default mappings
-    api.config.mappings.default_on_attach(bufnr)
+    api.map.default_on_attach(bufnr)
 
     -- remove a default
     vim.keymap.del("n", "", { buffer = bufnr })
@@ -1240,7 +1240,7 @@ You are encouraged to copy these to your {on_attach} function. >lua
   -- END_DEFAULT_ON_ATTACH
 <
 Alternatively, you may apply these default mappings from your |nvim_tree.Config| {on_attach} via
-|nvim_tree.api.config.mappings.default_on_attach()| e.g. >lua
+|nvim_tree.api.map.default_on_attach()| e.g. >lua
 
   local function my_on_attach(bufnr)
     local api = require("nvim-tree.api")
@@ -1249,7 +1249,7 @@ Alternatively, you may apply these default mappings from your |nvim_tree.Config|
       return { desc = "nvim-tree: " .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true }
     end
 
-    api.config.mappings.default_on_attach(bufnr)
+    api.map.default_on_attach(bufnr)
 
     -- your removals and mappings go here
   end
@@ -1767,7 +1767,7 @@ migrated and used.
 There are no plans to remove this migration.
 
 ==============================================================================
-Legacy: Config                                         *nvim-tree-legacy-opts*
+Legacy: Config                                       *nvim-tree-legacy-config*
 
 Legacy config is translated to the current, making type and value changes as
 needed.
@@ -1785,6 +1785,16 @@ needed.
 `renderer.icons.webdev_colors`       |nvim_tree.Config.Renderer.Icons.WebDevicons.File| {color}
 `renderer.icons.padding`             |nvim_tree.Config.Renderer.Icons.Padding| {icon}
 
+==============================================================================
+Legacy: API                                             *nvim-tree-legacy-api*
+
+Some API functions have been refactored however the previous function will
+continue to be available.
+
+`api.config.mappings.get_keymap`          |nvim_tree.api.map.get_keymap()|
+`api.config.mappings.get_keymap_default`  |nvim_tree.api.map.get_keymap_default()|
+`api.config.mappings.default_on_attach`   |nvim_tree.api.map.default_on_attach()|
+
 ==============================================================================
 Legacy: Highlight                                 *nvim-tree-legacy-highlight*
 
@@ -2840,17 +2850,16 @@ Class: Config.Log                                       *nvim-tree-config-log*
 
 
 ==============================================================================
-Lua module: nvim_tree.api.config                        *nvim-tree-api-config*
+Lua module: nvim_tree.api.map                              *nvim-tree-api-map*
 
-                           *nvim_tree.api.config.mappings.default_on_attach()*
-default_on_attach({bufnr})
+default_on_attach({bufnr})             *nvim_tree.api.map.default_on_attach()*
     Apply all |nvim-tree-mappings-default|. Call from your |nvim_tree.Config|
     {on_attach}.
 
     Parameters: ~
       • {bufnr}  (`integer`) use the `bufnr` passed to {on_attach}
 
-get_keymap()                      *nvim_tree.api.config.mappings.get_keymap()*
+get_keymap()                                  *nvim_tree.api.map.get_keymap()*
     Retrieve all buffer local mappings for nvim-tree. These are the mappings
     that are applied by |nvim_tree.Config| {on_attach}, which may include
     default mappings.
@@ -2858,10 +2867,9 @@ get_keymap()                      *nvim_tree.api.config.mappings.get_keymap()*
     Return: ~
         (`vim.api.keyset.get_keymap[]`)
 
-                          *nvim_tree.api.config.mappings.get_keymap_default()*
-get_keymap_default()
+get_keymap_default()                  *nvim_tree.api.map.get_keymap_default()*
     Retrieves the buffer local mappings for nvim-tree that are applied by
-    |nvim_tree.api.config.mappings.default_on_attach()|
+    |nvim_tree.api.map.default_on_attach()|
 
     Return: ~
         (`vim.api.keyset.get_keymap[]`)
diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index d41c035a5cb..4379ef0b723 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -35,13 +35,13 @@ local Api = {
   fs = {
     copy = {},
   },
-  git = {},
-  live_filter = {},
-  config = {
+  git = {}, -- 1 collides with Config.Git - api.tree.reload_git
+  live_filter = {}, -- 2 collides with Config.LiveFilter -  api.filter
+  config = {-- collides with Config - api.mapping
     mappings = {},
   },
   commands = {},
-  diagnostics = {},
+  diagnostics = {},-- 1 collides with Config.Diagnostics -  api.health
   decorator = {},
 }
 
@@ -364,12 +364,16 @@ Api.marks.navigate.next = wrap_explorer_member("marks", "navigate_next")
 Api.marks.navigate.prev = wrap_explorer_member("marks", "navigate_prev")
 Api.marks.navigate.select = wrap_explorer_member("marks", "navigate_select")
 
-function Api.hydrate_config(tree)
-  Api.tree = tree
+function Api.hydrate_map(map)
+  Api.map = map
+
+Api.map.get_keymap = wrap(keymap.get_keymap)
+Api.map.get_keymap_default = wrap(keymap.get_keymap_default)
+Api.map.default_on_attach = keymap.default_on_attach
 
-Api.config.mappings.get_keymap = wrap(keymap.get_keymap)
-Api.config.mappings.get_keymap_default = wrap(keymap.get_keymap_default)
-Api.config.mappings.default_on_attach = keymap.default_on_attach
+Api.config.mappings.get_keymap = Api.map.get_keymap
+Api.config.mappings.get_keymap_default = Api.map.get_keymap_default
+Api.config.mappings.default_on_attach = Api.map.default_on_attach
 
 end
 
@@ -384,4 +388,8 @@ end)
 ---@type nvim_tree.api.decorator.UserDecorator
 Api.decorator.UserDecorator = UserDecorator --[[@as nvim_tree.api.decorator.UserDecorator]]
 
+
+-- TODO #3088 legacy mappings have to go somewhere
+
+
 return Api
diff --git a/lua/nvim-tree/api/config/mappings.lua b/lua/nvim-tree/api/config/mappings.lua
deleted file mode 100644
index 305850961ab..00000000000
--- a/lua/nvim-tree/api/config/mappings.lua
+++ /dev/null
@@ -1,34 +0,0 @@
----@meta
-
-
--- # TODO #3088 this should be api/config.lua however that results in a filename clash in gen_vimdoc_config.lua
-
-
-local nvim_tree = { api = { config = { mappings = {} } } }
-
-
-
----Retrieve all buffer local mappings for nvim-tree. These are the mappings that are applied by [nvim_tree.Config] {on_attach}, which may include default mappings.
----
----@return vim.api.keyset.get_keymap[]
-function nvim_tree.api.config.mappings.get_keymap() end
-
-
-
---- Retrieves the buffer local mappings for nvim-tree that are applied by [nvim_tree.api.config.mappings.default_on_attach()]
----
----@return vim.api.keyset.get_keymap[]
-function nvim_tree.api.config.mappings.get_keymap_default() end
-
-
-
----Apply all [nvim-tree-mappings-default]. Call from your [nvim_tree.Config] {on_attach}.
----
----@param bufnr integer use the `bufnr` passed to {on_attach}
-function nvim_tree.api.config.mappings.default_on_attach(bufnr) end
-
-
-
-require("nvim-tree.api").hydrate_config(nvim_tree.api.config)
-
-return nvim_tree.api.tree
diff --git a/lua/nvim-tree/api/init.lua b/lua/nvim-tree/api/init.lua
index 1d7c12bc74d..03b4095adc3 100644
--- a/lua/nvim-tree/api/init.lua
+++ b/lua/nvim-tree/api/init.lua
@@ -1,4 +1,4 @@
 return {
-  config = require("nvim-tree.api.config.mappings"),
+  config = require("nvim-tree.api.map"),
   tree = require("nvim-tree.api.tree"),
 }
diff --git a/lua/nvim-tree/api/map.lua b/lua/nvim-tree/api/map.lua
new file mode 100644
index 00000000000..24b1d909a53
--- /dev/null
+++ b/lua/nvim-tree/api/map.lua
@@ -0,0 +1,29 @@
+---@meta
+local nvim_tree = { api = { map = {} } }
+
+
+
+---Retrieve all buffer local mappings for nvim-tree. These are the mappings that are applied by [nvim_tree.Config] {on_attach}, which may include default mappings.
+---
+---@return vim.api.keyset.get_keymap[]
+function nvim_tree.api.map.get_keymap() end
+
+
+
+--- Retrieves the buffer local mappings for nvim-tree that are applied by [nvim_tree.api.map.default_on_attach()]
+---
+---@return vim.api.keyset.get_keymap[]
+function nvim_tree.api.map.get_keymap_default() end
+
+
+
+---Apply all [nvim-tree-mappings-default]. Call from your [nvim_tree.Config] {on_attach}.
+---
+---@param bufnr integer use the `bufnr` passed to {on_attach}
+function nvim_tree.api.map.default_on_attach(bufnr) end
+
+
+
+require("nvim-tree.api").hydrate_map(nvim_tree.api.map)
+
+return nvim_tree.api.map
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index 4738829abef..0e9b52c255a 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -31,7 +31,7 @@ local modules = {
   { helptag = "nvim-tree-config-experimental",        title = "Class: Config.Experimental",       path = "./lua/nvim_tree/_meta/config/experimental.lua", },
   { helptag = "nvim-tree-config-log",                 title = "Class: Config.Log",                path = "./lua/nvim_tree/_meta/config/log.lua", },
 
-  { helptag = "nvim-tree-api-config",                 title = "Lua module: nvim_tree.api.config", path = "./lua/nvim_tree/api/config/mappings.lua", },
+  { helptag = "nvim-tree-api-map",                    title = "Lua module: nvim_tree.api.map",    path = "./lua/nvim_tree/api/map.lua", },
   { helptag = "nvim-tree-api-tree",                   title = "Lua module: nvim_tree.api.tree",   path = "./lua/nvim_tree/api/tree.lua", },
 }
 
@@ -63,12 +63,14 @@ local config = {
 
     section_fmt = function(name)
       print(string.format("section_fmt name=%s", name))
-      return modules_by_section[name] and modules_by_section[name].title or error(string.format("unknown module %s passed to section_fmt", name))
+      return modules_by_section[name] and modules_by_section[name].title or
+      error(string.format("unknown module %s passed to section_fmt", name))
     end,
 
     helptag_fmt = function(name)
       print(string.format("helptag_fmt name=%s", name))
-      return modules_by_section[name] and modules_by_section[name].helptag or error(string.format("unknown module %s passed to helptag_fmt", name))
+      return modules_by_section[name] and modules_by_section[name].helptag or
+      error(string.format("unknown module %s passed to helptag_fmt", name))
     end,
 
     -- optional, no default xform

From 6f2551b5c1c6ee53643d8ee08c4d9acc3c6d6348 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sun, 18 Jan 2026 11:37:38 +1100
Subject: [PATCH 088/170] docs(#3088): extract api/filter.lua

---
 doc/nvim-tree-lua.txt         | 151 +++++++++++++++++++++++-----------
 lua/nvim-tree/api.lua         |  14 +++-
 lua/nvim-tree/api/filter.lua  |  17 ++++
 lua/nvim-tree/api/init.lua    |   3 +-
 lua/nvim-tree/keymap.lua      |   4 +-
 scripts/gen_vimdoc_config.lua |   5 +-
 scripts/help-update.sh        |   2 +-
 7 files changed, 142 insertions(+), 54 deletions(-)
 create mode 100644 lua/nvim-tree/api/filter.lua

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index cba1a76f7e5..12f8e1a2302 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -96,68 +96,116 @@ Open the tree:  `:NvimTreeOpen`
 Show the mappings:  `g?`
 
 ``           CD                         |nvim_tree.api.tree.change_root_to_node()|
-``           Open: In Place             |nvim-tree-api.node.open.replace_tree_buffer()|
-``           Info                       |nvim-tree-api.node.show_info_popup()|
-``           Rename: Omit Filename      |nvim-tree-api.fs.rename_sub()|
-``           Open: New Tab              |nvim-tree-api.node.open.tab()|
-``           Open: Vertical Split       |nvim-tree-api.node.open.vertical()|
-``           Open: Horizontal Split     |nvim-tree-api.node.open.horizontal()|
-``            Close Directory            |nvim-tree-api.node.navigate.parent_close()|
-``            Open                       |nvim-tree-api.node.open.edit()|
-``           Delete                     |nvim-tree-api.fs.remove()|
-``           Open Preview               |nvim-tree-api.node.open.preview()|
-`>`               Next Sibling               |nvim-tree-api.node.navigate.sibling.next()|
-`<`               Previous Sibling           |nvim-tree-api.node.navigate.sibling.prev()|
-`.`               Run Command                |nvim-tree-api.node.run.cmd()|
+``           Open: In Place             |nvim_tree.api.node.open.replace_tree_buffer()|
+``           Info                       |nvim_tree.api.node.show_info_popup()|
+``           Rename: Omit Filename      |nvim_tree.api.fs.rename_sub()|
+``           Open: New Tab              |nvim_tree.api.node.open.tab()|
+``           Open: Vertical Split       |nvim_tree.api.node.open.vertical()|
+``           Open: Horizontal Split     |nvim_tree.api.node.open.horizontal()|
+``            Close Directory            |nvim_tree.api.node.navigate.parent_close()|
+``            Open                       |nvim_tree.api.node.open.edit()|
+``           Delete                     |nvim_tree.api.fs.remove()|
+``           Open Preview               |nvim_tree.api.node.open.preview()|
+`>`               Next Sibling               |nvim_tree.api.node.navigate.sibling.next()|
+`<`               Previous Sibling           |nvim_tree.api.node.navigate.sibling.prev()|
+`.`               Run Command                |nvim_tree.api.node.run.cmd()|
 `-`               Up                         |nvim_tree.api.tree.change_root_to_parent()|
-`a`               Create File Or Directory   |nvim-tree-api.fs.create()|
-`bd`              Delete Bookmarked          |nvim-tree-api.marks.bulk.delete()|
-`bt`              Trash Bookmarked           |nvim-tree-api.marks.bulk.trash()|
-`bmv`             Move Bookmarked            |nvim-tree-api.marks.bulk.move()|
+`a`               Create File Or Directory   |nvim_tree.api.fs.create()|
+`bd`              Delete Bookmarked          |nvim_tree.api.marks.bulk.delete()|
+`bt`              Trash Bookmarked           |nvim_tree.api.marks.bulk.trash()|
+`bmv`             Move Bookmarked            |nvim_tree.api.marks.bulk.move()|
 `B`               Toggle Filter: No Buffer   |nvim_tree.api.tree.toggle_no_buffer_filter()|
-`c`               Copy                       |nvim-tree-api.fs.copy.node()|
+`c`               Copy                       |nvim_tree.api.fs.copy.node()|
 `C`               Toggle Filter: Git Clean   |nvim_tree.api.tree.toggle_git_clean_filter()|
-`[c`              Prev Git                   |nvim-tree-api.node.navigate.git.prev()|
-`]c`              Next Git                   |nvim-tree-api.node.navigate.git.next()|
-`d`               Delete                     |nvim-tree-api.fs.remove()|
-`D`               Trash                      |nvim-tree-api.fs.trash()|
+`[c`              Prev Git                   |nvim_tree.api.node.navigate.git.prev()|
+`]c`              Next Git                   |nvim_tree.api.node.navigate.git.next()|
+`d`               Delete                     |nvim_tree.api.fs.remove()|
+`D`               Trash                      |nvim_tree.api.fs.trash()|
 `E`               Expand All                 |nvim_tree.api.tree.expand_all()|
-`e`               Rename: Basename           |nvim-tree-api.fs.rename_basename()|
-`]e`              Next Diagnostic            |nvim-tree-api.node.navigate.diagnostics.next()|
-`[e`              Prev Diagnostic            |nvim-tree-api.node.navigate.diagnostics.prev()|
-`F`               Live Filter: Clear         |nvim-tree-api.live_filter.clear()|
-`f`               Live Filter: Start         |nvim-tree-api.live_filter.start()|
+`e`               Rename: Basename           |nvim_tree.api.fs.rename_basename()|
+`]e`              Next Diagnostic            |nvim_tree.api.node.navigate.diagnostics.next()|
+`[e`              Prev Diagnostic            |nvim_tree.api.node.navigate.diagnostics.prev()|
+`F`               Live Filter: Clear         |nvim_tree.api.filter.live_filter.clear()|
+`f`               Live Filter: Start         |nvim_tree.api.filter.live_filter.start()|
 `g?`              Help                       |nvim_tree.api.tree.toggle_help()|
-`gy`              Copy Absolute Path         |nvim-tree-api.fs.copy.absolute_path()|
-`ge`              Copy Basename              |nvim-tree-api.fs.copy.basename()|
+`gy`              Copy Absolute Path         |nvim_tree.api.fs.copy.absolute_path()|
+`ge`              Copy Basename              |nvim_tree.api.fs.copy.basename()|
 `H`               Toggle Filter: Dotfiles    |nvim_tree.api.tree.toggle_hidden_filter()|
 `I`               Toggle Filter: Git Ignore  |nvim_tree.api.tree.toggle_gitignore_filter()|
-`J`               Last Sibling               |nvim-tree-api.node.navigate.sibling.last()|
-`K`               First Sibling              |nvim-tree-api.node.navigate.sibling.first()|
-`L`               Toggle Group Empty         |nvim-tree-api.node.open.toggle_group_empty()|
+`J`               Last Sibling               |nvim_tree.api.node.navigate.sibling.last()|
+`K`               First Sibling              |nvim_tree.api.node.navigate.sibling.first()|
+`L`               Toggle Group Empty         |nvim_tree.api.node.open.toggle_group_empty()|
 `M`               Toggle Filter: No Bookmark |nvim_tree.api.tree.toggle_no_bookmark_filter()|
-`m`               Toggle Bookmark            |nvim-tree-api.marks.toggle()|
-`o`               Open                       |nvim-tree-api.node.open.edit()|
-`O`               Open: No Window Picker     |nvim-tree-api.node.open.no_window_picker()|
-`p`               Paste                      |nvim-tree-api.fs.paste()|
-`P`               Parent Directory           |nvim-tree-api.node.navigate.parent()|
+`m`               Toggle Bookmark            |nvim_tree.api.marks.toggle()|
+`o`               Open                       |nvim_tree.api.node.open.edit()|
+`O`               Open: No Window Picker     |nvim_tree.api.node.open.no_window_picker()|
+`p`               Paste                      |nvim_tree.api.fs.paste()|
+`P`               Parent Directory           |nvim_tree.api.node.navigate.parent()|
 `q`               Close                      |nvim_tree.api.tree.close()|
-`r`               Rename                     |nvim-tree-api.fs.rename()|
+`r`               Rename                     |nvim_tree.api.fs.rename()|
 `R`               Refresh                    |nvim_tree.api.tree.reload()|
-`s`               Run System                 |nvim-tree-api.node.run.system()|
+`s`               Run System                 |nvim_tree.api.node.run.system()|
 `S`               Search                     |nvim_tree.api.tree.search_node()|
-`u`               Rename: Full Path          |nvim-tree-api.fs.rename_full()|
+`u`               Rename: Full Path          |nvim_tree.api.fs.rename_full()|
 `U`               Toggle Filter: Hidden      |nvim_tree.api.tree.toggle_custom_filter()|
 `W`               Collapse All               |nvim_tree.api.tree.collapse_all()|
-`x`               Cut                        |nvim-tree-api.fs.cut()|
-`y`               Copy Name                  |nvim-tree-api.fs.copy.filename()|
-`Y`               Copy Relative Path         |nvim-tree-api.fs.copy.relative_path()|
-`<2-LeftMouse>`   Open                       |nvim-tree-api.node.open.edit()|
+`x`               Cut                        |nvim_tree.api.fs.cut()|
+`y`               Copy Name                  |nvim_tree.api.fs.copy.filename()|
+`Y`               Copy Relative Path         |nvim_tree.api.fs.copy.relative_path()|
+`<2-LeftMouse>`   Open                       |nvim_tree.api.node.open.edit()|
 `<2-RightMouse>`  CD                         |nvim_tree.api.tree.change_root_to_node()|
 
 ==============================================================================
 Quickstart: Custom Mappings             *nvim-tree-quickstart-custom-mappings*
 
+
+
+
+TODO #3088 remove dummy tags once entire API has been migrated
+
+*nvim_tree.api.fs.copy.absolute_path()*
+*nvim_tree.api.fs.copy.basename()*
+*nvim_tree.api.fs.copy.filename()*
+*nvim_tree.api.fs.copy.node()*
+*nvim_tree.api.fs.copy.relative_path()*
+*nvim_tree.api.fs.create()*
+*nvim_tree.api.fs.cut()*
+*nvim_tree.api.fs.paste()*
+*nvim_tree.api.fs.remove()*
+*nvim_tree.api.fs.rename()*
+*nvim_tree.api.fs.rename_basename()*
+*nvim_tree.api.fs.rename_full()*
+*nvim_tree.api.fs.rename_sub()*
+*nvim_tree.api.fs.trash()*
+*nvim_tree.api.marks.bulk.delete()*
+*nvim_tree.api.marks.bulk.move()*
+*nvim_tree.api.marks.bulk.trash()*
+*nvim_tree.api.marks.toggle()*
+*nvim_tree.api.node.navigate.diagnostics.next()*
+*nvim_tree.api.node.navigate.diagnostics.prev()*
+*nvim_tree.api.node.navigate.git.next()*
+*nvim_tree.api.node.navigate.git.prev()*
+*nvim_tree.api.node.navigate.parent()*
+*nvim_tree.api.node.navigate.parent_close()*
+*nvim_tree.api.node.navigate.sibling.first()*
+*nvim_tree.api.node.navigate.sibling.last()*
+*nvim_tree.api.node.navigate.sibling.next()*
+*nvim_tree.api.node.navigate.sibling.prev()*
+*nvim_tree.api.node.open.edit()*
+*nvim_tree.api.node.open.horizontal()*
+*nvim_tree.api.node.open.no_window_picker()*
+*nvim_tree.api.node.open.preview()*
+*nvim_tree.api.node.open.replace_tree_buffer()*
+*nvim_tree.api.node.open.tab()*
+*nvim_tree.api.node.open.toggle_group_empty()*
+*nvim_tree.api.node.open.vertical()*
+*nvim_tree.api.node.run.cmd()*
+*nvim_tree.api.node.run.system()*
+*nvim_tree.api.node.show_info_popup()*
+
+
+
+
 |nvim-tree-mappings-default| are applied by default however you may customise
 via |nvim_tree.Config| {on_attach} e.g. >lua
 
@@ -1208,8 +1256,8 @@ You are encouraged to copy these to your {on_attach} function. >lua
   vim.keymap.set("n", "e",              api.fs.rename_basename,             opts("Rename: Basename"))
   vim.keymap.set("n", "]e",             api.node.navigate.diagnostics.next, opts("Next Diagnostic"))
   vim.keymap.set("n", "[e",             api.node.navigate.diagnostics.prev, opts("Prev Diagnostic"))
-  vim.keymap.set("n", "F",              api.live_filter.clear,              opts("Live Filter: Clear"))
-  vim.keymap.set("n", "f",              api.live_filter.start,              opts("Live Filter: Start"))
+  vim.keymap.set("n", "F",              api.filter.live_filter.clear,       opts("Live Filter: Clear"))
+  vim.keymap.set("n", "f",              api.filter.live_filter.start,       opts("Live Filter: Start"))
   vim.keymap.set("n", "g?",             api.tree.toggle_help,               opts("Help"))
   vim.keymap.set("n", "gy",             api.fs.copy.absolute_path,          opts("Copy Absolute Path"))
   vim.keymap.set("n", "ge",             api.fs.copy.basename,               opts("Copy Basename"))
@@ -2849,6 +2897,17 @@ Class: Config.Log                                       *nvim-tree-config-log*
 
 
 
+==============================================================================
+Lua module: nvim_tree.api.filter                        *nvim-tree-api-filter*
+
+live_filter.clear()                 *nvim_tree.api.filter.live_filter.clear()*
+    Exit live filter mode.
+
+live_filter.start()                 *nvim_tree.api.filter.live_filter.start()*
+    Enter live filter mode. Opens an input window with |filetype|
+    `NvimTreeFilter`
+
+
 ==============================================================================
 Lua module: nvim_tree.api.map                              *nvim-tree-api-map*
 
diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index 4379ef0b723..99db98987bd 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -350,8 +350,17 @@ Api.git.reload = wrap_explorer("reload_git")
 Api.events.subscribe = events.subscribe
 Api.events.Event = events.Event
 
-Api.live_filter.start = wrap_explorer_member("live_filter", "start_filtering")
-Api.live_filter.clear = wrap_explorer_member("live_filter", "clear_filter")
+function Api.hydrate_filter(filter)
+  Api.filter = filter
+
+Api.filter.live_filter.start = wrap_explorer_member("live_filter", "start_filtering")
+Api.filter.live_filter.clear = wrap_explorer_member("live_filter", "clear_filter")
+
+-- TODO #3088 legacy mappings have to go somewhere
+Api.live_filter.start = filter.live_filter.start
+Api.live_filter.clear = filter.live_filter.clear
+
+end
 
 Api.marks.get = wrap_node(wrap_explorer_member("marks", "get"))
 Api.marks.list = wrap_explorer_member("marks", "list")
@@ -371,6 +380,7 @@ Api.map.get_keymap = wrap(keymap.get_keymap)
 Api.map.get_keymap_default = wrap(keymap.get_keymap_default)
 Api.map.default_on_attach = keymap.default_on_attach
 
+-- TODO #3088 legacy mappings have to go somewhere
 Api.config.mappings.get_keymap = Api.map.get_keymap
 Api.config.mappings.get_keymap_default = Api.map.get_keymap_default
 Api.config.mappings.default_on_attach = Api.map.default_on_attach
diff --git a/lua/nvim-tree/api/filter.lua b/lua/nvim-tree/api/filter.lua
new file mode 100644
index 00000000000..b52ffd39460
--- /dev/null
+++ b/lua/nvim-tree/api/filter.lua
@@ -0,0 +1,17 @@
+---@meta
+local nvim_tree = { api = { filter = { live_filter = {} } } }
+
+
+
+---Enter live filter mode. Opens an input window with [filetype] `NvimTreeFilter`
+function nvim_tree.api.filter.live_filter.start() end
+
+
+---Exit live filter mode.
+function nvim_tree.api.filter.live_filter.clear() end
+
+
+
+require("nvim-tree.api").hydrate_filter(nvim_tree.api.filter)
+
+return nvim_tree.api.filter
diff --git a/lua/nvim-tree/api/init.lua b/lua/nvim-tree/api/init.lua
index 03b4095adc3..ac696d56e45 100644
--- a/lua/nvim-tree/api/init.lua
+++ b/lua/nvim-tree/api/init.lua
@@ -1,4 +1,5 @@
 return {
-  config = require("nvim-tree.api.map"),
+  filter = require("nvim-tree.api.filter"),
+  map = require("nvim-tree.api.map"),
   tree = require("nvim-tree.api.tree"),
 }
diff --git a/lua/nvim-tree/keymap.lua b/lua/nvim-tree/keymap.lua
index c3373741f22..1758b7f9bdc 100644
--- a/lua/nvim-tree/keymap.lua
+++ b/lua/nvim-tree/keymap.lua
@@ -74,8 +74,8 @@ function M.default_on_attach(bufnr)
   vim.keymap.set("n", "e",              api.fs.rename_basename,             opts("Rename: Basename"))
   vim.keymap.set("n", "]e",             api.node.navigate.diagnostics.next, opts("Next Diagnostic"))
   vim.keymap.set("n", "[e",             api.node.navigate.diagnostics.prev, opts("Prev Diagnostic"))
-  vim.keymap.set("n", "F",              api.live_filter.clear,              opts("Live Filter: Clear"))
-  vim.keymap.set("n", "f",              api.live_filter.start,              opts("Live Filter: Start"))
+  vim.keymap.set("n", "F",              api.filter.live_filter.clear,       opts("Live Filter: Clear"))
+  vim.keymap.set("n", "f",              api.filter.live_filter.start,       opts("Live Filter: Start"))
   vim.keymap.set("n", "g?",             api.tree.toggle_help,               opts("Help"))
   vim.keymap.set("n", "gy",             api.fs.copy.absolute_path,          opts("Copy Absolute Path"))
   vim.keymap.set("n", "ge",             api.fs.copy.basename,               opts("Copy Basename"))
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index 0e9b52c255a..61187318414 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -31,6 +31,7 @@ local modules = {
   { helptag = "nvim-tree-config-experimental",        title = "Class: Config.Experimental",       path = "./lua/nvim_tree/_meta/config/experimental.lua", },
   { helptag = "nvim-tree-config-log",                 title = "Class: Config.Log",                path = "./lua/nvim_tree/_meta/config/log.lua", },
 
+  { helptag = "nvim-tree-api-filter",                 title = "Lua module: nvim_tree.api.filter", path = "./lua/nvim_tree/api/filter.lua", },
   { helptag = "nvim-tree-api-map",                    title = "Lua module: nvim_tree.api.map",    path = "./lua/nvim_tree/api/map.lua", },
   { helptag = "nvim-tree-api-tree",                   title = "Lua module: nvim_tree.api.tree",   path = "./lua/nvim_tree/api/tree.lua", },
 }
@@ -64,13 +65,13 @@ local config = {
     section_fmt = function(name)
       print(string.format("section_fmt name=%s", name))
       return modules_by_section[name] and modules_by_section[name].title or
-      error(string.format("unknown module %s passed to section_fmt", name))
+        error(string.format("unknown module %s passed to section_fmt", name))
     end,
 
     helptag_fmt = function(name)
       print(string.format("helptag_fmt name=%s", name))
       return modules_by_section[name] and modules_by_section[name].helptag or
-      error(string.format("unknown module %s passed to helptag_fmt", name))
+        error(string.format("unknown module %s passed to helptag_fmt", name))
     end,
 
     -- optional, no default xform
diff --git a/scripts/help-update.sh b/scripts/help-update.sh
index a2d223817ed..5326b7fda10 100755
--- a/scripts/help-update.sh
+++ b/scripts/help-update.sh
@@ -37,7 +37,7 @@ sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/DEFAULT_ON_ATTACH.lua
 
 # help human
 echo > /tmp/DEFAULT_ON_ATTACH.help
-sed -E "s/^ *vim.keymap.set\(\"n\", \"(.*)\",.*api(.*),.*opts\(\"(.*)\".*$/'\`\1\`' '\3' '|nvim-tree-api\2()|'/g
+sed -E "s/^ *vim.keymap.set\(\"n\", \"(.*)\",.*api(.*),.*opts\(\"(.*)\".*$/'\`\1\`' '\3' '|nvim_tree.api\2()|'/g
 " /tmp/DEFAULT_ON_ATTACH.lua | while read -r line
 do
 	eval "printf '%-17.17s %-26.26s %s\n' ${line}" >> /tmp/DEFAULT_ON_ATTACH.help

From 2201bb08daa431564ff6e4fccfed90b7d62a3669 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sun, 18 Jan 2026 11:56:52 +1100
Subject: [PATCH 089/170] docs(#3088): move api.git into api.tree

---
 doc/nvim-tree-lua.txt      |   8 ++
 lua/nvim-tree/api.lua      |  15 ++--
 lua/nvim-tree/api/tree.lua | 156 +++++++++++++++++--------------------
 3 files changed, 89 insertions(+), 90 deletions(-)

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 12f8e1a2302..09b2634499e 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -1843,6 +1843,11 @@ continue to be available.
 `api.config.mappings.get_keymap_default`  |nvim_tree.api.map.get_keymap_default()|
 `api.config.mappings.default_on_attach`   |nvim_tree.api.map.default_on_attach()|
 
+`api.git.reload`                          |nvim_tree.api.tree.reload_git()|
+
+`api.live_filter.start`                   |nvim_tree.api.filter.live_filter.start()|
+`api.live_filter.clear`                   |nvim_tree.api.filter.live_filter.clear()|
+
 ==============================================================================
 Legacy: Highlight                                 *nvim-tree-legacy-highlight*
 
@@ -3059,6 +3064,9 @@ open({opts})                                       *nvim_tree.api.tree.open()*
 reload()                                         *nvim_tree.api.tree.reload()*
     Refresh the tree. Does nothing if closed.
 
+reload_git()                                 *nvim_tree.api.tree.reload_git()*
+    Update the git status of the entire tree.
+
 resize({opts})                                   *nvim_tree.api.tree.resize()*
     Resize the tree, persisting the new size. Resets to
     |nvim_tree.Config.View| {width} when no {opts} provided.
diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index 99db98987bd..8c67725ec59 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -35,9 +35,9 @@ local Api = {
   fs = {
     copy = {},
   },
-  git = {}, -- 1 collides with Config.Git - api.tree.reload_git
-  live_filter = {}, -- 2 collides with Config.LiveFilter -  api.filter
-  config = {-- collides with Config - api.mapping
+  git = {},
+  live_filter = {},
+  config = {
     mappings = {},
   },
   commands = {},
@@ -223,6 +223,11 @@ Api.tree.is_visible = wrap(view.is_visible)
 
 Api.tree.winid = wrap(view.winid)
 
+Api.tree.reload_git = wrap_explorer("reload_git")
+
+-- TODO #3088 legacy mappings have to go somewhere
+Api.git.reload = Api.tree.reload_git
+
 end
 
 Api.fs.create = wrap_node_or_nil(actions.fs.create_file.fn)
@@ -398,8 +403,4 @@ end)
 ---@type nvim_tree.api.decorator.UserDecorator
 Api.decorator.UserDecorator = UserDecorator --[[@as nvim_tree.api.decorator.UserDecorator]]
 
-
--- TODO #3088 legacy mappings have to go somewhere
-
-
 return Api
diff --git a/lua/nvim-tree/api/tree.lua b/lua/nvim-tree/api/tree.lua
index 77da44931cc..b441269020a 100644
--- a/lua/nvim-tree/api/tree.lua
+++ b/lua/nvim-tree/api/tree.lua
@@ -1,7 +1,13 @@
 ---@meta
 local nvim_tree = { api = { tree = {} } }
 
+-- TODO #3088 move expand/collapse into api.node
 
+---
+---Open the tree, focusing it if already open.
+---
+---@param opts? nvim_tree.api.tree.open.Opts optional
+function nvim_tree.api.tree.open(opts) end
 
 ---@class nvim_tree.api.tree.open.Opts
 ---@inlinedoc
@@ -24,12 +30,11 @@ local nvim_tree = { api = { tree = {} } }
 ---(default: false)
 ---@field update_root? boolean
 
----Open the tree, focusing it if already open.
 ---
----@param opts? nvim_tree.api.tree.open.Opts optional
-function nvim_tree.api.tree.open(opts) end
-
-
+---Open or close the tree.
+---
+---@param opts? nvim_tree.api.tree.toggle.Opts optional
+function nvim_tree.api.tree.toggle(opts) end
 
 ---@class nvim_tree.api.tree.toggle.Opts
 ---@inlinedoc
@@ -52,39 +57,40 @@ function nvim_tree.api.tree.open(opts) end
 ---(default: true)
 ---@field focus? boolean
 
----Open or close the tree.
 ---
----@param opts? nvim_tree.api.tree.toggle.Opts optional
-function nvim_tree.api.tree.toggle(opts) end
-
-
-
 ---Close the tree, affecting all tabs as per [nvim_tree.Config.Tab.Sync] {close}
 ---
 function nvim_tree.api.tree.close() end
 
-
+---
 ---Close the tree in this tab only.
 ---
 function nvim_tree.api.tree.close_in_this_tab() end
 
-
+---
 ---Close the tree in all tabs.
 ---
 function nvim_tree.api.tree.close_in_all_tabs() end
 
-
-
+---
 ---Focus the tree, opening it if necessary. Retained for compatibility, use [nvim_tree.api.tree.open()] with no arguments instead.
 ---
 function nvim_tree.api.tree.focus() end
 
-
+---
 ---Refresh the tree. Does nothing if closed.
 ---
 function nvim_tree.api.tree.reload() end
 
-
+---
+---Resize the tree, persisting the new size. Resets to [nvim_tree.Config.View] {width} when no {opts} provided.
+---
+---Only one option is supported, priority order: {width}, {absolute}, {relative}.
+---
+---{absolute} and {relative} do nothing when [nvim_tree.Config.View] {width} is a function.
+---
+---@param opts? nvim_tree.api.tree.resize.Opts optional
+function nvim_tree.api.tree.resize(opts) end
 
 ---@class nvim_tree.api.tree.resize.Opts
 ---@inlinedoc
@@ -98,47 +104,41 @@ function nvim_tree.api.tree.reload() end
 ---Increase or decrease the width.
 ---@field relative integer
 
----Resize the tree, persisting the new size. Resets to [nvim_tree.Config.View] {width} when no {opts} provided.
 ---
----Only one option is supported, priority order: {width}, {absolute}, {relative}.
----
----{absolute} and {relative} do nothing when [nvim_tree.Config.View] {width} is a function.
----@param opts? nvim_tree.api.tree.resize.Opts optional
-function nvim_tree.api.tree.resize(opts) end
-
-
-
 ---Change the tree's root to a path.
 ---
 ---@param path? string absolute or relative path.
 function nvim_tree.api.tree.change_root(path) end
 
-
-
+---
 ---Change the tree's root to a folder node or the parent of a file node.
 ---
 ---@param node nvim_tree.api.Node directory or file
 function nvim_tree.api.tree.change_root_to_node(node) end
 
-
+---
 ---Change the tree's root to the parent of a node.
 ---
 ---@param node nvim_tree.api.Node directory or file
 function nvim_tree.api.tree.change_root_to_parent(node) end
 
-
+---
 ---Retrieve the currently focused node.
 ---
 ---@return nvim_tree.api.Node? nil if tree is not visible.
 function nvim_tree.api.tree.get_node_under_cursor() end
 
-
+---
 ---Retrieve a hierarchical list of all the nodes.
 ---
 ---@return nvim_tree.api.Node[]
 function nvim_tree.api.tree.get_nodes() end
 
-
+---
+---Find and focus a file or folder in the tree. Finds current buffer unless otherwise specified.
+---
+---@param opts? nvim_tree.api.tree.find_file.Opts optional
+function nvim_tree.api.tree.find_file(opts) end
 
 ---@class nvim_tree.api.tree.find_file.Opts
 ---@inlinedoc
@@ -165,18 +165,16 @@ function nvim_tree.api.tree.get_nodes() end
 ---(default: false)
 ---@field focus? boolean
 
----Find and focus a file or folder in the tree. Finds current buffer unless otherwise specified.
 ---
----@param opts? nvim_tree.api.tree.find_file.Opts optional
-function nvim_tree.api.tree.find_file(opts) end
-
-
-
 ---Open the search dialogue.
 ---
 function nvim_tree.api.tree.search_node() end
 
-
+---
+---Collapse the tree.
+---
+---@param opts? nvim_tree.api.tree.collapse.Opts optional
+function nvim_tree.api.tree.collapse_all(opts) end
 
 ---@class nvim_tree.api.tree.collapse.Opts
 ---@inlinedoc
@@ -185,14 +183,12 @@ function nvim_tree.api.tree.search_node() end
 ---(default: false)
 ---@field keep_buffers? boolean
 
----Collapse the tree.
 ---
----@param opts? nvim_tree.api.tree.collapse.Opts optional
-function nvim_tree.api.tree.collapse_all(opts) end
-
-
-
---- TODO #3088 move expand/collapse into api.node
+---Recursively expand all nodes under the tree root or specified folder.
+---
+---@param node? nvim_tree.api.Node directory
+---@param opts? nvim_tree.api.tree.expand.Opts optional
+function nvim_tree.api.tree.expand_all(node, opts) end
 
 ---@class nvim_tree.api.tree.expand.Opts
 ---@inlinedoc
@@ -200,54 +196,47 @@ function nvim_tree.api.tree.collapse_all(opts) end
 ---Return `true` if `node` should be expanded. `expansion_count` is the total number of folders expanded.
 ---@field expand_until? fun(expansion_count: integer, node: Node): boolean
 
----Recursively expand all nodes under the tree root or specified folder.
----@param node? nvim_tree.api.Node directory
----@param opts? nvim_tree.api.tree.expand.Opts optional
-function nvim_tree.api.tree.expand_all(node, opts) end
-
-
-
+---
 ---Toggle [nvim_tree.Config.Filters] {enable} all filters.
+---
 function nvim_tree.api.tree.toggle_enable_filters() end
 
-
-
+---
 ---Toggle [nvim_tree.Config.Filters] {git_ignored} filter.
+---
 function nvim_tree.api.tree.toggle_gitignore_filter() end
 
-
-
+---
 ---Toggle [nvim_tree.Config.Filters] {dotfiles} filter.
+---
 function nvim_tree.api.tree.toggle_hidden_filter() end
 
-
-
+---
 ---Toggle [nvim_tree.Config.Filters] {git_clean} filter.
+---
 function nvim_tree.api.tree.toggle_git_clean_filter() end
 
-
-
+---
 ---Toggle [nvim_tree.Config.Filters] {no_buffer} filter.
+---
 function nvim_tree.api.tree.toggle_no_buffer_filter() end
 
-
-
+---
 ---Toggle [nvim_tree.Config.Filters] {no_bookmark} filter.
+---
 function nvim_tree.api.tree.toggle_no_bookmark_filter() end
 
-
-
+---
 ---Toggle [nvim_tree.Config.Filters] {custom} filter.
+---
 function nvim_tree.api.tree.toggle_custom_filter() end
 
-
-
-
+---
 ---Toggle help view.
+---
 function nvim_tree.api.tree.toggle_help() end
 
-
-
+---
 ---Checks if a buffer is an nvim-tree.
 ---
 ---@param bufnr? integer 0 or nil for current buffer.
@@ -255,7 +244,12 @@ function nvim_tree.api.tree.toggle_help() end
 ---@return boolean
 function nvim_tree.api.tree.is_tree_buf(bufnr) end
 
-
+---
+---Checks if nvim-tree is visible on the current, specified or any tab.
+---
+---@param opts? nvim_tree.api.tree.is_visible.Opts optional
+---@return boolean
+function nvim_tree.api.tree.is_visible(opts) end
 
 ---@class nvim_tree.api.tree.is_visible.Opts
 ---@inlinedoc
@@ -267,13 +261,12 @@ function nvim_tree.api.tree.is_tree_buf(bufnr) end
 ---(default: false)
 ---@field any_tabpage? boolean
 
----Checks if nvim-tree is visible on the current, specified or any tab.
 ---
----@param opts? nvim_tree.api.tree.is_visible.Opts optional
----@return boolean
-function nvim_tree.api.tree.is_visible(opts) end
-
-
+---Retrieve the window of the open tree.
+---
+---@param opts? nvim_tree.api.tree.winid.Opts optional
+---@return integer? [window-ID], nil if tree is not visible.
+function nvim_tree.api.tree.winid(opts) end
 
 ---@class nvim_tree.api.tree.winid.Opts
 ---@inlinedoc
@@ -281,13 +274,10 @@ function nvim_tree.api.tree.is_visible(opts) end
 ---[tab-ID] 0 or nil for current.
 ---@field tabpage? integer
 
----Retrieve the window of the open tree.
 ---
----@param opts? nvim_tree.api.tree.winid.Opts optional
----@return integer? [window-ID], nil if tree is not visible.
-function nvim_tree.api.tree.winid(opts) end
-
-
+---Update the git status of the entire tree.
+---
+function nvim_tree.api.tree.reload_git() end
 
 require("nvim-tree.api").hydrate_tree(nvim_tree.api.tree)
 

From 052d39f41b9a5ce089444e9f6b381796c94bcb42 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sun, 18 Jan 2026 12:27:39 +1100
Subject: [PATCH 090/170] docs(#3088): extract api/health.lua, tidy formatting

---
 lua/nvim-tree/api.lua         |  9 ++++++++-
 lua/nvim-tree/api/filter.lua  |  9 ++++-----
 lua/nvim-tree/api/health.lua  | 13 +++++++++++++
 lua/nvim-tree/api/init.lua    |  1 +
 lua/nvim-tree/api/map.lua     | 11 +++--------
 lua/nvim-tree/commands.lua    |  2 +-
 scripts/gen_vimdoc_config.lua |  1 +
 7 files changed, 31 insertions(+), 15 deletions(-)
 create mode 100644 lua/nvim-tree/api/health.lua

diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index 8c67725ec59..a6ecec09ac1 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -392,7 +392,14 @@ Api.config.mappings.default_on_attach = Api.map.default_on_attach
 
 end
 
-Api.diagnostics.hi_test = wrap(appearance_hi_test)
+function Api.hydrate_health(health)
+  Api.health = health
+
+Api.health.hi_test = wrap(appearance_hi_test)
+
+-- TODO #3088 legacy mappings have to go somewhere
+Api.diagnostics.hi_test = Api.health.hi_test
+end
 
 Api.commands.get = wrap(function()
   return require("nvim-tree.commands").get()
diff --git a/lua/nvim-tree/api/filter.lua b/lua/nvim-tree/api/filter.lua
index b52ffd39460..4aa6d71369b 100644
--- a/lua/nvim-tree/api/filter.lua
+++ b/lua/nvim-tree/api/filter.lua
@@ -1,17 +1,16 @@
 ---@meta
 local nvim_tree = { api = { filter = { live_filter = {} } } }
 
-
-
+---
 ---Enter live filter mode. Opens an input window with [filetype] `NvimTreeFilter`
+---
 function nvim_tree.api.filter.live_filter.start() end
 
-
+---
 ---Exit live filter mode.
+---
 function nvim_tree.api.filter.live_filter.clear() end
 
-
-
 require("nvim-tree.api").hydrate_filter(nvim_tree.api.filter)
 
 return nvim_tree.api.filter
diff --git a/lua/nvim-tree/api/health.lua b/lua/nvim-tree/api/health.lua
new file mode 100644
index 00000000000..dbd90c89d1f
--- /dev/null
+++ b/lua/nvim-tree/api/health.lua
@@ -0,0 +1,13 @@
+---@meta
+local nvim_tree = { api = { health = {} } }
+
+---
+---Open a new buffer displaying all nvim-tree highlight groups, their link chain and concrete definition.
+---
+---Similar to `:so $VIMRUNTIME/syntax/hitest.vim` as per |:highlight|
+---
+function nvim_tree.api.health.hi_test() end
+
+require("nvim-tree.api").hydrate_health(nvim_tree.api.health)
+
+return nvim_tree.api.health
diff --git a/lua/nvim-tree/api/init.lua b/lua/nvim-tree/api/init.lua
index ac696d56e45..b8773828c4b 100644
--- a/lua/nvim-tree/api/init.lua
+++ b/lua/nvim-tree/api/init.lua
@@ -1,5 +1,6 @@
 return {
   filter = require("nvim-tree.api.filter"),
+  health = require("nvim-tree.api.health"),
   map = require("nvim-tree.api.map"),
   tree = require("nvim-tree.api.tree"),
 }
diff --git a/lua/nvim-tree/api/map.lua b/lua/nvim-tree/api/map.lua
index 24b1d909a53..4f47541a0a1 100644
--- a/lua/nvim-tree/api/map.lua
+++ b/lua/nvim-tree/api/map.lua
@@ -1,29 +1,24 @@
 ---@meta
 local nvim_tree = { api = { map = {} } }
 
-
-
+---
 ---Retrieve all buffer local mappings for nvim-tree. These are the mappings that are applied by [nvim_tree.Config] {on_attach}, which may include default mappings.
 ---
 ---@return vim.api.keyset.get_keymap[]
 function nvim_tree.api.map.get_keymap() end
 
-
-
+---
 --- Retrieves the buffer local mappings for nvim-tree that are applied by [nvim_tree.api.map.default_on_attach()]
 ---
 ---@return vim.api.keyset.get_keymap[]
 function nvim_tree.api.map.get_keymap_default() end
 
-
-
+---
 ---Apply all [nvim-tree-mappings-default]. Call from your [nvim_tree.Config] {on_attach}.
 ---
 ---@param bufnr integer use the `bufnr` passed to {on_attach}
 function nvim_tree.api.map.default_on_attach(bufnr) end
 
-
-
 require("nvim-tree.api").hydrate_map(nvim_tree.api.map)
 
 return nvim_tree.api.map
diff --git a/lua/nvim-tree/commands.lua b/lua/nvim-tree/commands.lua
index 8158465a4c7..3be807ac2d0 100644
--- a/lua/nvim-tree/commands.lua
+++ b/lua/nvim-tree/commands.lua
@@ -137,7 +137,7 @@ local CMDS = {
       desc = "nvim-tree: highlight test",
     },
     command = function()
-      require("nvim-tree.api").diagnostics.hi_test()
+      require("nvim-tree.api").health.hi_test()
     end,
   },
 }
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index 61187318414..761d8689668 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -32,6 +32,7 @@ local modules = {
   { helptag = "nvim-tree-config-log",                 title = "Class: Config.Log",                path = "./lua/nvim_tree/_meta/config/log.lua", },
 
   { helptag = "nvim-tree-api-filter",                 title = "Lua module: nvim_tree.api.filter", path = "./lua/nvim_tree/api/filter.lua", },
+  { helptag = "nvim-tree-api-health",                 title = "Lua module: nvim_tree.api.health", path = "./lua/nvim_tree/api/health.lua", },
   { helptag = "nvim-tree-api-map",                    title = "Lua module: nvim_tree.api.map",    path = "./lua/nvim_tree/api/map.lua", },
   { helptag = "nvim-tree-api-tree",                   title = "Lua module: nvim_tree.api.tree",   path = "./lua/nvim_tree/api/tree.lua", },
 }

From fdba90055773765d9118af485de490739a0773fc Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sun, 18 Jan 2026 12:27:57 +1100
Subject: [PATCH 091/170] docs(#3088): extract api/health.lua, tidy formatting

---
 doc/nvim-tree-lua.txt | 27 ++++++++++++++++-----------
 1 file changed, 16 insertions(+), 11 deletions(-)

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 09b2634499e..5bffe57afa2 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -251,6 +251,8 @@ See |nvim-tree-highlight-groups| for details.
 ==============================================================================
 Commands                                                  *nvim-tree-commands*
 
+TODO #3088 clean up descriptions and render call as Lua.
+
 *:NvimTreeOpen*
 
     Opens the tree. See |nvim_tree.api.tree.open()|
@@ -346,9 +348,9 @@ Commands                                                  *nvim-tree-commands*
 
     Show nvim-tree highlight groups similar to `:so $VIMRUNTIME/syntax/hitest.vim`
 
-    See |nvim-tree-api.diagnostics.hi_test()|
+    See |nvim_tree.api.health.hi_test()|
 
-    Calls: `api.diagnostics.hi_test()`
+    Calls: `api.health.hi_test()`
 
 ==============================================================================
 Setup                                                        *nvim-tree-setup*
@@ -1140,15 +1142,6 @@ commands.get()                                  *nvim-tree-api.commands.get()*
         • {command} (function)
         • {opts}    (table)
 
-==============================================================================
-API: Diagnostics                                   *nvim-tree-api.diagnostics*
-
-diagnostics.hi_test()                    *nvim-tree-api.diagnostics.hi_test()*
-    Open a new buffer displaying all nvim-tree highlight groups, their link
-    chain and concrete definition.
-
-    Similar to `:so $VIMRUNTIME/syntax/hitest.vim` as per |:highlight|
-
 ==============================================================================
 Mappings                                                  *nvim-tree-mappings*
 
@@ -1843,6 +1836,8 @@ continue to be available.
 `api.config.mappings.get_keymap_default`  |nvim_tree.api.map.get_keymap_default()|
 `api.config.mappings.default_on_attach`   |nvim_tree.api.map.default_on_attach()|
 
+`api.diagnostics.hi_test`                 |nvim_tree.api.health.hi_test()|
+
 `api.git.reload`                          |nvim_tree.api.tree.reload_git()|
 
 `api.live_filter.start`                   |nvim_tree.api.filter.live_filter.start()|
@@ -2913,6 +2908,16 @@ live_filter.start()                 *nvim_tree.api.filter.live_filter.start()*
     `NvimTreeFilter`
 
 
+==============================================================================
+Lua module: nvim_tree.api.health                        *nvim-tree-api-health*
+
+hi_test()                                     *nvim_tree.api.health.hi_test()*
+    Open a new buffer displaying all nvim-tree highlight groups, their link
+    chain and concrete definition.
+
+    Similar to `:so $VIMRUNTIME/syntax/hitest.vim` as per |:highlight|
+
+
 ==============================================================================
 Lua module: nvim_tree.api.map                              *nvim-tree-api-map*
 

From cdf1148195d4d0e3df1145b6e6ffb4bbc8bb1c76 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sun, 18 Jan 2026 13:11:21 +1100
Subject: [PATCH 092/170] docs(#3088): remove command descriptions, show lua,
 link to api

---
 doc/nvim-tree-lua.txt | 141 ++++++++++++++++--------------------------
 1 file changed, 55 insertions(+), 86 deletions(-)

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 5bffe57afa2..74e8caac28b 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -251,106 +251,75 @@ See |nvim-tree-highlight-groups| for details.
 ==============================================================================
 Commands                                                  *nvim-tree-commands*
 
-TODO #3088 clean up descriptions and render call as Lua.
+Commands may be executed with a `` (`!`) or take a `` string argument.
 
-*:NvimTreeOpen*
+*:NvimTreeOpen*                            |nvim_tree.api.tree.open()| >lua
 
-    Opens the tree. See |nvim_tree.api.tree.open()|
-
-    Calls: `api.tree.open({ path = "" })`
-
-*:NvimTreeClose*
-
-    Closes the tree. See |nvim_tree.api.tree.close()|
-
-    Calls: `api.tree.close()`
-
-*:NvimTreeToggle*
-
-    Open or close the tree. See |nvim_tree.api.tree.toggle()|
-
-    Calls: `api.tree.toggle({ path = "", find_file = false, update_root = false, focus = true, })`
-
-*:NvimTreeFocus*
-
-    Open the tree if it is closed, and then focus on the tree.
-
-    See |nvim_tree.api.tree.open()|
-
-    Calls: `api.tree.open()`
-
-*:NvimTreeRefresh*
-
-    Refresh the tree. See |nvim_tree.api.tree.reload()|
-
-    Calls: `api.tree.reload()`
-
-*:NvimTreeFindFile*
-
-    The command will change the cursor in the tree for the current bufname.
-
-    It will also open the leafs of the tree leading to the file in the buffer
-    (if you opened a file with something else than the NvimTree, like `fzf` or
-    `:split`)
-
-    Invoke with a bang `:NvimTreeFindFile!` to update the root.
-
-    See |nvim_tree.api.tree.find_file()|
-
-    Calls: `api.tree.find_file({ update_root = , open = true, focus = true, })`
+  require("nvim-tree.api").tree.open({
+    path = ""
+  })
+<
+*:NvimTreeClose*                           |nvim_tree.api.tree.close()| >lua
 
-*:NvimTreeFindFileToggle*
+  require("nvim-tree.api").tree.close()
+<
+*:NvimTreeToggle*                          |nvim_tree.api.tree.toggle()| >lua
 
-    close the tree or change the cursor in the tree for the current bufname,
-    similar to combination of |:NvimTreeToggle| and |:NvimTreeFindFile|. Takes an
-    optional path argument.
+  require("nvim-tree.api").tree.toggle({
+    path = "",
+    find_file = false,
+    update_root = false,
+    focus = true,
+  })
+<
+*:NvimTreeFocus*                           |nvim_tree.api.tree.open()| >lua
 
-    Invoke with a bang `:NvimTreeFindFileToggle!` to update the root.
+  require("nvim-tree.api").tree.open()
+<
+*:NvimTreeRefresh*                         |nvim_tree.api.tree.reload()| >lua
 
-    See |nvim_tree.api.tree.toggle()|
+  require("nvim-tree.api").tree.reload()
+<
+*:NvimTreeFindFile*                        |nvim_tree.api.tree.find_file()| >lua
 
-    Calls: `api.tree.toggle({ path = "", update_root = , find_file = true, focus = true, })`
+  require("nvim-tree.api").tree.find_file({
+    open = true,
+    update_root = "",
+    focus = true,
+  })
+<
+*:NvimTreeFindFileToggle*                  |nvim_tree.api.tree.toggle()| >lua
 
-*:NvimTreeClipboard*
+  require("nvim-tree.api").tree.toggle({
+    path = "",
+    find_file = true,
+    update_root = "",
+    focus = true,
+  })
+<
+*:NvimTreeClipboard*                       |nvim-tree-api.fs.print_clipboard()| >lua
 
-    Print clipboard content for both cut and copy
+  require("nvim-tree.api").fs.print_clipboard()
+<
+*:NvimTreeCollapse*                        |nvim_tree.api.tree.collapse_all()| >lua
 
-    See |nvim-tree-api.fs.print_clipboard()|
+  require("nvim-tree.api").tree.collapse_all({
+    keep_buffers = false
+  })
+<
+*:NvimTreeCollapseKeepBuffers*             |nvim_tree.api.tree.collapse_all()| >lua
 
-    Calls: `api.fs.print_clipboard()`
+  require("nvim-tree.api").tree.collapse_all({
+    keep_buffers = true
+  })
+<
+*:NvimTreeHiTest*                          |nvim_tree.api.health.hi_test()| >lua
 
+  require("nvim-tree.api").health.hi_test()
+<
 *:NvimTreeResize*
 
-    Resize the NvimTree window to the given size. Example: `:NvimTreeResize 50`
-    resizes the window to the width of 50. If the size starts with "+" or "-" it
-    adds or removes the given value to the current window width.
-    Example `:NvimTreeResize -20` removes the value 20 from the current width. And
-    `:NvimTreeResize +20` adds the value 20 to the current width.
-
-*:NvimTreeCollapse*
-
-    Collapses the nvim-tree recursively.
-
-    See |nvim_tree.api.tree.collapse_all()|
-
-    Calls: `api.tree.collapse_all({ keep_buffers = false })`
-
-*:NvimTreeCollapseKeepBuffers*
-
-    Collapses the nvim-tree recursively, but keep the directories open, which are
-    used in an open buffer.
-
-    See |nvim_tree.api.tree.collapse_all()|
-
-    Calls: `api.tree.collapse_all({ keep_buffers = true })`
-
-*:NvimTreeHiTest*
-
-    Show nvim-tree highlight groups similar to `:so $VIMRUNTIME/syntax/hitest.vim`
-
-    See |nvim_tree.api.health.hi_test()|
-
-    Calls: `api.health.hi_test()`
+Columns integer argument is absolute (e.g. `40`) or a delta (e.g. `-5`, `+5`)
 
 ==============================================================================
 Setup                                                        *nvim-tree-setup*

From 8169547aee405b7e08dbd5885043bc44db055187 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sun, 18 Jan 2026 13:37:16 +1100
Subject: [PATCH 093/170] docs(#3088): extract api/marks.lua

---
 doc/nvim-tree-lua.txt         | 48 +++++++++++++++++++++++++---
 lua/nvim-tree/api.lua         |  5 +++
 lua/nvim-tree/api/init.lua    |  1 +
 lua/nvim-tree/api/marks.lua   | 60 +++++++++++++++++++++++++++++++++++
 scripts/gen_vimdoc_config.lua |  1 +
 5 files changed, 111 insertions(+), 4 deletions(-)
 create mode 100644 lua/nvim-tree/api/marks.lua

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 74e8caac28b..5f73997e1ca 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -177,10 +177,6 @@ TODO #3088 remove dummy tags once entire API has been migrated
 *nvim_tree.api.fs.rename_full()*
 *nvim_tree.api.fs.rename_sub()*
 *nvim_tree.api.fs.trash()*
-*nvim_tree.api.marks.bulk.delete()*
-*nvim_tree.api.marks.bulk.move()*
-*nvim_tree.api.marks.bulk.trash()*
-*nvim_tree.api.marks.toggle()*
 *nvim_tree.api.node.navigate.diagnostics.next()*
 *nvim_tree.api.node.navigate.diagnostics.prev()*
 *nvim_tree.api.node.navigate.git.next()*
@@ -2913,6 +2909,50 @@ get_keymap_default()                  *nvim_tree.api.map.get_keymap_default()*
         (`vim.api.keyset.get_keymap[]`)
 
 
+==============================================================================
+Lua module: nvim_tree.api.marks                          *nvim-tree-api-marks*
+
+bulk.delete()                              *nvim_tree.api.marks.bulk.delete()*
+    Delete all marked, prompting if |nvim_tree.Config.UI.Confirm| {remove}
+
+bulk.move()                                  *nvim_tree.api.marks.bulk.move()*
+    Prompts for a directory to move all marked nodes into.
+
+bulk.trash()                                *nvim_tree.api.marks.bulk.trash()*
+    Delete all marked, prompting if |nvim_tree.Config.UI.Confirm| {trash}
+
+clear()                                          *nvim_tree.api.marks.clear()*
+    Clear all bookmarks.
+
+get()                                              *nvim_tree.api.marks.get()*
+    Return the node if it is bookmarked.
+
+    Return: ~
+        (`nvim_tree.api.Node?`)
+
+list()                                            *nvim_tree.api.marks.list()*
+    Retrieve all bookmarked nodes.
+
+    Return: ~
+        (`nvim_tree.api.Node[]`)
+
+navigate.next()                          *nvim_tree.api.marks.navigate.next()*
+    Navigate to the next marked node, wraps.
+
+navigate.prev()                          *nvim_tree.api.marks.navigate.prev()*
+    Navigate to the previous marked node, wraps.
+
+navigate.select()                      *nvim_tree.api.marks.navigate.select()*
+    Prompts for selection of a marked node, sorted by absolute paths. A folder
+    will be focused, a file will be opened.
+
+toggle({node})                                  *nvim_tree.api.marks.toggle()*
+    Toggle bookmark.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node`) file or directory
+
+
 ==============================================================================
 Lua module: nvim_tree.api.tree                            *nvim-tree-api-tree*
 
diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index a6ecec09ac1..14d322348c7 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -367,6 +367,9 @@ Api.live_filter.clear = filter.live_filter.clear
 
 end
 
+function Api.hydrate_marks(marks)
+  Api.marks = marks
+
 Api.marks.get = wrap_node(wrap_explorer_member("marks", "get"))
 Api.marks.list = wrap_explorer_member("marks", "list")
 Api.marks.toggle = wrap_node(wrap_explorer_member("marks", "toggle"))
@@ -378,6 +381,8 @@ Api.marks.navigate.next = wrap_explorer_member("marks", "navigate_next")
 Api.marks.navigate.prev = wrap_explorer_member("marks", "navigate_prev")
 Api.marks.navigate.select = wrap_explorer_member("marks", "navigate_select")
 
+end
+
 function Api.hydrate_map(map)
   Api.map = map
 
diff --git a/lua/nvim-tree/api/init.lua b/lua/nvim-tree/api/init.lua
index b8773828c4b..d2d9a71e5ef 100644
--- a/lua/nvim-tree/api/init.lua
+++ b/lua/nvim-tree/api/init.lua
@@ -2,5 +2,6 @@ return {
   filter = require("nvim-tree.api.filter"),
   health = require("nvim-tree.api.health"),
   map = require("nvim-tree.api.map"),
+  marks = require("nvim-tree.api.marks"),
   tree = require("nvim-tree.api.tree"),
 }
diff --git a/lua/nvim-tree/api/marks.lua b/lua/nvim-tree/api/marks.lua
new file mode 100644
index 00000000000..e852c3aeaf3
--- /dev/null
+++ b/lua/nvim-tree/api/marks.lua
@@ -0,0 +1,60 @@
+---@meta
+local nvim_tree = { api = { marks = { bulk = {}, navigate = {}, } } }
+
+---
+---Return the node if it is marked.
+---
+---@return nvim_tree.api.Node?
+function nvim_tree.api.marks.get() end
+
+---
+---Retrieve all marked nodes.
+---
+---@return nvim_tree.api.Node[]
+function nvim_tree.api.marks.list() end
+
+---
+---Toggle mark.
+---
+---@param node nvim_tree.api.Node file or directory
+function nvim_tree.api.marks.toggle(node) end
+
+---
+---Clear all marks.
+---
+function nvim_tree.api.marks.clear() end
+
+---
+---Delete all marked, prompting if [nvim_tree.Config.UI.Confirm] {remove}
+---
+function nvim_tree.api.marks.bulk.delete() end
+
+---
+---Delete all marked, prompting if [nvim_tree.Config.UI.Confirm] {trash}
+---
+function nvim_tree.api.marks.bulk.trash() end
+
+---
+---Prompts for a directory to move all marked nodes into.
+---
+function nvim_tree.api.marks.bulk.move() end
+
+---
+---Navigate to the next marked node, wraps.
+---
+function nvim_tree.api.marks.navigate.next() end
+
+---
+---Navigate to the previous marked node, wraps.
+---
+function nvim_tree.api.marks.navigate.prev() end
+
+---
+---Prompts for selection of a marked node, sorted by absolute paths.
+---A folder will be focused, a file will be opened.
+---
+function nvim_tree.api.marks.navigate.select() end
+
+require("nvim-tree.api").hydrate_marks(nvim_tree.api.marks)
+
+return nvim_tree.api.marks
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index 761d8689668..cf0da3200b9 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -34,6 +34,7 @@ local modules = {
   { helptag = "nvim-tree-api-filter",                 title = "Lua module: nvim_tree.api.filter", path = "./lua/nvim_tree/api/filter.lua", },
   { helptag = "nvim-tree-api-health",                 title = "Lua module: nvim_tree.api.health", path = "./lua/nvim_tree/api/health.lua", },
   { helptag = "nvim-tree-api-map",                    title = "Lua module: nvim_tree.api.map",    path = "./lua/nvim_tree/api/map.lua", },
+  { helptag = "nvim-tree-api-marks",                    title = "Lua module: nvim_tree.api.marks",    path = "./lua/nvim_tree/api/marks.lua", },
   { helptag = "nvim-tree-api-tree",                   title = "Lua module: nvim_tree.api.tree",   path = "./lua/nvim_tree/api/tree.lua", },
 }
 

From ac9424ab9bf07a34005e5852b94e473adfb40f1a Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sun, 18 Jan 2026 13:45:00 +1100
Subject: [PATCH 094/170] docs(#3088): remove completed legacy api.lua members

---
 doc/nvim-tree-lua.txt |  8 +++----
 lua/nvim-tree/api.lua | 49 ++++++++++++++++++++++++++-----------------
 2 files changed, 34 insertions(+), 23 deletions(-)

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 5f73997e1ca..f70abefc0d8 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -2922,16 +2922,16 @@ bulk.trash()                                *nvim_tree.api.marks.bulk.trash()*
     Delete all marked, prompting if |nvim_tree.Config.UI.Confirm| {trash}
 
 clear()                                          *nvim_tree.api.marks.clear()*
-    Clear all bookmarks.
+    Clear all marks.
 
 get()                                              *nvim_tree.api.marks.get()*
-    Return the node if it is bookmarked.
+    Return the node if it is marked.
 
     Return: ~
         (`nvim_tree.api.Node?`)
 
 list()                                            *nvim_tree.api.marks.list()*
-    Retrieve all bookmarked nodes.
+    Retrieve all marked nodes.
 
     Return: ~
         (`nvim_tree.api.Node[]`)
@@ -2947,7 +2947,7 @@ navigate.select()                      *nvim_tree.api.marks.navigate.select()*
     will be focused, a file will be opened.
 
 toggle({node})                                  *nvim_tree.api.marks.toggle()*
-    Toggle bookmark.
+    Toggle mark.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node`) file or directory
diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index 14d322348c7..735fc86d997 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -15,7 +15,7 @@ local RootNode = require("nvim-tree.node.root")
 local UserDecorator = require("nvim-tree.renderer.decorator.user")
 
 local Api = {
-  tree = {},
+  -- tree = {},
   node = {
     navigate = {
       sibling = {},
@@ -28,20 +28,20 @@ local Api = {
     buffer = {},
   },
   events = {},
-  marks = {
-    bulk = {},
-    navigate = {},
-  },
+  -- marks = {
+  --   bulk = {},
+  --   navigate = {},
+  -- },
   fs = {
     copy = {},
   },
-  git = {},
-  live_filter = {},
-  config = {
-    mappings = {},
-  },
+  -- git = {},
+  -- live_filter = {},
+  -- config = {
+  --   mappings = {},
+  -- },
   commands = {},
-  diagnostics = {},-- 1 collides with Config.Diagnostics -  api.health
+  -- diagnostics = {},
   decorator = {},
 }
 
@@ -226,7 +226,9 @@ Api.tree.winid = wrap(view.winid)
 Api.tree.reload_git = wrap_explorer("reload_git")
 
 -- TODO #3088 legacy mappings have to go somewhere
-Api.git.reload = Api.tree.reload_git
+Api.git = {
+  reload = Api.tree.reload_git
+}
 
 end
 
@@ -350,7 +352,7 @@ Api.node.buffer.wipe = wrap_node(function(node, opts)
   actions.node.buffer.wipe(node, opts)
 end)
 
-Api.git.reload = wrap_explorer("reload_git")
+-- Api.git.reload = wrap_explorer("reload_git")
 
 Api.events.subscribe = events.subscribe
 Api.events.Event = events.Event
@@ -362,8 +364,10 @@ Api.filter.live_filter.start = wrap_explorer_member("live_filter", "start_filter
 Api.filter.live_filter.clear = wrap_explorer_member("live_filter", "clear_filter")
 
 -- TODO #3088 legacy mappings have to go somewhere
-Api.live_filter.start = filter.live_filter.start
-Api.live_filter.clear = filter.live_filter.clear
+Api.live_filter = {
+  start = filter.live_filter.start,
+  clear = filter.live_filter.clear,
+}
 
 end
 
@@ -391,9 +395,13 @@ Api.map.get_keymap_default = wrap(keymap.get_keymap_default)
 Api.map.default_on_attach = keymap.default_on_attach
 
 -- TODO #3088 legacy mappings have to go somewhere
-Api.config.mappings.get_keymap = Api.map.get_keymap
-Api.config.mappings.get_keymap_default = Api.map.get_keymap_default
-Api.config.mappings.default_on_attach = Api.map.default_on_attach
+Api.config = {
+  mappings = {
+    get_keymap = Api.map.get_keymap,
+    get_keymap_default = Api.map.get_keymap_default,
+    default_on_attach = Api.map.default_on_attach,
+  }
+}
 
 end
 
@@ -403,7 +411,10 @@ function Api.hydrate_health(health)
 Api.health.hi_test = wrap(appearance_hi_test)
 
 -- TODO #3088 legacy mappings have to go somewhere
-Api.diagnostics.hi_test = Api.health.hi_test
+Api.diagnostics = {
+  hi_test = Api.health.hi_test,
+}
+
 end
 
 Api.commands.get = wrap(function()

From 3a08fa22d993495fb4942015a82ca22134b02c14 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sun, 18 Jan 2026 14:23:14 +1100
Subject: [PATCH 095/170] docs(#3088): extract api/events.lua

---
 doc/nvim-tree-lua.txt         | 11 +++++++++++
 lua/nvim-tree/api.lua         |  5 +++++
 lua/nvim-tree/api/events.lua  | 20 ++++++++++++++++++++
 lua/nvim-tree/api/init.lua    |  1 +
 scripts/gen_vimdoc_config.lua |  3 ++-
 5 files changed, 39 insertions(+), 1 deletion(-)
 create mode 100644 lua/nvim-tree/api/events.lua

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index f70abefc0d8..f001fd6354a 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -2862,6 +2862,17 @@ Class: Config.Log                                       *nvim-tree-config-log*
 
 
 
+==============================================================================
+Lua module: nvim_tree.api.events                        *nvim-tree-api-events*
+
+subscribe({event_type}, {callback})         *nvim_tree.api.events.subscribe()*
+    Register a handler for an event, see |nvim-tree-events|.
+
+    Parameters: ~
+      • {event_type}  (`string`) |nvim_tree_events_kind|
+      • {callback}    (`fun(payload: table?)`)
+
+
 ==============================================================================
 Lua module: nvim_tree.api.filter                        *nvim-tree-api-filter*
 
diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index 735fc86d997..325ad604ca9 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -354,9 +354,14 @@ end)
 
 -- Api.git.reload = wrap_explorer("reload_git")
 
+function Api.hydrate_events(ev)
+  Api.events = ev
+
 Api.events.subscribe = events.subscribe
 Api.events.Event = events.Event
 
+end
+
 function Api.hydrate_filter(filter)
   Api.filter = filter
 
diff --git a/lua/nvim-tree/api/events.lua b/lua/nvim-tree/api/events.lua
new file mode 100644
index 00000000000..34e4d47a86e
--- /dev/null
+++ b/lua/nvim-tree/api/events.lua
@@ -0,0 +1,20 @@
+---@meta
+
+local events = require("nvim-tree.events")
+
+local nvim_tree = { api = { events = {} } }
+
+---
+---Register a handler for an event, see [nvim-tree-events].
+---
+---@param event_type string [nvim_tree_events_kind]
+---@param callback fun(payload: table?)
+function nvim_tree.api.events.subscribe(event_type, callback) end
+
+
+nvim_tree.api.events.Event = events.Event
+
+
+require("nvim-tree.api").hydrate_events(nvim_tree.api.events)
+
+return nvim_tree.api.events
diff --git a/lua/nvim-tree/api/init.lua b/lua/nvim-tree/api/init.lua
index d2d9a71e5ef..13b032d4066 100644
--- a/lua/nvim-tree/api/init.lua
+++ b/lua/nvim-tree/api/init.lua
@@ -1,4 +1,5 @@
 return {
+  events = require("nvim-tree.api.events"),
   filter = require("nvim-tree.api.filter"),
   health = require("nvim-tree.api.health"),
   map = require("nvim-tree.api.map"),
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index cf0da3200b9..fb0ced4cded 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -31,10 +31,11 @@ local modules = {
   { helptag = "nvim-tree-config-experimental",        title = "Class: Config.Experimental",       path = "./lua/nvim_tree/_meta/config/experimental.lua", },
   { helptag = "nvim-tree-config-log",                 title = "Class: Config.Log",                path = "./lua/nvim_tree/_meta/config/log.lua", },
 
+  { helptag = "nvim-tree-api-events",                 title = "Lua module: nvim_tree.api.events", path = "./lua/nvim_tree/api/events.lua", },
   { helptag = "nvim-tree-api-filter",                 title = "Lua module: nvim_tree.api.filter", path = "./lua/nvim_tree/api/filter.lua", },
   { helptag = "nvim-tree-api-health",                 title = "Lua module: nvim_tree.api.health", path = "./lua/nvim_tree/api/health.lua", },
   { helptag = "nvim-tree-api-map",                    title = "Lua module: nvim_tree.api.map",    path = "./lua/nvim_tree/api/map.lua", },
-  { helptag = "nvim-tree-api-marks",                    title = "Lua module: nvim_tree.api.marks",    path = "./lua/nvim_tree/api/marks.lua", },
+  { helptag = "nvim-tree-api-marks",                  title = "Lua module: nvim_tree.api.marks",  path = "./lua/nvim_tree/api/marks.lua", },
   { helptag = "nvim-tree-api-tree",                   title = "Lua module: nvim_tree.api.tree",   path = "./lua/nvim_tree/api/tree.lua", },
 }
 

From 219984a5baafb5765b47add03f24185698e514ec Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sun, 18 Jan 2026 14:26:32 +1100
Subject: [PATCH 096/170] docs(#3088): extract api/events.lua

---
 doc/nvim-tree-lua.txt | 18 ++----------------
 1 file changed, 2 insertions(+), 16 deletions(-)

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index f001fd6354a..458ebb14220 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -1024,20 +1024,6 @@ API: Git                                                   *nvim-tree-api.git*
 git.reload()                                      *nvim-tree-api.git.reload()*
     Update the git status of the entire tree.
 
-==============================================================================
-API: Events                                             *nvim-tree-api.events*
-
-                                            *nvim-tree-api.events.subscribe()*
-events.subscribe({event_type},     {callback})
-    Register a handler for an event, see |nvim-tree-events|
-
-    Parameters: ~
-      • {event_type} (string)   |nvim-tree-api.events.Event|
-      • {callback}   (function) see |nvim_tree_events_kind| for parameters
-
-events.Event                                      *nvim-tree-api.events.Event*
-    String enum: |nvim_tree_events_kind|
-
 
 ==============================================================================
 API: Live Filter                                   *nvim-tree-api.live_filter*
@@ -1491,8 +1477,8 @@ to |nvim_tree_registering_handlers| for more information.
 
 *nvim_tree_registering_handlers*
 
-Handlers are registered by calling |nvim-tree-api.events.subscribe()|
-function with an |nvim-tree-api.events.Event|
+Handlers are registered by calling |nvim_tree.api.events.subscribe()| function
+with an |nvim_tree_events_kind|.
 
 e.g. handler for node renamed: >lua
 

From 0ad171b75572d3059ab19bbf05b1fac9b49fbb7b Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sun, 18 Jan 2026 14:52:57 +1100
Subject: [PATCH 097/170] docs(#3088): extract api/fs.lua

---
 doc/nvim-tree-lua.txt         | 232 ++++++++++++++++------------------
 lua/nvim-tree/api.lua         |  14 +-
 lua/nvim-tree/api/fs.lua      | 115 +++++++++++++++++
 lua/nvim-tree/api/init.lua    |   1 +
 scripts/gen_vimdoc_config.lua |   1 +
 5 files changed, 239 insertions(+), 124 deletions(-)
 create mode 100644 lua/nvim-tree/api/fs.lua

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 458ebb14220..a25e36aa153 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -163,20 +163,6 @@ Quickstart: Custom Mappings             *nvim-tree-quickstart-custom-mappings*
 
 TODO #3088 remove dummy tags once entire API has been migrated
 
-*nvim_tree.api.fs.copy.absolute_path()*
-*nvim_tree.api.fs.copy.basename()*
-*nvim_tree.api.fs.copy.filename()*
-*nvim_tree.api.fs.copy.node()*
-*nvim_tree.api.fs.copy.relative_path()*
-*nvim_tree.api.fs.create()*
-*nvim_tree.api.fs.cut()*
-*nvim_tree.api.fs.paste()*
-*nvim_tree.api.fs.remove()*
-*nvim_tree.api.fs.rename()*
-*nvim_tree.api.fs.rename_basename()*
-*nvim_tree.api.fs.rename_full()*
-*nvim_tree.api.fs.rename_sub()*
-*nvim_tree.api.fs.trash()*
 *nvim_tree.api.node.navigate.diagnostics.next()*
 *nvim_tree.api.node.navigate.diagnostics.prev()*
 *nvim_tree.api.node.navigate.git.next()*
@@ -293,7 +279,7 @@ Commands may be executed with a `` (`!`) or take a `` string argumen
     focus = true,
   })
 <
-*:NvimTreeClipboard*                       |nvim-tree-api.fs.print_clipboard()| >lua
+*:NvimTreeClipboard*                       |nvim_tree.api.fs.print_clipboard()| >lua
 
   require("nvim-tree.api").fs.print_clipboard()
 <
@@ -635,108 +621,6 @@ Functions accepting {node} as their first argument will use the node under the
 cursor when that argument is not present or nil.
 
 
-==============================================================================
-API: File System                                            *nvim-tree-api.fs*
-
-fs.create({node})                                  *nvim-tree-api.fs.create()*
-    Prompt to create a file or directory. Use a trailing `/` for a directory.
-    Multiple directories/files may be created e.g. `foo/bar/baz`
-
-    Parameters: ~
-      • {node} (Node|nil) parent, uses the parent of a file.
-
-fs.remove({node})                                  *nvim-tree-api.fs.remove()*
-    Delete a file or folder from the file system.
-
-    Parameters: ~
-      • {node} (Node|nil) file or folder
-
-fs.trash({node})                                    *nvim-tree-api.fs.trash()*
-    Trash a file or folder as per |nvim_tree.Config.Trash|
-
-    Parameters: ~
-      • {node} (Node|nil) file or folder
-
-fs.rename_node({node})                        *nvim-tree-api.fs.rename_node()*
-    Prompt to rename a file or folder.
-
-    Parameters: ~
-      • {node} (Node|nil) file or folder
-
-fs.rename({node})                                  *nvim-tree-api.fs.rename()*
-    Prompt to rename a file or folder by name.
-
-    Parameters: ~
-      • {node} (Node|nil) file or folder
-
-fs.rename_basename({node})                *nvim-tree-api.fs.rename_basename()*
-    Prompt to rename a file or folder by name with extension omitted.
-
-    Parameters: ~
-      • {node} (Node|nil) file or folder
-
-fs.rename_sub({node})                          *nvim-tree-api.fs.rename_sub()*
-    Prompt to rename a file or folder by absolute path with name omitted.
-
-    Parameters: ~
-      • {node} (Node|nil) file or folder
-
-fs.rename_full({node})                        *nvim-tree-api.fs.rename_full()*
-    Prompt to rename a file or folder by absolute path.
-
-    Parameters: ~
-      • {node} (Node|nil) file or folder
-
-fs.cut({node})                                        *nvim-tree-api.fs.cut()*
-    Cut a file or folder to the nvim-tree clipboard.
-
-    Parameters: ~
-      • {node} (Node|nil) file or folder
-
-fs.paste({node})                                    *nvim-tree-api.fs.paste()*
-    Paste a file or folder from the nvim-tree clipboard.
-
-    Parameters: ~
-      • {node} (Node|nil) destination folder, uses the parent of a file.
-
-fs.copy.node({node})                            *nvim-tree-api.fs.copy.node()*
-    Copy a file or folder from the nvim-tree clipboard.
-
-    Parameters: ~
-      • {node} (Node|nil) file or folder
-
-fs.copy.absolute_path({node})          *nvim-tree-api.fs.copy.absolute_path()*
-    Copy the absolute path of a file or folder to the system clipboard.
-
-    Parameters: ~
-      • {node} (Node|nil) file or folder
-
-fs.copy.basename({node})                    *nvim-tree-api.fs.copy.basename()*
-    Copy the name of a file or folder with extension omitted to the system
-    clipboard.
-
-    Parameters: ~
-      • {node} (Node|nil) file or folder
-
-fs.copy.filename({node})                    *nvim-tree-api.fs.copy.filename()*
-    Copy the name of a file or folder to the system clipboard.
-
-    Parameters: ~
-      • {node} (Node|nil) file or folder
-
-fs.copy.relative_path({node})          *nvim-tree-api.fs.copy.relative_path()*
-    Copy the path of a file or folder relative to the tree root to the system
-    clipboard.
-
-    Parameters: ~
-      • {node} (Node|nil) file or folder
-
-fs.clear_clipboard()                      *nvim-tree-api.fs.clear_clipboard()*
-    Clear the nvim-tree clipboard.
-
-fs.print_clipboard()                      *nvim-tree-api.fs.print_clipboard()*
-    Print the contents of the nvim-tree clipboard.
-
 ==============================================================================
 API: Node                                                 *nvim-tree-api.node*
 
@@ -1596,13 +1480,13 @@ can can be used to identify the type of prompt, to allow user side
 configurations for different types of prompts.
 
 - `nvimtree_overwrite_rename`
-    overwrite or rename during |nvim-tree-api.fs.paste()|
+    overwrite or rename during |nvim_tree.api.fs.paste()|
 
 - `nvimtree_remove`
-    delete during |nvim-tree-api.fs.remove()|
+    delete during |nvim_tree.api.fs.remove()|
 
 - `nvimtree_trash`
-    send to trash during |nvim-tree-api.fs.trash()|
+    send to trash during |nvim_tree.api.fs.trash()|
 
 - `nvimtree_bulk_delete`
     delete all bookmarked during |nvim-tree-api.marks.bulk.delete()|
@@ -2870,6 +2754,114 @@ live_filter.start()                 *nvim_tree.api.filter.live_filter.start()*
     `NvimTreeFilter`
 
 
+==============================================================================
+Lua module: nvim_tree.api.fs                                *nvim-tree-api-fs*
+
+clear_clipboard()                         *nvim_tree.api.fs.clear_clipboard()*
+    Clear the nvim-tree clipboard.
+
+copy.absolute_path({node})             *nvim_tree.api.fs.copy.absolute_path()*
+    Copy the absolute path to the system clipboard.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node`)
+
+copy.basename({node})                       *nvim_tree.api.fs.copy.basename()*
+    Copy the name with extension omitted to the system clipboard.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node`)
+
+copy.filename({node})                       *nvim_tree.api.fs.copy.filename()*
+    Copy the name to the system clipboard.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node`)
+
+copy.node({node})                               *nvim_tree.api.fs.copy.node()*
+    Copy to the nvim-tree clipboard.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node`)
+
+copy.relative_path({node})             *nvim_tree.api.fs.copy.relative_path()*
+    Copy the path relative to the tree root to the system clipboard.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node`)
+
+create({node})                                     *nvim_tree.api.fs.create()*
+    Prompt to create a file or directory.
+
+    When {node} is a file it will be created in the parent directory.
+
+    Use a trailing `"/"` to create a directory e.g. `"foo/"`
+
+    Multiple directories/files may be created e.g. `"foo/bar/baz"`
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node`)
+
+cut({node})                                           *nvim_tree.api.fs.cut()*
+    Cut to the nvim-tree clipboard.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node`)
+
+paste({node})                                       *nvim_tree.api.fs.paste()*
+    Paste from the nvim-tree clipboard.
+
+    If {node} is a file it will pasted in the parent directory.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node`)
+
+print_clipboard()                         *nvim_tree.api.fs.print_clipboard()*
+    Print the contents of the nvim-tree clipboard.
+
+remove({node})                                     *nvim_tree.api.fs.remove()*
+    Delete from the file system.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node`)
+
+rename({node})                                     *nvim_tree.api.fs.rename()*
+    Prompt to rename by name.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node`)
+
+rename_basename({node})                   *nvim_tree.api.fs.rename_basename()*
+    Prompt to rename by name with extension omitted.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node`)
+
+rename_full({node})                           *nvim_tree.api.fs.rename_full()*
+    Prompt to rename by absolute path.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node`)
+
+rename_node({node})                           *nvim_tree.api.fs.rename_node()*
+    Prompt to rename.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node`)
+
+rename_sub({node})                             *nvim_tree.api.fs.rename_sub()*
+    Prompt to rename by absolute path with name omitted.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node`)
+
+trash({node})                                       *nvim_tree.api.fs.trash()*
+    Trash as per |nvim_tree.Config.Trash|
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node`)
+
+
 ==============================================================================
 Lua module: nvim_tree.api.health                        *nvim-tree-api-health*
 
diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index 325ad604ca9..a2fc727187c 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -27,14 +27,14 @@ local Api = {
     open = {},
     buffer = {},
   },
-  events = {},
+  -- events = {},
   -- marks = {
   --   bulk = {},
   --   navigate = {},
   -- },
-  fs = {
-    copy = {},
-  },
+  -- fs = {
+  --   copy = {},
+  -- },
   -- git = {},
   -- live_filter = {},
   -- config = {
@@ -232,6 +232,9 @@ Api.git = {
 
 end
 
+function Api.hydrate_fs(fs)
+  Api.fs = fs
+
 Api.fs.create = wrap_node_or_nil(actions.fs.create_file.fn)
 Api.fs.remove = wrap_node(actions.fs.remove_file.fn)
 Api.fs.trash = wrap_node(actions.fs.trash.fn)
@@ -249,6 +252,9 @@ Api.fs.copy.absolute_path = wrap_node(wrap_explorer_member("clipboard", "copy_ab
 Api.fs.copy.filename = wrap_node(wrap_explorer_member("clipboard", "copy_filename"))
 Api.fs.copy.basename = wrap_node(wrap_explorer_member("clipboard", "copy_basename"))
 Api.fs.copy.relative_path = wrap_node(wrap_explorer_member("clipboard", "copy_path"))
+
+end
+
 ---
 ---@class NodeEditOpts
 ---@field quit_on_open boolean|nil default false
diff --git a/lua/nvim-tree/api/fs.lua b/lua/nvim-tree/api/fs.lua
new file mode 100644
index 00000000000..83c6f4f277a
--- /dev/null
+++ b/lua/nvim-tree/api/fs.lua
@@ -0,0 +1,115 @@
+---@meta
+local nvim_tree = { api = { fs = { copy = {} } } }
+
+---
+---Clear the nvim-tree clipboard.
+---
+function nvim_tree.api.fs.clear_clipboard() end
+
+---
+---Copy the absolute path to the system clipboard.
+---
+---@param node nvim_tree.api.Node
+function nvim_tree.api.fs.copy.absolute_path(node) end
+
+---
+---Copy the name with extension omitted to the system clipboard.
+---
+---@param node nvim_tree.api.Node
+function nvim_tree.api.fs.copy.basename(node) end
+
+---
+---Copy the name to the system clipboard.
+---
+---@param node nvim_tree.api.Node
+function nvim_tree.api.fs.copy.filename(node) end
+
+---
+---Copy to the nvim-tree clipboard.
+---
+---@param node nvim_tree.api.Node
+function nvim_tree.api.fs.copy.node(node) end
+
+---
+---Copy the path relative to the tree root to the system clipboard.
+---
+---@param node nvim_tree.api.Node
+function nvim_tree.api.fs.copy.relative_path(node) end
+
+---
+---Prompt to create a file or directory.
+---
+---When {node} is a file it will be created in the parent directory.
+---
+---Use a trailing `"/"` to create a directory e.g. `"foo/"`
+---
+---Multiple directories/files may be created e.g. `"foo/bar/baz"`
+---
+---@param node nvim_tree.api.Node
+function nvim_tree.api.fs.create(node) end
+
+---
+---Cut to the nvim-tree clipboard.
+---
+---@param node nvim_tree.api.Node
+function nvim_tree.api.fs.cut(node) end
+
+---
+---Paste from the nvim-tree clipboard.
+---
+---If {node} is a file it will pasted in the parent directory.
+---
+---@param node nvim_tree.api.Node
+function nvim_tree.api.fs.paste(node) end
+
+---
+---Print the contents of the nvim-tree clipboard.
+---
+function nvim_tree.api.fs.print_clipboard() end
+
+---
+---Delete from the file system.
+---
+---@param node nvim_tree.api.Node
+function nvim_tree.api.fs.remove(node) end
+
+---
+---Prompt to rename by name.
+---
+---@param node nvim_tree.api.Node
+function nvim_tree.api.fs.rename(node) end
+
+---
+---Prompt to rename by name with extension omitted.
+---
+---@param node nvim_tree.api.Node
+function nvim_tree.api.fs.rename_basename(node) end
+
+---
+---Prompt to rename by absolute path.
+---
+---@param node nvim_tree.api.Node
+function nvim_tree.api.fs.rename_full(node) end
+
+---
+---Prompt to rename.
+---
+---@param node nvim_tree.api.Node
+function nvim_tree.api.fs.rename_node(node) end
+
+---
+---Prompt to rename by absolute path with name omitted.
+---
+---@param node nvim_tree.api.Node
+function nvim_tree.api.fs.rename_sub(node) end
+
+---
+---Trash as per |nvim_tree.Config.Trash|
+---
+---@param node nvim_tree.api.Node
+function nvim_tree.api.fs.trash(node) end
+
+require("nvim-tree.api").hydrate_fs(nvim_tree.api.fs)
+
+
+return nvim_tree.api.filter
diff --git a/lua/nvim-tree/api/init.lua b/lua/nvim-tree/api/init.lua
index 13b032d4066..11d23caab15 100644
--- a/lua/nvim-tree/api/init.lua
+++ b/lua/nvim-tree/api/init.lua
@@ -1,6 +1,7 @@
 return {
   events = require("nvim-tree.api.events"),
   filter = require("nvim-tree.api.filter"),
+  fs = require("nvim-tree.api.fs"),
   health = require("nvim-tree.api.health"),
   map = require("nvim-tree.api.map"),
   marks = require("nvim-tree.api.marks"),
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index fb0ced4cded..665cf75be12 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -33,6 +33,7 @@ local modules = {
 
   { helptag = "nvim-tree-api-events",                 title = "Lua module: nvim_tree.api.events", path = "./lua/nvim_tree/api/events.lua", },
   { helptag = "nvim-tree-api-filter",                 title = "Lua module: nvim_tree.api.filter", path = "./lua/nvim_tree/api/filter.lua", },
+  { helptag = "nvim-tree-api-fs",                     title = "Lua module: nvim_tree.api.fs",     path = "./lua/nvim_tree/api/fs.lua", },
   { helptag = "nvim-tree-api-health",                 title = "Lua module: nvim_tree.api.health", path = "./lua/nvim_tree/api/health.lua", },
   { helptag = "nvim-tree-api-map",                    title = "Lua module: nvim_tree.api.map",    path = "./lua/nvim_tree/api/map.lua", },
   { helptag = "nvim-tree-api-marks",                  title = "Lua module: nvim_tree.api.marks",  path = "./lua/nvim_tree/api/marks.lua", },

From 56e61c241e158a87b4ab1643fd71b13d66991c69 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sun, 18 Jan 2026 15:36:19 +1100
Subject: [PATCH 098/170] docs(#3088): extract api/commands.lua

---
 doc/nvim-tree-lua.txt          | 31 ++++++++++-------
 lua/nvim-tree/api.lua          |  5 +++
 lua/nvim-tree/api/commands.lua | 21 ++++++++++++
 lua/nvim-tree/commands.lua     |  2 ++
 scripts/gen_vimdoc_config.lua  | 61 +++++++++++++++++-----------------
 5 files changed, 78 insertions(+), 42 deletions(-)
 create mode 100644 lua/nvim-tree/api/commands.lua

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index a25e36aa153..1c5c8c84e2e 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -965,18 +965,6 @@ marks.navigate.select()                *nvim-tree-api.marks.navigate.select()*
     A folder will be focused, a file will be opened.
 
 
-==============================================================================
-API: Commands                                         *nvim-tree-api.commands*
-
-commands.get()                                  *nvim-tree-api.commands.get()*
-    Retrieve all commands, see |nvim-tree-commands|
-
-    Return: ~
-        (table) array containing |nvim_create_user_command()| parameters:
-        • {name}    (string)
-        • {command} (function)
-        • {opts}    (table)
-
 ==============================================================================
 Mappings                                                  *nvim-tree-mappings*
 
@@ -2732,6 +2720,25 @@ Class: Config.Log                                       *nvim-tree-config-log*
 
 
 
+==============================================================================
+Lua module: nvim_tree.api.commands                    *nvim-tree-api-commands*
+
+*nvim_tree.api.commands.Command*
+    Arguments for |nvim_create_user_command()|
+
+    Fields: ~
+      • {name}     (`string`)
+      • {command}  (`fun(args: vim.api.keyset.create_user_command.command_args)`)
+      • {opts}     (`vim.api.keyset.user_command`)
+
+
+get()                                           *nvim_tree.api.commands.get()*
+    Retrieve all nvim-tree commands, see |nvim-tree-commands|
+
+    Return: ~
+        (`nvim_tree.api.commands.Command[]`)
+
+
 ==============================================================================
 Lua module: nvim_tree.api.events                        *nvim-tree-api-events*
 
diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index a2fc727187c..3d18b248266 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -428,10 +428,15 @@ Api.diagnostics = {
 
 end
 
+function Api.hydrate_commands(commands)
+  Api.commands = commands
+
 Api.commands.get = wrap(function()
   return require("nvim-tree.commands").get()
 end)
 
+end
+
 ---Create a decorator class by calling :extend()
 ---See :help nvim-tree-decorators
 ---@type nvim_tree.api.decorator.UserDecorator
diff --git a/lua/nvim-tree/api/commands.lua b/lua/nvim-tree/api/commands.lua
new file mode 100644
index 00000000000..07facd2affc
--- /dev/null
+++ b/lua/nvim-tree/api/commands.lua
@@ -0,0 +1,21 @@
+---@meta
+local nvim_tree = { api = { commands = {} } }
+
+---
+---Arguments for [nvim_create_user_command()]
+---
+---@class nvim_tree.api.commands.Command
+---
+---@field name string
+---@field command fun(args: vim.api.keyset.create_user_command.command_args)
+---@field opts vim.api.keyset.user_command
+
+---
+---Retrieve all nvim-tree commands, see [nvim-tree-commands]
+---
+---@return nvim_tree.api.commands.Command[]
+function nvim_tree.api.commands.get() end
+
+require("nvim-tree.api").hydrate_commands(nvim_tree.api.commands)
+
+return nvim_tree.api.commands
diff --git a/lua/nvim-tree/commands.lua b/lua/nvim-tree/commands.lua
index 3be807ac2d0..178f2733b61 100644
--- a/lua/nvim-tree/commands.lua
+++ b/lua/nvim-tree/commands.lua
@@ -1,5 +1,6 @@
 local M = {}
 
+---@type nvim_tree.api.commands.Command[]
 local CMDS = {
   {
     name = "NvimTreeOpen",
@@ -142,6 +143,7 @@ local CMDS = {
   },
 }
 
+---@return nvim_tree.api.commands.Command[]
 function M.get()
   return vim.deepcopy(CMDS)
 end
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index 665cf75be12..e049ead3b2d 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -8,36 +8,37 @@
 ---Generated within help files in this order
 ---@type Module[]
 local modules = {
-  { helptag = "nvim-tree-config",                     title = "Class: Config",                    path = "./lua/nvim_tree/_meta/config.lua", },
-  { helptag = "nvim-tree-config-sort",                title = "Class: Config.Sort",               path = "./lua/nvim_tree/_meta/config/sort.lua", },
-  { helptag = "nvim-tree-config-view",                title = "Class: Config.View",               path = "./lua/nvim_tree/_meta/config/view.lua", },
-  { helptag = "nvim-tree-config-renderer",            title = "Class: Config.Renderer",           path = "./lua/nvim_tree/_meta/config/renderer.lua", },
-  { helptag = "nvim-tree-config-hijack-directories",  title = "Class: Config.HijackDirectories",  path = "./lua/nvim_tree/_meta/config/hijack_directories.lua", },
-  { helptag = "nvim-tree-config-update-focused-file", title = "Class: Config.UpdateFocusedFile",  path = "./lua/nvim_tree/_meta/config/update_focused_file.lua", },
-  { helptag = "nvim-tree-config-system-open",         title = "Class: Config.SystemOpen",         path = "./lua/nvim_tree/_meta/config/system_open.lua", },
-  { helptag = "nvim-tree-config-git",                 title = "Class: Config.Git",                path = "./lua/nvim_tree/_meta/config/git.lua", },
-  { helptag = "nvim-tree-config-diagnostics",         title = "Class: Config.Diagnostics",        path = "./lua/nvim_tree/_meta/config/diagnostics.lua", },
-  { helptag = "nvim-tree-config-modified",            title = "Class: Config.Modified",           path = "./lua/nvim_tree/_meta/config/modified.lua", },
-  { helptag = "nvim-tree-config-filters",             title = "Class: Config.Filters",            path = "./lua/nvim_tree/_meta/config/filters.lua", },
-  { helptag = "nvim-tree-config-live-filter",         title = "Class: Config.LiveFilter",         path = "./lua/nvim_tree/_meta/config/live_filter.lua", },
-  { helptag = "nvim-tree-config-filesystem-watchers", title = "Class: Config.FilesystemWatchers", path = "./lua/nvim_tree/_meta/config/filesystem_watchers.lua", },
-  { helptag = "nvim-tree-config-actions",             title = "Class: Config.Actions",            path = "./lua/nvim_tree/_meta/config/actions.lua", },
-  { helptag = "nvim-tree-config-trash",               title = "Class: Config.Trash",              path = "./lua/nvim_tree/_meta/config/trash.lua", },
-  { helptag = "nvim-tree-config-tab",                 title = "Class: Config.Tab",                path = "./lua/nvim_tree/_meta/config/tab.lua", },
-  { helptag = "nvim-tree-config-notify",              title = "Class: Config.Notify",             path = "./lua/nvim_tree/_meta/config/notify.lua", },
-  { helptag = "nvim-tree-config-bookmarks",           title = "Class: Config.Bookmarks",          path = "./lua/nvim_tree/_meta/config/bookmarks.lua", },
-  { helptag = "nvim-tree-config-help",                title = "Class: Config.Help",               path = "./lua/nvim_tree/_meta/config/help.lua", },
-  { helptag = "nvim-tree-config-ui",                  title = "Class: Config.UI",                 path = "./lua/nvim_tree/_meta/config/ui.lua",                  name = "UI", },
-  { helptag = "nvim-tree-config-experimental",        title = "Class: Config.Experimental",       path = "./lua/nvim_tree/_meta/config/experimental.lua", },
-  { helptag = "nvim-tree-config-log",                 title = "Class: Config.Log",                path = "./lua/nvim_tree/_meta/config/log.lua", },
-
-  { helptag = "nvim-tree-api-events",                 title = "Lua module: nvim_tree.api.events", path = "./lua/nvim_tree/api/events.lua", },
-  { helptag = "nvim-tree-api-filter",                 title = "Lua module: nvim_tree.api.filter", path = "./lua/nvim_tree/api/filter.lua", },
-  { helptag = "nvim-tree-api-fs",                     title = "Lua module: nvim_tree.api.fs",     path = "./lua/nvim_tree/api/fs.lua", },
-  { helptag = "nvim-tree-api-health",                 title = "Lua module: nvim_tree.api.health", path = "./lua/nvim_tree/api/health.lua", },
-  { helptag = "nvim-tree-api-map",                    title = "Lua module: nvim_tree.api.map",    path = "./lua/nvim_tree/api/map.lua", },
-  { helptag = "nvim-tree-api-marks",                  title = "Lua module: nvim_tree.api.marks",  path = "./lua/nvim_tree/api/marks.lua", },
-  { helptag = "nvim-tree-api-tree",                   title = "Lua module: nvim_tree.api.tree",   path = "./lua/nvim_tree/api/tree.lua", },
+  { helptag = "nvim-tree-config",                     title = "Class: Config",                      path = "./lua/nvim_tree/_meta/config.lua", },
+  { helptag = "nvim-tree-config-sort",                title = "Class: Config.Sort",                 path = "./lua/nvim_tree/_meta/config/sort.lua", },
+  { helptag = "nvim-tree-config-view",                title = "Class: Config.View",                 path = "./lua/nvim_tree/_meta/config/view.lua", },
+  { helptag = "nvim-tree-config-renderer",            title = "Class: Config.Renderer",             path = "./lua/nvim_tree/_meta/config/renderer.lua", },
+  { helptag = "nvim-tree-config-hijack-directories",  title = "Class: Config.HijackDirectories",    path = "./lua/nvim_tree/_meta/config/hijack_directories.lua", },
+  { helptag = "nvim-tree-config-update-focused-file", title = "Class: Config.UpdateFocusedFile",    path = "./lua/nvim_tree/_meta/config/update_focused_file.lua", },
+  { helptag = "nvim-tree-config-system-open",         title = "Class: Config.SystemOpen",           path = "./lua/nvim_tree/_meta/config/system_open.lua", },
+  { helptag = "nvim-tree-config-git",                 title = "Class: Config.Git",                  path = "./lua/nvim_tree/_meta/config/git.lua", },
+  { helptag = "nvim-tree-config-diagnostics",         title = "Class: Config.Diagnostics",          path = "./lua/nvim_tree/_meta/config/diagnostics.lua", },
+  { helptag = "nvim-tree-config-modified",            title = "Class: Config.Modified",             path = "./lua/nvim_tree/_meta/config/modified.lua", },
+  { helptag = "nvim-tree-config-filters",             title = "Class: Config.Filters",              path = "./lua/nvim_tree/_meta/config/filters.lua", },
+  { helptag = "nvim-tree-config-live-filter",         title = "Class: Config.LiveFilter",           path = "./lua/nvim_tree/_meta/config/live_filter.lua", },
+  { helptag = "nvim-tree-config-filesystem-watchers", title = "Class: Config.FilesystemWatchers",   path = "./lua/nvim_tree/_meta/config/filesystem_watchers.lua", },
+  { helptag = "nvim-tree-config-actions",             title = "Class: Config.Actions",              path = "./lua/nvim_tree/_meta/config/actions.lua", },
+  { helptag = "nvim-tree-config-trash",               title = "Class: Config.Trash",                path = "./lua/nvim_tree/_meta/config/trash.lua", },
+  { helptag = "nvim-tree-config-tab",                 title = "Class: Config.Tab",                  path = "./lua/nvim_tree/_meta/config/tab.lua", },
+  { helptag = "nvim-tree-config-notify",              title = "Class: Config.Notify",               path = "./lua/nvim_tree/_meta/config/notify.lua", },
+  { helptag = "nvim-tree-config-bookmarks",           title = "Class: Config.Bookmarks",            path = "./lua/nvim_tree/_meta/config/bookmarks.lua", },
+  { helptag = "nvim-tree-config-help",                title = "Class: Config.Help",                 path = "./lua/nvim_tree/_meta/config/help.lua", },
+  { helptag = "nvim-tree-config-ui",                  title = "Class: Config.UI",                   path = "./lua/nvim_tree/_meta/config/ui.lua",                  name = "UI", },
+  { helptag = "nvim-tree-config-experimental",        title = "Class: Config.Experimental",         path = "./lua/nvim_tree/_meta/config/experimental.lua", },
+  { helptag = "nvim-tree-config-log",                 title = "Class: Config.Log",                  path = "./lua/nvim_tree/_meta/config/log.lua", },
+
+  { helptag = "nvim-tree-api-commands",               title = "Lua module: nvim_tree.api.commands", path = "./lua/nvim_tree/api/commands.lua", },
+  { helptag = "nvim-tree-api-events",                 title = "Lua module: nvim_tree.api.events",   path = "./lua/nvim_tree/api/events.lua", },
+  { helptag = "nvim-tree-api-filter",                 title = "Lua module: nvim_tree.api.filter",   path = "./lua/nvim_tree/api/filter.lua", },
+  { helptag = "nvim-tree-api-fs",                     title = "Lua module: nvim_tree.api.fs",       path = "./lua/nvim_tree/api/fs.lua", },
+  { helptag = "nvim-tree-api-health",                 title = "Lua module: nvim_tree.api.health",   path = "./lua/nvim_tree/api/health.lua", },
+  { helptag = "nvim-tree-api-map",                    title = "Lua module: nvim_tree.api.map",      path = "./lua/nvim_tree/api/map.lua", },
+  { helptag = "nvim-tree-api-marks",                  title = "Lua module: nvim_tree.api.marks",    path = "./lua/nvim_tree/api/marks.lua", },
+  { helptag = "nvim-tree-api-tree",                   title = "Lua module: nvim_tree.api.tree",     path = "./lua/nvim_tree/api/tree.lua", },
 }
 
 -- hydrate file names

From 3c65e3f2f461497fc7db6c5f4e8fce199a75e223 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sun, 18 Jan 2026 15:51:34 +1100
Subject: [PATCH 099/170] docs(#3088): extract api/node.lua functions, doc TODO

---
 doc/nvim-tree-lua.txt         | 191 ++++++++++++++++++++++++++++------
 lua/nvim-tree/_meta/api.lua   |  35 -------
 lua/nvim-tree/api.lua         |  29 +++---
 lua/nvim-tree/api/init.lua    |   1 +
 lua/nvim-tree/api/node.lua    | 132 +++++++++++++++++++++++
 scripts/gen_vimdoc_config.lua |   1 +
 6 files changed, 312 insertions(+), 77 deletions(-)
 create mode 100644 lua/nvim-tree/api/node.lua

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 1c5c8c84e2e..9fabb6858fb 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -158,36 +158,6 @@ Show the mappings:  `g?`
 ==============================================================================
 Quickstart: Custom Mappings             *nvim-tree-quickstart-custom-mappings*
 
-
-
-
-TODO #3088 remove dummy tags once entire API has been migrated
-
-*nvim_tree.api.node.navigate.diagnostics.next()*
-*nvim_tree.api.node.navigate.diagnostics.prev()*
-*nvim_tree.api.node.navigate.git.next()*
-*nvim_tree.api.node.navigate.git.prev()*
-*nvim_tree.api.node.navigate.parent()*
-*nvim_tree.api.node.navigate.parent_close()*
-*nvim_tree.api.node.navigate.sibling.first()*
-*nvim_tree.api.node.navigate.sibling.last()*
-*nvim_tree.api.node.navigate.sibling.next()*
-*nvim_tree.api.node.navigate.sibling.prev()*
-*nvim_tree.api.node.open.edit()*
-*nvim_tree.api.node.open.horizontal()*
-*nvim_tree.api.node.open.no_window_picker()*
-*nvim_tree.api.node.open.preview()*
-*nvim_tree.api.node.open.replace_tree_buffer()*
-*nvim_tree.api.node.open.tab()*
-*nvim_tree.api.node.open.toggle_group_empty()*
-*nvim_tree.api.node.open.vertical()*
-*nvim_tree.api.node.run.cmd()*
-*nvim_tree.api.node.run.system()*
-*nvim_tree.api.node.show_info_popup()*
-
-
-
-
 |nvim-tree-mappings-default| are applied by default however you may customise
 via |nvim_tree.Config| {on_attach} e.g. >lua
 
@@ -2949,6 +2919,167 @@ toggle({node})                                  *nvim_tree.api.marks.toggle()*
       • {node}  (`nvim_tree.api.Node`) file or directory
 
 
+==============================================================================
+Lua module: nvim_tree.api.node                            *nvim-tree-api-node*
+
+*nvim_tree.api.DirectoryLinkNode*
+    Extends: |nvim_tree.api.DirectoryNode|
+
+    DirectoryLink
+
+*nvim_tree.api.DirectoryNode*
+    Extends: |nvim_tree.api.Node|
+
+    Directory
+
+    Fields: ~
+      • {has_children}  (`boolean`)
+      • {nodes}         (`nvim_tree.api.Node[]`)
+      • {open}          (`boolean`)
+
+*nvim_tree.api.FileLinkNode*
+    Extends: |nvim_tree.api.FileNode|
+
+    File Link
+
+*nvim_tree.api.FileNode*
+    Extends: |nvim_tree.api.Node|
+
+    File
+
+    Fields: ~
+      • {extension}  (`string`)
+
+*nvim_tree.api.LinkNode*
+    Link mixin
+
+    Fields: ~
+      • {link_to}         (`string`)
+      • {fs_stat_target}  (`uv.fs_stat.result`)
+
+*nvim_tree.api.Node*
+    Base Node, Abstract
+
+    Fields: ~
+      • {type}           (`"file"|"directory"|"link"`) uv.fs_stat.result.type
+      • {absolute_path}  (`string`)
+      • {executable}     (`boolean`)
+      • {fs_stat}        (`uv.fs_stat.result?`)
+      • {git_status}     (`GitNodeStatus?`)
+      • {hidden}         (`boolean`)
+      • {name}           (`string`)
+      • {parent}         (`nvim_tree.api.DirectoryNode?`)
+      • {diag_severity}  (`lsp.DiagnosticSeverity?`)
+
+*nvim_tree.api.RootNode*
+    Extends: |nvim_tree.api.DirectoryNode|
+
+    Root Directory
+
+
+nvim_tree.api.node.buffer.delete()        *nvim_tree.api.node.buffer.delete()*
+
+nvim_tree.api.node.buffer.wipe()            *nvim_tree.api.node.buffer.wipe()*
+
+nvim_tree.api.node.collapse()                  *nvim_tree.api.node.collapse()*
+
+nvim_tree.api.node.expand()                      *nvim_tree.api.node.expand()*
+
+                              *nvim_tree.api.node.navigate.diagnostics.next()*
+nvim_tree.api.node.navigate.diagnostics.next()
+
+                    *nvim_tree.api.node.navigate.diagnostics.next_recursive()*
+nvim_tree.api.node.navigate.diagnostics.next_recursive()
+
+                              *nvim_tree.api.node.navigate.diagnostics.prev()*
+nvim_tree.api.node.navigate.diagnostics.prev()
+
+                    *nvim_tree.api.node.navigate.diagnostics.prev_recursive()*
+nvim_tree.api.node.navigate.diagnostics.prev_recursive()
+
+                                      *nvim_tree.api.node.navigate.git.next()*
+nvim_tree.api.node.navigate.git.next()
+
+                            *nvim_tree.api.node.navigate.git.next_recursive()*
+nvim_tree.api.node.navigate.git.next_recursive()
+
+                      *nvim_tree.api.node.navigate.git.next_skip_gitignored()*
+nvim_tree.api.node.navigate.git.next_skip_gitignored()
+
+                                      *nvim_tree.api.node.navigate.git.prev()*
+nvim_tree.api.node.navigate.git.prev()
+
+                            *nvim_tree.api.node.navigate.git.prev_recursive()*
+nvim_tree.api.node.navigate.git.prev_recursive()
+
+                      *nvim_tree.api.node.navigate.git.prev_skip_gitignored()*
+nvim_tree.api.node.navigate.git.prev_skip_gitignored()
+
+                                   *nvim_tree.api.node.navigate.opened.next()*
+nvim_tree.api.node.navigate.opened.next()
+
+                                   *nvim_tree.api.node.navigate.opened.prev()*
+nvim_tree.api.node.navigate.opened.prev()
+
+                                        *nvim_tree.api.node.navigate.parent()*
+nvim_tree.api.node.navigate.parent()
+
+                                  *nvim_tree.api.node.navigate.parent_close()*
+nvim_tree.api.node.navigate.parent_close()
+
+                                 *nvim_tree.api.node.navigate.sibling.first()*
+nvim_tree.api.node.navigate.sibling.first()
+
+                                  *nvim_tree.api.node.navigate.sibling.last()*
+nvim_tree.api.node.navigate.sibling.last()
+
+                                  *nvim_tree.api.node.navigate.sibling.next()*
+nvim_tree.api.node.navigate.sibling.next()
+
+                                  *nvim_tree.api.node.navigate.sibling.prev()*
+nvim_tree.api.node.navigate.sibling.prev()
+
+nvim_tree.api.node.open.drop()                *nvim_tree.api.node.open.drop()*
+
+nvim_tree.api.node.open.edit()                *nvim_tree.api.node.open.edit()*
+
+                                        *nvim_tree.api.node.open.horizontal()*
+nvim_tree.api.node.open.horizontal()
+
+                              *nvim_tree.api.node.open.horizontal_no_picker()*
+nvim_tree.api.node.open.horizontal_no_picker()
+
+                                  *nvim_tree.api.node.open.no_window_picker()*
+nvim_tree.api.node.open.no_window_picker()
+
+nvim_tree.api.node.open.preview()          *nvim_tree.api.node.open.preview()*
+
+                                 *nvim_tree.api.node.open.preview_no_picker()*
+nvim_tree.api.node.open.preview_no_picker()
+
+                               *nvim_tree.api.node.open.replace_tree_buffer()*
+nvim_tree.api.node.open.replace_tree_buffer()
+
+nvim_tree.api.node.open.tab()                  *nvim_tree.api.node.open.tab()*
+
+nvim_tree.api.node.open.tab_drop()        *nvim_tree.api.node.open.tab_drop()*
+
+                                *nvim_tree.api.node.open.toggle_group_empty()*
+nvim_tree.api.node.open.toggle_group_empty()
+
+nvim_tree.api.node.open.vertical()        *nvim_tree.api.node.open.vertical()*
+
+                                *nvim_tree.api.node.open.vertical_no_picker()*
+nvim_tree.api.node.open.vertical_no_picker()
+
+nvim_tree.api.node.run.cmd()                    *nvim_tree.api.node.run.cmd()*
+
+nvim_tree.api.node.run.system()              *nvim_tree.api.node.run.system()*
+
+                                        *nvim_tree.api.node.show_info_popup()*
+nvim_tree.api.node.show_info_popup()
+
+
 ==============================================================================
 Lua module: nvim_tree.api.tree                            *nvim-tree-api-tree*
 
diff --git a/lua/nvim-tree/_meta/api.lua b/lua/nvim-tree/_meta/api.lua
index d6847940781..3783cef4760 100644
--- a/lua/nvim-tree/_meta/api.lua
+++ b/lua/nvim-tree/_meta/api.lua
@@ -5,41 +5,6 @@ error("Cannot require a meta file")
 -- Nodes
 --
 
----Base Node, Abstract
----@class (exact) nvim_tree.api.Node
----@field type "file" | "directory" | "link" uv.fs_stat.result.type
----@field absolute_path string
----@field executable boolean
----@field fs_stat uv.fs_stat.result?
----@field git_status GitNodeStatus?
----@field hidden boolean
----@field name string
----@field parent nvim_tree.api.DirectoryNode?
----@field diag_severity lsp.DiagnosticSeverity?
-
----File
----@class (exact) nvim_tree.api.FileNode: nvim_tree.api.Node
----@field extension string
-
----Directory
----@class (exact) nvim_tree.api.DirectoryNode: nvim_tree.api.Node
----@field has_children boolean
----@field nodes nvim_tree.api.Node[]
----@field open boolean
-
----Root Directory
----@class (exact) nvim_tree.api.RootNode: nvim_tree.api.DirectoryNode
-
----Link mixin
----@class (exact) nvim_tree.api.LinkNode
----@field link_to string
----@field fs_stat_target uv.fs_stat.result
-
----File Link
----@class (exact) nvim_tree.api.FileLinkNode: nvim_tree.api.FileNode, nvim_tree.api.LinkNode
-
----DirectoryLink
----@class (exact) nvim_tree.api.DirectoryLinkNode: nvim_tree.api.DirectoryNode, nvim_tree.api.LinkNode
 
 --
 -- Various Types
diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index 3d18b248266..7bb4f9b925b 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -16,17 +16,17 @@ local UserDecorator = require("nvim-tree.renderer.decorator.user")
 
 local Api = {
   -- tree = {},
-  node = {
-    navigate = {
-      sibling = {},
-      git = {},
-      diagnostics = {},
-      opened = {},
-    },
-    run = {},
-    open = {},
-    buffer = {},
-  },
+  -- node = {
+  --   navigate = {
+  --     sibling = {},
+  --     git = {},
+  --     diagnostics = {},
+  --     opened = {},
+  --   },
+  --   run = {},
+  --   open = {},
+  --   buffer = {},
+  -- },
   -- events = {},
   -- marks = {
   --   bulk = {},
@@ -40,7 +40,7 @@ local Api = {
   -- config = {
   --   mappings = {},
   -- },
-  commands = {},
+  -- commands = {},
   -- diagnostics = {},
   decorator = {},
 }
@@ -308,6 +308,9 @@ local function open_or_expand_or_dir_up(mode, toggle_group)
   end
 end
 
+function Api.hydrate_node(n)
+  Api.node = n
+
 Api.node.open.edit = wrap_node(open_or_expand_or_dir_up("edit"))
 Api.node.open.drop = wrap_node(open_or_expand_or_dir_up("drop"))
 Api.node.open.tab_drop = wrap_node(open_or_expand_or_dir_up("tab_drop"))
@@ -358,6 +361,8 @@ Api.node.buffer.wipe = wrap_node(function(node, opts)
   actions.node.buffer.wipe(node, opts)
 end)
 
+end
+
 -- Api.git.reload = wrap_explorer("reload_git")
 
 function Api.hydrate_events(ev)
diff --git a/lua/nvim-tree/api/init.lua b/lua/nvim-tree/api/init.lua
index 11d23caab15..6123c9c8d44 100644
--- a/lua/nvim-tree/api/init.lua
+++ b/lua/nvim-tree/api/init.lua
@@ -5,5 +5,6 @@ return {
   health = require("nvim-tree.api.health"),
   map = require("nvim-tree.api.map"),
   marks = require("nvim-tree.api.marks"),
+  node = require("nvim-tree.api.node"),
   tree = require("nvim-tree.api.tree"),
 }
diff --git a/lua/nvim-tree/api/node.lua b/lua/nvim-tree/api/node.lua
new file mode 100644
index 00000000000..7f40be04aa3
--- /dev/null
+++ b/lua/nvim-tree/api/node.lua
@@ -0,0 +1,132 @@
+---@meta
+local nvim_tree = { api = { node = { navigate = { sibling = {}, git = {}, diagnostics = {}, opened = {}, }, run = {}, open = {}, buffer = {}, } } }
+
+---
+---Base Node, Abstract
+---
+---@class nvim_tree.api.Node
+---@field type "file" | "directory" | "link" uv.fs_stat.result.type
+---@field absolute_path string
+---@field executable boolean
+---@field fs_stat uv.fs_stat.result?
+---@field git_status GitNodeStatus?
+---@field hidden boolean
+---@field name string
+---@field parent nvim_tree.api.DirectoryNode?
+---@field diag_severity lsp.DiagnosticSeverity?
+
+---
+---File
+---
+---@class nvim_tree.api.FileNode: nvim_tree.api.Node
+---@field extension string
+
+---
+---Directory
+---
+---@class nvim_tree.api.DirectoryNode: nvim_tree.api.Node
+---@field has_children boolean
+---@field nodes nvim_tree.api.Node[]
+---@field open boolean
+
+---
+---Root Directory
+---
+---@class nvim_tree.api.RootNode: nvim_tree.api.DirectoryNode
+
+---
+---Link mixin
+---
+---@class nvim_tree.api.LinkNode
+---@field link_to string
+---@field fs_stat_target uv.fs_stat.result
+
+---
+---File Link
+---
+---@class nvim_tree.api.FileLinkNode: nvim_tree.api.FileNode, nvim_tree.api.LinkNode
+
+---
+---DirectoryLink
+---
+---@class nvim_tree.api.DirectoryLinkNode: nvim_tree.api.DirectoryNode, nvim_tree.api.LinkNode
+
+function nvim_tree.api.node.buffer.delete() end
+
+function nvim_tree.api.node.buffer.wipe() end
+
+function nvim_tree.api.node.collapse() end
+
+function nvim_tree.api.node.expand() end
+
+function nvim_tree.api.node.navigate.diagnostics.next() end
+
+function nvim_tree.api.node.navigate.diagnostics.next_recursive() end
+
+function nvim_tree.api.node.navigate.diagnostics.prev() end
+
+function nvim_tree.api.node.navigate.diagnostics.prev_recursive() end
+
+function nvim_tree.api.node.navigate.git.next() end
+
+function nvim_tree.api.node.navigate.git.next_recursive() end
+
+function nvim_tree.api.node.navigate.git.next_skip_gitignored() end
+
+function nvim_tree.api.node.navigate.git.prev() end
+
+function nvim_tree.api.node.navigate.git.prev_recursive() end
+
+function nvim_tree.api.node.navigate.git.prev_skip_gitignored() end
+
+function nvim_tree.api.node.navigate.opened.next() end
+
+function nvim_tree.api.node.navigate.opened.prev() end
+
+function nvim_tree.api.node.navigate.parent() end
+
+function nvim_tree.api.node.navigate.parent_close() end
+
+function nvim_tree.api.node.navigate.sibling.first() end
+
+function nvim_tree.api.node.navigate.sibling.last() end
+
+function nvim_tree.api.node.navigate.sibling.next() end
+
+function nvim_tree.api.node.navigate.sibling.prev() end
+
+function nvim_tree.api.node.open.drop() end
+
+function nvim_tree.api.node.open.edit() end
+
+function nvim_tree.api.node.open.horizontal() end
+
+function nvim_tree.api.node.open.horizontal_no_picker() end
+
+function nvim_tree.api.node.open.no_window_picker() end
+
+function nvim_tree.api.node.open.preview() end
+
+function nvim_tree.api.node.open.preview_no_picker() end
+
+function nvim_tree.api.node.open.replace_tree_buffer() end
+
+function nvim_tree.api.node.open.tab() end
+
+function nvim_tree.api.node.open.tab_drop() end
+
+function nvim_tree.api.node.open.toggle_group_empty() end
+
+function nvim_tree.api.node.open.vertical() end
+
+function nvim_tree.api.node.open.vertical_no_picker() end
+
+function nvim_tree.api.node.run.cmd() end
+
+function nvim_tree.api.node.run.system() end
+
+function nvim_tree.api.node.show_info_popup() end
+
+require("nvim-tree.api").hydrate_node(nvim_tree.api.node)
+
+return nvim_tree.api.node
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index e049ead3b2d..97a461f9b9e 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -38,6 +38,7 @@ local modules = {
   { helptag = "nvim-tree-api-health",                 title = "Lua module: nvim_tree.api.health",   path = "./lua/nvim_tree/api/health.lua", },
   { helptag = "nvim-tree-api-map",                    title = "Lua module: nvim_tree.api.map",      path = "./lua/nvim_tree/api/map.lua", },
   { helptag = "nvim-tree-api-marks",                  title = "Lua module: nvim_tree.api.marks",    path = "./lua/nvim_tree/api/marks.lua", },
+  { helptag = "nvim-tree-api-node",                   title = "Lua module: nvim_tree.api.node",     path = "./lua/nvim_tree/api/node.lua", },
   { helptag = "nvim-tree-api-tree",                   title = "Lua module: nvim_tree.api.tree",     path = "./lua/nvim_tree/api/tree.lua", },
 }
 

From 9a8fb71413724a139b2e6e6157bb62415283ac07 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sun, 18 Jan 2026 16:33:06 +1100
Subject: [PATCH 100/170] docs(#3088): move all nvim-tree-api to generated doc

---
 doc/nvim-tree-lua.txt                  | 508 +++++--------------------
 lua/nvim-tree/_meta/config/actions.lua |   2 +-
 lua/nvim-tree/api/init.lua             |  75 ++++
 lua/nvim-tree/api/node.lua             |  49 ---
 scripts/gen_vimdoc_config.lua          |   2 +
 5 files changed, 167 insertions(+), 469 deletions(-)

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 9fabb6858fb..f0e9665effc 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -574,367 +574,6 @@ Following is the default configuration. See |nvim_tree.Config| for details. >lua
     } -- END_DEFAULT_OPTS
 <
 
-==============================================================================
-API                                                            *nvim-tree-api*
-
-Nvim-tree's public API can be used to access features. e.g. >lua
-    local api = require("nvim-tree.api")
-    api.tree.toggle()
-<
-This module exposes stable functionalities, it is advised to use this in order
-to avoid breaking configurations due to internal breaking changes.
-
-The api is separated in multiple modules, which can be accessed with
-`api..`
-
-Functions accepting {node} as their first argument will use the node under the
-cursor when that argument is not present or nil.
-
-
-==============================================================================
-API: Node                                                 *nvim-tree-api.node*
-
-node.open.edit({node}, {opts})                *nvim-tree-api.node.open.edit()*
-    File:   open as per |nvim_tree.Config.Actions.OpenFile|
-    Folder: expand or collapse
-    Root:   change directory up
-
-    Parameters: ~
-      • {node} (Node|nil) file or folder
-      • {opts} (table) optional parameters
-
-    Options: ~
-      • {quit_on_open} (boolean) quits the tree when opening the file
-      • {focus} (boolean) keep focus in the tree when opening the file
-
-                               *nvim-tree-api.node.open.replace_tree_buffer()*
-node.open.replace_tree_buffer({node})
-    |nvim-tree-api.node.open.edit()|, file will be opened in place: in the
-    nvim-tree window.
-
-                                  *nvim-tree-api.node.open.no_window_picker()*
-node.open.no_window_picker({node}, {opts})
-    |nvim-tree-api.node.open.edit()|, window picker will be bypassed.
-
-    Parameters: ~
-      • {node} (Node|nil) file or folder
-      • {opts} (table) optional parameters
-
-    Options: ~
-      • {quit_on_open} (boolean) quits the tree when opening the file
-      • {focus} (boolean) keep focus in the tree when opening the file
-
-node.open.vertical({node}, {opts})                *nvim-tree-api.node.open.vertical()*
-    |nvim-tree-api.node.open.edit()|, file will be opened in a new vertical split.
-
-    Parameters: ~
-      • {node} (Node|nil) file or folder
-      • {opts} (table) optional parameters
-
-    Options: ~
-      • {quit_on_open} (boolean) quits the tree when opening the file
-      • {focus} (boolean) keep focus in the tree when opening the file
-
-                                *nvim-tree-api.node.open.vertical_no_picker()*
-node.open.vertical_no_picker({node}, {opts})
-    |nvim-tree-api.node.open.vertical()|, window picker will be bypassed.
-
-    Parameters: ~
-      • {node} (Node|nil) file or folder
-      • {opts} (table) optional parameters
-
-    Options: ~
-      • {quit_on_open} (boolean) quits the tree when opening the file
-      • {focus} (boolean) keep focus in the tree when opening the file
-
-node.open.horizontal({node}, {opts})            *nvim-tree-api.node.open.horizontal()*
-    |nvim-tree-api.node.open.edit()|, file will be opened in a new horizontal split.
-
-    Parameters: ~
-      • {node} (Node|nil) file or folder
-      • {opts} (table) optional parameters
-
-    Options: ~
-      • {quit_on_open} (boolean) quits the tree when opening the file
-      • {focus} (boolean) keep focus in the tree when opening the file
-
-                              *nvim-tree-api.node.open.horizontal_no_picker()*
-node.open.horizontal_no_picker({node}, {opts})
-    |nvim-tree-api.node.open.horizontal()|, window picker will be bypassed.
-
-    Parameters: ~
-      • {node} (Node|nil) file or folder
-      • {opts} (table) optional parameters
-
-    Options: ~
-      • {quit_on_open} (boolean) quits the tree when opening the file
-      • {focus} (boolean) keep focus in the tree when opening the file
-
-                                *nvim-tree-api.node.open.toggle_group_empty()*
-node.open.toggle_group_empty({node}, {opts})
-    Toggle |nvim_tree.Config.Renderer| {group_empty} for a specific folder.
-    Does nothing on files.
-    Needs |nvim_tree.Config.Renderer| {group_empty} set.
-
-    Parameters: ~
-      • {node} (Node|nil) file or folder
-      • {opts} (table) optional parameters
-
-    Options: ~
-      • {quit_on_open} (boolean) quits the tree when opening the file
-      • {focus} (boolean) keep focus in the tree when opening the file
-
-node.open.drop({node})                        *nvim-tree-api.node.open.drop()*
-    Switch to window with selected file if it exists.
-    Open file otherwise.
-    See: `:h :drop`.
-
-    File:   open file using `:drop`
-    Folder: expand or collapse
-    Root:   change directory up
-
-node.open.tab({node}, {opts})                          *nvim-tree-api.node.open.tab()*
-    |nvim-tree-api.node.open.edit()|, file will be opened in a new tab.
-
-    Parameters: ~
-      • {node} (Node|nil) file or folder
-      • {opts} (table) optional parameters
-
-    Options: ~
-      • {quit_on_open} (boolean) quits the tree when opening the file
-      • {focus} (boolean) keep focus in the tree when opening the file
-
-                                          *nvim-tree-api.node.open.tab_drop()*
-node.open.tab_drop({node})
-    Switch to tab containing window with selected file if it exists.
-    Open file in new tab otherwise.
-
-    File:   open file using `tab :drop`
-    Folder: expand or collapse
-    Root:   change directory up
-
-node.open.preview({node}, {opts})                  *nvim-tree-api.node.open.preview()*
-    |nvim-tree-api.node.open.edit()|, file buffer will have |'bufhidden'| set to `delete`.
-
-    Parameters: ~
-      • {node} (Node|nil) file or folder
-      • {opts} (table) optional parameters
-
-    Options: ~
-      • {quit_on_open} (boolean) quits the tree when opening the file
-      • {focus} (boolean) keep focus in the tree when opening the file
-
-                                 *nvim-tree-api.node.open.preview_no_picker()*
-node.open.preview_no_picker({node}, {opts})
-    |nvim-tree-api.node.open.edit()|, file buffer will have |'bufhidden'| set to `delete`.
-    window picker will be bypassed.
-
-    Parameters: ~
-      • {node} (Node|nil) file or folder
-      • {opts} (table) optional parameters
-
-    Options: ~
-      • {quit_on_open} (boolean) quits the tree when opening the file
-      • {focus} (boolean) keep focus in the tree when opening the file
-
-node.navigate.git.next({node})        *nvim-tree-api.node.navigate.git.next()*
-    Navigate to the next item showing git status.
-
-                            *nvim-tree-api.node.navigate.git.next_recursive()*
-node.navigate.git.next_recursive({node})
-    Alternative to |nvim-tree-api.node.navigate.git.next()| that navigates to
-    the next file showing git status, recursively.
-    Needs |nvim_tree.Config.Git| {show_on_dirs} set.
-
-                      *nvim-tree-api.node.navigate.git.next_skip_gitignored()*
-node.navigate.git.next_skip_gitignored({node})
-    Same as |nvim-tree-api.node.navigate.git.next()|, but skips gitignored files.
-
-node.navigate.git.prev({node})        *nvim-tree-api.node.navigate.git.prev()*
-    Navigate to the previous item showing git status.
-
-                      *nvim-tree-api.node.navigate.git.prev_recursive()*
-node.navigate.git.prev_recursive({node})
-    Alternative to |nvim-tree-api.node.navigate.git.prev()| that navigates to
-    the previous file showing git status, recursively.
-    Needs |nvim_tree.Config.Git| {show_on_dirs} set.
-
-                      *nvim-tree-api.node.navigate.git.prev_skip_gitignored()*
-node.navigate.git.prev_skip_gitignored({node})
-    same as |nvim-tree-api.node.navigate.git.prev()|, but skips gitignored files.
-
-                              *nvim-tree-api.node.navigate.diagnostics.next()*
-node.navigate.diagnostics.next({node})
-    Navigate to the next item showing diagnostic status.
-
-                    *nvim-tree-api.node.navigate.diagnostics.next_recursive()*
-node.navigate.diagnostics.next_recursive({node})
-    Alternative to |nvim-tree-api.node.navigate.diagnostics.next()| that
-    navigates to the next file showing diagnostic status, recursively.
-    Needs |nvim_tree.Config.Diagnostics| {show_on_dirs} set.
-
-                              *nvim-tree-api.node.navigate.diagnostics.prev()*
-node.navigate.diagnostics.prev({node})
-    Navigate to the next item showing diagnostic status.
-
-                    *nvim-tree-api.node.navigate.diagnostics.prev_recursive()*
-node.navigate.diagnostics.prev_recursive({node})
-    Alternative to |nvim-tree-api.node.navigate.diagnostics.prev()| that
-    navigates to the previous file showing diagnostic status, recursively.
-    Needs |nvim_tree.Config.Diagnostics| {show_on_dirs} set.
-
-                                   *nvim-tree-api.node.navigate.opened.next()*
-node.navigate.opened.next({node})
-    Navigate to the next |bufloaded()| item.
-    See |nvim_tree.Config.Renderer| {highlight_opened_files}
-
-                                   *nvim-tree-api.node.navigate.opened.prev()*
-node.navigate.opened.prev({node})
-    Navigate to the previous |bufloaded()| item.
-    See |nvim_tree.Config.Renderer| {highlight_opened_files}
-
-                                  *nvim-tree-api.node.navigate.sibling.next()*
-node.navigate.sibling.next({node})
-    Navigate to the next node in the current node's folder, wraps.
-
-                                  *nvim-tree-api.node.navigate.sibling.prev()*
-node.navigate.sibling.prev({node})
-    Navigate to the previous node in the current node's folder, wraps.
-
-                                 *nvim-tree-api.node.navigate.sibling.first()*
-node.navigate.sibling.first({node})
-    Navigate to the first node in the current node's folder.
-
-                                  *nvim-tree-api.node.navigate.sibling.last()*
-node.navigate.sibling.last({node})
-    Navigate to the last node in the current node's folder.
-
-                                        *nvim-tree-api.node.navigate.parent()*
-node.navigate.parent({node})
-    Navigate to the parent folder of the current node.
-
-                                  *nvim-tree-api.node.navigate.parent_close()*
-node.navigate.parent_close({node})
-    |nvim-tree-api.node.navigate.parent()|, closing that folder.
-
-node.show_info_popup({node})            *nvim-tree-api.node.show_info_popup()*
-    Open a popup window showing: fullpath, size, accessed, modified, created.
-
-node.run.cmd({node})                            *nvim-tree-api.node.run.cmd()*
-    Enter |cmdline| with the full path of the node and the cursor at the start
-    of the line.
-
-node.run.system({node})                      *nvim-tree-api.node.run.system()*
-    Execute |nvim_tree.Config.SystemOpen|
-
-node.buffer.delete({node}, {opts})        *nvim-tree-api.node.buffer.delete()*
-    Deletes node's related buffer, if one exists.
-    Executes |:bdelete| or |:bdelete|!
-
-    Parameters: ~
-      • {node} (Node|nil) file or folder
-      • {opts} (table) optional parameters
-
-    Options: ~
-      • {force} (boolean) delete even if buffer is modified, default false
-
-node.buffer.wipe({node}, {opts})            *nvim-tree-api.node.buffer.wipe()*
-    Wipes node's related buffer, if one exists.
-    Executes |:bwipe| or |:bwipe|!
-
-    Parameters: ~
-      • {node} (Node|nil) file or folder
-      • {opts} (table) optional parameters
-
-    Options: ~
-      • {force} (boolean) wipe even if buffer is modified, default false
-
-node.expand({node}, {opts})                      *nvim-tree-api.node.expand()*
-    Recursively expand all nodes under a directory or a file's parent
-    directory.
-
-    Parameters: ~
-      • {node} (Node|nil) file or folder
-      • {opts} (ApiTreeExpandOpts) optional parameters
-
-    Options: ~
-      • {expand_until} ((fun(expansion_count: integer, node: Node?): boolean)?)
-            Return true if {node} should be expanded.
-            {expansion_count} is the total number of folders expanded.
-
-node.collapse({node}, {opts})                  *nvim-tree-api.node.collapse()*
-    Collapse the tree under a directory or a file's parent directory.
-
-    Parameters: ~
-      • {node} (Node|nil) file or folder
-      • {opts} (table) optional parameters
-
-    Options: ~
-      • {keep_buffers} (boolean) do not collapse nodes with open buffers.
-
-==============================================================================
-API: Git                                                   *nvim-tree-api.git*
-
-git.reload()                                      *nvim-tree-api.git.reload()*
-    Update the git status of the entire tree.
-
-
-==============================================================================
-API: Live Filter                                   *nvim-tree-api.live_filter*
-
-live_filter.start()                        *nvim-tree-api.live_filter.start()*
-    Enter |nvim-tree-api.live_filter| mode.
-    Opens an input window with |filetype| `"NvimTreeFilter"`
-
-live_filter.clear()                        *nvim-tree-api.live_filter.clear()*
-    Exit |nvim-tree-api.live_filter| mode.
-
-==============================================================================
-API: Marks                                               *nvim-tree-api.marks*
-
-marks.get({node})                                  *nvim-tree-api.marks.get()*
-    Return the node if it is marked.
-
-    Parameters: ~
-      • {node} (Node) folder or file
-
-marks.list()                                      *nvim-tree-api.marks.list()*
-    Retrieve all marked nodes.
-
-    Return: ~
-      (table) marked nodes
-
-marks.toggle({node})                            *nvim-tree-api.marks.toggle()*
-    Toggle node mark.
-
-    Parameters: ~
-      • {node} (Node) folder or file
-
-marks.clear()                                    *nvim-tree-api.marks.clear()*
-    Clear all marks.
-
-marks.bulk.delete()                        *nvim-tree-api.marks.bulk.delete()*
-    Delete all marked. Optionally prompts.
-
-marks.bulk.trash()                          *nvim-tree-api.marks.bulk.trash()*
-    Trash all marked. Optionally prompts.
-
-marks.bulk.move()                            *nvim-tree-api.marks.bulk.move()*
-    Prompts for a directory to move all marked nodes into.
-
-marks.navigate.next()                    *nvim-tree-api.marks.navigate.next()*
-    Navigate to the next marked node, wraps.
-    Opens files as per |nvim_tree.Config.Actions.OpenFile|
-    Works best with |nvim_tree.Config.UpdateFocusedFile| enabled.
-
-marks.navigate.prev()                    *nvim-tree-api.marks.navigate.prev()*
-    As per |nvim-tree-api.marks.navigate.next()|
-
-marks.navigate.select()                *nvim-tree-api.marks.navigate.select()*
-    Prompts for selection of a marked node, sorted by absolute paths.
-    A folder will be focused, a file will be opened.
-
-
 ==============================================================================
 Mappings                                                  *nvim-tree-mappings*
 
@@ -1447,10 +1086,10 @@ configurations for different types of prompts.
     send to trash during |nvim_tree.api.fs.trash()|
 
 - `nvimtree_bulk_delete`
-    delete all bookmarked during |nvim-tree-api.marks.bulk.delete()|
+    delete all bookmarked during |nvim_tree.api.marks.bulk.delete()|
 
 - `nvimtree_bulk_trash`
-    send all bookmarked to trash during |nvim-tree-api.marks.bulk.trash()|
+    send all bookmarked to trash during |nvim_tree.api.marks.bulk.trash()|
 
 ==============================================================================
 Decorators                                              *nvim-tree-decorators*
@@ -2449,7 +2088,7 @@ Class: Config.Actions                               *nvim-tree-config-actions*
 
 *nvim_tree.Config.Actions.ExpandAll*
     Configure |nvim_tree.api.tree.expand_all()| and
-    |nvim-tree-api.node.expand()|
+    |nvim_tree.api.node.expand()|
 
     Fields: ~
       • {max_folder_discovery}?  (`integer`, default: `300`) Limit the number
@@ -2690,6 +2329,92 @@ Class: Config.Log                                       *nvim-tree-config-log*
 
 
 
+==============================================================================
+Lua module: nvim_tree.api                                      *nvim-tree-api*
+
+nvim-tree exposes a public API. This is non breaking, with additions made as
+necessary.
+
+Please do not require or use modules other than `nvim-tree.api`, as internal
+modules are not stable and will change without notice.
+
+The API is separated into multiple modules, which can be accessed via the
+parent `nvim-tree.api` or via `nvim-tree.api.`. The following examples
+are equivalent: >lua
+
+    local api = require("nvim-tree.api")
+    api.tree.reload()
+
+    local tree = require("nvim-tree.api.tree")
+    tree.reload()
+<
+
+Generally, functions accepting {node} as their first argument will use the
+node under the cursor when that argument is not present or nil. e.g. the
+following are functionally identical: >lua
+
+    api.node.open.edit(nil, { focus = true })
+
+    api.node.open.edit(api.tree.get_node_under_cursor(), { focus = true })
+<
+
+
+*nvim_tree.api.DirectoryLinkNode*
+    Extends: |nvim_tree.api.DirectoryNode|
+
+    DirectoryLink
+
+*nvim_tree.api.DirectoryNode*
+    Extends: |nvim_tree.api.Node|
+
+    Directory
+
+    Fields: ~
+      • {has_children}  (`boolean`)
+      • {nodes}         (`nvim_tree.api.Node[]`)
+      • {open}          (`boolean`)
+
+*nvim_tree.api.FileLinkNode*
+    Extends: |nvim_tree.api.FileNode|
+
+    File Link
+
+*nvim_tree.api.FileNode*
+    Extends: |nvim_tree.api.Node|
+
+    File
+
+    Fields: ~
+      • {extension}  (`string`)
+
+*nvim_tree.api.LinkNode*
+    Link mixin
+
+    Fields: ~
+      • {link_to}         (`string`)
+      • {fs_stat_target}  (`uv.fs_stat.result`)
+
+*nvim_tree.api.Node*
+    Base Node, Abstract
+
+    Fields: ~
+      • {type}           (`"file"|"directory"|"link"`) uv.fs_stat.result.type
+      • {absolute_path}  (`string`)
+      • {executable}     (`boolean`)
+      • {fs_stat}        (`uv.fs_stat.result?`)
+      • {git_status}     (`GitNodeStatus?`)
+      • {hidden}         (`boolean`)
+      • {name}           (`string`)
+      • {parent}         (`nvim_tree.api.DirectoryNode?`)
+      • {diag_severity}  (`lsp.DiagnosticSeverity?`)
+
+*nvim_tree.api.RootNode*
+    Extends: |nvim_tree.api.DirectoryNode|
+
+    Root Directory
+
+
+
 ==============================================================================
 Lua module: nvim_tree.api.commands                    *nvim-tree-api-commands*
 
@@ -2922,61 +2647,6 @@ toggle({node})                                  *nvim_tree.api.marks.toggle()*
 ==============================================================================
 Lua module: nvim_tree.api.node                            *nvim-tree-api-node*
 
-*nvim_tree.api.DirectoryLinkNode*
-    Extends: |nvim_tree.api.DirectoryNode|
-
-    DirectoryLink
-
-*nvim_tree.api.DirectoryNode*
-    Extends: |nvim_tree.api.Node|
-
-    Directory
-
-    Fields: ~
-      • {has_children}  (`boolean`)
-      • {nodes}         (`nvim_tree.api.Node[]`)
-      • {open}          (`boolean`)
-
-*nvim_tree.api.FileLinkNode*
-    Extends: |nvim_tree.api.FileNode|
-
-    File Link
-
-*nvim_tree.api.FileNode*
-    Extends: |nvim_tree.api.Node|
-
-    File
-
-    Fields: ~
-      • {extension}  (`string`)
-
-*nvim_tree.api.LinkNode*
-    Link mixin
-
-    Fields: ~
-      • {link_to}         (`string`)
-      • {fs_stat_target}  (`uv.fs_stat.result`)
-
-*nvim_tree.api.Node*
-    Base Node, Abstract
-
-    Fields: ~
-      • {type}           (`"file"|"directory"|"link"`) uv.fs_stat.result.type
-      • {absolute_path}  (`string`)
-      • {executable}     (`boolean`)
-      • {fs_stat}        (`uv.fs_stat.result?`)
-      • {git_status}     (`GitNodeStatus?`)
-      • {hidden}         (`boolean`)
-      • {name}           (`string`)
-      • {parent}         (`nvim_tree.api.DirectoryNode?`)
-      • {diag_severity}  (`lsp.DiagnosticSeverity?`)
-
-*nvim_tree.api.RootNode*
-    Extends: |nvim_tree.api.DirectoryNode|
-
-    Root Directory
-
-
 nvim_tree.api.node.buffer.delete()        *nvim_tree.api.node.buffer.delete()*
 
 nvim_tree.api.node.buffer.wipe()            *nvim_tree.api.node.buffer.wipe()*
diff --git a/lua/nvim-tree/_meta/config/actions.lua b/lua/nvim-tree/_meta/config/actions.lua
index 5e46edfa133..d741752c365 100644
--- a/lua/nvim-tree/_meta/config/actions.lua
+++ b/lua/nvim-tree/_meta/config/actions.lua
@@ -43,7 +43,7 @@ error("Cannot require a meta file")
 
 
 
----Configure [nvim_tree.api.tree.expand_all()] and [nvim-tree-api.node.expand()]
+---Configure [nvim_tree.api.tree.expand_all()] and [nvim_tree.api.node.expand()]
 ---@class nvim_tree.Config.Actions.ExpandAll
 ---
 ---Limit the number of folders being explored when expanding every folder. Avoids hanging Nvim when running this action on very large folders.
diff --git a/lua/nvim-tree/api/init.lua b/lua/nvim-tree/api/init.lua
index 6123c9c8d44..68743966b2a 100644
--- a/lua/nvim-tree/api/init.lua
+++ b/lua/nvim-tree/api/init.lua
@@ -1,3 +1,78 @@
+-- TODO #3088 rename this to nvim-tree/api.lua
+
+---@brief
+---nvim-tree exposes a public API. This is non breaking, with additions made as necessary.
+---
+---Please do not require or use modules other than `nvim-tree.api`, as internal modules are not stable and will change without notice.
+---
+---The API is separated into multiple modules, which can be accessed via the parent `nvim-tree.api` or via `nvim-tree.api.`. The following examples are equivalent:
+---```lua
+---
+---local api = require("nvim-tree.api")
+---api.tree.reload()
+---
+---local tree = require("nvim-tree.api.tree")
+---tree.reload()
+---```
+---
+---Generally, functions accepting {node} as their first argument will use the node under the cursor when that argument is not present or nil. e.g. the following are functionally identical:
+---```lua
+---
+---api.node.open.edit(nil, { focus = true })
+---
+---api.node.open.edit(api.tree.get_node_under_cursor(), { focus = true })
+---```
+
+---
+---Base Node, Abstract
+---
+---@class nvim_tree.api.Node
+---@field type "file" | "directory" | "link" uv.fs_stat.result.type
+---@field absolute_path string
+---@field executable boolean
+---@field fs_stat uv.fs_stat.result?
+---@field git_status GitNodeStatus?
+---@field hidden boolean
+---@field name string
+---@field parent nvim_tree.api.DirectoryNode?
+---@field diag_severity lsp.DiagnosticSeverity?
+
+---
+---File
+---
+---@class nvim_tree.api.FileNode: nvim_tree.api.Node
+---@field extension string
+
+---
+---Directory
+---
+---@class nvim_tree.api.DirectoryNode: nvim_tree.api.Node
+---@field has_children boolean
+---@field nodes nvim_tree.api.Node[]
+---@field open boolean
+
+---
+---Root Directory
+---
+---@class nvim_tree.api.RootNode: nvim_tree.api.DirectoryNode
+
+---
+---Link mixin
+---
+---@class nvim_tree.api.LinkNode
+---@field link_to string
+---@field fs_stat_target uv.fs_stat.result
+
+---
+---File Link
+---
+---@class nvim_tree.api.FileLinkNode: nvim_tree.api.FileNode, nvim_tree.api.LinkNode
+
+---
+---DirectoryLink
+---
+---@class nvim_tree.api.DirectoryLinkNode: nvim_tree.api.DirectoryNode, nvim_tree.api.LinkNode
+
 return {
   events = require("nvim-tree.api.events"),
   filter = require("nvim-tree.api.filter"),
diff --git a/lua/nvim-tree/api/node.lua b/lua/nvim-tree/api/node.lua
index 7f40be04aa3..49ac3f6daa9 100644
--- a/lua/nvim-tree/api/node.lua
+++ b/lua/nvim-tree/api/node.lua
@@ -1,55 +1,6 @@
 ---@meta
 local nvim_tree = { api = { node = { navigate = { sibling = {}, git = {}, diagnostics = {}, opened = {}, }, run = {}, open = {}, buffer = {}, } } }
 
----
----Base Node, Abstract
----
----@class nvim_tree.api.Node
----@field type "file" | "directory" | "link" uv.fs_stat.result.type
----@field absolute_path string
----@field executable boolean
----@field fs_stat uv.fs_stat.result?
----@field git_status GitNodeStatus?
----@field hidden boolean
----@field name string
----@field parent nvim_tree.api.DirectoryNode?
----@field diag_severity lsp.DiagnosticSeverity?
-
----
----File
----
----@class nvim_tree.api.FileNode: nvim_tree.api.Node
----@field extension string
-
----
----Directory
----
----@class nvim_tree.api.DirectoryNode: nvim_tree.api.Node
----@field has_children boolean
----@field nodes nvim_tree.api.Node[]
----@field open boolean
-
----
----Root Directory
----
----@class nvim_tree.api.RootNode: nvim_tree.api.DirectoryNode
-
----
----Link mixin
----
----@class nvim_tree.api.LinkNode
----@field link_to string
----@field fs_stat_target uv.fs_stat.result
-
----
----File Link
----
----@class nvim_tree.api.FileLinkNode: nvim_tree.api.FileNode, nvim_tree.api.LinkNode
-
----
----DirectoryLink
----
----@class nvim_tree.api.DirectoryLinkNode: nvim_tree.api.DirectoryNode, nvim_tree.api.LinkNode
 
 function nvim_tree.api.node.buffer.delete() end
 
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index 97a461f9b9e..da677f15021 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -31,6 +31,8 @@ local modules = {
   { helptag = "nvim-tree-config-experimental",        title = "Class: Config.Experimental",         path = "./lua/nvim_tree/_meta/config/experimental.lua", },
   { helptag = "nvim-tree-config-log",                 title = "Class: Config.Log",                  path = "./lua/nvim_tree/_meta/config/log.lua", },
 
+  { helptag = "nvim-tree-api",                        title = "Lua module: nvim_tree.api",          path = "./lua/nvim_tree/api/init.lua", },
+
   { helptag = "nvim-tree-api-commands",               title = "Lua module: nvim_tree.api.commands", path = "./lua/nvim_tree/api/commands.lua", },
   { helptag = "nvim-tree-api-events",                 title = "Lua module: nvim_tree.api.events",   path = "./lua/nvim_tree/api/events.lua", },
   { helptag = "nvim-tree-api-filter",                 title = "Lua module: nvim_tree.api.filter",   path = "./lua/nvim_tree/api/filter.lua", },

From e9b5ca66445c0b9a4b72ef6f7f3d9064bbcb093c Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sun, 18 Jan 2026 17:15:33 +1100
Subject: [PATCH 101/170] docs(#3088): old api is now impl, use new api

---
 doc/nvim-tree-lua.txt                         |  15 +
 lua/nvim-tree.lua                             |   3 -
 lua/nvim-tree/_meta/api.lua                   |  16 -
 lua/nvim-tree/_meta/api_decorator.lua         |   5 +
 lua/nvim-tree/actions/tree/find-file.lua      |   2 +-
 .../actions/tree/modifiers/collapse.lua       |   6 +-
 .../actions/tree/modifiers/expand.lua         |   6 +-
 lua/nvim-tree/actions/tree/open.lua           |   2 +-
 lua/nvim-tree/actions/tree/resize.lua         |   2 +-
 lua/nvim-tree/actions/tree/toggle.lua         |   2 +-
 lua/nvim-tree/api.lua                         | 523 ++++--------------
 lua/nvim-tree/api/commands.lua                |   2 +-
 lua/nvim-tree/api/events.lua                  |   4 +-
 lua/nvim-tree/api/filter.lua                  |   2 +-
 lua/nvim-tree/api/fs.lua                      |   5 +-
 lua/nvim-tree/api/health.lua                  |   2 +-
 lua/nvim-tree/api/impl.lua                    | 288 ++++++++++
 lua/nvim-tree/api/init.lua                    |  85 ---
 lua/nvim-tree/api/map.lua                     |   2 +-
 lua/nvim-tree/api/marks.lua                   |   2 +-
 lua/nvim-tree/api/node.lua                    |   8 +-
 lua/nvim-tree/api/tree.lua                    |   8 +-
 lua/nvim-tree/commands.lua                    |   4 +-
 lua/nvim-tree/view.lua                        |   2 +-
 scripts/gen_vimdoc_config.lua                 |   2 +-
 25 files changed, 438 insertions(+), 560 deletions(-)
 delete mode 100644 lua/nvim-tree/_meta/api.lua
 create mode 100644 lua/nvim-tree/api/impl.lua
 delete mode 100644 lua/nvim-tree/api/init.lua

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index f0e9665effc..d7dbd9ec510 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -2647,6 +2647,18 @@ toggle({node})                                  *nvim_tree.api.marks.toggle()*
 ==============================================================================
 Lua module: nvim_tree.api.node                            *nvim-tree-api-node*
 
+*ApiNodeDeleteWipeBufferOpts*
+
+    Fields: ~
+      • {force}  (`boolean?`) default false
+
+*NodeEditOpts*
+
+    Fields: ~
+      • {quit_on_open}  (`boolean?`) default false
+      • {focus}         (`boolean?`) default true
+
+
 nvim_tree.api.node.buffer.delete()        *nvim_tree.api.node.buffer.delete()*
 
 nvim_tree.api.node.buffer.wipe()            *nvim_tree.api.node.buffer.wipe()*
@@ -2911,6 +2923,9 @@ toggle({opts})                                   *nvim_tree.api.tree.toggle()*
                   |window-ID|, overrides {current_window}
                 • {find_file}? (`boolean`, default: false) Find the current
                   buffer.
+                • {update_root}? (`boolean`, default: false) Update root
+                  following {find_file}, see
+                  |nvim_tree.Config.UpdateFocusedFile| {update_root}
                 • {focus}? (`boolean`, default: true) Focus the tree when
                   opening.
 
diff --git a/lua/nvim-tree.lua b/lua/nvim-tree.lua
index 351b2993bd7..9d27cee3541 100644
--- a/lua/nvim-tree.lua
+++ b/lua/nvim-tree.lua
@@ -793,9 +793,6 @@ function M.setup(conf)
 
   vim.g.NvimTreeSetup = 1
   vim.api.nvim_exec_autocmds("User", { pattern = "NvimTreeSetup" })
-
-  -- TODO #3088 remove this bootstrap once api/init.lua replaces old api.lua
-  require("nvim-tree.api.init")
 end
 
 vim.g.NvimTreeRequired = 1
diff --git a/lua/nvim-tree/_meta/api.lua b/lua/nvim-tree/_meta/api.lua
deleted file mode 100644
index 3783cef4760..00000000000
--- a/lua/nvim-tree/_meta/api.lua
+++ /dev/null
@@ -1,16 +0,0 @@
----@meta
-error("Cannot require a meta file")
-
---
--- Nodes
---
-
-
---
--- Various Types
---
-
----A string for rendering, with optional highlight groups to apply to it
----@class (exact) nvim_tree.api.HighlightedString
----@field str string
----@field hl string[]
diff --git a/lua/nvim-tree/_meta/api_decorator.lua b/lua/nvim-tree/_meta/api_decorator.lua
index d85fe02fff0..4acca3a9acf 100644
--- a/lua/nvim-tree/_meta/api_decorator.lua
+++ b/lua/nvim-tree/_meta/api_decorator.lua
@@ -12,6 +12,11 @@ local nvim_tree = { api = { decorator = {} } }
 ---Names of builtin decorators or your decorator classes. Builtins are ordered lowest to highest priority.
 ---@alias nvim_tree.api.decorator.Name "Git" | "Opened" | "Hidden" | "Modified" | "Bookmarks" | "Diagnostics" | "Copied" | "Cut" | nvim_tree.api.decorator.UserDecorator
 
+---A string for rendering, with optional highlight groups to apply to it
+---@class (exact) nvim_tree.api.HighlightedString
+---@field str string
+---@field hl string[]
+
 ---Custom decorator, see :help nvim-tree-decorators
 ---
 ---@class (exact) nvim_tree.api.decorator.UserDecorator
diff --git a/lua/nvim-tree/actions/tree/find-file.lua b/lua/nvim-tree/actions/tree/find-file.lua
index 8a05bf6db45..231a56a2bb2 100644
--- a/lua/nvim-tree/actions/tree/find-file.lua
+++ b/lua/nvim-tree/actions/tree/find-file.lua
@@ -6,7 +6,7 @@ local finders_find_file = require("nvim-tree.actions.finders.find-file")
 local M = {}
 
 --- Find file or buffer
----@param opts ApiTreeFindFileOpts|nil|boolean legacy -> opts.buf
+---@param opts nvim_tree.api.tree.find_file.Opts|nil|boolean legacy -> opts.buf
 function M.fn(opts)
   -- legacy arguments
   if type(opts) == "string" then
diff --git a/lua/nvim-tree/actions/tree/modifiers/collapse.lua b/lua/nvim-tree/actions/tree/modifiers/collapse.lua
index 51a15f3d464..614a62fb8b7 100644
--- a/lua/nvim-tree/actions/tree/modifiers/collapse.lua
+++ b/lua/nvim-tree/actions/tree/modifiers/collapse.lua
@@ -26,7 +26,7 @@ end
 
 ---Collapse a node, root if nil
 ---@param node Node?
----@param opts ApiCollapseOpts
+---@param opts nvim_tree.api.tree.collapse.Opts
 local function collapse(node, opts)
   local explorer = core.get_explorer()
   if not explorer then
@@ -60,7 +60,7 @@ local function collapse(node, opts)
 end
 
 
----@param opts ApiCollapseOpts|boolean|nil legacy -> opts.keep_buffers
+---@param opts nvim_tree.api.tree.collapse.Opts|boolean|nil legacy -> opts.keep_buffers
 function M.all(opts)
   -- legacy arguments
   if type(opts) == "boolean" then
@@ -73,7 +73,7 @@ function M.all(opts)
 end
 
 ---@param node Node
----@param opts ApiCollapseOpts?
+---@param opts nvim_tree.api.tree.collapse.Opts?
 function M.node(node, opts)
   collapse(node, opts or {})
 end
diff --git a/lua/nvim-tree/actions/tree/modifiers/expand.lua b/lua/nvim-tree/actions/tree/modifiers/expand.lua
index 44e3fa67baa..0fe725fd1dc 100644
--- a/lua/nvim-tree/actions/tree/modifiers/expand.lua
+++ b/lua/nvim-tree/actions/tree/modifiers/expand.lua
@@ -125,7 +125,7 @@ local function gen_iterator(should_descend)
 end
 
 ---@param node Node?
----@param expand_opts ApiTreeExpandOpts?
+---@param expand_opts nvim_tree.api.tree.expand.Opts?
 local function expand_node(node, expand_opts)
   if not node then
     return
@@ -141,14 +141,14 @@ end
 
 ---Expand the directory node or the root
 ---@param node Node
----@param expand_opts ApiTreeExpandOpts?
+---@param expand_opts nvim_tree.api.tree.expand.Opts?
 function M.all(node, expand_opts)
   expand_node(node and node:as(DirectoryNode) or core.get_explorer(), expand_opts)
 end
 
 ---Expand the directory node or parent node
 ---@param node Node
----@param expand_opts ApiTreeExpandOpts?
+---@param expand_opts nvim_tree.api.tree.expand.Opts?
 function M.node(node, expand_opts)
   if not node then
     return
diff --git a/lua/nvim-tree/actions/tree/open.lua b/lua/nvim-tree/actions/tree/open.lua
index ff2da837b87..48f7d93c7f0 100644
--- a/lua/nvim-tree/actions/tree/open.lua
+++ b/lua/nvim-tree/actions/tree/open.lua
@@ -5,7 +5,7 @@ local finders_find_file = require("nvim-tree.actions.finders.find-file")
 local M = {}
 
 ---Open the tree, focusing if already open.
----@param opts ApiTreeOpenOpts|nil|string legacy -> opts.path
+---@param opts nvim_tree.api.tree.open.Opts|nil|string legacy -> opts.path
 function M.fn(opts)
   -- legacy arguments
   if type(opts) == "string" then
diff --git a/lua/nvim-tree/actions/tree/resize.lua b/lua/nvim-tree/actions/tree/resize.lua
index e8d4e950729..77bb379ea61 100644
--- a/lua/nvim-tree/actions/tree/resize.lua
+++ b/lua/nvim-tree/actions/tree/resize.lua
@@ -3,7 +3,7 @@ local view = require("nvim-tree.view")
 local M = {}
 
 ---Resize the tree, persisting the new size.
----@param opts ApiTreeResizeOpts|nil
+---@param opts nvim_tree.api.tree.resize.Opts|nil
 function M.fn(opts)
   if opts == nil then
     -- reset to config values
diff --git a/lua/nvim-tree/actions/tree/toggle.lua b/lua/nvim-tree/actions/tree/toggle.lua
index 10aa978467e..6fefe089593 100644
--- a/lua/nvim-tree/actions/tree/toggle.lua
+++ b/lua/nvim-tree/actions/tree/toggle.lua
@@ -5,7 +5,7 @@ local finders_find_file = require("nvim-tree.actions.finders.find-file")
 local M = {}
 
 ---Toggle the tree.
----@param opts ApiTreeToggleOpts|nil|boolean legacy -> opts.find_file
+---@param opts nvim_tree.api.tree.toggle.Opts|nil|boolean legacy -> opts.find_file
 ---@param no_focus string|nil legacy -> opts.focus
 ---@param cwd boolean|nil legacy -> opts.path
 ---@param bang boolean|nil legacy -> opts.update_root
diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index 7bb4f9b925b..bdb0beab289 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -1,450 +1,117 @@
-local core = require("nvim-tree.core")
-local view = require("nvim-tree.view")
-local utils = require("nvim-tree.utils")
-local actions = require("nvim-tree.actions")
-local appearance_hi_test = require("nvim-tree.appearance.hi-test")
-local events = require("nvim-tree.events")
-local help = require("nvim-tree.help")
-local keymap = require("nvim-tree.keymap")
-local notify = require("nvim-tree.notify")
-
-local DirectoryNode = require("nvim-tree.node.directory")
-local FileNode = require("nvim-tree.node.file")
-local FileLinkNode = require("nvim-tree.node.file-link")
-local RootNode = require("nvim-tree.node.root")
-local UserDecorator = require("nvim-tree.renderer.decorator.user")
-
-local Api = {
-  -- tree = {},
-  -- node = {
-  --   navigate = {
-  --     sibling = {},
-  --     git = {},
-  --     diagnostics = {},
-  --     opened = {},
-  --   },
-  --   run = {},
-  --   open = {},
-  --   buffer = {},
-  -- },
-  -- events = {},
-  -- marks = {
-  --   bulk = {},
-  --   navigate = {},
-  -- },
-  -- fs = {
-  --   copy = {},
-  -- },
-  -- git = {},
-  -- live_filter = {},
-  -- config = {
-  --   mappings = {},
-  -- },
-  -- commands = {},
-  -- diagnostics = {},
-  decorator = {},
-}
-
----Print error when setup not called.
----@param fn fun(...): any
----@return fun(...): any
-local function wrap(fn)
-  return function(...)
-    if vim.g.NvimTreeSetup == 1 then
-      return fn(...)
-    else
-      notify.error("nvim-tree setup not called")
-    end
-  end
-end
-
----Invoke a method on the singleton explorer.
----Print error when setup not called.
----@param explorer_method string explorer method name
----@return fun(...): any
-local function wrap_explorer(explorer_method)
-  return wrap(function(...)
-    local explorer = core.get_explorer()
-    if explorer then
-      return explorer[explorer_method](explorer, ...)
-    end
-  end)
-end
-
----Inject the node as the first argument if present otherwise do nothing.
----@param fn fun(node: Node, ...): any
----@return fun(node: Node?, ...): any
-local function wrap_node(fn)
-  return function(node, ...)
-    node = node or wrap_explorer("get_node_at_cursor")()
-    if node then
-      return fn(node, ...)
-    end
-  end
-end
-
----Inject the node or nil as the first argument if absent.
----@param fn fun(node: Node?, ...): any
----@return fun(node: Node?, ...): any
-local function wrap_node_or_nil(fn)
-  return function(node, ...)
-    node = node or wrap_explorer("get_node_at_cursor")()
-    return fn(node, ...)
-  end
-end
-
----Invoke a member's method on the singleton explorer.
----Print error when setup not called.
----@param explorer_member string explorer member name
----@param member_method string method name to invoke on member
----@param ... any passed to method
----@return fun(...): any
-local function wrap_explorer_member_args(explorer_member, member_method, ...)
-  local method_args = ...
-  return wrap(function(...)
-    local explorer = core.get_explorer()
-    if explorer then
-      return explorer[explorer_member][member_method](explorer[explorer_member], method_args, ...)
-    end
-  end)
-end
-
----Invoke a member's method on the singleton explorer.
----Print error when setup not called.
----@param explorer_member string explorer member name
----@param member_method string method name to invoke on member
----@return fun(...): any
-local function wrap_explorer_member(explorer_member, member_method)
-  return wrap(function(...)
-    local explorer = core.get_explorer()
-    if explorer then
-      return explorer[explorer_member][member_method](explorer[explorer_member], ...)
-    end
-  end)
-end
-
-function Api.hydrate_tree(tree)
-  Api.tree = tree
-
----@class ApiTreeOpenOpts
----@field path string|nil path
----@field current_window boolean|nil default false
----@field winid number|nil
----@field find_file boolean|nil default false
----@field update_root boolean|nil default false
-
-Api.tree.open = wrap(actions.tree.open.fn)
-Api.tree.focus = Api.tree.open
-
----@class ApiTreeToggleOpts
----@field path string|nil
----@field current_window boolean|nil default false
----@field winid number|nil
----@field find_file boolean|nil default false
----@field update_root boolean|nil default false
----@field focus boolean|nil default true
-
-Api.tree.toggle = wrap(actions.tree.toggle.fn)
-Api.tree.close = wrap(view.close)
-Api.tree.close_in_this_tab = wrap(view.close_this_tab_only)
-Api.tree.close_in_all_tabs = wrap(view.close_all_tabs)
-Api.tree.reload = wrap_explorer("reload_explorer")
-
----@class ApiTreeResizeOpts
----@field width string|function|number|table|nil
----@field absolute number|nil
----@field relative number|nil
-
-Api.tree.resize = wrap(actions.tree.resize.fn)
-
-Api.tree.change_root = wrap(function(...)
-  require("nvim-tree").change_dir(...)
-end)
-
-Api.tree.change_root_to_node = wrap_node(function(node)
-  if node.name == ".." or node:is(RootNode) then
-    actions.root.change_dir.fn("..")
-    return
-  end
-
-  if node:is(FileNode) and node.parent ~= nil then
-    actions.root.change_dir.fn(node.parent:last_group_node().absolute_path)
-    return
-  end
-
-  if node:is(DirectoryNode) then
-    actions.root.change_dir.fn(node:last_group_node().absolute_path)
-    return
-  end
-end)
-
-Api.tree.change_root_to_parent = wrap_node(wrap_explorer("dir_up"))
-Api.tree.get_node_under_cursor = wrap_explorer("get_node_at_cursor")
-Api.tree.get_nodes = wrap_explorer("get_nodes")
-
----@class ApiTreeFindFileOpts
----@field buf string|number|nil
----@field open boolean|nil default false
----@field current_window boolean|nil default false
----@field winid number|nil
----@field update_root boolean|nil default false
----@field focus boolean|nil default false
-
-Api.tree.find_file = wrap(actions.tree.find_file.fn)
-Api.tree.search_node = wrap(actions.finders.search_node.fn)
-
----@class ApiCollapseOpts
----@field keep_buffers boolean|nil default false
-
-Api.tree.collapse_all = wrap(actions.tree.modifiers.collapse.all)
-
----@class ApiTreeExpandOpts
----@field expand_until (fun(expansion_count: integer, node: Node): boolean)|nil
-
-Api.tree.expand_all = wrap_node(actions.tree.modifiers.expand.all)
-Api.tree.toggle_enable_filters = wrap_explorer_member("filters", "toggle")
-Api.tree.toggle_gitignore_filter = wrap_explorer_member_args("filters", "toggle", "git_ignored")
-Api.tree.toggle_git_clean_filter = wrap_explorer_member_args("filters", "toggle", "git_clean")
-Api.tree.toggle_no_buffer_filter = wrap_explorer_member_args("filters", "toggle", "no_buffer")
-Api.tree.toggle_custom_filter = wrap_explorer_member_args("filters", "toggle", "custom")
-Api.tree.toggle_hidden_filter = wrap_explorer_member_args("filters", "toggle", "dotfiles")
-Api.tree.toggle_no_bookmark_filter = wrap_explorer_member_args("filters", "toggle", "no_bookmark")
-Api.tree.toggle_help = wrap(help.toggle)
-Api.tree.is_tree_buf = wrap(utils.is_nvim_tree_buf)
-
----@class ApiTreeIsVisibleOpts
----@field tabpage number|nil
----@field any_tabpage boolean|nil default false
-
-Api.tree.is_visible = wrap(view.is_visible)
-
----@class ApiTreeWinIdOpts
----@field tabpage number|nil default nil
-
-Api.tree.winid = wrap(view.winid)
-
-Api.tree.reload_git = wrap_explorer("reload_git")
-
--- TODO #3088 legacy mappings have to go somewhere
-Api.git = {
-  reload = Api.tree.reload_git
-}
-
-end
-
-function Api.hydrate_fs(fs)
-  Api.fs = fs
-
-Api.fs.create = wrap_node_or_nil(actions.fs.create_file.fn)
-Api.fs.remove = wrap_node(actions.fs.remove_file.fn)
-Api.fs.trash = wrap_node(actions.fs.trash.fn)
-Api.fs.rename_node = wrap_node(actions.fs.rename_file.fn(":t"))
-Api.fs.rename = wrap_node(actions.fs.rename_file.fn(":t"))
-Api.fs.rename_sub = wrap_node(actions.fs.rename_file.fn(":p:h"))
-Api.fs.rename_basename = wrap_node(actions.fs.rename_file.fn(":t:r"))
-Api.fs.rename_full = wrap_node(actions.fs.rename_file.fn(":p"))
-Api.fs.cut = wrap_node(wrap_explorer_member("clipboard", "cut"))
-Api.fs.paste = wrap_node(wrap_explorer_member("clipboard", "paste"))
-Api.fs.clear_clipboard = wrap_explorer_member("clipboard", "clear_clipboard")
-Api.fs.print_clipboard = wrap_explorer_member("clipboard", "print_clipboard")
-Api.fs.copy.node = wrap_node(wrap_explorer_member("clipboard", "copy"))
-Api.fs.copy.absolute_path = wrap_node(wrap_explorer_member("clipboard", "copy_absolute_path"))
-Api.fs.copy.filename = wrap_node(wrap_explorer_member("clipboard", "copy_filename"))
-Api.fs.copy.basename = wrap_node(wrap_explorer_member("clipboard", "copy_basename"))
-Api.fs.copy.relative_path = wrap_node(wrap_explorer_member("clipboard", "copy_path"))
-
-end
+-- TODO #3088 rename this to nvim-tree/api.lua
 
+---@brief
+---nvim-tree exposes a public API. This is non breaking, with additions made as necessary.
 ---
----@class NodeEditOpts
----@field quit_on_open boolean|nil default false
----@field focus boolean|nil default true
-
----@param mode string
----@param node Node
----@param edit_opts NodeEditOpts?
-local function edit(mode, node, edit_opts)
-  local file_link = node:as(FileLinkNode)
-  local path = file_link and file_link.link_to or node.absolute_path
-  local cur_tabpage = vim.api.nvim_get_current_tabpage()
-
-  actions.node.open_file.fn(mode, path)
-
-  edit_opts = edit_opts or {}
-
-  local mode_unsupported_quit_on_open = mode == "drop" or mode == "tab_drop" or mode == "edit_in_place"
-  if not mode_unsupported_quit_on_open and edit_opts.quit_on_open then
-    view.close(cur_tabpage)
-  end
-
-  local mode_unsupported_focus = mode == "drop" or mode == "tab_drop" or mode == "edit_in_place"
-  local focus = edit_opts.focus == nil or edit_opts.focus == true
-  if not mode_unsupported_focus and not focus then
-    -- if mode == "tabnew" a new tab will be opened and we need to focus back to the previous tab
-    if mode == "tabnew" then
-      vim.cmd(":tabprev")
-    end
-    view.focus()
-  end
-end
-
----@param mode string
----@param toggle_group boolean?
----@return fun(node: Node, edit_opts: NodeEditOpts?)
-local function open_or_expand_or_dir_up(mode, toggle_group)
-  ---@param node Node
-  ---@param edit_opts NodeEditOpts?
-  return function(node, edit_opts)
-    local root = node:as(RootNode)
-    local dir = node:as(DirectoryNode)
-
-    if root or node.name == ".." then
-      actions.root.change_dir.fn("..")
-    elseif dir then
-      dir:expand_or_collapse(toggle_group)
-    elseif not toggle_group then
-      edit(mode, node, edit_opts)
-    end
-  end
-end
-
-function Api.hydrate_node(n)
-  Api.node = n
-
-Api.node.open.edit = wrap_node(open_or_expand_or_dir_up("edit"))
-Api.node.open.drop = wrap_node(open_or_expand_or_dir_up("drop"))
-Api.node.open.tab_drop = wrap_node(open_or_expand_or_dir_up("tab_drop"))
-Api.node.open.replace_tree_buffer = wrap_node(open_or_expand_or_dir_up("edit_in_place"))
-Api.node.open.no_window_picker = wrap_node(open_or_expand_or_dir_up("edit_no_picker"))
-Api.node.open.vertical = wrap_node(open_or_expand_or_dir_up("vsplit"))
-Api.node.open.vertical_no_picker = wrap_node(open_or_expand_or_dir_up("vsplit_no_picker"))
-Api.node.open.horizontal = wrap_node(open_or_expand_or_dir_up("split"))
-Api.node.open.horizontal_no_picker = wrap_node(open_or_expand_or_dir_up("split_no_picker"))
-Api.node.open.tab = wrap_node(open_or_expand_or_dir_up("tabnew"))
-Api.node.open.toggle_group_empty = wrap_node(open_or_expand_or_dir_up("toggle_group_empty", true))
-Api.node.open.preview = wrap_node(open_or_expand_or_dir_up("preview"))
-Api.node.open.preview_no_picker = wrap_node(open_or_expand_or_dir_up("preview_no_picker"))
-
-Api.node.show_info_popup = wrap_node(actions.node.file_popup.toggle_file_info)
-Api.node.run.cmd = wrap_node(actions.node.run_command.run_file_command)
-Api.node.run.system = wrap_node(actions.node.system_open.fn)
-
-Api.node.navigate.sibling.next = wrap_node(actions.moves.sibling.fn("next"))
-Api.node.navigate.sibling.prev = wrap_node(actions.moves.sibling.fn("prev"))
-Api.node.navigate.sibling.first = wrap_node(actions.moves.sibling.fn("first"))
-Api.node.navigate.sibling.last = wrap_node(actions.moves.sibling.fn("last"))
-Api.node.navigate.parent = wrap_node(actions.moves.parent.fn(false))
-Api.node.navigate.parent_close = wrap_node(actions.moves.parent.fn(true))
-Api.node.navigate.git.next = wrap_node(actions.moves.item.fn({ where = "next", what = "git" }))
-Api.node.navigate.git.next_skip_gitignored = wrap_node(actions.moves.item.fn({ where = "next", what = "git", skip_gitignored = true }))
-Api.node.navigate.git.next_recursive = wrap_node(actions.moves.item.fn({ where = "next", what = "git", recurse = true }))
-Api.node.navigate.git.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "git" }))
-Api.node.navigate.git.prev_skip_gitignored = wrap_node(actions.moves.item.fn({ where = "prev", what = "git", skip_gitignored = true }))
-Api.node.navigate.git.prev_recursive = wrap_node(actions.moves.item.fn({ where = "prev", what = "git", recurse = true }))
-Api.node.navigate.diagnostics.next = wrap_node(actions.moves.item.fn({ where = "next", what = "diag" }))
-Api.node.navigate.diagnostics.next_recursive = wrap_node(actions.moves.item.fn({ where = "next", what = "diag", recurse = true }))
-Api.node.navigate.diagnostics.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "diag" }))
-Api.node.navigate.diagnostics.prev_recursive = wrap_node(actions.moves.item.fn({ where = "prev", what = "diag", recurse = true }))
-Api.node.navigate.opened.next = wrap_node(actions.moves.item.fn({ where = "next", what = "opened" }))
-Api.node.navigate.opened.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "opened" }))
-
-Api.node.expand = wrap_node(actions.tree.modifiers.expand.node)
-Api.node.collapse = wrap_node(actions.tree.modifiers.collapse.node)
-
----@class ApiNodeDeleteWipeBufferOpts
----@field force boolean|nil default false
-
-Api.node.buffer.delete = wrap_node(function(node, opts)
-  actions.node.buffer.delete(node, opts)
-end)
-Api.node.buffer.wipe = wrap_node(function(node, opts)
-  actions.node.buffer.wipe(node, opts)
-end)
-
-end
+---Please do not require or use modules other than `nvim-tree.api`, as internal modules are not stable and will change without notice.
+---
+---The API is separated into multiple modules, which can be accessed via the parent `nvim-tree.api` or via `nvim-tree.api.`. The following examples are equivalent:
+---```lua
+---
+---local api = require("nvim-tree.api")
+---api.tree.reload()
+---
+---local tree = require("nvim-tree.api.tree")
+---tree.reload()
+---```
+---
+---Generally, functions accepting {node} as their first argument will use the node under the cursor when that argument is not present or nil. e.g. the following are functionally identical:
+---```lua
+---
+---api.node.open.edit(nil, { focus = true })
+---
+---api.node.open.edit(api.tree.get_node_under_cursor(), { focus = true })
+---```
 
--- Api.git.reload = wrap_explorer("reload_git")
+---
+---Base Node, Abstract
+---
+---@class nvim_tree.api.Node
+---@field type "file" | "directory" | "link" uv.fs_stat.result.type
+---@field absolute_path string
+---@field executable boolean
+---@field fs_stat uv.fs_stat.result?
+---@field git_status GitNodeStatus?
+---@field hidden boolean
+---@field name string
+---@field parent nvim_tree.api.DirectoryNode?
+---@field diag_severity lsp.DiagnosticSeverity?
 
-function Api.hydrate_events(ev)
-  Api.events = ev
+---
+---File
+---
+---@class nvim_tree.api.FileNode: nvim_tree.api.Node
+---@field extension string
 
-Api.events.subscribe = events.subscribe
-Api.events.Event = events.Event
+---
+---Directory
+---
+---@class nvim_tree.api.DirectoryNode: nvim_tree.api.Node
+---@field has_children boolean
+---@field nodes nvim_tree.api.Node[]
+---@field open boolean
 
-end
+---
+---Root Directory
+---
+---@class nvim_tree.api.RootNode: nvim_tree.api.DirectoryNode
 
-function Api.hydrate_filter(filter)
-  Api.filter = filter
+---
+---Link mixin
+---
+---@class nvim_tree.api.LinkNode
+---@field link_to string
+---@field fs_stat_target uv.fs_stat.result
 
-Api.filter.live_filter.start = wrap_explorer_member("live_filter", "start_filtering")
-Api.filter.live_filter.clear = wrap_explorer_member("live_filter", "clear_filter")
+---
+---File Link
+---
+---@class nvim_tree.api.FileLinkNode: nvim_tree.api.FileNode, nvim_tree.api.LinkNode
 
--- TODO #3088 legacy mappings have to go somewhere
-Api.live_filter = {
-  start = filter.live_filter.start,
-  clear = filter.live_filter.clear,
+---
+---DirectoryLink
+---
+---@class nvim_tree.api.DirectoryLinkNode: nvim_tree.api.DirectoryNode, nvim_tree.api.LinkNode
+
+local api = {
+  events = require("nvim-tree.api.events"),
+  filter = require("nvim-tree.api.filter"),
+  fs = require("nvim-tree.api.fs"),
+  health = require("nvim-tree.api.health"),
+  map = require("nvim-tree.api.map"),
+  marks = require("nvim-tree.api.marks"),
+  node = require("nvim-tree.api.node"),
+  tree = require("nvim-tree.api.tree"),
 }
 
-end
-
-function Api.hydrate_marks(marks)
-  Api.marks = marks
-
-Api.marks.get = wrap_node(wrap_explorer_member("marks", "get"))
-Api.marks.list = wrap_explorer_member("marks", "list")
-Api.marks.toggle = wrap_node(wrap_explorer_member("marks", "toggle"))
-Api.marks.clear = wrap_explorer_member("marks", "clear")
-Api.marks.bulk.delete = wrap_explorer_member("marks", "bulk_delete")
-Api.marks.bulk.trash = wrap_explorer_member("marks", "bulk_trash")
-Api.marks.bulk.move = wrap_explorer_member("marks", "bulk_move")
-Api.marks.navigate.next = wrap_explorer_member("marks", "navigate_next")
-Api.marks.navigate.prev = wrap_explorer_member("marks", "navigate_prev")
-Api.marks.navigate.select = wrap_explorer_member("marks", "navigate_select")
-
-end
-
-function Api.hydrate_map(map)
-  Api.map = map
 
-Api.map.get_keymap = wrap(keymap.get_keymap)
-Api.map.get_keymap_default = wrap(keymap.get_keymap_default)
-Api.map.default_on_attach = keymap.default_on_attach
-
--- TODO #3088 legacy mappings have to go somewhere
-Api.config = {
+--
+--Legacy mappings
+--
+api.git = {
+  reload = api.tree.reload_git,
+}
+api.live_filter = {
+  start = api.filter.live_filter.start,
+  clear = api.filter.live_filter.clear,
+}
+api.config = {
   mappings = {
-    get_keymap = Api.map.get_keymap,
-    get_keymap_default = Api.map.get_keymap_default,
-    default_on_attach = Api.map.default_on_attach,
+    get_keymap = api.map.get_keymap,
+    get_keymap_default = api.map.get_keymap_default,
+    default_on_attach = api.map.default_on_attach,
   }
 }
-
-end
-
-function Api.hydrate_health(health)
-  Api.health = health
-
-Api.health.hi_test = wrap(appearance_hi_test)
-
--- TODO #3088 legacy mappings have to go somewhere
-Api.diagnostics = {
-  hi_test = Api.health.hi_test,
+api.diagnostics = {
+  hi_test = api.health.hi_test,
 }
 
-end
-
-function Api.hydrate_commands(commands)
-  Api.commands = commands
-
-Api.commands.get = wrap(function()
-  return require("nvim-tree.commands").get()
-end)
-
-end
+-- TODO #3241 create a proper decorator API
+api.decorator = {}
 
 ---Create a decorator class by calling :extend()
 ---See :help nvim-tree-decorators
 ---@type nvim_tree.api.decorator.UserDecorator
-Api.decorator.UserDecorator = UserDecorator --[[@as nvim_tree.api.decorator.UserDecorator]]
+api.decorator.UserDecorator = require("nvim-tree.renderer.decorator.user") --[[@as nvim_tree.api.decorator.UserDecorator]]
 
-return Api
+return api
diff --git a/lua/nvim-tree/api/commands.lua b/lua/nvim-tree/api/commands.lua
index 07facd2affc..b5414f0c7e2 100644
--- a/lua/nvim-tree/api/commands.lua
+++ b/lua/nvim-tree/api/commands.lua
@@ -16,6 +16,6 @@ local nvim_tree = { api = { commands = {} } }
 ---@return nvim_tree.api.commands.Command[]
 function nvim_tree.api.commands.get() end
 
-require("nvim-tree.api").hydrate_commands(nvim_tree.api.commands)
+require("nvim-tree.api.impl").commands(nvim_tree.api.commands)
 
 return nvim_tree.api.commands
diff --git a/lua/nvim-tree/api/events.lua b/lua/nvim-tree/api/events.lua
index 34e4d47a86e..7877b14fc63 100644
--- a/lua/nvim-tree/api/events.lua
+++ b/lua/nvim-tree/api/events.lua
@@ -11,10 +11,8 @@ local nvim_tree = { api = { events = {} } }
 ---@param callback fun(payload: table?)
 function nvim_tree.api.events.subscribe(event_type, callback) end
 
-
 nvim_tree.api.events.Event = events.Event
 
-
-require("nvim-tree.api").hydrate_events(nvim_tree.api.events)
+require("nvim-tree.api.impl").events(nvim_tree.api.events)
 
 return nvim_tree.api.events
diff --git a/lua/nvim-tree/api/filter.lua b/lua/nvim-tree/api/filter.lua
index 4aa6d71369b..784a9d7622d 100644
--- a/lua/nvim-tree/api/filter.lua
+++ b/lua/nvim-tree/api/filter.lua
@@ -11,6 +11,6 @@ function nvim_tree.api.filter.live_filter.start() end
 ---
 function nvim_tree.api.filter.live_filter.clear() end
 
-require("nvim-tree.api").hydrate_filter(nvim_tree.api.filter)
+require("nvim-tree.api.impl").filter(nvim_tree.api.filter)
 
 return nvim_tree.api.filter
diff --git a/lua/nvim-tree/api/fs.lua b/lua/nvim-tree/api/fs.lua
index 83c6f4f277a..206ab393e55 100644
--- a/lua/nvim-tree/api/fs.lua
+++ b/lua/nvim-tree/api/fs.lua
@@ -109,7 +109,6 @@ function nvim_tree.api.fs.rename_sub(node) end
 ---@param node nvim_tree.api.Node
 function nvim_tree.api.fs.trash(node) end
 
-require("nvim-tree.api").hydrate_fs(nvim_tree.api.fs)
+require("nvim-tree.api.impl").fs(nvim_tree.api.fs)
 
-
-return nvim_tree.api.filter
+return nvim_tree.api.fs
diff --git a/lua/nvim-tree/api/health.lua b/lua/nvim-tree/api/health.lua
index dbd90c89d1f..454dfb9217f 100644
--- a/lua/nvim-tree/api/health.lua
+++ b/lua/nvim-tree/api/health.lua
@@ -8,6 +8,6 @@ local nvim_tree = { api = { health = {} } }
 ---
 function nvim_tree.api.health.hi_test() end
 
-require("nvim-tree.api").hydrate_health(nvim_tree.api.health)
+require("nvim-tree.api.impl").health(nvim_tree.api.health)
 
 return nvim_tree.api.health
diff --git a/lua/nvim-tree/api/impl.lua b/lua/nvim-tree/api/impl.lua
new file mode 100644
index 00000000000..034a98aeb9d
--- /dev/null
+++ b/lua/nvim-tree/api/impl.lua
@@ -0,0 +1,288 @@
+local core = require("nvim-tree.core")
+local view = require("nvim-tree.view")
+local utils = require("nvim-tree.utils")
+local actions = require("nvim-tree.actions")
+local appearance_hi_test = require("nvim-tree.appearance.hi-test")
+local help = require("nvim-tree.help")
+local keymap = require("nvim-tree.keymap")
+local notify = require("nvim-tree.notify")
+
+local DirectoryNode = require("nvim-tree.node.directory")
+local FileNode = require("nvim-tree.node.file")
+local FileLinkNode = require("nvim-tree.node.file-link")
+local RootNode = require("nvim-tree.node.root")
+
+local M = {}
+
+---Print error when setup not called.
+---@param fn fun(...): any
+---@return fun(...): any
+local function wrap(fn)
+  return function(...)
+    if vim.g.NvimTreeSetup == 1 then
+      return fn(...)
+    else
+      notify.error("nvim-tree setup not called")
+    end
+  end
+end
+
+---Invoke a method on the singleton explorer.
+---Print error when setup not called.
+---@param explorer_method string explorer method name
+---@return fun(...): any
+local function wrap_explorer(explorer_method)
+  return wrap(function(...)
+    local explorer = core.get_explorer()
+    if explorer then
+      return explorer[explorer_method](explorer, ...)
+    end
+  end)
+end
+
+---Inject the node as the first argument if present otherwise do nothing.
+---@param fn fun(node: Node, ...): any
+---@return fun(node: Node?, ...): any
+local function wrap_node(fn)
+  return function(node, ...)
+    node = node or wrap_explorer("get_node_at_cursor")()
+    if node then
+      return fn(node, ...)
+    end
+  end
+end
+
+---Inject the node or nil as the first argument if absent.
+---@param fn fun(node: Node?, ...): any
+---@return fun(node: Node?, ...): any
+local function wrap_node_or_nil(fn)
+  return function(node, ...)
+    node = node or wrap_explorer("get_node_at_cursor")()
+    return fn(node, ...)
+  end
+end
+
+---Invoke a member's method on the singleton explorer.
+---Print error when setup not called.
+---@param explorer_member string explorer member name
+---@param member_method string method name to invoke on member
+---@param ... any passed to method
+---@return fun(...): any
+local function wrap_explorer_member_args(explorer_member, member_method, ...)
+  local method_args = ...
+  return wrap(function(...)
+    local explorer = core.get_explorer()
+    if explorer then
+      return explorer[explorer_member][member_method](explorer[explorer_member], method_args, ...)
+    end
+  end)
+end
+
+---Invoke a member's method on the singleton explorer.
+---Print error when setup not called.
+---@param explorer_member string explorer member name
+---@param member_method string method name to invoke on member
+---@return fun(...): any
+local function wrap_explorer_member(explorer_member, member_method)
+  return wrap(function(...)
+    local explorer = core.get_explorer()
+    if explorer then
+      return explorer[explorer_member][member_method](explorer[explorer_member], ...)
+    end
+  end)
+end
+
+---@param mode string
+---@param node Node
+---@param edit_opts NodeEditOpts?
+local function edit(mode, node, edit_opts)
+  local file_link = node:as(FileLinkNode)
+  local path = file_link and file_link.link_to or node.absolute_path
+  local cur_tabpage = vim.api.nvim_get_current_tabpage()
+
+  actions.node.open_file.fn(mode, path)
+
+  edit_opts = edit_opts or {}
+
+  local mode_unsupported_quit_on_open = mode == "drop" or mode == "tab_drop" or mode == "edit_in_place"
+  if not mode_unsupported_quit_on_open and edit_opts.quit_on_open then
+    view.close(cur_tabpage)
+  end
+
+  local mode_unsupported_focus = mode == "drop" or mode == "tab_drop" or mode == "edit_in_place"
+  local focus = edit_opts.focus == nil or edit_opts.focus == true
+  if not mode_unsupported_focus and not focus then
+    -- if mode == "tabnew" a new tab will be opened and we need to focus back to the previous tab
+    if mode == "tabnew" then
+      vim.cmd(":tabprev")
+    end
+    view.focus()
+  end
+end
+
+---@param mode string
+---@param toggle_group boolean?
+---@return fun(node: Node, edit_opts: NodeEditOpts?)
+local function open_or_expand_or_dir_up(mode, toggle_group)
+  ---@param node Node
+  ---@param edit_opts NodeEditOpts?
+  return function(node, edit_opts)
+    local root = node:as(RootNode)
+    local dir = node:as(DirectoryNode)
+
+    if root or node.name == ".." then
+      actions.root.change_dir.fn("..")
+    elseif dir then
+      dir:expand_or_collapse(toggle_group)
+    elseif not toggle_group then
+      edit(mode, node, edit_opts)
+    end
+  end
+end
+
+function M.tree(tree)
+  tree.open = wrap(actions.tree.open.fn)
+  tree.focus = tree.open
+  tree.toggle = wrap(actions.tree.toggle.fn)
+  tree.close = wrap(view.close)
+  tree.close_in_this_tab = wrap(view.close_this_tab_only)
+  tree.close_in_all_tabs = wrap(view.close_all_tabs)
+  tree.reload = wrap_explorer("reload_explorer")
+  tree.resize = wrap(actions.tree.resize.fn)
+  tree.change_root = wrap(function(...) require("nvim-tree").change_dir(...) end)
+  tree.change_root_to_parent = wrap_node(wrap_explorer("dir_up"))
+  tree.get_node_under_cursor = wrap_explorer("get_node_at_cursor")
+  tree.get_nodes = wrap_explorer("get_nodes")
+  tree.find_file = wrap(actions.tree.find_file.fn)
+  tree.search_node = wrap(actions.finders.search_node.fn)
+  tree.collapse_all = wrap(actions.tree.modifiers.collapse.all)
+  tree.expand_all = wrap_node(actions.tree.modifiers.expand.all)
+  tree.toggle_enable_filters = wrap_explorer_member("filters", "toggle")
+  tree.toggle_gitignore_filter = wrap_explorer_member_args("filters", "toggle", "git_ignored")
+  tree.toggle_git_clean_filter = wrap_explorer_member_args("filters", "toggle", "git_clean")
+  tree.toggle_no_buffer_filter = wrap_explorer_member_args("filters", "toggle", "no_buffer")
+  tree.toggle_custom_filter = wrap_explorer_member_args("filters", "toggle", "custom")
+  tree.toggle_hidden_filter = wrap_explorer_member_args("filters", "toggle", "dotfiles")
+  tree.toggle_no_bookmark_filter = wrap_explorer_member_args("filters", "toggle", "no_bookmark")
+  tree.toggle_help = wrap(help.toggle)
+  tree.is_tree_buf = wrap(utils.is_nvim_tree_buf)
+  tree.is_visible = wrap(view.is_visible)
+  tree.winid = wrap(view.winid)
+  tree.reload_git = wrap_explorer("reload_git")
+  tree.change_root_to_node = wrap_node(function(node)
+    if node.name == ".." or node:is(RootNode) then
+      actions.root.change_dir.fn("..")
+      return
+    end
+
+    if node:is(FileNode) and node.parent ~= nil then
+      actions.root.change_dir.fn(node.parent:last_group_node().absolute_path)
+      return
+    end
+
+    if node:is(DirectoryNode) then
+      actions.root.change_dir.fn(node:last_group_node().absolute_path)
+      return
+    end
+  end)
+end
+
+function M.fs(fs)
+  fs.create = wrap_node_or_nil(actions.fs.create_file.fn)
+  fs.remove = wrap_node(actions.fs.remove_file.fn)
+  fs.trash = wrap_node(actions.fs.trash.fn)
+  fs.rename_node = wrap_node(actions.fs.rename_file.fn(":t"))
+  fs.rename = wrap_node(actions.fs.rename_file.fn(":t"))
+  fs.rename_sub = wrap_node(actions.fs.rename_file.fn(":p:h"))
+  fs.rename_basename = wrap_node(actions.fs.rename_file.fn(":t:r"))
+  fs.rename_full = wrap_node(actions.fs.rename_file.fn(":p"))
+  fs.cut = wrap_node(wrap_explorer_member("clipboard", "cut"))
+  fs.paste = wrap_node(wrap_explorer_member("clipboard", "paste"))
+  fs.clear_clipboard = wrap_explorer_member("clipboard", "clear_clipboard")
+  fs.print_clipboard = wrap_explorer_member("clipboard", "print_clipboard")
+  fs.copy.node = wrap_node(wrap_explorer_member("clipboard", "copy"))
+  fs.copy.absolute_path = wrap_node(wrap_explorer_member("clipboard", "copy_absolute_path"))
+  fs.copy.filename = wrap_node(wrap_explorer_member("clipboard", "copy_filename"))
+  fs.copy.basename = wrap_node(wrap_explorer_member("clipboard", "copy_basename"))
+  fs.copy.relative_path = wrap_node(wrap_explorer_member("clipboard", "copy_path"))
+end
+
+function M.node(node)
+  node.open.edit = wrap_node(open_or_expand_or_dir_up("edit"))
+  node.open.drop = wrap_node(open_or_expand_or_dir_up("drop"))
+  node.open.tab_drop = wrap_node(open_or_expand_or_dir_up("tab_drop"))
+  node.open.replace_tree_buffer = wrap_node(open_or_expand_or_dir_up("edit_in_place"))
+  node.open.no_window_picker = wrap_node(open_or_expand_or_dir_up("edit_no_picker"))
+  node.open.vertical = wrap_node(open_or_expand_or_dir_up("vsplit"))
+  node.open.vertical_no_picker = wrap_node(open_or_expand_or_dir_up("vsplit_no_picker"))
+  node.open.horizontal = wrap_node(open_or_expand_or_dir_up("split"))
+  node.open.horizontal_no_picker = wrap_node(open_or_expand_or_dir_up("split_no_picker"))
+  node.open.tab = wrap_node(open_or_expand_or_dir_up("tabnew"))
+  node.open.toggle_group_empty = wrap_node(open_or_expand_or_dir_up("toggle_group_empty", true))
+  node.open.preview = wrap_node(open_or_expand_or_dir_up("preview"))
+  node.open.preview_no_picker = wrap_node(open_or_expand_or_dir_up("preview_no_picker"))
+  node.show_info_popup = wrap_node(actions.node.file_popup.toggle_file_info)
+  node.run.cmd = wrap_node(actions.node.run_command.run_file_command)
+  node.run.system = wrap_node(actions.node.system_open.fn)
+  node.navigate.sibling.next = wrap_node(actions.moves.sibling.fn("next"))
+  node.navigate.sibling.prev = wrap_node(actions.moves.sibling.fn("prev"))
+  node.navigate.sibling.first = wrap_node(actions.moves.sibling.fn("first"))
+  node.navigate.sibling.last = wrap_node(actions.moves.sibling.fn("last"))
+  node.navigate.parent = wrap_node(actions.moves.parent.fn(false))
+  node.navigate.parent_close = wrap_node(actions.moves.parent.fn(true))
+  node.navigate.git.next = wrap_node(actions.moves.item.fn({ where = "next", what = "git" }))
+  node.navigate.git.next_skip_gitignored = wrap_node(actions.moves.item.fn({ where = "next", what = "git", skip_gitignored = true }))
+  node.navigate.git.next_recursive = wrap_node(actions.moves.item.fn({ where = "next", what = "git", recurse = true }))
+  node.navigate.git.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "git" }))
+  node.navigate.git.prev_skip_gitignored = wrap_node(actions.moves.item.fn({ where = "prev", what = "git", skip_gitignored = true }))
+  node.navigate.git.prev_recursive = wrap_node(actions.moves.item.fn({ where = "prev", what = "git", recurse = true }))
+  node.navigate.diagnostics.next = wrap_node(actions.moves.item.fn({ where = "next", what = "diag" }))
+  node.navigate.diagnostics.next_recursive = wrap_node(actions.moves.item.fn({ where = "next", what = "diag", recurse = true }))
+  node.navigate.diagnostics.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "diag" }))
+  node.navigate.diagnostics.prev_recursive = wrap_node(actions.moves.item.fn({ where = "prev", what = "diag", recurse = true }))
+  node.navigate.opened.next = wrap_node(actions.moves.item.fn({ where = "next", what = "opened" }))
+  node.navigate.opened.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "opened" }))
+  node.expand = wrap_node(actions.tree.modifiers.expand.node)
+  node.collapse = wrap_node(actions.tree.modifiers.collapse.node)
+  node.buffer.delete = wrap_node(function(n, opts) actions.node.buffer.delete(n, opts) end)
+  node.buffer.wipe = wrap_node(function(n, opts) actions.node.buffer.wipe(n, opts) end)
+end
+
+function M.events(events)
+  events.subscribe = require("nvim-tree.events").subscribe
+  events.Event = require("nvim-tree.events").Event
+end
+
+function M.filter(filter)
+  filter.live_filter.start = wrap_explorer_member("live_filter", "start_filtering")
+  filter.live_filter.clear = wrap_explorer_member("live_filter", "clear_filter")
+end
+
+function M.marks(marks)
+  marks.get = wrap_node(wrap_explorer_member("marks", "get"))
+  marks.list = wrap_explorer_member("marks", "list")
+  marks.toggle = wrap_node(wrap_explorer_member("marks", "toggle"))
+  marks.clear = wrap_explorer_member("marks", "clear")
+  marks.bulk.delete = wrap_explorer_member("marks", "bulk_delete")
+  marks.bulk.trash = wrap_explorer_member("marks", "bulk_trash")
+  marks.bulk.move = wrap_explorer_member("marks", "bulk_move")
+  marks.navigate.next = wrap_explorer_member("marks", "navigate_next")
+  marks.navigate.prev = wrap_explorer_member("marks", "navigate_prev")
+  marks.navigate.select = wrap_explorer_member("marks", "navigate_select")
+end
+
+function M.map(map)
+  map.get_keymap = wrap(keymap.get_keymap)
+  map.get_keymap_default = wrap(keymap.get_keymap_default)
+  map.default_on_attach = keymap.default_on_attach
+end
+
+function M.health(health)
+  health.hi_test = wrap(appearance_hi_test)
+end
+
+function M.commands(commands)
+  commands.get = wrap(function() return require("nvim-tree.commands").get() end)
+end
+
+return M
diff --git a/lua/nvim-tree/api/init.lua b/lua/nvim-tree/api/init.lua
deleted file mode 100644
index 68743966b2a..00000000000
--- a/lua/nvim-tree/api/init.lua
+++ /dev/null
@@ -1,85 +0,0 @@
--- TODO #3088 rename this to nvim-tree/api.lua
-
----@brief
----nvim-tree exposes a public API. This is non breaking, with additions made as necessary.
----
----Please do not require or use modules other than `nvim-tree.api`, as internal modules are not stable and will change without notice.
----
----The API is separated into multiple modules, which can be accessed via the parent `nvim-tree.api` or via `nvim-tree.api.`. The following examples are equivalent:
----```lua
----
----local api = require("nvim-tree.api")
----api.tree.reload()
----
----local tree = require("nvim-tree.api.tree")
----tree.reload()
----```
----
----Generally, functions accepting {node} as their first argument will use the node under the cursor when that argument is not present or nil. e.g. the following are functionally identical:
----```lua
----
----api.node.open.edit(nil, { focus = true })
----
----api.node.open.edit(api.tree.get_node_under_cursor(), { focus = true })
----```
-
----
----Base Node, Abstract
----
----@class nvim_tree.api.Node
----@field type "file" | "directory" | "link" uv.fs_stat.result.type
----@field absolute_path string
----@field executable boolean
----@field fs_stat uv.fs_stat.result?
----@field git_status GitNodeStatus?
----@field hidden boolean
----@field name string
----@field parent nvim_tree.api.DirectoryNode?
----@field diag_severity lsp.DiagnosticSeverity?
-
----
----File
----
----@class nvim_tree.api.FileNode: nvim_tree.api.Node
----@field extension string
-
----
----Directory
----
----@class nvim_tree.api.DirectoryNode: nvim_tree.api.Node
----@field has_children boolean
----@field nodes nvim_tree.api.Node[]
----@field open boolean
-
----
----Root Directory
----
----@class nvim_tree.api.RootNode: nvim_tree.api.DirectoryNode
-
----
----Link mixin
----
----@class nvim_tree.api.LinkNode
----@field link_to string
----@field fs_stat_target uv.fs_stat.result
-
----
----File Link
----
----@class nvim_tree.api.FileLinkNode: nvim_tree.api.FileNode, nvim_tree.api.LinkNode
-
----
----DirectoryLink
----
----@class nvim_tree.api.DirectoryLinkNode: nvim_tree.api.DirectoryNode, nvim_tree.api.LinkNode
-
-return {
-  events = require("nvim-tree.api.events"),
-  filter = require("nvim-tree.api.filter"),
-  fs = require("nvim-tree.api.fs"),
-  health = require("nvim-tree.api.health"),
-  map = require("nvim-tree.api.map"),
-  marks = require("nvim-tree.api.marks"),
-  node = require("nvim-tree.api.node"),
-  tree = require("nvim-tree.api.tree"),
-}
diff --git a/lua/nvim-tree/api/map.lua b/lua/nvim-tree/api/map.lua
index 4f47541a0a1..96cfcc3b7c5 100644
--- a/lua/nvim-tree/api/map.lua
+++ b/lua/nvim-tree/api/map.lua
@@ -19,6 +19,6 @@ function nvim_tree.api.map.get_keymap_default() end
 ---@param bufnr integer use the `bufnr` passed to {on_attach}
 function nvim_tree.api.map.default_on_attach(bufnr) end
 
-require("nvim-tree.api").hydrate_map(nvim_tree.api.map)
+require("nvim-tree.api.impl").map(nvim_tree.api.map)
 
 return nvim_tree.api.map
diff --git a/lua/nvim-tree/api/marks.lua b/lua/nvim-tree/api/marks.lua
index e852c3aeaf3..63f2f2b8ed9 100644
--- a/lua/nvim-tree/api/marks.lua
+++ b/lua/nvim-tree/api/marks.lua
@@ -55,6 +55,6 @@ function nvim_tree.api.marks.navigate.prev() end
 ---
 function nvim_tree.api.marks.navigate.select() end
 
-require("nvim-tree.api").hydrate_marks(nvim_tree.api.marks)
+require("nvim-tree.api.impl").marks(nvim_tree.api.marks)
 
 return nvim_tree.api.marks
diff --git a/lua/nvim-tree/api/node.lua b/lua/nvim-tree/api/node.lua
index 49ac3f6daa9..420b3fea03c 100644
--- a/lua/nvim-tree/api/node.lua
+++ b/lua/nvim-tree/api/node.lua
@@ -1,6 +1,12 @@
 ---@meta
 local nvim_tree = { api = { node = { navigate = { sibling = {}, git = {}, diagnostics = {}, opened = {}, }, run = {}, open = {}, buffer = {}, } } }
 
+---@class ApiNodeDeleteWipeBufferOpts
+---@field force boolean|nil default false
+
+---@class NodeEditOpts
+---@field quit_on_open boolean|nil default false
+---@field focus boolean|nil default true
 
 function nvim_tree.api.node.buffer.delete() end
 
@@ -78,6 +84,6 @@ function nvim_tree.api.node.run.system() end
 
 function nvim_tree.api.node.show_info_popup() end
 
-require("nvim-tree.api").hydrate_node(nvim_tree.api.node)
+require("nvim-tree.api.impl").node(nvim_tree.api.node)
 
 return nvim_tree.api.node
diff --git a/lua/nvim-tree/api/tree.lua b/lua/nvim-tree/api/tree.lua
index b441269020a..ada772571d3 100644
--- a/lua/nvim-tree/api/tree.lua
+++ b/lua/nvim-tree/api/tree.lua
@@ -19,7 +19,7 @@ function nvim_tree.api.tree.open(opts) end
 ---(default: false)
 ---@field current_window? boolean
 ---
----Open the tree in the specified  [window-ID], overrides {current_window}
+---Open the tree in the specified [window-ID], overrides {current_window}
 ---@field winid? integer
 ---
 ---Find the current buffer.
@@ -53,6 +53,10 @@ function nvim_tree.api.tree.toggle(opts) end
 ---(default: false)
 ---@field find_file? boolean
 ---
+---Update root following {find_file}, see [nvim_tree.Config.UpdateFocusedFile] {update_root}
+---(default: false)
+---@field update_root? boolean
+---
 ---Focus the tree when opening.
 ---(default: true)
 ---@field focus? boolean
@@ -279,6 +283,6 @@ function nvim_tree.api.tree.winid(opts) end
 ---
 function nvim_tree.api.tree.reload_git() end
 
-require("nvim-tree.api").hydrate_tree(nvim_tree.api.tree)
+require("nvim-tree.api.impl").tree(nvim_tree.api.tree)
 
 return nvim_tree.api.tree
diff --git a/lua/nvim-tree/commands.lua b/lua/nvim-tree/commands.lua
index 178f2733b61..093254707bd 100644
--- a/lua/nvim-tree/commands.lua
+++ b/lua/nvim-tree/commands.lua
@@ -119,7 +119,7 @@ local CMDS = {
       bar = true,
     },
     command = function()
-      require("nvim-tree.api").tree.collapse_all(false)
+      require("nvim-tree.api").tree.collapse_all({ keep_buffers = false })
     end,
   },
   {
@@ -129,7 +129,7 @@ local CMDS = {
       bar = true,
     },
     command = function()
-      require("nvim-tree.api").tree.collapse_all(true)
+      require("nvim-tree.api").tree.collapse_all({ keep_buffers = true })
     end,
   },
   {
diff --git a/lua/nvim-tree/view.lua b/lua/nvim-tree/view.lua
index 275e68635d0..e1ad5d5fd70 100644
--- a/lua/nvim-tree/view.lua
+++ b/lua/nvim-tree/view.lua
@@ -487,7 +487,7 @@ function M.focus(winnr, open_if_closed)
 end
 
 --- Retrieve the winid of the open tree.
----@param opts ApiTreeWinIdOpts|nil
+---@param opts nvim_tree.api.tree.winid.Opts|nil
 ---@return number|nil winid unlike get_winnr(), this returns nil if the nvim-tree window is not visible
 function M.winid(opts)
   local tabpage = opts and opts.tabpage
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index da677f15021..acdf3df6fb0 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -31,7 +31,7 @@ local modules = {
   { helptag = "nvim-tree-config-experimental",        title = "Class: Config.Experimental",         path = "./lua/nvim_tree/_meta/config/experimental.lua", },
   { helptag = "nvim-tree-config-log",                 title = "Class: Config.Log",                  path = "./lua/nvim_tree/_meta/config/log.lua", },
 
-  { helptag = "nvim-tree-api",                        title = "Lua module: nvim_tree.api",          path = "./lua/nvim_tree/api/init.lua", },
+  { helptag = "nvim-tree-api",                        title = "Lua module: nvim_tree.api",          path = "./lua/nvim_tree/api.lua", },
 
   { helptag = "nvim-tree-api-commands",               title = "Lua module: nvim_tree.api.commands", path = "./lua/nvim_tree/api/commands.lua", },
   { helptag = "nvim-tree-api-events",                 title = "Lua module: nvim_tree.api.events",   path = "./lua/nvim_tree/api/events.lua", },

From cbc97fe0efe438d63f316f50a0807d9449b9613f Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Tue, 20 Jan 2026 12:50:57 +1100
Subject: [PATCH 102/170] docs(#3088): extract api/node.lua functions, doc WIP

---
 doc/nvim-tree-lua.txt      | 234 +++++++++---
 lua/nvim-tree/api.lua      |   6 +-
 lua/nvim-tree/api/impl.lua |   4 +
 lua/nvim-tree/api/node.lua | 706 ++++++++++++++++++++++++++++++++-----
 scripts/help-update.sh     |   3 -
 scripts/lintdoc.sh         |   3 +
 6 files changed, 819 insertions(+), 137 deletions(-)

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index d7dbd9ec510..ccc12042cb6 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -2647,119 +2647,251 @@ toggle({node})                                  *nvim_tree.api.marks.toggle()*
 ==============================================================================
 Lua module: nvim_tree.api.node                            *nvim-tree-api-node*
 
-*ApiNodeDeleteWipeBufferOpts*
+buffer.delete({node}, {opts})             *nvim_tree.api.node.buffer.delete()*
+    Deletes node's related buffer, if one exists. Executes |:bdelete| or
+    |:bdelete|!
 
-    Fields: ~
-      • {force}  (`boolean?`) default false
-
-*NodeEditOpts*
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node`) file
+      • {opts}  (`table?`) A table with the following fields:
+                • {force}? (`boolean`, default: false) Delete even if buffer
+                  is modified.
 
-    Fields: ~
-      • {quit_on_open}  (`boolean?`) default false
-      • {focus}         (`boolean?`) default true
+buffer.wipe({node}, {opts})                 *nvim_tree.api.node.buffer.wipe()*
+    Wipes node's related buffer, if one exists. Executes |:bwipe| or |:bwipe|!
 
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) file
+      • {opts}  (`table?`) optional
+                • {force}? (`boolean`, default: false) Wipe even if buffer is
+                  modified.
 
-nvim_tree.api.node.buffer.delete()        *nvim_tree.api.node.buffer.delete()*
+collapse({node}, {opts})                       *nvim_tree.api.node.collapse()*
+    Collapse the tree under a directory or a file's parent directory.
 
-nvim_tree.api.node.buffer.wipe()            *nvim_tree.api.node.buffer.wipe()*
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
+      • {opts}  (`table?`) optional
+                • {keep_buffers}? (`boolean`, default: false) Do not collapse
+                  nodes with open buffers.
 
-nvim_tree.api.node.collapse()                  *nvim_tree.api.node.collapse()*
+expand({node}, {opts})                           *nvim_tree.api.node.expand()*
 
-nvim_tree.api.node.expand()                      *nvim_tree.api.node.expand()*
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
+      • {opts}  (`table?`) optional
+                • {foo}? (`boolean`) (default: false)
 
                               *nvim_tree.api.node.navigate.diagnostics.next()*
-nvim_tree.api.node.navigate.diagnostics.next()
+navigate.diagnostics.next({node})
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
 
                     *nvim_tree.api.node.navigate.diagnostics.next_recursive()*
-nvim_tree.api.node.navigate.diagnostics.next_recursive()
+navigate.diagnostics.next_recursive({node})
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
 
                               *nvim_tree.api.node.navigate.diagnostics.prev()*
-nvim_tree.api.node.navigate.diagnostics.prev()
+navigate.diagnostics.prev({node})
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
 
                     *nvim_tree.api.node.navigate.diagnostics.prev_recursive()*
-nvim_tree.api.node.navigate.diagnostics.prev_recursive()
+navigate.diagnostics.prev_recursive({node})
 
-                                      *nvim_tree.api.node.navigate.git.next()*
-nvim_tree.api.node.navigate.git.next()
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
+
+navigate.git.next({node})             *nvim_tree.api.node.navigate.git.next()*
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
 
                             *nvim_tree.api.node.navigate.git.next_recursive()*
-nvim_tree.api.node.navigate.git.next_recursive()
+navigate.git.next_recursive({node})
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
 
                       *nvim_tree.api.node.navigate.git.next_skip_gitignored()*
-nvim_tree.api.node.navigate.git.next_skip_gitignored()
+navigate.git.next_skip_gitignored({node})
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
 
-                                      *nvim_tree.api.node.navigate.git.prev()*
-nvim_tree.api.node.navigate.git.prev()
+navigate.git.prev({node})             *nvim_tree.api.node.navigate.git.prev()*
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
 
                             *nvim_tree.api.node.navigate.git.prev_recursive()*
-nvim_tree.api.node.navigate.git.prev_recursive()
+navigate.git.prev_recursive({node})
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
 
                       *nvim_tree.api.node.navigate.git.prev_skip_gitignored()*
-nvim_tree.api.node.navigate.git.prev_skip_gitignored()
+navigate.git.prev_skip_gitignored({node})
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
 
                                    *nvim_tree.api.node.navigate.opened.next()*
-nvim_tree.api.node.navigate.opened.next()
+navigate.opened.next({node})
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
 
                                    *nvim_tree.api.node.navigate.opened.prev()*
-nvim_tree.api.node.navigate.opened.prev()
+navigate.opened.prev({node})
 
-                                        *nvim_tree.api.node.navigate.parent()*
-nvim_tree.api.node.navigate.parent()
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
+
+navigate.parent({node})                 *nvim_tree.api.node.navigate.parent()*
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
 
                                   *nvim_tree.api.node.navigate.parent_close()*
-nvim_tree.api.node.navigate.parent_close()
+navigate.parent_close({node})
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
 
                                  *nvim_tree.api.node.navigate.sibling.first()*
-nvim_tree.api.node.navigate.sibling.first()
+navigate.sibling.first({node})
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
 
                                   *nvim_tree.api.node.navigate.sibling.last()*
-nvim_tree.api.node.navigate.sibling.last()
+navigate.sibling.last({node})
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
 
                                   *nvim_tree.api.node.navigate.sibling.next()*
-nvim_tree.api.node.navigate.sibling.next()
+navigate.sibling.next({node})
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
 
                                   *nvim_tree.api.node.navigate.sibling.prev()*
-nvim_tree.api.node.navigate.sibling.prev()
+navigate.sibling.prev({node})
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
+
+open.drop({node})                             *nvim_tree.api.node.open.drop()*
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
 
-nvim_tree.api.node.open.drop()                *nvim_tree.api.node.open.drop()*
+open.edit({node}, {opts})                     *nvim_tree.api.node.open.edit()*
 
-nvim_tree.api.node.open.edit()                *nvim_tree.api.node.open.edit()*
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
+      • {opts}  (`table?`) optional
+                • {foo}? (`boolean`) (default: false)
+
+open.horizontal({node}, {opts})         *nvim_tree.api.node.open.horizontal()*
 
-                                        *nvim_tree.api.node.open.horizontal()*
-nvim_tree.api.node.open.horizontal()
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
+      • {opts}  (`table?`) optional
+                • {foo}? (`boolean`) (default: false)
 
                               *nvim_tree.api.node.open.horizontal_no_picker()*
-nvim_tree.api.node.open.horizontal_no_picker()
+open.horizontal_no_picker({node}, {opts})
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
+      • {opts}  (`table?`) optional
+                • {foo}? (`boolean`) (default: false)
 
                                   *nvim_tree.api.node.open.no_window_picker()*
-nvim_tree.api.node.open.no_window_picker()
+open.no_window_picker({node}, {opts})
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
+      • {opts}  (`table?`) optional
+                • {foo}? (`boolean`) (default: false)
 
-nvim_tree.api.node.open.preview()          *nvim_tree.api.node.open.preview()*
+open.preview({node}, {opts})               *nvim_tree.api.node.open.preview()*
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
+      • {opts}  (`table?`) optional
+                • {foo}? (`boolean`) (default: false)
 
                                  *nvim_tree.api.node.open.preview_no_picker()*
-nvim_tree.api.node.open.preview_no_picker()
+open.preview_no_picker({node}, {opts})
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
+      • {opts}  (`table?`) optional
+                • {foo}? (`boolean`) (default: false)
 
                                *nvim_tree.api.node.open.replace_tree_buffer()*
-nvim_tree.api.node.open.replace_tree_buffer()
+open.replace_tree_buffer({node})
 
-nvim_tree.api.node.open.tab()                  *nvim_tree.api.node.open.tab()*
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
+
+open.tab({node}, {opts})                       *nvim_tree.api.node.open.tab()*
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
+      • {opts}  (`table?`) optional
+                • {foo}? (`boolean`) (default: false)
 
-nvim_tree.api.node.open.tab_drop()        *nvim_tree.api.node.open.tab_drop()*
+open.tab_drop({node})                     *nvim_tree.api.node.open.tab_drop()*
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
 
                                 *nvim_tree.api.node.open.toggle_group_empty()*
-nvim_tree.api.node.open.toggle_group_empty()
+open.toggle_group_empty({node}, {opts})
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
+      • {opts}  (`table?`) optional
+                • {foo}? (`boolean`) (default: false)
+
+open.vertical({node}, {opts})             *nvim_tree.api.node.open.vertical()*
 
-nvim_tree.api.node.open.vertical()        *nvim_tree.api.node.open.vertical()*
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
+      • {opts}  (`table?`) optional
+                • {foo}? (`boolean`) (default: false)
 
                                 *nvim_tree.api.node.open.vertical_no_picker()*
-nvim_tree.api.node.open.vertical_no_picker()
+open.vertical_no_picker({node}, {opts})
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
+      • {opts}  (`table?`) optional
+                • {foo}? (`boolean`) (default: false)
 
-nvim_tree.api.node.run.cmd()                    *nvim_tree.api.node.run.cmd()*
+run.cmd({node})                                 *nvim_tree.api.node.run.cmd()*
 
-nvim_tree.api.node.run.system()              *nvim_tree.api.node.run.system()*
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
 
-                                        *nvim_tree.api.node.show_info_popup()*
-nvim_tree.api.node.show_info_popup()
+run.system({node})                           *nvim_tree.api.node.run.system()*
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
+
+show_info_popup({node})                 *nvim_tree.api.node.show_info_popup()*
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
 
 
 ==============================================================================
diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index bdb0beab289..0c1dbf5ab31 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -1,5 +1,3 @@
--- TODO #3088 rename this to nvim-tree/api.lua
-
 ---@brief
 ---nvim-tree exposes a public API. This is non breaking, with additions made as necessary.
 ---
@@ -73,6 +71,10 @@
 ---
 ---@class nvim_tree.api.DirectoryLinkNode: nvim_tree.api.DirectoryNode, nvim_tree.api.LinkNode
 
+
+--
+--Load and hydrate all
+--
 local api = {
   events = require("nvim-tree.api.events"),
   filter = require("nvim-tree.api.filter"),
diff --git a/lua/nvim-tree/api/impl.lua b/lua/nvim-tree/api/impl.lua
index 034a98aeb9d..14156cde9b0 100644
--- a/lua/nvim-tree/api/impl.lua
+++ b/lua/nvim-tree/api/impl.lua
@@ -92,6 +92,10 @@ local function wrap_explorer_member(explorer_member, member_method)
   end)
 end
 
+---@class NodeEditOpts
+---@field quit_on_open boolean|nil default false
+---@field focus boolean|nil default true
+
 ---@param mode string
 ---@param node Node
 ---@param edit_opts NodeEditOpts?
diff --git a/lua/nvim-tree/api/node.lua b/lua/nvim-tree/api/node.lua
index 420b3fea03c..0db3cb9fe3a 100644
--- a/lua/nvim-tree/api/node.lua
+++ b/lua/nvim-tree/api/node.lua
@@ -1,88 +1,632 @@
 ---@meta
 local nvim_tree = { api = { node = { navigate = { sibling = {}, git = {}, diagnostics = {}, opened = {}, }, run = {}, open = {}, buffer = {}, } } }
 
----@class ApiNodeDeleteWipeBufferOpts
----@field force boolean|nil default false
 
----@class NodeEditOpts
----@field quit_on_open boolean|nil default false
----@field focus boolean|nil default true
-
-function nvim_tree.api.node.buffer.delete() end
-
-function nvim_tree.api.node.buffer.wipe() end
-
-function nvim_tree.api.node.collapse() end
-
-function nvim_tree.api.node.expand() end
-
-function nvim_tree.api.node.navigate.diagnostics.next() end
-
-function nvim_tree.api.node.navigate.diagnostics.next_recursive() end
-
-function nvim_tree.api.node.navigate.diagnostics.prev() end
-
-function nvim_tree.api.node.navigate.diagnostics.prev_recursive() end
-
-function nvim_tree.api.node.navigate.git.next() end
-
-function nvim_tree.api.node.navigate.git.next_recursive() end
-
-function nvim_tree.api.node.navigate.git.next_skip_gitignored() end
-
-function nvim_tree.api.node.navigate.git.prev() end
-
-function nvim_tree.api.node.navigate.git.prev_recursive() end
-
-function nvim_tree.api.node.navigate.git.prev_skip_gitignored() end
-
-function nvim_tree.api.node.navigate.opened.next() end
-
-function nvim_tree.api.node.navigate.opened.prev() end
-
-function nvim_tree.api.node.navigate.parent() end
-
-function nvim_tree.api.node.navigate.parent_close() end
-
-function nvim_tree.api.node.navigate.sibling.first() end
-
-function nvim_tree.api.node.navigate.sibling.last() end
-
-function nvim_tree.api.node.navigate.sibling.next() end
-
-function nvim_tree.api.node.navigate.sibling.prev() end
-
-function nvim_tree.api.node.open.drop() end
-
-function nvim_tree.api.node.open.edit() end
-
-function nvim_tree.api.node.open.horizontal() end
-
-function nvim_tree.api.node.open.horizontal_no_picker() end
-
-function nvim_tree.api.node.open.no_window_picker() end
-
-function nvim_tree.api.node.open.preview() end
-
-function nvim_tree.api.node.open.preview_no_picker() end
-
-function nvim_tree.api.node.open.replace_tree_buffer() end
-
-function nvim_tree.api.node.open.tab() end
-
-function nvim_tree.api.node.open.tab_drop() end
-
-function nvim_tree.api.node.open.toggle_group_empty() end
-
-function nvim_tree.api.node.open.vertical() end
-
-function nvim_tree.api.node.open.vertical_no_picker() end
-
-function nvim_tree.api.node.run.cmd() end
-
-function nvim_tree.api.node.run.system() end
-
-function nvim_tree.api.node.show_info_popup() end
+---
+---Deletes node's related buffer, if one exists. Executes [:bdelete] or [:bdelete]!
+---
+---@param node nvim_tree.api.Node file
+---@param opts? nvim_tree.api.node.buffer.delete.Opts
+function nvim_tree.api.node.buffer.delete(node, opts) end
+
+---@class nvim_tree.api.node.buffer.delete.Opts optional
+---@inlinedoc
+---
+---Delete even if buffer is modified.
+---(default: false)
+---@field force? boolean
+
+---
+---Wipes node's related buffer, if one exists. Executes [:bwipe] or [:bwipe]!
+---
+---@param node? nvim_tree.api.Node file
+---@param opts? nvim_tree.api.node.buffer.wipe.Opts optional
+function nvim_tree.api.node.buffer.wipe(node, opts) end
+
+---@class nvim_tree.api.node.buffer.wipe.Opts
+---@inlinedoc
+---
+---Wipe even if buffer is modified.
+---(default: false)
+---@field force? boolean
+
+---
+---Collapse the tree under a directory or a file's parent directory.
+---
+---@param node? nvim_tree.api.Node directory or file
+---@param opts? nvim_tree.api.node.collapse.Opts optional
+function nvim_tree.api.node.collapse(node, opts) end
+
+---@class nvim_tree.api.node.collapse.Opts
+---@inlinedoc
+---
+---Do not collapse nodes with open buffers.
+---(default: false)
+---@field keep_buffers? boolean
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+---@param opts? nvim_tree.api.node.expand.Opts optional
+function nvim_tree.api.node.expand(node, opts) end
+
+---@class nvim_tree.api.node.expand.Opts
+---@inlinedoc
+---
+---
+---(default: false)
+---@field foo? boolean
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.diagnostics.next(node) end
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.diagnostics.next_recursive(node) end
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.diagnostics.prev(node) end
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.diagnostics.prev_recursive(node) end
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.git.next(node) end
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.git.next_recursive(node) end
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.git.next_skip_gitignored(node) end
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.git.prev(node) end
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.git.prev_recursive(node) end
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.git.prev_skip_gitignored(node) end
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.opened.next(node) end
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.opened.prev(node) end
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.parent(node) end
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.parent_close(node) end
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.sibling.first(node) end
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.sibling.last(node) end
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.sibling.next(node) end
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.sibling.prev(node) end
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.open.drop(node) end
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+---@param opts? nvim_tree.api.node.open.edit.Opts optional
+function nvim_tree.api.node.open.edit(node, opts) end
+
+---@class nvim_tree.api.node.open.edit.Opts
+---@inlinedoc
+---
+---
+---(default: false)
+---@field foo? boolean
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+---@param opts? nvim_tree.api.node.open.horizontal.Opts optional
+function nvim_tree.api.node.open.horizontal(node, opts) end
+
+---@class nvim_tree.api.node.open.horizontal.Opts
+---@inlinedoc
+---
+---
+---(default: false)
+---@field foo? boolean
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+---@param opts? nvim_tree.api.node.open.horizontal_no_picker.Opts optional
+function nvim_tree.api.node.open.horizontal_no_picker(node, opts) end
+
+---@class nvim_tree.api.node.open.horizontal_no_picker.Opts
+---@inlinedoc
+---
+---
+---(default: false)
+---@field foo? boolean
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+---@param opts? nvim_tree.api.node.open.no_window_picker.Opts optional
+function nvim_tree.api.node.open.no_window_picker(node, opts) end
+
+---@class nvim_tree.api.node.open.no_window_picker.Opts
+---@inlinedoc
+---
+---
+---(default: false)
+---@field foo? boolean
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+---@param opts? nvim_tree.api.node.open.preview.Opts optional
+function nvim_tree.api.node.open.preview(node, opts) end
+
+---@class nvim_tree.api.node.open.preview.Opts
+---@inlinedoc
+---
+---
+---(default: false)
+---@field foo? boolean
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+---@param opts? nvim_tree.api.node.open.preview_no_picker.Opts optional
+function nvim_tree.api.node.open.preview_no_picker(node, opts) end
+
+---@class nvim_tree.api.node.open.preview_no_picker.Opts
+---@inlinedoc
+---
+---
+---(default: false)
+---@field foo? boolean
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.open.replace_tree_buffer(node) end
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+---@param opts? nvim_tree.api.node.open.tab.Opts optional
+function nvim_tree.api.node.open.tab(node, opts) end
+
+---@class nvim_tree.api.node.open.tab.Opts
+---@inlinedoc
+---
+---
+---(default: false)
+---@field foo? boolean
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.open.tab_drop(node) end
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+---@param opts? nvim_tree.api.node.open.toggle_group_empty.Opts optional
+function nvim_tree.api.node.open.toggle_group_empty(node, opts) end
+
+---@class nvim_tree.api.node.open.toggle_group_empty.Opts
+---@inlinedoc
+---
+---
+---(default: false)
+---@field foo? boolean
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+---@param opts? nvim_tree.api.node.open.vertical.Opts optional
+function nvim_tree.api.node.open.vertical(node, opts) end
+
+---@class nvim_tree.api.node.open.vertical.Opts
+---@inlinedoc
+---
+---
+---(default: false)
+---@field foo? boolean
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+---@param opts? nvim_tree.api.node.open.vertical_no_picker.Opts optional
+function nvim_tree.api.node.open.vertical_no_picker(node, opts) end
+
+---@class nvim_tree.api.node.open.vertical_no_picker.Opts
+---@inlinedoc
+---
+---
+---(default: false)
+---@field foo? boolean
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.run.cmd(node) end
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.run.system(node) end
+
+---
+---
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.show_info_popup(node) end
+
+
+
+
+
+-- node.open.edit({node}, {opts})                        *nvim-tree-api.node.open.edit()*
+--     File:   open as per |nvim-tree.actions.open_file|
+--     Folder: expand or collapse
+--     Root:   change directory up
+--
+--     Parameters: ~
+--       • {node} (Node|nil) file or folder
+--       • {opts} (table) optional parameters
+--
+--     Options: ~
+--       • {quit_on_open} (boolean) quits the tree when opening the file
+--       • {focus} (boolean) keep focus in the tree when opening the file
+--
+--                                *nvim-tree-api.node.open.replace_tree_buffer()*
+-- node.open.replace_tree_buffer({node})
+--     |nvim-tree-api.node.edit()|, file will be opened in place: in the
+--     nvim-tree window.
+--
+--                                   *nvim-tree-api.node.open.no_window_picker()*
+-- node.open.no_window_picker({node}, {opts})
+--     |nvim-tree-api.node.edit()|, window picker will never be used as per
+--     |nvim-tree.actions.open_file.window_picker.enable| `false`
+--
+--     Parameters: ~
+--       • {node} (Node|nil) file or folder
+--       • {opts} (table) optional parameters
+--
+--     Options: ~
+--       • {quit_on_open} (boolean) quits the tree when opening the file
+--       • {focus} (boolean) keep focus in the tree when opening the file
+--
+-- node.open.vertical({node}, {opts})                *nvim-tree-api.node.open.vertical()*
+--     |nvim-tree-api.node.edit()|, file will be opened in a new vertical split.
+--
+--     Parameters: ~
+--       • {node} (Node|nil) file or folder
+--       • {opts} (table) optional parameters
+--
+--     Options: ~
+--       • {quit_on_open} (boolean) quits the tree when opening the file
+--       • {focus} (boolean) keep focus in the tree when opening the file
+--
+--                                 *nvim-tree-api.node.open.vertical_no_picker()*
+-- node.open.vertical_no_picker({node}, {opts})
+--     |nvim-tree-api.node.vertical()|, window picker will never be used as per
+--     |nvim-tree.actions.open_file.window_picker.enable| `false`
+--
+--     Parameters: ~
+--       • {node} (Node|nil) file or folder
+--       • {opts} (table) optional parameters
+--
+--     Options: ~
+--       • {quit_on_open} (boolean) quits the tree when opening the file
+--       • {focus} (boolean) keep focus in the tree when opening the file
+--
+-- node.open.horizontal({node}, {opts})            *nvim-tree-api.node.open.horizontal()*
+--     |nvim-tree-api.node.edit()|, file will be opened in a new horizontal split.
+--
+--     Parameters: ~
+--       • {node} (Node|nil) file or folder
+--       • {opts} (table) optional parameters
+--
+--     Options: ~
+--       • {quit_on_open} (boolean) quits the tree when opening the file
+--       • {focus} (boolean) keep focus in the tree when opening the file
+--
+--                               *nvim-tree-api.node.open.horizontal_no_picker()*
+-- node.open.horizontal_no_picker({node}, {opts})
+--     |nvim-tree-api.node.horizontal()|, window picker will never be used as per
+--     |nvim-tree.actions.open_file.window_picker.enable| `false`
+--
+--     Parameters: ~
+--       • {node} (Node|nil) file or folder
+--       • {opts} (table) optional parameters
+--
+--     Options: ~
+--       • {quit_on_open} (boolean) quits the tree when opening the file
+--       • {focus} (boolean) keep focus in the tree when opening the file
+--
+--                                 *nvim-tree-api.node.open.toggle_group_empty()*
+-- node.open.toggle_group_empty({node}, {opts})
+--     Toggle |nvim-tree.renderer.group_empty| for a specific folder.
+--     Does nothing on files.
+--     Needs |nvim-tree.renderer.group_empty| set.
+--
+--     Parameters: ~
+--       • {node} (Node|nil) file or folder
+--       • {opts} (table) optional parameters
+--
+--     Options: ~
+--       • {quit_on_open} (boolean) quits the tree when opening the file
+--       • {focus} (boolean) keep focus in the tree when opening the file
+--
+-- node.open.drop({node})                        *nvim-tree-api.node.open.drop()*
+--     Switch to window with selected file if it exists.
+--     Open file otherwise.
+--     See: `:h :drop`.
+--
+--     File:   open file using `:drop`
+--     Folder: expand or collapse
+--     Root:   change directory up
+--
+-- node.open.tab({node}, {opts})                          *nvim-tree-api.node.open.tab()*
+--     |nvim-tree-api.node.edit()|, file will be opened in a new tab.
+--
+--     Parameters: ~
+--       • {node} (Node|nil) file or folder
+--       • {opts} (table) optional parameters
+--
+--     Options: ~
+--       • {quit_on_open} (boolean) quits the tree when opening the file
+--       • {focus} (boolean) keep focus in the tree when opening the file
+--
+--                                           *nvim-tree-api.node.open.tab_drop()*
+-- node.open.tab_drop({node})
+--     Switch to tab containing window with selected file if it exists.
+--     Open file in new tab otherwise.
+--
+--     File:   open file using `tab :drop`
+--     Folder: expand or collapse
+--     Root:   change directory up
+--
+-- node.open.preview({node}, {opts})                  *nvim-tree-api.node.open.preview()*
+--     |nvim-tree-api.node.edit()|, file buffer will have |bufhidden| set to `delete`.
+--
+--     Parameters: ~
+--       • {node} (Node|nil) file or folder
+--       • {opts} (table) optional parameters
+--
+--     Options: ~
+--       • {quit_on_open} (boolean) quits the tree when opening the file
+--       • {focus} (boolean) keep focus in the tree when opening the file
+--
+--                                  *nvim-tree-api.node.open.preview_no_picker()*
+-- node.open.preview_no_picker({node}, {opts})
+--     |nvim-tree-api.node.edit()|, file buffer will have |bufhidden| set to `delete`.
+--     window picker will never be used as per
+--     |nvim-tree.actions.open_file.window_picker.enable| `false`
+--
+--     Parameters: ~
+--       • {node} (Node|nil) file or folder
+--       • {opts} (table) optional parameters
+--
+--     Options: ~
+--       • {quit_on_open} (boolean) quits the tree when opening the file
+--       • {focus} (boolean) keep focus in the tree when opening the file
+--
+-- node.navigate.git.next({node})        *nvim-tree-api.node.navigate.git.next()*
+--     Navigate to the next item showing git status.
+--
+--                             *nvim-tree-api.node.navigate.git.next_recursive()*
+-- node.navigate.git.next_recursive({node})
+--     Alternative to |nvim-tree-api.node.navigate.git.next()| that navigates to
+--     the next file showing git status, recursively.
+--     Needs |nvim-tree.git.show_on_dirs| set.
+--
+--                       *nvim-tree-api.node.navigate.git.next_skip_gitignored()*
+-- node.navigate.git.next_skip_gitignored({node})
+--     Same as |node.navigate.git.next()|, but skips gitignored files.
+--
+-- node.navigate.git.prev({node})        *nvim-tree-api.node.navigate.git.prev()*
+--     Navigate to the previous item showing git status.
+--
+--                       *nvim-tree-api.node.navigate.git.prev_recursive()*
+-- node.navigate.git.prev_recursive({node})
+--     Alternative to |nvim-tree-api.node.navigate.git.prev()| that navigates to
+--     the previous file showing git status, recursively.
+--     Needs |nvim-tree.git.show_on_dirs| set.
+--
+--                       *nvim-tree-api.node.navigate.git.prev_skip_gitignored()*
+-- node.navigate.git.prev_skip_gitignored({node})
+--     Same as |node.navigate.git.prev()|, but skips gitignored files.
+--
+--                               *nvim-tree-api.node.navigate.diagnostics.next()*
+-- node.navigate.diagnostics.next({node})
+--     Navigate to the next item showing diagnostic status.
+--
+--                     *nvim-tree-api.node.navigate.diagnostics.next_recursive()*
+-- node.navigate.diagnostics.next_recursive({node})
+--     Alternative to |nvim-tree-api.node.navigate.diagnostics.next()| that
+--     navigates to the next file showing diagnostic status, recursively.
+--     Needs |nvim-tree.diagnostics.show_on_dirs| set.
+--
+--                               *nvim-tree-api.node.navigate.diagnostics.prev()*
+-- node.navigate.diagnostics.prev({node})
+--     Navigate to the next item showing diagnostic status.
+--
+--                     *nvim-tree-api.node.navigate.diagnostics.prev_recursive()*
+-- node.navigate.diagnostics.prev_recursive({node})
+--     Alternative to |nvim-tree-api.node.navigate.diagnostics.prev()| that
+--     navigates to the previous file showing diagnostic status, recursively.
+--     Needs |nvim-tree.diagnostics.show_on_dirs| set.
+--
+--                                    *nvim-tree-api.node.navigate.opened.next()*
+-- node.navigate.opened.next({node})
+--     Navigate to the next |bufloaded()| item.
+--     See |nvim-tree.renderer.highlight_opened_files|
+--
+--                                    *nvim-tree-api.node.navigate.opened.prev()*
+-- node.navigate.opened.prev({node})
+--     Navigate to the previous |bufloaded()| item.
+--     See |nvim-tree.renderer.highlight_opened_files|
+--
+--                                   *nvim-tree-api.node.navigate.sibling.next()*
+-- node.navigate.sibling.next({node})
+--     Navigate to the next node in the current node's folder, wraps.
+--
+--                                   *nvim-tree-api.node.navigate.sibling.prev()*
+-- node.navigate.sibling.prev({node})
+--     Navigate to the previous node in the current node's folder, wraps.
+--
+--                                  *nvim-tree-api.node.navigate.sibling.first()*
+-- node.navigate.sibling.first({node})
+--     Navigate to the first node in the current node's folder.
+--
+--                                   *nvim-tree-api.node.navigate.sibling.last()*
+-- node.navigate.sibling.last({node})
+--     Navigate to the last node in the current node's folder.
+--
+--                                         *nvim-tree-api.node.navigate.parent()*
+-- node.navigate.parent({node})
+--     Navigate to the parent folder of the current node.
+--
+--                                   *nvim-tree-api.node.navigate.parent_close()*
+-- node.navigate.parent_close({node})
+--     |api.node.navigate.parent()|, closing that folder.
+--
+-- node.show_info_popup({node})            *nvim-tree-api.node.show_info_popup()*
+--     Open a popup window showing: fullpath, size, accessed, modified, created.
+--
+-- node.run.cmd({node})                            *nvim-tree-api.node.run.cmd()*
+--     Enter |cmdline| with the full path of the node and the cursor at the start
+--     of the line.
+--
+-- node.run.system({node})                      *nvim-tree-api.node.run.system()*
+--     Execute |nvim-tree.system_open|
+--
+-- node.buffer.delete({node}, {opts})        *nvim-tree-api.node.buffer.delete()*
+--     Deletes node's related buffer, if one exists.
+--     Executes |:bdelete| or |:bdelete|!
+--
+--     Parameters: ~
+--       • {node} (Node|nil) file or folder
+--       • {opts} (table) optional parameters
+--
+--     Options: ~
+--       • {force} (boolean) delete even if buffer is modified, default false
+--
+-- node.buffer.wipe({node}, {opts})            *nvim-tree-api.node.buffer.wipe()*
+--     Wipes node's related buffer, if one exists.
+--     Executes |:bwipe| or |:bwipe|!
+--
+--     Parameters: ~
+--       • {node} (Node|nil) file or folder
+--       • {opts} (table) optional parameters
+--
+--     Options: ~
+--       • {force} (boolean) wipe even if buffer is modified, default false
+--
+-- node.expand({node}, {opts})                      *nvim-tree-api.node.expand()*
+--     Recursively expand all nodes under a directory or a file's parent
+--     directory.
+--
+--     Parameters: ~
+--       • {node} (Node|nil) file or folder
+--       • {opts} (ApiTreeExpandOpts) optional parameters
+--
+--     Options: ~
+--       • {expand_until} ((fun(expansion_count: integer, node: Node?): boolean)?)
+--             Return true if {node} should be expanded.
+--             {expansion_count} is the total number of folders expanded.
+--
+-- node.collapse({node}, {opts})                  *nvim-tree-api.node.collapse()*
+--     Collapse the tree under a directory or a file's parent directory.
+--
+--     Parameters: ~
+--       • {node} (Node|nil) file or folder
+--       • {opts} (table) optional parameters
+--
+--     Options: ~
+--       • {keep_buffers} (boolean) do not collapse nodes with open buffers.
 
 require("nvim-tree.api.impl").node(nvim_tree.api.node)
 
diff --git a/scripts/help-update.sh b/scripts/help-update.sh
index 5326b7fda10..aacd22a36c1 100755
--- a/scripts/help-update.sh
+++ b/scripts/help-update.sh
@@ -47,6 +47,3 @@ begin="Show the mappings:"
 end="======"
 sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/DEFAULT_ON_ATTACH.help
            }; /${end}/p; d; }" doc/nvim-tree-lua.txt
-
-# TODO #3088 remove once all api references have been updated
-sed -i -e "s/nvim\-tree\-api\.tree\./nvim_tree.api.tree./g" doc/nvim-tree-lua.txt
diff --git a/scripts/lintdoc.sh b/scripts/lintdoc.sh
index 6b5b0a88d77..f3de5fbc5b7 100755
--- a/scripts/lintdoc.sh
+++ b/scripts/lintdoc.sh
@@ -55,3 +55,6 @@ cd "${DIR_NVIM_SRC}"
 
 # make nvim and execute the lint
 make lintdoc
+
+# clean up
+rm -v "${DIR_NVIM_SRC}/runtime/doc/nvim-tree-lua.txt"

From 46652cb23bac874854b569b353161f4a73bcb49b Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Tue, 20 Jan 2026 13:32:09 +1100
Subject: [PATCH 103/170] docs(#3088): extract api/node.lua functions, doc WIP

---
 doc/nvim-tree-lua.txt      |  96 ++++++--
 lua/nvim-tree/api/node.lua | 459 +++++--------------------------------
 2 files changed, 131 insertions(+), 424 deletions(-)

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index ccc12042cb6..db13a1365a2 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -2676,11 +2676,16 @@ collapse({node}, {opts})                       *nvim_tree.api.node.collapse()*
                   nodes with open buffers.
 
 expand({node}, {opts})                           *nvim_tree.api.node.expand()*
+    Recursively expand all nodes under a directory or a file's parent
+    directory.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
       • {opts}  (`table?`) optional
-                • {foo}? (`boolean`) (default: false)
+                • {expand_until}?
+                  (`fun(expansion_count: integer, node: Node): boolean`)
+                  Return `true` if `node` should be expanded.
+                  `expansion_count` is the total number of folders expanded.
 
                               *nvim_tree.api.node.navigate.diagnostics.next()*
 navigate.diagnostics.next({node})
@@ -2788,107 +2793,162 @@ navigate.sibling.prev({node})
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
 open.drop({node})                             *nvim_tree.api.node.open.drop()*
+    Switch to window with selected file if it exists, open file otherwise.
+    • file: open file using |:drop|
+    • directory: expand or collapse
+    • root: change directory up
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
 open.edit({node}, {opts})                     *nvim_tree.api.node.open.edit()*
+    • file: open as per |nvim_tree.Config.Actions.OpenFile|
+    • directory: expand or collapse
+    • root: change directory up
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
       • {opts}  (`table?`) optional
-                • {foo}? (`boolean`) (default: false)
+                • {quit_on_open}? (`boolean`, default: false) Quits the tree
+                  when opening the file.
+                • {focus}? (`boolean`, default: false) Keep focus in the tree
+                  when opening the file.
 
 open.horizontal({node}, {opts})         *nvim_tree.api.node.open.horizontal()*
+    Open file in a new horizontal split.
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node?`) directory or file
+      • {node}  (`nvim_tree.api.Node?`) file
       • {opts}  (`table?`) optional
-                • {foo}? (`boolean`) (default: false)
+                • {quit_on_open}? (`boolean`, default: false) Quits the tree
+                  when opening the file.
+                • {focus}? (`boolean`, default: false) Keep focus in the tree
+                  when opening the file.
 
                               *nvim_tree.api.node.open.horizontal_no_picker()*
 open.horizontal_no_picker({node}, {opts})
+    Open file in a new horizontal split without using the window picker.
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node?`) directory or file
+      • {node}  (`nvim_tree.api.Node?`) file
       • {opts}  (`table?`) optional
-                • {foo}? (`boolean`) (default: false)
+                • {quit_on_open}? (`boolean`, default: false) Quits the tree
+                  when opening the file.
+                • {focus}? (`boolean`, default: false) Keep focus in the tree
+                  when opening the file.
 
                                   *nvim_tree.api.node.open.no_window_picker()*
 open.no_window_picker({node}, {opts})
+    Open file without using the window picker.
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node?`) directory or file
+      • {node}  (`nvim_tree.api.Node?`) file
       • {opts}  (`table?`) optional
-                • {foo}? (`boolean`) (default: false)
+                • {quit_on_open}? (`boolean`, default: false) Quits the tree
+                  when opening the file.
+                • {focus}? (`boolean`, default: false) Keep focus in the tree
+                  when opening the file.
 
 open.preview({node}, {opts})               *nvim_tree.api.node.open.preview()*
+    Open file with |'bufhidden'| set to `delete`.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
       • {opts}  (`table?`) optional
-                • {foo}? (`boolean`) (default: false)
+                • {quit_on_open}? (`boolean`, default: false) Quits the tree
+                  when opening the file.
+                • {focus}? (`boolean`, default: false) Keep focus in the tree
+                  when opening the file.
 
                                  *nvim_tree.api.node.open.preview_no_picker()*
 open.preview_no_picker({node}, {opts})
+    Open file with |'bufhidden'| set to `delete` without using the window
+    picker.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
       • {opts}  (`table?`) optional
-                • {foo}? (`boolean`) (default: false)
+                • {quit_on_open}? (`boolean`, default: false) Quits the tree
+                  when opening the file.
+                • {focus}? (`boolean`, default: false) Keep focus in the tree
+                  when opening the file.
 
                                *nvim_tree.api.node.open.replace_tree_buffer()*
 open.replace_tree_buffer({node})
+    Open file in place: in the nvim-tree window.
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node?`) directory or file
+      • {node}  (`nvim_tree.api.Node?`) file
 
 open.tab({node}, {opts})                       *nvim_tree.api.node.open.tab()*
+    Open file in a new tab.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
       • {opts}  (`table?`) optional
-                • {foo}? (`boolean`) (default: false)
+                • {quit_on_open}? (`boolean`, default: false) Quits the tree
+                  when opening the file.
+                • {focus}? (`boolean`, default: false) Keep focus in the tree
+                  when opening the file.
 
 open.tab_drop({node})                     *nvim_tree.api.node.open.tab_drop()*
+    Switch to tab containing window with selected file if it exists. Open file
+    in new tab otherwise.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                                 *nvim_tree.api.node.open.toggle_group_empty()*
 open.toggle_group_empty({node}, {opts})
+    Toggle |nvim_tree.Config.Renderer| {group_empty} for a directory. Needs
+    {group_empty} set.
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node?`) directory or file
+      • {node}  (`nvim_tree.api.Node?`) directory
       • {opts}  (`table?`) optional
-                • {foo}? (`boolean`) (default: false)
+                • {quit_on_open}? (`boolean`, default: false) Quits the tree
+                  when opening the file.
+                • {focus}? (`boolean`, default: false) Keep focus in the tree
+                  when opening the file.
 
 open.vertical({node}, {opts})             *nvim_tree.api.node.open.vertical()*
+    Open file in a new vertical split.
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node?`) directory or file
+      • {node}  (`nvim_tree.api.Node?`) file
       • {opts}  (`table?`) optional
-                • {foo}? (`boolean`) (default: false)
+                • {quit_on_open}? (`boolean`, default: false) Quits the tree
+                  when opening the file.
+                • {focus}? (`boolean`, default: false) Keep focus in the tree
+                  when opening the file.
 
                                 *nvim_tree.api.node.open.vertical_no_picker()*
 open.vertical_no_picker({node}, {opts})
+    Open file in a new vertical split without using the window picker.
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node?`) directory or file
+      • {node}  (`nvim_tree.api.Node?`) file
       • {opts}  (`table?`) optional
-                • {foo}? (`boolean`) (default: false)
+                • {quit_on_open}? (`boolean`, default: false) Quits the tree
+                  when opening the file.
+                • {focus}? (`boolean`, default: false) Keep focus in the tree
+                  when opening the file.
 
 run.cmd({node})                                 *nvim_tree.api.node.run.cmd()*
+    Enter |cmdline| with the full path of the node and the cursor at the start
+    of the line.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
 run.system({node})                           *nvim_tree.api.node.run.system()*
+    Execute |nvim_tree.Config.SystemOpen|.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
 show_info_popup({node})                 *nvim_tree.api.node.show_info_popup()*
+    Open a popup window showing: fullpath, size, accessed, modified, created.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
diff --git a/lua/nvim-tree/api/node.lua b/lua/nvim-tree/api/node.lua
index 0db3cb9fe3a..d706b21715e 100644
--- a/lua/nvim-tree/api/node.lua
+++ b/lua/nvim-tree/api/node.lua
@@ -2,6 +2,18 @@
 local nvim_tree = { api = { node = { navigate = { sibling = {}, git = {}, diagnostics = {}, opened = {}, }, run = {}, open = {}, buffer = {}, } } }
 
 
+---@class nvim_tree.api.node.open.Opts
+---@inlinedoc
+---
+---Quits the tree when opening the file.
+---(default: false)
+---@field quit_on_open? boolean
+---
+---Keep focus in the tree when opening the file.
+---(default: false)
+---@field focus? boolean
+
+
 ---
 ---Deletes node's related buffer, if one exists. Executes [:bdelete] or [:bdelete]!
 ---
@@ -34,30 +46,16 @@ function nvim_tree.api.node.buffer.wipe(node, opts) end
 ---Collapse the tree under a directory or a file's parent directory.
 ---
 ---@param node? nvim_tree.api.Node directory or file
----@param opts? nvim_tree.api.node.collapse.Opts optional
+---@param opts? nvim_tree.api.tree.collapse.Opts optional
 function nvim_tree.api.node.collapse(node, opts) end
 
----@class nvim_tree.api.node.collapse.Opts
----@inlinedoc
----
----Do not collapse nodes with open buffers.
----(default: false)
----@field keep_buffers? boolean
-
----
 ---
+---Recursively expand all nodes under a directory or a file's parent directory.
 ---
 ---@param node? nvim_tree.api.Node directory or file
----@param opts? nvim_tree.api.node.expand.Opts optional
+---@param opts? nvim_tree.api.tree.expand.Opts optional
 function nvim_tree.api.node.expand(node, opts) end
 
----@class nvim_tree.api.node.expand.Opts
----@inlinedoc
----
----
----(default: false)
----@field foo? boolean
-
 ---
 ---
 ---
@@ -167,467 +165,116 @@ function nvim_tree.api.node.navigate.sibling.next(node) end
 function nvim_tree.api.node.navigate.sibling.prev(node) end
 
 ---
----
+---Switch to window with selected file if it exists, open file otherwise.
+---- file: open file using [:drop]
+---- directory: expand or collapse
+---- root: change directory up
 ---
 ---@param node? nvim_tree.api.Node directory or file
 function nvim_tree.api.node.open.drop(node) end
 
 ---
----
+---- file: open as per [nvim_tree.Config.Actions.OpenFile]
+---- directory: expand or collapse
+---- root: change directory up
 ---
 ---@param node? nvim_tree.api.Node directory or file
----@param opts? nvim_tree.api.node.open.edit.Opts optional
+---@param opts? nvim_tree.api.node.open.Opts optional
 function nvim_tree.api.node.open.edit(node, opts) end
 
----@class nvim_tree.api.node.open.edit.Opts
----@inlinedoc
 ---
+---Open file in a new horizontal split.
 ---
----(default: false)
----@field foo? boolean
-
----
----
----
----@param node? nvim_tree.api.Node directory or file
----@param opts? nvim_tree.api.node.open.horizontal.Opts optional
+---@param node? nvim_tree.api.Node file
+---@param opts? nvim_tree.api.node.open.Opts optional
 function nvim_tree.api.node.open.horizontal(node, opts) end
 
----@class nvim_tree.api.node.open.horizontal.Opts
----@inlinedoc
----
----
----(default: false)
----@field foo? boolean
-
----
 ---
+---Open file in a new horizontal split without using the window picker.
 ---
----@param node? nvim_tree.api.Node directory or file
----@param opts? nvim_tree.api.node.open.horizontal_no_picker.Opts optional
+---@param node? nvim_tree.api.Node file
+---@param opts? nvim_tree.api.node.open.Opts optional
 function nvim_tree.api.node.open.horizontal_no_picker(node, opts) end
 
----@class nvim_tree.api.node.open.horizontal_no_picker.Opts
----@inlinedoc
 ---
+---Open file without using the window picker.
 ---
----(default: false)
----@field foo? boolean
-
----
----
----
----@param node? nvim_tree.api.Node directory or file
----@param opts? nvim_tree.api.node.open.no_window_picker.Opts optional
+---@param node? nvim_tree.api.Node file
+---@param opts? nvim_tree.api.node.open.Opts optional
 function nvim_tree.api.node.open.no_window_picker(node, opts) end
 
----@class nvim_tree.api.node.open.no_window_picker.Opts
----@inlinedoc
----
----
----(default: false)
----@field foo? boolean
-
----
 ---
+---Open file with ['bufhidden'] set to `delete`.
 ---
 ---@param node? nvim_tree.api.Node directory or file
----@param opts? nvim_tree.api.node.open.preview.Opts optional
+---@param opts? nvim_tree.api.node.open.Opts optional
 function nvim_tree.api.node.open.preview(node, opts) end
 
----@class nvim_tree.api.node.open.preview.Opts
----@inlinedoc
----
----
----(default: false)
----@field foo? boolean
-
----
 ---
+---Open file with ['bufhidden'] set to `delete` without using the window picker.
 ---
 ---@param node? nvim_tree.api.Node directory or file
----@param opts? nvim_tree.api.node.open.preview_no_picker.Opts optional
+---@param opts? nvim_tree.api.node.open.Opts optional
 function nvim_tree.api.node.open.preview_no_picker(node, opts) end
 
----@class nvim_tree.api.node.open.preview_no_picker.Opts
----@inlinedoc
 ---
+---Open file in place: in the nvim-tree window.
 ---
----(default: false)
----@field foo? boolean
-
----
----
----
----@param node? nvim_tree.api.Node directory or file
+---@param node? nvim_tree.api.Node file
 function nvim_tree.api.node.open.replace_tree_buffer(node) end
 
 ---
----
+---Open file in a new tab.
 ---
 ---@param node? nvim_tree.api.Node directory or file
----@param opts? nvim_tree.api.node.open.tab.Opts optional
+---@param opts? nvim_tree.api.node.open.Opts optional
 function nvim_tree.api.node.open.tab(node, opts) end
 
----@class nvim_tree.api.node.open.tab.Opts
----@inlinedoc
----
----
----(default: false)
----@field foo? boolean
-
----
 ---
+---Switch to tab containing window with selected file if it exists. Open file in new tab otherwise.
 ---
 ---@param node? nvim_tree.api.Node directory or file
 function nvim_tree.api.node.open.tab_drop(node) end
 
 ---
+---Toggle [nvim_tree.Config.Renderer] {group_empty} for a directory. Needs {group_empty} set.
 ---
----
----@param node? nvim_tree.api.Node directory or file
----@param opts? nvim_tree.api.node.open.toggle_group_empty.Opts optional
+---@param node? nvim_tree.api.Node directory
+---@param opts? nvim_tree.api.node.open.Opts optional
 function nvim_tree.api.node.open.toggle_group_empty(node, opts) end
 
----@class nvim_tree.api.node.open.toggle_group_empty.Opts
----@inlinedoc
----
----
----(default: false)
----@field foo? boolean
-
----
 ---
+---Open file in a new vertical split.
 ---
----@param node? nvim_tree.api.Node directory or file
----@param opts? nvim_tree.api.node.open.vertical.Opts optional
+---@param node? nvim_tree.api.Node file
+---@param opts? nvim_tree.api.node.open.Opts optional
 function nvim_tree.api.node.open.vertical(node, opts) end
 
----@class nvim_tree.api.node.open.vertical.Opts
----@inlinedoc
 ---
+---Open file in a new vertical split without using the window picker.
 ---
----(default: false)
----@field foo? boolean
-
----
----
----
----@param node? nvim_tree.api.Node directory or file
----@param opts? nvim_tree.api.node.open.vertical_no_picker.Opts optional
+---@param node? nvim_tree.api.Node file
+---@param opts? nvim_tree.api.node.open.Opts optional
 function nvim_tree.api.node.open.vertical_no_picker(node, opts) end
 
----@class nvim_tree.api.node.open.vertical_no_picker.Opts
----@inlinedoc
----
----
----(default: false)
----@field foo? boolean
-
----
 ---
+---Enter [cmdline] with the full path of the node and the cursor at the start of the line.
 ---
 ---@param node? nvim_tree.api.Node directory or file
 function nvim_tree.api.node.run.cmd(node) end
 
 ---
----
+---Execute [nvim_tree.Config.SystemOpen].
 ---
 ---@param node? nvim_tree.api.Node directory or file
 function nvim_tree.api.node.run.system(node) end
 
 ---
----
+---Open a popup window showing: fullpath, size, accessed, modified, created.
 ---
 ---@param node? nvim_tree.api.Node directory or file
 function nvim_tree.api.node.show_info_popup(node) end
 
-
-
-
-
--- node.open.edit({node}, {opts})                        *nvim-tree-api.node.open.edit()*
---     File:   open as per |nvim-tree.actions.open_file|
---     Folder: expand or collapse
---     Root:   change directory up
---
---     Parameters: ~
---       • {node} (Node|nil) file or folder
---       • {opts} (table) optional parameters
---
---     Options: ~
---       • {quit_on_open} (boolean) quits the tree when opening the file
---       • {focus} (boolean) keep focus in the tree when opening the file
---
---                                *nvim-tree-api.node.open.replace_tree_buffer()*
--- node.open.replace_tree_buffer({node})
---     |nvim-tree-api.node.edit()|, file will be opened in place: in the
---     nvim-tree window.
---
---                                   *nvim-tree-api.node.open.no_window_picker()*
--- node.open.no_window_picker({node}, {opts})
---     |nvim-tree-api.node.edit()|, window picker will never be used as per
---     |nvim-tree.actions.open_file.window_picker.enable| `false`
---
---     Parameters: ~
---       • {node} (Node|nil) file or folder
---       • {opts} (table) optional parameters
---
---     Options: ~
---       • {quit_on_open} (boolean) quits the tree when opening the file
---       • {focus} (boolean) keep focus in the tree when opening the file
---
--- node.open.vertical({node}, {opts})                *nvim-tree-api.node.open.vertical()*
---     |nvim-tree-api.node.edit()|, file will be opened in a new vertical split.
---
---     Parameters: ~
---       • {node} (Node|nil) file or folder
---       • {opts} (table) optional parameters
---
---     Options: ~
---       • {quit_on_open} (boolean) quits the tree when opening the file
---       • {focus} (boolean) keep focus in the tree when opening the file
---
---                                 *nvim-tree-api.node.open.vertical_no_picker()*
--- node.open.vertical_no_picker({node}, {opts})
---     |nvim-tree-api.node.vertical()|, window picker will never be used as per
---     |nvim-tree.actions.open_file.window_picker.enable| `false`
---
---     Parameters: ~
---       • {node} (Node|nil) file or folder
---       • {opts} (table) optional parameters
---
---     Options: ~
---       • {quit_on_open} (boolean) quits the tree when opening the file
---       • {focus} (boolean) keep focus in the tree when opening the file
---
--- node.open.horizontal({node}, {opts})            *nvim-tree-api.node.open.horizontal()*
---     |nvim-tree-api.node.edit()|, file will be opened in a new horizontal split.
---
---     Parameters: ~
---       • {node} (Node|nil) file or folder
---       • {opts} (table) optional parameters
---
---     Options: ~
---       • {quit_on_open} (boolean) quits the tree when opening the file
---       • {focus} (boolean) keep focus in the tree when opening the file
---
---                               *nvim-tree-api.node.open.horizontal_no_picker()*
--- node.open.horizontal_no_picker({node}, {opts})
---     |nvim-tree-api.node.horizontal()|, window picker will never be used as per
---     |nvim-tree.actions.open_file.window_picker.enable| `false`
---
---     Parameters: ~
---       • {node} (Node|nil) file or folder
---       • {opts} (table) optional parameters
---
---     Options: ~
---       • {quit_on_open} (boolean) quits the tree when opening the file
---       • {focus} (boolean) keep focus in the tree when opening the file
---
---                                 *nvim-tree-api.node.open.toggle_group_empty()*
--- node.open.toggle_group_empty({node}, {opts})
---     Toggle |nvim-tree.renderer.group_empty| for a specific folder.
---     Does nothing on files.
---     Needs |nvim-tree.renderer.group_empty| set.
---
---     Parameters: ~
---       • {node} (Node|nil) file or folder
---       • {opts} (table) optional parameters
---
---     Options: ~
---       • {quit_on_open} (boolean) quits the tree when opening the file
---       • {focus} (boolean) keep focus in the tree when opening the file
---
--- node.open.drop({node})                        *nvim-tree-api.node.open.drop()*
---     Switch to window with selected file if it exists.
---     Open file otherwise.
---     See: `:h :drop`.
---
---     File:   open file using `:drop`
---     Folder: expand or collapse
---     Root:   change directory up
---
--- node.open.tab({node}, {opts})                          *nvim-tree-api.node.open.tab()*
---     |nvim-tree-api.node.edit()|, file will be opened in a new tab.
---
---     Parameters: ~
---       • {node} (Node|nil) file or folder
---       • {opts} (table) optional parameters
---
---     Options: ~
---       • {quit_on_open} (boolean) quits the tree when opening the file
---       • {focus} (boolean) keep focus in the tree when opening the file
---
---                                           *nvim-tree-api.node.open.tab_drop()*
--- node.open.tab_drop({node})
---     Switch to tab containing window with selected file if it exists.
---     Open file in new tab otherwise.
---
---     File:   open file using `tab :drop`
---     Folder: expand or collapse
---     Root:   change directory up
---
--- node.open.preview({node}, {opts})                  *nvim-tree-api.node.open.preview()*
---     |nvim-tree-api.node.edit()|, file buffer will have |bufhidden| set to `delete`.
---
---     Parameters: ~
---       • {node} (Node|nil) file or folder
---       • {opts} (table) optional parameters
---
---     Options: ~
---       • {quit_on_open} (boolean) quits the tree when opening the file
---       • {focus} (boolean) keep focus in the tree when opening the file
---
---                                  *nvim-tree-api.node.open.preview_no_picker()*
--- node.open.preview_no_picker({node}, {opts})
---     |nvim-tree-api.node.edit()|, file buffer will have |bufhidden| set to `delete`.
---     window picker will never be used as per
---     |nvim-tree.actions.open_file.window_picker.enable| `false`
---
---     Parameters: ~
---       • {node} (Node|nil) file or folder
---       • {opts} (table) optional parameters
---
---     Options: ~
---       • {quit_on_open} (boolean) quits the tree when opening the file
---       • {focus} (boolean) keep focus in the tree when opening the file
---
--- node.navigate.git.next({node})        *nvim-tree-api.node.navigate.git.next()*
---     Navigate to the next item showing git status.
---
---                             *nvim-tree-api.node.navigate.git.next_recursive()*
--- node.navigate.git.next_recursive({node})
---     Alternative to |nvim-tree-api.node.navigate.git.next()| that navigates to
---     the next file showing git status, recursively.
---     Needs |nvim-tree.git.show_on_dirs| set.
---
---                       *nvim-tree-api.node.navigate.git.next_skip_gitignored()*
--- node.navigate.git.next_skip_gitignored({node})
---     Same as |node.navigate.git.next()|, but skips gitignored files.
---
--- node.navigate.git.prev({node})        *nvim-tree-api.node.navigate.git.prev()*
---     Navigate to the previous item showing git status.
---
---                       *nvim-tree-api.node.navigate.git.prev_recursive()*
--- node.navigate.git.prev_recursive({node})
---     Alternative to |nvim-tree-api.node.navigate.git.prev()| that navigates to
---     the previous file showing git status, recursively.
---     Needs |nvim-tree.git.show_on_dirs| set.
---
---                       *nvim-tree-api.node.navigate.git.prev_skip_gitignored()*
--- node.navigate.git.prev_skip_gitignored({node})
---     Same as |node.navigate.git.prev()|, but skips gitignored files.
---
---                               *nvim-tree-api.node.navigate.diagnostics.next()*
--- node.navigate.diagnostics.next({node})
---     Navigate to the next item showing diagnostic status.
---
---                     *nvim-tree-api.node.navigate.diagnostics.next_recursive()*
--- node.navigate.diagnostics.next_recursive({node})
---     Alternative to |nvim-tree-api.node.navigate.diagnostics.next()| that
---     navigates to the next file showing diagnostic status, recursively.
---     Needs |nvim-tree.diagnostics.show_on_dirs| set.
---
---                               *nvim-tree-api.node.navigate.diagnostics.prev()*
--- node.navigate.diagnostics.prev({node})
---     Navigate to the next item showing diagnostic status.
---
---                     *nvim-tree-api.node.navigate.diagnostics.prev_recursive()*
--- node.navigate.diagnostics.prev_recursive({node})
---     Alternative to |nvim-tree-api.node.navigate.diagnostics.prev()| that
---     navigates to the previous file showing diagnostic status, recursively.
---     Needs |nvim-tree.diagnostics.show_on_dirs| set.
---
---                                    *nvim-tree-api.node.navigate.opened.next()*
--- node.navigate.opened.next({node})
---     Navigate to the next |bufloaded()| item.
---     See |nvim-tree.renderer.highlight_opened_files|
---
---                                    *nvim-tree-api.node.navigate.opened.prev()*
--- node.navigate.opened.prev({node})
---     Navigate to the previous |bufloaded()| item.
---     See |nvim-tree.renderer.highlight_opened_files|
---
---                                   *nvim-tree-api.node.navigate.sibling.next()*
--- node.navigate.sibling.next({node})
---     Navigate to the next node in the current node's folder, wraps.
---
---                                   *nvim-tree-api.node.navigate.sibling.prev()*
--- node.navigate.sibling.prev({node})
---     Navigate to the previous node in the current node's folder, wraps.
---
---                                  *nvim-tree-api.node.navigate.sibling.first()*
--- node.navigate.sibling.first({node})
---     Navigate to the first node in the current node's folder.
---
---                                   *nvim-tree-api.node.navigate.sibling.last()*
--- node.navigate.sibling.last({node})
---     Navigate to the last node in the current node's folder.
---
---                                         *nvim-tree-api.node.navigate.parent()*
--- node.navigate.parent({node})
---     Navigate to the parent folder of the current node.
---
---                                   *nvim-tree-api.node.navigate.parent_close()*
--- node.navigate.parent_close({node})
---     |api.node.navigate.parent()|, closing that folder.
---
--- node.show_info_popup({node})            *nvim-tree-api.node.show_info_popup()*
---     Open a popup window showing: fullpath, size, accessed, modified, created.
---
--- node.run.cmd({node})                            *nvim-tree-api.node.run.cmd()*
---     Enter |cmdline| with the full path of the node and the cursor at the start
---     of the line.
---
--- node.run.system({node})                      *nvim-tree-api.node.run.system()*
---     Execute |nvim-tree.system_open|
---
--- node.buffer.delete({node}, {opts})        *nvim-tree-api.node.buffer.delete()*
---     Deletes node's related buffer, if one exists.
---     Executes |:bdelete| or |:bdelete|!
---
---     Parameters: ~
---       • {node} (Node|nil) file or folder
---       • {opts} (table) optional parameters
---
---     Options: ~
---       • {force} (boolean) delete even if buffer is modified, default false
---
--- node.buffer.wipe({node}, {opts})            *nvim-tree-api.node.buffer.wipe()*
---     Wipes node's related buffer, if one exists.
---     Executes |:bwipe| or |:bwipe|!
---
---     Parameters: ~
---       • {node} (Node|nil) file or folder
---       • {opts} (table) optional parameters
---
---     Options: ~
---       • {force} (boolean) wipe even if buffer is modified, default false
---
--- node.expand({node}, {opts})                      *nvim-tree-api.node.expand()*
---     Recursively expand all nodes under a directory or a file's parent
---     directory.
---
---     Parameters: ~
---       • {node} (Node|nil) file or folder
---       • {opts} (ApiTreeExpandOpts) optional parameters
---
---     Options: ~
---       • {expand_until} ((fun(expansion_count: integer, node: Node?): boolean)?)
---             Return true if {node} should be expanded.
---             {expansion_count} is the total number of folders expanded.
---
--- node.collapse({node}, {opts})                  *nvim-tree-api.node.collapse()*
---     Collapse the tree under a directory or a file's parent directory.
---
---     Parameters: ~
---       • {node} (Node|nil) file or folder
---       • {opts} (table) optional parameters
---
---     Options: ~
---       • {keep_buffers} (boolean) do not collapse nodes with open buffers.
-
 require("nvim-tree.api.impl").node(nvim_tree.api.node)
 
 return nvim_tree.api.node

From 8853151e42a4cd5ce7778e479b802f56be2c99ed Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Tue, 20 Jan 2026 13:46:38 +1100
Subject: [PATCH 104/170] docs(#3088): extract api/node.lua functions, doc WIP

---
 doc/nvim-tree-lua.txt                 | 10 +++++-----
 lua/nvim-tree/actions/node/buffer.lua |  6 +++---
 lua/nvim-tree/api/node.lua            | 28 ++++++++++++---------------
 3 files changed, 20 insertions(+), 24 deletions(-)

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index db13a1365a2..160b25732de 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -2653,9 +2653,9 @@ buffer.delete({node}, {opts})             *nvim_tree.api.node.buffer.delete()*
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node`) file
-      • {opts}  (`table?`) A table with the following fields:
-                • {force}? (`boolean`, default: false) Delete even if buffer
-                  is modified.
+      • {opts}  (`table?`)
+                • {force}? (`boolean`, default: false) Proceed even if the
+                  buffer is modified.
 
 buffer.wipe({node}, {opts})                 *nvim_tree.api.node.buffer.wipe()*
     Wipes node's related buffer, if one exists. Executes |:bwipe| or |:bwipe|!
@@ -2663,8 +2663,8 @@ buffer.wipe({node}, {opts})                 *nvim_tree.api.node.buffer.wipe()*
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) file
       • {opts}  (`table?`) optional
-                • {force}? (`boolean`, default: false) Wipe even if buffer is
-                  modified.
+                • {force}? (`boolean`, default: false) Proceed even if the
+                  buffer is modified.
 
 collapse({node}, {opts})                       *nvim_tree.api.node.collapse()*
     Collapse the tree under a directory or a file's parent directory.
diff --git a/lua/nvim-tree/actions/node/buffer.lua b/lua/nvim-tree/actions/node/buffer.lua
index 425fcfa4ba6..050c207572a 100644
--- a/lua/nvim-tree/actions/node/buffer.lua
+++ b/lua/nvim-tree/actions/node/buffer.lua
@@ -4,14 +4,14 @@ local notify = require("nvim-tree.notify")
 local M = {}
 
 ---@param node Node
----@param opts ApiNodeDeleteWipeBufferOpts|nil
+---@param opts? nvim_tree.api.node.buffer.RemoveOpts
 ---@return nil
 function M.delete(node, opts)
   M.delete_buffer("delete", node.absolute_path, opts)
 end
 
 ---@param node Node
----@param opts ApiNodeDeleteWipeBufferOpts|nil
+---@param opts? nvim_tree.api.node.buffer.RemoveOpts
 ---@return nil
 function M.wipe(node, opts)
   M.delete_buffer("wipe", node.absolute_path, opts)
@@ -21,7 +21,7 @@ end
 
 ---@param mode ApiNodeDeleteWipeBufferMode
 ---@param filename string
----@param opts ApiNodeDeleteWipeBufferOpts|nil
+---@param opts? nvim_tree.api.node.buffer.RemoveOpts
 ---@return nil
 function M.delete_buffer(mode, filename, opts)
   if type(mode) ~= "string" then
diff --git a/lua/nvim-tree/api/node.lua b/lua/nvim-tree/api/node.lua
index d706b21715e..031e30b4281 100644
--- a/lua/nvim-tree/api/node.lua
+++ b/lua/nvim-tree/api/node.lua
@@ -2,6 +2,7 @@
 local nvim_tree = { api = { node = { navigate = { sibling = {}, git = {}, diagnostics = {}, opened = {}, }, run = {}, open = {}, buffer = {}, } } }
 
 
+---
 ---@class nvim_tree.api.node.open.Opts
 ---@inlinedoc
 ---
@@ -15,33 +16,28 @@ local nvim_tree = { api = { node = { navigate = { sibling = {}, git = {}, diagno
 
 
 ---
----Deletes node's related buffer, if one exists. Executes [:bdelete] or [:bdelete]!
----
----@param node nvim_tree.api.Node file
----@param opts? nvim_tree.api.node.buffer.delete.Opts
-function nvim_tree.api.node.buffer.delete(node, opts) end
-
----@class nvim_tree.api.node.buffer.delete.Opts optional
+---@class nvim_tree.api.node.buffer.RemoveOpts
 ---@inlinedoc
 ---
----Delete even if buffer is modified.
+---Proceed even if the buffer is modified.
 ---(default: false)
 ---@field force? boolean
 
+
+---
+---Deletes node's related buffer, if one exists. Executes [:bdelete] or [:bdelete]!
+---
+---@param node nvim_tree.api.Node file
+---@param opts? nvim_tree.api.node.buffer.RemoveOpts
+function nvim_tree.api.node.buffer.delete(node, opts) end
+
 ---
 ---Wipes node's related buffer, if one exists. Executes [:bwipe] or [:bwipe]!
 ---
 ---@param node? nvim_tree.api.Node file
----@param opts? nvim_tree.api.node.buffer.wipe.Opts optional
+---@param opts? nvim_tree.api.node.buffer.RemoveOpts optional
 function nvim_tree.api.node.buffer.wipe(node, opts) end
 
----@class nvim_tree.api.node.buffer.wipe.Opts
----@inlinedoc
----
----Wipe even if buffer is modified.
----(default: false)
----@field force? boolean
-
 ---
 ---Collapse the tree under a directory or a file's parent directory.
 ---

From 941f11f4d690d367934be13b8439f9410ba57132 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Tue, 20 Jan 2026 13:56:31 +1100
Subject: [PATCH 105/170] docs(#3088): extract api/node.lua functions

---
 doc/nvim-tree-lua.txt                         | 22 ++++++++
 .../actions/tree/modifiers/collapse.lua       |  6 +--
 .../actions/tree/modifiers/expand.lua         |  6 +--
 lua/nvim-tree/api/node.lua                    | 51 ++++++++++++-------
 lua/nvim-tree/api/tree.lua                    | 19 +------
 5 files changed, 62 insertions(+), 42 deletions(-)

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 160b25732de..1fcac2b742b 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -2689,105 +2689,127 @@ expand({node}, {opts})                           *nvim_tree.api.node.expand()*
 
                               *nvim_tree.api.node.navigate.diagnostics.next()*
 navigate.diagnostics.next({node})
+    Navigate to the next item showing diagnostic status.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                     *nvim_tree.api.node.navigate.diagnostics.next_recursive()*
 navigate.diagnostics.next_recursive({node})
+    Navigate to the next item showing diagnostic status, recursively. Needs
+    |nvim_tree.Config.Diagnostics| {show_on_dirs}
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                               *nvim_tree.api.node.navigate.diagnostics.prev()*
 navigate.diagnostics.prev({node})
+    Navigate to the previous item showing diagnostic status.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                     *nvim_tree.api.node.navigate.diagnostics.prev_recursive()*
 navigate.diagnostics.prev_recursive({node})
+    Navigate to the previous item showing diagnostic status, recursively.
+    Needs |nvim_tree.Config.Diagnostics| {show_on_dirs}
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
 navigate.git.next({node})             *nvim_tree.api.node.navigate.git.next()*
+    Navigate to the next item showing git status.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                             *nvim_tree.api.node.navigate.git.next_recursive()*
 navigate.git.next_recursive({node})
+    Navigate to the next item showing git status, recursively. Needs
+    |nvim_tree.Config.Git| {show_on_dirs}
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                       *nvim_tree.api.node.navigate.git.next_skip_gitignored()*
 navigate.git.next_skip_gitignored({node})
+    Navigate to the next item showing git status, skipping `.gitignore`
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
 navigate.git.prev({node})             *nvim_tree.api.node.navigate.git.prev()*
+    Navigate to the previous item showing git status.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                             *nvim_tree.api.node.navigate.git.prev_recursive()*
 navigate.git.prev_recursive({node})
+    Navigate to the previous item showing git status, recursively. Needs
+    |nvim_tree.Config.Git| {show_on_dirs}
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                       *nvim_tree.api.node.navigate.git.prev_skip_gitignored()*
 navigate.git.prev_skip_gitignored({node})
+    Navigate to the previous item showing git status, skipping `.gitignore`
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                                    *nvim_tree.api.node.navigate.opened.next()*
 navigate.opened.next({node})
+    Navigate to the next |bufloaded()| file.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                                    *nvim_tree.api.node.navigate.opened.prev()*
 navigate.opened.prev({node})
+    Navigate to the previous |bufloaded()| file.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
 navigate.parent({node})                 *nvim_tree.api.node.navigate.parent()*
+    Navigate to the parent directory of the node.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                                   *nvim_tree.api.node.navigate.parent_close()*
 navigate.parent_close({node})
+    Navigate to the parent directory of the node, closing it.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                                  *nvim_tree.api.node.navigate.sibling.first()*
 navigate.sibling.first({node})
+    Navigate to the first node in the current node's folder.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                                   *nvim_tree.api.node.navigate.sibling.last()*
 navigate.sibling.last({node})
+    Navigate to the last node in the current node's folder.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                                   *nvim_tree.api.node.navigate.sibling.next()*
 navigate.sibling.next({node})
+    Navigate to the next node in the current node's folder, wraps.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                                   *nvim_tree.api.node.navigate.sibling.prev()*
 navigate.sibling.prev({node})
+    Navigate to the previous node in the current node's folder, wraps.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
diff --git a/lua/nvim-tree/actions/tree/modifiers/collapse.lua b/lua/nvim-tree/actions/tree/modifiers/collapse.lua
index 614a62fb8b7..c1c0a5b4b3b 100644
--- a/lua/nvim-tree/actions/tree/modifiers/collapse.lua
+++ b/lua/nvim-tree/actions/tree/modifiers/collapse.lua
@@ -26,7 +26,7 @@ end
 
 ---Collapse a node, root if nil
 ---@param node Node?
----@param opts nvim_tree.api.tree.collapse.Opts
+---@param opts nvim_tree.api.node.collapse.Opts
 local function collapse(node, opts)
   local explorer = core.get_explorer()
   if not explorer then
@@ -60,7 +60,7 @@ local function collapse(node, opts)
 end
 
 
----@param opts nvim_tree.api.tree.collapse.Opts|boolean|nil legacy -> opts.keep_buffers
+---@param opts nvim_tree.api.node.collapse.Opts|boolean|nil legacy -> opts.keep_buffers
 function M.all(opts)
   -- legacy arguments
   if type(opts) == "boolean" then
@@ -73,7 +73,7 @@ function M.all(opts)
 end
 
 ---@param node Node
----@param opts nvim_tree.api.tree.collapse.Opts?
+---@param opts nvim_tree.api.node.collapse.Opts?
 function M.node(node, opts)
   collapse(node, opts or {})
 end
diff --git a/lua/nvim-tree/actions/tree/modifiers/expand.lua b/lua/nvim-tree/actions/tree/modifiers/expand.lua
index 0fe725fd1dc..c1c40f45cdb 100644
--- a/lua/nvim-tree/actions/tree/modifiers/expand.lua
+++ b/lua/nvim-tree/actions/tree/modifiers/expand.lua
@@ -125,7 +125,7 @@ local function gen_iterator(should_descend)
 end
 
 ---@param node Node?
----@param expand_opts nvim_tree.api.tree.expand.Opts?
+---@param expand_opts nvim_tree.api.node.expand.Opts?
 local function expand_node(node, expand_opts)
   if not node then
     return
@@ -141,14 +141,14 @@ end
 
 ---Expand the directory node or the root
 ---@param node Node
----@param expand_opts nvim_tree.api.tree.expand.Opts?
+---@param expand_opts nvim_tree.api.node.expand.Opts?
 function M.all(node, expand_opts)
   expand_node(node and node:as(DirectoryNode) or core.get_explorer(), expand_opts)
 end
 
 ---Expand the directory node or parent node
 ---@param node Node
----@param expand_opts nvim_tree.api.tree.expand.Opts?
+---@param expand_opts nvim_tree.api.node.expand.Opts?
 function M.node(node, expand_opts)
   if not node then
     return
diff --git a/lua/nvim-tree/api/node.lua b/lua/nvim-tree/api/node.lua
index 031e30b4281..4e73c047fbb 100644
--- a/lua/nvim-tree/api/node.lua
+++ b/lua/nvim-tree/api/node.lua
@@ -42,120 +42,133 @@ function nvim_tree.api.node.buffer.wipe(node, opts) end
 ---Collapse the tree under a directory or a file's parent directory.
 ---
 ---@param node? nvim_tree.api.Node directory or file
----@param opts? nvim_tree.api.tree.collapse.Opts optional
+---@param opts? nvim_tree.api.node.collapse.Opts optional
 function nvim_tree.api.node.collapse(node, opts) end
 
+---@class nvim_tree.api.node.collapse.Opts
+---@inlinedoc
+---
+---Do not collapse nodes with open buffers.
+---(default: false)
+---@field keep_buffers? boolean
+
 ---
 ---Recursively expand all nodes under a directory or a file's parent directory.
 ---
 ---@param node? nvim_tree.api.Node directory or file
----@param opts? nvim_tree.api.tree.expand.Opts optional
+---@param opts? nvim_tree.api.node.expand.Opts optional
 function nvim_tree.api.node.expand(node, opts) end
 
+---@class nvim_tree.api.node.expand.Opts
+---@inlinedoc
 ---
+---Return `true` if `node` should be expanded. `expansion_count` is the total number of folders expanded.
+---@field expand_until? fun(expansion_count: integer, node: Node): boolean
+
 ---
+---Navigate to the next item showing diagnostic status.
 ---
 ---@param node? nvim_tree.api.Node directory or file
 function nvim_tree.api.node.navigate.diagnostics.next(node) end
 
 ---
----
+---Navigate to the next item showing diagnostic status, recursively. Needs [nvim_tree.Config.Diagnostics] {show_on_dirs}
 ---
 ---@param node? nvim_tree.api.Node directory or file
 function nvim_tree.api.node.navigate.diagnostics.next_recursive(node) end
 
 ---
----
+---Navigate to the previous item showing diagnostic status.
 ---
 ---@param node? nvim_tree.api.Node directory or file
 function nvim_tree.api.node.navigate.diagnostics.prev(node) end
 
 ---
----
+---Navigate to the previous item showing diagnostic status, recursively. Needs [nvim_tree.Config.Diagnostics] {show_on_dirs}
 ---
 ---@param node? nvim_tree.api.Node directory or file
 function nvim_tree.api.node.navigate.diagnostics.prev_recursive(node) end
 
 ---
----
+---Navigate to the next item showing git status.
 ---
 ---@param node? nvim_tree.api.Node directory or file
 function nvim_tree.api.node.navigate.git.next(node) end
 
 ---
----
+---Navigate to the next item showing git status, recursively. Needs [nvim_tree.Config.Git] {show_on_dirs}
 ---
 ---@param node? nvim_tree.api.Node directory or file
 function nvim_tree.api.node.navigate.git.next_recursive(node) end
 
 ---
----
+---Navigate to the next item showing git status, skipping `.gitignore`
 ---
 ---@param node? nvim_tree.api.Node directory or file
 function nvim_tree.api.node.navigate.git.next_skip_gitignored(node) end
 
 ---
----
+---Navigate to the previous item showing git status.
 ---
 ---@param node? nvim_tree.api.Node directory or file
 function nvim_tree.api.node.navigate.git.prev(node) end
 
 ---
----
+---Navigate to the previous item showing git status, recursively. Needs [nvim_tree.Config.Git] {show_on_dirs}
 ---
 ---@param node? nvim_tree.api.Node directory or file
 function nvim_tree.api.node.navigate.git.prev_recursive(node) end
 
 ---
----
+---Navigate to the previous item showing git status, skipping `.gitignore`
 ---
 ---@param node? nvim_tree.api.Node directory or file
 function nvim_tree.api.node.navigate.git.prev_skip_gitignored(node) end
 
 ---
----
+---Navigate to the next [bufloaded()] file.
 ---
 ---@param node? nvim_tree.api.Node directory or file
 function nvim_tree.api.node.navigate.opened.next(node) end
 
 ---
----
+---Navigate to the previous [bufloaded()] file.
 ---
 ---@param node? nvim_tree.api.Node directory or file
 function nvim_tree.api.node.navigate.opened.prev(node) end
 
 ---
----
+---Navigate to the parent directory of the node.
 ---
 ---@param node? nvim_tree.api.Node directory or file
 function nvim_tree.api.node.navigate.parent(node) end
 
 ---
----
+---Navigate to the parent directory of the node, closing it.
 ---
 ---@param node? nvim_tree.api.Node directory or file
 function nvim_tree.api.node.navigate.parent_close(node) end
 
 ---
----
+---Navigate to the first node in the current node's folder.
 ---
 ---@param node? nvim_tree.api.Node directory or file
 function nvim_tree.api.node.navigate.sibling.first(node) end
 
 ---
----
+---Navigate to the last node in the current node's folder.
 ---
 ---@param node? nvim_tree.api.Node directory or file
 function nvim_tree.api.node.navigate.sibling.last(node) end
 
 ---
----
+---Navigate to the next node in the current node's folder, wraps.
 ---
 ---@param node? nvim_tree.api.Node directory or file
 function nvim_tree.api.node.navigate.sibling.next(node) end
 
 ---
----
+---Navigate to the previous node in the current node's folder, wraps.
 ---
 ---@param node? nvim_tree.api.Node directory or file
 function nvim_tree.api.node.navigate.sibling.prev(node) end
diff --git a/lua/nvim-tree/api/tree.lua b/lua/nvim-tree/api/tree.lua
index ada772571d3..0aabda0d9e4 100644
--- a/lua/nvim-tree/api/tree.lua
+++ b/lua/nvim-tree/api/tree.lua
@@ -1,8 +1,6 @@
 ---@meta
 local nvim_tree = { api = { tree = {} } }
 
--- TODO #3088 move expand/collapse into api.node
-
 ---
 ---Open the tree, focusing it if already open.
 ---
@@ -177,29 +175,16 @@ function nvim_tree.api.tree.search_node() end
 ---
 ---Collapse the tree.
 ---
----@param opts? nvim_tree.api.tree.collapse.Opts optional
+---@param opts? nvim_tree.api.node.collapse.Opts optional
 function nvim_tree.api.tree.collapse_all(opts) end
 
----@class nvim_tree.api.tree.collapse.Opts
----@inlinedoc
----
----Do not collapse nodes with open buffers.
----(default: false)
----@field keep_buffers? boolean
-
 ---
 ---Recursively expand all nodes under the tree root or specified folder.
 ---
 ---@param node? nvim_tree.api.Node directory
----@param opts? nvim_tree.api.tree.expand.Opts optional
+---@param opts? nvim_tree.api.node.expand.Opts optional
 function nvim_tree.api.tree.expand_all(node, opts) end
 
----@class nvim_tree.api.tree.expand.Opts
----@inlinedoc
----
----Return `true` if `node` should be expanded. `expansion_count` is the total number of folders expanded.
----@field expand_until? fun(expansion_count: integer, node: Node): boolean
-
 ---
 ---Toggle [nvim_tree.Config.Filters] {enable} all filters.
 ---

From db6d210ff216337220a40079753ee26ed786d245 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Tue, 20 Jan 2026 14:12:45 +1100
Subject: [PATCH 106/170] docs(#3088): move api into _meta

---
 .luacheckrc                                  |  1 -
 lua/nvim-tree/{ => _meta}/api/commands.lua   |  2 +-
 lua/nvim-tree/{ => _meta}/api/events.lua     |  2 +-
 lua/nvim-tree/{ => _meta}/api/filter.lua     |  2 +-
 lua/nvim-tree/{ => _meta}/api/fs.lua         |  2 +-
 lua/nvim-tree/{ => _meta}/api/health.lua     |  2 +-
 lua/nvim-tree/{ => _meta}/api/map.lua        |  2 +-
 lua/nvim-tree/{ => _meta}/api/marks.lua      |  2 +-
 lua/nvim-tree/{ => _meta}/api/node.lua       |  2 +-
 lua/nvim-tree/{ => _meta}/api/tree.lua       |  2 +-
 lua/nvim-tree/{api/impl.lua => api-impl.lua} |  0
 lua/nvim-tree/api.lua                        | 16 ++++++-------
 scripts/gen_vimdoc_config.lua                | 25 ++++++++------------
 scripts/luals-check.sh                       |  2 --
 14 files changed, 27 insertions(+), 35 deletions(-)
 rename lua/nvim-tree/{ => _meta}/api/commands.lua (88%)
 rename lua/nvim-tree/{ => _meta}/api/events.lua (87%)
 rename lua/nvim-tree/{ => _meta}/api/filter.lua (85%)
 rename lua/nvim-tree/{ => _meta}/api/fs.lua (98%)
 rename lua/nvim-tree/{ => _meta}/api/health.lua (84%)
 rename lua/nvim-tree/{ => _meta}/api/map.lua (93%)
 rename lua/nvim-tree/{ => _meta}/api/marks.lua (95%)
 rename lua/nvim-tree/{ => _meta}/api/node.lua (99%)
 rename lua/nvim-tree/{ => _meta}/api/tree.lua (99%)
 rename lua/nvim-tree/{api/impl.lua => api-impl.lua} (100%)

diff --git a/.luacheckrc b/.luacheckrc
index 9155f6f4386..267d0ce54ce 100644
--- a/.luacheckrc
+++ b/.luacheckrc
@@ -5,7 +5,6 @@ M.self = false
 
 M.ignore = {
   "631",  -- max_line_length
-  "212", -- TODO #3088 make luacheck understand @meta
 }
 
 -- Global objects defined by the C code
diff --git a/lua/nvim-tree/api/commands.lua b/lua/nvim-tree/_meta/api/commands.lua
similarity index 88%
rename from lua/nvim-tree/api/commands.lua
rename to lua/nvim-tree/_meta/api/commands.lua
index b5414f0c7e2..6d2b8616c50 100644
--- a/lua/nvim-tree/api/commands.lua
+++ b/lua/nvim-tree/_meta/api/commands.lua
@@ -16,6 +16,6 @@ local nvim_tree = { api = { commands = {} } }
 ---@return nvim_tree.api.commands.Command[]
 function nvim_tree.api.commands.get() end
 
-require("nvim-tree.api.impl").commands(nvim_tree.api.commands)
+require("nvim-tree.api-impl").commands(nvim_tree.api.commands)
 
 return nvim_tree.api.commands
diff --git a/lua/nvim-tree/api/events.lua b/lua/nvim-tree/_meta/api/events.lua
similarity index 87%
rename from lua/nvim-tree/api/events.lua
rename to lua/nvim-tree/_meta/api/events.lua
index 7877b14fc63..e36270cc3b6 100644
--- a/lua/nvim-tree/api/events.lua
+++ b/lua/nvim-tree/_meta/api/events.lua
@@ -13,6 +13,6 @@ function nvim_tree.api.events.subscribe(event_type, callback) end
 
 nvim_tree.api.events.Event = events.Event
 
-require("nvim-tree.api.impl").events(nvim_tree.api.events)
+require("nvim-tree.api-impl").events(nvim_tree.api.events)
 
 return nvim_tree.api.events
diff --git a/lua/nvim-tree/api/filter.lua b/lua/nvim-tree/_meta/api/filter.lua
similarity index 85%
rename from lua/nvim-tree/api/filter.lua
rename to lua/nvim-tree/_meta/api/filter.lua
index 784a9d7622d..a025791bdf6 100644
--- a/lua/nvim-tree/api/filter.lua
+++ b/lua/nvim-tree/_meta/api/filter.lua
@@ -11,6 +11,6 @@ function nvim_tree.api.filter.live_filter.start() end
 ---
 function nvim_tree.api.filter.live_filter.clear() end
 
-require("nvim-tree.api.impl").filter(nvim_tree.api.filter)
+require("nvim-tree.api-impl").filter(nvim_tree.api.filter)
 
 return nvim_tree.api.filter
diff --git a/lua/nvim-tree/api/fs.lua b/lua/nvim-tree/_meta/api/fs.lua
similarity index 98%
rename from lua/nvim-tree/api/fs.lua
rename to lua/nvim-tree/_meta/api/fs.lua
index 206ab393e55..abf6af74578 100644
--- a/lua/nvim-tree/api/fs.lua
+++ b/lua/nvim-tree/_meta/api/fs.lua
@@ -109,6 +109,6 @@ function nvim_tree.api.fs.rename_sub(node) end
 ---@param node nvim_tree.api.Node
 function nvim_tree.api.fs.trash(node) end
 
-require("nvim-tree.api.impl").fs(nvim_tree.api.fs)
+require("nvim-tree.api-impl").fs(nvim_tree.api.fs)
 
 return nvim_tree.api.fs
diff --git a/lua/nvim-tree/api/health.lua b/lua/nvim-tree/_meta/api/health.lua
similarity index 84%
rename from lua/nvim-tree/api/health.lua
rename to lua/nvim-tree/_meta/api/health.lua
index 454dfb9217f..1cb2b972d14 100644
--- a/lua/nvim-tree/api/health.lua
+++ b/lua/nvim-tree/_meta/api/health.lua
@@ -8,6 +8,6 @@ local nvim_tree = { api = { health = {} } }
 ---
 function nvim_tree.api.health.hi_test() end
 
-require("nvim-tree.api.impl").health(nvim_tree.api.health)
+require("nvim-tree.api-impl").health(nvim_tree.api.health)
 
 return nvim_tree.api.health
diff --git a/lua/nvim-tree/api/map.lua b/lua/nvim-tree/_meta/api/map.lua
similarity index 93%
rename from lua/nvim-tree/api/map.lua
rename to lua/nvim-tree/_meta/api/map.lua
index 96cfcc3b7c5..c1d32ab74d7 100644
--- a/lua/nvim-tree/api/map.lua
+++ b/lua/nvim-tree/_meta/api/map.lua
@@ -19,6 +19,6 @@ function nvim_tree.api.map.get_keymap_default() end
 ---@param bufnr integer use the `bufnr` passed to {on_attach}
 function nvim_tree.api.map.default_on_attach(bufnr) end
 
-require("nvim-tree.api.impl").map(nvim_tree.api.map)
+require("nvim-tree.api-impl").map(nvim_tree.api.map)
 
 return nvim_tree.api.map
diff --git a/lua/nvim-tree/api/marks.lua b/lua/nvim-tree/_meta/api/marks.lua
similarity index 95%
rename from lua/nvim-tree/api/marks.lua
rename to lua/nvim-tree/_meta/api/marks.lua
index 63f2f2b8ed9..367a534e6e4 100644
--- a/lua/nvim-tree/api/marks.lua
+++ b/lua/nvim-tree/_meta/api/marks.lua
@@ -55,6 +55,6 @@ function nvim_tree.api.marks.navigate.prev() end
 ---
 function nvim_tree.api.marks.navigate.select() end
 
-require("nvim-tree.api.impl").marks(nvim_tree.api.marks)
+require("nvim-tree.api-impl").marks(nvim_tree.api.marks)
 
 return nvim_tree.api.marks
diff --git a/lua/nvim-tree/api/node.lua b/lua/nvim-tree/_meta/api/node.lua
similarity index 99%
rename from lua/nvim-tree/api/node.lua
rename to lua/nvim-tree/_meta/api/node.lua
index 4e73c047fbb..be5110c8eb2 100644
--- a/lua/nvim-tree/api/node.lua
+++ b/lua/nvim-tree/_meta/api/node.lua
@@ -284,6 +284,6 @@ function nvim_tree.api.node.run.system(node) end
 ---@param node? nvim_tree.api.Node directory or file
 function nvim_tree.api.node.show_info_popup(node) end
 
-require("nvim-tree.api.impl").node(nvim_tree.api.node)
+require("nvim-tree.api-impl").node(nvim_tree.api.node)
 
 return nvim_tree.api.node
diff --git a/lua/nvim-tree/api/tree.lua b/lua/nvim-tree/_meta/api/tree.lua
similarity index 99%
rename from lua/nvim-tree/api/tree.lua
rename to lua/nvim-tree/_meta/api/tree.lua
index 0aabda0d9e4..ffed60ec708 100644
--- a/lua/nvim-tree/api/tree.lua
+++ b/lua/nvim-tree/_meta/api/tree.lua
@@ -268,6 +268,6 @@ function nvim_tree.api.tree.winid(opts) end
 ---
 function nvim_tree.api.tree.reload_git() end
 
-require("nvim-tree.api.impl").tree(nvim_tree.api.tree)
+require("nvim-tree.api-impl").tree(nvim_tree.api.tree)
 
 return nvim_tree.api.tree
diff --git a/lua/nvim-tree/api/impl.lua b/lua/nvim-tree/api-impl.lua
similarity index 100%
rename from lua/nvim-tree/api/impl.lua
rename to lua/nvim-tree/api-impl.lua
diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index 0c1dbf5ab31..c47c047014f 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -76,14 +76,14 @@
 --Load and hydrate all
 --
 local api = {
-  events = require("nvim-tree.api.events"),
-  filter = require("nvim-tree.api.filter"),
-  fs = require("nvim-tree.api.fs"),
-  health = require("nvim-tree.api.health"),
-  map = require("nvim-tree.api.map"),
-  marks = require("nvim-tree.api.marks"),
-  node = require("nvim-tree.api.node"),
-  tree = require("nvim-tree.api.tree"),
+  events = require("nvim-tree._meta.api.events"),
+  filter = require("nvim-tree._meta.api.filter"),
+  fs = require("nvim-tree._meta.api.fs"),
+  health = require("nvim-tree._meta.api.health"),
+  map = require("nvim-tree._meta.api.map"),
+  marks = require("nvim-tree._meta.api.marks"),
+  node = require("nvim-tree._meta.api.node"),
+  tree = require("nvim-tree._meta.api.tree"),
 }
 
 
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index acdf3df6fb0..74cff8e2ddd 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -33,15 +33,15 @@ local modules = {
 
   { helptag = "nvim-tree-api",                        title = "Lua module: nvim_tree.api",          path = "./lua/nvim_tree/api.lua", },
 
-  { helptag = "nvim-tree-api-commands",               title = "Lua module: nvim_tree.api.commands", path = "./lua/nvim_tree/api/commands.lua", },
-  { helptag = "nvim-tree-api-events",                 title = "Lua module: nvim_tree.api.events",   path = "./lua/nvim_tree/api/events.lua", },
-  { helptag = "nvim-tree-api-filter",                 title = "Lua module: nvim_tree.api.filter",   path = "./lua/nvim_tree/api/filter.lua", },
-  { helptag = "nvim-tree-api-fs",                     title = "Lua module: nvim_tree.api.fs",       path = "./lua/nvim_tree/api/fs.lua", },
-  { helptag = "nvim-tree-api-health",                 title = "Lua module: nvim_tree.api.health",   path = "./lua/nvim_tree/api/health.lua", },
-  { helptag = "nvim-tree-api-map",                    title = "Lua module: nvim_tree.api.map",      path = "./lua/nvim_tree/api/map.lua", },
-  { helptag = "nvim-tree-api-marks",                  title = "Lua module: nvim_tree.api.marks",    path = "./lua/nvim_tree/api/marks.lua", },
-  { helptag = "nvim-tree-api-node",                   title = "Lua module: nvim_tree.api.node",     path = "./lua/nvim_tree/api/node.lua", },
-  { helptag = "nvim-tree-api-tree",                   title = "Lua module: nvim_tree.api.tree",     path = "./lua/nvim_tree/api/tree.lua", },
+  { helptag = "nvim-tree-api-commands",               title = "Lua module: nvim_tree.api.commands", path = "./lua/nvim_tree/_meta/api/commands.lua", },
+  { helptag = "nvim-tree-api-events",                 title = "Lua module: nvim_tree.api.events",   path = "./lua/nvim_tree/_meta/api/events.lua", },
+  { helptag = "nvim-tree-api-filter",                 title = "Lua module: nvim_tree.api.filter",   path = "./lua/nvim_tree/_meta/api/filter.lua", },
+  { helptag = "nvim-tree-api-fs",                     title = "Lua module: nvim_tree.api.fs",       path = "./lua/nvim_tree/_meta/api/fs.lua", },
+  { helptag = "nvim-tree-api-health",                 title = "Lua module: nvim_tree.api.health",   path = "./lua/nvim_tree/_meta/api/health.lua", },
+  { helptag = "nvim-tree-api-map",                    title = "Lua module: nvim_tree.api.map",      path = "./lua/nvim_tree/_meta/api/map.lua", },
+  { helptag = "nvim-tree-api-marks",                  title = "Lua module: nvim_tree.api.marks",    path = "./lua/nvim_tree/_meta/api/marks.lua", },
+  { helptag = "nvim-tree-api-node",                   title = "Lua module: nvim_tree.api.node",     path = "./lua/nvim_tree/_meta/api/node.lua", },
+  { helptag = "nvim-tree-api-tree",                   title = "Lua module: nvim_tree.api.tree",     path = "./lua/nvim_tree/_meta/api/tree.lua", },
 }
 
 -- hydrate file names
@@ -84,18 +84,13 @@ local config = {
 
     -- optional, no default xform
     fn_xform = function(fun)
-      -- print(string.format("fn_xform fun=%s", vim.inspect(fun)))
+      print(string.format("fn_xform fun=%s", vim.inspect(fun)))
 
       if (fun.module) then
         -- generator doesn't strip meta
         -- also cascades into fn_helptag_fmt
         local module = fun.module:gsub("._meta", "", 1)
 
-        if module ~= fun.module then
-          error("unexpected _meta in module")
-          print(string.format("fn_xform module: %s -> %s", fun.module, module))
-        end
-
         -- remove the API prefix from the left aligned function name
         -- this will cascade into fn_helptag_fmt, which will apply the module prefix anyway
         local name, replaced = fun.name:gsub("^" .. module .. "%.", "", 1)
diff --git a/scripts/luals-check.sh b/scripts/luals-check.sh
index d145beb046a..5c611b18b98 100755
--- a/scripts/luals-check.sh
+++ b/scripts/luals-check.sh
@@ -21,8 +21,6 @@ mkdir "${DIR_OUT}"
 
 case "${1}" in
 	"codestyle-check")
-		echo "TODO #3088 skipping codestyle-check until api.lua refactor is complete"
-		exit 0
 		jq \
 			'.diagnostics.neededFileStatus[] = "None" | .diagnostics.neededFileStatus."codestyle-check" = "Any"' \
 			"${PWD}/.luarc.json" > "${FILE_LUARC}"

From d8a5442bec6b249d0bfebb11bd7a1f3fa05dbccf Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Tue, 20 Jan 2026 14:42:29 +1100
Subject: [PATCH 107/170] docs(#3088): move api-impl out of meta, restore it to
 its original state with a hyrdrate function

---
 lua/nvim-tree/_meta/api/commands.lua |   2 -
 lua/nvim-tree/_meta/api/events.lua   |   2 -
 lua/nvim-tree/_meta/api/filter.lua   |   2 -
 lua/nvim-tree/_meta/api/fs.lua       |   2 -
 lua/nvim-tree/_meta/api/health.lua   |   2 -
 lua/nvim-tree/_meta/api/map.lua      |   2 -
 lua/nvim-tree/_meta/api/marks.lua    |   2 -
 lua/nvim-tree/_meta/api/node.lua     |   2 -
 lua/nvim-tree/_meta/api/tree.lua     |   2 -
 lua/nvim-tree/api-impl.lua           | 351 ++++++++++++++++-----------
 lua/nvim-tree/api.lua                |  31 +--
 11 files changed, 218 insertions(+), 182 deletions(-)

diff --git a/lua/nvim-tree/_meta/api/commands.lua b/lua/nvim-tree/_meta/api/commands.lua
index 6d2b8616c50..f4073cdf69c 100644
--- a/lua/nvim-tree/_meta/api/commands.lua
+++ b/lua/nvim-tree/_meta/api/commands.lua
@@ -16,6 +16,4 @@ local nvim_tree = { api = { commands = {} } }
 ---@return nvim_tree.api.commands.Command[]
 function nvim_tree.api.commands.get() end
 
-require("nvim-tree.api-impl").commands(nvim_tree.api.commands)
-
 return nvim_tree.api.commands
diff --git a/lua/nvim-tree/_meta/api/events.lua b/lua/nvim-tree/_meta/api/events.lua
index e36270cc3b6..8616fae986c 100644
--- a/lua/nvim-tree/_meta/api/events.lua
+++ b/lua/nvim-tree/_meta/api/events.lua
@@ -13,6 +13,4 @@ function nvim_tree.api.events.subscribe(event_type, callback) end
 
 nvim_tree.api.events.Event = events.Event
 
-require("nvim-tree.api-impl").events(nvim_tree.api.events)
-
 return nvim_tree.api.events
diff --git a/lua/nvim-tree/_meta/api/filter.lua b/lua/nvim-tree/_meta/api/filter.lua
index a025791bdf6..06922fd848d 100644
--- a/lua/nvim-tree/_meta/api/filter.lua
+++ b/lua/nvim-tree/_meta/api/filter.lua
@@ -11,6 +11,4 @@ function nvim_tree.api.filter.live_filter.start() end
 ---
 function nvim_tree.api.filter.live_filter.clear() end
 
-require("nvim-tree.api-impl").filter(nvim_tree.api.filter)
-
 return nvim_tree.api.filter
diff --git a/lua/nvim-tree/_meta/api/fs.lua b/lua/nvim-tree/_meta/api/fs.lua
index abf6af74578..46abe204759 100644
--- a/lua/nvim-tree/_meta/api/fs.lua
+++ b/lua/nvim-tree/_meta/api/fs.lua
@@ -109,6 +109,4 @@ function nvim_tree.api.fs.rename_sub(node) end
 ---@param node nvim_tree.api.Node
 function nvim_tree.api.fs.trash(node) end
 
-require("nvim-tree.api-impl").fs(nvim_tree.api.fs)
-
 return nvim_tree.api.fs
diff --git a/lua/nvim-tree/_meta/api/health.lua b/lua/nvim-tree/_meta/api/health.lua
index 1cb2b972d14..088ae5076cd 100644
--- a/lua/nvim-tree/_meta/api/health.lua
+++ b/lua/nvim-tree/_meta/api/health.lua
@@ -8,6 +8,4 @@ local nvim_tree = { api = { health = {} } }
 ---
 function nvim_tree.api.health.hi_test() end
 
-require("nvim-tree.api-impl").health(nvim_tree.api.health)
-
 return nvim_tree.api.health
diff --git a/lua/nvim-tree/_meta/api/map.lua b/lua/nvim-tree/_meta/api/map.lua
index c1d32ab74d7..6fc6ded8a30 100644
--- a/lua/nvim-tree/_meta/api/map.lua
+++ b/lua/nvim-tree/_meta/api/map.lua
@@ -19,6 +19,4 @@ function nvim_tree.api.map.get_keymap_default() end
 ---@param bufnr integer use the `bufnr` passed to {on_attach}
 function nvim_tree.api.map.default_on_attach(bufnr) end
 
-require("nvim-tree.api-impl").map(nvim_tree.api.map)
-
 return nvim_tree.api.map
diff --git a/lua/nvim-tree/_meta/api/marks.lua b/lua/nvim-tree/_meta/api/marks.lua
index 367a534e6e4..b615ae73a4a 100644
--- a/lua/nvim-tree/_meta/api/marks.lua
+++ b/lua/nvim-tree/_meta/api/marks.lua
@@ -55,6 +55,4 @@ function nvim_tree.api.marks.navigate.prev() end
 ---
 function nvim_tree.api.marks.navigate.select() end
 
-require("nvim-tree.api-impl").marks(nvim_tree.api.marks)
-
 return nvim_tree.api.marks
diff --git a/lua/nvim-tree/_meta/api/node.lua b/lua/nvim-tree/_meta/api/node.lua
index be5110c8eb2..670e82a0008 100644
--- a/lua/nvim-tree/_meta/api/node.lua
+++ b/lua/nvim-tree/_meta/api/node.lua
@@ -284,6 +284,4 @@ function nvim_tree.api.node.run.system(node) end
 ---@param node? nvim_tree.api.Node directory or file
 function nvim_tree.api.node.show_info_popup(node) end
 
-require("nvim-tree.api-impl").node(nvim_tree.api.node)
-
 return nvim_tree.api.node
diff --git a/lua/nvim-tree/_meta/api/tree.lua b/lua/nvim-tree/_meta/api/tree.lua
index ffed60ec708..cdfd88acc38 100644
--- a/lua/nvim-tree/_meta/api/tree.lua
+++ b/lua/nvim-tree/_meta/api/tree.lua
@@ -268,6 +268,4 @@ function nvim_tree.api.tree.winid(opts) end
 ---
 function nvim_tree.api.tree.reload_git() end
 
-require("nvim-tree.api-impl").tree(nvim_tree.api.tree)
-
 return nvim_tree.api.tree
diff --git a/lua/nvim-tree/api-impl.lua b/lua/nvim-tree/api-impl.lua
index 14156cde9b0..e8683b0ee7b 100644
--- a/lua/nvim-tree/api-impl.lua
+++ b/lua/nvim-tree/api-impl.lua
@@ -3,6 +3,7 @@ local view = require("nvim-tree.view")
 local utils = require("nvim-tree.utils")
 local actions = require("nvim-tree.actions")
 local appearance_hi_test = require("nvim-tree.appearance.hi-test")
+local events = require("nvim-tree.events")
 local help = require("nvim-tree.help")
 local keymap = require("nvim-tree.keymap")
 local notify = require("nvim-tree.notify")
@@ -11,9 +12,9 @@ local DirectoryNode = require("nvim-tree.node.directory")
 local FileNode = require("nvim-tree.node.file")
 local FileLinkNode = require("nvim-tree.node.file-link")
 local RootNode = require("nvim-tree.node.root")
+local UserDecorator = require("nvim-tree.renderer.decorator.user")
 
-local M = {}
-
+return function(Api)
 ---Print error when setup not called.
 ---@param fn fun(...): any
 ---@return fun(...): any
@@ -92,6 +93,121 @@ local function wrap_explorer_member(explorer_member, member_method)
   end)
 end
 
+---@class ApiTreeOpenOpts
+---@field path string|nil path
+---@field current_window boolean|nil default false
+---@field winid number|nil
+---@field find_file boolean|nil default false
+---@field update_root boolean|nil default false
+
+Api.tree.open = wrap(actions.tree.open.fn)
+Api.tree.focus = Api.tree.open
+
+---@class ApiTreeToggleOpts
+---@field path string|nil
+---@field current_window boolean|nil default false
+---@field winid number|nil
+---@field find_file boolean|nil default false
+---@field update_root boolean|nil default false
+---@field focus boolean|nil default true
+
+Api.tree.toggle = wrap(actions.tree.toggle.fn)
+Api.tree.close = wrap(view.close)
+Api.tree.close_in_this_tab = wrap(view.close_this_tab_only)
+Api.tree.close_in_all_tabs = wrap(view.close_all_tabs)
+Api.tree.reload = wrap_explorer("reload_explorer")
+
+---@class ApiTreeResizeOpts
+---@field width string|function|number|table|nil
+---@field absolute number|nil
+---@field relative number|nil
+
+Api.tree.resize = wrap(actions.tree.resize.fn)
+
+Api.tree.change_root = wrap(function(...)
+  require("nvim-tree").change_dir(...)
+end)
+
+Api.tree.change_root_to_node = wrap_node(function(node)
+  if node.name == ".." or node:is(RootNode) then
+    actions.root.change_dir.fn("..")
+    return
+  end
+
+  if node:is(FileNode) and node.parent ~= nil then
+    actions.root.change_dir.fn(node.parent:last_group_node().absolute_path)
+    return
+  end
+
+  if node:is(DirectoryNode) then
+    actions.root.change_dir.fn(node:last_group_node().absolute_path)
+    return
+  end
+end)
+
+Api.tree.change_root_to_parent = wrap_node(wrap_explorer("dir_up"))
+Api.tree.get_node_under_cursor = wrap_explorer("get_node_at_cursor")
+Api.tree.get_nodes = wrap_explorer("get_nodes")
+
+---@class ApiTreeFindFileOpts
+---@field buf string|number|nil
+---@field open boolean|nil default false
+---@field current_window boolean|nil default false
+---@field winid number|nil
+---@field update_root boolean|nil default false
+---@field focus boolean|nil default false
+
+Api.tree.find_file = wrap(actions.tree.find_file.fn)
+Api.tree.search_node = wrap(actions.finders.search_node.fn)
+
+---@class ApiCollapseOpts
+---@field keep_buffers boolean|nil default false
+
+Api.tree.collapse_all = wrap(actions.tree.modifiers.collapse.all)
+
+---@class ApiTreeExpandOpts
+---@field expand_until (fun(expansion_count: integer, node: Node): boolean)|nil
+
+Api.tree.expand_all = wrap_node(actions.tree.modifiers.expand.all)
+Api.tree.toggle_enable_filters = wrap_explorer_member("filters", "toggle")
+Api.tree.toggle_gitignore_filter = wrap_explorer_member_args("filters", "toggle", "git_ignored")
+Api.tree.toggle_git_clean_filter = wrap_explorer_member_args("filters", "toggle", "git_clean")
+Api.tree.toggle_no_buffer_filter = wrap_explorer_member_args("filters", "toggle", "no_buffer")
+Api.tree.toggle_custom_filter = wrap_explorer_member_args("filters", "toggle", "custom")
+Api.tree.toggle_hidden_filter = wrap_explorer_member_args("filters", "toggle", "dotfiles")
+Api.tree.toggle_no_bookmark_filter = wrap_explorer_member_args("filters", "toggle", "no_bookmark")
+Api.tree.toggle_help = wrap(help.toggle)
+Api.tree.is_tree_buf = wrap(utils.is_nvim_tree_buf)
+
+---@class ApiTreeIsVisibleOpts
+---@field tabpage number|nil
+---@field any_tabpage boolean|nil default false
+
+Api.tree.is_visible = wrap(view.is_visible)
+
+---@class ApiTreeWinIdOpts
+---@field tabpage number|nil default nil
+
+Api.tree.winid = wrap(view.winid)
+
+Api.fs.create = wrap_node_or_nil(actions.fs.create_file.fn)
+Api.fs.remove = wrap_node(actions.fs.remove_file.fn)
+Api.fs.trash = wrap_node(actions.fs.trash.fn)
+Api.fs.rename_node = wrap_node(actions.fs.rename_file.fn(":t"))
+Api.fs.rename = wrap_node(actions.fs.rename_file.fn(":t"))
+Api.fs.rename_sub = wrap_node(actions.fs.rename_file.fn(":p:h"))
+Api.fs.rename_basename = wrap_node(actions.fs.rename_file.fn(":t:r"))
+Api.fs.rename_full = wrap_node(actions.fs.rename_file.fn(":p"))
+Api.fs.cut = wrap_node(wrap_explorer_member("clipboard", "cut"))
+Api.fs.paste = wrap_node(wrap_explorer_member("clipboard", "paste"))
+Api.fs.clear_clipboard = wrap_explorer_member("clipboard", "clear_clipboard")
+Api.fs.print_clipboard = wrap_explorer_member("clipboard", "print_clipboard")
+Api.fs.copy.node = wrap_node(wrap_explorer_member("clipboard", "copy"))
+Api.fs.copy.absolute_path = wrap_node(wrap_explorer_member("clipboard", "copy_absolute_path"))
+Api.fs.copy.filename = wrap_node(wrap_explorer_member("clipboard", "copy_filename"))
+Api.fs.copy.basename = wrap_node(wrap_explorer_member("clipboard", "copy_basename"))
+Api.fs.copy.relative_path = wrap_node(wrap_explorer_member("clipboard", "copy_path"))
+---
 ---@class NodeEditOpts
 ---@field quit_on_open boolean|nil default false
 ---@field focus boolean|nil default true
@@ -144,149 +260,110 @@ local function open_or_expand_or_dir_up(mode, toggle_group)
   end
 end
 
-function M.tree(tree)
-  tree.open = wrap(actions.tree.open.fn)
-  tree.focus = tree.open
-  tree.toggle = wrap(actions.tree.toggle.fn)
-  tree.close = wrap(view.close)
-  tree.close_in_this_tab = wrap(view.close_this_tab_only)
-  tree.close_in_all_tabs = wrap(view.close_all_tabs)
-  tree.reload = wrap_explorer("reload_explorer")
-  tree.resize = wrap(actions.tree.resize.fn)
-  tree.change_root = wrap(function(...) require("nvim-tree").change_dir(...) end)
-  tree.change_root_to_parent = wrap_node(wrap_explorer("dir_up"))
-  tree.get_node_under_cursor = wrap_explorer("get_node_at_cursor")
-  tree.get_nodes = wrap_explorer("get_nodes")
-  tree.find_file = wrap(actions.tree.find_file.fn)
-  tree.search_node = wrap(actions.finders.search_node.fn)
-  tree.collapse_all = wrap(actions.tree.modifiers.collapse.all)
-  tree.expand_all = wrap_node(actions.tree.modifiers.expand.all)
-  tree.toggle_enable_filters = wrap_explorer_member("filters", "toggle")
-  tree.toggle_gitignore_filter = wrap_explorer_member_args("filters", "toggle", "git_ignored")
-  tree.toggle_git_clean_filter = wrap_explorer_member_args("filters", "toggle", "git_clean")
-  tree.toggle_no_buffer_filter = wrap_explorer_member_args("filters", "toggle", "no_buffer")
-  tree.toggle_custom_filter = wrap_explorer_member_args("filters", "toggle", "custom")
-  tree.toggle_hidden_filter = wrap_explorer_member_args("filters", "toggle", "dotfiles")
-  tree.toggle_no_bookmark_filter = wrap_explorer_member_args("filters", "toggle", "no_bookmark")
-  tree.toggle_help = wrap(help.toggle)
-  tree.is_tree_buf = wrap(utils.is_nvim_tree_buf)
-  tree.is_visible = wrap(view.is_visible)
-  tree.winid = wrap(view.winid)
-  tree.reload_git = wrap_explorer("reload_git")
-  tree.change_root_to_node = wrap_node(function(node)
-    if node.name == ".." or node:is(RootNode) then
-      actions.root.change_dir.fn("..")
-      return
-    end
+Api.node.open.edit = wrap_node(open_or_expand_or_dir_up("edit"))
+Api.node.open.drop = wrap_node(open_or_expand_or_dir_up("drop"))
+Api.node.open.tab_drop = wrap_node(open_or_expand_or_dir_up("tab_drop"))
+Api.node.open.replace_tree_buffer = wrap_node(open_or_expand_or_dir_up("edit_in_place"))
+Api.node.open.no_window_picker = wrap_node(open_or_expand_or_dir_up("edit_no_picker"))
+Api.node.open.vertical = wrap_node(open_or_expand_or_dir_up("vsplit"))
+Api.node.open.vertical_no_picker = wrap_node(open_or_expand_or_dir_up("vsplit_no_picker"))
+Api.node.open.horizontal = wrap_node(open_or_expand_or_dir_up("split"))
+Api.node.open.horizontal_no_picker = wrap_node(open_or_expand_or_dir_up("split_no_picker"))
+Api.node.open.tab = wrap_node(open_or_expand_or_dir_up("tabnew"))
+Api.node.open.toggle_group_empty = wrap_node(open_or_expand_or_dir_up("toggle_group_empty", true))
+Api.node.open.preview = wrap_node(open_or_expand_or_dir_up("preview"))
+Api.node.open.preview_no_picker = wrap_node(open_or_expand_or_dir_up("preview_no_picker"))
 
-    if node:is(FileNode) and node.parent ~= nil then
-      actions.root.change_dir.fn(node.parent:last_group_node().absolute_path)
-      return
-    end
+Api.node.show_info_popup = wrap_node(actions.node.file_popup.toggle_file_info)
+Api.node.run.cmd = wrap_node(actions.node.run_command.run_file_command)
+Api.node.run.system = wrap_node(actions.node.system_open.fn)
 
-    if node:is(DirectoryNode) then
-      actions.root.change_dir.fn(node:last_group_node().absolute_path)
-      return
-    end
-  end)
-end
+Api.node.navigate.sibling.next = wrap_node(actions.moves.sibling.fn("next"))
+Api.node.navigate.sibling.prev = wrap_node(actions.moves.sibling.fn("prev"))
+Api.node.navigate.sibling.first = wrap_node(actions.moves.sibling.fn("first"))
+Api.node.navigate.sibling.last = wrap_node(actions.moves.sibling.fn("last"))
+Api.node.navigate.parent = wrap_node(actions.moves.parent.fn(false))
+Api.node.navigate.parent_close = wrap_node(actions.moves.parent.fn(true))
+Api.node.navigate.git.next = wrap_node(actions.moves.item.fn({ where = "next", what = "git" }))
+Api.node.navigate.git.next_skip_gitignored = wrap_node(actions.moves.item.fn({ where = "next", what = "git", skip_gitignored = true }))
+Api.node.navigate.git.next_recursive = wrap_node(actions.moves.item.fn({ where = "next", what = "git", recurse = true }))
+Api.node.navigate.git.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "git" }))
+Api.node.navigate.git.prev_skip_gitignored = wrap_node(actions.moves.item.fn({ where = "prev", what = "git", skip_gitignored = true }))
+Api.node.navigate.git.prev_recursive = wrap_node(actions.moves.item.fn({ where = "prev", what = "git", recurse = true }))
+Api.node.navigate.diagnostics.next = wrap_node(actions.moves.item.fn({ where = "next", what = "diag" }))
+Api.node.navigate.diagnostics.next_recursive = wrap_node(actions.moves.item.fn({ where = "next", what = "diag", recurse = true }))
+Api.node.navigate.diagnostics.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "diag" }))
+Api.node.navigate.diagnostics.prev_recursive = wrap_node(actions.moves.item.fn({ where = "prev", what = "diag", recurse = true }))
+Api.node.navigate.opened.next = wrap_node(actions.moves.item.fn({ where = "next", what = "opened" }))
+Api.node.navigate.opened.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "opened" }))
 
-function M.fs(fs)
-  fs.create = wrap_node_or_nil(actions.fs.create_file.fn)
-  fs.remove = wrap_node(actions.fs.remove_file.fn)
-  fs.trash = wrap_node(actions.fs.trash.fn)
-  fs.rename_node = wrap_node(actions.fs.rename_file.fn(":t"))
-  fs.rename = wrap_node(actions.fs.rename_file.fn(":t"))
-  fs.rename_sub = wrap_node(actions.fs.rename_file.fn(":p:h"))
-  fs.rename_basename = wrap_node(actions.fs.rename_file.fn(":t:r"))
-  fs.rename_full = wrap_node(actions.fs.rename_file.fn(":p"))
-  fs.cut = wrap_node(wrap_explorer_member("clipboard", "cut"))
-  fs.paste = wrap_node(wrap_explorer_member("clipboard", "paste"))
-  fs.clear_clipboard = wrap_explorer_member("clipboard", "clear_clipboard")
-  fs.print_clipboard = wrap_explorer_member("clipboard", "print_clipboard")
-  fs.copy.node = wrap_node(wrap_explorer_member("clipboard", "copy"))
-  fs.copy.absolute_path = wrap_node(wrap_explorer_member("clipboard", "copy_absolute_path"))
-  fs.copy.filename = wrap_node(wrap_explorer_member("clipboard", "copy_filename"))
-  fs.copy.basename = wrap_node(wrap_explorer_member("clipboard", "copy_basename"))
-  fs.copy.relative_path = wrap_node(wrap_explorer_member("clipboard", "copy_path"))
-end
+Api.node.expand = wrap_node(actions.tree.modifiers.expand.node)
+Api.node.collapse = wrap_node(actions.tree.modifiers.collapse.node)
 
-function M.node(node)
-  node.open.edit = wrap_node(open_or_expand_or_dir_up("edit"))
-  node.open.drop = wrap_node(open_or_expand_or_dir_up("drop"))
-  node.open.tab_drop = wrap_node(open_or_expand_or_dir_up("tab_drop"))
-  node.open.replace_tree_buffer = wrap_node(open_or_expand_or_dir_up("edit_in_place"))
-  node.open.no_window_picker = wrap_node(open_or_expand_or_dir_up("edit_no_picker"))
-  node.open.vertical = wrap_node(open_or_expand_or_dir_up("vsplit"))
-  node.open.vertical_no_picker = wrap_node(open_or_expand_or_dir_up("vsplit_no_picker"))
-  node.open.horizontal = wrap_node(open_or_expand_or_dir_up("split"))
-  node.open.horizontal_no_picker = wrap_node(open_or_expand_or_dir_up("split_no_picker"))
-  node.open.tab = wrap_node(open_or_expand_or_dir_up("tabnew"))
-  node.open.toggle_group_empty = wrap_node(open_or_expand_or_dir_up("toggle_group_empty", true))
-  node.open.preview = wrap_node(open_or_expand_or_dir_up("preview"))
-  node.open.preview_no_picker = wrap_node(open_or_expand_or_dir_up("preview_no_picker"))
-  node.show_info_popup = wrap_node(actions.node.file_popup.toggle_file_info)
-  node.run.cmd = wrap_node(actions.node.run_command.run_file_command)
-  node.run.system = wrap_node(actions.node.system_open.fn)
-  node.navigate.sibling.next = wrap_node(actions.moves.sibling.fn("next"))
-  node.navigate.sibling.prev = wrap_node(actions.moves.sibling.fn("prev"))
-  node.navigate.sibling.first = wrap_node(actions.moves.sibling.fn("first"))
-  node.navigate.sibling.last = wrap_node(actions.moves.sibling.fn("last"))
-  node.navigate.parent = wrap_node(actions.moves.parent.fn(false))
-  node.navigate.parent_close = wrap_node(actions.moves.parent.fn(true))
-  node.navigate.git.next = wrap_node(actions.moves.item.fn({ where = "next", what = "git" }))
-  node.navigate.git.next_skip_gitignored = wrap_node(actions.moves.item.fn({ where = "next", what = "git", skip_gitignored = true }))
-  node.navigate.git.next_recursive = wrap_node(actions.moves.item.fn({ where = "next", what = "git", recurse = true }))
-  node.navigate.git.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "git" }))
-  node.navigate.git.prev_skip_gitignored = wrap_node(actions.moves.item.fn({ where = "prev", what = "git", skip_gitignored = true }))
-  node.navigate.git.prev_recursive = wrap_node(actions.moves.item.fn({ where = "prev", what = "git", recurse = true }))
-  node.navigate.diagnostics.next = wrap_node(actions.moves.item.fn({ where = "next", what = "diag" }))
-  node.navigate.diagnostics.next_recursive = wrap_node(actions.moves.item.fn({ where = "next", what = "diag", recurse = true }))
-  node.navigate.diagnostics.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "diag" }))
-  node.navigate.diagnostics.prev_recursive = wrap_node(actions.moves.item.fn({ where = "prev", what = "diag", recurse = true }))
-  node.navigate.opened.next = wrap_node(actions.moves.item.fn({ where = "next", what = "opened" }))
-  node.navigate.opened.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "opened" }))
-  node.expand = wrap_node(actions.tree.modifiers.expand.node)
-  node.collapse = wrap_node(actions.tree.modifiers.collapse.node)
-  node.buffer.delete = wrap_node(function(n, opts) actions.node.buffer.delete(n, opts) end)
-  node.buffer.wipe = wrap_node(function(n, opts) actions.node.buffer.wipe(n, opts) end)
-end
+---@class ApiNodeDeleteWipeBufferOpts
+---@field force boolean|nil default false
 
-function M.events(events)
-  events.subscribe = require("nvim-tree.events").subscribe
-  events.Event = require("nvim-tree.events").Event
-end
+Api.node.buffer.delete = wrap_node(function(node, opts)
+  actions.node.buffer.delete(node, opts)
+end)
+Api.node.buffer.wipe = wrap_node(function(node, opts)
+  actions.node.buffer.wipe(node, opts)
+end)
 
-function M.filter(filter)
-  filter.live_filter.start = wrap_explorer_member("live_filter", "start_filtering")
-  filter.live_filter.clear = wrap_explorer_member("live_filter", "clear_filter")
-end
+Api.tree.reload_git = wrap_explorer("reload_git")
 
-function M.marks(marks)
-  marks.get = wrap_node(wrap_explorer_member("marks", "get"))
-  marks.list = wrap_explorer_member("marks", "list")
-  marks.toggle = wrap_node(wrap_explorer_member("marks", "toggle"))
-  marks.clear = wrap_explorer_member("marks", "clear")
-  marks.bulk.delete = wrap_explorer_member("marks", "bulk_delete")
-  marks.bulk.trash = wrap_explorer_member("marks", "bulk_trash")
-  marks.bulk.move = wrap_explorer_member("marks", "bulk_move")
-  marks.navigate.next = wrap_explorer_member("marks", "navigate_next")
-  marks.navigate.prev = wrap_explorer_member("marks", "navigate_prev")
-  marks.navigate.select = wrap_explorer_member("marks", "navigate_select")
-end
+Api.events.subscribe = events.subscribe
+Api.events.Event = events.Event
 
-function M.map(map)
-  map.get_keymap = wrap(keymap.get_keymap)
-  map.get_keymap_default = wrap(keymap.get_keymap_default)
-  map.default_on_attach = keymap.default_on_attach
-end
+Api.filter.live_filter.start = wrap_explorer_member("live_filter", "start_filtering")
+Api.filter.live_filter.clear = wrap_explorer_member("live_filter", "clear_filter")
 
-function M.health(health)
-  health.hi_test = wrap(appearance_hi_test)
-end
+Api.marks.get = wrap_node(wrap_explorer_member("marks", "get"))
+Api.marks.list = wrap_explorer_member("marks", "list")
+Api.marks.toggle = wrap_node(wrap_explorer_member("marks", "toggle"))
+Api.marks.clear = wrap_explorer_member("marks", "clear")
+Api.marks.bulk.delete = wrap_explorer_member("marks", "bulk_delete")
+Api.marks.bulk.trash = wrap_explorer_member("marks", "bulk_trash")
+Api.marks.bulk.move = wrap_explorer_member("marks", "bulk_move")
+Api.marks.navigate.next = wrap_explorer_member("marks", "navigate_next")
+Api.marks.navigate.prev = wrap_explorer_member("marks", "navigate_prev")
+Api.marks.navigate.select = wrap_explorer_member("marks", "navigate_select")
 
-function M.commands(commands)
-  commands.get = wrap(function() return require("nvim-tree.commands").get() end)
-end
+Api.map.get_keymap = wrap(keymap.get_keymap)
+Api.map.get_keymap_default = wrap(keymap.get_keymap_default)
+Api.map.default_on_attach = keymap.default_on_attach
 
-return M
+Api.health.hi_test = wrap(appearance_hi_test)
+
+Api.commands.get = wrap(function()
+  return require("nvim-tree.commands").get()
+end)
+
+Api.decorator = {}
+---Create a decorator class by calling :extend()
+---See :help nvim-tree-decorators
+---@type nvim_tree.api.decorator.UserDecorator
+Api.decorator.UserDecorator = UserDecorator --[[@as nvim_tree.api.decorator.UserDecorator]]
+
+
+--
+--Legacy API mappings
+--
+Api.git = {
+  reload = Api.tree.reload_git,
+}
+Api.live_filter = {
+  start = Api.filter.live_filter.start,
+  clear = Api.filter.live_filter.clear,
+}
+Api.config = {
+  mappings = {
+    get_keymap = Api.map.get_keymap,
+    get_keymap_default = Api.map.get_keymap_default,
+    default_on_attach = Api.map.default_on_attach,
+  }
+}
+Api.diagnostics = {
+  hi_test = Api.health.hi_test,
+}
+end
diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index c47c047014f..37b27307d94 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -73,9 +73,10 @@
 
 
 --
---Load and hydrate all
+--Load the (empty) meta definitions
 --
 local api = {
+  commands = require("nvim-tree._meta.api.commands"),
   events = require("nvim-tree._meta.api.events"),
   filter = require("nvim-tree._meta.api.filter"),
   fs = require("nvim-tree._meta.api.fs"),
@@ -88,32 +89,8 @@ local api = {
 
 
 --
---Legacy mappings
+--Hydrate the implementations
 --
-api.git = {
-  reload = api.tree.reload_git,
-}
-api.live_filter = {
-  start = api.filter.live_filter.start,
-  clear = api.filter.live_filter.clear,
-}
-api.config = {
-  mappings = {
-    get_keymap = api.map.get_keymap,
-    get_keymap_default = api.map.get_keymap_default,
-    default_on_attach = api.map.default_on_attach,
-  }
-}
-api.diagnostics = {
-  hi_test = api.health.hi_test,
-}
-
--- TODO #3241 create a proper decorator API
-api.decorator = {}
-
----Create a decorator class by calling :extend()
----See :help nvim-tree-decorators
----@type nvim_tree.api.decorator.UserDecorator
-api.decorator.UserDecorator = require("nvim-tree.renderer.decorator.user") --[[@as nvim_tree.api.decorator.UserDecorator]]
+require("nvim-tree.api-impl")(api)
 
 return api

From f1d1f1b64f6b5a924b8da0fb63aab6a9332966f0 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Tue, 20 Jan 2026 14:49:31 +1100
Subject: [PATCH 108/170] docs(#3088): remove old Api classes, rename impl Api
 -> api

---
 lua/nvim-tree/api-impl.lua | 613 +++++++++++++++++--------------------
 1 file changed, 287 insertions(+), 326 deletions(-)

diff --git a/lua/nvim-tree/api-impl.lua b/lua/nvim-tree/api-impl.lua
index e8683b0ee7b..5d9fcfdb0b9 100644
--- a/lua/nvim-tree/api-impl.lua
+++ b/lua/nvim-tree/api-impl.lua
@@ -14,356 +14,317 @@ local FileLinkNode = require("nvim-tree.node.file-link")
 local RootNode = require("nvim-tree.node.root")
 local UserDecorator = require("nvim-tree.renderer.decorator.user")
 
-return function(Api)
----Print error when setup not called.
----@param fn fun(...): any
----@return fun(...): any
-local function wrap(fn)
-  return function(...)
-    if vim.g.NvimTreeSetup == 1 then
-      return fn(...)
-    else
-      notify.error("nvim-tree setup not called")
+-- hydrates meta api definitions with implementations
+return function(api)
+
+  ---Print error when setup not called.
+  ---@param fn fun(...): any
+  ---@return fun(...): any
+  local function wrap(fn)
+    return function(...)
+      if vim.g.NvimTreeSetup == 1 then
+        return fn(...)
+      else
+        notify.error("nvim-tree setup not called")
+      end
     end
   end
-end
 
----Invoke a method on the singleton explorer.
----Print error when setup not called.
----@param explorer_method string explorer method name
----@return fun(...): any
-local function wrap_explorer(explorer_method)
-  return wrap(function(...)
-    local explorer = core.get_explorer()
-    if explorer then
-      return explorer[explorer_method](explorer, ...)
+  ---Invoke a method on the singleton explorer.
+  ---Print error when setup not called.
+  ---@param explorer_method string explorer method name
+  ---@return fun(...): any
+  local function wrap_explorer(explorer_method)
+    return wrap(function(...)
+      local explorer = core.get_explorer()
+      if explorer then
+        return explorer[explorer_method](explorer, ...)
+      end
+    end)
+  end
+
+  ---Inject the node as the first argument if present otherwise do nothing.
+  ---@param fn fun(node: Node, ...): any
+  ---@return fun(node: Node?, ...): any
+  local function wrap_node(fn)
+    return function(node, ...)
+      node = node or wrap_explorer("get_node_at_cursor")()
+      if node then
+        return fn(node, ...)
+      end
     end
-  end)
-end
+  end
 
----Inject the node as the first argument if present otherwise do nothing.
----@param fn fun(node: Node, ...): any
----@return fun(node: Node?, ...): any
-local function wrap_node(fn)
-  return function(node, ...)
-    node = node or wrap_explorer("get_node_at_cursor")()
-    if node then
+  ---Inject the node or nil as the first argument if absent.
+  ---@param fn fun(node: Node?, ...): any
+  ---@return fun(node: Node?, ...): any
+  local function wrap_node_or_nil(fn)
+    return function(node, ...)
+      node = node or wrap_explorer("get_node_at_cursor")()
       return fn(node, ...)
     end
   end
-end
 
----Inject the node or nil as the first argument if absent.
----@param fn fun(node: Node?, ...): any
----@return fun(node: Node?, ...): any
-local function wrap_node_or_nil(fn)
-  return function(node, ...)
-    node = node or wrap_explorer("get_node_at_cursor")()
-    return fn(node, ...)
+  ---Invoke a member's method on the singleton explorer.
+  ---Print error when setup not called.
+  ---@param explorer_member string explorer member name
+  ---@param member_method string method name to invoke on member
+  ---@param ... any passed to method
+  ---@return fun(...): any
+  local function wrap_explorer_member_args(explorer_member, member_method, ...)
+    local method_args = ...
+    return wrap(function(...)
+      local explorer = core.get_explorer()
+      if explorer then
+        return explorer[explorer_member][member_method](explorer[explorer_member], method_args, ...)
+      end
+    end)
   end
-end
 
----Invoke a member's method on the singleton explorer.
----Print error when setup not called.
----@param explorer_member string explorer member name
----@param member_method string method name to invoke on member
----@param ... any passed to method
----@return fun(...): any
-local function wrap_explorer_member_args(explorer_member, member_method, ...)
-  local method_args = ...
-  return wrap(function(...)
-    local explorer = core.get_explorer()
-    if explorer then
-      return explorer[explorer_member][member_method](explorer[explorer_member], method_args, ...)
-    end
+  ---Invoke a member's method on the singleton explorer.
+  ---Print error when setup not called.
+  ---@param explorer_member string explorer member name
+  ---@param member_method string method name to invoke on member
+  ---@return fun(...): any
+  local function wrap_explorer_member(explorer_member, member_method)
+    return wrap(function(...)
+      local explorer = core.get_explorer()
+      if explorer then
+        return explorer[explorer_member][member_method](explorer[explorer_member], ...)
+      end
+    end)
+  end
+
+  api.tree.open = wrap(actions.tree.open.fn)
+  api.tree.focus = api.tree.open
+
+  api.tree.toggle = wrap(actions.tree.toggle.fn)
+  api.tree.close = wrap(view.close)
+  api.tree.close_in_this_tab = wrap(view.close_this_tab_only)
+  api.tree.close_in_all_tabs = wrap(view.close_all_tabs)
+  api.tree.reload = wrap_explorer("reload_explorer")
+
+  api.tree.resize = wrap(actions.tree.resize.fn)
+
+  api.tree.change_root = wrap(function(...)
+    require("nvim-tree").change_dir(...)
   end)
-end
 
----Invoke a member's method on the singleton explorer.
----Print error when setup not called.
----@param explorer_member string explorer member name
----@param member_method string method name to invoke on member
----@return fun(...): any
-local function wrap_explorer_member(explorer_member, member_method)
-  return wrap(function(...)
-    local explorer = core.get_explorer()
-    if explorer then
-      return explorer[explorer_member][member_method](explorer[explorer_member], ...)
+  api.tree.change_root_to_node = wrap_node(function(node)
+    if node.name == ".." or node:is(RootNode) then
+      actions.root.change_dir.fn("..")
+      return
+    end
+
+    if node:is(FileNode) and node.parent ~= nil then
+      actions.root.change_dir.fn(node.parent:last_group_node().absolute_path)
+      return
+    end
+
+    if node:is(DirectoryNode) then
+      actions.root.change_dir.fn(node:last_group_node().absolute_path)
+      return
     end
   end)
-end
 
----@class ApiTreeOpenOpts
----@field path string|nil path
----@field current_window boolean|nil default false
----@field winid number|nil
----@field find_file boolean|nil default false
----@field update_root boolean|nil default false
-
-Api.tree.open = wrap(actions.tree.open.fn)
-Api.tree.focus = Api.tree.open
-
----@class ApiTreeToggleOpts
----@field path string|nil
----@field current_window boolean|nil default false
----@field winid number|nil
----@field find_file boolean|nil default false
----@field update_root boolean|nil default false
----@field focus boolean|nil default true
-
-Api.tree.toggle = wrap(actions.tree.toggle.fn)
-Api.tree.close = wrap(view.close)
-Api.tree.close_in_this_tab = wrap(view.close_this_tab_only)
-Api.tree.close_in_all_tabs = wrap(view.close_all_tabs)
-Api.tree.reload = wrap_explorer("reload_explorer")
-
----@class ApiTreeResizeOpts
----@field width string|function|number|table|nil
----@field absolute number|nil
----@field relative number|nil
-
-Api.tree.resize = wrap(actions.tree.resize.fn)
-
-Api.tree.change_root = wrap(function(...)
-  require("nvim-tree").change_dir(...)
-end)
-
-Api.tree.change_root_to_node = wrap_node(function(node)
-  if node.name == ".." or node:is(RootNode) then
-    actions.root.change_dir.fn("..")
-    return
-  end
+  api.tree.change_root_to_parent = wrap_node(wrap_explorer("dir_up"))
+  api.tree.get_node_under_cursor = wrap_explorer("get_node_at_cursor")
+  api.tree.get_nodes = wrap_explorer("get_nodes")
+
+  api.tree.find_file = wrap(actions.tree.find_file.fn)
+  api.tree.search_node = wrap(actions.finders.search_node.fn)
+
+  api.tree.collapse_all = wrap(actions.tree.modifiers.collapse.all)
+
+  api.tree.expand_all = wrap_node(actions.tree.modifiers.expand.all)
+  api.tree.toggle_enable_filters = wrap_explorer_member("filters", "toggle")
+  api.tree.toggle_gitignore_filter = wrap_explorer_member_args("filters", "toggle", "git_ignored")
+  api.tree.toggle_git_clean_filter = wrap_explorer_member_args("filters", "toggle", "git_clean")
+  api.tree.toggle_no_buffer_filter = wrap_explorer_member_args("filters", "toggle", "no_buffer")
+  api.tree.toggle_custom_filter = wrap_explorer_member_args("filters", "toggle", "custom")
+  api.tree.toggle_hidden_filter = wrap_explorer_member_args("filters", "toggle", "dotfiles")
+  api.tree.toggle_no_bookmark_filter = wrap_explorer_member_args("filters", "toggle", "no_bookmark")
+  api.tree.toggle_help = wrap(help.toggle)
+  api.tree.is_tree_buf = wrap(utils.is_nvim_tree_buf)
+
+  api.tree.is_visible = wrap(view.is_visible)
+
+  api.tree.winid = wrap(view.winid)
+
+  api.fs.create = wrap_node_or_nil(actions.fs.create_file.fn)
+  api.fs.remove = wrap_node(actions.fs.remove_file.fn)
+  api.fs.trash = wrap_node(actions.fs.trash.fn)
+  api.fs.rename_node = wrap_node(actions.fs.rename_file.fn(":t"))
+  api.fs.rename = wrap_node(actions.fs.rename_file.fn(":t"))
+  api.fs.rename_sub = wrap_node(actions.fs.rename_file.fn(":p:h"))
+  api.fs.rename_basename = wrap_node(actions.fs.rename_file.fn(":t:r"))
+  api.fs.rename_full = wrap_node(actions.fs.rename_file.fn(":p"))
+  api.fs.cut = wrap_node(wrap_explorer_member("clipboard", "cut"))
+  api.fs.paste = wrap_node(wrap_explorer_member("clipboard", "paste"))
+  api.fs.clear_clipboard = wrap_explorer_member("clipboard", "clear_clipboard")
+  api.fs.print_clipboard = wrap_explorer_member("clipboard", "print_clipboard")
+  api.fs.copy.node = wrap_node(wrap_explorer_member("clipboard", "copy"))
+  api.fs.copy.absolute_path = wrap_node(wrap_explorer_member("clipboard", "copy_absolute_path"))
+  api.fs.copy.filename = wrap_node(wrap_explorer_member("clipboard", "copy_filename"))
+  api.fs.copy.basename = wrap_node(wrap_explorer_member("clipboard", "copy_basename"))
+  api.fs.copy.relative_path = wrap_node(wrap_explorer_member("clipboard", "copy_path"))
+  ---
+  ---@class NodeEditOpts
+  ---@field quit_on_open boolean|nil default false
+  ---@field focus boolean|nil default true
+
+  ---@param mode string
+  ---@param node Node
+  ---@param edit_opts NodeEditOpts?
+  local function edit(mode, node, edit_opts)
+    local file_link = node:as(FileLinkNode)
+    local path = file_link and file_link.link_to or node.absolute_path
+    local cur_tabpage = vim.api.nvim_get_current_tabpage()
 
-  if node:is(FileNode) and node.parent ~= nil then
-    actions.root.change_dir.fn(node.parent:last_group_node().absolute_path)
-    return
-  end
+    actions.node.open_file.fn(mode, path)
 
-  if node:is(DirectoryNode) then
-    actions.root.change_dir.fn(node:last_group_node().absolute_path)
-    return
-  end
-end)
-
-Api.tree.change_root_to_parent = wrap_node(wrap_explorer("dir_up"))
-Api.tree.get_node_under_cursor = wrap_explorer("get_node_at_cursor")
-Api.tree.get_nodes = wrap_explorer("get_nodes")
-
----@class ApiTreeFindFileOpts
----@field buf string|number|nil
----@field open boolean|nil default false
----@field current_window boolean|nil default false
----@field winid number|nil
----@field update_root boolean|nil default false
----@field focus boolean|nil default false
-
-Api.tree.find_file = wrap(actions.tree.find_file.fn)
-Api.tree.search_node = wrap(actions.finders.search_node.fn)
-
----@class ApiCollapseOpts
----@field keep_buffers boolean|nil default false
-
-Api.tree.collapse_all = wrap(actions.tree.modifiers.collapse.all)
-
----@class ApiTreeExpandOpts
----@field expand_until (fun(expansion_count: integer, node: Node): boolean)|nil
-
-Api.tree.expand_all = wrap_node(actions.tree.modifiers.expand.all)
-Api.tree.toggle_enable_filters = wrap_explorer_member("filters", "toggle")
-Api.tree.toggle_gitignore_filter = wrap_explorer_member_args("filters", "toggle", "git_ignored")
-Api.tree.toggle_git_clean_filter = wrap_explorer_member_args("filters", "toggle", "git_clean")
-Api.tree.toggle_no_buffer_filter = wrap_explorer_member_args("filters", "toggle", "no_buffer")
-Api.tree.toggle_custom_filter = wrap_explorer_member_args("filters", "toggle", "custom")
-Api.tree.toggle_hidden_filter = wrap_explorer_member_args("filters", "toggle", "dotfiles")
-Api.tree.toggle_no_bookmark_filter = wrap_explorer_member_args("filters", "toggle", "no_bookmark")
-Api.tree.toggle_help = wrap(help.toggle)
-Api.tree.is_tree_buf = wrap(utils.is_nvim_tree_buf)
-
----@class ApiTreeIsVisibleOpts
----@field tabpage number|nil
----@field any_tabpage boolean|nil default false
-
-Api.tree.is_visible = wrap(view.is_visible)
-
----@class ApiTreeWinIdOpts
----@field tabpage number|nil default nil
-
-Api.tree.winid = wrap(view.winid)
-
-Api.fs.create = wrap_node_or_nil(actions.fs.create_file.fn)
-Api.fs.remove = wrap_node(actions.fs.remove_file.fn)
-Api.fs.trash = wrap_node(actions.fs.trash.fn)
-Api.fs.rename_node = wrap_node(actions.fs.rename_file.fn(":t"))
-Api.fs.rename = wrap_node(actions.fs.rename_file.fn(":t"))
-Api.fs.rename_sub = wrap_node(actions.fs.rename_file.fn(":p:h"))
-Api.fs.rename_basename = wrap_node(actions.fs.rename_file.fn(":t:r"))
-Api.fs.rename_full = wrap_node(actions.fs.rename_file.fn(":p"))
-Api.fs.cut = wrap_node(wrap_explorer_member("clipboard", "cut"))
-Api.fs.paste = wrap_node(wrap_explorer_member("clipboard", "paste"))
-Api.fs.clear_clipboard = wrap_explorer_member("clipboard", "clear_clipboard")
-Api.fs.print_clipboard = wrap_explorer_member("clipboard", "print_clipboard")
-Api.fs.copy.node = wrap_node(wrap_explorer_member("clipboard", "copy"))
-Api.fs.copy.absolute_path = wrap_node(wrap_explorer_member("clipboard", "copy_absolute_path"))
-Api.fs.copy.filename = wrap_node(wrap_explorer_member("clipboard", "copy_filename"))
-Api.fs.copy.basename = wrap_node(wrap_explorer_member("clipboard", "copy_basename"))
-Api.fs.copy.relative_path = wrap_node(wrap_explorer_member("clipboard", "copy_path"))
----
----@class NodeEditOpts
----@field quit_on_open boolean|nil default false
----@field focus boolean|nil default true
-
----@param mode string
----@param node Node
----@param edit_opts NodeEditOpts?
-local function edit(mode, node, edit_opts)
-  local file_link = node:as(FileLinkNode)
-  local path = file_link and file_link.link_to or node.absolute_path
-  local cur_tabpage = vim.api.nvim_get_current_tabpage()
-
-  actions.node.open_file.fn(mode, path)
-
-  edit_opts = edit_opts or {}
-
-  local mode_unsupported_quit_on_open = mode == "drop" or mode == "tab_drop" or mode == "edit_in_place"
-  if not mode_unsupported_quit_on_open and edit_opts.quit_on_open then
-    view.close(cur_tabpage)
-  end
+    edit_opts = edit_opts or {}
 
-  local mode_unsupported_focus = mode == "drop" or mode == "tab_drop" or mode == "edit_in_place"
-  local focus = edit_opts.focus == nil or edit_opts.focus == true
-  if not mode_unsupported_focus and not focus then
-    -- if mode == "tabnew" a new tab will be opened and we need to focus back to the previous tab
-    if mode == "tabnew" then
-      vim.cmd(":tabprev")
+    local mode_unsupported_quit_on_open = mode == "drop" or mode == "tab_drop" or mode == "edit_in_place"
+    if not mode_unsupported_quit_on_open and edit_opts.quit_on_open then
+      view.close(cur_tabpage)
     end
-    view.focus()
-  end
-end
 
----@param mode string
----@param toggle_group boolean?
----@return fun(node: Node, edit_opts: NodeEditOpts?)
-local function open_or_expand_or_dir_up(mode, toggle_group)
-  ---@param node Node
-  ---@param edit_opts NodeEditOpts?
-  return function(node, edit_opts)
-    local root = node:as(RootNode)
-    local dir = node:as(DirectoryNode)
+    local mode_unsupported_focus = mode == "drop" or mode == "tab_drop" or mode == "edit_in_place"
+    local focus = edit_opts.focus == nil or edit_opts.focus == true
+    if not mode_unsupported_focus and not focus then
+      -- if mode == "tabnew" a new tab will be opened and we need to focus back to the previous tab
+      if mode == "tabnew" then
+        vim.cmd(":tabprev")
+      end
+      view.focus()
+    end
+  end
 
-    if root or node.name == ".." then
-      actions.root.change_dir.fn("..")
-    elseif dir then
-      dir:expand_or_collapse(toggle_group)
-    elseif not toggle_group then
-      edit(mode, node, edit_opts)
+  ---@param mode string
+  ---@param toggle_group boolean?
+  ---@return fun(node: Node, edit_opts: NodeEditOpts?)
+  local function open_or_expand_or_dir_up(mode, toggle_group)
+    ---@param node Node
+    ---@param edit_opts NodeEditOpts?
+    return function(node, edit_opts)
+      local root = node:as(RootNode)
+      local dir = node:as(DirectoryNode)
+
+      if root or node.name == ".." then
+        actions.root.change_dir.fn("..")
+      elseif dir then
+        dir:expand_or_collapse(toggle_group)
+      elseif not toggle_group then
+        edit(mode, node, edit_opts)
+      end
     end
   end
-end
 
-Api.node.open.edit = wrap_node(open_or_expand_or_dir_up("edit"))
-Api.node.open.drop = wrap_node(open_or_expand_or_dir_up("drop"))
-Api.node.open.tab_drop = wrap_node(open_or_expand_or_dir_up("tab_drop"))
-Api.node.open.replace_tree_buffer = wrap_node(open_or_expand_or_dir_up("edit_in_place"))
-Api.node.open.no_window_picker = wrap_node(open_or_expand_or_dir_up("edit_no_picker"))
-Api.node.open.vertical = wrap_node(open_or_expand_or_dir_up("vsplit"))
-Api.node.open.vertical_no_picker = wrap_node(open_or_expand_or_dir_up("vsplit_no_picker"))
-Api.node.open.horizontal = wrap_node(open_or_expand_or_dir_up("split"))
-Api.node.open.horizontal_no_picker = wrap_node(open_or_expand_or_dir_up("split_no_picker"))
-Api.node.open.tab = wrap_node(open_or_expand_or_dir_up("tabnew"))
-Api.node.open.toggle_group_empty = wrap_node(open_or_expand_or_dir_up("toggle_group_empty", true))
-Api.node.open.preview = wrap_node(open_or_expand_or_dir_up("preview"))
-Api.node.open.preview_no_picker = wrap_node(open_or_expand_or_dir_up("preview_no_picker"))
-
-Api.node.show_info_popup = wrap_node(actions.node.file_popup.toggle_file_info)
-Api.node.run.cmd = wrap_node(actions.node.run_command.run_file_command)
-Api.node.run.system = wrap_node(actions.node.system_open.fn)
-
-Api.node.navigate.sibling.next = wrap_node(actions.moves.sibling.fn("next"))
-Api.node.navigate.sibling.prev = wrap_node(actions.moves.sibling.fn("prev"))
-Api.node.navigate.sibling.first = wrap_node(actions.moves.sibling.fn("first"))
-Api.node.navigate.sibling.last = wrap_node(actions.moves.sibling.fn("last"))
-Api.node.navigate.parent = wrap_node(actions.moves.parent.fn(false))
-Api.node.navigate.parent_close = wrap_node(actions.moves.parent.fn(true))
-Api.node.navigate.git.next = wrap_node(actions.moves.item.fn({ where = "next", what = "git" }))
-Api.node.navigate.git.next_skip_gitignored = wrap_node(actions.moves.item.fn({ where = "next", what = "git", skip_gitignored = true }))
-Api.node.navigate.git.next_recursive = wrap_node(actions.moves.item.fn({ where = "next", what = "git", recurse = true }))
-Api.node.navigate.git.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "git" }))
-Api.node.navigate.git.prev_skip_gitignored = wrap_node(actions.moves.item.fn({ where = "prev", what = "git", skip_gitignored = true }))
-Api.node.navigate.git.prev_recursive = wrap_node(actions.moves.item.fn({ where = "prev", what = "git", recurse = true }))
-Api.node.navigate.diagnostics.next = wrap_node(actions.moves.item.fn({ where = "next", what = "diag" }))
-Api.node.navigate.diagnostics.next_recursive = wrap_node(actions.moves.item.fn({ where = "next", what = "diag", recurse = true }))
-Api.node.navigate.diagnostics.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "diag" }))
-Api.node.navigate.diagnostics.prev_recursive = wrap_node(actions.moves.item.fn({ where = "prev", what = "diag", recurse = true }))
-Api.node.navigate.opened.next = wrap_node(actions.moves.item.fn({ where = "next", what = "opened" }))
-Api.node.navigate.opened.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "opened" }))
-
-Api.node.expand = wrap_node(actions.tree.modifiers.expand.node)
-Api.node.collapse = wrap_node(actions.tree.modifiers.collapse.node)
-
----@class ApiNodeDeleteWipeBufferOpts
----@field force boolean|nil default false
-
-Api.node.buffer.delete = wrap_node(function(node, opts)
-  actions.node.buffer.delete(node, opts)
-end)
-Api.node.buffer.wipe = wrap_node(function(node, opts)
-  actions.node.buffer.wipe(node, opts)
-end)
-
-Api.tree.reload_git = wrap_explorer("reload_git")
-
-Api.events.subscribe = events.subscribe
-Api.events.Event = events.Event
-
-Api.filter.live_filter.start = wrap_explorer_member("live_filter", "start_filtering")
-Api.filter.live_filter.clear = wrap_explorer_member("live_filter", "clear_filter")
-
-Api.marks.get = wrap_node(wrap_explorer_member("marks", "get"))
-Api.marks.list = wrap_explorer_member("marks", "list")
-Api.marks.toggle = wrap_node(wrap_explorer_member("marks", "toggle"))
-Api.marks.clear = wrap_explorer_member("marks", "clear")
-Api.marks.bulk.delete = wrap_explorer_member("marks", "bulk_delete")
-Api.marks.bulk.trash = wrap_explorer_member("marks", "bulk_trash")
-Api.marks.bulk.move = wrap_explorer_member("marks", "bulk_move")
-Api.marks.navigate.next = wrap_explorer_member("marks", "navigate_next")
-Api.marks.navigate.prev = wrap_explorer_member("marks", "navigate_prev")
-Api.marks.navigate.select = wrap_explorer_member("marks", "navigate_select")
-
-Api.map.get_keymap = wrap(keymap.get_keymap)
-Api.map.get_keymap_default = wrap(keymap.get_keymap_default)
-Api.map.default_on_attach = keymap.default_on_attach
-
-Api.health.hi_test = wrap(appearance_hi_test)
-
-Api.commands.get = wrap(function()
-  return require("nvim-tree.commands").get()
-end)
-
-Api.decorator = {}
----Create a decorator class by calling :extend()
----See :help nvim-tree-decorators
----@type nvim_tree.api.decorator.UserDecorator
-Api.decorator.UserDecorator = UserDecorator --[[@as nvim_tree.api.decorator.UserDecorator]]
-
-
---
---Legacy API mappings
---
-Api.git = {
-  reload = Api.tree.reload_git,
-}
-Api.live_filter = {
-  start = Api.filter.live_filter.start,
-  clear = Api.filter.live_filter.clear,
-}
-Api.config = {
-  mappings = {
-    get_keymap = Api.map.get_keymap,
-    get_keymap_default = Api.map.get_keymap_default,
-    default_on_attach = Api.map.default_on_attach,
+  api.node.open.edit = wrap_node(open_or_expand_or_dir_up("edit"))
+  api.node.open.drop = wrap_node(open_or_expand_or_dir_up("drop"))
+  api.node.open.tab_drop = wrap_node(open_or_expand_or_dir_up("tab_drop"))
+  api.node.open.replace_tree_buffer = wrap_node(open_or_expand_or_dir_up("edit_in_place"))
+  api.node.open.no_window_picker = wrap_node(open_or_expand_or_dir_up("edit_no_picker"))
+  api.node.open.vertical = wrap_node(open_or_expand_or_dir_up("vsplit"))
+  api.node.open.vertical_no_picker = wrap_node(open_or_expand_or_dir_up("vsplit_no_picker"))
+  api.node.open.horizontal = wrap_node(open_or_expand_or_dir_up("split"))
+  api.node.open.horizontal_no_picker = wrap_node(open_or_expand_or_dir_up("split_no_picker"))
+  api.node.open.tab = wrap_node(open_or_expand_or_dir_up("tabnew"))
+  api.node.open.toggle_group_empty = wrap_node(open_or_expand_or_dir_up("toggle_group_empty", true))
+  api.node.open.preview = wrap_node(open_or_expand_or_dir_up("preview"))
+  api.node.open.preview_no_picker = wrap_node(open_or_expand_or_dir_up("preview_no_picker"))
+
+  api.node.show_info_popup = wrap_node(actions.node.file_popup.toggle_file_info)
+  api.node.run.cmd = wrap_node(actions.node.run_command.run_file_command)
+  api.node.run.system = wrap_node(actions.node.system_open.fn)
+
+  api.node.navigate.sibling.next = wrap_node(actions.moves.sibling.fn("next"))
+  api.node.navigate.sibling.prev = wrap_node(actions.moves.sibling.fn("prev"))
+  api.node.navigate.sibling.first = wrap_node(actions.moves.sibling.fn("first"))
+  api.node.navigate.sibling.last = wrap_node(actions.moves.sibling.fn("last"))
+  api.node.navigate.parent = wrap_node(actions.moves.parent.fn(false))
+  api.node.navigate.parent_close = wrap_node(actions.moves.parent.fn(true))
+  api.node.navigate.git.next = wrap_node(actions.moves.item.fn({ where = "next", what = "git" }))
+  api.node.navigate.git.next_skip_gitignored = wrap_node(actions.moves.item.fn({ where = "next", what = "git", skip_gitignored = true }))
+  api.node.navigate.git.next_recursive = wrap_node(actions.moves.item.fn({ where = "next", what = "git", recurse = true }))
+  api.node.navigate.git.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "git" }))
+  api.node.navigate.git.prev_skip_gitignored = wrap_node(actions.moves.item.fn({ where = "prev", what = "git", skip_gitignored = true }))
+  api.node.navigate.git.prev_recursive = wrap_node(actions.moves.item.fn({ where = "prev", what = "git", recurse = true }))
+  api.node.navigate.diagnostics.next = wrap_node(actions.moves.item.fn({ where = "next", what = "diag" }))
+  api.node.navigate.diagnostics.next_recursive = wrap_node(actions.moves.item.fn({ where = "next", what = "diag", recurse = true }))
+  api.node.navigate.diagnostics.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "diag" }))
+  api.node.navigate.diagnostics.prev_recursive = wrap_node(actions.moves.item.fn({ where = "prev", what = "diag", recurse = true }))
+  api.node.navigate.opened.next = wrap_node(actions.moves.item.fn({ where = "next", what = "opened" }))
+  api.node.navigate.opened.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "opened" }))
+
+  api.node.expand = wrap_node(actions.tree.modifiers.expand.node)
+  api.node.collapse = wrap_node(actions.tree.modifiers.collapse.node)
+
+  ---@class ApiNodeDeleteWipeBufferOpts
+  ---@field force boolean|nil default false
+
+  api.node.buffer.delete = wrap_node(function(node, opts)
+    actions.node.buffer.delete(node, opts)
+  end)
+  api.node.buffer.wipe = wrap_node(function(node, opts)
+    actions.node.buffer.wipe(node, opts)
+  end)
+
+  api.tree.reload_git = wrap_explorer("reload_git")
+
+  api.events.subscribe = events.subscribe
+  api.events.Event = events.Event
+
+  api.filter.live_filter.start = wrap_explorer_member("live_filter", "start_filtering")
+  api.filter.live_filter.clear = wrap_explorer_member("live_filter", "clear_filter")
+
+  api.marks.get = wrap_node(wrap_explorer_member("marks", "get"))
+  api.marks.list = wrap_explorer_member("marks", "list")
+  api.marks.toggle = wrap_node(wrap_explorer_member("marks", "toggle"))
+  api.marks.clear = wrap_explorer_member("marks", "clear")
+  api.marks.bulk.delete = wrap_explorer_member("marks", "bulk_delete")
+  api.marks.bulk.trash = wrap_explorer_member("marks", "bulk_trash")
+  api.marks.bulk.move = wrap_explorer_member("marks", "bulk_move")
+  api.marks.navigate.next = wrap_explorer_member("marks", "navigate_next")
+  api.marks.navigate.prev = wrap_explorer_member("marks", "navigate_prev")
+  api.marks.navigate.select = wrap_explorer_member("marks", "navigate_select")
+
+  api.map.get_keymap = wrap(keymap.get_keymap)
+  api.map.get_keymap_default = wrap(keymap.get_keymap_default)
+  api.map.default_on_attach = keymap.default_on_attach
+
+  api.health.hi_test = wrap(appearance_hi_test)
+
+  api.commands.get = wrap(function()
+    return require("nvim-tree.commands").get()
+  end)
+
+  api.decorator = {}
+  ---Create a decorator class by calling :extend()
+  ---See :help nvim-tree-decorators
+  ---@type nvim_tree.api.decorator.UserDecorator
+  api.decorator.UserDecorator = UserDecorator --[[@as nvim_tree.api.decorator.UserDecorator]]
+
+
+  --
+  --Legacy API mappings
+  --
+  api.git = {
+    reload = api.tree.reload_git,
+  }
+  api.live_filter = {
+    start = api.filter.live_filter.start,
+    clear = api.filter.live_filter.clear,
+  }
+  api.config = {
+    mappings = {
+      get_keymap = api.map.get_keymap,
+      get_keymap_default = api.map.get_keymap_default,
+      default_on_attach = api.map.default_on_attach,
+    }
+  }
+  api.diagnostics = {
+    hi_test = api.health.hi_test,
   }
-}
-Api.diagnostics = {
-  hi_test = Api.health.hi_test,
-}
 end

From 506def5525f9d09ad6059f21dd06b0be4cead476 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Tue, 20 Jan 2026 15:02:31 +1100
Subject: [PATCH 109/170] docs(#3088): tidy migrated annotations

---
 lua/nvim-tree/actions/node/buffer.lua             | 3 ---
 lua/nvim-tree/actions/tree/find-file.lua          | 2 +-
 lua/nvim-tree/actions/tree/modifiers/collapse.lua | 8 ++++----
 lua/nvim-tree/actions/tree/modifiers/expand.lua   | 8 ++++----
 lua/nvim-tree/actions/tree/open.lua               | 2 +-
 lua/nvim-tree/actions/tree/resize.lua             | 2 +-
 lua/nvim-tree/actions/tree/toggle.lua             | 8 ++++----
 lua/nvim-tree/view.lua                            | 4 ++--
 8 files changed, 17 insertions(+), 20 deletions(-)

diff --git a/lua/nvim-tree/actions/node/buffer.lua b/lua/nvim-tree/actions/node/buffer.lua
index 050c207572a..7e6610f84af 100644
--- a/lua/nvim-tree/actions/node/buffer.lua
+++ b/lua/nvim-tree/actions/node/buffer.lua
@@ -5,14 +5,12 @@ local M = {}
 
 ---@param node Node
 ---@param opts? nvim_tree.api.node.buffer.RemoveOpts
----@return nil
 function M.delete(node, opts)
   M.delete_buffer("delete", node.absolute_path, opts)
 end
 
 ---@param node Node
 ---@param opts? nvim_tree.api.node.buffer.RemoveOpts
----@return nil
 function M.wipe(node, opts)
   M.delete_buffer("wipe", node.absolute_path, opts)
 end
@@ -22,7 +20,6 @@ end
 ---@param mode ApiNodeDeleteWipeBufferMode
 ---@param filename string
 ---@param opts? nvim_tree.api.node.buffer.RemoveOpts
----@return nil
 function M.delete_buffer(mode, filename, opts)
   if type(mode) ~= "string" then
     mode = "delete"
diff --git a/lua/nvim-tree/actions/tree/find-file.lua b/lua/nvim-tree/actions/tree/find-file.lua
index 231a56a2bb2..0290ce2e17f 100644
--- a/lua/nvim-tree/actions/tree/find-file.lua
+++ b/lua/nvim-tree/actions/tree/find-file.lua
@@ -6,7 +6,7 @@ local finders_find_file = require("nvim-tree.actions.finders.find-file")
 local M = {}
 
 --- Find file or buffer
----@param opts nvim_tree.api.tree.find_file.Opts|nil|boolean legacy -> opts.buf
+---@param opts? nvim_tree.api.tree.find_file.Opts|boolean legacy -> opts.buf
 function M.fn(opts)
   -- legacy arguments
   if type(opts) == "string" then
diff --git a/lua/nvim-tree/actions/tree/modifiers/collapse.lua b/lua/nvim-tree/actions/tree/modifiers/collapse.lua
index c1c0a5b4b3b..b0611e21789 100644
--- a/lua/nvim-tree/actions/tree/modifiers/collapse.lua
+++ b/lua/nvim-tree/actions/tree/modifiers/collapse.lua
@@ -25,7 +25,7 @@ local function buf_match()
 end
 
 ---Collapse a node, root if nil
----@param node Node?
+---@param node? Node
 ---@param opts nvim_tree.api.node.collapse.Opts
 local function collapse(node, opts)
   local explorer = core.get_explorer()
@@ -60,7 +60,7 @@ local function collapse(node, opts)
 end
 
 
----@param opts nvim_tree.api.node.collapse.Opts|boolean|nil legacy -> opts.keep_buffers
+---@param opts? nvim_tree.api.node.collapse.Opts|boolean legacy -> opts.keep_buffers
 function M.all(opts)
   -- legacy arguments
   if type(opts) == "boolean" then
@@ -72,8 +72,8 @@ function M.all(opts)
   collapse(nil, opts or {})
 end
 
----@param node Node
----@param opts nvim_tree.api.node.collapse.Opts?
+---@param node? Node
+---@param opts? nvim_tree.api.node.collapse.Opts
 function M.node(node, opts)
   collapse(node, opts or {})
 end
diff --git a/lua/nvim-tree/actions/tree/modifiers/expand.lua b/lua/nvim-tree/actions/tree/modifiers/expand.lua
index c1c40f45cdb..a79900e00e0 100644
--- a/lua/nvim-tree/actions/tree/modifiers/expand.lua
+++ b/lua/nvim-tree/actions/tree/modifiers/expand.lua
@@ -124,8 +124,8 @@ local function gen_iterator(should_descend)
   end
 end
 
----@param node Node?
----@param expand_opts nvim_tree.api.node.expand.Opts?
+---@param node? Node
+---@param expand_opts? nvim_tree.api.node.expand.Opts
 local function expand_node(node, expand_opts)
   if not node then
     return
@@ -147,8 +147,8 @@ function M.all(node, expand_opts)
 end
 
 ---Expand the directory node or parent node
----@param node Node
----@param expand_opts nvim_tree.api.node.expand.Opts?
+---@param node? Node
+---@param expand_opts? nvim_tree.api.node.expand.Opts
 function M.node(node, expand_opts)
   if not node then
     return
diff --git a/lua/nvim-tree/actions/tree/open.lua b/lua/nvim-tree/actions/tree/open.lua
index 48f7d93c7f0..8c559d8cb54 100644
--- a/lua/nvim-tree/actions/tree/open.lua
+++ b/lua/nvim-tree/actions/tree/open.lua
@@ -5,7 +5,7 @@ local finders_find_file = require("nvim-tree.actions.finders.find-file")
 local M = {}
 
 ---Open the tree, focusing if already open.
----@param opts nvim_tree.api.tree.open.Opts|nil|string legacy -> opts.path
+---@param opts? nvim_tree.api.tree.open.Opts|string legacy -> opts.path
 function M.fn(opts)
   -- legacy arguments
   if type(opts) == "string" then
diff --git a/lua/nvim-tree/actions/tree/resize.lua b/lua/nvim-tree/actions/tree/resize.lua
index 77bb379ea61..7498efdfcca 100644
--- a/lua/nvim-tree/actions/tree/resize.lua
+++ b/lua/nvim-tree/actions/tree/resize.lua
@@ -3,7 +3,7 @@ local view = require("nvim-tree.view")
 local M = {}
 
 ---Resize the tree, persisting the new size.
----@param opts nvim_tree.api.tree.resize.Opts|nil
+---@param opts? nvim_tree.api.tree.resize.Opts
 function M.fn(opts)
   if opts == nil then
     -- reset to config values
diff --git a/lua/nvim-tree/actions/tree/toggle.lua b/lua/nvim-tree/actions/tree/toggle.lua
index 6fefe089593..cb9e557838a 100644
--- a/lua/nvim-tree/actions/tree/toggle.lua
+++ b/lua/nvim-tree/actions/tree/toggle.lua
@@ -5,10 +5,10 @@ local finders_find_file = require("nvim-tree.actions.finders.find-file")
 local M = {}
 
 ---Toggle the tree.
----@param opts nvim_tree.api.tree.toggle.Opts|nil|boolean legacy -> opts.find_file
----@param no_focus string|nil legacy -> opts.focus
----@param cwd boolean|nil legacy -> opts.path
----@param bang boolean|nil legacy -> opts.update_root
+---@param opts? nvim_tree.api.tree.toggle.Opts|boolean legacy -> opts.find_file
+---@param no_focus? string legacy -> opts.focus
+---@param cwd? boolean legacy -> opts.path
+---@param bang? boolean legacy -> opts.update_root
 function M.fn(opts, no_focus, cwd, bang)
   -- legacy arguments
   if type(opts) == "boolean" then
diff --git a/lua/nvim-tree/view.lua b/lua/nvim-tree/view.lua
index e1ad5d5fd70..f906cba4ba2 100644
--- a/lua/nvim-tree/view.lua
+++ b/lua/nvim-tree/view.lua
@@ -487,8 +487,8 @@ function M.focus(winnr, open_if_closed)
 end
 
 --- Retrieve the winid of the open tree.
----@param opts nvim_tree.api.tree.winid.Opts|nil
----@return number|nil winid unlike get_winnr(), this returns nil if the nvim-tree window is not visible
+---@param opts? nvim_tree.api.tree.winid.Opts
+---@return number? winid unlike get_winnr(), this returns nil if the nvim-tree window is not visible
 function M.winid(opts)
   local tabpage = opts and opts.tabpage
   if tabpage == 0 then

From 4f966c687bab4119eaf73383777093d3c80da52b Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Tue, 20 Jan 2026 15:31:12 +1100
Subject: [PATCH 110/170] docs(#3088): format nvim_tree.api.commands

---
 doc/nvim-tree-lua.txt                | 25 +++++++++++++------------
 lua/nvim-tree/_meta/api/commands.lua | 14 ++++++++------
 2 files changed, 21 insertions(+), 18 deletions(-)

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 1fcac2b742b..74b003a257a 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -203,7 +203,9 @@ See |nvim-tree-highlight-groups| for details.
 ==============================================================================
 Commands                                                  *nvim-tree-commands*
 
-Commands may be executed with a `` (`!`) or take a `` string argument.
+Commands may be executed with a `` (`!`) or take a `path` string argument.
+
+All commands execute public API.
 
 *:NvimTreeOpen*                            |nvim_tree.api.tree.open()| >lua
 
@@ -2418,20 +2420,19 @@ following are functionally identical: >lua
 ==============================================================================
 Lua module: nvim_tree.api.commands                    *nvim-tree-api-commands*
 
-*nvim_tree.api.commands.Command*
-    Arguments for |nvim_create_user_command()|
-
-    Fields: ~
-      • {name}     (`string`)
-      • {command}  (`fun(args: vim.api.keyset.create_user_command.command_args)`)
-      • {opts}     (`vim.api.keyset.user_command`)
-
-
 get()                                           *nvim_tree.api.commands.get()*
-    Retrieve all nvim-tree commands, see |nvim-tree-commands|
+    Retrieve all |nvim-tree-commands|
+
+    They have been created via |nvim_create_user_command()|, see also
+    |lua-guide-commands-create|
 
     Return: ~
-        (`nvim_tree.api.commands.Command[]`)
+        (`table[]`)
+        • {name} (`string`) name of the `:NvimTree*` command
+        • {command}
+          (`fun(args: vim.api.keyset.create_user_command.command_args)`)
+          function that the command will execute
+        • {opts} (`vim.api.keyset.user_command`) |command-attributes|
 
 
 ==============================================================================
diff --git a/lua/nvim-tree/_meta/api/commands.lua b/lua/nvim-tree/_meta/api/commands.lua
index f4073cdf69c..ea35df09b65 100644
--- a/lua/nvim-tree/_meta/api/commands.lua
+++ b/lua/nvim-tree/_meta/api/commands.lua
@@ -1,17 +1,19 @@
 ---@meta
 local nvim_tree = { api = { commands = {} } }
 
----
----Arguments for [nvim_create_user_command()]
+
 ---
 ---@class nvim_tree.api.commands.Command
+---@inlinedoc
 ---
----@field name string
----@field command fun(args: vim.api.keyset.create_user_command.command_args)
----@field opts vim.api.keyset.user_command
+---@field name string name of the `:NvimTree*` command
+---@field command fun(args: vim.api.keyset.create_user_command.command_args) function that the command will execute
+---@field opts vim.api.keyset.user_command [command-attributes]
 
 ---
----Retrieve all nvim-tree commands, see [nvim-tree-commands]
+---Retrieve all [nvim-tree-commands]
+---
+---They have been created via [nvim_create_user_command()], see also [lua-guide-commands-create]
 ---
 ---@return nvim_tree.api.commands.Command[]
 function nvim_tree.api.commands.get() end

From 0170127f4e4b175d9263ece36c29b0c0ac602e6e Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Tue, 20 Jan 2026 15:59:25 +1100
Subject: [PATCH 111/170] docs(#3088): separate api classes at the end

---
 doc/nvim-tree-lua.txt               | 161 +++++++++++++++-------------
 lua/nvim-tree/_meta/api/classes.lua |  54 ++++++++++
 lua/nvim-tree/api.lua               |  74 +++----------
 scripts/gen_vimdoc_config.lua       |  76 ++++++-------
 4 files changed, 198 insertions(+), 167 deletions(-)
 create mode 100644 lua/nvim-tree/_meta/api/classes.lua

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 74b003a257a..d1bafb7514e 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -2332,26 +2332,34 @@ Class: Config.Log                                       *nvim-tree-config-log*
 
 
 ==============================================================================
-Lua module: nvim_tree.api                                      *nvim-tree-api*
+api Overview                                                   *nvim-tree-api*
 
 nvim-tree exposes a public API. This is non breaking, with additions made as
 necessary.
 
 Please do not require or use modules other than `nvim-tree.api`, as internal
-modules are not stable and will change without notice.
+modules will change without notice.
 
-The API is separated into multiple modules, which can be accessed via the
-parent `nvim-tree.api` or via `nvim-tree.api.`. The following examples
-are equivalent: >lua
+The API is separated into multiple modules:
+• |nvim-tree-api-commands|
+• |nvim-tree-api-events|
+• |nvim-tree-api-filter|
+• |nvim-tree-api-fs|
+• |nvim-tree-api-health|
+• |nvim-tree-api-map|
+• |nvim-tree-api-marks|
+• |nvim-tree-api-node|
+• |nvim-tree-api-tree|
+
+Modules are accessed via `api..`
+
+Example invocation of the `reload` function in the `tree` module: >lua
 
     local api = require("nvim-tree.api")
     api.tree.reload()
-
-    local tree = require("nvim-tree.api.tree")
-    tree.reload()
 <
 
-Generally, functions accepting {node} as their first argument will use the
+Generally, functions accepting a {node} as their first argument will use the
 node under the cursor when that argument is not present or nil. e.g. the
 following are functionally identical: >lua
 
@@ -2361,64 +2369,9 @@ following are functionally identical: >lua
 <
 
 
-*nvim_tree.api.DirectoryLinkNode*
-    Extends: |nvim_tree.api.DirectoryNode|
-
-    DirectoryLink
-
-*nvim_tree.api.DirectoryNode*
-    Extends: |nvim_tree.api.Node|
-
-    Directory
-
-    Fields: ~
-      • {has_children}  (`boolean`)
-      • {nodes}         (`nvim_tree.api.Node[]`)
-      • {open}          (`boolean`)
-
-*nvim_tree.api.FileLinkNode*
-    Extends: |nvim_tree.api.FileNode|
-
-    File Link
-
-*nvim_tree.api.FileNode*
-    Extends: |nvim_tree.api.Node|
-
-    File
-
-    Fields: ~
-      • {extension}  (`string`)
-
-*nvim_tree.api.LinkNode*
-    Link mixin
-
-    Fields: ~
-      • {link_to}         (`string`)
-      • {fs_stat_target}  (`uv.fs_stat.result`)
-
-*nvim_tree.api.Node*
-    Base Node, Abstract
-
-    Fields: ~
-      • {type}           (`"file"|"directory"|"link"`) uv.fs_stat.result.type
-      • {absolute_path}  (`string`)
-      • {executable}     (`boolean`)
-      • {fs_stat}        (`uv.fs_stat.result?`)
-      • {git_status}     (`GitNodeStatus?`)
-      • {hidden}         (`boolean`)
-      • {name}           (`string`)
-      • {parent}         (`nvim_tree.api.DirectoryNode?`)
-      • {diag_severity}  (`lsp.DiagnosticSeverity?`)
-
-*nvim_tree.api.RootNode*
-    Extends: |nvim_tree.api.DirectoryNode|
-
-    Root Directory
-
-
 
 ==============================================================================
-Lua module: nvim_tree.api.commands                    *nvim-tree-api-commands*
+api.commands                                          *nvim-tree-api-commands*
 
 get()                                           *nvim_tree.api.commands.get()*
     Retrieve all |nvim-tree-commands|
@@ -2436,7 +2389,7 @@ get()                                           *nvim_tree.api.commands.get()*
 
 
 ==============================================================================
-Lua module: nvim_tree.api.events                        *nvim-tree-api-events*
+api.events                                              *nvim-tree-api-events*
 
 subscribe({event_type}, {callback})         *nvim_tree.api.events.subscribe()*
     Register a handler for an event, see |nvim-tree-events|.
@@ -2447,7 +2400,7 @@ subscribe({event_type}, {callback})         *nvim_tree.api.events.subscribe()*
 
 
 ==============================================================================
-Lua module: nvim_tree.api.filter                        *nvim-tree-api-filter*
+api.filter                                              *nvim-tree-api-filter*
 
 live_filter.clear()                 *nvim_tree.api.filter.live_filter.clear()*
     Exit live filter mode.
@@ -2458,7 +2411,7 @@ live_filter.start()                 *nvim_tree.api.filter.live_filter.start()*
 
 
 ==============================================================================
-Lua module: nvim_tree.api.fs                                *nvim-tree-api-fs*
+api.fs                                                      *nvim-tree-api-fs*
 
 clear_clipboard()                         *nvim_tree.api.fs.clear_clipboard()*
     Clear the nvim-tree clipboard.
@@ -2566,7 +2519,7 @@ trash({node})                                       *nvim_tree.api.fs.trash()*
 
 
 ==============================================================================
-Lua module: nvim_tree.api.health                        *nvim-tree-api-health*
+api.health                                              *nvim-tree-api-health*
 
 hi_test()                                     *nvim_tree.api.health.hi_test()*
     Open a new buffer displaying all nvim-tree highlight groups, their link
@@ -2576,7 +2529,7 @@ hi_test()                                     *nvim_tree.api.health.hi_test()*
 
 
 ==============================================================================
-Lua module: nvim_tree.api.map                              *nvim-tree-api-map*
+api.map                                                    *nvim-tree-api-map*
 
 default_on_attach({bufnr})             *nvim_tree.api.map.default_on_attach()*
     Apply all |nvim-tree-mappings-default|. Call from your |nvim_tree.Config|
@@ -2602,7 +2555,7 @@ get_keymap_default()                  *nvim_tree.api.map.get_keymap_default()*
 
 
 ==============================================================================
-Lua module: nvim_tree.api.marks                          *nvim-tree-api-marks*
+api.marks                                                *nvim-tree-api-marks*
 
 bulk.delete()                              *nvim_tree.api.marks.bulk.delete()*
     Delete all marked, prompting if |nvim_tree.Config.UI.Confirm| {remove}
@@ -2646,7 +2599,7 @@ toggle({node})                                  *nvim_tree.api.marks.toggle()*
 
 
 ==============================================================================
-Lua module: nvim_tree.api.node                            *nvim-tree-api-node*
+api.node                                                  *nvim-tree-api-node*
 
 buffer.delete({node}, {opts})             *nvim_tree.api.node.buffer.delete()*
     Deletes node's related buffer, if one exists. Executes |:bdelete| or
@@ -2978,7 +2931,7 @@ show_info_popup({node})                 *nvim_tree.api.node.show_info_popup()*
 
 
 ==============================================================================
-Lua module: nvim_tree.api.tree                            *nvim-tree-api-tree*
+api.tree                                                  *nvim-tree-api-tree*
 
 change_root({path})                         *nvim_tree.api.tree.change_root()*
     Change the tree's root to a path.
@@ -3183,4 +3136,66 @@ winid({opts})                                     *nvim_tree.api.tree.winid()*
         (`integer?`) |window-ID|, nil if tree is not visible.
 
 
+==============================================================================
+api Classes                                            *nvim-tree-api-classes*
+
+Classes shared by multiple API modules.
+
+
+*nvim_tree.api.DirectoryLinkNode*
+    Extends: |nvim_tree.api.DirectoryNode|
+
+    DirectoryLink
+
+*nvim_tree.api.DirectoryNode*
+    Extends: |nvim_tree.api.Node|
+
+    Directory
+
+    Fields: ~
+      • {has_children}  (`boolean`)
+      • {nodes}         (`nvim_tree.api.Node[]`)
+      • {open}          (`boolean`)
+
+*nvim_tree.api.FileLinkNode*
+    Extends: |nvim_tree.api.FileNode|
+
+    File Link
+
+*nvim_tree.api.FileNode*
+    Extends: |nvim_tree.api.Node|
+
+    File
+
+    Fields: ~
+      • {extension}  (`string`)
+
+*nvim_tree.api.LinkNode*
+    Link mixin
+
+    Fields: ~
+      • {link_to}         (`string`)
+      • {fs_stat_target}  (`uv.fs_stat.result`)
+
+*nvim_tree.api.Node*
+    Base Node, Abstract
+
+    Fields: ~
+      • {type}           (`"file"|"directory"|"link"`) uv.fs_stat.result.type
+      • {absolute_path}  (`string`)
+      • {executable}     (`boolean`)
+      • {fs_stat}        (`uv.fs_stat.result?`)
+      • {git_status}     (`GitNodeStatus?`)
+      • {hidden}         (`boolean`)
+      • {name}           (`string`)
+      • {parent}         (`nvim_tree.api.DirectoryNode?`)
+      • {diag_severity}  (`lsp.DiagnosticSeverity?`)
+
+*nvim_tree.api.RootNode*
+    Extends: |nvim_tree.api.DirectoryNode|
+
+    Root Directory
+
+
+
  vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:
diff --git a/lua/nvim-tree/_meta/api/classes.lua b/lua/nvim-tree/_meta/api/classes.lua
new file mode 100644
index 00000000000..79cabda504c
--- /dev/null
+++ b/lua/nvim-tree/_meta/api/classes.lua
@@ -0,0 +1,54 @@
+---@brief
+---Classes shared by multiple API modules.
+---
+
+---
+---Base Node, Abstract
+---
+---@class nvim_tree.api.Node
+---@field type "file" | "directory" | "link" uv.fs_stat.result.type
+---@field absolute_path string
+---@field executable boolean
+---@field fs_stat uv.fs_stat.result?
+---@field git_status GitNodeStatus?
+---@field hidden boolean
+---@field name string
+---@field parent nvim_tree.api.DirectoryNode?
+---@field diag_severity lsp.DiagnosticSeverity?
+
+---
+---File
+---
+---@class nvim_tree.api.FileNode: nvim_tree.api.Node
+---@field extension string
+
+---
+---Directory
+---
+---@class nvim_tree.api.DirectoryNode: nvim_tree.api.Node
+---@field has_children boolean
+---@field nodes nvim_tree.api.Node[]
+---@field open boolean
+
+---
+---Root Directory
+---
+---@class nvim_tree.api.RootNode: nvim_tree.api.DirectoryNode
+
+---
+---Link mixin
+---
+---@class nvim_tree.api.LinkNode
+---@field link_to string
+---@field fs_stat_target uv.fs_stat.result
+
+---
+---File Link
+---
+---@class nvim_tree.api.FileLinkNode: nvim_tree.api.FileNode, nvim_tree.api.LinkNode
+
+---
+---DirectoryLink
+---
+---@class nvim_tree.api.DirectoryLinkNode: nvim_tree.api.DirectoryNode, nvim_tree.api.LinkNode
+
diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index 37b27307d94..b5d29fc1833 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -1,19 +1,29 @@
 ---@brief
 ---nvim-tree exposes a public API. This is non breaking, with additions made as necessary.
 ---
----Please do not require or use modules other than `nvim-tree.api`, as internal modules are not stable and will change without notice.
+---Please do not require or use modules other than `nvim-tree.api`, as internal modules will change without notice.
 ---
----The API is separated into multiple modules, which can be accessed via the parent `nvim-tree.api` or via `nvim-tree.api.`. The following examples are equivalent:
+---The API is separated into multiple modules:
+---
+---- [nvim-tree-api-commands]
+---- [nvim-tree-api-events]
+---- [nvim-tree-api-filter]
+---- [nvim-tree-api-fs]
+---- [nvim-tree-api-health]
+---- [nvim-tree-api-map]
+---- [nvim-tree-api-marks]
+---- [nvim-tree-api-node]
+---- [nvim-tree-api-tree]
+---
+---Modules are accessed via `api..`
+---
+---Example invocation of the `reload` function in the `tree` module:
 ---```lua
 ---
 ---local api = require("nvim-tree.api")
 ---api.tree.reload()
----
----local tree = require("nvim-tree.api.tree")
----tree.reload()
 ---```
----
----Generally, functions accepting {node} as their first argument will use the node under the cursor when that argument is not present or nil. e.g. the following are functionally identical:
+---Generally, functions accepting a {node} as their first argument will use the node under the cursor when that argument is not present or nil. e.g. the following are functionally identical:
 ---```lua
 ---
 ---api.node.open.edit(nil, { focus = true })
@@ -21,56 +31,6 @@
 ---api.node.open.edit(api.tree.get_node_under_cursor(), { focus = true })
 ---```
 
----
----Base Node, Abstract
----
----@class nvim_tree.api.Node
----@field type "file" | "directory" | "link" uv.fs_stat.result.type
----@field absolute_path string
----@field executable boolean
----@field fs_stat uv.fs_stat.result?
----@field git_status GitNodeStatus?
----@field hidden boolean
----@field name string
----@field parent nvim_tree.api.DirectoryNode?
----@field diag_severity lsp.DiagnosticSeverity?
-
----
----File
----
----@class nvim_tree.api.FileNode: nvim_tree.api.Node
----@field extension string
-
----
----Directory
----
----@class nvim_tree.api.DirectoryNode: nvim_tree.api.Node
----@field has_children boolean
----@field nodes nvim_tree.api.Node[]
----@field open boolean
-
----
----Root Directory
----
----@class nvim_tree.api.RootNode: nvim_tree.api.DirectoryNode
-
----
----Link mixin
----
----@class nvim_tree.api.LinkNode
----@field link_to string
----@field fs_stat_target uv.fs_stat.result
-
----
----File Link
----
----@class nvim_tree.api.FileLinkNode: nvim_tree.api.FileNode, nvim_tree.api.LinkNode
-
----
----DirectoryLink
----
----@class nvim_tree.api.DirectoryLinkNode: nvim_tree.api.DirectoryNode, nvim_tree.api.LinkNode
-
 
 --
 --Load the (empty) meta definitions
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index 74cff8e2ddd..3716eb18fd6 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -1,6 +1,6 @@
 ---@class (exact) Module
 ---@field helptag string must be globally unique
----@field title string arbitrary
+---@field section string arbitrary
 ---@field path string relative to root
 ---@field file string? generated from path
 ---@field name string? override generated module name
@@ -8,40 +8,42 @@
 ---Generated within help files in this order
 ---@type Module[]
 local modules = {
-  { helptag = "nvim-tree-config",                     title = "Class: Config",                      path = "./lua/nvim_tree/_meta/config.lua", },
-  { helptag = "nvim-tree-config-sort",                title = "Class: Config.Sort",                 path = "./lua/nvim_tree/_meta/config/sort.lua", },
-  { helptag = "nvim-tree-config-view",                title = "Class: Config.View",                 path = "./lua/nvim_tree/_meta/config/view.lua", },
-  { helptag = "nvim-tree-config-renderer",            title = "Class: Config.Renderer",             path = "./lua/nvim_tree/_meta/config/renderer.lua", },
-  { helptag = "nvim-tree-config-hijack-directories",  title = "Class: Config.HijackDirectories",    path = "./lua/nvim_tree/_meta/config/hijack_directories.lua", },
-  { helptag = "nvim-tree-config-update-focused-file", title = "Class: Config.UpdateFocusedFile",    path = "./lua/nvim_tree/_meta/config/update_focused_file.lua", },
-  { helptag = "nvim-tree-config-system-open",         title = "Class: Config.SystemOpen",           path = "./lua/nvim_tree/_meta/config/system_open.lua", },
-  { helptag = "nvim-tree-config-git",                 title = "Class: Config.Git",                  path = "./lua/nvim_tree/_meta/config/git.lua", },
-  { helptag = "nvim-tree-config-diagnostics",         title = "Class: Config.Diagnostics",          path = "./lua/nvim_tree/_meta/config/diagnostics.lua", },
-  { helptag = "nvim-tree-config-modified",            title = "Class: Config.Modified",             path = "./lua/nvim_tree/_meta/config/modified.lua", },
-  { helptag = "nvim-tree-config-filters",             title = "Class: Config.Filters",              path = "./lua/nvim_tree/_meta/config/filters.lua", },
-  { helptag = "nvim-tree-config-live-filter",         title = "Class: Config.LiveFilter",           path = "./lua/nvim_tree/_meta/config/live_filter.lua", },
-  { helptag = "nvim-tree-config-filesystem-watchers", title = "Class: Config.FilesystemWatchers",   path = "./lua/nvim_tree/_meta/config/filesystem_watchers.lua", },
-  { helptag = "nvim-tree-config-actions",             title = "Class: Config.Actions",              path = "./lua/nvim_tree/_meta/config/actions.lua", },
-  { helptag = "nvim-tree-config-trash",               title = "Class: Config.Trash",                path = "./lua/nvim_tree/_meta/config/trash.lua", },
-  { helptag = "nvim-tree-config-tab",                 title = "Class: Config.Tab",                  path = "./lua/nvim_tree/_meta/config/tab.lua", },
-  { helptag = "nvim-tree-config-notify",              title = "Class: Config.Notify",               path = "./lua/nvim_tree/_meta/config/notify.lua", },
-  { helptag = "nvim-tree-config-bookmarks",           title = "Class: Config.Bookmarks",            path = "./lua/nvim_tree/_meta/config/bookmarks.lua", },
-  { helptag = "nvim-tree-config-help",                title = "Class: Config.Help",                 path = "./lua/nvim_tree/_meta/config/help.lua", },
-  { helptag = "nvim-tree-config-ui",                  title = "Class: Config.UI",                   path = "./lua/nvim_tree/_meta/config/ui.lua",                  name = "UI", },
-  { helptag = "nvim-tree-config-experimental",        title = "Class: Config.Experimental",         path = "./lua/nvim_tree/_meta/config/experimental.lua", },
-  { helptag = "nvim-tree-config-log",                 title = "Class: Config.Log",                  path = "./lua/nvim_tree/_meta/config/log.lua", },
-
-  { helptag = "nvim-tree-api",                        title = "Lua module: nvim_tree.api",          path = "./lua/nvim_tree/api.lua", },
-
-  { helptag = "nvim-tree-api-commands",               title = "Lua module: nvim_tree.api.commands", path = "./lua/nvim_tree/_meta/api/commands.lua", },
-  { helptag = "nvim-tree-api-events",                 title = "Lua module: nvim_tree.api.events",   path = "./lua/nvim_tree/_meta/api/events.lua", },
-  { helptag = "nvim-tree-api-filter",                 title = "Lua module: nvim_tree.api.filter",   path = "./lua/nvim_tree/_meta/api/filter.lua", },
-  { helptag = "nvim-tree-api-fs",                     title = "Lua module: nvim_tree.api.fs",       path = "./lua/nvim_tree/_meta/api/fs.lua", },
-  { helptag = "nvim-tree-api-health",                 title = "Lua module: nvim_tree.api.health",   path = "./lua/nvim_tree/_meta/api/health.lua", },
-  { helptag = "nvim-tree-api-map",                    title = "Lua module: nvim_tree.api.map",      path = "./lua/nvim_tree/_meta/api/map.lua", },
-  { helptag = "nvim-tree-api-marks",                  title = "Lua module: nvim_tree.api.marks",    path = "./lua/nvim_tree/_meta/api/marks.lua", },
-  { helptag = "nvim-tree-api-node",                   title = "Lua module: nvim_tree.api.node",     path = "./lua/nvim_tree/_meta/api/node.lua", },
-  { helptag = "nvim-tree-api-tree",                   title = "Lua module: nvim_tree.api.tree",     path = "./lua/nvim_tree/_meta/api/tree.lua", },
+  { helptag = "nvim-tree-config",                     section = "Class: Config",                    path = "./lua/nvim_tree/_meta/config.lua", },
+  { helptag = "nvim-tree-config-sort",                section = "Class: Config.Sort",               path = "./lua/nvim_tree/_meta/config/sort.lua", },
+  { helptag = "nvim-tree-config-view",                section = "Class: Config.View",               path = "./lua/nvim_tree/_meta/config/view.lua", },
+  { helptag = "nvim-tree-config-renderer",            section = "Class: Config.Renderer",           path = "./lua/nvim_tree/_meta/config/renderer.lua", },
+  { helptag = "nvim-tree-config-hijack-directories",  section = "Class: Config.HijackDirectories",  path = "./lua/nvim_tree/_meta/config/hijack_directories.lua", },
+  { helptag = "nvim-tree-config-update-focused-file", section = "Class: Config.UpdateFocusedFile",  path = "./lua/nvim_tree/_meta/config/update_focused_file.lua", },
+  { helptag = "nvim-tree-config-system-open",         section = "Class: Config.SystemOpen",         path = "./lua/nvim_tree/_meta/config/system_open.lua", },
+  { helptag = "nvim-tree-config-git",                 section = "Class: Config.Git",                path = "./lua/nvim_tree/_meta/config/git.lua", },
+  { helptag = "nvim-tree-config-diagnostics",         section = "Class: Config.Diagnostics",        path = "./lua/nvim_tree/_meta/config/diagnostics.lua", },
+  { helptag = "nvim-tree-config-modified",            section = "Class: Config.Modified",           path = "./lua/nvim_tree/_meta/config/modified.lua", },
+  { helptag = "nvim-tree-config-filters",             section = "Class: Config.Filters",            path = "./lua/nvim_tree/_meta/config/filters.lua", },
+  { helptag = "nvim-tree-config-live-filter",         section = "Class: Config.LiveFilter",         path = "./lua/nvim_tree/_meta/config/live_filter.lua", },
+  { helptag = "nvim-tree-config-filesystem-watchers", section = "Class: Config.FilesystemWatchers", path = "./lua/nvim_tree/_meta/config/filesystem_watchers.lua", },
+  { helptag = "nvim-tree-config-actions",             section = "Class: Config.Actions",            path = "./lua/nvim_tree/_meta/config/actions.lua", },
+  { helptag = "nvim-tree-config-trash",               section = "Class: Config.Trash",              path = "./lua/nvim_tree/_meta/config/trash.lua", },
+  { helptag = "nvim-tree-config-tab",                 section = "Class: Config.Tab",                path = "./lua/nvim_tree/_meta/config/tab.lua", },
+  { helptag = "nvim-tree-config-notify",              section = "Class: Config.Notify",             path = "./lua/nvim_tree/_meta/config/notify.lua", },
+  { helptag = "nvim-tree-config-bookmarks",           section = "Class: Config.Bookmarks",          path = "./lua/nvim_tree/_meta/config/bookmarks.lua", },
+  { helptag = "nvim-tree-config-help",                section = "Class: Config.Help",               path = "./lua/nvim_tree/_meta/config/help.lua", },
+  { helptag = "nvim-tree-config-ui",                  section = "Class: Config.UI",                 path = "./lua/nvim_tree/_meta/config/ui.lua",                  name = "UI", },
+  { helptag = "nvim-tree-config-experimental",        section = "Class: Config.Experimental",       path = "./lua/nvim_tree/_meta/config/experimental.lua", },
+  { helptag = "nvim-tree-config-log",                 section = "Class: Config.Log",                path = "./lua/nvim_tree/_meta/config/log.lua", },
+
+  { helptag = "nvim-tree-api",                        section = "api Overview",                     path = "./lua/nvim_tree/api.lua", },
+
+  { helptag = "nvim-tree-api-commands",               section = "api.commands",                     path = "./lua/nvim_tree/_meta/api/commands.lua", },
+  { helptag = "nvim-tree-api-events",                 section = "api.events",                       path = "./lua/nvim_tree/_meta/api/events.lua", },
+  { helptag = "nvim-tree-api-filter",                 section = "api.filter",                       path = "./lua/nvim_tree/_meta/api/filter.lua", },
+  { helptag = "nvim-tree-api-fs",                     section = "api.fs",                           path = "./lua/nvim_tree/_meta/api/fs.lua", },
+  { helptag = "nvim-tree-api-health",                 section = "api.health",                       path = "./lua/nvim_tree/_meta/api/health.lua", },
+  { helptag = "nvim-tree-api-map",                    section = "api.map",                          path = "./lua/nvim_tree/_meta/api/map.lua", },
+  { helptag = "nvim-tree-api-marks",                  section = "api.marks",                        path = "./lua/nvim_tree/_meta/api/marks.lua", },
+  { helptag = "nvim-tree-api-node",                   section = "api.node",                         path = "./lua/nvim_tree/_meta/api/node.lua", },
+  { helptag = "nvim-tree-api-tree",                   section = "api.tree",                         path = "./lua/nvim_tree/_meta/api/tree.lua", },
+
+  { helptag = "nvim-tree-api-classes",                section = "api Classes",                      path = "./lua/nvim_tree/_meta/api/classes.lua", },
 }
 
 -- hydrate file names
@@ -49,7 +51,7 @@ for _, m in ipairs(modules) do
   m.file = vim.fn.fnamemodify(m.path, ":t")
 end
 
---section name is derived by the generator as the file name with the first letter capitalised
+--name is derived by the generator as the file name with the first letter capitalised
 --except for some like UI
 ---@type table
 local modules_by_section = {}
@@ -72,7 +74,7 @@ local config = {
 
     section_fmt = function(name)
       print(string.format("section_fmt name=%s", name))
-      return modules_by_section[name] and modules_by_section[name].title or
+      return modules_by_section[name] and modules_by_section[name].section or
         error(string.format("unknown module %s passed to section_fmt", name))
     end,
 

From 002b99d0ba3da5ce8e149661fa66fe8939a3108f Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Tue, 20 Jan 2026 16:10:40 +1100
Subject: [PATCH 112/170] docs(#3088): polish vimdoc config

---
 scripts/gen_vimdoc_config.lua | 42 +++++++++++++++++------------------
 1 file changed, 21 insertions(+), 21 deletions(-)

diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index 3716eb18fd6..ae53bf2c26a 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -1,13 +1,13 @@
----@class (exact) Module
+---@class (exact) Src
 ---@field helptag string must be globally unique
 ---@field section string arbitrary
 ---@field path string relative to root
----@field file string? generated from path
----@field name string? override generated module name
+---@field file_name string? generated from path
+---@field name string? override generated name
 
----Generated within help files in this order
----@type Module[]
-local modules = {
+---Help txt is deleted from first tag down and generated content is appended.
+---@type Src[]
+local srcs = {
   { helptag = "nvim-tree-config",                     section = "Class: Config",                    path = "./lua/nvim_tree/_meta/config.lua", },
   { helptag = "nvim-tree-config-sort",                section = "Class: Config.Sort",               path = "./lua/nvim_tree/_meta/config/sort.lua", },
   { helptag = "nvim-tree-config-view",                section = "Class: Config.View",               path = "./lua/nvim_tree/_meta/config/view.lua", },
@@ -47,17 +47,17 @@ local modules = {
 }
 
 -- hydrate file names
-for _, m in ipairs(modules) do
-  m.file = vim.fn.fnamemodify(m.path, ":t")
+for _, m in ipairs(srcs) do
+  m.file_name = vim.fn.fnamemodify(m.path, ":t")
 end
 
 --name is derived by the generator as the file name with the first letter capitalised
---except for some like UI
----@type table
-local modules_by_section = {}
-for _, m in ipairs(modules) do
-  local name = m.name or m.file:gsub(".lua", ""):gsub("^%l", string.upper)
-  modules_by_section[name] = m
+--except for some like UI which are overridden in srcs
+---@type table
+local srcs_by_name = {}
+for _, m in ipairs(srcs) do
+  local name = m.name or m.file_name:gsub(".lua", ""):gsub("^%l", string.upper)
+  srcs_by_name[name] = m
 end
 
 ---@diagnostic disable-next-line: undefined-doc-name
@@ -66,22 +66,22 @@ local config = {
   all = {
     filename = "nvim-tree-lua.txt",
 
-    -- file is used to set order
-    section_order = vim.tbl_map(function(m) return m.file end, modules),
+    -- source file name is used to set order
+    section_order = vim.tbl_map(function(src) return src.file_name end, srcs),
 
     -- path
-    files = vim.tbl_map(function(m) return m.path end, modules),
+    files = vim.tbl_map(function(src) return src.path end, srcs),
 
     section_fmt = function(name)
       print(string.format("section_fmt name=%s", name))
-      return modules_by_section[name] and modules_by_section[name].section or
-        error(string.format("unknown module %s passed to section_fmt", name))
+      return srcs_by_name[name] and srcs_by_name[name].section or
+        error(string.format("unknown name %s passed to section_fmt", name))
     end,
 
     helptag_fmt = function(name)
       print(string.format("helptag_fmt name=%s", name))
-      return modules_by_section[name] and modules_by_section[name].helptag or
-        error(string.format("unknown module %s passed to helptag_fmt", name))
+      return srcs_by_name[name] and srcs_by_name[name].helptag or
+        error(string.format("unknown name %s passed to helptag_fmt", name))
     end,
 
     -- optional, no default xform

From 29fec0845a790bb1f09fb9086571779a12efdf1f Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Tue, 20 Jan 2026 16:14:01 +1100
Subject: [PATCH 113/170] docs(#3088): format

---
 lua/nvim-tree/_meta/api/classes.lua  | 2 ++
 lua/nvim-tree/_meta/api/commands.lua | 1 -
 lua/nvim-tree/_meta/api/events.lua   | 5 +----
 lua/nvim-tree/_meta/api/node.lua     | 1 -
 4 files changed, 3 insertions(+), 6 deletions(-)

diff --git a/lua/nvim-tree/_meta/api/classes.lua b/lua/nvim-tree/_meta/api/classes.lua
index 79cabda504c..ce17737349b 100644
--- a/lua/nvim-tree/_meta/api/classes.lua
+++ b/lua/nvim-tree/_meta/api/classes.lua
@@ -1,3 +1,5 @@
+---@meta
+
 ---@brief
 ---Classes shared by multiple API modules.
 ---
diff --git a/lua/nvim-tree/_meta/api/commands.lua b/lua/nvim-tree/_meta/api/commands.lua
index ea35df09b65..e2d401d5be0 100644
--- a/lua/nvim-tree/_meta/api/commands.lua
+++ b/lua/nvim-tree/_meta/api/commands.lua
@@ -1,7 +1,6 @@
 ---@meta
 local nvim_tree = { api = { commands = {} } }
 
-
 ---
 ---@class nvim_tree.api.commands.Command
 ---@inlinedoc
diff --git a/lua/nvim-tree/_meta/api/events.lua b/lua/nvim-tree/_meta/api/events.lua
index 8616fae986c..846598f6543 100644
--- a/lua/nvim-tree/_meta/api/events.lua
+++ b/lua/nvim-tree/_meta/api/events.lua
@@ -1,7 +1,4 @@
 ---@meta
-
-local events = require("nvim-tree.events")
-
 local nvim_tree = { api = { events = {} } }
 
 ---
@@ -11,6 +8,6 @@ local nvim_tree = { api = { events = {} } }
 ---@param callback fun(payload: table?)
 function nvim_tree.api.events.subscribe(event_type, callback) end
 
-nvim_tree.api.events.Event = events.Event
+nvim_tree.api.events.Event = require("nvim-tree.events").Event
 
 return nvim_tree.api.events
diff --git a/lua/nvim-tree/_meta/api/node.lua b/lua/nvim-tree/_meta/api/node.lua
index 670e82a0008..252fe74e944 100644
--- a/lua/nvim-tree/_meta/api/node.lua
+++ b/lua/nvim-tree/_meta/api/node.lua
@@ -1,7 +1,6 @@
 ---@meta
 local nvim_tree = { api = { node = { navigate = { sibling = {}, git = {}, diagnostics = {}, opened = {}, }, run = {}, open = {}, buffer = {}, } } }
 
-
 ---
 ---@class nvim_tree.api.node.open.Opts
 ---@inlinedoc

From dc536aa43e4acabfd4b7ecf3b1091743ba6cdeb1 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Tue, 20 Jan 2026 16:19:08 +1100
Subject: [PATCH 114/170] docs(#2934): polish vimdoc config

---
 scripts/gen_vimdoc_config.lua | 122 +++++++++++++++++++---------------
 1 file changed, 67 insertions(+), 55 deletions(-)

diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index e8dda6f50e1..bfdedd23213 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -1,49 +1,49 @@
----@class (exact) Module
+---@class (exact) Src
 ---@field helptag string must be globally unique
----@field title string arbitrary
+---@field section string arbitrary
 ---@field path string relative to root
----@field file string? generated from path
----@field name string? override generated module name
+---@field file_name string? generated from path
+---@field name string? override generated name
 
----Generated within help files in this order
----@type Module[]
-local modules = {
-  { helptag = "nvim-tree-config",                     title = "Class: Config",                    path = "./lua/nvim_tree/_meta/config.lua", },
-  { helptag = "nvim-tree-config-sort",                title = "Class: Config.Sort",               path = "./lua/nvim_tree/_meta/config/sort.lua", },
-  { helptag = "nvim-tree-config-view",                title = "Class: Config.View",               path = "./lua/nvim_tree/_meta/config/view.lua", },
-  { helptag = "nvim-tree-config-renderer",            title = "Class: Config.Renderer",           path = "./lua/nvim_tree/_meta/config/renderer.lua", },
-  { helptag = "nvim-tree-config-hijack-directories",  title = "Class: Config.HijackDirectories",  path = "./lua/nvim_tree/_meta/config/hijack_directories.lua", },
-  { helptag = "nvim-tree-config-update-focused-file", title = "Class: Config.UpdateFocusedFile",  path = "./lua/nvim_tree/_meta/config/update_focused_file.lua", },
-  { helptag = "nvim-tree-config-system-open",         title = "Class: Config.SystemOpen",         path = "./lua/nvim_tree/_meta/config/system_open.lua", },
-  { helptag = "nvim-tree-config-git",                 title = "Class: Config.Git",                path = "./lua/nvim_tree/_meta/config/git.lua", },
-  { helptag = "nvim-tree-config-diagnostics",         title = "Class: Config.Diagnostics",        path = "./lua/nvim_tree/_meta/config/diagnostics.lua", },
-  { helptag = "nvim-tree-config-modified",            title = "Class: Config.Modified",           path = "./lua/nvim_tree/_meta/config/modified.lua", },
-  { helptag = "nvim-tree-config-filters",             title = "Class: Config.Filters",            path = "./lua/nvim_tree/_meta/config/filters.lua", },
-  { helptag = "nvim-tree-config-live-filter",         title = "Class: Config.LiveFilter",         path = "./lua/nvim_tree/_meta/config/live_filter.lua", },
-  { helptag = "nvim-tree-config-filesystem-watchers", title = "Class: Config.FilesystemWatchers", path = "./lua/nvim_tree/_meta/config/filesystem_watchers.lua", },
-  { helptag = "nvim-tree-config-actions",             title = "Class: Config.Actions",            path = "./lua/nvim_tree/_meta/config/actions.lua", },
-  { helptag = "nvim-tree-config-trash",               title = "Class: Config.Trash",              path = "./lua/nvim_tree/_meta/config/trash.lua", },
-  { helptag = "nvim-tree-config-tab",                 title = "Class: Config.Tab",                path = "./lua/nvim_tree/_meta/config/tab.lua", },
-  { helptag = "nvim-tree-config-notify",              title = "Class: Config.Notify",             path = "./lua/nvim_tree/_meta/config/notify.lua", },
-  { helptag = "nvim-tree-config-bookmarks",           title = "Class: Config.Bookmarks",          path = "./lua/nvim_tree/_meta/config/bookmarks.lua", },
-  { helptag = "nvim-tree-config-help",                title = "Class: Config.Help",               path = "./lua/nvim_tree/_meta/config/help.lua", },
-  { helptag = "nvim-tree-config-ui",                  title = "Class: Config.UI",                 path = "./lua/nvim_tree/_meta/config/ui.lua",                  name = "UI", },
-  { helptag = "nvim-tree-config-experimental",        title = "Class: Config.Experimental",       path = "./lua/nvim_tree/_meta/config/experimental.lua", },
-  { helptag = "nvim-tree-config-log",                 title = "Class: Config.Log",                path = "./lua/nvim_tree/_meta/config/log.lua", },
+---Help txt is deleted from first tag down and generated content is appended.
+---@type Src[]
+local srcs = {
+  { helptag = "nvim-tree-config",                     section = "Class: Config",                    path = "./lua/nvim_tree/_meta/config.lua", },
+  { helptag = "nvim-tree-config-sort",                section = "Class: Config.Sort",               path = "./lua/nvim_tree/_meta/config/sort.lua", },
+  { helptag = "nvim-tree-config-view",                section = "Class: Config.View",               path = "./lua/nvim_tree/_meta/config/view.lua", },
+  { helptag = "nvim-tree-config-renderer",            section = "Class: Config.Renderer",           path = "./lua/nvim_tree/_meta/config/renderer.lua", },
+  { helptag = "nvim-tree-config-hijack-directories",  section = "Class: Config.HijackDirectories",  path = "./lua/nvim_tree/_meta/config/hijack_directories.lua", },
+  { helptag = "nvim-tree-config-update-focused-file", section = "Class: Config.UpdateFocusedFile",  path = "./lua/nvim_tree/_meta/config/update_focused_file.lua", },
+  { helptag = "nvim-tree-config-system-open",         section = "Class: Config.SystemOpen",         path = "./lua/nvim_tree/_meta/config/system_open.lua", },
+  { helptag = "nvim-tree-config-git",                 section = "Class: Config.Git",                path = "./lua/nvim_tree/_meta/config/git.lua", },
+  { helptag = "nvim-tree-config-diagnostics",         section = "Class: Config.Diagnostics",        path = "./lua/nvim_tree/_meta/config/diagnostics.lua", },
+  { helptag = "nvim-tree-config-modified",            section = "Class: Config.Modified",           path = "./lua/nvim_tree/_meta/config/modified.lua", },
+  { helptag = "nvim-tree-config-filters",             section = "Class: Config.Filters",            path = "./lua/nvim_tree/_meta/config/filters.lua", },
+  { helptag = "nvim-tree-config-live-filter",         section = "Class: Config.LiveFilter",         path = "./lua/nvim_tree/_meta/config/live_filter.lua", },
+  { helptag = "nvim-tree-config-filesystem-watchers", section = "Class: Config.FilesystemWatchers", path = "./lua/nvim_tree/_meta/config/filesystem_watchers.lua", },
+  { helptag = "nvim-tree-config-actions",             section = "Class: Config.Actions",            path = "./lua/nvim_tree/_meta/config/actions.lua", },
+  { helptag = "nvim-tree-config-trash",               section = "Class: Config.Trash",              path = "./lua/nvim_tree/_meta/config/trash.lua", },
+  { helptag = "nvim-tree-config-tab",                 section = "Class: Config.Tab",                path = "./lua/nvim_tree/_meta/config/tab.lua", },
+  { helptag = "nvim-tree-config-notify",              section = "Class: Config.Notify",             path = "./lua/nvim_tree/_meta/config/notify.lua", },
+  { helptag = "nvim-tree-config-bookmarks",           section = "Class: Config.Bookmarks",          path = "./lua/nvim_tree/_meta/config/bookmarks.lua", },
+  { helptag = "nvim-tree-config-help",                section = "Class: Config.Help",               path = "./lua/nvim_tree/_meta/config/help.lua", },
+  { helptag = "nvim-tree-config-ui",                  section = "Class: Config.UI",                 path = "./lua/nvim_tree/_meta/config/ui.lua",                  name = "UI", },
+  { helptag = "nvim-tree-config-experimental",        section = "Class: Config.Experimental",       path = "./lua/nvim_tree/_meta/config/experimental.lua", },
+  { helptag = "nvim-tree-config-log",                 section = "Class: Config.Log",                path = "./lua/nvim_tree/_meta/config/log.lua", },
 }
 
 -- hydrate file names
-for _, m in ipairs(modules) do
-  m.file = vim.fn.fnamemodify(m.path, ":t")
+for _, m in ipairs(srcs) do
+  m.file_name = vim.fn.fnamemodify(m.path, ":t")
 end
 
---module name is derived by the generator as the file name with the first letter capitalised
---except for some like UI
----@type table
-local modules_by_name = {}
-for _, m in ipairs(modules) do
-  local name = m.name or m.file:gsub(".lua", ""):gsub("^%l", string.upper)
-  modules_by_name[name] = m
+--name is derived by the generator as the file name with the first letter capitalised
+--except for some like UI which are overridden in srcs
+---@type table
+local srcs_by_name = {}
+for _, m in ipairs(srcs) do
+  local name = m.name or m.file_name:gsub(".lua", ""):gsub("^%l", string.upper)
+  srcs_by_name[name] = m
 end
 
 ---@diagnostic disable-next-line: undefined-doc-name
@@ -52,33 +52,45 @@ local config = {
   all = {
     filename = "nvim-tree-lua.txt",
 
-    -- file is used to set order
-    section_order = vim.tbl_map(function(m) return m.file end, modules),
+    -- source file name is used to set order
+    section_order = vim.tbl_map(function(src) return src.file_name end, srcs),
 
     -- path
-    files = vim.tbl_map(function(m) return m.path end, modules),
+    files = vim.tbl_map(function(src) return src.path end, srcs),
 
     section_fmt = function(name)
-      return modules_by_name[name] and modules_by_name[name].title or error(string.format("unknown module %s passed to section_fmt", name))
+      print(string.format("section_fmt name=%s", name))
+      return srcs_by_name[name] and srcs_by_name[name].section or
+        error(string.format("unknown name %s passed to section_fmt", name))
     end,
 
     helptag_fmt = function(name)
-      return modules_by_name[name] and modules_by_name[name].helptag or error(string.format("unknown module %s passed to helptag_fmt", name))
+      print(string.format("helptag_fmt name=%s", name))
+      return srcs_by_name[name] and srcs_by_name[name].helptag or
+        error(string.format("unknown name %s passed to helptag_fmt", name))
     end,
 
-    -- class/function's help tag
-    fn_helptag_fmt = function(fun)
-      -- Modified copy of fn_helptag_fmt_common
-      -- Uses fully qualified class name in the tag for methods.
-      -- The module is used everywhere else, however not available for classes.
-      local fn_sfx = fun.table and "" or "()"
-      if fun.classvar then
-        return string.format("%s:%s%s", fun.class or fun.classvar, fun.name, fn_sfx)
-      end
-      if fun.module then
-        return string.format("%s.%s%s", fun.module, fun.name, fn_sfx)
+    -- optional, no default xform
+    fn_xform = function(fun)
+      print(string.format("fn_xform fun=%s", vim.inspect(fun)))
+
+      if (fun.module) then
+        -- generator doesn't strip meta
+        -- also cascades into fn_helptag_fmt
+        local module = fun.module:gsub("._meta", "", 1)
+
+        -- remove the API prefix from the left aligned function name
+        -- this will cascade into fn_helptag_fmt, which will apply the module prefix anyway
+        local name, replaced = fun.name:gsub("^" .. module .. "%.", "", 1)
+        if (replaced ~= 1) then
+          error(string.format("function name does not start with module: %s", vim.inspect(fun)))
+        end
+
+        print(string.format("fn_xform name: %s -> %s", fun.name, name))
+
+        fun.module = module
+        fun.name = name
       end
-      return fun.name .. fn_sfx
     end,
   }
 }

From c51db1dd3ca57e801e484fb8458b702e358251e1 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Tue, 20 Jan 2026 17:12:30 +1100
Subject: [PATCH 115/170] docs(#2934): snake case config class names

---
 doc/nvim-tree-lua.txt                         | 472 +++++++++---------
 lua/nvim-tree.lua                             |   6 +-
 lua/nvim-tree/_meta/config.lua                |  92 ++--
 lua/nvim-tree/_meta/config/actions.lua        |  44 +-
 lua/nvim-tree/_meta/config/bookmarks.lua      |   2 +-
 lua/nvim-tree/_meta/config/diagnostics.lua    |  14 +-
 lua/nvim-tree/_meta/config/experimental.lua   |   2 +-
 .../_meta/config/filesystem_watchers.lua      |   2 +-
 lua/nvim-tree/_meta/config/filters.lua        |   4 +-
 lua/nvim-tree/_meta/config/git.lua            |   2 +-
 lua/nvim-tree/_meta/config/help.lua           |  10 +-
 .../_meta/config/hijack_directories.lua       |   4 +-
 lua/nvim-tree/_meta/config/live_filter.lua    |   2 +-
 lua/nvim-tree/_meta/config/log.lua            |  10 +-
 lua/nvim-tree/_meta/config/modified.lua       |   6 +-
 lua/nvim-tree/_meta/config/notify.lua         |   2 +-
 lua/nvim-tree/_meta/config/renderer.lua       | 104 ++--
 lua/nvim-tree/_meta/config/sort.lua           |  12 +-
 lua/nvim-tree/_meta/config/system_open.lua    |   2 +-
 lua/nvim-tree/_meta/config/tab.lua            |   8 +-
 lua/nvim-tree/_meta/config/trash.lua          |   2 +-
 lua/nvim-tree/_meta/config/ui.lua             |   8 +-
 .../_meta/config/update_focused_file.lua      |  12 +-
 lua/nvim-tree/_meta/config/view.lua           |  26 +-
 24 files changed, 424 insertions(+), 424 deletions(-)

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index b055e7dabac..95d9de42f20 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -24,7 +24,7 @@ File Icons
 
      should look like an open folder.
 
-    Disable the display of icons with |nvim_tree.Config.Renderer.Icons.Show|
+    Disable the display of icons with |nvim_tree.config.renderer.icons.show|
 
 Colours
 
@@ -59,7 +59,7 @@ Disabling |netrw| is strongly advised, see |nvim-tree-netrw|
 ==============================================================================
 Quickstart: Setup                                 *nvim-tree-quickstart-setup*
 
-Setup the plugin in your `init.lua`, passing |nvim_tree.Config|
+Setup the plugin in your `init.lua`, passing |nvim_tree.config|
 e.g. >lua
 
   -- disable netrw at the very start of your init.lua
@@ -159,7 +159,7 @@ Show the mappings:  `g?`
 Quickstart: Custom Mappings             *nvim-tree-quickstart-custom-mappings*
 
 |nvim-tree-mappings-default| are applied by default however you may customise
-via |nvim_tree.Config| {on_attach} e.g. >lua
+via |nvim_tree.config| {on_attach} e.g. >lua
 
   local function my_on_attach(bufnr)
     local api = require "nvim-tree.api"
@@ -317,7 +317,7 @@ the configuration. Nothing happens until the tree is first opened.
 Subsequent setup() calls are expensive as they tear down the world before
 applying configuration.
 
-Following is the default configuration. See |nvim_tree.Config| for details. >lua
+Following is the default configuration. See |nvim_tree.config| for details. >lua
 
     require("nvim-tree").setup { -- BEGIN_DEFAULT_OPTS
       on_attach = "default",
@@ -635,7 +635,7 @@ tree.open({opts})                                  *nvim-tree-api.tree.open()*
                                    overrides {current_window}
       • {find_file}      (boolean) find the current buffer
       • {update_root}    (boolean) requires {find_file}, see
-                                   |nvim_tree.Config.UpdateFocusedFile| {update_root}
+                                   |nvim_tree.config.update_focused_file| {update_root}
 
 tree.toggle({opts})                              *nvim-tree-api.tree.toggle()*
     Open or close the tree.
@@ -650,11 +650,11 @@ tree.toggle({opts})                              *nvim-tree-api.tree.toggle()*
                                    overrides {current_window}
       • {find_file}      (boolean) find the current buffer
       • {update_root}    (boolean) requires {find_file}, see
-                                   |nvim_tree.Config.UpdateFocusedFile| {update_root}
+                                   |nvim_tree.config.update_focused_file| {update_root}
       • {focus}          (boolean) focus the tree when opening, default true
 
 tree.close()                                      *nvim-tree-api.tree.close()*
-    Close the tree, affecting all tabs as per |nvim_tree.Config.Tab.Sync| {close}
+    Close the tree, affecting all tabs as per |nvim_tree.config.tab.sync| {close}
 
 tree.close_in_this_tab()              *nvim-tree-api.tree.close_in_this_tab()*
     Close the tree in this tab only.
@@ -671,14 +671,14 @@ tree.reload()                                    *nvim-tree-api.tree.reload()*
 
 tree.resize({opts})                              *nvim-tree-api.tree.resize()*
     Resize the tree, persisting the new size.
-    Resets to |nvim_tree.Config.View| {width} when no {opts} provided.
+    Resets to |nvim_tree.config.view| {width} when no {opts} provided.
     See |:NvimTreeResize|
 
     Parameters: ~
       • {opts} (table) optional parameters
 
     Options: ~
-      • {width}    (table)  new |nvim_tree.Config.View| {width} value
+      • {width}    (table)  new |nvim_tree.config.view| {width} value
       • {absolute} (number) set the width
       • {relative} (number) increase or decrease the width
 
@@ -731,7 +731,7 @@ tree.find_file({opts})                        *nvim-tree-api.tree.find_file()*
       • {current_window} (boolean)        requires {open}, open in the current window
       • {winid}          (number)         open the tree in the specified |winid|,
                                           overrides {current_window}
-      • {update_root}    (boolean)        see |nvim_tree.Config.UpdateFocusedFile| {update_root}
+      • {update_root}    (boolean)        see |nvim_tree.config.update_focused_file| {update_root}
       • {focus}          (boolean)        focus the tree
 
 tree.search_node()                          *nvim-tree-api.tree.search_node()*
@@ -760,31 +760,31 @@ tree.expand_all({node}, {opts})              *nvim-tree-api.tree.expand_all()*
 
                                   *nvim-tree-api.tree.toggle_enable_filters()*
 tree.toggle_enable_filters()
-    Toggle |nvim_tree.Config.Filters| {enable} all filters.
+    Toggle |nvim_tree.config.filters| {enable} all filters.
 
                                 *nvim-tree-api.tree.toggle_gitignore_filter()*
 tree.toggle_gitignore_filter()
-    Toggle |nvim_tree.Config.Filters| {git_ignored} filter.
+    Toggle |nvim_tree.config.filters| {git_ignored} filter.
 
                                 *nvim-tree-api.tree.toggle_git_clean_filter()*
 tree.toggle_git_clean_filter()
-    Toggle |nvim_tree.Config.Filters| {git_clean} filter.
+    Toggle |nvim_tree.config.filters| {git_clean} filter.
 
                                 *nvim-tree-api.tree.toggle_no_buffer_filter()*
 tree.toggle_no_buffer_filter()
-    Toggle |nvim_tree.Config.Filters| {no_buffer} filter.
+    Toggle |nvim_tree.config.filters| {no_buffer} filter.
 
                               *nvim-tree-api.tree.toggle_no_bookmark_filter()*
 tree.toggle_no_bookmark_filter()
-    Toggle |nvim_tree.Config.Filters| {no_bookmark} filter.
+    Toggle |nvim_tree.config.filters| {no_bookmark} filter.
 
                                    *nvim-tree-api.tree.toggle_custom_filter()*
 tree.toggle_custom_filter()
-    Toggle |nvim_tree.Config.Filters| {custom} filter.
+    Toggle |nvim_tree.config.filters| {custom} filter.
 
                                    *nvim-tree-api.tree.toggle_hidden_filter()*
 tree.toggle_hidden_filter()
-    Toggle |nvim_tree.Config.Filters| {dotfiles} filter.
+    Toggle |nvim_tree.config.filters| {dotfiles} filter.
 
 tree.toggle_help()                          *nvim-tree-api.tree.toggle_help()*
     Toggle help view.
@@ -840,7 +840,7 @@ fs.remove({node})                                  *nvim-tree-api.fs.remove()*
       • {node} (Node|nil) file or folder
 
 fs.trash({node})                                    *nvim-tree-api.fs.trash()*
-    Trash a file or folder as per |nvim_tree.Config.Trash|
+    Trash a file or folder as per |nvim_tree.config.trash|
 
     Parameters: ~
       • {node} (Node|nil) file or folder
@@ -929,7 +929,7 @@ fs.print_clipboard()                      *nvim-tree-api.fs.print_clipboard()*
 API: Node                                                 *nvim-tree-api.node*
 
 node.open.edit({node}, {opts})                *nvim-tree-api.node.open.edit()*
-    File:   open as per |nvim_tree.Config.Actions.OpenFile|
+    File:   open as per |nvim_tree.config.actions.open_file|
     Folder: expand or collapse
     Root:   change directory up
 
@@ -1006,9 +1006,9 @@ node.open.horizontal_no_picker({node}, {opts})
 
                                 *nvim-tree-api.node.open.toggle_group_empty()*
 node.open.toggle_group_empty({node}, {opts})
-    Toggle |nvim_tree.Config.Renderer| {group_empty} for a specific folder.
+    Toggle |nvim_tree.config.renderer| {group_empty} for a specific folder.
     Does nothing on files.
-    Needs |nvim_tree.Config.Renderer| {group_empty} set.
+    Needs |nvim_tree.config.renderer| {group_empty} set.
 
     Parameters: ~
       • {node} (Node|nil) file or folder
@@ -1078,7 +1078,7 @@ node.navigate.git.next({node})        *nvim-tree-api.node.navigate.git.next()*
 node.navigate.git.next_recursive({node})
     Alternative to |nvim-tree-api.node.navigate.git.next()| that navigates to
     the next file showing git status, recursively.
-    Needs |nvim_tree.Config.Git| {show_on_dirs} set.
+    Needs |nvim_tree.config.git| {show_on_dirs} set.
 
                       *nvim-tree-api.node.navigate.git.next_skip_gitignored()*
 node.navigate.git.next_skip_gitignored({node})
@@ -1091,7 +1091,7 @@ node.navigate.git.prev({node})        *nvim-tree-api.node.navigate.git.prev()*
 node.navigate.git.prev_recursive({node})
     Alternative to |nvim-tree-api.node.navigate.git.prev()| that navigates to
     the previous file showing git status, recursively.
-    Needs |nvim_tree.Config.Git| {show_on_dirs} set.
+    Needs |nvim_tree.config.git| {show_on_dirs} set.
 
                       *nvim-tree-api.node.navigate.git.prev_skip_gitignored()*
 node.navigate.git.prev_skip_gitignored({node})
@@ -1105,7 +1105,7 @@ node.navigate.diagnostics.next({node})
 node.navigate.diagnostics.next_recursive({node})
     Alternative to |nvim-tree-api.node.navigate.diagnostics.next()| that
     navigates to the next file showing diagnostic status, recursively.
-    Needs |nvim_tree.Config.Diagnostics| {show_on_dirs} set.
+    Needs |nvim_tree.config.diagnostics| {show_on_dirs} set.
 
                               *nvim-tree-api.node.navigate.diagnostics.prev()*
 node.navigate.diagnostics.prev({node})
@@ -1115,17 +1115,17 @@ node.navigate.diagnostics.prev({node})
 node.navigate.diagnostics.prev_recursive({node})
     Alternative to |nvim-tree-api.node.navigate.diagnostics.prev()| that
     navigates to the previous file showing diagnostic status, recursively.
-    Needs |nvim_tree.Config.Diagnostics| {show_on_dirs} set.
+    Needs |nvim_tree.config.diagnostics| {show_on_dirs} set.
 
                                    *nvim-tree-api.node.navigate.opened.next()*
 node.navigate.opened.next({node})
     Navigate to the next |bufloaded()| item.
-    See |nvim_tree.Config.Renderer| {highlight_opened_files}
+    See |nvim_tree.config.renderer| {highlight_opened_files}
 
                                    *nvim-tree-api.node.navigate.opened.prev()*
 node.navigate.opened.prev({node})
     Navigate to the previous |bufloaded()| item.
-    See |nvim_tree.Config.Renderer| {highlight_opened_files}
+    See |nvim_tree.config.renderer| {highlight_opened_files}
 
                                   *nvim-tree-api.node.navigate.sibling.next()*
 node.navigate.sibling.next({node})
@@ -1159,7 +1159,7 @@ node.run.cmd({node})                            *nvim-tree-api.node.run.cmd()*
     of the line.
 
 node.run.system({node})                      *nvim-tree-api.node.run.system()*
-    Execute |nvim_tree.Config.SystemOpen|
+    Execute |nvim_tree.config.system_open|
 
 node.buffer.delete({node}, {opts})        *nvim-tree-api.node.buffer.delete()*
     Deletes node's related buffer, if one exists.
@@ -1272,8 +1272,8 @@ marks.bulk.move()                            *nvim-tree-api.marks.bulk.move()*
 
 marks.navigate.next()                    *nvim-tree-api.marks.navigate.next()*
     Navigate to the next marked node, wraps.
-    Opens files as per |nvim_tree.Config.Actions.OpenFile|
-    Works best with |nvim_tree.Config.UpdateFocusedFile| enabled.
+    Opens files as per |nvim_tree.config.actions.open_file|
+    Works best with |nvim_tree.config.update_focused_file| enabled.
 
 marks.navigate.prev()                    *nvim-tree-api.marks.navigate.prev()*
     As per |nvim-tree-api.marks.navigate.next()|
@@ -1287,15 +1287,15 @@ API: Config                                             *nvim-tree-api.config*
 
                            *nvim-tree-api.config.mappings.default_on_attach()*
 config.mappings.default_on_attach({bufnr})
-    Set all |nvim-tree-mappings-default|. Call from your |nvim_tree.Config| {on_attach}
+    Set all |nvim-tree-mappings-default|. Call from your |nvim_tree.config| {on_attach}
 
     Parameters: ~
-      • {bufnr} (number) nvim-tree buffer number passed to |nvim_tree.Config| {on_attach}
+      • {bufnr} (number) nvim-tree buffer number passed to |nvim_tree.config| {on_attach}
 
                                   *nvim-tree-api.config.mappings.get_keymap()*
 config.mappings.get_keymap()
     Retrieves all buffer local mappings for nvim-tree.
-    These are the mappings that are applied by |nvim_tree.Config| {on_attach}, which
+    These are the mappings that are applied by |nvim_tree.config| {on_attach}, which
     may include default mappings.
 
     Return: ~
@@ -1333,7 +1333,7 @@ diagnostics.hi_test()                    *nvim-tree-api.diagnostics.hi_test()*
 ==============================================================================
 Mappings                                                  *nvim-tree-mappings*
 
-Mappings are set via the |nvim_tree.Config| {on_attach} function, which is run upon
+Mappings are set via the |nvim_tree.config| {on_attach} function, which is run upon
 creating the nvim-tree buffer. Mappings are usually |nvim-tree-api| functions
 however may be your own.
 
@@ -1395,7 +1395,7 @@ define your own function to map complex functionality e.g. >lua
 ==============================================================================
 Mappings: Default                                 *nvim-tree-mappings-default*
 
-In the absence of an |nvim_tree.Config| {on_attach} function, the following
+In the absence of an |nvim_tree.config| {on_attach} function, the following
 defaults will be applied.
 
 You are encouraged to copy these to your {on_attach} function. >lua
@@ -1468,7 +1468,7 @@ You are encouraged to copy these to your {on_attach} function. >lua
   vim.keymap.set("n", "<2-RightMouse>", api.tree.change_root_to_node,       opts("CD"))
   -- END_DEFAULT_ON_ATTACH
 <
-Alternatively, you may apply these default mappings from your |nvim_tree.Config| {on_attach} via
+Alternatively, you may apply these default mappings from your |nvim_tree.config| {on_attach} via
 |nvim-tree-api.config.mappings.default_on_attach()| e.g. >lua
 
   local function my_on_attach(bufnr)
@@ -1494,25 +1494,25 @@ for files and and directories.
 
 Highlighting is additive, with higher precedence overriding lower.
 
-|nvim_tree.Config.Renderer| {decorators} controls which highlighting is
+|nvim_tree.config.renderer| {decorators} controls which highlighting is
 applied and its precedence. See |nvim-tree-decorators| for information on
 creating custom decorators.
 <
 `ICON`
-  Enable via |nvim_tree.Config.Renderer.Icons.Show
+  Enable via |nvim_tree.config.renderer.icons.show
 
 `REQUIRES`
   Feature must be enabled to show icons and highlighting.
 
-`PLACEMENT`                          *nvim_tree.Config.Renderer.Icons.Placement*
-  Where to place the icon: |nvim_tree.Config.Renderer.Icons| {_placement}
+`PLACEMENT`                          *nvim_tree.config.renderer.icons.Placement*
+  Where to place the icon: |nvim_tree.config.renderer.icons| {_placement}
   • `before`: before file/folder, after the file/folders icons
   • `after`: after file/folder
-  • `signcolumn`: far left, requires |nvim_tree.Config.View| {signcolumn}.
+  • `signcolumn`: far left, requires |nvim_tree.config.view| {signcolumn}.
   • `right_align`: far right
 
-`HIGHLIGHT`                                *nvim_tree.Config.Renderer.Highlight*
-  What should be highlighted: |nvim_tree.Config.Renderer| {highlight_}
+`HIGHLIGHT`                                *nvim_tree.config.renderer.Highlight*
+  What should be highlighted: |nvim_tree.config.renderer| {highlight_}
   • `none`: no highlighting
   • `icon`: icon only
   • `name`: name only
@@ -1520,7 +1520,7 @@ creating custom decorators.
 
 `DEVICONS`
   Glyphs and their colors will be overridden by optional plugin:
-  `nvim-tree/nvim-web-devicons` |nvim_tree.Config.Renderer.Icons.WebDevicons|
+  `nvim-tree/nvim-web-devicons` |nvim_tree.config.renderer.icons.web_devicons|
 
 `GLYPHS`
   Icon glyphs definitions.
@@ -1531,14 +1531,14 @@ creating custom decorators.
 Some defaults noted. In ascending order of default highlight precedence:
 
 `WHAT          ICON             REQUIRES                      PLACEMENT                             HIGHLIGHT                        GLYPHS                                              DEVICONS   GROUPS`
-File Icon     {file}       Y    -                             -                                     -                               |nvim_tree.Config.Renderer.Icons.Glyphs| {default}    Y          `NvimTreeNormal`, `NvimTreeFileIcon`
-Folder Icon   {folder}     Y    -                             -                                     -                               |nvim_tree.Config.Renderer.Icons.Glyphs.Folder|       Y          `NvimTree*FolderName`, `NvimTree*FolderIcon`
-Git Status    {git}        Y   |nvim_tree.Config.Git|          {git_placement}        `"before"`       {highlight_git}         `"none"`   |nvim_tree.Config.Renderer.Icons.Glyphs.Git|          N          `NvimTreeGit*`
+File Icon     {file}       Y    -                             -                                     -                               |nvim_tree.config.renderer.icons.glyphs| {default}    Y          `NvimTreeNormal`, `NvimTreeFileIcon`
+Folder Icon   {folder}     Y    -                             -                                     -                               |nvim_tree.config.renderer.icons.glyphs.folder|       Y          `NvimTree*FolderName`, `NvimTree*FolderIcon`
+Git Status    {git}        Y   |nvim_tree.config.git|          {git_placement}        `"before"`       {highlight_git}         `"none"`   |nvim_tree.config.renderer.icons.glyphs.git|          N          `NvimTreeGit*`
 |bufloaded()|    -                -                             -                                    {highlight_opened_files}`"none"`    -                                                  N         ` NvimTreeOpened*`
-Dotfiles      {hidden}     N    -                            {hidden_placement}     `"after"`        {highlight_hidden}      `"none"`   |nvim_tree.Config.Renderer.Icons.Glyphs| {hidden}     N          `NvimTreeHidden*`
-|'modified'|    {modified}   Y   |nvim_tree.Config.Modified|     {modified_placement}   `"after"`        {highlight_modified}    `"none"`   |nvim_tree.Config.Renderer.Icons.Glyphs| {modified}   N          `NvimTreeModified*`
-Bookmarked    {bookmarks}  Y    -                            {bookmarks_placement}  `"signcolumn"`   {highlight_bookmarks}   `"none"`   |nvim_tree.Config.Renderer.Icons.Glyphs| {bookmark}   N          `NvimTreeBookmark*`
-Diag Status   {diagnostics}Y   |nvim_tree.Config.Diagnostics|  {diagnostics_placement}`"signcolumn"`   {highlight_diagnostics} `"none" `  |nvim_tree.Config.Diagnostics.Icons|                  N          `NvimTreeDiagnostic*`
+Dotfiles      {hidden}     N    -                            {hidden_placement}     `"after"`        {highlight_hidden}      `"none"`   |nvim_tree.config.renderer.icons.glyphs| {hidden}     N          `NvimTreeHidden*`
+|'modified'|    {modified}   Y   |nvim_tree.config.modified|     {modified_placement}   `"after"`        {highlight_modified}    `"none"`   |nvim_tree.config.renderer.icons.glyphs| {modified}   N          `NvimTreeModified*`
+Bookmarked    {bookmarks}  Y    -                            {bookmarks_placement}  `"signcolumn"`   {highlight_bookmarks}   `"none"`   |nvim_tree.config.renderer.icons.glyphs| {bookmark}   N          `NvimTreeBookmark*`
+Diag Status   {diagnostics}Y   |nvim_tree.config.diagnostics|  {diagnostics_placement}`"signcolumn"`   {highlight_diagnostics} `"none" `  |nvim_tree.config.diagnostics.icons|                  N          `NvimTreeDiagnostic*`
 Cut/Copied     -                -                             -                                    {highlight_clipboard}   `"name"`    -                                                  N          `NvimTreeCutHL`, `NvimTreeCopiedHL`
 
 
@@ -1560,7 +1560,7 @@ To view the nvim-tree highlight groups run |:NvimTreeHiTest|
 To view all active highlight groups run `:so $VIMRUNTIME/syntax/hitest.vim`
 as per |:highlight|
 
-The `*HL` groups are additive as per |nvim_tree.Config.Renderer| precedence.
+The `*HL` groups are additive as per |nvim_tree.config.renderer| precedence.
 Only present attributes will clobber each other.
 In this example a modified, opened file will have magenta text, with cyan
 undercurl: >vim
@@ -1790,7 +1790,7 @@ e.g. handler for node renamed: >lua
 
 - Event.TreeAttachedPost
                 Invoked after the tree's buffer has been created and mappings
-                have been applied: |nvim-tree-mappings| or |nvim_tree.Config| {on_attach}
+                have been applied: |nvim-tree-mappings| or |nvim_tree.config| {on_attach}
                 handler parameters: ~
                   {buf}          `{number} `API buffer handle (buffer number)
 
@@ -1826,7 +1826,7 @@ Example subscription: >lua
 Prompts                                                    *nvim-tree-prompts*
 
 Some NvimTree actions use the builtin |vim.ui.select()| prompt API for
-confirmations when the |nvim_tree.Config| {select_prompts} option is set.
+confirmations when the |nvim_tree.config| {select_prompts} option is set.
 
 The API accepts the optional `kind` key as part of the {opts} parameter, which
 can can be used to identify the type of prompt, to allow user side
@@ -1859,7 +1859,7 @@ Decorators may:
 - Override node icon
 
 Create a `nvim_tree.api.decorator.UserDecorator` class and register it with
-precedence via |nvim_tree.Config.Renderer| {decorators}
+precedence via |nvim_tree.config.renderer| {decorators}
 
 See |nvim-tree-decorator-example|
 
@@ -1985,8 +1985,8 @@ must be disabled manually at the start of your `init.lua` as per |netrw-noload|:
 There are many |netrw| features beyond the file browser. If you want to
 keep using |netrw| without its browser features please ensure:
 
-|nvim_tree.Config| {disable_netrw}` = false`
-|nvim_tree.Config| {hijack_netrw}`  = true`
+|nvim_tree.config| {disable_netrw}` = false`
+|nvim_tree.config| {hijack_netrw}`  = true`
 
 ==============================================================================
 Legacy                                                      *nvim-tree-legacy*
@@ -2001,18 +2001,18 @@ Legacy: Config                                         *nvim-tree-legacy-opts*
 Legacy config is translated to the current, making type and value changes as
 needed.
 
-`update_cwd`                         |nvim_tree.Config| {sync_root_with_cwd}
-`update_focused_file.update_cwd`     |nvim_tree.Config.UpdateFocusedFile| {update_root}
-`open_on_tab`                        |nvim_tree.Config.Tab.Sync| {open}
-`ignore_buf_on_tab_change`           |nvim_tree.Config.Tab.Sync| {ignore}
-`renderer.root_folder_modifier`      |nvim_tree.Config.Renderer| {root_folder_label}
-`update_focused_file.debounce_delay` |nvim_tree.Config.View| {debounce_delay}
-`trash.require_confirm`              |nvim_tree.Config.UI.Confirm| {trash}
-`view.adaptive_size`                 |nvim_tree.Config.View| {width}
-`sort_by`                            |nvim_tree.Config.Sort| {sorter}
-`git.ignore`                         |nvim_tree.Config.Filters| {git_ignored}
-`renderer.icons.webdev_colors`       |nvim_tree.Config.Renderer.Icons.WebDevicons.File| {color}
-`renderer.icons.padding`             |nvim_tree.Config.Renderer.Icons.Padding| {icon}
+`update_cwd`                         |nvim_tree.config| {sync_root_with_cwd}
+`update_focused_file.update_cwd`     |nvim_tree.config.update_focused_file| {update_root}
+`open_on_tab`                        |nvim_tree.config.tab.sync| {open}
+`ignore_buf_on_tab_change`           |nvim_tree.config.tab.sync| {ignore}
+`renderer.root_folder_modifier`      |nvim_tree.config.renderer| {root_folder_label}
+`update_focused_file.debounce_delay` |nvim_tree.config.view| {debounce_delay}
+`trash.require_confirm`              |nvim_tree.config.ui.confirm| {trash}
+`view.adaptive_size`                 |nvim_tree.config.view| {width}
+`sort_by`                            |nvim_tree.config.sort| {sorter}
+`git.ignore`                         |nvim_tree.config.filters| {git_ignored}
+`renderer.icons.webdev_colors`       |nvim_tree.config.renderer.icons.web_devicons.file| {color}
+`renderer.icons.padding`             |nvim_tree.config.renderer.icons.padding| {icon}
 
 ==============================================================================
 Legacy: Highlight                                 *nvim-tree-legacy-highlight*
@@ -2069,9 +2069,9 @@ Hidden Display                                      *nvim-tree-hidden-display*
 
 Show a summary of hidden files below the tree highlighted with `NvimTreeHiddenDisplay
 
-Configure via |nvim_tree.Config.Renderer| {hidden_display}
+Configure via |nvim_tree.config.renderer| {hidden_display}
 
-                                     *nvim_tree.Config.Renderer.HiddenDisplay*
+                                     *nvim_tree.config.renderer.HiddenDisplay*
  • `none`: disabled
  • `simple`: show how many hidden files are in a folder
  • `all`: show how many hidden and the number of hidden files by reason
@@ -2112,7 +2112,7 @@ Example of function that can be passed: >lua
 ==============================================================================
 Class: Config                                               *nvim-tree-config*
 
-*nvim_tree.Config*
+*nvim_tree.config*
     Arguments to pass to |nvim-tree-setup|.
 
     When a value is not present/nil, the default will be used.
@@ -2124,7 +2124,7 @@ Class: Config                                               *nvim-tree-config*
 <
 
     or as a typed variable e.g. >lua
-         ---@type nvim_tree.Config
+         ---@type nvim_tree.config
          local config = {
            hijack_cursor = true,
          }
@@ -2151,11 +2151,11 @@ Class: Config                                               *nvim-tree-config*
     if it's empty.
 
     {root_dirs} preferred root directories, requires
-    |nvim_tree.Config.UpdateFocusedFile.UpdateRoot|.
+    |nvim_tree.config.update_focused_file.update_root|.
 
     {prefer_startup_root} prefer startup root directory when updating root
     directory of the tree. Requires
-    |nvim_tree.Config.UpdateFocusedFile.UpdateRoot|.
+    |nvim_tree.config.update_focused_file.update_root|.
 
     {sync_root_with_cwd} changes the tree root directory on |DirChanged| and
     refreshes the tree.
@@ -2184,58 +2184,58 @@ Class: Config                                               *nvim-tree-config*
       • {reload_on_bufenter}?                  (`boolean`) (default: `false`)
       • {respect_buf_cwd}?                     (`boolean`) (default: `false`)
       • {select_prompts}?                      (`boolean`) (default: `false`)
-      • {sort}?                                (`nvim_tree.Config.Sort`)
-                                               |nvim_tree.Config.Sort|
-      • {view}?                                (`nvim_tree.Config.View`)
-                                               |nvim_tree.Config.View|
-      • {renderer}?                            (`nvim_tree.Config.Renderer`)
-                                               |nvim_tree.Config.Renderer|
-      • {hijack_directories}?                  (`nvim_tree.Config.HijackDirectories`)
-                                               |nvim_tree.Config.HijackDirectories|
-      • {update_focused_file}?                 (`nvim_tree.Config.UpdateFocusedFile`)
-                                               |nvim_tree.Config.UpdateFocusedFile|
-      • {system_open}?                         (`nvim_tree.Config.SystemOpen`)
-                                               |nvim_tree.Config.SystemOpen|
-      • {git}?                                 (`nvim_tree.Config.Git`)
-                                               |nvim_tree.Config.Git|
-      • {diagnostics}?                         (`nvim_tree.Config.Diagnostics`)
-                                               |nvim_tree.Config.Diagnostics|
-      • {modified}?                            (`nvim_tree.Config.Modified`)
-                                               |nvim_tree.Config.Modified|
-      • {filters}?                             (`nvim_tree.Config.Filters`)
-                                               |nvim_tree.Config.Filters|
-      • {live_filter}?                         (`nvim_tree.Config.LiveFilter`)
-                                               |nvim_tree.Config.LiveFilter|
-      • {filesystem_watchers}?                 (`nvim_tree.Config.FilesystemWatchers`)
-                                               |nvim_tree.Config.FilesystemWatchers|
-      • {actions}?                             (`nvim_tree.Config.Actions`)
-                                               |nvim_tree.Config.Actions|
-      • {trash}?                               (`nvim_tree.Config.Trash`)
-                                               |nvim_tree.Config.Trash|
-      • {tab}?                                 (`nvim_tree.Config.Tab`)
-                                               |nvim_tree.Config.Tab|
-      • {bookmarks}?                           (`nvim_tree.Config.Bookmarks`)
-                                               |nvim_tree.Config.Bookmarks|
-      • {notify}?                              (`nvim_tree.Config.Notify`)
-                                               |nvim_tree.Config.Notify|
-      • {help}?                                (`nvim_tree.Config.Help`)
-                                               |nvim_tree.Config.Help|
-      • {ui}?                                  (`nvim_tree.Config.UI`)
-                                               |nvim_tree.Config.UI|
-      • {experimental}?                        (`nvim_tree.Config.Experimental`)
-                                               |nvim_tree.Config.Experimental|
-      • {log}?                                 (`nvim_tree.Config.Log`)
-                                               |nvim_tree.Config.Log|
+      • {sort}?                                (`nvim_tree.config.sort`)
+                                               |nvim_tree.config.sort|
+      • {view}?                                (`nvim_tree.config.view`)
+                                               |nvim_tree.config.view|
+      • {renderer}?                            (`nvim_tree.config.renderer`)
+                                               |nvim_tree.config.renderer|
+      • {hijack_directories}?                  (`nvim_tree.config.hijack_directories`)
+                                               |nvim_tree.config.hijack_directories|
+      • {update_focused_file}?                 (`nvim_tree.config.update_focused_file`)
+                                               |nvim_tree.config.update_focused_file|
+      • {system_open}?                         (`nvim_tree.config.system_open`)
+                                               |nvim_tree.config.system_open|
+      • {git}?                                 (`nvim_tree.config.git`)
+                                               |nvim_tree.config.git|
+      • {diagnostics}?                         (`nvim_tree.config.diagnostics`)
+                                               |nvim_tree.config.diagnostics|
+      • {modified}?                            (`nvim_tree.config.modified`)
+                                               |nvim_tree.config.modified|
+      • {filters}?                             (`nvim_tree.config.filters`)
+                                               |nvim_tree.config.filters|
+      • {live_filter}?                         (`nvim_tree.config.live_filter`)
+                                               |nvim_tree.config.live_filter|
+      • {filesystem_watchers}?                 (`nvim_tree.config.filesystem_watchers`)
+                                               |nvim_tree.config.filesystem_watchers|
+      • {actions}?                             (`nvim_tree.config.actions`)
+                                               |nvim_tree.config.actions|
+      • {trash}?                               (`nvim_tree.config.trash`)
+                                               |nvim_tree.config.trash|
+      • {tab}?                                 (`nvim_tree.config.tab`)
+                                               |nvim_tree.config.tab|
+      • {bookmarks}?                           (`nvim_tree.config.bookmarks`)
+                                               |nvim_tree.config.bookmarks|
+      • {notify}?                              (`nvim_tree.config.notify`)
+                                               |nvim_tree.config.notify|
+      • {help}?                                (`nvim_tree.config.help`)
+                                               |nvim_tree.config.help|
+      • {ui}?                                  (`nvim_tree.config.ui`)
+                                               |nvim_tree.config.ui|
+      • {experimental}?                        (`nvim_tree.config.experimental`)
+                                               |nvim_tree.config.experimental|
+      • {log}?                                 (`nvim_tree.config.log`)
+                                               |nvim_tree.config.log|
 
 
 
 ==============================================================================
 Class: Config.Sort                                     *nvim-tree-config-sort*
 
-*nvim_tree.Config.Sort*
+*nvim_tree.config.sort*
     Sort files within a directory.
 
-    {sorter} presets                            *nvim_tree.Config.Sort.Sorter*
+    {sorter} presets                            *nvim_tree.config.sort.Sorter*
     • `"name"`
     • `"case_sensitive"` name
     • `"modification_time"`
@@ -2248,7 +2248,7 @@ Class: Config.Sort                                     *nvim-tree-config-sort*
 
         ---Sort by name length
         ---@param nodes nvim_tree.api.Node[]
-        ---@return nvim_tree.Config.Sort.Sorter?
+        ---@return nvim_tree.config.sort.Sorter?
         local sorter = function(nodes)
          table.sort(nodes, function(a, b)
            return #a.name < #b.name
@@ -2256,10 +2256,10 @@ Class: Config.Sort                                     *nvim-tree-config-sort*
         end
 <
 
-    {sorter} may be a function that returns a |nvim_tree.Config.Sort.Sorter|
+    {sorter} may be a function that returns a |nvim_tree.config.sort.Sorter|
 
     Fields: ~
-      • {sorter}?         (`nvim_tree.Config.Sort.Sorter|(fun(nodes: nvim_tree.api.Node[]): nvim_tree.Config.Sort.Sorter?)`)
+      • {sorter}?         (`nvim_tree.config.sort.Sorter|(fun(nodes: nvim_tree.api.Node[]): nvim_tree.config.sort.Sorter?)`)
                           (default: `"name"`)
       • {folders_first}?  (`boolean`, default: `true`) Sort folders before
                           files. Has no effect when {sorter} is a function.
@@ -2272,17 +2272,17 @@ Class: Config.Sort                                     *nvim-tree-config-sort*
 ==============================================================================
 Class: Config.View                                     *nvim-tree-config-view*
 
-*nvim_tree.Config.View*
+*nvim_tree.config.view*
     Configures the dimensions and appearance of the nvim-tree window.
 
     The window is "docked" at the left by default, however may be configured
-    to float: |nvim_tree.Config.View.Float|
+    to float: |nvim_tree.config.view.float|
 
-    {width} can be a |nvim_tree.Config.View.WidthSpec| for simple static
-    control or a |nvim_tree.Config.View.Width| for fully dynamic control based
+    {width} can be a |nvim_tree.config.view.widthSpec| for simple static
+    control or a |nvim_tree.config.view.width| for fully dynamic control based
     on longest line.
 
-                                             *nvim_tree.Config.View.WidthSpec*
+                                             *nvim_tree.config.view.widthSpec*
     • `string`: `x%` string e.g. `30%`
     • `integer`: number of columns
     • `function`: returns one of the above
@@ -2313,12 +2313,12 @@ Class: Config.View                                     *nvim-tree-config-view*
                                         |'relativenumber'|
       • {signcolumn}?                   (`"yes"|"auto"|"no"`, default:
                                         `"yes"`) |'signcolumn'|
-      • {width}?                        (`nvim_tree.Config.View.WidthSpec|nvim_tree.Config.View.Width`)
+      • {width}?                        (`nvim_tree.config.view.widthSpec|nvim_tree.config.view.width`)
                                         (default: `30`)
-      • {float}?                        (`nvim_tree.Config.View.Float`)
-                                        |nvim_tree.Config.View.Float|
+      • {float}?                        (`nvim_tree.config.view.float`)
+                                        |nvim_tree.config.view.float|
 
-*nvim_tree.Config.View.Float*
+*nvim_tree.config.view.float*
     Configure floating window behaviour
 
     {open_win_config} is passed to |nvim_open_win()|, default: >lua
@@ -2340,16 +2340,16 @@ Class: Config.View                                     *nvim-tree-config-view*
                                (default:
                                `{ relative = "editor", border = "rounded", width = 30, height = 30, row = 1, col = 1, }`)
 
-*nvim_tree.Config.View.Width*
+*nvim_tree.config.view.width*
     Configure dynamic width based on longest line.
 
     Fields: ~
-      • {min}?             (`nvim_tree.Config.View.WidthSpec`) (default: `30`)
-      • {max}?             (`nvim_tree.Config.View.WidthSpec`, default: `-1`)
+      • {min}?             (`nvim_tree.config.view.widthSpec`) (default: `30`)
+      • {max}?             (`nvim_tree.config.view.widthSpec`, default: `-1`)
                            -1 for unbounded.
       • {lines_excluded}?  (`("root")[]`, default: `{ "root" }`) Exclude these
                            lines when computing width.
-      • {padding}?         (`nvim_tree.Config.View.WidthSpec`, default: `1`)
+      • {padding}?         (`nvim_tree.config.view.widthSpec`, default: `1`)
                            Extra padding to the right.
 
 
@@ -2357,7 +2357,7 @@ Class: Config.View                                     *nvim-tree-config-view*
 ==============================================================================
 Class: Config.Renderer                             *nvim-tree-config-renderer*
 
-*nvim_tree.Config.Renderer*
+*nvim_tree.config.renderer*
     Controls the appearance of the tree.
 
     See |nvim-tree-icons-highlighting| for {highlight_} and {decorators}
@@ -2389,7 +2389,7 @@ Class: Config.Renderer                             *nvim-tree-config-renderer*
                                    (default: `":~:s?$?/..?"`)
       • {indent_width}?            (`integer`, default: `2`) Number of spaces
                                    for each tree nesting level. Minimum 1.
-      • {hidden_display}?          (`nvim_tree.Config.Renderer.HiddenDisplay`, default: `none`)
+      • {hidden_display}?          (`nvim_tree.config.renderer.HiddenDisplay`, default: `none`)
                                    |nvim-tree-hidden-display|
       • {symlink_destination}?     (`boolean`, default: `true`) Appends an
                                    arrow followed by the target of the
@@ -2397,46 +2397,46 @@ Class: Config.Renderer                             *nvim-tree-config-renderer*
       • {decorators}?              (`(string|nvim_tree.api.decorator.UserDecorator)[]`)
                                    (default:
                                    `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`)
-      • {highlight_git}?           (`nvim_tree.Config.Renderer.Highlight`)
+      • {highlight_git}?           (`nvim_tree.config.renderer.Highlight`)
                                    (default: `"none"`)
-      • {highlight_opened_files}?  (`nvim_tree.Config.Renderer.Highlight`)
+      • {highlight_opened_files}?  (`nvim_tree.config.renderer.Highlight`)
                                    (default: `"none"`)
-      • {highlight_hidden}?        (`nvim_tree.Config.Renderer.Highlight`)
+      • {highlight_hidden}?        (`nvim_tree.config.renderer.Highlight`)
                                    (default: `"none"`)
-      • {highlight_modified}?      (`nvim_tree.Config.Renderer.Highlight`)
+      • {highlight_modified}?      (`nvim_tree.config.renderer.Highlight`)
                                    (default: `"none"`)
-      • {highlight_bookmarks}?     (`nvim_tree.Config.Renderer.Highlight`)
+      • {highlight_bookmarks}?     (`nvim_tree.config.renderer.Highlight`)
                                    (default: `"none"`)
-      • {highlight_diagnostics}?   (`nvim_tree.Config.Renderer.Highlight`)
+      • {highlight_diagnostics}?   (`nvim_tree.config.renderer.Highlight`)
                                    (default: `"none"`)
-      • {highlight_clipboard}?     (`nvim_tree.Config.Renderer.Highlight`)
+      • {highlight_clipboard}?     (`nvim_tree.config.renderer.Highlight`)
                                    (default: `"name"`)
       • {special_files}?           (`string[]`, default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }`)
                                    Highlight special files and directories
                                    with `NvimTreeSpecial*`.
-      • {indent_markers}?          (`nvim_tree.Config.Renderer.IndentMarkers`)
-                                   |nvim_tree.Config.Renderer.IndentMarkers|
-      • {icons}?                   (`nvim_tree.Config.Renderer.Icons`)
-                                   |nvim_tree.Config.Renderer.Icons|
+      • {indent_markers}?          (`nvim_tree.config.renderer.indent_markers`)
+                                   |nvim_tree.config.renderer.indent_markers|
+      • {icons}?                   (`nvim_tree.config.renderer.icons`)
+                                   |nvim_tree.config.renderer.icons|
 
-*nvim_tree.Config.Renderer.Icons*
+*nvim_tree.config.renderer.icons*
     Icons and separators
 
     See |nvim-tree-icons-highlighting| for: {_placement} fields.
 
     Fields: ~
-      • {git_placement}?          (`nvim_tree.Config.Renderer.Icons.Placement`)
+      • {git_placement}?          (`nvim_tree.config.renderer.icons.Placement`)
                                   (default: `before`)
-      • {hidden_placement}?       (`nvim_tree.Config.Renderer.Icons.Placement`)
+      • {hidden_placement}?       (`nvim_tree.config.renderer.icons.Placement`)
                                   (default: `after`)
-      • {modified_placement}?     (`nvim_tree.Config.Renderer.Icons.Placement`)
+      • {modified_placement}?     (`nvim_tree.config.renderer.icons.Placement`)
                                   (default: `after`)
-      • {bookmarks_placement}?    (`nvim_tree.Config.Renderer.Icons.Placement`)
+      • {bookmarks_placement}?    (`nvim_tree.config.renderer.icons.Placement`)
                                   (default: `signcolumn`)
-      • {diagnostics_placement}?  (`nvim_tree.Config.Renderer.Icons.Placement`)
+      • {diagnostics_placement}?  (`nvim_tree.config.renderer.icons.Placement`)
                                   (default: `signcolumn`)
       • {padding}?                (`table`)
-                                     *nvim_tree.Config.Renderer.Icons.Padding*
+                                     *nvim_tree.config.renderer.icons.padding*
                                   • {icon}? (`string`, default: `" "`) Between
                                     icon and filename.
                                   • {folder_arrow}? (`string`, default: `" "`)
@@ -2444,14 +2444,14 @@ Class: Config.Renderer                             *nvim-tree-config-renderer*
                                     icon.
       • {symlink_arrow}?          (`string`, default: `" ➛ "`) Separator
                                   between symlink source and target.
-      • {show}?                   (`nvim_tree.Config.Renderer.Icons.Show`)
-                                  |nvim_tree.Config.Renderer.Icons.Show|
-      • {glyphs}?                 (`nvim_tree.Config.Renderer.Icons.Glyphs`)
-                                  |nvim_tree.Config.Renderer.Icons.Glyphs|
-      • {web_devicons}?           (`nvim_tree.Config.Renderer.Icons.WebDevicons`)
-                                  |nvim_tree.Config.Renderer.Icons.WebDevicons|
-
-*nvim_tree.Config.Renderer.Icons.Glyphs*
+      • {show}?                   (`nvim_tree.config.renderer.icons.show`)
+                                  |nvim_tree.config.renderer.icons.show|
+      • {glyphs}?                 (`nvim_tree.config.renderer.icons.glyphs`)
+                                  |nvim_tree.config.renderer.icons.glyphs|
+      • {web_devicons}?           (`nvim_tree.config.renderer.icons.web_devicons`)
+                                  |nvim_tree.config.renderer.icons.web_devicons|
+
+*nvim_tree.config.renderer.icons.glyphs*
     See |nvim-tree-icons-highlighting|.
 
     Glyphs that appear in the sign column must have length <= 2
@@ -2462,7 +2462,7 @@ Class: Config.Renderer                             *nvim-tree-config-renderer*
       • {bookmark}?  (`string`) (default: `"󰆤"`)
       • {modified}?  (`string`) (default: `"●"`)
       • {hidden}?    (`string`) (default: `"󰜌"`)
-      • {folder}?    (`table`)                     *nvim_tree.Config.Renderer.Icons.Glyphs.Folder*
+      • {folder}?    (`table`)                     *nvim_tree.config.renderer.icons.glyphs.folder*
                      • {arrow_closed}? (`string`) (default: left arrow)
                      • {arrow_open}? (`string`) (default: down arrow)
                      • {default}? (`string`) (default: `""`)
@@ -2471,7 +2471,7 @@ Class: Config.Renderer                             *nvim-tree-config-renderer*
                      • {empty_open}? (`string`) (default: `""`)
                      • {symlink}? (`string`) (default: `""`)
                      • {symlink_open}? (`string`) (default: `""`)
-      • {git}?       (`table`)                        *nvim_tree.Config.Renderer.Icons.Glyphs.Git*
+      • {git}?       (`table`)                        *nvim_tree.config.renderer.icons.glyphs.git*
                      • {unstaged}? (`string`) (default: `"✗"`)
                      • {staged}? (`string`) (default: `"✓"`)
                      • {unmerged}? (`string`) (default: `""`)
@@ -2480,7 +2480,7 @@ Class: Config.Renderer                             *nvim-tree-config-renderer*
                      • {deleted}? (`string`) (default: `""`)
                      • {ignored}? (`string`) (default: `"◌"`)
 
-*nvim_tree.Config.Renderer.Icons.Show*
+*nvim_tree.config.renderer.icons.show*
     See |nvim-tree-icons-highlighting|.
 
     Fields: ~
@@ -2494,33 +2494,33 @@ Class: Config.Renderer                             *nvim-tree-config-renderer*
       • {folder_arrow}?  (`boolean`, default: `true`) Show a small arrow
                          before the folder node. Arrow will be a part of the
                          node when using
-                         |nvim_tree.Config.Renderer.IndentMarkers|.
+                         |nvim_tree.config.renderer.indent_markers|.
 
-*nvim_tree.Config.Renderer.Icons.WebDevicons*
+*nvim_tree.config.renderer.icons.web_devicons*
     Configure optional plugin `nvim-tree/nvim-web-devicons`, see
     |nvim-tree-icons-highlighting|.
 
     Fields: ~
       • {file}?    (`table`)
-                            *nvim_tree.Config.Renderer.Icons.WebDevicons.File*
+                           *nvim_tree.config.renderer.icons.web_devicons.file*
                    • {enable}? (`boolean`) (default: `true`)
                    • {color}? (`boolean`) (default: `true`)
       • {folder}?  (`table`)
-                          *nvim_tree.Config.Renderer.Icons.WebDevicons.Folder*
+                         *nvim_tree.config.renderer.icons.web_devicons.folder*
                    • {enable}? (`boolean`) (default: `false`)
                    • {color}? (`boolean`) (default: `true`)
 
-*nvim_tree.Config.Renderer.IndentMarkers*
+*nvim_tree.config.renderer.indent_markers*
 
     Fields: ~
       • {enable}?         (`boolean`, default: `false`) Display indent markers
                           when folders are open.
       • {inline_arrows}?  (`boolean`, default: `true`) Display folder arrows
                           in the same column as indent marker when using
-                          |nvim_tree.Config.Renderer.Icons.Padding|
+                          |nvim_tree.config.renderer.icons.padding|
                           {folder_arrow}
       • {icons}?          (`table`)
-                               *nvim_tree.Config.Renderer.IndentMarkers.Icons*
+                              *nvim_tree.config.renderer.indent_markers.icons*
                           Before the file/directory, length 1.
                           • {corner}? (`string`) (default: `"└"`)
                           • {edge}? (`string`) (default: `"│"`)
@@ -2533,12 +2533,12 @@ Class: Config.Renderer                             *nvim-tree-config-renderer*
 ==============================================================================
 Class: Config.HijackDirectories          *nvim-tree-config-hijack-directories*
 
-*nvim_tree.Config.HijackDirectories*
+*nvim_tree.config.hijack_directories*
     Hijack directory buffers by replacing the directory buffer with the tree.
 
     Disable this option if you use vim-dirvish or dirbuf.nvim.
 
-    If |nvim_tree.Config| {hijack_netrw} and {disable_netrw} are `false` this
+    If |nvim_tree.config| {hijack_netrw} and {disable_netrw} are `false` this
     feature will be disabled.
 
     Fields: ~
@@ -2551,25 +2551,25 @@ Class: Config.HijackDirectories          *nvim-tree-config-hijack-directories*
 ==============================================================================
 Class: Config.UpdateFocusedFile         *nvim-tree-config-update-focused-file*
 
-*nvim_tree.Config.UpdateFocusedFile*
+*nvim_tree.config.update_focused_file*
     Update the focused file on |BufEnter|, uncollapsing folders recursively.
 
     Fields: ~
       • {enable}?       (`boolean`) (default: `false`)
-      • {update_root}?  (`nvim_tree.Config.UpdateFocusedFile.UpdateRoot`)
-                        |nvim_tree.Config.UpdateFocusedFile.UpdateRoot|
+      • {update_root}?  (`nvim_tree.config.update_focused_file.update_root`)
+                        |nvim_tree.config.update_focused_file.update_root|
       • {exclude}?      (`boolean|(fun(args: vim.api.keyset.create_autocmd.callback_args): boolean)`, default: `false`)
                         A function called on |BufEnter| that returns true if
                         the file should not be focused when opening.
 
-*nvim_tree.Config.UpdateFocusedFile.UpdateRoot*
+*nvim_tree.config.update_focused_file.update_root*
     Update the root directory of the tree if the file is not under the current
     root directory.
 
-    Prefers vim's cwd and |nvim_tree.Config| {root_dirs}, falling back to the
+    Prefers vim's cwd and |nvim_tree.config| {root_dirs}, falling back to the
     directory containing the file.
 
-    Requires |nvim_tree.Config.UpdateFocusedFile|
+    Requires |nvim_tree.config.update_focused_file|
 
     Fields: ~
       • {enable}?       (`boolean`) (default: `false`)
@@ -2583,7 +2583,7 @@ Class: Config.UpdateFocusedFile         *nvim-tree-config-update-focused-file*
 ==============================================================================
 Class: Config.SystemOpen                        *nvim-tree-config-system-open*
 
-*nvim_tree.Config.SystemOpen*
+*nvim_tree.config.system_open*
     Open files or directories via the OS.
 
     Nvim:
@@ -2607,7 +2607,7 @@ Class: Config.SystemOpen                        *nvim-tree-config-system-open*
 ==============================================================================
 Class: Config.Git                                       *nvim-tree-config-git*
 
-*nvim_tree.Config.Git*
+*nvim_tree.config.git*
     Git operations are run in the background thus status may not immediately
     appear.
 
@@ -2641,7 +2641,7 @@ Class: Config.Git                                       *nvim-tree-config-git*
 ==============================================================================
 Class: Config.Diagnostics                       *nvim-tree-config-diagnostics*
 
-*nvim_tree.Config.Diagnostics*
+*nvim_tree.config.diagnostics*
     Integrate with |lsp| or COC diagnostics.
 
     See |nvim-tree-icons-highlighting|.
@@ -2659,12 +2659,12 @@ Class: Config.Diagnostics                       *nvim-tree-config-diagnostics*
                               |vim.diagnostic.Opts| overrides {severity} and
                               {icons}
       • {severity}?           (`table`)
-                                       *nvim_tree.Config.Diagnostics.Severity*
+                                       *nvim_tree.config.diagnostics.severity*
                               • {min}? (`vim.diagnostic.Severity`, default:
                                 HINT) |vim.diagnostic.severity|
                               • {max}? (`vim.diagnostic.Severity`, default:
                                 ERROR) |vim.diagnostic.severity|
-      • {icons}?              (`table`)                                *nvim_tree.Config.Diagnostics.Icons*
+      • {icons}?              (`table`)                                *nvim_tree.config.diagnostics.icons*
                               • {hint}? (`string`) (default: `""` )
                               • {info}? (`string`) (default: `""` )
                               • {warning}? (`string`) (default: `""` )
@@ -2675,11 +2675,11 @@ Class: Config.Diagnostics                       *nvim-tree-config-diagnostics*
 ==============================================================================
 Class: Config.Modified                             *nvim-tree-config-modified*
 
-*nvim_tree.Config.Modified*
+*nvim_tree.config.modified*
     Indicate which files have unsaved modification. To see modified status in
     the tree you will need:
-    • |nvim_tree.Config.Renderer.Icons.Show| {modified} OR
-    • |nvim_tree.Config.Renderer| {highlight_modified}
+    • |nvim_tree.config.renderer.icons.show| {modified} OR
+    • |nvim_tree.config.renderer| {highlight_modified}
 
     See |nvim-tree-icons-highlighting|.
 
@@ -2697,7 +2697,7 @@ Class: Config.Modified                             *nvim-tree-config-modified*
 ==============================================================================
 Class: Config.Filters                               *nvim-tree-config-filters*
 
-*nvim_tree.Config.Filters*
+*nvim_tree.config.filters*
     Filters may be applied to the tree to exlude the display of
     file/directories.
 
@@ -2707,7 +2707,7 @@ Class: Config.Filters                               *nvim-tree-config-filters*
     mappings.
 
     `I     `{git_ignored}`         `|nvim-tree-api.tree.toggle_gitignore_filter()|
-    Ignore files based on `.gitignore`. Requires |nvim_tree.Config.Git|
+    Ignore files based on `.gitignore`. Requires |nvim_tree.config.git|
 
     `H     `{dotfiles}`            `|nvim-tree-api.tree.toggle_hidden_filter()|
     Filter dotfiles: files/directories starting with a `.`
@@ -2752,7 +2752,7 @@ Class: Config.Filters                               *nvim-tree-config-filters*
 ==============================================================================
 Class: Config.LiveFilter                        *nvim-tree-config-live-filter*
 
-*nvim_tree.Config.LiveFilter*
+*nvim_tree.config.live_filter*
     Live filter allows you to filter the tree nodes dynamically, based on
     regex matching, see |vim.regex|
 
@@ -2770,7 +2770,7 @@ Class: Config.LiveFilter                        *nvim-tree-config-live-filter*
 ==============================================================================
 Class: Config.FilesystemWatchers        *nvim-tree-config-filesystem-watchers*
 
-*nvim_tree.Config.FilesystemWatchers*
+*nvim_tree.config.filesystem_watchers*
     Use file system watchers (libuv `uv_fs_event_t`) to monitor the filesystem
     for changes and update the tree.
 
@@ -2796,25 +2796,25 @@ Class: Config.FilesystemWatchers        *nvim-tree-config-filesystem-watchers*
 ==============================================================================
 Class: Config.Actions                               *nvim-tree-config-actions*
 
-*nvim_tree.Config.Actions*
+*nvim_tree.config.actions*
 
     Fields: ~
       • {use_system_clipboard}?  (`boolean`, default: `true`) Use the system
                                  clipboard for copy/paste. Copied text will be
                                  stored in registers `+` (system), otherwise,
                                  it will be stored in `1` and `"`
-      • {change_dir}?            (`nvim_tree.Config.Actions.ChangeDir`)
-                                 |nvim_tree.Config.Actions.ChangeDir|
-      • {expand_all}?            (`nvim_tree.Config.Actions.ExpandAll`)
-                                 |nvim_tree.Config.Actions.ExpandAll|
-      • {file_popup}?            (`nvim_tree.Config.Actions.FilePopup`)
-                                 |nvim_tree.Config.Actions.FilePopup|
-      • {open_file}?             (`nvim_tree.Config.Actions.OpenFile`)
-                                 |nvim_tree.Config.Actions.OpenFile|
-      • {remove_file}?           (`nvim_tree.Config.Actions.RemoveFile`)
-                                 |nvim_tree.Config.Actions.RemoveFile|
-
-*nvim_tree.Config.Actions.ChangeDir*
+      • {change_dir}?            (`nvim_tree.config.actions.change_dir`)
+                                 |nvim_tree.config.actions.change_dir|
+      • {expand_all}?            (`nvim_tree.config.actions.expand_all`)
+                                 |nvim_tree.config.actions.expand_all|
+      • {file_popup}?            (`nvim_tree.config.actions.file_popup`)
+                                 |nvim_tree.config.actions.file_popup|
+      • {open_file}?             (`nvim_tree.config.actions.open_file`)
+                                 |nvim_tree.config.actions.open_file|
+      • {remove_file}?           (`nvim_tree.config.actions.remove_file`)
+                                 |nvim_tree.config.actions.remove_file|
+
+*nvim_tree.config.actions.change_dir*
     vim |current-directory| behaviour
 
     Fields: ~
@@ -2825,7 +2825,7 @@ Class: Config.Actions                               *nvim-tree-config-actions*
       • {restrict_above_cwd}?  (`boolean`, default: `false`) Restrict changing
                                to a directory above the global cwd.
 
-*nvim_tree.Config.Actions.ExpandAll*
+*nvim_tree.config.actions.expand_all*
     Configure |nvim-tree-api.tree.expand_all()| and
     |nvim-tree-api.node.expand()|
 
@@ -2839,7 +2839,7 @@ Class: Config.Actions                               *nvim-tree-config-actions*
                                  automatically e.g
                                  `{ ".git", "target", "build" }`
 
-*nvim_tree.Config.Actions.FilePopup*
+*nvim_tree.config.actions.file_popup*
     {file_popup} floating window.
 
     {open_win_config} is passed to |nvim_open_win()|, default: >lua
@@ -2859,7 +2859,7 @@ Class: Config.Actions                               *nvim-tree-config-actions*
       • {open_win_config}?  (`vim.api.keyset.win_config`) (default:
                             `{ col = 1, row = 1, relative = "cursor", border = "shadow", style = "minimal", }`)
 
-*nvim_tree.Config.Actions.OpenFile*
+*nvim_tree.config.actions.open_file*
     Opening files.
 
     Fields: ~
@@ -2869,10 +2869,10 @@ Class: Config.Actions                               *nvim-tree-config-actions*
                           from opening in the same window as the tree.
       • {resize_window}?  (`boolean`, default: `true`) Resizes the tree when
                           opening a file
-      • {window_picker}?  (`nvim_tree.Config.Actions.OpenFile.WindowPicker`)
-                          |nvim_tree.Config.Actions.OpenFile.WindowPicker|
+      • {window_picker}?  (`nvim_tree.config.actions.open_file.window_picker`)
+                          |nvim_tree.config.actions.open_file.window_picker|
 
-*nvim_tree.Config.Actions.OpenFile.WindowPicker*
+*nvim_tree.config.actions.open_file.window_picker*
     A window picker will be shown when there are multiple windows available to
     open a file. It will show a single character identifier in each window's
     status line.
@@ -2891,10 +2891,10 @@ Class: Config.Actions                               *nvim-tree-config-actions*
       • {chars}?    (`string`, default:
                     `"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"`) Identifier
                     characters to use.
-      • {exclude}?  (`nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude`)
-                    |nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude|
+      • {exclude}?  (`nvim_tree.config.actions.open_file.window_picker.exclude`)
+                    |nvim_tree.config.actions.open_file.window_picker.exclude|
 
-*nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude*
+*nvim_tree.config.actions.open_file.window_picker.exclude*
     Tables of buffer option names mapped to a list of option values. Windows
     containing matching buffers will not be:
     • available when using a window picker
@@ -2906,7 +2906,7 @@ Class: Config.Actions                               *nvim-tree-config-actions*
       • {buftype}?   (`string[]`) (default:
                      `{ "nofile", "terminal", "help", }`)
 
-*nvim_tree.Config.Actions.RemoveFile*
+*nvim_tree.config.actions.remove_file*
     Removing files.
 
     Fields: ~
@@ -2919,7 +2919,7 @@ Class: Config.Actions                               *nvim-tree-config-actions*
 ==============================================================================
 Class: Config.Trash                                   *nvim-tree-config-trash*
 
-*nvim_tree.Config.Trash*
+*nvim_tree.config.trash*
     Files may be trashed via an external command that must be installed on
     your system.
     • linux: `gio trash`, from linux package `glib2`
@@ -2934,12 +2934,12 @@ Class: Config.Trash                                   *nvim-tree-config-trash*
 ==============================================================================
 Class: Config.Tab                                       *nvim-tree-config-tab*
 
-*nvim_tree.Config.Tab*
+*nvim_tree.config.tab*
 
     Fields: ~
-      • {sync}?  (`nvim_tree.Config.Tab.Sync`) |nvim_tree.Config.Tab.Sync|
+      • {sync}?  (`nvim_tree.config.tab.sync`) |nvim_tree.config.tab.sync|
 
-*nvim_tree.Config.Tab.Sync*
+*nvim_tree.config.tab.sync*
 
     Fields: ~
       • {open}?    (`boolean`, default: `false`) Opens the tree automatically
@@ -2955,7 +2955,7 @@ Class: Config.Tab                                       *nvim-tree-config-tab*
 ==============================================================================
 Class: Config.Notify                                 *nvim-tree-config-notify*
 
-*nvim_tree.Config.Notify*
+*nvim_tree.config.notify*
     nvim-tree |vim.log.levels|
     • `ERROR`: hard errors e.g. failure to read from the file system.
     • `WARN`: non-fatal errors e.g. unable to system open a file.
@@ -2974,7 +2974,7 @@ Class: Config.Notify                                 *nvim-tree-config-notify*
 ==============================================================================
 Class: Config.Bookmarks                           *nvim-tree-config-bookmarks*
 
-*nvim_tree.Config.Bookmarks*
+*nvim_tree.config.bookmarks*
     Optionally {persist} bookmarks to a json file:
     • `true` use default: `stdpath("data") .. "/nvim-tree-bookmarks.json"`
     • `false` do not persist
@@ -2988,29 +2988,29 @@ Class: Config.Bookmarks                           *nvim-tree-config-bookmarks*
 ==============================================================================
 Class: Config.Help                                     *nvim-tree-config-help*
 
-*nvim_tree.Config.Help*
+*nvim_tree.config.help*
     Configure help window, default mapping `g?`
 
-                                                *nvim_tree.Config.Help.SortBy*
+                                                *nvim_tree.config.help.SortBy*
     • `"key"`: alphabetically by keymap
     • `"desc"`: alphabetically by description
 
     Fields: ~
-      • {sort_by}?  (`nvim_tree.Config.Help.SortBy`, default: `"key"`)
-                    |nvim_tree.Config.Help.SortBy|
+      • {sort_by}?  (`nvim_tree.config.help.SortBy`, default: `"key"`)
+                    |nvim_tree.config.help.SortBy|
 
 
 
 ==============================================================================
 Class: Config.UI                                         *nvim-tree-config-ui*
 
-*nvim_tree.Config.UI*
+*nvim_tree.config.ui*
 
     Fields: ~
-      • {confirm}?  (`nvim_tree.Config.UI.Confirm`)
-                    |nvim_tree.Config.UI.Confirm|
+      • {confirm}?  (`nvim_tree.config.ui.confirm`)
+                    |nvim_tree.config.ui.confirm|
 
-*nvim_tree.Config.UI.Confirm*
+*nvim_tree.config.ui.confirm*
     Confirmation prompts.
 
     Fields: ~
@@ -3024,7 +3024,7 @@ Class: Config.UI                                         *nvim-tree-config-ui*
 ==============================================================================
 Class: Config.Experimental                     *nvim-tree-config-experimental*
 
-*nvim_tree.Config.Experimental*
+*nvim_tree.config.experimental*
     Experimental features that may become default or optional functionality.
 
     In the event of a problem please disable the experiment and raise an
@@ -3035,7 +3035,7 @@ Class: Config.Experimental                     *nvim-tree-config-experimental*
 ==============================================================================
 Class: Config.Log                                       *nvim-tree-config-log*
 
-*nvim_tree.Config.Log*
+*nvim_tree.config.log*
     Log to a file `nvim-tree.log` in |stdpath()| `log`, usually
     `${XDG_STATE_HOME}/nvim`
 
@@ -3043,10 +3043,10 @@ Class: Config.Log                                       *nvim-tree-config-log*
       • {enable}?    (`boolean`) (default: `false`)
       • {truncate}?  (`boolean`, default: `false`) Remove existing log file at
                      startup.
-      • {types}?     (`nvim_tree.Config.Log.Types`)
-                     |nvim_tree.Config.Log.Types|
+      • {types}?     (`nvim_tree.config.log.types`)
+                     |nvim_tree.config.log.types|
 
-*nvim_tree.Config.Log.Types*
+*nvim_tree.config.log.types*
     Specify which information to log.
 
     Fields: ~
@@ -3063,7 +3063,7 @@ Class: Config.Log                                       *nvim-tree-config-log*
                         verbose.
       • {git}?          (`boolean`, default: `false`) Git processing, verbose.
       • {watcher}?      (`boolean`, default: `false`)
-                        |nvim_tree.Config.FilesystemWatchers| processing,
+                        |nvim_tree.config.filesystem_watchers| processing,
                         verbose.
 
 
diff --git a/lua/nvim-tree.lua b/lua/nvim-tree.lua
index 9d27cee3541..fcec5f91b82 100644
--- a/lua/nvim-tree.lua
+++ b/lua/nvim-tree.lua
@@ -252,7 +252,7 @@ local function setup_autocommands(opts)
   })
 end
 
----@type nvim_tree.Config
+---@type nvim_tree.config
 local DEFAULT_OPTS = { -- BEGIN_DEFAULT_OPTS
   on_attach = "default",
   hijack_cursor = false,
@@ -628,7 +628,7 @@ local ACCEPTED_ENUMS = {
   },
 }
 
----@param conf? nvim_tree.Config
+---@param conf? nvim_tree.config
 local function validate_options(conf)
   local msg
 
@@ -733,7 +733,7 @@ function M.purge_all_state()
   require("nvim-tree.watcher").purge_watchers()
 end
 
----@param conf? nvim_tree.Config
+---@param conf? nvim_tree.config
 function M.setup(conf)
   if vim.fn.has("nvim-0.9") == 0 then
     notify.warn("nvim-tree.lua requires Neovim 0.9 or higher")
diff --git a/lua/nvim-tree/_meta/config.lua b/lua/nvim-tree/_meta/config.lua
index aa3f7aa1b1f..56ee8f9a722 100644
--- a/lua/nvim-tree/_meta/config.lua
+++ b/lua/nvim-tree/_meta/config.lua
@@ -20,7 +20,7 @@ error("Cannot require a meta file")
 ---
 ---or as a typed variable e.g.
 ---```lua
----  ---@type nvim_tree.Config
+---  ---@type nvim_tree.config
 ---  local config = {
 ---    hijack_cursor = true,
 ---  }
@@ -38,9 +38,9 @@ error("Cannot require a meta file")
 ---
 ---{hijack_unnamed_buffer_when_opening} opens in place of the unnamed buffer if it's empty.
 ---
----{root_dirs} preferred root directories, requires [nvim_tree.Config.UpdateFocusedFile.UpdateRoot].
+---{root_dirs} preferred root directories, requires [nvim_tree.config.update_focused_file.update_root].
 ---
----{prefer_startup_root} prefer startup root directory when updating root directory of the tree. Requires [nvim_tree.Config.UpdateFocusedFile.UpdateRoot].
+---{prefer_startup_root} prefer startup root directory when updating root directory of the tree. Requires [nvim_tree.config.update_focused_file.update_root].
 ---
 ---{sync_root_with_cwd} changes the tree root directory on [DirChanged] and refreshes the tree.
 ---
@@ -49,7 +49,7 @@ error("Cannot require a meta file")
 ---{respect_buf_cwd} changes the [current-directory] of nvim-tree to that of new buffer's when opening nvim-tree.
 ---
 ---{select_prompts} uses [vim.ui.select()] style prompts. Necessary when using a UI prompt decorator such as dressing.nvim or telescope-ui-select.nvim
----@class nvim_tree.Config
+---@class nvim_tree.config
 ---
 ---(default: `default`)
 ---@field on_attach? "default"|(fun(bufnr: integer))
@@ -87,65 +87,65 @@ error("Cannot require a meta file")
 ---(default: `false`)
 ---@field select_prompts? boolean
 ---
----[nvim_tree.Config.Sort]
----@field sort? nvim_tree.Config.Sort
+---[nvim_tree.config.sort]
+---@field sort? nvim_tree.config.sort
 ---
----[nvim_tree.Config.View]
----@field view? nvim_tree.Config.View
+---[nvim_tree.config.view]
+---@field view? nvim_tree.config.view
 ---
----[nvim_tree.Config.Renderer]
----@field renderer? nvim_tree.Config.Renderer
+---[nvim_tree.config.renderer]
+---@field renderer? nvim_tree.config.renderer
 ---
----[nvim_tree.Config.HijackDirectories]
----@field hijack_directories? nvim_tree.Config.HijackDirectories
+---[nvim_tree.config.hijack_directories]
+---@field hijack_directories? nvim_tree.config.hijack_directories
 ---
----[nvim_tree.Config.UpdateFocusedFile]
----@field update_focused_file? nvim_tree.Config.UpdateFocusedFile
+---[nvim_tree.config.update_focused_file]
+---@field update_focused_file? nvim_tree.config.update_focused_file
 ---
----[nvim_tree.Config.SystemOpen]
----@field system_open? nvim_tree.Config.SystemOpen
+---[nvim_tree.config.system_open]
+---@field system_open? nvim_tree.config.system_open
 ---
----[nvim_tree.Config.Git]
----@field git? nvim_tree.Config.Git
+---[nvim_tree.config.git]
+---@field git? nvim_tree.config.git
 ---
----[nvim_tree.Config.Diagnostics]
----@field diagnostics? nvim_tree.Config.Diagnostics
+---[nvim_tree.config.diagnostics]
+---@field diagnostics? nvim_tree.config.diagnostics
 ---
----[nvim_tree.Config.Modified]
----@field modified? nvim_tree.Config.Modified
+---[nvim_tree.config.modified]
+---@field modified? nvim_tree.config.modified
 ---
----[nvim_tree.Config.Filters]
----@field filters? nvim_tree.Config.Filters
+---[nvim_tree.config.filters]
+---@field filters? nvim_tree.config.filters
 ---
----[nvim_tree.Config.LiveFilter]
----@field live_filter? nvim_tree.Config.LiveFilter
+---[nvim_tree.config.live_filter]
+---@field live_filter? nvim_tree.config.live_filter
 ---
----[nvim_tree.Config.FilesystemWatchers]
----@field filesystem_watchers? nvim_tree.Config.FilesystemWatchers
+---[nvim_tree.config.filesystem_watchers]
+---@field filesystem_watchers? nvim_tree.config.filesystem_watchers
 ---
----[nvim_tree.Config.Actions]
----@field actions? nvim_tree.Config.Actions
+---[nvim_tree.config.actions]
+---@field actions? nvim_tree.config.actions
 ---
----[nvim_tree.Config.Trash]
----@field trash? nvim_tree.Config.Trash
+---[nvim_tree.config.trash]
+---@field trash? nvim_tree.config.trash
 ---
----[nvim_tree.Config.Tab]
----@field tab? nvim_tree.Config.Tab
+---[nvim_tree.config.tab]
+---@field tab? nvim_tree.config.tab
 ---
----[nvim_tree.Config.Bookmarks]
----@field bookmarks? nvim_tree.Config.Bookmarks
+---[nvim_tree.config.bookmarks]
+---@field bookmarks? nvim_tree.config.bookmarks
 ---
----[nvim_tree.Config.Notify]
----@field notify? nvim_tree.Config.Notify
+---[nvim_tree.config.notify]
+---@field notify? nvim_tree.config.notify
 ---
----[nvim_tree.Config.Help]
----@field help? nvim_tree.Config.Help
+---[nvim_tree.config.help]
+---@field help? nvim_tree.config.help
 ---
----[nvim_tree.Config.UI]
----@field ui? nvim_tree.Config.UI
+---[nvim_tree.config.ui]
+---@field ui? nvim_tree.config.ui
 ---
----[nvim_tree.Config.Experimental]
----@field experimental? nvim_tree.Config.Experimental
+---[nvim_tree.config.experimental]
+---@field experimental? nvim_tree.config.experimental
 ---
----[nvim_tree.Config.Log]
----@field log? nvim_tree.Config.Log
+---[nvim_tree.config.log]
+---@field log? nvim_tree.config.log
diff --git a/lua/nvim-tree/_meta/config/actions.lua b/lua/nvim-tree/_meta/config/actions.lua
index e65fe4d79c4..2228c15a87e 100644
--- a/lua/nvim-tree/_meta/config/actions.lua
+++ b/lua/nvim-tree/_meta/config/actions.lua
@@ -3,31 +3,31 @@ error("Cannot require a meta file")
 
 
 
----@class nvim_tree.Config.Actions
+---@class nvim_tree.config.actions
 ---
 ---Use the system clipboard for copy/paste. Copied text will be stored in registers `+` (system), otherwise, it will be stored in `1` and `"`
 ---(default: `true`)
 ---@field use_system_clipboard? boolean
 ---
----[nvim_tree.Config.Actions.ChangeDir]
----@field change_dir? nvim_tree.Config.Actions.ChangeDir
+---[nvim_tree.config.actions.change_dir]
+---@field change_dir? nvim_tree.config.actions.change_dir
 ---
----[nvim_tree.Config.Actions.ExpandAll]
----@field expand_all? nvim_tree.Config.Actions.ExpandAll
+---[nvim_tree.config.actions.expand_all]
+---@field expand_all? nvim_tree.config.actions.expand_all
 ---
----[nvim_tree.Config.Actions.FilePopup]
----@field file_popup? nvim_tree.Config.Actions.FilePopup
+---[nvim_tree.config.actions.file_popup]
+---@field file_popup? nvim_tree.config.actions.file_popup
 ---
----[nvim_tree.Config.Actions.OpenFile]
----@field open_file? nvim_tree.Config.Actions.OpenFile
+---[nvim_tree.config.actions.open_file]
+---@field open_file? nvim_tree.config.actions.open_file
 ---
----[nvim_tree.Config.Actions.RemoveFile]
----@field remove_file? nvim_tree.Config.Actions.RemoveFile
+---[nvim_tree.config.actions.remove_file]
+---@field remove_file? nvim_tree.config.actions.remove_file
 
 
 
 --- vim [current-directory] behaviour
----@class nvim_tree.Config.Actions.ChangeDir
+---@class nvim_tree.config.actions.change_dir
 ---
 ---Change the working directory when changing directories in the tree
 ---(default: `true`)
@@ -44,7 +44,7 @@ error("Cannot require a meta file")
 
 
 ---Configure [nvim-tree-api.tree.expand_all()] and [nvim-tree-api.node.expand()]
----@class nvim_tree.Config.Actions.ExpandAll
+---@class nvim_tree.config.actions.expand_all
 ---
 ---Limit the number of folders being explored when expanding every folder. Avoids hanging Nvim when running this action on very large folders.
 ---(default: `300`)
@@ -69,7 +69,7 @@ error("Cannot require a meta file")
 ---}
 ---```
 ---You shouldn't define {width} and {height} values here. They will be overridden to fit the file_popup content.
----@class nvim_tree.Config.Actions.FilePopup
+---@class nvim_tree.config.actions.file_popup
 ---
 ---(default: `{ col = 1, row = 1, relative = "cursor", border = "shadow", style = "minimal", }`)
 ---@field open_win_config? vim.api.keyset.win_config
@@ -77,7 +77,7 @@ error("Cannot require a meta file")
 
 
 ---Opening files.
----@class nvim_tree.Config.Actions.OpenFile
+---@class nvim_tree.config.actions.open_file
 ---
 ---Closes the explorer when opening a file
 ---(default: `false`)
@@ -91,8 +91,8 @@ error("Cannot require a meta file")
 ---(default: `true`)
 ---@field resize_window? boolean
 ---
----[nvim_tree.Config.Actions.OpenFile.WindowPicker]
----@field window_picker? nvim_tree.Config.Actions.OpenFile.WindowPicker
+---[nvim_tree.config.actions.open_file.window_picker]
+---@field window_picker? nvim_tree.config.actions.open_file.window_picker
 
 
 
@@ -102,7 +102,7 @@ error("Cannot require a meta file")
 ---
 ---You may define a {picker} function that should return the window id that will open the node, or `nil` if an invalid window is picked or user cancelled the action. The picker may create a new window.
 ---
----@class nvim_tree.Config.Actions.OpenFile.WindowPicker
+---@class nvim_tree.config.actions.open_file.window_picker
 ---
 ---(default: `true`)
 ---@field enable? boolean
@@ -115,15 +115,15 @@ error("Cannot require a meta file")
 ---(default: `"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"`)
 ---@field chars? string
 ---
----[nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude]
----@field exclude? nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude
+---[nvim_tree.config.actions.open_file.window_picker.exclude]
+---@field exclude? nvim_tree.config.actions.open_file.window_picker.exclude
 
 
 
 ---Tables of buffer option names mapped to a list of option values. Windows containing matching buffers will not be:
 --- - available when using a window picker
 --- - selected when not using a window picker
----@class nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude
+---@class nvim_tree.config.actions.open_file.window_picker.exclude
 ---
 ---(default: `{ "notify", "lazy", "qf", "diff", "fugitive", "fugitiveblame", }`)
 ---@field filetype? string[]
@@ -133,7 +133,7 @@ error("Cannot require a meta file")
 
 
 ---Removing files.
----@class nvim_tree.Config.Actions.RemoveFile
+---@class nvim_tree.config.actions.remove_file
 ---
 ---Close any window that displays a file when removing that file from the tree.
 ---(default: `true`)
diff --git a/lua/nvim-tree/_meta/config/bookmarks.lua b/lua/nvim-tree/_meta/config/bookmarks.lua
index 83a3c3d0ac3..84cff5ba603 100644
--- a/lua/nvim-tree/_meta/config/bookmarks.lua
+++ b/lua/nvim-tree/_meta/config/bookmarks.lua
@@ -7,7 +7,7 @@ error("Cannot require a meta file")
 ---- `false` do not persist
 ---- `string` absolute path of your choice
 ---
----@class nvim_tree.Config.Bookmarks
+---@class nvim_tree.config.bookmarks
 ---
 ---(default: `false`)
 ---@field persist? boolean|string
diff --git a/lua/nvim-tree/_meta/config/diagnostics.lua b/lua/nvim-tree/_meta/config/diagnostics.lua
index 44b0d6d4f8c..e58eedebcf9 100644
--- a/lua/nvim-tree/_meta/config/diagnostics.lua
+++ b/lua/nvim-tree/_meta/config/diagnostics.lua
@@ -7,7 +7,7 @@ error("Cannot require a meta file")
 ---
 ---See [nvim-tree-icons-highlighting].
 ---
----@class nvim_tree.Config.Diagnostics
+---@class nvim_tree.config.diagnostics
 ---
 ---(default: `false`)
 ---@field enable? boolean
@@ -28,14 +28,14 @@ error("Cannot require a meta file")
 ---(default: `false`)
 ---@field diagnostic_opts? boolean
 ---
----@field severity? nvim_tree.Config.Diagnostics.Severity
+---@field severity? nvim_tree.config.diagnostics.severity
 ---
----@field icons? nvim_tree.Config.Diagnostics.Icons
+---@field icons? nvim_tree.config.diagnostics.icons
 
 
 
----[nvim_tree.Config.Diagnostics.Severity]()
----@class nvim_tree.Config.Diagnostics.Severity
+---[nvim_tree.config.diagnostics.severity]()
+---@class nvim_tree.config.diagnostics.severity
 ---@inlinedoc
 ---
 ---[vim.diagnostic.severity]
@@ -48,8 +48,8 @@ error("Cannot require a meta file")
 
 
 
----[nvim_tree.Config.Diagnostics.Icons]()
----@class nvim_tree.Config.Diagnostics.Icons
+---[nvim_tree.config.diagnostics.icons]()
+---@class nvim_tree.config.diagnostics.icons
 ---@inlinedoc
 ---
 ---(default: `""` )
diff --git a/lua/nvim-tree/_meta/config/experimental.lua b/lua/nvim-tree/_meta/config/experimental.lua
index ce2afeeb1c8..ee46529632a 100644
--- a/lua/nvim-tree/_meta/config/experimental.lua
+++ b/lua/nvim-tree/_meta/config/experimental.lua
@@ -7,7 +7,7 @@ error("Cannot require a meta file")
 ---
 ---In the event of a problem please disable the experiment and raise an issue.
 ---
----@class nvim_tree.Config.Experimental
+---@class nvim_tree.config.experimental
 ---
 --Example below for future reference:
 --
diff --git a/lua/nvim-tree/_meta/config/filesystem_watchers.lua b/lua/nvim-tree/_meta/config/filesystem_watchers.lua
index 959d70017ac..1db15b985fb 100644
--- a/lua/nvim-tree/_meta/config/filesystem_watchers.lua
+++ b/lua/nvim-tree/_meta/config/filesystem_watchers.lua
@@ -12,7 +12,7 @@ error("Cannot require a meta file")
 --- - A function that is passed an absolute path and returns `true` to disable
 ---This may be useful when a path is not in `.gitignore` or git integration is disabled.
 ---
----@class nvim_tree.Config.FilesystemWatchers
+---@class nvim_tree.config.filesystem_watchers
 ---
 ---(default: `true`)
 ---@field enable? boolean
diff --git a/lua/nvim-tree/_meta/config/filters.lua b/lua/nvim-tree/_meta/config/filters.lua
index 93de5d64733..812233e6bb2 100644
--- a/lua/nvim-tree/_meta/config/filters.lua
+++ b/lua/nvim-tree/_meta/config/filters.lua
@@ -10,7 +10,7 @@ error("Cannot require a meta file")
 ---Filters can be set at startup or toggled live via API with default mappings.
 ---
 ---`I     `{git_ignored}`         `|nvim-tree-api.tree.toggle_gitignore_filter()|
----Ignore files based on `.gitignore`. Requires |nvim_tree.Config.Git|
+---Ignore files based on `.gitignore`. Requires |nvim_tree.config.git|
 ---
 ---`H     `{dotfiles}`            `|nvim-tree-api.tree.toggle_hidden_filter()|
 ---Filter dotfiles: files/directories starting with a `.`
@@ -32,7 +32,7 @@ error("Cannot require a meta file")
 ---All filters including live filter may be disabled via {enable} and toggled with |nvim-tree-api.tree.toggle_enable_filters()|
 ---
 ---Files/directories may be {exclude}d from filtering: they will always be shown, overriding {git_ignored}, {dotfiles} and {custom}.
----@class nvim_tree.Config.Filters
+---@class nvim_tree.config.filters
 ---
 ---Enable all filters.
 ---(default: `true`)
diff --git a/lua/nvim-tree/_meta/config/git.lua b/lua/nvim-tree/_meta/config/git.lua
index 318fec0aed1..41a14a4529a 100644
--- a/lua/nvim-tree/_meta/config/git.lua
+++ b/lua/nvim-tree/_meta/config/git.lua
@@ -13,7 +13,7 @@ error("Cannot require a meta file")
 ---
 ---See [nvim-tree-icons-highlighting].
 ---
----@class nvim_tree.Config.Git
+---@class nvim_tree.config.git
 ---
 ---(default: `true`)
 ---@field enable? boolean
diff --git a/lua/nvim-tree/_meta/config/help.lua b/lua/nvim-tree/_meta/config/help.lua
index 8724b397c6f..00bfcdcf926 100644
--- a/lua/nvim-tree/_meta/config/help.lua
+++ b/lua/nvim-tree/_meta/config/help.lua
@@ -3,18 +3,18 @@ error("Cannot require a meta file")
 
 
 
----@alias nvim_tree.Config.Help.SortBy "key"|"desc"
+---@alias nvim_tree.config.help.SortBy "key"|"desc"
 
 
 
 ---Configure help window, default mapping `g?`
 ---
----[nvim_tree.Config.Help.SortBy]()
+---[nvim_tree.config.help.SortBy]()
 ---- `"key"`: alphabetically by keymap
 ---- `"desc"`: alphabetically by description
 ---
----@class nvim_tree.Config.Help
+---@class nvim_tree.config.help
 ---
----[nvim_tree.Config.Help.SortBy]
+---[nvim_tree.config.help.SortBy]
 ---(default: `"key"`)
----@field sort_by? nvim_tree.Config.Help.SortBy
+---@field sort_by? nvim_tree.config.help.SortBy
diff --git a/lua/nvim-tree/_meta/config/hijack_directories.lua b/lua/nvim-tree/_meta/config/hijack_directories.lua
index af601f4ac1e..c8c24ddd5c0 100644
--- a/lua/nvim-tree/_meta/config/hijack_directories.lua
+++ b/lua/nvim-tree/_meta/config/hijack_directories.lua
@@ -7,9 +7,9 @@ error("Cannot require a meta file")
 ---
 ---Disable this option if you use vim-dirvish or dirbuf.nvim.
 ---
----If [nvim_tree.Config] {hijack_netrw} and {disable_netrw} are `false` this feature will be disabled.
+---If [nvim_tree.config] {hijack_netrw} and {disable_netrw} are `false` this feature will be disabled.
 ---
----@class nvim_tree.Config.HijackDirectories
+---@class nvim_tree.config.hijack_directories
 ---
 ---(default: `true`)
 ---@field enable? boolean
diff --git a/lua/nvim-tree/_meta/config/live_filter.lua b/lua/nvim-tree/_meta/config/live_filter.lua
index b5569a68d93..7651dc3595a 100644
--- a/lua/nvim-tree/_meta/config/live_filter.lua
+++ b/lua/nvim-tree/_meta/config/live_filter.lua
@@ -7,7 +7,7 @@ error("Cannot require a meta file")
 ---
 --- This feature is bound to the `f` key by default. The filter can be cleared with the `F` key by default.
 ---
----@class nvim_tree.Config.LiveFilter
+---@class nvim_tree.config.live_filter
 ---
 ---Prefix of the filter displayed in the buffer.
 ---(default: `"[FILTER]: "`)
diff --git a/lua/nvim-tree/_meta/config/log.lua b/lua/nvim-tree/_meta/config/log.lua
index 3f43101f2f8..396e25ef626 100644
--- a/lua/nvim-tree/_meta/config/log.lua
+++ b/lua/nvim-tree/_meta/config/log.lua
@@ -5,7 +5,7 @@ error("Cannot require a meta file")
 
 ---Log to a file `nvim-tree.log` in [stdpath()] `log`, usually `${XDG_STATE_HOME}/nvim`
 ---
----@class nvim_tree.Config.Log
+---@class nvim_tree.config.log
 ---
 ---(default: `false`)
 ---@field enable? boolean
@@ -14,11 +14,11 @@ error("Cannot require a meta file")
 ---(default: `false`)
 ---@field truncate? boolean
 ---
----[nvim_tree.Config.Log.Types]
----@field types? nvim_tree.Config.Log.Types
+---[nvim_tree.config.log.types]
+---@field types? nvim_tree.config.log.types
 
 ---Specify which information to log.
----@class nvim_tree.Config.Log.Types
+---@class nvim_tree.config.log.types
 ---
 ---Everything.
 ---(default: `false`)
@@ -48,6 +48,6 @@ error("Cannot require a meta file")
 ---(default: `false`)
 ---@field git? boolean
 ---
----[nvim_tree.Config.FilesystemWatchers] processing, verbose.
+---[nvim_tree.config.filesystem_watchers] processing, verbose.
 ---(default: `false`)
 ---@field watcher? boolean
diff --git a/lua/nvim-tree/_meta/config/modified.lua b/lua/nvim-tree/_meta/config/modified.lua
index e527d6ee62e..ea1909d0870 100644
--- a/lua/nvim-tree/_meta/config/modified.lua
+++ b/lua/nvim-tree/_meta/config/modified.lua
@@ -5,12 +5,12 @@ error("Cannot require a meta file")
 
 ---Indicate which files have unsaved modification.
 ---To see modified status in the tree you will need:
---- - [nvim_tree.Config.Renderer.Icons.Show] {modified} OR
---- - [nvim_tree.Config.Renderer] {highlight_modified}
+--- - [nvim_tree.config.renderer.icons.show] {modified} OR
+--- - [nvim_tree.config.renderer] {highlight_modified}
 ---
 ---See [nvim-tree-icons-highlighting].
 ---
----@class nvim_tree.Config.Modified
+---@class nvim_tree.config.modified
 ---
 ---(default: `false`)
 ---@field enable? boolean
diff --git a/lua/nvim-tree/_meta/config/notify.lua b/lua/nvim-tree/_meta/config/notify.lua
index bf6b9493005..b6acbe586f2 100644
--- a/lua/nvim-tree/_meta/config/notify.lua
+++ b/lua/nvim-tree/_meta/config/notify.lua
@@ -9,7 +9,7 @@ error("Cannot require a meta file")
 ---- `INFO`: information only e.g. file copy path confirmation.
 ---- `DEBUG`: information for troubleshooting, e.g. failures in some window closing operations.
 ---
----@class nvim_tree.Config.Notify
+---@class nvim_tree.config.notify
 ---
 ---Specify minimum notification |vim.log.levels|
 ---(Default: `vim.log.levels.INFO`)
diff --git a/lua/nvim-tree/_meta/config/renderer.lua b/lua/nvim-tree/_meta/config/renderer.lua
index 08f052b8393..dc17823a1d8 100644
--- a/lua/nvim-tree/_meta/config/renderer.lua
+++ b/lua/nvim-tree/_meta/config/renderer.lua
@@ -3,11 +3,11 @@ error("Cannot require a meta file")
 
 
 
----@alias nvim_tree.Config.Renderer.Highlight "none"|"icon"|"name"|"all"
+---@alias nvim_tree.config.renderer.Highlight "none"|"icon"|"name"|"all"
 
----@alias nvim_tree.Config.Renderer.HiddenDisplay "none"|"simple"|"all"|(fun(hidden_stats: table): string)
+---@alias nvim_tree.config.renderer.HiddenDisplay "none"|"simple"|"all"|(fun(hidden_stats: table): string)
 
----@alias nvim_tree.Config.Renderer.Icons.Placement "before"|"after"|"signcolumn"|"right_align"
+---@alias nvim_tree.config.renderer.icons.Placement "before"|"after"|"signcolumn"|"right_align"
 
 
 
@@ -24,7 +24,7 @@ error("Cannot require a meta file")
 ---  return ".../" .. vim.fn.fnamemodify(path, ":t")
 ---end
 ---```
----@class nvim_tree.Config.Renderer
+---@class nvim_tree.config.renderer
 ---
 ---Appends a trailing slash to folder and symlink folder target names.
 ---(default: `false`)
@@ -47,7 +47,7 @@ error("Cannot require a meta file")
 ---
 ---[nvim-tree-hidden-display]
 ---(default: `none`)
----@field hidden_display? nvim_tree.Config.Renderer.HiddenDisplay
+---@field hidden_display? nvim_tree.config.renderer.HiddenDisplay
 ---
 ---Appends an arrow followed by the target of the symlink.
 ---(default: `true`)
@@ -57,55 +57,55 @@ error("Cannot require a meta file")
 ---@field decorators? (string|nvim_tree.api.decorator.UserDecorator)[]
 ---
 ---(default: `"none"`)
----@field highlight_git? nvim_tree.Config.Renderer.Highlight
+---@field highlight_git? nvim_tree.config.renderer.Highlight
 ---
 ---(default: `"none"`)
----@field highlight_opened_files? nvim_tree.Config.Renderer.Highlight
+---@field highlight_opened_files? nvim_tree.config.renderer.Highlight
 ---
 ---(default: `"none"`)
----@field highlight_hidden? nvim_tree.Config.Renderer.Highlight
+---@field highlight_hidden? nvim_tree.config.renderer.Highlight
 ---
 ---(default: `"none"`)
----@field highlight_modified? nvim_tree.Config.Renderer.Highlight
+---@field highlight_modified? nvim_tree.config.renderer.Highlight
 ---
 ---(default: `"none"`)
----@field highlight_bookmarks? nvim_tree.Config.Renderer.Highlight
+---@field highlight_bookmarks? nvim_tree.config.renderer.Highlight
 ---
 ---(default: `"none"`)
----@field highlight_diagnostics? nvim_tree.Config.Renderer.Highlight
+---@field highlight_diagnostics? nvim_tree.config.renderer.Highlight
 ---
 ---(default: `"name"`)
----@field highlight_clipboard? nvim_tree.Config.Renderer.Highlight
+---@field highlight_clipboard? nvim_tree.config.renderer.Highlight
 ---
 ---Highlight special files and directories with `NvimTreeSpecial*`.
 ---(default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }`)
 ---@field special_files? string[]
 ---
----[nvim_tree.Config.Renderer.IndentMarkers]
----@field indent_markers? nvim_tree.Config.Renderer.IndentMarkers
+---[nvim_tree.config.renderer.indent_markers]
+---@field indent_markers? nvim_tree.config.renderer.indent_markers
 ---
----[nvim_tree.Config.Renderer.Icons]
----@field icons? nvim_tree.Config.Renderer.Icons
+---[nvim_tree.config.renderer.icons]
+---@field icons? nvim_tree.config.renderer.icons
 
 
 
----@class nvim_tree.Config.Renderer.IndentMarkers
+---@class nvim_tree.config.renderer.indent_markers
 ---
 ---Display indent markers when folders are open.
 ---(default: `false`)
 ---@field enable? boolean
 ---
----Display folder arrows in the same column as indent marker when using [nvim_tree.Config.Renderer.Icons.Padding] {folder_arrow}
+---Display folder arrows in the same column as indent marker when using [nvim_tree.config.renderer.icons.padding] {folder_arrow}
 ---(default: `true`)
 ---@field inline_arrows? boolean
 ---
----@field icons? nvim_tree.Config.Renderer.IndentMarkers.Icons
+---@field icons? nvim_tree.config.renderer.indent_markers.icons
 
 
 
----[nvim_tree.Config.Renderer.IndentMarkers.Icons]()
+---[nvim_tree.config.renderer.indent_markers.icons]()
 ---Before the file/directory, length 1.
----@class nvim_tree.Config.Renderer.IndentMarkers.Icons
+---@class nvim_tree.config.renderer.indent_markers.icons
 ---@inlinedoc
 ---
 ---(default: `"└"`)
@@ -124,52 +124,52 @@ error("Cannot require a meta file")
 ---Icons and separators
 ---
 ---See [nvim-tree-icons-highlighting] for: {_placement} fields.
----@class nvim_tree.Config.Renderer.Icons
+---@class nvim_tree.config.renderer.icons
 ---
 ---(default: `before`)
----@field git_placement? nvim_tree.Config.Renderer.Icons.Placement
+---@field git_placement? nvim_tree.config.renderer.icons.Placement
 ---
 ---(default: `after`)
----@field hidden_placement? nvim_tree.Config.Renderer.Icons.Placement
+---@field hidden_placement? nvim_tree.config.renderer.icons.Placement
 ---
 ---(default: `after`)
----@field modified_placement? nvim_tree.Config.Renderer.Icons.Placement
+---@field modified_placement? nvim_tree.config.renderer.icons.Placement
 ---
 ---(default: `signcolumn`)
----@field bookmarks_placement? nvim_tree.Config.Renderer.Icons.Placement
+---@field bookmarks_placement? nvim_tree.config.renderer.icons.Placement
 ---
 ---(default: `signcolumn`)
----@field diagnostics_placement? nvim_tree.Config.Renderer.Icons.Placement
+---@field diagnostics_placement? nvim_tree.config.renderer.icons.Placement
 ---
----@field padding? nvim_tree.Config.Renderer.Icons.Padding
+---@field padding? nvim_tree.config.renderer.icons.padding
 ---
 ---Separator between symlink source and target.
 ---(default: `" ➛ "`)
 ---@field symlink_arrow? string
 ---
----[nvim_tree.Config.Renderer.Icons.Show]
----@field show? nvim_tree.Config.Renderer.Icons.Show
+---[nvim_tree.config.renderer.icons.show]
+---@field show? nvim_tree.config.renderer.icons.show
 ---
----[nvim_tree.Config.Renderer.Icons.Glyphs]
----@field glyphs? nvim_tree.Config.Renderer.Icons.Glyphs
+---[nvim_tree.config.renderer.icons.glyphs]
+---@field glyphs? nvim_tree.config.renderer.icons.glyphs
 ---
----[nvim_tree.Config.Renderer.Icons.WebDevicons]
----@field web_devicons? nvim_tree.Config.Renderer.Icons.WebDevicons
+---[nvim_tree.config.renderer.icons.web_devicons]
+---@field web_devicons? nvim_tree.config.renderer.icons.web_devicons
 
 
 
 ---Configure optional plugin `nvim-tree/nvim-web-devicons`, see [nvim-tree-icons-highlighting].
 ---
----@class nvim_tree.Config.Renderer.Icons.WebDevicons
+---@class nvim_tree.config.renderer.icons.web_devicons
 ---
----@field file? nvim_tree.Config.Renderer.Icons.WebDevicons.File
+---@field file? nvim_tree.config.renderer.icons.web_devicons.file
 ---
----@field folder? nvim_tree.Config.Renderer.Icons.WebDevicons.Folder
+---@field folder? nvim_tree.config.renderer.icons.web_devicons.folder
 
 
 
----[nvim_tree.Config.Renderer.Icons.WebDevicons.File]()
----@class nvim_tree.Config.Renderer.Icons.WebDevicons.File
+---[nvim_tree.config.renderer.icons.web_devicons.file]()
+---@class nvim_tree.config.renderer.icons.web_devicons.file
 ---@inlinedoc
 ---
 ---(default: `true`)
@@ -179,8 +179,8 @@ error("Cannot require a meta file")
 ---@field color? boolean
 
 
----[nvim_tree.Config.Renderer.Icons.WebDevicons.Folder]()
----@class nvim_tree.Config.Renderer.Icons.WebDevicons.Folder
+---[nvim_tree.config.renderer.icons.web_devicons.folder]()
+---@class nvim_tree.config.renderer.icons.web_devicons.folder
 ---@inlinedoc
 ---
 ---(default: `false`)
@@ -191,8 +191,8 @@ error("Cannot require a meta file")
 
 
 
----[nvim_tree.Config.Renderer.Icons.Padding]()
----@class nvim_tree.Config.Renderer.Icons.Padding
+---[nvim_tree.config.renderer.icons.padding]()
+---@class nvim_tree.config.renderer.icons.padding
 ---@inlinedoc
 ---
 ---Between icon and filename.
@@ -206,7 +206,7 @@ error("Cannot require a meta file")
 
 
 ---See [nvim-tree-icons-highlighting].
----@class nvim_tree.Config.Renderer.Icons.Show
+---@class nvim_tree.config.renderer.icons.show
 ---
 ---(default: `true`)
 ---@field file? boolean
@@ -229,7 +229,7 @@ error("Cannot require a meta file")
 ---(default: `true`)
 ---@field bookmarks? boolean
 ---
----Show a small arrow before the folder node. Arrow will be a part of the node when using [nvim_tree.Config.Renderer.IndentMarkers].
+---Show a small arrow before the folder node. Arrow will be a part of the node when using [nvim_tree.config.renderer.indent_markers].
 ---(default: `true`)
 ---@field folder_arrow? boolean
 
@@ -238,7 +238,7 @@ error("Cannot require a meta file")
 ---See [nvim-tree-icons-highlighting].
 ---
 ---Glyphs that appear in the sign column must have length <= 2
----@class nvim_tree.Config.Renderer.Icons.Glyphs
+---@class nvim_tree.config.renderer.icons.glyphs
 ---
 ---Files
 ---(default: `""`)
@@ -256,14 +256,14 @@ error("Cannot require a meta file")
 ---(default: `"󰜌"`)
 ---@field hidden? string
 ---
----@field folder? nvim_tree.Config.Renderer.Icons.Glyphs.Folder
+---@field folder? nvim_tree.config.renderer.icons.glyphs.folder
 ---
----@field git? nvim_tree.Config.Renderer.Icons.Glyphs.Git
+---@field git? nvim_tree.config.renderer.icons.glyphs.git
 
 
 
----[nvim_tree.Config.Renderer.Icons.Glyphs.Folder]()
----@class nvim_tree.Config.Renderer.Icons.Glyphs.Folder
+---[nvim_tree.config.renderer.icons.glyphs.folder]()
+---@class nvim_tree.config.renderer.icons.glyphs.folder
 ---@inlinedoc
 ---(default: left arrow)
 ---@field arrow_closed? string
@@ -284,8 +284,8 @@ error("Cannot require a meta file")
 
 
 
----[nvim_tree.Config.Renderer.Icons.Glyphs.Git]()
----@class nvim_tree.Config.Renderer.Icons.Glyphs.Git
+---[nvim_tree.config.renderer.icons.glyphs.git]()
+---@class nvim_tree.config.renderer.icons.glyphs.git
 ---@inlinedoc
 ---(default: `"✗"`)
 ---@field unstaged? string
diff --git a/lua/nvim-tree/_meta/config/sort.lua b/lua/nvim-tree/_meta/config/sort.lua
index 0646ab587a2..255d9e1fe59 100644
--- a/lua/nvim-tree/_meta/config/sort.lua
+++ b/lua/nvim-tree/_meta/config/sort.lua
@@ -3,13 +3,13 @@ error("Cannot require a meta file")
 
 
 
----@alias nvim_tree.Config.Sort.Sorter "name"|"case_sensitive"|"modification_time"|"extension"|"suffix"|"filetype"
+---@alias nvim_tree.config.sort.Sorter "name"|"case_sensitive"|"modification_time"|"extension"|"suffix"|"filetype"
 
 
 
 ---Sort files within a directory.
 ---
----{sorter} presets [nvim_tree.Config.Sort.Sorter]()
+---{sorter} presets [nvim_tree.config.sort.Sorter]()
 ---- `"name"`
 ---- `"case_sensitive"` name
 ---- `"modification_time"`
@@ -22,19 +22,19 @@ error("Cannot require a meta file")
 ---
 ------Sort by name length
 ------@param nodes nvim_tree.api.Node[]
-------@return nvim_tree.Config.Sort.Sorter?
+------@return nvim_tree.config.sort.Sorter?
 ---local sorter = function(nodes)
 ---  table.sort(nodes, function(a, b)
 ---    return #a.name < #b.name
 ---  end)
 ---end
 ---```
----{sorter} may be a function that returns a [nvim_tree.Config.Sort.Sorter]
+---{sorter} may be a function that returns a [nvim_tree.config.sort.Sorter]
 ---
----@class nvim_tree.Config.Sort
+---@class nvim_tree.config.sort
 ---
 ---(default: `"name"`)
----@field sorter? nvim_tree.Config.Sort.Sorter|(fun(nodes: nvim_tree.api.Node[]): nvim_tree.Config.Sort.Sorter?)
+---@field sorter? nvim_tree.config.sort.Sorter|(fun(nodes: nvim_tree.api.Node[]): nvim_tree.config.sort.Sorter?)
 ---
 ---Sort folders before files. Has no effect when {sorter} is a function.
 ---(default: `true`)
diff --git a/lua/nvim-tree/_meta/config/system_open.lua b/lua/nvim-tree/_meta/config/system_open.lua
index 00ea263e11a..114bdf6501d 100644
--- a/lua/nvim-tree/_meta/config/system_open.lua
+++ b/lua/nvim-tree/_meta/config/system_open.lua
@@ -14,7 +14,7 @@ error("Cannot require a meta file")
 ---
 ---Once nvim-tree minimum Nvim version is updated to 0.10, these options will no longer be necessary and will be removed.
 ---
----@class nvim_tree.Config.SystemOpen
+---@class nvim_tree.config.system_open
 ---
 ---The open command itself
 ---@field cmd? string
diff --git a/lua/nvim-tree/_meta/config/tab.lua b/lua/nvim-tree/_meta/config/tab.lua
index 7fc5f9f2146..daaf8cc26ed 100644
--- a/lua/nvim-tree/_meta/config/tab.lua
+++ b/lua/nvim-tree/_meta/config/tab.lua
@@ -3,14 +3,14 @@ error("Cannot require a meta file")
 
 
 
----@class nvim_tree.Config.Tab
+---@class nvim_tree.config.tab
 ---
----[nvim_tree.Config.Tab.Sync]
----@field sync? nvim_tree.Config.Tab.Sync
+---[nvim_tree.config.tab.sync]
+---@field sync? nvim_tree.config.tab.sync
 
 
 
----@class nvim_tree.Config.Tab.Sync
+---@class nvim_tree.config.tab.sync
 ---
 ---Opens the tree automatically when switching tabpage or opening a new tabpage if the tree was previously open.
 ---(default: `false`)
diff --git a/lua/nvim-tree/_meta/config/trash.lua b/lua/nvim-tree/_meta/config/trash.lua
index ad7a6f48cfc..56f3b7ebc66 100644
--- a/lua/nvim-tree/_meta/config/trash.lua
+++ b/lua/nvim-tree/_meta/config/trash.lua
@@ -8,7 +8,7 @@ error("Cannot require a meta file")
 --- - macOS: `trash`, from homebrew package `trash`
 --- - windows: `trash`, requires `trash-cli` or similar
 ---
----@class nvim_tree.Config.Trash
+---@class nvim_tree.config.trash
 ---
 ---(default: `"gio trash"` or `"trash"`)
 ---@field cmd? string
diff --git a/lua/nvim-tree/_meta/config/ui.lua b/lua/nvim-tree/_meta/config/ui.lua
index b1b50905359..5fdae9c0894 100644
--- a/lua/nvim-tree/_meta/config/ui.lua
+++ b/lua/nvim-tree/_meta/config/ui.lua
@@ -3,15 +3,15 @@ error("Cannot require a meta file")
 
 
 
----@class nvim_tree.Config.UI
+---@class nvim_tree.config.ui
 ---
----[nvim_tree.Config.UI.Confirm]
----@field confirm? nvim_tree.Config.UI.Confirm
+---[nvim_tree.config.ui.confirm]
+---@field confirm? nvim_tree.config.ui.confirm
 
 
 
 ---Confirmation prompts.
----@class nvim_tree.Config.UI.Confirm
+---@class nvim_tree.config.ui.confirm
 ---
 ---Prompt before removing.
 ---(default: `true`)
diff --git a/lua/nvim-tree/_meta/config/update_focused_file.lua b/lua/nvim-tree/_meta/config/update_focused_file.lua
index a193cddc0bc..290252ebfb5 100644
--- a/lua/nvim-tree/_meta/config/update_focused_file.lua
+++ b/lua/nvim-tree/_meta/config/update_focused_file.lua
@@ -5,13 +5,13 @@ error("Cannot require a meta file")
 
 ---Update the focused file on [BufEnter], uncollapsing folders recursively.
 ---
----@class nvim_tree.Config.UpdateFocusedFile
+---@class nvim_tree.config.update_focused_file
 ---
 ---(default: `false`)
 ---@field enable? boolean
 ---
----[nvim_tree.Config.UpdateFocusedFile.UpdateRoot]
----@field update_root? nvim_tree.Config.UpdateFocusedFile.UpdateRoot
+---[nvim_tree.config.update_focused_file.update_root]
+---@field update_root? nvim_tree.config.update_focused_file.update_root
 ---
 ---A function called on [BufEnter] that returns true if the file should not be focused when opening.
 ---(default: `false`)
@@ -21,11 +21,11 @@ error("Cannot require a meta file")
 
 ---Update the root directory of the tree if the file is not under the current root directory.
 ---
----Prefers vim's cwd and [nvim_tree.Config] {root_dirs}, falling back to the directory containing the file.
+---Prefers vim's cwd and [nvim_tree.config] {root_dirs}, falling back to the directory containing the file.
 ---
----Requires [nvim_tree.Config.UpdateFocusedFile]
+---Requires [nvim_tree.config.update_focused_file]
 ---
----@class nvim_tree.Config.UpdateFocusedFile.UpdateRoot
+---@class nvim_tree.config.update_focused_file.update_root
 ---
 ---(default: `false`)
 ---@field enable? boolean
diff --git a/lua/nvim-tree/_meta/config/view.lua b/lua/nvim-tree/_meta/config/view.lua
index 1a9d24d78a0..cede4837ba5 100644
--- a/lua/nvim-tree/_meta/config/view.lua
+++ b/lua/nvim-tree/_meta/config/view.lua
@@ -3,22 +3,22 @@ error("Cannot require a meta file")
 
 
 
----@alias nvim_tree.Config.View.WidthSpec string|integer|(fun(): integer|string)
+---@alias nvim_tree.config.view.widthSpec string|integer|(fun(): integer|string)
 
 
 
 ---Configures the dimensions and appearance of the nvim-tree window.
 ---
----The window is "docked" at the left by default, however may be configured to float: [nvim_tree.Config.View.Float]
+---The window is "docked" at the left by default, however may be configured to float: [nvim_tree.config.view.float]
 ---
----{width} can be a [nvim_tree.Config.View.WidthSpec] for simple static control or a [nvim_tree.Config.View.Width] for fully dynamic control based on longest line.
+---{width} can be a [nvim_tree.config.view.widthSpec] for simple static control or a [nvim_tree.config.view.width] for fully dynamic control based on longest line.
 ---
----[nvim_tree.Config.View.WidthSpec]()
+---[nvim_tree.config.view.widthSpec]()
 ---- `string`: `x%` string e.g. `30%`
 ---- `integer`: number of columns
 ---- `function`: returns one of the above
 ---
----@class nvim_tree.Config.View
+---@class nvim_tree.config.view
 ---
 ---When entering nvim-tree, reposition the view so that the current node is initially centralized, see [zz].
 ---(default: `false`)
@@ -56,23 +56,23 @@ error("Cannot require a meta file")
 ---@field signcolumn? "yes"|"auto"|"no"
 ---
 ---(default: `30`)
----@field width? nvim_tree.Config.View.WidthSpec|nvim_tree.Config.View.Width
+---@field width? nvim_tree.config.view.widthSpec|nvim_tree.config.view.width
 ---
----[nvim_tree.Config.View.Float]
----@field float? nvim_tree.Config.View.Float
+---[nvim_tree.config.view.float]
+---@field float? nvim_tree.config.view.float
 
 
 
 ---Configure dynamic width based on longest line.
 ---
----@class nvim_tree.Config.View.Width
+---@class nvim_tree.config.view.width
 ---
 ---(default: `30`)
----@field min? nvim_tree.Config.View.WidthSpec
+---@field min? nvim_tree.config.view.widthSpec
 ---
 ----1 for unbounded.
 ---(default: `-1`)
----@field max? nvim_tree.Config.View.WidthSpec
+---@field max? nvim_tree.config.view.widthSpec
 ---
 ---Exclude these lines when computing width.
 ---(default: `{ "root" }`)
@@ -80,7 +80,7 @@ error("Cannot require a meta file")
 ---
 ---Extra padding to the right.
 ---(default: `1`)
----@field padding? nvim_tree.Config.View.WidthSpec
+---@field padding? nvim_tree.config.view.widthSpec
 
 
 
@@ -97,7 +97,7 @@ error("Cannot require a meta file")
 ---  col = 1,
 ---}
 ---```
----@class nvim_tree.Config.View.Float
+---@class nvim_tree.config.view.float
 ---
 ---(default: `false`)
 ---@field enable? boolean

From de68ae3c16aeb5bc72e97ab5f54e4b273dcc6e12 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Wed, 21 Jan 2026 10:12:19 +1100
Subject: [PATCH 116/170] docs(#2934): snake case config alias names

---
 doc/nvim-tree-lua.txt                   | 57 +++++++++++--------------
 lua/nvim-tree/_meta/config/help.lua     | 13 +-----
 lua/nvim-tree/_meta/config/renderer.lua | 32 +++++++-------
 lua/nvim-tree/_meta/config/view.lua     | 14 +++---
 4 files changed, 51 insertions(+), 65 deletions(-)

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 95d9de42f20..a63e25ebb70 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -1504,14 +1504,14 @@ creating custom decorators.
 `REQUIRES`
   Feature must be enabled to show icons and highlighting.
 
-`PLACEMENT`                          *nvim_tree.config.renderer.icons.Placement*
+`PLACEMENT`                          *nvim_tree.config.renderer.icons.placement*
   Where to place the icon: |nvim_tree.config.renderer.icons| {_placement}
   • `before`: before file/folder, after the file/folders icons
   • `after`: after file/folder
   • `signcolumn`: far left, requires |nvim_tree.config.view| {signcolumn}.
   • `right_align`: far right
 
-`HIGHLIGHT`                                *nvim_tree.config.renderer.Highlight*
+`HIGHLIGHT`                                *nvim_tree.config.renderer.highlight*
   What should be highlighted: |nvim_tree.config.renderer| {highlight_}
   • `none`: no highlighting
   • `icon`: icon only
@@ -2071,7 +2071,7 @@ Show a summary of hidden files below the tree highlighted with `NvimTreeHiddenDi
 
 Configure via |nvim_tree.config.renderer| {hidden_display}
 
-                                     *nvim_tree.config.renderer.HiddenDisplay*
+                                    *nvim_tree.config.renderer.hidden_display*
  • `none`: disabled
  • `simple`: show how many hidden files are in a folder
  • `all`: show how many hidden and the number of hidden files by reason
@@ -2278,11 +2278,11 @@ Class: Config.View                                     *nvim-tree-config-view*
     The window is "docked" at the left by default, however may be configured
     to float: |nvim_tree.config.view.float|
 
-    {width} can be a |nvim_tree.config.view.widthSpec| for simple static
-    control or a |nvim_tree.config.view.width| for fully dynamic control based
-    on longest line.
+    {width} can be a |nvim_tree.config.view.width.spec| for static control or
+    a |nvim_tree.config.view.width| for fully dynamic control based on longest
+    line.
 
-                                             *nvim_tree.config.view.widthSpec*
+                                            *nvim_tree.config.view.width.spec*
     • `string`: `x%` string e.g. `30%`
     • `integer`: number of columns
     • `function`: returns one of the above
@@ -2313,7 +2313,7 @@ Class: Config.View                                     *nvim-tree-config-view*
                                         |'relativenumber'|
       • {signcolumn}?                   (`"yes"|"auto"|"no"`, default:
                                         `"yes"`) |'signcolumn'|
-      • {width}?                        (`nvim_tree.config.view.widthSpec|nvim_tree.config.view.width`)
+      • {width}?                        (`nvim_tree.config.view.width.spec|nvim_tree.config.view.width`)
                                         (default: `30`)
       • {float}?                        (`nvim_tree.config.view.float`)
                                         |nvim_tree.config.view.float|
@@ -2344,12 +2344,13 @@ Class: Config.View                                     *nvim-tree-config-view*
     Configure dynamic width based on longest line.
 
     Fields: ~
-      • {min}?             (`nvim_tree.config.view.widthSpec`) (default: `30`)
-      • {max}?             (`nvim_tree.config.view.widthSpec`, default: `-1`)
+      • {min}?             (`nvim_tree.config.view.width.spec`) (default:
+                           `30`)
+      • {max}?             (`nvim_tree.config.view.width.spec`, default: `-1`)
                            -1 for unbounded.
       • {lines_excluded}?  (`("root")[]`, default: `{ "root" }`) Exclude these
                            lines when computing width.
-      • {padding}?         (`nvim_tree.config.view.widthSpec`, default: `1`)
+      • {padding}?         (`nvim_tree.config.view.width.spec`, default: `1`)
                            Extra padding to the right.
 
 
@@ -2389,7 +2390,7 @@ Class: Config.Renderer                             *nvim-tree-config-renderer*
                                    (default: `":~:s?$?/..?"`)
       • {indent_width}?            (`integer`, default: `2`) Number of spaces
                                    for each tree nesting level. Minimum 1.
-      • {hidden_display}?          (`nvim_tree.config.renderer.HiddenDisplay`, default: `none`)
+      • {hidden_display}?          (`nvim_tree.config.renderer.hidden_display`, default: `none`)
                                    |nvim-tree-hidden-display|
       • {symlink_destination}?     (`boolean`, default: `true`) Appends an
                                    arrow followed by the target of the
@@ -2397,19 +2398,19 @@ Class: Config.Renderer                             *nvim-tree-config-renderer*
       • {decorators}?              (`(string|nvim_tree.api.decorator.UserDecorator)[]`)
                                    (default:
                                    `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`)
-      • {highlight_git}?           (`nvim_tree.config.renderer.Highlight`)
+      • {highlight_git}?           (`nvim_tree.config.renderer.highlight`)
                                    (default: `"none"`)
-      • {highlight_opened_files}?  (`nvim_tree.config.renderer.Highlight`)
+      • {highlight_opened_files}?  (`nvim_tree.config.renderer.highlight`)
                                    (default: `"none"`)
-      • {highlight_hidden}?        (`nvim_tree.config.renderer.Highlight`)
+      • {highlight_hidden}?        (`nvim_tree.config.renderer.highlight`)
                                    (default: `"none"`)
-      • {highlight_modified}?      (`nvim_tree.config.renderer.Highlight`)
+      • {highlight_modified}?      (`nvim_tree.config.renderer.highlight`)
                                    (default: `"none"`)
-      • {highlight_bookmarks}?     (`nvim_tree.config.renderer.Highlight`)
+      • {highlight_bookmarks}?     (`nvim_tree.config.renderer.highlight`)
                                    (default: `"none"`)
-      • {highlight_diagnostics}?   (`nvim_tree.config.renderer.Highlight`)
+      • {highlight_diagnostics}?   (`nvim_tree.config.renderer.highlight`)
                                    (default: `"none"`)
-      • {highlight_clipboard}?     (`nvim_tree.config.renderer.Highlight`)
+      • {highlight_clipboard}?     (`nvim_tree.config.renderer.highlight`)
                                    (default: `"name"`)
       • {special_files}?           (`string[]`, default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }`)
                                    Highlight special files and directories
@@ -2425,15 +2426,15 @@ Class: Config.Renderer                             *nvim-tree-config-renderer*
     See |nvim-tree-icons-highlighting| for: {_placement} fields.
 
     Fields: ~
-      • {git_placement}?          (`nvim_tree.config.renderer.icons.Placement`)
+      • {git_placement}?          (`nvim_tree.config.renderer.icons.placement`)
                                   (default: `before`)
-      • {hidden_placement}?       (`nvim_tree.config.renderer.icons.Placement`)
+      • {hidden_placement}?       (`nvim_tree.config.renderer.icons.placement`)
                                   (default: `after`)
-      • {modified_placement}?     (`nvim_tree.config.renderer.icons.Placement`)
+      • {modified_placement}?     (`nvim_tree.config.renderer.icons.placement`)
                                   (default: `after`)
-      • {bookmarks_placement}?    (`nvim_tree.config.renderer.icons.Placement`)
+      • {bookmarks_placement}?    (`nvim_tree.config.renderer.icons.placement`)
                                   (default: `signcolumn`)
-      • {diagnostics_placement}?  (`nvim_tree.config.renderer.icons.Placement`)
+      • {diagnostics_placement}?  (`nvim_tree.config.renderer.icons.placement`)
                                   (default: `signcolumn`)
       • {padding}?                (`table`)
                                      *nvim_tree.config.renderer.icons.padding*
@@ -2989,15 +2990,9 @@ Class: Config.Bookmarks                           *nvim-tree-config-bookmarks*
 Class: Config.Help                                     *nvim-tree-config-help*
 
 *nvim_tree.config.help*
-    Configure help window, default mapping `g?`
-
-                                                *nvim_tree.config.help.SortBy*
-    • `"key"`: alphabetically by keymap
-    • `"desc"`: alphabetically by description
 
     Fields: ~
-      • {sort_by}?  (`nvim_tree.config.help.SortBy`, default: `"key"`)
-                    |nvim_tree.config.help.SortBy|
+      • {sort_by}?  (`"key"|"desc"`, default: `"key"`) Alphabetically.
 
 
 
diff --git a/lua/nvim-tree/_meta/config/help.lua b/lua/nvim-tree/_meta/config/help.lua
index 00bfcdcf926..b47a10e628e 100644
--- a/lua/nvim-tree/_meta/config/help.lua
+++ b/lua/nvim-tree/_meta/config/help.lua
@@ -3,18 +3,9 @@ error("Cannot require a meta file")
 
 
 
----@alias nvim_tree.config.help.SortBy "key"|"desc"
-
-
-
----Configure help window, default mapping `g?`
----
----[nvim_tree.config.help.SortBy]()
----- `"key"`: alphabetically by keymap
----- `"desc"`: alphabetically by description
 ---
 ---@class nvim_tree.config.help
 ---
----[nvim_tree.config.help.SortBy]
+---Alphabetically.
 ---(default: `"key"`)
----@field sort_by? nvim_tree.config.help.SortBy
+---@field sort_by? "key"|"desc"
diff --git a/lua/nvim-tree/_meta/config/renderer.lua b/lua/nvim-tree/_meta/config/renderer.lua
index dc17823a1d8..114a96d53a5 100644
--- a/lua/nvim-tree/_meta/config/renderer.lua
+++ b/lua/nvim-tree/_meta/config/renderer.lua
@@ -3,11 +3,11 @@ error("Cannot require a meta file")
 
 
 
----@alias nvim_tree.config.renderer.Highlight "none"|"icon"|"name"|"all"
+---@alias nvim_tree.config.renderer.highlight "none"|"icon"|"name"|"all"
 
----@alias nvim_tree.config.renderer.HiddenDisplay "none"|"simple"|"all"|(fun(hidden_stats: table): string)
+---@alias nvim_tree.config.renderer.hidden_display "none"|"simple"|"all"|(fun(hidden_stats: table): string)
 
----@alias nvim_tree.config.renderer.icons.Placement "before"|"after"|"signcolumn"|"right_align"
+---@alias nvim_tree.config.renderer.icons.placement "before"|"after"|"signcolumn"|"right_align"
 
 
 
@@ -47,7 +47,7 @@ error("Cannot require a meta file")
 ---
 ---[nvim-tree-hidden-display]
 ---(default: `none`)
----@field hidden_display? nvim_tree.config.renderer.HiddenDisplay
+---@field hidden_display? nvim_tree.config.renderer.hidden_display
 ---
 ---Appends an arrow followed by the target of the symlink.
 ---(default: `true`)
@@ -57,25 +57,25 @@ error("Cannot require a meta file")
 ---@field decorators? (string|nvim_tree.api.decorator.UserDecorator)[]
 ---
 ---(default: `"none"`)
----@field highlight_git? nvim_tree.config.renderer.Highlight
+---@field highlight_git? nvim_tree.config.renderer.highlight
 ---
 ---(default: `"none"`)
----@field highlight_opened_files? nvim_tree.config.renderer.Highlight
+---@field highlight_opened_files? nvim_tree.config.renderer.highlight
 ---
 ---(default: `"none"`)
----@field highlight_hidden? nvim_tree.config.renderer.Highlight
+---@field highlight_hidden? nvim_tree.config.renderer.highlight
 ---
 ---(default: `"none"`)
----@field highlight_modified? nvim_tree.config.renderer.Highlight
+---@field highlight_modified? nvim_tree.config.renderer.highlight
 ---
 ---(default: `"none"`)
----@field highlight_bookmarks? nvim_tree.config.renderer.Highlight
+---@field highlight_bookmarks? nvim_tree.config.renderer.highlight
 ---
 ---(default: `"none"`)
----@field highlight_diagnostics? nvim_tree.config.renderer.Highlight
+---@field highlight_diagnostics? nvim_tree.config.renderer.highlight
 ---
 ---(default: `"name"`)
----@field highlight_clipboard? nvim_tree.config.renderer.Highlight
+---@field highlight_clipboard? nvim_tree.config.renderer.highlight
 ---
 ---Highlight special files and directories with `NvimTreeSpecial*`.
 ---(default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }`)
@@ -127,19 +127,19 @@ error("Cannot require a meta file")
 ---@class nvim_tree.config.renderer.icons
 ---
 ---(default: `before`)
----@field git_placement? nvim_tree.config.renderer.icons.Placement
+---@field git_placement? nvim_tree.config.renderer.icons.placement
 ---
 ---(default: `after`)
----@field hidden_placement? nvim_tree.config.renderer.icons.Placement
+---@field hidden_placement? nvim_tree.config.renderer.icons.placement
 ---
 ---(default: `after`)
----@field modified_placement? nvim_tree.config.renderer.icons.Placement
+---@field modified_placement? nvim_tree.config.renderer.icons.placement
 ---
 ---(default: `signcolumn`)
----@field bookmarks_placement? nvim_tree.config.renderer.icons.Placement
+---@field bookmarks_placement? nvim_tree.config.renderer.icons.placement
 ---
 ---(default: `signcolumn`)
----@field diagnostics_placement? nvim_tree.config.renderer.icons.Placement
+---@field diagnostics_placement? nvim_tree.config.renderer.icons.placement
 ---
 ---@field padding? nvim_tree.config.renderer.icons.padding
 ---
diff --git a/lua/nvim-tree/_meta/config/view.lua b/lua/nvim-tree/_meta/config/view.lua
index cede4837ba5..b526262a50d 100644
--- a/lua/nvim-tree/_meta/config/view.lua
+++ b/lua/nvim-tree/_meta/config/view.lua
@@ -3,7 +3,7 @@ error("Cannot require a meta file")
 
 
 
----@alias nvim_tree.config.view.widthSpec string|integer|(fun(): integer|string)
+---@alias nvim_tree.config.view.width.spec string|integer|(fun(): integer|string)
 
 
 
@@ -11,9 +11,9 @@ error("Cannot require a meta file")
 ---
 ---The window is "docked" at the left by default, however may be configured to float: [nvim_tree.config.view.float]
 ---
----{width} can be a [nvim_tree.config.view.widthSpec] for simple static control or a [nvim_tree.config.view.width] for fully dynamic control based on longest line.
+---{width} can be a [nvim_tree.config.view.width.spec] for static control or a [nvim_tree.config.view.width] for fully dynamic control based on longest line.
 ---
----[nvim_tree.config.view.widthSpec]()
+---[nvim_tree.config.view.width.spec]()
 ---- `string`: `x%` string e.g. `30%`
 ---- `integer`: number of columns
 ---- `function`: returns one of the above
@@ -56,7 +56,7 @@ error("Cannot require a meta file")
 ---@field signcolumn? "yes"|"auto"|"no"
 ---
 ---(default: `30`)
----@field width? nvim_tree.config.view.widthSpec|nvim_tree.config.view.width
+---@field width? nvim_tree.config.view.width.spec|nvim_tree.config.view.width
 ---
 ---[nvim_tree.config.view.float]
 ---@field float? nvim_tree.config.view.float
@@ -68,11 +68,11 @@ error("Cannot require a meta file")
 ---@class nvim_tree.config.view.width
 ---
 ---(default: `30`)
----@field min? nvim_tree.config.view.widthSpec
+---@field min? nvim_tree.config.view.width.spec
 ---
 ----1 for unbounded.
 ---(default: `-1`)
----@field max? nvim_tree.config.view.widthSpec
+---@field max? nvim_tree.config.view.width.spec
 ---
 ---Exclude these lines when computing width.
 ---(default: `{ "root" }`)
@@ -80,7 +80,7 @@ error("Cannot require a meta file")
 ---
 ---Extra padding to the right.
 ---(default: `1`)
----@field padding? nvim_tree.config.view.widthSpec
+---@field padding? nvim_tree.config.view.width.spec
 
 
 

From c11308ba728b2890328544f65a4002e685eaf2de Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Wed, 21 Jan 2026 10:34:21 +1100
Subject: [PATCH 117/170] docs(#2934): note help tag prefixes

---
 doc/nvim-tree-lua.txt | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index a63e25ebb70..16c8cf8ee03 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -2,6 +2,12 @@
 
 Author: Yazdani Kiyan
                                        Type |gO| to see the table of contents.
+Help tag prefixes:
+• `nvim-tree-`  Help Sections e.g.
+  • |nvim-tree-mappings|
+  • |nvim-tree-config|
+• `nvim_tree.`  API and classes e.g.
+  • |nvim_tree.config.filesystem_watchers|
 
 ==============================================================================
 Introduction                                          *nvim-tree-introduction*

From eb9f27def4f9eb35e4b46518e172ff45cc6d41ec Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Wed, 21 Jan 2026 11:20:34 +1100
Subject: [PATCH 118/170] docs(#2934): snake case config sections

---
 doc/nvim-tree-lua.txt         | 44 +++++++++++++++++------------------
 scripts/gen_vimdoc_config.lua | 44 +++++++++++++++++------------------
 2 files changed, 44 insertions(+), 44 deletions(-)

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 16c8cf8ee03..056ce6fc4a6 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -2116,7 +2116,7 @@ Example of function that can be passed: >lua
 <
 
 ==============================================================================
-Class: Config                                               *nvim-tree-config*
+class: config                                               *nvim-tree-config*
 
 *nvim_tree.config*
     Arguments to pass to |nvim-tree-setup|.
@@ -2236,7 +2236,7 @@ Class: Config                                               *nvim-tree-config*
 
 
 ==============================================================================
-Class: Config.Sort                                     *nvim-tree-config-sort*
+class: config.sort                                     *nvim-tree-config-sort*
 
 *nvim_tree.config.sort*
     Sort files within a directory.
@@ -2276,7 +2276,7 @@ Class: Config.Sort                                     *nvim-tree-config-sort*
 
 
 ==============================================================================
-Class: Config.View                                     *nvim-tree-config-view*
+class: config.view                                     *nvim-tree-config-view*
 
 *nvim_tree.config.view*
     Configures the dimensions and appearance of the nvim-tree window.
@@ -2362,7 +2362,7 @@ Class: Config.View                                     *nvim-tree-config-view*
 
 
 ==============================================================================
-Class: Config.Renderer                             *nvim-tree-config-renderer*
+class: config.renderer                             *nvim-tree-config-renderer*
 
 *nvim_tree.config.renderer*
     Controls the appearance of the tree.
@@ -2538,7 +2538,7 @@ Class: Config.Renderer                             *nvim-tree-config-renderer*
 
 
 ==============================================================================
-Class: Config.HijackDirectories          *nvim-tree-config-hijack-directories*
+class: config.hijack_directories         *nvim-tree-config-hijack-directories*
 
 *nvim_tree.config.hijack_directories*
     Hijack directory buffers by replacing the directory buffer with the tree.
@@ -2556,7 +2556,7 @@ Class: Config.HijackDirectories          *nvim-tree-config-hijack-directories*
 
 
 ==============================================================================
-Class: Config.UpdateFocusedFile         *nvim-tree-config-update-focused-file*
+class: config.update_focused_file       *nvim-tree-config-update-focused-file*
 
 *nvim_tree.config.update_focused_file*
     Update the focused file on |BufEnter|, uncollapsing folders recursively.
@@ -2588,7 +2588,7 @@ Class: Config.UpdateFocusedFile         *nvim-tree-config-update-focused-file*
 
 
 ==============================================================================
-Class: Config.SystemOpen                        *nvim-tree-config-system-open*
+class: config.system_open                       *nvim-tree-config-system-open*
 
 *nvim_tree.config.system_open*
     Open files or directories via the OS.
@@ -2612,7 +2612,7 @@ Class: Config.SystemOpen                        *nvim-tree-config-system-open*
 
 
 ==============================================================================
-Class: Config.Git                                       *nvim-tree-config-git*
+class: config.git                                       *nvim-tree-config-git*
 
 *nvim_tree.config.git*
     Git operations are run in the background thus status may not immediately
@@ -2646,7 +2646,7 @@ Class: Config.Git                                       *nvim-tree-config-git*
 
 
 ==============================================================================
-Class: Config.Diagnostics                       *nvim-tree-config-diagnostics*
+class: config.diagnostics                       *nvim-tree-config-diagnostics*
 
 *nvim_tree.config.diagnostics*
     Integrate with |lsp| or COC diagnostics.
@@ -2680,7 +2680,7 @@ Class: Config.Diagnostics                       *nvim-tree-config-diagnostics*
 
 
 ==============================================================================
-Class: Config.Modified                             *nvim-tree-config-modified*
+class: config.modified                             *nvim-tree-config-modified*
 
 *nvim_tree.config.modified*
     Indicate which files have unsaved modification. To see modified status in
@@ -2702,7 +2702,7 @@ Class: Config.Modified                             *nvim-tree-config-modified*
 
 
 ==============================================================================
-Class: Config.Filters                               *nvim-tree-config-filters*
+class: config.filters                               *nvim-tree-config-filters*
 
 *nvim_tree.config.filters*
     Filters may be applied to the tree to exlude the display of
@@ -2757,7 +2757,7 @@ Class: Config.Filters                               *nvim-tree-config-filters*
 
 
 ==============================================================================
-Class: Config.LiveFilter                        *nvim-tree-config-live-filter*
+class: config.live_filter                       *nvim-tree-config-live-filter*
 
 *nvim_tree.config.live_filter*
     Live filter allows you to filter the tree nodes dynamically, based on
@@ -2775,7 +2775,7 @@ Class: Config.LiveFilter                        *nvim-tree-config-live-filter*
 
 
 ==============================================================================
-Class: Config.FilesystemWatchers        *nvim-tree-config-filesystem-watchers*
+class: config.filesystem_watchers       *nvim-tree-config-filesystem-watchers*
 
 *nvim_tree.config.filesystem_watchers*
     Use file system watchers (libuv `uv_fs_event_t`) to monitor the filesystem
@@ -2801,7 +2801,7 @@ Class: Config.FilesystemWatchers        *nvim-tree-config-filesystem-watchers*
 
 
 ==============================================================================
-Class: Config.Actions                               *nvim-tree-config-actions*
+class: config.actions                               *nvim-tree-config-actions*
 
 *nvim_tree.config.actions*
 
@@ -2924,7 +2924,7 @@ Class: Config.Actions                               *nvim-tree-config-actions*
 
 
 ==============================================================================
-Class: Config.Trash                                   *nvim-tree-config-trash*
+class: config.trash                                   *nvim-tree-config-trash*
 
 *nvim_tree.config.trash*
     Files may be trashed via an external command that must be installed on
@@ -2939,7 +2939,7 @@ Class: Config.Trash                                   *nvim-tree-config-trash*
 
 
 ==============================================================================
-Class: Config.Tab                                       *nvim-tree-config-tab*
+class: config.tab                                       *nvim-tree-config-tab*
 
 *nvim_tree.config.tab*
 
@@ -2960,7 +2960,7 @@ Class: Config.Tab                                       *nvim-tree-config-tab*
 
 
 ==============================================================================
-Class: Config.Notify                                 *nvim-tree-config-notify*
+class: config.notify                                 *nvim-tree-config-notify*
 
 *nvim_tree.config.notify*
     nvim-tree |vim.log.levels|
@@ -2979,7 +2979,7 @@ Class: Config.Notify                                 *nvim-tree-config-notify*
 
 
 ==============================================================================
-Class: Config.Bookmarks                           *nvim-tree-config-bookmarks*
+class: config.bookmarks                           *nvim-tree-config-bookmarks*
 
 *nvim_tree.config.bookmarks*
     Optionally {persist} bookmarks to a json file:
@@ -2993,7 +2993,7 @@ Class: Config.Bookmarks                           *nvim-tree-config-bookmarks*
 
 
 ==============================================================================
-Class: Config.Help                                     *nvim-tree-config-help*
+class: config.help                                     *nvim-tree-config-help*
 
 *nvim_tree.config.help*
 
@@ -3003,7 +3003,7 @@ Class: Config.Help                                     *nvim-tree-config-help*
 
 
 ==============================================================================
-Class: Config.UI                                         *nvim-tree-config-ui*
+class: config.ui                                         *nvim-tree-config-ui*
 
 *nvim_tree.config.ui*
 
@@ -3023,7 +3023,7 @@ Class: Config.UI                                         *nvim-tree-config-ui*
 
 
 ==============================================================================
-Class: Config.Experimental                     *nvim-tree-config-experimental*
+class: config.experimental                     *nvim-tree-config-experimental*
 
 *nvim_tree.config.experimental*
     Experimental features that may become default or optional functionality.
@@ -3034,7 +3034,7 @@ Class: Config.Experimental                     *nvim-tree-config-experimental*
 
 
 ==============================================================================
-Class: Config.Log                                       *nvim-tree-config-log*
+class: config.log                                       *nvim-tree-config-log*
 
 *nvim_tree.config.log*
     Log to a file `nvim-tree.log` in |stdpath()| `log`, usually
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index bfdedd23213..a059932dfcb 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -8,28 +8,28 @@
 ---Help txt is deleted from first tag down and generated content is appended.
 ---@type Src[]
 local srcs = {
-  { helptag = "nvim-tree-config",                     section = "Class: Config",                    path = "./lua/nvim_tree/_meta/config.lua", },
-  { helptag = "nvim-tree-config-sort",                section = "Class: Config.Sort",               path = "./lua/nvim_tree/_meta/config/sort.lua", },
-  { helptag = "nvim-tree-config-view",                section = "Class: Config.View",               path = "./lua/nvim_tree/_meta/config/view.lua", },
-  { helptag = "nvim-tree-config-renderer",            section = "Class: Config.Renderer",           path = "./lua/nvim_tree/_meta/config/renderer.lua", },
-  { helptag = "nvim-tree-config-hijack-directories",  section = "Class: Config.HijackDirectories",  path = "./lua/nvim_tree/_meta/config/hijack_directories.lua", },
-  { helptag = "nvim-tree-config-update-focused-file", section = "Class: Config.UpdateFocusedFile",  path = "./lua/nvim_tree/_meta/config/update_focused_file.lua", },
-  { helptag = "nvim-tree-config-system-open",         section = "Class: Config.SystemOpen",         path = "./lua/nvim_tree/_meta/config/system_open.lua", },
-  { helptag = "nvim-tree-config-git",                 section = "Class: Config.Git",                path = "./lua/nvim_tree/_meta/config/git.lua", },
-  { helptag = "nvim-tree-config-diagnostics",         section = "Class: Config.Diagnostics",        path = "./lua/nvim_tree/_meta/config/diagnostics.lua", },
-  { helptag = "nvim-tree-config-modified",            section = "Class: Config.Modified",           path = "./lua/nvim_tree/_meta/config/modified.lua", },
-  { helptag = "nvim-tree-config-filters",             section = "Class: Config.Filters",            path = "./lua/nvim_tree/_meta/config/filters.lua", },
-  { helptag = "nvim-tree-config-live-filter",         section = "Class: Config.LiveFilter",         path = "./lua/nvim_tree/_meta/config/live_filter.lua", },
-  { helptag = "nvim-tree-config-filesystem-watchers", section = "Class: Config.FilesystemWatchers", path = "./lua/nvim_tree/_meta/config/filesystem_watchers.lua", },
-  { helptag = "nvim-tree-config-actions",             section = "Class: Config.Actions",            path = "./lua/nvim_tree/_meta/config/actions.lua", },
-  { helptag = "nvim-tree-config-trash",               section = "Class: Config.Trash",              path = "./lua/nvim_tree/_meta/config/trash.lua", },
-  { helptag = "nvim-tree-config-tab",                 section = "Class: Config.Tab",                path = "./lua/nvim_tree/_meta/config/tab.lua", },
-  { helptag = "nvim-tree-config-notify",              section = "Class: Config.Notify",             path = "./lua/nvim_tree/_meta/config/notify.lua", },
-  { helptag = "nvim-tree-config-bookmarks",           section = "Class: Config.Bookmarks",          path = "./lua/nvim_tree/_meta/config/bookmarks.lua", },
-  { helptag = "nvim-tree-config-help",                section = "Class: Config.Help",               path = "./lua/nvim_tree/_meta/config/help.lua", },
-  { helptag = "nvim-tree-config-ui",                  section = "Class: Config.UI",                 path = "./lua/nvim_tree/_meta/config/ui.lua",                  name = "UI", },
-  { helptag = "nvim-tree-config-experimental",        section = "Class: Config.Experimental",       path = "./lua/nvim_tree/_meta/config/experimental.lua", },
-  { helptag = "nvim-tree-config-log",                 section = "Class: Config.Log",                path = "./lua/nvim_tree/_meta/config/log.lua", },
+  { helptag = "nvim-tree-config",                     section = "class: config",                     path = "./lua/nvim_tree/_meta/config.lua", },
+  { helptag = "nvim-tree-config-sort",                section = "class: config.sort",                path = "./lua/nvim_tree/_meta/config/sort.lua", },
+  { helptag = "nvim-tree-config-view",                section = "class: config.view",                path = "./lua/nvim_tree/_meta/config/view.lua", },
+  { helptag = "nvim-tree-config-renderer",            section = "class: config.renderer",            path = "./lua/nvim_tree/_meta/config/renderer.lua", },
+  { helptag = "nvim-tree-config-hijack-directories",  section = "class: config.hijack_directories",  path = "./lua/nvim_tree/_meta/config/hijack_directories.lua", },
+  { helptag = "nvim-tree-config-update-focused-file", section = "class: config.update_focused_file", path = "./lua/nvim_tree/_meta/config/update_focused_file.lua", },
+  { helptag = "nvim-tree-config-system-open",         section = "class: config.system_open",         path = "./lua/nvim_tree/_meta/config/system_open.lua", },
+  { helptag = "nvim-tree-config-git",                 section = "class: config.git",                 path = "./lua/nvim_tree/_meta/config/git.lua", },
+  { helptag = "nvim-tree-config-diagnostics",         section = "class: config.diagnostics",         path = "./lua/nvim_tree/_meta/config/diagnostics.lua", },
+  { helptag = "nvim-tree-config-modified",            section = "class: config.modified",            path = "./lua/nvim_tree/_meta/config/modified.lua", },
+  { helptag = "nvim-tree-config-filters",             section = "class: config.filters",             path = "./lua/nvim_tree/_meta/config/filters.lua", },
+  { helptag = "nvim-tree-config-live-filter",         section = "class: config.live_filter",         path = "./lua/nvim_tree/_meta/config/live_filter.lua", },
+  { helptag = "nvim-tree-config-filesystem-watchers", section = "class: config.filesystem_watchers", path = "./lua/nvim_tree/_meta/config/filesystem_watchers.lua", },
+  { helptag = "nvim-tree-config-actions",             section = "class: config.actions",             path = "./lua/nvim_tree/_meta/config/actions.lua", },
+  { helptag = "nvim-tree-config-trash",               section = "class: config.trash",               path = "./lua/nvim_tree/_meta/config/trash.lua", },
+  { helptag = "nvim-tree-config-tab",                 section = "class: config.tab",                 path = "./lua/nvim_tree/_meta/config/tab.lua", },
+  { helptag = "nvim-tree-config-notify",              section = "class: config.notify",              path = "./lua/nvim_tree/_meta/config/notify.lua", },
+  { helptag = "nvim-tree-config-bookmarks",           section = "class: config.bookmarks",           path = "./lua/nvim_tree/_meta/config/bookmarks.lua", },
+  { helptag = "nvim-tree-config-help",                section = "class: config.help",                path = "./lua/nvim_tree/_meta/config/help.lua", },
+  { helptag = "nvim-tree-config-ui",                  section = "class: config.ui",                  path = "./lua/nvim_tree/_meta/config/ui.lua",                  name = "UI", },
+  { helptag = "nvim-tree-config-experimental",        section = "class: config.experimental",        path = "./lua/nvim_tree/_meta/config/experimental.lua", },
+  { helptag = "nvim-tree-config-log",                 section = "class: config.log",                 path = "./lua/nvim_tree/_meta/config/log.lua", },
 }
 
 -- hydrate file names

From 411e3af573483bdcb2ecce68356604414340ac63 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Wed, 21 Jan 2026 12:37:31 +1100
Subject: [PATCH 119/170] docs(#2934): move default config to end

---
 CONTRIBUTING.md                        |   4 +-
 Makefile                               |   2 +-
 doc/nvim-tree-lua.txt                  | 625 +++++++++++++------------
 lua/nvim-tree.lua                      |   4 +-
 lua/nvim-tree/_meta/config/default.lua |  11 +
 scripts/gen_vimdoc_config.lua          |  50 +-
 scripts/help-update.sh                 |  18 +-
 7 files changed, 371 insertions(+), 343 deletions(-)
 create mode 100644 lua/nvim-tree/_meta/config/default.lua

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 50bff754ea3..337b540ee6f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -126,8 +126,8 @@ end
 ## Config And Mappings
 
 When adding to or changing:
-1. `DEFAULT_OPTS`
-2. `Config` classes
+1. Default config
+2. `config` classes
 3. `on_attach` default mappings
 
 You must generate help documentation. This requires neovim stable sources. You will be promted with instructions on fetching and referencing the source.
diff --git a/Makefile b/Makefile
index 9b3b00cc71a..187dce385c0 100644
--- a/Makefile
+++ b/Makefile
@@ -35,8 +35,8 @@ style-fix:
 # utility
 #
 help-update:
-	scripts/help-update.sh
 	scripts/gen_vimdoc.sh
+	scripts/help-update.sh
 
 #
 # CI
diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 056ce6fc4a6..2a3e6dc7d8f 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -317,297 +317,16 @@ again to apply a change in configuration without restarting Nvim.
 setup() function takes one optional argument: configuration table. If omitted
 nvim-tree will be initialised with default configuration.
 
+See |nvim-tree-default-config| for the default configuration table.
+
+TODO #2934 move setup call patterns from config to here
+
 The first setup() call is cheap: it does nothing more than validate / apply
 the configuration. Nothing happens until the tree is first opened.
 
 Subsequent setup() calls are expensive as they tear down the world before
 applying configuration.
 
-Following is the default configuration. See |nvim_tree.config| for details. >lua
-
-    require("nvim-tree").setup { -- BEGIN_DEFAULT_OPTS
-      on_attach = "default",
-      hijack_cursor = false,
-      auto_reload_on_write = true,
-      disable_netrw = false,
-      hijack_netrw = true,
-      hijack_unnamed_buffer_when_opening = false,
-      root_dirs = {},
-      prefer_startup_root = false,
-      sync_root_with_cwd = false,
-      reload_on_bufenter = false,
-      respect_buf_cwd = false,
-      select_prompts = false,
-      sort = {
-        sorter = "name",
-        folders_first = true,
-        files_first = false,
-      },
-      view = {
-        centralize_selection = false,
-        cursorline = true,
-        cursorlineopt = "both",
-        debounce_delay = 15,
-        side = "left",
-        preserve_window_proportions = false,
-        number = false,
-        relativenumber = false,
-        signcolumn = "yes",
-        width = 30,
-        float = {
-          enable = false,
-          quit_on_focus_loss = true,
-          open_win_config = {
-            relative = "editor",
-            border = "rounded",
-            width = 30,
-            height = 30,
-            row = 1,
-            col = 1,
-          },
-        },
-      },
-      renderer = {
-        add_trailing = false,
-        group_empty = false,
-        full_name = false,
-        root_folder_label = ":~:s?$?/..?",
-        indent_width = 2,
-        special_files = { "Cargo.toml", "Makefile", "README.md", "readme.md" },
-        hidden_display = "none",
-        symlink_destination = true,
-        decorators = { "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", },
-        highlight_git = "none",
-        highlight_diagnostics = "none",
-        highlight_opened_files = "none",
-        highlight_modified = "none",
-        highlight_hidden = "none",
-        highlight_bookmarks = "none",
-        highlight_clipboard = "name",
-        indent_markers = {
-          enable = false,
-          inline_arrows = true,
-          icons = {
-            corner = "└",
-            edge = "│",
-            item = "│",
-            bottom = "─",
-            none = " ",
-          },
-        },
-        icons = {
-          web_devicons = {
-            file = {
-              enable = true,
-              color = true,
-            },
-            folder = {
-              enable = false,
-              color = true,
-            },
-          },
-          git_placement = "before",
-          modified_placement = "after",
-          hidden_placement = "after",
-          diagnostics_placement = "signcolumn",
-          bookmarks_placement = "signcolumn",
-          padding = {
-            icon = " ",
-            folder_arrow = " ",
-          },
-          symlink_arrow = " ➛ ",
-          show = {
-            file = true,
-            folder = true,
-            folder_arrow = true,
-            git = true,
-            modified = true,
-            hidden = false,
-            diagnostics = true,
-            bookmarks = true,
-          },
-          glyphs = {
-            default = "",
-            symlink = "",
-            bookmark = "󰆤",
-            modified = "●",
-            hidden = "󰜌",
-            folder = {
-              arrow_closed = "",
-              arrow_open = "",
-              default = "",
-              open = "",
-              empty = "",
-              empty_open = "",
-              symlink = "",
-              symlink_open = "",
-            },
-            git = {
-              unstaged = "✗",
-              staged = "✓",
-              unmerged = "",
-              renamed = "➜",
-              untracked = "★",
-              deleted = "",
-              ignored = "◌",
-            },
-          },
-        },
-      },
-      hijack_directories = {
-        enable = true,
-        auto_open = true,
-      },
-      update_focused_file = {
-        enable = false,
-        update_root = {
-          enable = false,
-          ignore_list = {},
-        },
-        exclude = false,
-      },
-      system_open = {
-        cmd = "",
-        args = {},
-      },
-      git = {
-        enable = true,
-        show_on_dirs = true,
-        show_on_open_dirs = true,
-        disable_for_dirs = {},
-        timeout = 400,
-        cygwin_support = false,
-      },
-      diagnostics = {
-        enable = false,
-        show_on_dirs = false,
-        show_on_open_dirs = true,
-        debounce_delay = 500,
-        severity = {
-          min = vim.diagnostic.severity.HINT,
-          max = vim.diagnostic.severity.ERROR,
-        },
-        icons = {
-          hint = "",
-          info = "",
-          warning = "",
-          error = "",
-        },
-        diagnostic_opts = false,
-      },
-      modified = {
-        enable = false,
-        show_on_dirs = true,
-        show_on_open_dirs = true,
-      },
-      filters = {
-        enable = true,
-        git_ignored = true,
-        dotfiles = false,
-        git_clean = false,
-        no_buffer = false,
-        no_bookmark = false,
-        custom = {},
-        exclude = {},
-      },
-      live_filter = {
-        prefix = "[FILTER]: ",
-        always_show_folders = true,
-      },
-      filesystem_watchers = {
-        enable = true,
-        debounce_delay = 50,
-        ignore_dirs = {
-          "/.ccls-cache",
-          "/build",
-          "/node_modules",
-          "/target",
-        },
-      },
-      actions = {
-        use_system_clipboard = true,
-        change_dir = {
-          enable = true,
-          global = false,
-          restrict_above_cwd = false,
-        },
-        expand_all = {
-          max_folder_discovery = 300,
-          exclude = {},
-        },
-        file_popup = {
-          open_win_config = {
-            col = 1,
-            row = 1,
-            relative = "cursor",
-            border = "shadow",
-            style = "minimal",
-          },
-        },
-        open_file = {
-          quit_on_open = false,
-          eject = true,
-          resize_window = true,
-          relative_path = true,
-          window_picker = {
-            enable = true,
-            picker = "default",
-            chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
-            exclude = {
-              filetype = { "notify", "packer", "qf", "diff", "fugitive", "fugitiveblame" },
-              buftype = { "nofile", "terminal", "help" },
-            },
-          },
-        },
-        remove_file = {
-          close_window = true,
-        },
-      },
-      trash = {
-        cmd = "gio trash",
-      },
-      tab = {
-        sync = {
-          open = false,
-          close = false,
-          ignore = {},
-        },
-      },
-      notify = {
-        threshold = vim.log.levels.INFO,
-        absolute_path = true,
-      },
-      help = {
-        sort_by = "key",
-      },
-      ui = {
-        confirm = {
-          remove = true,
-          trash = true,
-          default_yes = false,
-        },
-      },
-      bookmarks = {
-        persist = false,
-      },
-      experimental = {
-      },
-      log = {
-        enable = false,
-        truncate = false,
-        types = {
-          all = false,
-          config = false,
-          copy_paste = false,
-          dev = false,
-          diagnostics = false,
-          git = false,
-          profile = false,
-          watcher = false,
-        },
-      },
-    } -- END_DEFAULT_OPTS
-<
 
 ==============================================================================
 API                                                            *nvim-tree-api*
@@ -2116,7 +1835,7 @@ Example of function that can be passed: >lua
 <
 
 ==============================================================================
-class: config                                               *nvim-tree-config*
+Class: config                                               *nvim-tree-config*
 
 *nvim_tree.config*
     Arguments to pass to |nvim-tree-setup|.
@@ -2236,7 +1955,7 @@ class: config                                               *nvim-tree-config*
 
 
 ==============================================================================
-class: config.sort                                     *nvim-tree-config-sort*
+Class: config.sort                                     *nvim-tree-config-sort*
 
 *nvim_tree.config.sort*
     Sort files within a directory.
@@ -2276,7 +1995,7 @@ class: config.sort                                     *nvim-tree-config-sort*
 
 
 ==============================================================================
-class: config.view                                     *nvim-tree-config-view*
+Class: config.view                                     *nvim-tree-config-view*
 
 *nvim_tree.config.view*
     Configures the dimensions and appearance of the nvim-tree window.
@@ -2362,7 +2081,7 @@ class: config.view                                     *nvim-tree-config-view*
 
 
 ==============================================================================
-class: config.renderer                             *nvim-tree-config-renderer*
+Class: config.renderer                             *nvim-tree-config-renderer*
 
 *nvim_tree.config.renderer*
     Controls the appearance of the tree.
@@ -2538,7 +2257,7 @@ class: config.renderer                             *nvim-tree-config-renderer*
 
 
 ==============================================================================
-class: config.hijack_directories         *nvim-tree-config-hijack-directories*
+Class: config.hijack_directories         *nvim-tree-config-hijack-directories*
 
 *nvim_tree.config.hijack_directories*
     Hijack directory buffers by replacing the directory buffer with the tree.
@@ -2556,7 +2275,7 @@ class: config.hijack_directories         *nvim-tree-config-hijack-directories*
 
 
 ==============================================================================
-class: config.update_focused_file       *nvim-tree-config-update-focused-file*
+Class: config.update_focused_file       *nvim-tree-config-update-focused-file*
 
 *nvim_tree.config.update_focused_file*
     Update the focused file on |BufEnter|, uncollapsing folders recursively.
@@ -2588,7 +2307,7 @@ class: config.update_focused_file       *nvim-tree-config-update-focused-file*
 
 
 ==============================================================================
-class: config.system_open                       *nvim-tree-config-system-open*
+Class: config.system_open                       *nvim-tree-config-system-open*
 
 *nvim_tree.config.system_open*
     Open files or directories via the OS.
@@ -2612,7 +2331,7 @@ class: config.system_open                       *nvim-tree-config-system-open*
 
 
 ==============================================================================
-class: config.git                                       *nvim-tree-config-git*
+Class: config.git                                       *nvim-tree-config-git*
 
 *nvim_tree.config.git*
     Git operations are run in the background thus status may not immediately
@@ -2646,7 +2365,7 @@ class: config.git                                       *nvim-tree-config-git*
 
 
 ==============================================================================
-class: config.diagnostics                       *nvim-tree-config-diagnostics*
+Class: config.diagnostics                       *nvim-tree-config-diagnostics*
 
 *nvim_tree.config.diagnostics*
     Integrate with |lsp| or COC diagnostics.
@@ -2680,7 +2399,7 @@ class: config.diagnostics                       *nvim-tree-config-diagnostics*
 
 
 ==============================================================================
-class: config.modified                             *nvim-tree-config-modified*
+Class: config.modified                             *nvim-tree-config-modified*
 
 *nvim_tree.config.modified*
     Indicate which files have unsaved modification. To see modified status in
@@ -2702,7 +2421,7 @@ class: config.modified                             *nvim-tree-config-modified*
 
 
 ==============================================================================
-class: config.filters                               *nvim-tree-config-filters*
+Class: config.filters                               *nvim-tree-config-filters*
 
 *nvim_tree.config.filters*
     Filters may be applied to the tree to exlude the display of
@@ -2757,7 +2476,7 @@ class: config.filters                               *nvim-tree-config-filters*
 
 
 ==============================================================================
-class: config.live_filter                       *nvim-tree-config-live-filter*
+Class: config.live_filter                       *nvim-tree-config-live-filter*
 
 *nvim_tree.config.live_filter*
     Live filter allows you to filter the tree nodes dynamically, based on
@@ -2775,7 +2494,7 @@ class: config.live_filter                       *nvim-tree-config-live-filter*
 
 
 ==============================================================================
-class: config.filesystem_watchers       *nvim-tree-config-filesystem-watchers*
+Class: config.filesystem_watchers       *nvim-tree-config-filesystem-watchers*
 
 *nvim_tree.config.filesystem_watchers*
     Use file system watchers (libuv `uv_fs_event_t`) to monitor the filesystem
@@ -2801,7 +2520,7 @@ class: config.filesystem_watchers       *nvim-tree-config-filesystem-watchers*
 
 
 ==============================================================================
-class: config.actions                               *nvim-tree-config-actions*
+Class: config.actions                               *nvim-tree-config-actions*
 
 *nvim_tree.config.actions*
 
@@ -2924,7 +2643,7 @@ class: config.actions                               *nvim-tree-config-actions*
 
 
 ==============================================================================
-class: config.trash                                   *nvim-tree-config-trash*
+Class: config.trash                                   *nvim-tree-config-trash*
 
 *nvim_tree.config.trash*
     Files may be trashed via an external command that must be installed on
@@ -2939,7 +2658,7 @@ class: config.trash                                   *nvim-tree-config-trash*
 
 
 ==============================================================================
-class: config.tab                                       *nvim-tree-config-tab*
+Class: config.tab                                       *nvim-tree-config-tab*
 
 *nvim_tree.config.tab*
 
@@ -2960,7 +2679,7 @@ class: config.tab                                       *nvim-tree-config-tab*
 
 
 ==============================================================================
-class: config.notify                                 *nvim-tree-config-notify*
+Class: config.notify                                 *nvim-tree-config-notify*
 
 *nvim_tree.config.notify*
     nvim-tree |vim.log.levels|
@@ -2979,7 +2698,7 @@ class: config.notify                                 *nvim-tree-config-notify*
 
 
 ==============================================================================
-class: config.bookmarks                           *nvim-tree-config-bookmarks*
+Class: config.bookmarks                           *nvim-tree-config-bookmarks*
 
 *nvim_tree.config.bookmarks*
     Optionally {persist} bookmarks to a json file:
@@ -2993,7 +2712,7 @@ class: config.bookmarks                           *nvim-tree-config-bookmarks*
 
 
 ==============================================================================
-class: config.help                                     *nvim-tree-config-help*
+Class: config.help                                     *nvim-tree-config-help*
 
 *nvim_tree.config.help*
 
@@ -3003,7 +2722,7 @@ class: config.help                                     *nvim-tree-config-help*
 
 
 ==============================================================================
-class: config.ui                                         *nvim-tree-config-ui*
+Class: config.ui                                         *nvim-tree-config-ui*
 
 *nvim_tree.config.ui*
 
@@ -3023,7 +2742,7 @@ class: config.ui                                         *nvim-tree-config-ui*
 
 
 ==============================================================================
-class: config.experimental                     *nvim-tree-config-experimental*
+Class: config.experimental                     *nvim-tree-config-experimental*
 
 *nvim_tree.config.experimental*
     Experimental features that may become default or optional functionality.
@@ -3034,7 +2753,7 @@ class: config.experimental                     *nvim-tree-config-experimental*
 
 
 ==============================================================================
-class: config.log                                       *nvim-tree-config-log*
+Class: config.log                                       *nvim-tree-config-log*
 
 *nvim_tree.config.log*
     Log to a file `nvim-tree.log` in |stdpath()| `log`, usually
@@ -3069,4 +2788,296 @@ class: config.log                                       *nvim-tree-config-log*
 
 
 
+==============================================================================
+Config: default                                     *nvim-tree-default-config*
+
+Following is the default configuration, see |nvim_tree.config| for details. >lua
+
+    ---@type nvim_tree.config
+    local config = {
+      on_attach = "default",
+      hijack_cursor = false,
+      auto_reload_on_write = true,
+      disable_netrw = false,
+      hijack_netrw = true,
+      hijack_unnamed_buffer_when_opening = false,
+      root_dirs = {},
+      prefer_startup_root = false,
+      sync_root_with_cwd = false,
+      reload_on_bufenter = false,
+      respect_buf_cwd = false,
+      select_prompts = false,
+      sort = {
+        sorter = "name",
+        folders_first = true,
+        files_first = false,
+      },
+      view = {
+        centralize_selection = false,
+        cursorline = true,
+        cursorlineopt = "both",
+        debounce_delay = 15,
+        side = "left",
+        preserve_window_proportions = false,
+        number = false,
+        relativenumber = false,
+        signcolumn = "yes",
+        width = 30,
+        float = {
+          enable = false,
+          quit_on_focus_loss = true,
+          open_win_config = {
+            relative = "editor",
+            border = "rounded",
+            width = 30,
+            height = 30,
+            row = 1,
+            col = 1,
+          },
+        },
+      },
+      renderer = {
+        add_trailing = false,
+        group_empty = false,
+        full_name = false,
+        root_folder_label = ":~:s?$?/..?",
+        indent_width = 2,
+        special_files = { "Cargo.toml", "Makefile", "README.md", "readme.md" },
+        hidden_display = "none",
+        symlink_destination = true,
+        decorators = { "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", },
+        highlight_git = "none",
+        highlight_diagnostics = "none",
+        highlight_opened_files = "none",
+        highlight_modified = "none",
+        highlight_hidden = "none",
+        highlight_bookmarks = "none",
+        highlight_clipboard = "name",
+        indent_markers = {
+          enable = false,
+          inline_arrows = true,
+          icons = {
+            corner = "└",
+            edge = "│",
+            item = "│",
+            bottom = "─",
+            none = " ",
+          },
+        },
+        icons = {
+          web_devicons = {
+            file = {
+              enable = true,
+              color = true,
+            },
+            folder = {
+              enable = false,
+              color = true,
+            },
+          },
+          git_placement = "before",
+          modified_placement = "after",
+          hidden_placement = "after",
+          diagnostics_placement = "signcolumn",
+          bookmarks_placement = "signcolumn",
+          padding = {
+            icon = " ",
+            folder_arrow = " ",
+          },
+          symlink_arrow = " ➛ ",
+          show = {
+            file = true,
+            folder = true,
+            folder_arrow = true,
+            git = true,
+            modified = true,
+            hidden = false,
+            diagnostics = true,
+            bookmarks = true,
+          },
+          glyphs = {
+            default = "",
+            symlink = "",
+            bookmark = "󰆤",
+            modified = "●",
+            hidden = "󰜌",
+            folder = {
+              arrow_closed = "",
+              arrow_open = "",
+              default = "",
+              open = "",
+              empty = "",
+              empty_open = "",
+              symlink = "",
+              symlink_open = "",
+            },
+            git = {
+              unstaged = "✗",
+              staged = "✓",
+              unmerged = "",
+              renamed = "➜",
+              untracked = "★",
+              deleted = "",
+              ignored = "◌",
+            },
+          },
+        },
+      },
+      hijack_directories = {
+        enable = true,
+        auto_open = true,
+      },
+      update_focused_file = {
+        enable = false,
+        update_root = {
+          enable = false,
+          ignore_list = {},
+        },
+        exclude = false,
+      },
+      system_open = {
+        cmd = "",
+        args = {},
+      },
+      git = {
+        enable = true,
+        show_on_dirs = true,
+        show_on_open_dirs = true,
+        disable_for_dirs = {},
+        timeout = 400,
+        cygwin_support = false,
+      },
+      diagnostics = {
+        enable = false,
+        show_on_dirs = false,
+        show_on_open_dirs = true,
+        debounce_delay = 500,
+        severity = {
+          min = vim.diagnostic.severity.HINT,
+          max = vim.diagnostic.severity.ERROR,
+        },
+        icons = {
+          hint = "",
+          info = "",
+          warning = "",
+          error = "",
+        },
+        diagnostic_opts = false,
+      },
+      modified = {
+        enable = false,
+        show_on_dirs = true,
+        show_on_open_dirs = true,
+      },
+      filters = {
+        enable = true,
+        git_ignored = true,
+        dotfiles = false,
+        git_clean = false,
+        no_buffer = false,
+        no_bookmark = false,
+        custom = {},
+        exclude = {},
+      },
+      live_filter = {
+        prefix = "[FILTER]: ",
+        always_show_folders = true,
+      },
+      filesystem_watchers = {
+        enable = true,
+        debounce_delay = 50,
+        ignore_dirs = {
+          "/.ccls-cache",
+          "/build",
+          "/node_modules",
+          "/target",
+        },
+      },
+      actions = {
+        use_system_clipboard = true,
+        change_dir = {
+          enable = true,
+          global = false,
+          restrict_above_cwd = false,
+        },
+        expand_all = {
+          max_folder_discovery = 300,
+          exclude = {},
+        },
+        file_popup = {
+          open_win_config = {
+            col = 1,
+            row = 1,
+            relative = "cursor",
+            border = "shadow",
+            style = "minimal",
+          },
+        },
+        open_file = {
+          quit_on_open = false,
+          eject = true,
+          resize_window = true,
+          relative_path = true,
+          window_picker = {
+            enable = true,
+            picker = "default",
+            chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
+            exclude = {
+              filetype = { "notify", "packer", "qf", "diff", "fugitive", "fugitiveblame" },
+              buftype = { "nofile", "terminal", "help" },
+            },
+          },
+        },
+        remove_file = {
+          close_window = true,
+        },
+      },
+      trash = {
+        cmd = "gio trash",
+      },
+      tab = {
+        sync = {
+          open = false,
+          close = false,
+          ignore = {},
+        },
+      },
+      notify = {
+        threshold = vim.log.levels.INFO,
+        absolute_path = true,
+      },
+      help = {
+        sort_by = "key",
+      },
+      ui = {
+        confirm = {
+          remove = true,
+          trash = true,
+          default_yes = false,
+        },
+      },
+      bookmarks = {
+        persist = false,
+      },
+      experimental = {
+      },
+      log = {
+        enable = false,
+        truncate = false,
+        types = {
+          all = false,
+          config = false,
+          copy_paste = false,
+          dev = false,
+          diagnostics = false,
+          git = false,
+          profile = false,
+          watcher = false,
+        },
+      },
+    }
+<
+
+
+
  vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:
diff --git a/lua/nvim-tree.lua b/lua/nvim-tree.lua
index fcec5f91b82..b7ab856c0f0 100644
--- a/lua/nvim-tree.lua
+++ b/lua/nvim-tree.lua
@@ -253,7 +253,7 @@ local function setup_autocommands(opts)
 end
 
 ---@type nvim_tree.config
-local DEFAULT_OPTS = { -- BEGIN_DEFAULT_OPTS
+local DEFAULT_OPTS = { -- default-config-start
   on_attach = "default",
   hijack_cursor = false,
   auto_reload_on_write = true,
@@ -534,7 +534,7 @@ local DEFAULT_OPTS = { -- BEGIN_DEFAULT_OPTS
       watcher = false,
     },
   },
-}-- END_DEFAULT_OPTS
+}-- default-config-end
 
 local function merge_options(conf)
   return vim.tbl_deep_extend("force", DEFAULT_OPTS, conf or {})
diff --git a/lua/nvim-tree/_meta/config/default.lua b/lua/nvim-tree/_meta/config/default.lua
new file mode 100644
index 00000000000..1f1252f7483
--- /dev/null
+++ b/lua/nvim-tree/_meta/config/default.lua
@@ -0,0 +1,11 @@
+---@brief
+---Following is the default configuration, see |nvim_tree.config| for details.
+---
+---```lua
+---
+------@type nvim_tree.config
+---local config = {
+---default-config-injection-placeholder
+---}
+---```
+---
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index a059932dfcb..3de0c684c3f 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -1,3 +1,7 @@
+--nvim-tree configuration for Nvim's gen_vimdoc.lua
+--Returned config is injected into the above.
+--See gen_vimdoc.sh
+
 ---@class (exact) Src
 ---@field helptag string must be globally unique
 ---@field section string arbitrary
@@ -8,28 +12,30 @@
 ---Help txt is deleted from first tag down and generated content is appended.
 ---@type Src[]
 local srcs = {
-  { helptag = "nvim-tree-config",                     section = "class: config",                     path = "./lua/nvim_tree/_meta/config.lua", },
-  { helptag = "nvim-tree-config-sort",                section = "class: config.sort",                path = "./lua/nvim_tree/_meta/config/sort.lua", },
-  { helptag = "nvim-tree-config-view",                section = "class: config.view",                path = "./lua/nvim_tree/_meta/config/view.lua", },
-  { helptag = "nvim-tree-config-renderer",            section = "class: config.renderer",            path = "./lua/nvim_tree/_meta/config/renderer.lua", },
-  { helptag = "nvim-tree-config-hijack-directories",  section = "class: config.hijack_directories",  path = "./lua/nvim_tree/_meta/config/hijack_directories.lua", },
-  { helptag = "nvim-tree-config-update-focused-file", section = "class: config.update_focused_file", path = "./lua/nvim_tree/_meta/config/update_focused_file.lua", },
-  { helptag = "nvim-tree-config-system-open",         section = "class: config.system_open",         path = "./lua/nvim_tree/_meta/config/system_open.lua", },
-  { helptag = "nvim-tree-config-git",                 section = "class: config.git",                 path = "./lua/nvim_tree/_meta/config/git.lua", },
-  { helptag = "nvim-tree-config-diagnostics",         section = "class: config.diagnostics",         path = "./lua/nvim_tree/_meta/config/diagnostics.lua", },
-  { helptag = "nvim-tree-config-modified",            section = "class: config.modified",            path = "./lua/nvim_tree/_meta/config/modified.lua", },
-  { helptag = "nvim-tree-config-filters",             section = "class: config.filters",             path = "./lua/nvim_tree/_meta/config/filters.lua", },
-  { helptag = "nvim-tree-config-live-filter",         section = "class: config.live_filter",         path = "./lua/nvim_tree/_meta/config/live_filter.lua", },
-  { helptag = "nvim-tree-config-filesystem-watchers", section = "class: config.filesystem_watchers", path = "./lua/nvim_tree/_meta/config/filesystem_watchers.lua", },
-  { helptag = "nvim-tree-config-actions",             section = "class: config.actions",             path = "./lua/nvim_tree/_meta/config/actions.lua", },
-  { helptag = "nvim-tree-config-trash",               section = "class: config.trash",               path = "./lua/nvim_tree/_meta/config/trash.lua", },
-  { helptag = "nvim-tree-config-tab",                 section = "class: config.tab",                 path = "./lua/nvim_tree/_meta/config/tab.lua", },
-  { helptag = "nvim-tree-config-notify",              section = "class: config.notify",              path = "./lua/nvim_tree/_meta/config/notify.lua", },
-  { helptag = "nvim-tree-config-bookmarks",           section = "class: config.bookmarks",           path = "./lua/nvim_tree/_meta/config/bookmarks.lua", },
-  { helptag = "nvim-tree-config-help",                section = "class: config.help",                path = "./lua/nvim_tree/_meta/config/help.lua", },
-  { helptag = "nvim-tree-config-ui",                  section = "class: config.ui",                  path = "./lua/nvim_tree/_meta/config/ui.lua",                  name = "UI", },
-  { helptag = "nvim-tree-config-experimental",        section = "class: config.experimental",        path = "./lua/nvim_tree/_meta/config/experimental.lua", },
-  { helptag = "nvim-tree-config-log",                 section = "class: config.log",                 path = "./lua/nvim_tree/_meta/config/log.lua", },
+  { helptag = "nvim-tree-config",                     section = "Class: config",                     path = "./lua/nvim_tree/_meta/config.lua", },
+  { helptag = "nvim-tree-config-sort",                section = "Class: config.sort",                path = "./lua/nvim_tree/_meta/config/sort.lua", },
+  { helptag = "nvim-tree-config-view",                section = "Class: config.view",                path = "./lua/nvim_tree/_meta/config/view.lua", },
+  { helptag = "nvim-tree-config-renderer",            section = "Class: config.renderer",            path = "./lua/nvim_tree/_meta/config/renderer.lua", },
+  { helptag = "nvim-tree-config-hijack-directories",  section = "Class: config.hijack_directories",  path = "./lua/nvim_tree/_meta/config/hijack_directories.lua", },
+  { helptag = "nvim-tree-config-update-focused-file", section = "Class: config.update_focused_file", path = "./lua/nvim_tree/_meta/config/update_focused_file.lua", },
+  { helptag = "nvim-tree-config-system-open",         section = "Class: config.system_open",         path = "./lua/nvim_tree/_meta/config/system_open.lua", },
+  { helptag = "nvim-tree-config-git",                 section = "Class: config.git",                 path = "./lua/nvim_tree/_meta/config/git.lua", },
+  { helptag = "nvim-tree-config-diagnostics",         section = "Class: config.diagnostics",         path = "./lua/nvim_tree/_meta/config/diagnostics.lua", },
+  { helptag = "nvim-tree-config-modified",            section = "Class: config.modified",            path = "./lua/nvim_tree/_meta/config/modified.lua", },
+  { helptag = "nvim-tree-config-filters",             section = "Class: config.filters",             path = "./lua/nvim_tree/_meta/config/filters.lua", },
+  { helptag = "nvim-tree-config-live-filter",         section = "Class: config.live_filter",         path = "./lua/nvim_tree/_meta/config/live_filter.lua", },
+  { helptag = "nvim-tree-config-filesystem-watchers", section = "Class: config.filesystem_watchers", path = "./lua/nvim_tree/_meta/config/filesystem_watchers.lua", },
+  { helptag = "nvim-tree-config-actions",             section = "Class: config.actions",             path = "./lua/nvim_tree/_meta/config/actions.lua", },
+  { helptag = "nvim-tree-config-trash",               section = "Class: config.trash",               path = "./lua/nvim_tree/_meta/config/trash.lua", },
+  { helptag = "nvim-tree-config-tab",                 section = "Class: config.tab",                 path = "./lua/nvim_tree/_meta/config/tab.lua", },
+  { helptag = "nvim-tree-config-notify",              section = "Class: config.notify",              path = "./lua/nvim_tree/_meta/config/notify.lua", },
+  { helptag = "nvim-tree-config-bookmarks",           section = "Class: config.bookmarks",           path = "./lua/nvim_tree/_meta/config/bookmarks.lua", },
+  { helptag = "nvim-tree-config-help",                section = "Class: config.help",                path = "./lua/nvim_tree/_meta/config/help.lua", },
+  { helptag = "nvim-tree-config-ui",                  section = "Class: config.ui",                  path = "./lua/nvim_tree/_meta/config/ui.lua",                  name = "UI", },
+  { helptag = "nvim-tree-config-experimental",        section = "Class: config.experimental",        path = "./lua/nvim_tree/_meta/config/experimental.lua", },
+  { helptag = "nvim-tree-config-log",                 section = "Class: config.log",                 path = "./lua/nvim_tree/_meta/config/log.lua", },
+
+  { helptag = "nvim-tree-default-config",             section = "Config: default",                   path = "./lua/nvim_tree/_meta/config/default.lua", },
 }
 
 -- hydrate file names
diff --git a/scripts/help-update.sh b/scripts/help-update.sh
index 7fe52a263f2..64580ba9ead 100755
--- a/scripts/help-update.sh
+++ b/scripts/help-update.sh
@@ -1,28 +1,28 @@
 #!/usr/bin/env sh
 
-# run after changing nvim-tree.lua DEFAULT_OPTS or keymap.lua M.default_on_attach
+# run after changing default config or keymap.lua M.default_on_attach
 # scrapes and updates nvim-tree-lua.txt
 # run from repository root: scripts/help-update.sh  OR  make help-update
 
 
 #
-# DEFAULT_OPTS
+# Inject default config
 #
-begin="BEGIN_DEFAULT_OPTS"
-end="END_DEFAULT_OPTS"
+begin="default-config-start"
+end="default-config-end"
+inject="default-config-injection-placeholder"
 
 # scrape DEFAULT_OPTS, indented at 2
 sed -n -e "/${begin}/,/${end}/{ /${begin}/d; /${end}/d; p; }" lua/nvim-tree.lua > /tmp/DEFAULT_OPTS.2.lua
 
-# indent some more
+# indent to match help
 sed -e "s/^  /      /" /tmp/DEFAULT_OPTS.2.lua > /tmp/DEFAULT_OPTS.6.lua
 
-# help, indented at 6
-sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/DEFAULT_OPTS.6.lua
-           }; /${end}/p; d; }" doc/nvim-tree-lua.txt
+# inject then remove the placeholder
+sed -i -e "/${inject}/r /tmp/DEFAULT_OPTS.6.lua" -e "/${inject}/d" doc/nvim-tree-lua.txt
 
 #
-# DEFAULT_ON_ATTACH
+# Inject default mappings
 #
 
 begin="BEGIN_DEFAULT_ON_ATTACH"

From ae58d2e544bd1110ca4fbb32fce73662d426a38d Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Wed, 21 Jan 2026 12:54:59 +1100
Subject: [PATCH 120/170] docs(#2934): move setup doc from config to quickstart
 and setup

---
 doc/nvim-tree-lua.txt          | 59 +++++++++++++++++-----------------
 lua/nvim-tree/_meta/config.lua | 15 ---------
 2 files changed, 30 insertions(+), 44 deletions(-)

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 2a3e6dc7d8f..7256cca56ac 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -65,8 +65,9 @@ Disabling |netrw| is strongly advised, see |nvim-tree-netrw|
 ==============================================================================
 Quickstart: Setup                                 *nvim-tree-quickstart-setup*
 
-Setup the plugin in your `init.lua`, passing |nvim_tree.config|
-e.g. >lua
+Setup the plugin in your `init.lua`.
+
+See |nvim-tree-setup| and |nvim-tree-default-config >lua
 
   -- disable netrw at the very start of your init.lua
   vim.g.loaded_netrw = 1
@@ -78,8 +79,10 @@ e.g. >lua
   -- empty setup using defaults
   require("nvim-tree").setup()
 
-  -- OR setup with some options
-  require("nvim-tree").setup({
+  -- OR setup with a config
+
+  ---@type nvim_tree.config
+  local config = {
     sort = {
       sorter = "case_sensitive",
     },
@@ -92,7 +95,8 @@ e.g. >lua
     filters = {
       dotfiles = true,
     },
-  })
+  }
+  require("nvim-tree").setup(config)
 <
 ==============================================================================
 Quickstart: Help                                   *nvim-tree-quickstart-help*
@@ -183,11 +187,11 @@ via |nvim_tree.config| {on_attach} e.g. >lua
   end
 
   -- pass to setup along with your other options
-  require("nvim-tree").setup {
+  require("nvim-tree").setup({
     ---
     on_attach = my_on_attach,
     ---
-  }
+  })
 <
 ==============================================================================
 Quickstart: Highlight Groups                  *nvim-tree-quickstart-highlight*
@@ -311,20 +315,31 @@ Commands                                                  *nvim-tree-commands*
 ==============================================================================
 Setup                                                        *nvim-tree-setup*
 
-You must run setup() function once to initialise nvim-tree. It may be called
-again to apply a change in configuration without restarting Nvim.
+You must run the `setup()` function once to initialise nvim-tree. It may be
+called again to apply a change in configuration without restarting Nvim.
 
-setup() function takes one optional argument: configuration table. If omitted
-nvim-tree will be initialised with default configuration.
+The `setup()` function takes one optional argument: |nvim_tree.config|. If
+omitted nvim-tree will be initialised with default configuration:
+|nvim-tree-default-config|.
 
-See |nvim-tree-default-config| for the default configuration table.
+Config can be validated with |lsp| when passed directly e.g. >lua
 
-TODO #2934 move setup call patterns from config to here
+  require("nvim-tree").setup({
+    hijack_cursor = true,
+  })
+<
+or as a typed variable e.g. >lua
 
-The first setup() call is cheap: it does nothing more than validate / apply
+  ---@type nvim_tree.config
+  local config = {
+    hijack_cursor = true,
+  }
+  require("nvim-tree").setup(config)
+<
+The first `setup()` call is cheap: it does nothing more than validate / apply
 the configuration. Nothing happens until the tree is first opened.
 
-Subsequent setup() calls are expensive as they tear down the world before
+Subsequent `setup()` calls are expensive as they tear down the world before
 applying configuration.
 
 
@@ -1842,20 +1857,6 @@ Class: config                                               *nvim-tree-config*
 
     When a value is not present/nil, the default will be used.
 
-    They can be validated by |lsp| when passed directly e.g. >lua
-         require("nvim-tree").setup({
-           hijack_cursor = true,
-         })
-<
-
-    or as a typed variable e.g. >lua
-         ---@type nvim_tree.config
-         local config = {
-           hijack_cursor = true,
-         }
-         require("nvim-tree").setup(config)
-<
-
     {on_attach} Runs when creating the nvim-tree buffer. Use this to set your
     |nvim-tree-mappings|. When not a function, |nvim-tree-mappings-default|
     will be used.
diff --git a/lua/nvim-tree/_meta/config.lua b/lua/nvim-tree/_meta/config.lua
index 56ee8f9a722..692699ae827 100644
--- a/lua/nvim-tree/_meta/config.lua
+++ b/lua/nvim-tree/_meta/config.lua
@@ -11,21 +11,6 @@ error("Cannot require a meta file")
 ---
 ---When a value is not present/nil, the default will be used.
 ---
----They can be validated by |lsp| when passed directly e.g.
----```lua
----  require("nvim-tree").setup({
----    hijack_cursor = true,
----  })
----```
----
----or as a typed variable e.g.
----```lua
----  ---@type nvim_tree.config
----  local config = {
----    hijack_cursor = true,
----  }
----  require("nvim-tree").setup(config)
----```
 ---{on_attach} Runs when creating the nvim-tree buffer. Use this to set your [nvim-tree-mappings]. When not a function, [nvim-tree-mappings-default] will be used.
 ---
 ---{hijack_cursor} keep the cursor on the first letter of the filename when moving in the tree.

From 0ed74d2feabfeb3b789b5a736a2d4af991b06293 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Wed, 21 Jan 2026 12:56:48 +1100
Subject: [PATCH 121/170] docs(#2934): index contributing

---
 CONTRIBUTING.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 337b540ee6f..ca40f0a0541 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -18,9 +18,8 @@ markdown-toc --maxdepth=2 -i CONTRIBUTING.md
   * [check](#check)
 - [Diagnostics](#diagnostics)
 - [Backwards Compatibility](#backwards-compatibility)
-- [Adding New Actions](#adding-new-actions)
 - [Documentation](#documentation)
-  * [Opts](#opts)
+  * [Config And Mappings](#config-and-mappings)
   * [API](#api)
 - [Windows](#windows)
 - [Pull Request](#pull-request)

From 0c78c276055ca4b80341154134143fb171076c9e Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 22 Jan 2026 13:06:51 +1100
Subject: [PATCH 122/170] docs(#3088): cleanup following merge

---
 .gitignore                          | 1 -
 CONTRIBUTING.md                     | 1 -
 doc/nvim-tree-lua.txt               | 4 ++--
 lua/nvim-tree/_meta/api/classes.lua | 2 ++
 lua/nvim-tree/_meta/api/filter.lua  | 3 +++
 5 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/.gitignore b/.gitignore
index 97422fc2180..faee0c43dd9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,4 @@
 /luals-out/
 /luals/
-/src/
 # backup vim files
 *~
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ca40f0a0541..da7ae82e1b1 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -104,7 +104,6 @@ Suppressions are permitted only in the following cases:
 - Backwards compatibility shims
 - neovim API metadata incorrect, awaiting upstream fix
 - classic class framework
-- `gen_vimdoc_config.lua` help generator as it requires neovim source
 
 # Backwards Compatibility
 
diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 4d0736115ef..7fa47445a61 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -342,7 +342,7 @@ The `on_attach` function is passed the `bufnr` of nvim-tree. Use
     vim.keymap.set("n", "", api.node.open.replace_tree_buffer,     opts("Open: In Place"))
     ---
     -- OR use all default mappings
-    api.config.mappings.default_on_attach(bufnr)
+    api.map.default_on_attach.default_on_attach(bufnr)
 
     -- remove a default
     vim.keymap.del("n", "", { buffer = bufnr })
@@ -463,7 +463,7 @@ Alternatively, you may apply these default mappings from your
       return { desc = "nvim-tree: " .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true }
     end
 
-    api.config.mappings.default_on_attach(bufnr)
+    api.map.default_on_attach.default_on_attach(bufnr)
 
     -- your removals and mappings go here
   end
diff --git a/lua/nvim-tree/_meta/api/classes.lua b/lua/nvim-tree/_meta/api/classes.lua
index bd8701529a2..44b869f5a6e 100644
--- a/lua/nvim-tree/_meta/api/classes.lua
+++ b/lua/nvim-tree/_meta/api/classes.lua
@@ -1,5 +1,7 @@
 ---@meta
 
+-- TODO #3088 document these
+
 ---@brief
 ---Classes shared by multiple API modules.
 ---
diff --git a/lua/nvim-tree/_meta/api/filter.lua b/lua/nvim-tree/_meta/api/filter.lua
index 06922fd848d..92a916ce292 100644
--- a/lua/nvim-tree/_meta/api/filter.lua
+++ b/lua/nvim-tree/_meta/api/filter.lua
@@ -1,6 +1,9 @@
 ---@meta
 local nvim_tree = { api = { filter = { live_filter = {} } } }
 
+
+-- TODO 3088 move tree filters in here
+
 ---
 ---Enter live filter mode. Opens an input window with [filetype] `NvimTreeFilter`
 ---

From 43fab325cfd5b4fd1ff9e76beda3ed2911bb2a13 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 22 Jan 2026 13:14:42 +1100
Subject: [PATCH 123/170] docs(#3088): tidy section names

---
 CONTRIBUTING.md               |  2 +-
 doc/nvim-tree-lua.txt         | 24 ++++++++++++------------
 scripts/gen_vimdoc_config.lua | 24 ++++++++++++------------
 3 files changed, 25 insertions(+), 25 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index da7ae82e1b1..e16c20402a2 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -139,7 +139,7 @@ This will:
 2. Regenerate from `*nvim-tree-config*` to the end of the file, see `gen_vimdoc.sh`
 3. Update default mappings in `*nvim-tree-mappings-default*` and `*nvim-tree-quickstart-help*`
 
-Commit your changes then run:
+Commit or stage your changes then run:
 ```sh
 make help-check
 ```
diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 7fa47445a61..7ece33b38ed 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -2052,7 +2052,7 @@ Config: log                                             *nvim-tree-config-log*
 
 
 ==============================================================================
-Config: Default                                     *nvim-tree-default-config*
+Config: Default                                     *nvim-tree-config-default*
 
 Following is the default configuration, see |nvim_tree.config| for details. >lua
 
@@ -2344,7 +2344,7 @@ Following is the default configuration, see |nvim_tree.config| for details. >lua
 
 
 ==============================================================================
-api Overview                                                   *nvim-tree-api*
+API                                                            *nvim-tree-api*
 
 nvim-tree exposes a public API. This is non breaking, with additions made as
 necessary.
@@ -2383,7 +2383,7 @@ following are functionally identical: >lua
 
 
 ==============================================================================
-api.commands                                          *nvim-tree-api-commands*
+API: commands                                         *nvim-tree-api-commands*
 
 get()                                           *nvim_tree.api.commands.get()*
     Retrieve all |nvim-tree-commands|
@@ -2401,7 +2401,7 @@ get()                                           *nvim_tree.api.commands.get()*
 
 
 ==============================================================================
-api.events                                              *nvim-tree-api-events*
+API: events                                             *nvim-tree-api-events*
 
 subscribe({event_type}, {callback})         *nvim_tree.api.events.subscribe()*
     Register a handler for an event, see |nvim-tree-events|.
@@ -2412,7 +2412,7 @@ subscribe({event_type}, {callback})         *nvim_tree.api.events.subscribe()*
 
 
 ==============================================================================
-api.filter                                              *nvim-tree-api-filter*
+API: filter                                             *nvim-tree-api-filter*
 
 live_filter.clear()                 *nvim_tree.api.filter.live_filter.clear()*
     Exit live filter mode.
@@ -2423,7 +2423,7 @@ live_filter.start()                 *nvim_tree.api.filter.live_filter.start()*
 
 
 ==============================================================================
-api.fs                                                      *nvim-tree-api-fs*
+API: fs                                                     *nvim-tree-api-fs*
 
 clear_clipboard()                         *nvim_tree.api.fs.clear_clipboard()*
     Clear the nvim-tree clipboard.
@@ -2531,7 +2531,7 @@ trash({node})                                       *nvim_tree.api.fs.trash()*
 
 
 ==============================================================================
-api.health                                              *nvim-tree-api-health*
+API: health                                             *nvim-tree-api-health*
 
 hi_test()                                     *nvim_tree.api.health.hi_test()*
     Open a new buffer displaying all nvim-tree highlight groups, their link
@@ -2541,7 +2541,7 @@ hi_test()                                     *nvim_tree.api.health.hi_test()*
 
 
 ==============================================================================
-api.map                                                    *nvim-tree-api-map*
+API: map                                                   *nvim-tree-api-map*
 
 default_on_attach({bufnr})             *nvim_tree.api.map.default_on_attach()*
     Apply all |nvim-tree-mappings-default|. Call from your |nvim_tree.config|
@@ -2567,7 +2567,7 @@ get_keymap_default()                  *nvim_tree.api.map.get_keymap_default()*
 
 
 ==============================================================================
-api.marks                                                *nvim-tree-api-marks*
+API: marks                                               *nvim-tree-api-marks*
 
 bulk.delete()                              *nvim_tree.api.marks.bulk.delete()*
     Delete all marked, prompting if |nvim_tree.config.ui.confirm| {remove}
@@ -2611,7 +2611,7 @@ toggle({node})                                  *nvim_tree.api.marks.toggle()*
 
 
 ==============================================================================
-api.node                                                  *nvim-tree-api-node*
+API: node                                                 *nvim-tree-api-node*
 
 buffer.delete({node}, {opts})             *nvim_tree.api.node.buffer.delete()*
     Deletes node's related buffer, if one exists. Executes |:bdelete| or
@@ -2943,7 +2943,7 @@ show_info_popup({node})                 *nvim_tree.api.node.show_info_popup()*
 
 
 ==============================================================================
-api.tree                                                  *nvim-tree-api-tree*
+API: tree                                                 *nvim-tree-api-tree*
 
 change_root({path})                         *nvim_tree.api.tree.change_root()*
     Change the tree's root to a path.
@@ -3150,7 +3150,7 @@ winid({opts})                                     *nvim_tree.api.tree.winid()*
 
 
 ==============================================================================
-api Classes                                            *nvim-tree-api-classes*
+API: Classes                                           *nvim-tree-api-classes*
 
 Classes shared by multiple API modules.
 
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index 37034ddd490..ac3224248bc 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -35,21 +35,21 @@ local srcs = {
   { helptag = "nvim-tree-config-experimental",        section = "Config: experimental",        path = "./lua/nvim_tree/_meta/config/experimental.lua", },
   { helptag = "nvim-tree-config-log",                 section = "Config: log",                 path = "./lua/nvim_tree/_meta/config/log.lua", },
 
-  { helptag = "nvim-tree-default-config",             section = "Config: Default",             path = "./lua/nvim_tree/_meta/config/default.lua", },
+  { helptag = "nvim-tree-config-default",             section = "Config: Default",             path = "./lua/nvim_tree/_meta/config/default.lua", },
 
-  { helptag = "nvim-tree-api",                        section = "api Overview",                path = "./lua/nvim_tree/api.lua", },
+  { helptag = "nvim-tree-api",                        section = "API",                         path = "./lua/nvim_tree/api.lua", },
 
-  { helptag = "nvim-tree-api-commands",               section = "api.commands",                path = "./lua/nvim_tree/_meta/api/commands.lua", },
-  { helptag = "nvim-tree-api-events",                 section = "api.events",                  path = "./lua/nvim_tree/_meta/api/events.lua", },
-  { helptag = "nvim-tree-api-filter",                 section = "api.filter",                  path = "./lua/nvim_tree/_meta/api/filter.lua", },
-  { helptag = "nvim-tree-api-fs",                     section = "api.fs",                      path = "./lua/nvim_tree/_meta/api/fs.lua", },
-  { helptag = "nvim-tree-api-health",                 section = "api.health",                  path = "./lua/nvim_tree/_meta/api/health.lua", },
-  { helptag = "nvim-tree-api-map",                    section = "api.map",                     path = "./lua/nvim_tree/_meta/api/map.lua", },
-  { helptag = "nvim-tree-api-marks",                  section = "api.marks",                   path = "./lua/nvim_tree/_meta/api/marks.lua", },
-  { helptag = "nvim-tree-api-node",                   section = "api.node",                    path = "./lua/nvim_tree/_meta/api/node.lua", },
-  { helptag = "nvim-tree-api-tree",                   section = "api.tree",                    path = "./lua/nvim_tree/_meta/api/tree.lua", },
+  { helptag = "nvim-tree-api-commands",               section = "API: commands",               path = "./lua/nvim_tree/_meta/api/commands.lua", },
+  { helptag = "nvim-tree-api-events",                 section = "API: events",                 path = "./lua/nvim_tree/_meta/api/events.lua", },
+  { helptag = "nvim-tree-api-filter",                 section = "API: filter",                 path = "./lua/nvim_tree/_meta/api/filter.lua", },
+  { helptag = "nvim-tree-api-fs",                     section = "API: fs",                     path = "./lua/nvim_tree/_meta/api/fs.lua", },
+  { helptag = "nvim-tree-api-health",                 section = "API: health",                 path = "./lua/nvim_tree/_meta/api/health.lua", },
+  { helptag = "nvim-tree-api-map",                    section = "API: map",                    path = "./lua/nvim_tree/_meta/api/map.lua", },
+  { helptag = "nvim-tree-api-marks",                  section = "API: marks",                  path = "./lua/nvim_tree/_meta/api/marks.lua", },
+  { helptag = "nvim-tree-api-node",                   section = "API: node",                   path = "./lua/nvim_tree/_meta/api/node.lua", },
+  { helptag = "nvim-tree-api-tree",                   section = "API: tree",                   path = "./lua/nvim_tree/_meta/api/tree.lua", },
 
-  { helptag = "nvim-tree-api-classes",                section = "api Classes",                 path = "./lua/nvim_tree/_meta/api/classes.lua", },
+  { helptag = "nvim-tree-api-classes",                section = "API: Classes",                path = "./lua/nvim_tree/_meta/api/classes.lua", },
 }
 
 -- hydrate file names

From ae0a83a15779e1932621ca104354860afd71a373 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 22 Jan 2026 17:42:15 +1100
Subject: [PATCH 124/170] docs(#3088): split node.navigate and open, move all
 filters into api.filter

---
 doc/nvim-tree-lua.txt                     | 222 ++++++++++------------
 lua/nvim-tree/_meta/api/filter.lua        |  52 ++++-
 lua/nvim-tree/_meta/api/node.lua          | 218 +--------------------
 lua/nvim-tree/_meta/api/node/navigate.lua | 120 ++++++++++++
 lua/nvim-tree/_meta/api/node/open.lua     | 101 ++++++++++
 lua/nvim-tree/_meta/api/tree.lua          |  35 ----
 lua/nvim-tree/_meta/config/filters.lua    |  14 +-
 lua/nvim-tree/api-impl.lua                |  22 +--
 lua/nvim-tree/keymap.lua                  |  16 +-
 scripts/gen_vimdoc_config.lua             |   2 +
 10 files changed, 408 insertions(+), 394 deletions(-)
 create mode 100644 lua/nvim-tree/_meta/api/node/navigate.lua
 create mode 100644 lua/nvim-tree/_meta/api/node/open.lua

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 7ece33b38ed..dfa12813fbd 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -67,7 +67,7 @@ Quickstart: Setup                                 *nvim-tree-quickstart-setup*
 
 Setup the plugin in your `init.lua`.
 
-See |nvim-tree-setup| and |nvim-tree-default-config >lua
+See |nvim-tree-setup| and |nvim-tree-config-default| >lua
 
   -- disable netrw at the very start of your init.lua
   vim.g.loaded_netrw = 1
@@ -124,9 +124,9 @@ Show the mappings:  `g?`
 `bd`              Delete Bookmarked          |nvim_tree.api.marks.bulk.delete()|
 `bt`              Trash Bookmarked           |nvim_tree.api.marks.bulk.trash()|
 `bmv`             Move Bookmarked            |nvim_tree.api.marks.bulk.move()|
-`B`               Toggle Filter: No Buffer   |nvim_tree.api.tree.toggle_no_buffer_filter()|
+`B`               Toggle Filter: No Buffer   |nvim_tree.api.filter.no_buffer.toggle()|
 `c`               Copy                       |nvim_tree.api.fs.copy.node()|
-`C`               Toggle Filter: Git Clean   |nvim_tree.api.tree.toggle_git_clean_filter()|
+`C`               Toggle Filter: Git Clean   |nvim_tree.api.filter.git.clean.toggle()|
 `[c`              Prev Git                   |nvim_tree.api.node.navigate.git.prev()|
 `]c`              Next Git                   |nvim_tree.api.node.navigate.git.next()|
 `d`               Delete                     |nvim_tree.api.fs.remove()|
@@ -135,17 +135,17 @@ Show the mappings:  `g?`
 `e`               Rename: Basename           |nvim_tree.api.fs.rename_basename()|
 `]e`              Next Diagnostic            |nvim_tree.api.node.navigate.diagnostics.next()|
 `[e`              Prev Diagnostic            |nvim_tree.api.node.navigate.diagnostics.prev()|
-`F`               Live Filter: Clear         |nvim_tree.api.filter.live_filter.clear()|
-`f`               Live Filter: Start         |nvim_tree.api.filter.live_filter.start()|
+`F`               Live Filter: Clear         |nvim_tree.api.filter.live.clear()|
+`f`               Live Filter: Start         |nvim_tree.api.filter.live.start()|
 `g?`              Help                       |nvim_tree.api.tree.toggle_help()|
 `gy`              Copy Absolute Path         |nvim_tree.api.fs.copy.absolute_path()|
 `ge`              Copy Basename              |nvim_tree.api.fs.copy.basename()|
-`H`               Toggle Filter: Dotfiles    |nvim_tree.api.tree.toggle_hidden_filter()|
-`I`               Toggle Filter: Git Ignore  |nvim_tree.api.tree.toggle_gitignore_filter()|
+`H`               Toggle Filter: Dotfiles    |nvim_tree.api.filter.dotfiles.toggle()|
+`I`               Toggle Filter: Git Ignore  |nvim_tree.api.filter.git.ignored.toggle()|
 `J`               Last Sibling               |nvim_tree.api.node.navigate.sibling.last()|
 `K`               First Sibling              |nvim_tree.api.node.navigate.sibling.first()|
 `L`               Toggle Group Empty         |nvim_tree.api.node.open.toggle_group_empty()|
-`M`               Toggle Filter: No Bookmark |nvim_tree.api.tree.toggle_no_bookmark_filter()|
+`M`               Toggle Filter: No Bookmark |nvim_tree.api.filter.no_bookmark.toggle()|
 `m`               Toggle Bookmark            |nvim_tree.api.marks.toggle()|
 `o`               Open                       |nvim_tree.api.node.open.edit()|
 `O`               Open: No Window Picker     |nvim_tree.api.node.open.no_window_picker()|
@@ -157,7 +157,7 @@ Show the mappings:  `g?`
 `s`               Run System                 |nvim_tree.api.node.run.system()|
 `S`               Search                     |nvim_tree.api.tree.search_node()|
 `u`               Rename: Full Path          |nvim_tree.api.fs.rename_full()|
-`U`               Toggle Filter: Hidden      |nvim_tree.api.tree.toggle_custom_filter()|
+`U`               Toggle Filter: Hidden      |nvim_tree.api.filter.custom.toggle()|
 `W`               Collapse All               |nvim_tree.api.tree.collapse_all()|
 `x`               Cut                        |nvim_tree.api.fs.cut()|
 `y`               Copy Name                  |nvim_tree.api.fs.copy.filename()|
@@ -293,7 +293,7 @@ called again to apply a change in configuration without restarting Nvim.
 
 The `setup()` function takes one optional argument: |nvim_tree.config|. If
 omitted nvim-tree will be initialised with default configuration:
-|nvim-tree-default-config|.
+|nvim-tree-config-default|.
 
 Config can be validated with |lsp| when passed directly e.g. >lua
 
@@ -411,9 +411,9 @@ You are encouraged to copy these to your {on_attach} function. >lua
   vim.keymap.set("n", "bd",             api.marks.bulk.delete,              opts("Delete Bookmarked"))
   vim.keymap.set("n", "bt",             api.marks.bulk.trash,               opts("Trash Bookmarked"))
   vim.keymap.set("n", "bmv",            api.marks.bulk.move,                opts("Move Bookmarked"))
-  vim.keymap.set("n", "B",              api.tree.toggle_no_buffer_filter,   opts("Toggle Filter: No Buffer"))
+  vim.keymap.set("n", "B",              api.filter.no_buffer.toggle,        opts("Toggle Filter: No Buffer"))
   vim.keymap.set("n", "c",              api.fs.copy.node,                   opts("Copy"))
-  vim.keymap.set("n", "C",              api.tree.toggle_git_clean_filter,   opts("Toggle Filter: Git Clean"))
+  vim.keymap.set("n", "C",              api.filter.git.clean.toggle,        opts("Toggle Filter: Git Clean"))
   vim.keymap.set("n", "[c",             api.node.navigate.git.prev,         opts("Prev Git"))
   vim.keymap.set("n", "]c",             api.node.navigate.git.next,         opts("Next Git"))
   vim.keymap.set("n", "d",              api.fs.remove,                      opts("Delete"))
@@ -422,17 +422,17 @@ You are encouraged to copy these to your {on_attach} function. >lua
   vim.keymap.set("n", "e",              api.fs.rename_basename,             opts("Rename: Basename"))
   vim.keymap.set("n", "]e",             api.node.navigate.diagnostics.next, opts("Next Diagnostic"))
   vim.keymap.set("n", "[e",             api.node.navigate.diagnostics.prev, opts("Prev Diagnostic"))
-  vim.keymap.set("n", "F",              api.filter.live_filter.clear,       opts("Live Filter: Clear"))
-  vim.keymap.set("n", "f",              api.filter.live_filter.start,       opts("Live Filter: Start"))
+  vim.keymap.set("n", "F",              api.filter.live.clear,              opts("Live Filter: Clear"))
+  vim.keymap.set("n", "f",              api.filter.live.start,              opts("Live Filter: Start"))
   vim.keymap.set("n", "g?",             api.tree.toggle_help,               opts("Help"))
   vim.keymap.set("n", "gy",             api.fs.copy.absolute_path,          opts("Copy Absolute Path"))
   vim.keymap.set("n", "ge",             api.fs.copy.basename,               opts("Copy Basename"))
-  vim.keymap.set("n", "H",              api.tree.toggle_hidden_filter,      opts("Toggle Filter: Dotfiles"))
-  vim.keymap.set("n", "I",              api.tree.toggle_gitignore_filter,   opts("Toggle Filter: Git Ignore"))
+  vim.keymap.set("n", "H",              api.filter.dotfiles.toggle,         opts("Toggle Filter: Dotfiles"))
+  vim.keymap.set("n", "I",              api.filter.git.ignored.toggle,      opts("Toggle Filter: Git Ignore"))
   vim.keymap.set("n", "J",              api.node.navigate.sibling.last,     opts("Last Sibling"))
   vim.keymap.set("n", "K",              api.node.navigate.sibling.first,    opts("First Sibling"))
   vim.keymap.set("n", "L",              api.node.open.toggle_group_empty,   opts("Toggle Group Empty"))
-  vim.keymap.set("n", "M",              api.tree.toggle_no_bookmark_filter, opts("Toggle Filter: No Bookmark"))
+  vim.keymap.set("n", "M",              api.filter.no_bookmark.toggle,      opts("Toggle Filter: No Bookmark"))
   vim.keymap.set("n", "m",              api.marks.toggle,                   opts("Toggle Bookmark"))
   vim.keymap.set("n", "o",              api.node.open.edit,                 opts("Open"))
   vim.keymap.set("n", "O",              api.node.open.no_window_picker,     opts("Open: No Window Picker"))
@@ -444,7 +444,7 @@ You are encouraged to copy these to your {on_attach} function. >lua
   vim.keymap.set("n", "s",              api.node.run.system,                opts("Run System"))
   vim.keymap.set("n", "S",              api.tree.search_node,               opts("Search"))
   vim.keymap.set("n", "u",              api.fs.rename_full,                 opts("Rename: Full Path"))
-  vim.keymap.set("n", "U",              api.tree.toggle_custom_filter,      opts("Toggle Filter: Hidden"))
+  vim.keymap.set("n", "U",              api.filter.custom.toggle,           opts("Toggle Filter: Hidden"))
   vim.keymap.set("n", "W",              api.tree.collapse_all,              opts("Collapse All"))
   vim.keymap.set("n", "x",              api.fs.cut,                         opts("Cut"))
   vim.keymap.set("n", "y",              api.fs.copy.filename,               opts("Copy Name"))
@@ -1013,8 +1013,8 @@ continue to be available.
 
 `api.git.reload`                          |nvim_tree.api.tree.reload_git()|
 
-`api.live_filter.start`                   |nvim_tree.api.filter.live_filter.start()|
-`api.live_filter.clear`                   |nvim_tree.api.filter.live_filter.clear()|
+`api.live_filter.start`                   |nvim_tree.api.filter.live.start()|
+`api.live_filter.clear`                   |nvim_tree.api.filter.live.clear()|
 
 ==============================================================================
 Legacy: Highlight                                 *nvim-tree-legacy-highlight*
@@ -1695,32 +1695,32 @@ Config: filters                                     *nvim-tree-config-filters*
     Filters can be set at startup or toggled live via API with default
     mappings.
 
-    `I     `{git_ignored}`         `|nvim_tree.api.tree.toggle_gitignore_filter()|
+    `I     `{git_ignored}`         `|nvim_tree.api.filter.git.ignored.toggle()|
     Ignore files based on `.gitignore`. Requires |nvim_tree.config.git|
 
-    `H     `{dotfiles}`            `|nvim_tree.api.tree.toggle_hidden_filter()|
+    `H     `{dotfiles}`            `|nvim_tree.api.filter.dotfiles.toggle()|
     Filter dotfiles: files/directories starting with a `.`
 
-    `C     `{git_clean}`           `|nvim_tree.api.tree.toggle_git_clean_filter()|
+    `C     `{git_clean}`           `|nvim_tree.api.filter.git.clean.toggle()|
     Filter files with no git status. `.gitignore` files will not be filtered
     when {git_ignored}, as they are effectively dirty.
 
-    `B     `{no_buffer}`           `|nvim_tree.api.tree.toggle_no_buffer_filter()|
+    `B     `{no_buffer}`           `|nvim_tree.api.filter.no_buffer.toggle()|
     Filter files that have no |buflisted()| buffer. For performance reasons
     buffer delete/wipe may not be immediately shown. A reload or filesystem
     event will always result in an update.
 
-    `M     `{no_bookmark}`         `|nvim_tree.api.tree.toggle_no_bookmark_filter()|
+    `M     `{no_bookmark}`         `|nvim_tree.api.filter.no_bookmark.toggle()|
     Filter files that are not bookmarked. Enabling this is not useful as there
     is no means yet to persist bookmarks.
 
-    `U     `{custom}`              `|nvim_tree.api.tree.toggle_custom_filter()|
+    `U     `{custom}`              `|nvim_tree.api.filter.custom.toggle()|
     Disable specific file/directory names via:
     • a list of backslash escaped |vim.regex| strings e.g. `"^\\.git""`
     • a function passed the absolute path of the directory.
 
     All filters including live filter may be disabled via {enable} and toggled
-    with |nvim_tree.api.tree.toggle_enable_filters()|
+    with |nvim_tree.api.filter.toggle()|
 
     Files/directories may be {exclude}d from filtering: they will always be
     shown, overriding {git_ignored}, {dotfiles} and {custom}.
@@ -2414,13 +2414,34 @@ subscribe({event_type}, {callback})         *nvim_tree.api.events.subscribe()*
 ==============================================================================
 API: filter                                             *nvim-tree-api-filter*
 
-live_filter.clear()                 *nvim_tree.api.filter.live_filter.clear()*
+custom.toggle()                         *nvim_tree.api.filter.custom.toggle()*
+    Toggle |nvim_tree.config.filters| {custom} filter.
+
+dotfiles.toggle()                     *nvim_tree.api.filter.dotfiles.toggle()*
+    Toggle |nvim_tree.config.filters| {dotfiles} filter.
+
+git.clean.toggle()                   *nvim_tree.api.filter.git.clean.toggle()*
+    Toggle |nvim_tree.config.filters| {git_clean} filter.
+
+git.ignored.toggle()               *nvim_tree.api.filter.git.ignored.toggle()*
+    Toggle |nvim_tree.config.filters| {git_ignored} filter.
+
+live.clear()                               *nvim_tree.api.filter.live.clear()*
     Exit live filter mode.
 
-live_filter.start()                 *nvim_tree.api.filter.live_filter.start()*
+live.start()                               *nvim_tree.api.filter.live.start()*
     Enter live filter mode. Opens an input window with |filetype|
     `NvimTreeFilter`
 
+no_bookmark.toggle()               *nvim_tree.api.filter.no_bookmark.toggle()*
+    Toggle |nvim_tree.config.filters| {no_bookmark} filter.
+
+no_buffer.toggle()                   *nvim_tree.api.filter.no_buffer.toggle()*
+    Toggle |nvim_tree.config.filters| {no_buffer} filter.
+
+toggle()                                       *nvim_tree.api.filter.toggle()*
+    Toggle |nvim_tree.config.filters| {enable} all filters.
+
 
 ==============================================================================
 API: fs                                                     *nvim-tree-api-fs*
@@ -2653,15 +2674,38 @@ expand({node}, {opts})                           *nvim_tree.api.node.expand()*
                   Return `true` if `node` should be expanded.
                   `expansion_count` is the total number of folders expanded.
 
+run.cmd({node})                                 *nvim_tree.api.node.run.cmd()*
+    Enter |cmdline| with the full path of the node and the cursor at the start
+    of the line.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
+
+run.system({node})                           *nvim_tree.api.node.run.system()*
+    Execute |nvim_tree.config.system_open|.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
+
+show_info_popup({node})                 *nvim_tree.api.node.show_info_popup()*
+    Open a popup window showing: fullpath, size, accessed, modified, created.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
+
+
+==============================================================================
+API: node.navigate                               *nvim-tree-api-node-navigate*
+
                               *nvim_tree.api.node.navigate.diagnostics.next()*
-navigate.diagnostics.next({node})
+diagnostics.next({node})
     Navigate to the next item showing diagnostic status.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                     *nvim_tree.api.node.navigate.diagnostics.next_recursive()*
-navigate.diagnostics.next_recursive({node})
+diagnostics.next_recursive({node})
     Navigate to the next item showing diagnostic status, recursively. Needs
     |nvim_tree.config.diagnostics| {show_on_dirs}
 
@@ -2669,28 +2713,28 @@ navigate.diagnostics.next_recursive({node})
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                               *nvim_tree.api.node.navigate.diagnostics.prev()*
-navigate.diagnostics.prev({node})
+diagnostics.prev({node})
     Navigate to the previous item showing diagnostic status.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                     *nvim_tree.api.node.navigate.diagnostics.prev_recursive()*
-navigate.diagnostics.prev_recursive({node})
+diagnostics.prev_recursive({node})
     Navigate to the previous item showing diagnostic status, recursively.
     Needs |nvim_tree.config.diagnostics| {show_on_dirs}
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
-navigate.git.next({node})             *nvim_tree.api.node.navigate.git.next()*
+git.next({node})                      *nvim_tree.api.node.navigate.git.next()*
     Navigate to the next item showing git status.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                             *nvim_tree.api.node.navigate.git.next_recursive()*
-navigate.git.next_recursive({node})
+git.next_recursive({node})
     Navigate to the next item showing git status, recursively. Needs
     |nvim_tree.config.git| {show_on_dirs}
 
@@ -2698,20 +2742,20 @@ navigate.git.next_recursive({node})
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                       *nvim_tree.api.node.navigate.git.next_skip_gitignored()*
-navigate.git.next_skip_gitignored({node})
+git.next_skip_gitignored({node})
     Navigate to the next item showing git status, skipping `.gitignore`
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
-navigate.git.prev({node})             *nvim_tree.api.node.navigate.git.prev()*
+git.prev({node})                      *nvim_tree.api.node.navigate.git.prev()*
     Navigate to the previous item showing git status.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                             *nvim_tree.api.node.navigate.git.prev_recursive()*
-navigate.git.prev_recursive({node})
+git.prev_recursive({node})
     Navigate to the previous item showing git status, recursively. Needs
     |nvim_tree.config.git| {show_on_dirs}
 
@@ -2719,77 +2763,65 @@ navigate.git.prev_recursive({node})
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                       *nvim_tree.api.node.navigate.git.prev_skip_gitignored()*
-navigate.git.prev_skip_gitignored({node})
+git.prev_skip_gitignored({node})
     Navigate to the previous item showing git status, skipping `.gitignore`
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
-                                   *nvim_tree.api.node.navigate.opened.next()*
-navigate.opened.next({node})
+opened.next({node})                *nvim_tree.api.node.navigate.opened.next()*
     Navigate to the next |bufloaded()| file.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
-                                   *nvim_tree.api.node.navigate.opened.prev()*
-navigate.opened.prev({node})
+opened.prev({node})                *nvim_tree.api.node.navigate.opened.prev()*
     Navigate to the previous |bufloaded()| file.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
-navigate.parent({node})                 *nvim_tree.api.node.navigate.parent()*
+parent({node})                          *nvim_tree.api.node.navigate.parent()*
     Navigate to the parent directory of the node.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
-                                  *nvim_tree.api.node.navigate.parent_close()*
-navigate.parent_close({node})
+parent_close({node})              *nvim_tree.api.node.navigate.parent_close()*
     Navigate to the parent directory of the node, closing it.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
-                                 *nvim_tree.api.node.navigate.sibling.first()*
-navigate.sibling.first({node})
+sibling.first({node})            *nvim_tree.api.node.navigate.sibling.first()*
     Navigate to the first node in the current node's folder.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
-                                  *nvim_tree.api.node.navigate.sibling.last()*
-navigate.sibling.last({node})
+sibling.last({node})              *nvim_tree.api.node.navigate.sibling.last()*
     Navigate to the last node in the current node's folder.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
-                                  *nvim_tree.api.node.navigate.sibling.next()*
-navigate.sibling.next({node})
+sibling.next({node})              *nvim_tree.api.node.navigate.sibling.next()*
     Navigate to the next node in the current node's folder, wraps.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
-                                  *nvim_tree.api.node.navigate.sibling.prev()*
-navigate.sibling.prev({node})
+sibling.prev({node})              *nvim_tree.api.node.navigate.sibling.prev()*
     Navigate to the previous node in the current node's folder, wraps.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
-open.drop({node})                             *nvim_tree.api.node.open.drop()*
-    Switch to window with selected file if it exists, open file otherwise.
-    • file: open file using |:drop|
-    • directory: expand or collapse
-    • root: change directory up
 
-    Parameters: ~
-      • {node}  (`nvim_tree.api.Node?`) directory or file
+==============================================================================
+API: node.open                                       *nvim-tree-api-node-open*
 
-open.edit({node}, {opts})                     *nvim_tree.api.node.open.edit()*
+edit({node}, {opts})                          *nvim_tree.api.node.open.edit()*
     • file: open as per |nvim_tree.config.actions.open_file|
     • directory: expand or collapse
     • root: change directory up
@@ -2802,7 +2834,7 @@ open.edit({node}, {opts})                     *nvim_tree.api.node.open.edit()*
                 • {focus}? (`boolean`, default: false) Keep focus in the tree
                   when opening the file.
 
-open.horizontal({node}, {opts})         *nvim_tree.api.node.open.horizontal()*
+horizontal({node}, {opts})              *nvim_tree.api.node.open.horizontal()*
     Open file in a new horizontal split.
 
     Parameters: ~
@@ -2814,7 +2846,7 @@ open.horizontal({node}, {opts})         *nvim_tree.api.node.open.horizontal()*
                   when opening the file.
 
                               *nvim_tree.api.node.open.horizontal_no_picker()*
-open.horizontal_no_picker({node}, {opts})
+horizontal_no_picker({node}, {opts})
     Open file in a new horizontal split without using the window picker.
 
     Parameters: ~
@@ -2826,7 +2858,7 @@ open.horizontal_no_picker({node}, {opts})
                   when opening the file.
 
                                   *nvim_tree.api.node.open.no_window_picker()*
-open.no_window_picker({node}, {opts})
+no_window_picker({node}, {opts})
     Open file without using the window picker.
 
     Parameters: ~
@@ -2837,7 +2869,7 @@ open.no_window_picker({node}, {opts})
                 • {focus}? (`boolean`, default: false) Keep focus in the tree
                   when opening the file.
 
-open.preview({node}, {opts})               *nvim_tree.api.node.open.preview()*
+preview({node}, {opts})                    *nvim_tree.api.node.open.preview()*
     Open file with |'bufhidden'| set to `delete`.
 
     Parameters: ~
@@ -2849,7 +2881,7 @@ open.preview({node}, {opts})               *nvim_tree.api.node.open.preview()*
                   when opening the file.
 
                                  *nvim_tree.api.node.open.preview_no_picker()*
-open.preview_no_picker({node}, {opts})
+preview_no_picker({node}, {opts})
     Open file with |'bufhidden'| set to `delete` without using the window
     picker.
 
@@ -2862,13 +2894,13 @@ open.preview_no_picker({node}, {opts})
                   when opening the file.
 
                                *nvim_tree.api.node.open.replace_tree_buffer()*
-open.replace_tree_buffer({node})
+replace_tree_buffer({node})
     Open file in place: in the nvim-tree window.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) file
 
-open.tab({node}, {opts})                       *nvim_tree.api.node.open.tab()*
+tab({node}, {opts})                            *nvim_tree.api.node.open.tab()*
     Open file in a new tab.
 
     Parameters: ~
@@ -2879,7 +2911,7 @@ open.tab({node}, {opts})                       *nvim_tree.api.node.open.tab()*
                 • {focus}? (`boolean`, default: false) Keep focus in the tree
                   when opening the file.
 
-open.tab_drop({node})                     *nvim_tree.api.node.open.tab_drop()*
+tab_drop({node})                          *nvim_tree.api.node.open.tab_drop()*
     Switch to tab containing window with selected file if it exists. Open file
     in new tab otherwise.
 
@@ -2887,7 +2919,7 @@ open.tab_drop({node})                     *nvim_tree.api.node.open.tab_drop()*
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                                 *nvim_tree.api.node.open.toggle_group_empty()*
-open.toggle_group_empty({node}, {opts})
+toggle_group_empty({node}, {opts})
     Toggle |nvim_tree.config.renderer| {group_empty} for a directory. Needs
     {group_empty} set.
 
@@ -2899,7 +2931,7 @@ open.toggle_group_empty({node}, {opts})
                 • {focus}? (`boolean`, default: false) Keep focus in the tree
                   when opening the file.
 
-open.vertical({node}, {opts})             *nvim_tree.api.node.open.vertical()*
+vertical({node}, {opts})                  *nvim_tree.api.node.open.vertical()*
     Open file in a new vertical split.
 
     Parameters: ~
@@ -2911,7 +2943,7 @@ open.vertical({node}, {opts})             *nvim_tree.api.node.open.vertical()*
                   when opening the file.
 
                                 *nvim_tree.api.node.open.vertical_no_picker()*
-open.vertical_no_picker({node}, {opts})
+vertical_no_picker({node}, {opts})
     Open file in a new vertical split without using the window picker.
 
     Parameters: ~
@@ -2922,25 +2954,6 @@ open.vertical_no_picker({node}, {opts})
                 • {focus}? (`boolean`, default: false) Keep focus in the tree
                   when opening the file.
 
-run.cmd({node})                                 *nvim_tree.api.node.run.cmd()*
-    Enter |cmdline| with the full path of the node and the cursor at the start
-    of the line.
-
-    Parameters: ~
-      • {node}  (`nvim_tree.api.Node?`) directory or file
-
-run.system({node})                           *nvim_tree.api.node.run.system()*
-    Execute |nvim_tree.config.system_open|.
-
-    Parameters: ~
-      • {node}  (`nvim_tree.api.Node?`) directory or file
-
-show_info_popup({node})                 *nvim_tree.api.node.show_info_popup()*
-    Open a popup window showing: fullpath, size, accessed, modified, created.
-
-    Parameters: ~
-      • {node}  (`nvim_tree.api.Node?`) directory or file
-
 
 ==============================================================================
 API: tree                                                 *nvim-tree-api-tree*
@@ -3110,34 +3123,9 @@ toggle({opts})                                   *nvim_tree.api.tree.toggle()*
                 • {focus}? (`boolean`, default: true) Focus the tree when
                   opening.
 
-toggle_custom_filter()             *nvim_tree.api.tree.toggle_custom_filter()*
-    Toggle |nvim_tree.config.filters| {custom} filter.
-
-toggle_enable_filters()           *nvim_tree.api.tree.toggle_enable_filters()*
-    Toggle |nvim_tree.config.filters| {enable} all filters.
-
-                                *nvim_tree.api.tree.toggle_git_clean_filter()*
-toggle_git_clean_filter()
-    Toggle |nvim_tree.config.filters| {git_clean} filter.
-
-                                *nvim_tree.api.tree.toggle_gitignore_filter()*
-toggle_gitignore_filter()
-    Toggle |nvim_tree.config.filters| {git_ignored} filter.
-
 toggle_help()                               *nvim_tree.api.tree.toggle_help()*
     Toggle help view.
 
-toggle_hidden_filter()             *nvim_tree.api.tree.toggle_hidden_filter()*
-    Toggle |nvim_tree.config.filters| {dotfiles} filter.
-
-                              *nvim_tree.api.tree.toggle_no_bookmark_filter()*
-toggle_no_bookmark_filter()
-    Toggle |nvim_tree.config.filters| {no_bookmark} filter.
-
-                                *nvim_tree.api.tree.toggle_no_buffer_filter()*
-toggle_no_buffer_filter()
-    Toggle |nvim_tree.config.filters| {no_buffer} filter.
-
 winid({opts})                                     *nvim_tree.api.tree.winid()*
     Retrieve the window of the open tree.
 
diff --git a/lua/nvim-tree/_meta/api/filter.lua b/lua/nvim-tree/_meta/api/filter.lua
index 92a916ce292..e0b3ad9794e 100644
--- a/lua/nvim-tree/_meta/api/filter.lua
+++ b/lua/nvim-tree/_meta/api/filter.lua
@@ -1,17 +1,61 @@
 ---@meta
-local nvim_tree = { api = { filter = { live_filter = {} } } }
+local nvim_tree = { api = { filter = {} } }
 
+---
+---Toggle [nvim_tree.config.filters] {enable} all filters.
+---
+function nvim_tree.api.filter.toggle() end
 
--- TODO 3088 move tree filters in here
+nvim_tree.api.filter.live = {}
 
 ---
 ---Enter live filter mode. Opens an input window with [filetype] `NvimTreeFilter`
 ---
-function nvim_tree.api.filter.live_filter.start() end
+function nvim_tree.api.filter.live.start() end
 
 ---
 ---Exit live filter mode.
 ---
-function nvim_tree.api.filter.live_filter.clear() end
+function nvim_tree.api.filter.live.clear() end
+
+nvim_tree.api.filter.git = {}
+
+---
+---Toggle [nvim_tree.config.filters] {git_clean} filter.
+---
+function nvim_tree.api.filter.git.clean.toggle() end
+
+---
+---Toggle [nvim_tree.config.filters] {git_ignored} filter.
+---
+function nvim_tree.api.filter.git.ignored.toggle() end
+
+nvim_tree.api.filter.dotfiles = {}
+
+---
+---Toggle [nvim_tree.config.filters] {dotfiles} filter.
+---
+function nvim_tree.api.filter.dotfiles.toggle() end
+
+nvim_tree.api.filter.no_buffer = {}
+
+---
+---Toggle [nvim_tree.config.filters] {no_buffer} filter.
+---
+function nvim_tree.api.filter.no_buffer.toggle() end
+
+nvim_tree.api.filter.no_bookmark = {}
+
+---
+---Toggle [nvim_tree.config.filters] {no_bookmark} filter.
+---
+function nvim_tree.api.filter.no_bookmark.toggle() end
+
+nvim_tree.api.filter.custom = {}
+
+---
+---Toggle [nvim_tree.config.filters] {custom} filter.
+---
+function nvim_tree.api.filter.custom.toggle() end
 
 return nvim_tree.api.filter
diff --git a/lua/nvim-tree/_meta/api/node.lua b/lua/nvim-tree/_meta/api/node.lua
index 01005156564..9db6a93c295 100644
--- a/lua/nvim-tree/_meta/api/node.lua
+++ b/lua/nvim-tree/_meta/api/node.lua
@@ -1,18 +1,8 @@
 ---@meta
-local nvim_tree = { api = { node = { navigate = { sibling = {}, git = {}, diagnostics = {}, opened = {}, }, run = {}, open = {}, buffer = {}, } } }
-
----
----@class nvim_tree.api.node.open.Opts
----@inlinedoc
----
----Quits the tree when opening the file.
----(default: false)
----@field quit_on_open? boolean
----
----Keep focus in the tree when opening the file.
----(default: false)
----@field focus? boolean
+local nvim_tree = { api = { node = {} } }
 
+nvim_tree.api.node.navigate = require("nvim-tree._meta.api.node.navigate");
+nvim_tree.api.node.open = require("nvim-tree._meta.api.node.open");
 
 ---
 ---@class nvim_tree.api.node.buffer.RemoveOpts
@@ -23,6 +13,8 @@ local nvim_tree = { api = { node = { navigate = { sibling = {}, git = {}, diagno
 ---@field force? boolean
 
 
+nvim_tree.api.node.buffer = {}
+
 ---
 ---Deletes node's related buffer, if one exists. Executes [:bdelete] or [:bdelete]!
 ---
@@ -64,206 +56,8 @@ function nvim_tree.api.node.expand(node, opts) end
 ---Return `true` if `node` should be expanded. `expansion_count` is the total number of folders expanded.
 ---@field expand_until? fun(expansion_count: integer, node: Node): boolean
 
----
----Navigate to the next item showing diagnostic status.
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.diagnostics.next(node) end
-
----
----Navigate to the next item showing diagnostic status, recursively. Needs [nvim_tree.config.diagnostics] {show_on_dirs}
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.diagnostics.next_recursive(node) end
 
----
----Navigate to the previous item showing diagnostic status.
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.diagnostics.prev(node) end
-
----
----Navigate to the previous item showing diagnostic status, recursively. Needs [nvim_tree.config.diagnostics] {show_on_dirs}
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.diagnostics.prev_recursive(node) end
-
----
----Navigate to the next item showing git status.
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.git.next(node) end
-
----
----Navigate to the next item showing git status, recursively. Needs [nvim_tree.config.git] {show_on_dirs}
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.git.next_recursive(node) end
-
----
----Navigate to the next item showing git status, skipping `.gitignore`
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.git.next_skip_gitignored(node) end
-
----
----Navigate to the previous item showing git status.
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.git.prev(node) end
-
----
----Navigate to the previous item showing git status, recursively. Needs [nvim_tree.config.git] {show_on_dirs}
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.git.prev_recursive(node) end
-
----
----Navigate to the previous item showing git status, skipping `.gitignore`
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.git.prev_skip_gitignored(node) end
-
----
----Navigate to the next [bufloaded()] file.
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.opened.next(node) end
-
----
----Navigate to the previous [bufloaded()] file.
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.opened.prev(node) end
-
----
----Navigate to the parent directory of the node.
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.parent(node) end
-
----
----Navigate to the parent directory of the node, closing it.
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.parent_close(node) end
-
----
----Navigate to the first node in the current node's folder.
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.sibling.first(node) end
-
----
----Navigate to the last node in the current node's folder.
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.sibling.last(node) end
-
----
----Navigate to the next node in the current node's folder, wraps.
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.sibling.next(node) end
-
----
----Navigate to the previous node in the current node's folder, wraps.
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.sibling.prev(node) end
-
----
----Switch to window with selected file if it exists, open file otherwise.
----- file: open file using [:drop]
----- directory: expand or collapse
----- root: change directory up
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.open.drop(node) end
-
----
----- file: open as per [nvim_tree.config.actions.open_file]
----- directory: expand or collapse
----- root: change directory up
----
----@param node? nvim_tree.api.Node directory or file
----@param opts? nvim_tree.api.node.open.Opts optional
-function nvim_tree.api.node.open.edit(node, opts) end
-
----
----Open file in a new horizontal split.
----
----@param node? nvim_tree.api.Node file
----@param opts? nvim_tree.api.node.open.Opts optional
-function nvim_tree.api.node.open.horizontal(node, opts) end
-
----
----Open file in a new horizontal split without using the window picker.
----
----@param node? nvim_tree.api.Node file
----@param opts? nvim_tree.api.node.open.Opts optional
-function nvim_tree.api.node.open.horizontal_no_picker(node, opts) end
-
----
----Open file without using the window picker.
----
----@param node? nvim_tree.api.Node file
----@param opts? nvim_tree.api.node.open.Opts optional
-function nvim_tree.api.node.open.no_window_picker(node, opts) end
-
----
----Open file with ['bufhidden'] set to `delete`.
----
----@param node? nvim_tree.api.Node directory or file
----@param opts? nvim_tree.api.node.open.Opts optional
-function nvim_tree.api.node.open.preview(node, opts) end
-
----
----Open file with ['bufhidden'] set to `delete` without using the window picker.
----
----@param node? nvim_tree.api.Node directory or file
----@param opts? nvim_tree.api.node.open.Opts optional
-function nvim_tree.api.node.open.preview_no_picker(node, opts) end
-
----
----Open file in place: in the nvim-tree window.
----
----@param node? nvim_tree.api.Node file
-function nvim_tree.api.node.open.replace_tree_buffer(node) end
-
----
----Open file in a new tab.
----
----@param node? nvim_tree.api.Node directory or file
----@param opts? nvim_tree.api.node.open.Opts optional
-function nvim_tree.api.node.open.tab(node, opts) end
-
----
----Switch to tab containing window with selected file if it exists. Open file in new tab otherwise.
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.open.tab_drop(node) end
-
----
----Toggle [nvim_tree.config.renderer] {group_empty} for a directory. Needs {group_empty} set.
----
----@param node? nvim_tree.api.Node directory
----@param opts? nvim_tree.api.node.open.Opts optional
-function nvim_tree.api.node.open.toggle_group_empty(node, opts) end
-
----
----Open file in a new vertical split.
----
----@param node? nvim_tree.api.Node file
----@param opts? nvim_tree.api.node.open.Opts optional
-function nvim_tree.api.node.open.vertical(node, opts) end
-
----
----Open file in a new vertical split without using the window picker.
----
----@param node? nvim_tree.api.Node file
----@param opts? nvim_tree.api.node.open.Opts optional
-function nvim_tree.api.node.open.vertical_no_picker(node, opts) end
+nvim_tree.api.node.run = {}
 
 ---
 ---Enter [cmdline] with the full path of the node and the cursor at the start of the line.
diff --git a/lua/nvim-tree/_meta/api/node/navigate.lua b/lua/nvim-tree/_meta/api/node/navigate.lua
new file mode 100644
index 00000000000..b398b1b88fd
--- /dev/null
+++ b/lua/nvim-tree/_meta/api/node/navigate.lua
@@ -0,0 +1,120 @@
+---@meta
+local nvim_tree = { api = { node = { navigate = {}, } } }
+
+---
+---Navigate to the parent directory of the node.
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.parent(node) end
+
+---
+---Navigate to the parent directory of the node, closing it.
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.parent_close(node) end
+
+nvim_tree.api.node.navigate.diagnostics = {}
+
+---
+---Navigate to the next item showing diagnostic status.
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.diagnostics.next(node) end
+
+---
+---Navigate to the next item showing diagnostic status, recursively. Needs [nvim_tree.config.diagnostics] {show_on_dirs}
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.diagnostics.next_recursive(node) end
+
+---
+---Navigate to the previous item showing diagnostic status.
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.diagnostics.prev(node) end
+
+---
+---Navigate to the previous item showing diagnostic status, recursively. Needs [nvim_tree.config.diagnostics] {show_on_dirs}
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.diagnostics.prev_recursive(node) end
+
+nvim_tree.api.node.navigate.git = {}
+
+---
+---Navigate to the next item showing git status.
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.git.next(node) end
+
+---
+---Navigate to the next item showing git status, recursively. Needs [nvim_tree.config.git] {show_on_dirs}
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.git.next_recursive(node) end
+
+---
+---Navigate to the next item showing git status, skipping `.gitignore`
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.git.next_skip_gitignored(node) end
+
+---
+---Navigate to the previous item showing git status.
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.git.prev(node) end
+
+---
+---Navigate to the previous item showing git status, recursively. Needs [nvim_tree.config.git] {show_on_dirs}
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.git.prev_recursive(node) end
+
+---
+---Navigate to the previous item showing git status, skipping `.gitignore`
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.git.prev_skip_gitignored(node) end
+
+nvim_tree.api.node.navigate.opened = {}
+
+---
+---Navigate to the next [bufloaded()] file.
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.opened.next(node) end
+
+---
+---Navigate to the previous [bufloaded()] file.
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.opened.prev(node) end
+
+nvim_tree.api.node.navigate.sibling = {}
+
+---
+---Navigate to the first node in the current node's folder.
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.sibling.first(node) end
+
+---
+---Navigate to the last node in the current node's folder.
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.sibling.last(node) end
+
+---
+---Navigate to the next node in the current node's folder, wraps.
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.sibling.next(node) end
+
+---
+---Navigate to the previous node in the current node's folder, wraps.
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.sibling.prev(node) end
+
+return nvim_tree.api.node.navigate
diff --git a/lua/nvim-tree/_meta/api/node/open.lua b/lua/nvim-tree/_meta/api/node/open.lua
new file mode 100644
index 00000000000..1b33bf2346e
--- /dev/null
+++ b/lua/nvim-tree/_meta/api/node/open.lua
@@ -0,0 +1,101 @@
+---@meta
+local nvim_tree = { api = { node = { open = {}, } } }
+
+---
+---@class nvim_tree.api.node.open.Opts
+---@inlinedoc
+---
+---Quits the tree when opening the file.
+---(default: false)
+---@field quit_on_open? boolean
+---
+---Keep focus in the tree when opening the file.
+---(default: false)
+---@field focus? boolean
+
+
+---
+---- file: open as per [nvim_tree.config.actions.open_file]
+---- directory: expand or collapse
+---- root: change directory up
+---
+---@param node? nvim_tree.api.Node directory or file
+---@param opts? nvim_tree.api.node.open.Opts optional
+function nvim_tree.api.node.open.edit(node, opts) end
+
+---
+---Open file in a new horizontal split.
+---
+---@param node? nvim_tree.api.Node file
+---@param opts? nvim_tree.api.node.open.Opts optional
+function nvim_tree.api.node.open.horizontal(node, opts) end
+
+---
+---Open file in a new horizontal split without using the window picker.
+---
+---@param node? nvim_tree.api.Node file
+---@param opts? nvim_tree.api.node.open.Opts optional
+function nvim_tree.api.node.open.horizontal_no_picker(node, opts) end
+
+---
+---Open file without using the window picker.
+---
+---@param node? nvim_tree.api.Node file
+---@param opts? nvim_tree.api.node.open.Opts optional
+function nvim_tree.api.node.open.no_window_picker(node, opts) end
+
+---
+---Open file with ['bufhidden'] set to `delete`.
+---
+---@param node? nvim_tree.api.Node directory or file
+---@param opts? nvim_tree.api.node.open.Opts optional
+function nvim_tree.api.node.open.preview(node, opts) end
+
+---
+---Open file with ['bufhidden'] set to `delete` without using the window picker.
+---
+---@param node? nvim_tree.api.Node directory or file
+---@param opts? nvim_tree.api.node.open.Opts optional
+function nvim_tree.api.node.open.preview_no_picker(node, opts) end
+
+---
+---Open file in place: in the nvim-tree window.
+---
+---@param node? nvim_tree.api.Node file
+function nvim_tree.api.node.open.replace_tree_buffer(node) end
+
+---
+---Open file in a new tab.
+---
+---@param node? nvim_tree.api.Node directory or file
+---@param opts? nvim_tree.api.node.open.Opts optional
+function nvim_tree.api.node.open.tab(node, opts) end
+
+---
+---Switch to tab containing window with selected file if it exists. Open file in new tab otherwise.
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.open.tab_drop(node) end
+
+---
+---Toggle [nvim_tree.config.renderer] {group_empty} for a directory. Needs {group_empty} set.
+---
+---@param node? nvim_tree.api.Node directory
+---@param opts? nvim_tree.api.node.open.Opts optional
+function nvim_tree.api.node.open.toggle_group_empty(node, opts) end
+
+---
+---Open file in a new vertical split.
+---
+---@param node? nvim_tree.api.Node file
+---@param opts? nvim_tree.api.node.open.Opts optional
+function nvim_tree.api.node.open.vertical(node, opts) end
+
+---
+---Open file in a new vertical split without using the window picker.
+---
+---@param node? nvim_tree.api.Node file
+---@param opts? nvim_tree.api.node.open.Opts optional
+function nvim_tree.api.node.open.vertical_no_picker(node, opts) end
+
+return nvim_tree.api.node.open
diff --git a/lua/nvim-tree/_meta/api/tree.lua b/lua/nvim-tree/_meta/api/tree.lua
index 363e6ccea8b..54c2185f905 100644
--- a/lua/nvim-tree/_meta/api/tree.lua
+++ b/lua/nvim-tree/_meta/api/tree.lua
@@ -185,41 +185,6 @@ function nvim_tree.api.tree.collapse_all(opts) end
 ---@param opts? nvim_tree.api.node.expand.Opts optional
 function nvim_tree.api.tree.expand_all(node, opts) end
 
----
----Toggle [nvim_tree.config.filters] {enable} all filters.
----
-function nvim_tree.api.tree.toggle_enable_filters() end
-
----
----Toggle [nvim_tree.config.filters] {git_ignored} filter.
----
-function nvim_tree.api.tree.toggle_gitignore_filter() end
-
----
----Toggle [nvim_tree.config.filters] {dotfiles} filter.
----
-function nvim_tree.api.tree.toggle_hidden_filter() end
-
----
----Toggle [nvim_tree.config.filters] {git_clean} filter.
----
-function nvim_tree.api.tree.toggle_git_clean_filter() end
-
----
----Toggle [nvim_tree.config.filters] {no_buffer} filter.
----
-function nvim_tree.api.tree.toggle_no_buffer_filter() end
-
----
----Toggle [nvim_tree.config.filters] {no_bookmark} filter.
----
-function nvim_tree.api.tree.toggle_no_bookmark_filter() end
-
----
----Toggle [nvim_tree.config.filters] {custom} filter.
----
-function nvim_tree.api.tree.toggle_custom_filter() end
-
 ---
 ---Toggle help view.
 ---
diff --git a/lua/nvim-tree/_meta/config/filters.lua b/lua/nvim-tree/_meta/config/filters.lua
index b126c060692..746bc5f1a36 100644
--- a/lua/nvim-tree/_meta/config/filters.lua
+++ b/lua/nvim-tree/_meta/config/filters.lua
@@ -9,27 +9,27 @@ error("Cannot require a meta file")
 ---
 ---Filters can be set at startup or toggled live via API with default mappings.
 ---
----`I     `{git_ignored}`         `|nvim_tree.api.tree.toggle_gitignore_filter()|
+---`I     `{git_ignored}`         `|nvim_tree.api.filter.git.ignored.toggle()|
 ---Ignore files based on `.gitignore`. Requires |nvim_tree.config.git|
 ---
----`H     `{dotfiles}`            `|nvim_tree.api.tree.toggle_hidden_filter()|
+---`H     `{dotfiles}`            `|nvim_tree.api.filter.dotfiles.toggle()|
 ---Filter dotfiles: files/directories starting with a `.`
 ---
----`C     `{git_clean}`           `|nvim_tree.api.tree.toggle_git_clean_filter()|
+---`C     `{git_clean}`           `|nvim_tree.api.filter.git.clean.toggle()|
 ---Filter files with no git status. `.gitignore` files will not be filtered when {git_ignored}, as they are effectively dirty.
 ---
----`B     `{no_buffer}`           `|nvim_tree.api.tree.toggle_no_buffer_filter()|
+---`B     `{no_buffer}`           `|nvim_tree.api.filter.no_buffer.toggle()|
 ---Filter files that have no |buflisted()| buffer. For performance reasons buffer delete/wipe may not be immediately shown. A reload or filesystem event will always result in an update.
 ---
----`M     `{no_bookmark}`         `|nvim_tree.api.tree.toggle_no_bookmark_filter()|
+---`M     `{no_bookmark}`         `|nvim_tree.api.filter.no_bookmark.toggle()|
 ---Filter files that are not bookmarked. Enabling this is not useful as there is no means yet to persist bookmarks.
 ---
----`U     `{custom}`              `|nvim_tree.api.tree.toggle_custom_filter()|
+---`U     `{custom}`              `|nvim_tree.api.filter.custom.toggle()|
 ---Disable specific file/directory names via:
 ---- a list of backslash escaped |vim.regex| strings e.g. `"^\\.git""`
 ---- a function passed the absolute path of the directory.
 ---
----All filters including live filter may be disabled via {enable} and toggled with |nvim_tree.api.tree.toggle_enable_filters()|
+---All filters including live filter may be disabled via {enable} and toggled with |nvim_tree.api.filter.toggle()|
 ---
 ---Files/directories may be {exclude}d from filtering: they will always be shown, overriding {git_ignored}, {dotfiles} and {custom}.
 ---@class nvim_tree.config.filters
diff --git a/lua/nvim-tree/api-impl.lua b/lua/nvim-tree/api-impl.lua
index 9bca35523c6..f316d1fca06 100644
--- a/lua/nvim-tree/api-impl.lua
+++ b/lua/nvim-tree/api-impl.lua
@@ -136,13 +136,6 @@ return function(api)
   api.tree.collapse_all = wrap(actions.tree.modifiers.collapse.all)
 
   api.tree.expand_all = wrap_node(actions.tree.modifiers.expand.all)
-  api.tree.toggle_enable_filters = wrap_explorer_member("filters", "toggle")
-  api.tree.toggle_gitignore_filter = wrap_explorer_member_args("filters", "toggle", "git_ignored")
-  api.tree.toggle_git_clean_filter = wrap_explorer_member_args("filters", "toggle", "git_clean")
-  api.tree.toggle_no_buffer_filter = wrap_explorer_member_args("filters", "toggle", "no_buffer")
-  api.tree.toggle_custom_filter = wrap_explorer_member_args("filters", "toggle", "custom")
-  api.tree.toggle_hidden_filter = wrap_explorer_member_args("filters", "toggle", "dotfiles")
-  api.tree.toggle_no_bookmark_filter = wrap_explorer_member_args("filters", "toggle", "no_bookmark")
   api.tree.toggle_help = wrap(help.toggle)
   api.tree.is_tree_buf = wrap(utils.is_nvim_tree_buf)
 
@@ -275,8 +268,15 @@ return function(api)
   api.events.subscribe = events.subscribe
   api.events.Event = events.Event
 
-  api.filter.live_filter.start = wrap_explorer_member("live_filter", "start_filtering")
-  api.filter.live_filter.clear = wrap_explorer_member("live_filter", "clear_filter")
+  api.filter.live.start = wrap_explorer_member("live_filter", "start_filtering")
+  api.filter.live.clear = wrap_explorer_member("live_filter", "clear_filter")
+  api.filter.toggle = wrap_explorer_member("filters", "toggle")
+  api.filter.git.ignored.toggle = wrap_explorer_member_args("filters", "toggle", "git_ignored")
+  api.filter.git.clean.toggle = wrap_explorer_member_args("filters", "toggle", "git_clean")
+  api.filter.no_buffer.toggle = wrap_explorer_member_args("filters", "toggle", "no_buffer")
+  api.filter.custom.toggle = wrap_explorer_member_args("filters", "toggle", "custom")
+  api.filter.dotfiles.toggle = wrap_explorer_member_args("filters", "toggle", "dotfiles")
+  api.filter.no_bookmark.toggle = wrap_explorer_member_args("filters", "toggle", "no_bookmark")
 
   api.marks.get = wrap_node(wrap_explorer_member("marks", "get"))
   api.marks.list = wrap_explorer_member("marks", "list")
@@ -313,8 +313,8 @@ return function(api)
     reload = api.tree.reload_git,
   }
   api.live_filter = {
-    start = api.filter.live_filter.start,
-    clear = api.filter.live_filter.clear,
+    start = api.filter.live.start,
+    clear = api.filter.live.clear,
   }
   api.config = {
     mappings = {
diff --git a/lua/nvim-tree/keymap.lua b/lua/nvim-tree/keymap.lua
index 1758b7f9bdc..22848750921 100644
--- a/lua/nvim-tree/keymap.lua
+++ b/lua/nvim-tree/keymap.lua
@@ -63,9 +63,9 @@ function M.default_on_attach(bufnr)
   vim.keymap.set("n", "bd",             api.marks.bulk.delete,              opts("Delete Bookmarked"))
   vim.keymap.set("n", "bt",             api.marks.bulk.trash,               opts("Trash Bookmarked"))
   vim.keymap.set("n", "bmv",            api.marks.bulk.move,                opts("Move Bookmarked"))
-  vim.keymap.set("n", "B",              api.tree.toggle_no_buffer_filter,   opts("Toggle Filter: No Buffer"))
+  vim.keymap.set("n", "B",              api.filter.no_buffer.toggle,        opts("Toggle Filter: No Buffer"))
   vim.keymap.set("n", "c",              api.fs.copy.node,                   opts("Copy"))
-  vim.keymap.set("n", "C",              api.tree.toggle_git_clean_filter,   opts("Toggle Filter: Git Clean"))
+  vim.keymap.set("n", "C",              api.filter.git.clean.toggle,        opts("Toggle Filter: Git Clean"))
   vim.keymap.set("n", "[c",             api.node.navigate.git.prev,         opts("Prev Git"))
   vim.keymap.set("n", "]c",             api.node.navigate.git.next,         opts("Next Git"))
   vim.keymap.set("n", "d",              api.fs.remove,                      opts("Delete"))
@@ -74,17 +74,17 @@ function M.default_on_attach(bufnr)
   vim.keymap.set("n", "e",              api.fs.rename_basename,             opts("Rename: Basename"))
   vim.keymap.set("n", "]e",             api.node.navigate.diagnostics.next, opts("Next Diagnostic"))
   vim.keymap.set("n", "[e",             api.node.navigate.diagnostics.prev, opts("Prev Diagnostic"))
-  vim.keymap.set("n", "F",              api.filter.live_filter.clear,       opts("Live Filter: Clear"))
-  vim.keymap.set("n", "f",              api.filter.live_filter.start,       opts("Live Filter: Start"))
+  vim.keymap.set("n", "F",              api.filter.live.clear,              opts("Live Filter: Clear"))
+  vim.keymap.set("n", "f",              api.filter.live.start,              opts("Live Filter: Start"))
   vim.keymap.set("n", "g?",             api.tree.toggle_help,               opts("Help"))
   vim.keymap.set("n", "gy",             api.fs.copy.absolute_path,          opts("Copy Absolute Path"))
   vim.keymap.set("n", "ge",             api.fs.copy.basename,               opts("Copy Basename"))
-  vim.keymap.set("n", "H",              api.tree.toggle_hidden_filter,      opts("Toggle Filter: Dotfiles"))
-  vim.keymap.set("n", "I",              api.tree.toggle_gitignore_filter,   opts("Toggle Filter: Git Ignore"))
+  vim.keymap.set("n", "H",              api.filter.dotfiles.toggle,         opts("Toggle Filter: Dotfiles"))
+  vim.keymap.set("n", "I",              api.filter.git.ignored.toggle,      opts("Toggle Filter: Git Ignore"))
   vim.keymap.set("n", "J",              api.node.navigate.sibling.last,     opts("Last Sibling"))
   vim.keymap.set("n", "K",              api.node.navigate.sibling.first,    opts("First Sibling"))
   vim.keymap.set("n", "L",              api.node.open.toggle_group_empty,   opts("Toggle Group Empty"))
-  vim.keymap.set("n", "M",              api.tree.toggle_no_bookmark_filter, opts("Toggle Filter: No Bookmark"))
+  vim.keymap.set("n", "M",              api.filter.no_bookmark.toggle,      opts("Toggle Filter: No Bookmark"))
   vim.keymap.set("n", "m",              api.marks.toggle,                   opts("Toggle Bookmark"))
   vim.keymap.set("n", "o",              api.node.open.edit,                 opts("Open"))
   vim.keymap.set("n", "O",              api.node.open.no_window_picker,     opts("Open: No Window Picker"))
@@ -96,7 +96,7 @@ function M.default_on_attach(bufnr)
   vim.keymap.set("n", "s",              api.node.run.system,                opts("Run System"))
   vim.keymap.set("n", "S",              api.tree.search_node,               opts("Search"))
   vim.keymap.set("n", "u",              api.fs.rename_full,                 opts("Rename: Full Path"))
-  vim.keymap.set("n", "U",              api.tree.toggle_custom_filter,      opts("Toggle Filter: Hidden"))
+  vim.keymap.set("n", "U",              api.filter.custom.toggle,           opts("Toggle Filter: Hidden"))
   vim.keymap.set("n", "W",              api.tree.collapse_all,              opts("Collapse All"))
   vim.keymap.set("n", "x",              api.fs.cut,                         opts("Cut"))
   vim.keymap.set("n", "y",              api.fs.copy.filename,               opts("Copy Name"))
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index ac3224248bc..9e82e185985 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -47,6 +47,8 @@ local srcs = {
   { helptag = "nvim-tree-api-map",                    section = "API: map",                    path = "./lua/nvim_tree/_meta/api/map.lua", },
   { helptag = "nvim-tree-api-marks",                  section = "API: marks",                  path = "./lua/nvim_tree/_meta/api/marks.lua", },
   { helptag = "nvim-tree-api-node",                   section = "API: node",                   path = "./lua/nvim_tree/_meta/api/node.lua", },
+  { helptag = "nvim-tree-api-node-navigate",          section = "API: node.navigate",          path = "./lua/nvim_tree/_meta/api/node/navigate.lua", },
+  { helptag = "nvim-tree-api-node-open",              section = "API: node.open",              path = "./lua/nvim_tree/_meta/api/node/open.lua", },
   { helptag = "nvim-tree-api-tree",                   section = "API: tree",                   path = "./lua/nvim_tree/_meta/api/tree.lua", },
 
   { helptag = "nvim-tree-api-classes",                section = "API: Classes",                path = "./lua/nvim_tree/_meta/api/classes.lua", },

From 48de5e03696b4dfbf5cbcd36083338253473a565 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 22 Jan 2026 17:48:36 +1100
Subject: [PATCH 125/170] docs(#3088): hidden->custom toggle default desc

---
 doc/nvim-tree-lua.txt    | 8 ++++----
 lua/nvim-tree/keymap.lua | 4 ++--
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index dfa12813fbd..8dfa6692259 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -141,7 +141,7 @@ Show the mappings:  `g?`
 `gy`              Copy Absolute Path         |nvim_tree.api.fs.copy.absolute_path()|
 `ge`              Copy Basename              |nvim_tree.api.fs.copy.basename()|
 `H`               Toggle Filter: Dotfiles    |nvim_tree.api.filter.dotfiles.toggle()|
-`I`               Toggle Filter: Git Ignore  |nvim_tree.api.filter.git.ignored.toggle()|
+`I`               Toggle Filter: Git Ignored |nvim_tree.api.filter.git.ignored.toggle()|
 `J`               Last Sibling               |nvim_tree.api.node.navigate.sibling.last()|
 `K`               First Sibling              |nvim_tree.api.node.navigate.sibling.first()|
 `L`               Toggle Group Empty         |nvim_tree.api.node.open.toggle_group_empty()|
@@ -157,7 +157,7 @@ Show the mappings:  `g?`
 `s`               Run System                 |nvim_tree.api.node.run.system()|
 `S`               Search                     |nvim_tree.api.tree.search_node()|
 `u`               Rename: Full Path          |nvim_tree.api.fs.rename_full()|
-`U`               Toggle Filter: Hidden      |nvim_tree.api.filter.custom.toggle()|
+`U`               Toggle Filter: Custom      |nvim_tree.api.filter.custom.toggle()|
 `W`               Collapse All               |nvim_tree.api.tree.collapse_all()|
 `x`               Cut                        |nvim_tree.api.fs.cut()|
 `y`               Copy Name                  |nvim_tree.api.fs.copy.filename()|
@@ -428,7 +428,7 @@ You are encouraged to copy these to your {on_attach} function. >lua
   vim.keymap.set("n", "gy",             api.fs.copy.absolute_path,          opts("Copy Absolute Path"))
   vim.keymap.set("n", "ge",             api.fs.copy.basename,               opts("Copy Basename"))
   vim.keymap.set("n", "H",              api.filter.dotfiles.toggle,         opts("Toggle Filter: Dotfiles"))
-  vim.keymap.set("n", "I",              api.filter.git.ignored.toggle,      opts("Toggle Filter: Git Ignore"))
+  vim.keymap.set("n", "I",              api.filter.git.ignored.toggle,      opts("Toggle Filter: Git Ignored"))
   vim.keymap.set("n", "J",              api.node.navigate.sibling.last,     opts("Last Sibling"))
   vim.keymap.set("n", "K",              api.node.navigate.sibling.first,    opts("First Sibling"))
   vim.keymap.set("n", "L",              api.node.open.toggle_group_empty,   opts("Toggle Group Empty"))
@@ -444,7 +444,7 @@ You are encouraged to copy these to your {on_attach} function. >lua
   vim.keymap.set("n", "s",              api.node.run.system,                opts("Run System"))
   vim.keymap.set("n", "S",              api.tree.search_node,               opts("Search"))
   vim.keymap.set("n", "u",              api.fs.rename_full,                 opts("Rename: Full Path"))
-  vim.keymap.set("n", "U",              api.filter.custom.toggle,           opts("Toggle Filter: Hidden"))
+  vim.keymap.set("n", "U",              api.filter.custom.toggle,           opts("Toggle Filter: Custom"))
   vim.keymap.set("n", "W",              api.tree.collapse_all,              opts("Collapse All"))
   vim.keymap.set("n", "x",              api.fs.cut,                         opts("Cut"))
   vim.keymap.set("n", "y",              api.fs.copy.filename,               opts("Copy Name"))
diff --git a/lua/nvim-tree/keymap.lua b/lua/nvim-tree/keymap.lua
index 22848750921..09481b0b831 100644
--- a/lua/nvim-tree/keymap.lua
+++ b/lua/nvim-tree/keymap.lua
@@ -80,7 +80,7 @@ function M.default_on_attach(bufnr)
   vim.keymap.set("n", "gy",             api.fs.copy.absolute_path,          opts("Copy Absolute Path"))
   vim.keymap.set("n", "ge",             api.fs.copy.basename,               opts("Copy Basename"))
   vim.keymap.set("n", "H",              api.filter.dotfiles.toggle,         opts("Toggle Filter: Dotfiles"))
-  vim.keymap.set("n", "I",              api.filter.git.ignored.toggle,      opts("Toggle Filter: Git Ignore"))
+  vim.keymap.set("n", "I",              api.filter.git.ignored.toggle,      opts("Toggle Filter: Git Ignored"))
   vim.keymap.set("n", "J",              api.node.navigate.sibling.last,     opts("Last Sibling"))
   vim.keymap.set("n", "K",              api.node.navigate.sibling.first,    opts("First Sibling"))
   vim.keymap.set("n", "L",              api.node.open.toggle_group_empty,   opts("Toggle Group Empty"))
@@ -96,7 +96,7 @@ function M.default_on_attach(bufnr)
   vim.keymap.set("n", "s",              api.node.run.system,                opts("Run System"))
   vim.keymap.set("n", "S",              api.tree.search_node,               opts("Search"))
   vim.keymap.set("n", "u",              api.fs.rename_full,                 opts("Rename: Full Path"))
-  vim.keymap.set("n", "U",              api.filter.custom.toggle,           opts("Toggle Filter: Hidden"))
+  vim.keymap.set("n", "U",              api.filter.custom.toggle,           opts("Toggle Filter: Custom"))
   vim.keymap.set("n", "W",              api.tree.collapse_all,              opts("Collapse All"))
   vim.keymap.set("n", "x",              api.fs.cut,                         opts("Cut"))
   vim.keymap.set("n", "y",              api.fs.copy.filename,               opts("Copy Name"))

From e47079e5fd262fe70802355f46c78285aa92467e Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 22 Jan 2026 18:05:34 +1100
Subject: [PATCH 126/170] docs(#3088): add legacy filter api mappings

---
 doc/nvim-tree-lua.txt              | 24 ++++++++++++++++--------
 lua/nvim-tree/_meta/api/filter.lua |  4 ++--
 lua/nvim-tree/api-impl.lua         | 10 ++++++++++
 3 files changed, 28 insertions(+), 10 deletions(-)

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 8dfa6692259..17efacf369f 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -1005,16 +1005,24 @@ Legacy: API                                             *nvim-tree-legacy-api*
 Some API functions have been refactored however the previous function will
 continue to be available.
 
-`api.config.mappings.get_keymap`          |nvim_tree.api.map.get_keymap()|
-`api.config.mappings.get_keymap_default`  |nvim_tree.api.map.get_keymap_default()|
-`api.config.mappings.default_on_attach`   |nvim_tree.api.map.default_on_attach()|
+`api.config.mappings.get_keymap`         |nvim_tree.api.map.get_keymap()|
+`api.config.mappings.get_keymap_default` |nvim_tree.api.map.get_keymap_default()|
+`api.config.mappings.default_on_attach`  |nvim_tree.api.map.default_on_attach()|
 
-`api.diagnostics.hi_test`                 |nvim_tree.api.health.hi_test()|
+`api.diagnostics.hi_test`                |nvim_tree.api.health.hi_test()|
 
-`api.git.reload`                          |nvim_tree.api.tree.reload_git()|
+`api.git.reload`                         |nvim_tree.api.tree.reload_git()|
 
-`api.live_filter.start`                   |nvim_tree.api.filter.live.start()|
-`api.live_filter.clear`                   |nvim_tree.api.filter.live.clear()|
+`api.live_filter.start`                  |nvim_tree.api.filter.live.start()|
+`api.live_filter.clear`                  |nvim_tree.api.filter.live.clear()|
+
+`api.tree.toggle_enable_filters`         |nvim_tree.api.filter.toggle()|
+`api.tree.toggle_gitignore_filter`       |nvim_tree.api.filter.git.ignored.toggle()|
+`api.tree.toggle_git_clean_filter`       |nvim_tree.api.filter.git.clean.toggle()|
+`api.tree.toggle_no_buffer_filter`       |nvim_tree.api.filter.no_buffer.toggle()|
+`api.tree.toggle_custom_filter`          |nvim_tree.api.filter.custom.toggle()|
+`api.tree.toggle_hidden_filter`          |nvim_tree.api.filter.dotfiles.toggle()|
+`api.tree.toggle_no_bookmark_filter`     |nvim_tree.api.filter.no_bookmark.toggle()|
 
 ==============================================================================
 Legacy: Highlight                                 *nvim-tree-legacy-highlight*
@@ -2440,7 +2448,7 @@ no_buffer.toggle()                   *nvim_tree.api.filter.no_buffer.toggle()*
     Toggle |nvim_tree.config.filters| {no_buffer} filter.
 
 toggle()                                       *nvim_tree.api.filter.toggle()*
-    Toggle |nvim_tree.config.filters| {enable} all filters.
+    Toggle |nvim_tree.config.filters| {enable} which applies to ALL filters.
 
 
 ==============================================================================
diff --git a/lua/nvim-tree/_meta/api/filter.lua b/lua/nvim-tree/_meta/api/filter.lua
index e0b3ad9794e..d28172f483d 100644
--- a/lua/nvim-tree/_meta/api/filter.lua
+++ b/lua/nvim-tree/_meta/api/filter.lua
@@ -2,7 +2,7 @@
 local nvim_tree = { api = { filter = {} } }
 
 ---
----Toggle [nvim_tree.config.filters] {enable} all filters.
+---Toggle [nvim_tree.config.filters] {enable} which applies to ALL filters.
 ---
 function nvim_tree.api.filter.toggle() end
 
@@ -18,7 +18,7 @@ function nvim_tree.api.filter.live.start() end
 ---
 function nvim_tree.api.filter.live.clear() end
 
-nvim_tree.api.filter.git = {}
+nvim_tree.api.filter.git = { clean = {}, ignored = {} }
 
 ---
 ---Toggle [nvim_tree.config.filters] {git_clean} filter.
diff --git a/lua/nvim-tree/api-impl.lua b/lua/nvim-tree/api-impl.lua
index f316d1fca06..8a977fdff33 100644
--- a/lua/nvim-tree/api-impl.lua
+++ b/lua/nvim-tree/api-impl.lua
@@ -312,10 +312,19 @@ return function(api)
   api.git = {
     reload = api.tree.reload_git,
   }
+
   api.live_filter = {
     start = api.filter.live.start,
     clear = api.filter.live.clear,
   }
+  api.tree.toggle_enable_filters = api.filter.toggle
+  api.tree.toggle_gitignore_filter = api.filter.git.ignored.toggle
+  api.tree.toggle_git_clean_filter = api.filter.git.clean.toggle
+  api.tree.toggle_no_buffer_filter = api.filter.no_buffer.toggle
+  api.tree.toggle_custom_filter = api.filter.custom.toggle
+  api.tree.toggle_hidden_filter = api.filter.dotfiles.toggle
+  api.tree.toggle_no_bookmark_filter = api.filter.no_bookmark.toggle
+
   api.config = {
     mappings = {
       get_keymap = api.map.get_keymap,
@@ -323,6 +332,7 @@ return function(api)
       default_on_attach = api.map.default_on_attach,
     }
   }
+
   api.diagnostics = {
     hi_test = api.health.hi_test,
   }

From 98c3655b965aa02b846831df96ace6469701c0a0 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 22 Jan 2026 18:33:32 +1100
Subject: [PATCH 127/170] docs(#3088): tidy api meta

---
 lua/nvim-tree/_meta/api/fs.lua    |  4 +++-
 lua/nvim-tree/_meta/api/marks.lua |  6 +++++-
 lua/nvim-tree/api.lua             | 22 +++++++++++-----------
 3 files changed, 19 insertions(+), 13 deletions(-)

diff --git a/lua/nvim-tree/_meta/api/fs.lua b/lua/nvim-tree/_meta/api/fs.lua
index 94fe7ea1d41..1cac6e00409 100644
--- a/lua/nvim-tree/_meta/api/fs.lua
+++ b/lua/nvim-tree/_meta/api/fs.lua
@@ -1,11 +1,13 @@
 ---@meta
-local nvim_tree = { api = { fs = { copy = {} } } }
+local nvim_tree = { api = { fs = {} } }
 
 ---
 ---Clear the nvim-tree clipboard.
 ---
 function nvim_tree.api.fs.clear_clipboard() end
 
+nvim_tree.api.fs.copy = {}
+
 ---
 ---Copy the absolute path to the system clipboard.
 ---
diff --git a/lua/nvim-tree/_meta/api/marks.lua b/lua/nvim-tree/_meta/api/marks.lua
index 81b8d295091..bb555a96fd0 100644
--- a/lua/nvim-tree/_meta/api/marks.lua
+++ b/lua/nvim-tree/_meta/api/marks.lua
@@ -1,5 +1,5 @@
 ---@meta
-local nvim_tree = { api = { marks = { bulk = {}, navigate = {}, } } }
+local nvim_tree = { api = { marks = {} } }
 
 ---
 ---Return the node if it is marked.
@@ -24,6 +24,8 @@ function nvim_tree.api.marks.toggle(node) end
 ---
 function nvim_tree.api.marks.clear() end
 
+nvim_tree.api.marks.bulk = {}
+
 ---
 ---Delete all marked, prompting if [nvim_tree.config.ui.confirm] {remove}
 ---
@@ -39,6 +41,8 @@ function nvim_tree.api.marks.bulk.trash() end
 ---
 function nvim_tree.api.marks.bulk.move() end
 
+nvim_tree.api.marks.navigate = {}
+
 ---
 ---Navigate to the next marked node, wraps.
 ---
diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index b5d29fc1833..181a9aa6b79 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -1,3 +1,5 @@
+local api = {}
+
 ---@brief
 ---nvim-tree exposes a public API. This is non breaking, with additions made as necessary.
 ---
@@ -35,17 +37,15 @@
 --
 --Load the (empty) meta definitions
 --
-local api = {
-  commands = require("nvim-tree._meta.api.commands"),
-  events = require("nvim-tree._meta.api.events"),
-  filter = require("nvim-tree._meta.api.filter"),
-  fs = require("nvim-tree._meta.api.fs"),
-  health = require("nvim-tree._meta.api.health"),
-  map = require("nvim-tree._meta.api.map"),
-  marks = require("nvim-tree._meta.api.marks"),
-  node = require("nvim-tree._meta.api.node"),
-  tree = require("nvim-tree._meta.api.tree"),
-}
+api.commands = require("nvim-tree._meta.api.commands")
+api.events = require("nvim-tree._meta.api.events")
+api.filter = require("nvim-tree._meta.api.filter")
+api.fs = require("nvim-tree._meta.api.fs")
+api.health = require("nvim-tree._meta.api.health")
+api.map = require("nvim-tree._meta.api.map")
+api.marks = require("nvim-tree._meta.api.marks")
+api.node = require("nvim-tree._meta.api.node")
+api.tree = require("nvim-tree._meta.api.tree")
 
 
 --

From 9d4a117c47831af0209b3d5c20caa7b6e70d07b1 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 22 Jan 2026 18:38:52 +1100
Subject: [PATCH 128/170] docs(#3088): always exclude meta from luacheck, it
 doesn't offer anything useful

---
 Makefile | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/Makefile b/Makefile
index 223070c84d8..30f712ed6a6 100644
--- a/Makefile
+++ b/Makefile
@@ -12,11 +12,8 @@ check: luals
 #
 # subtasks
 #
-# TODO #3241 ensure that decorator is checked - all meta should be valid
-# TODO #3088 check api
 luacheck:
-	# luacheck --codes --quiet lua --exclude-files "**/_meta/api_decorator.lua"
-	luacheck --codes --quiet lua --exclude-files "**/_meta/api*"
+	luacheck --codes --quiet lua --exclude-files "**/_meta/**"
 	luacheck --codes --quiet scripts
 
 style-check:

From 69396196bfc58707f0e7bf65e7e0fa60dea98363 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Fri, 23 Jan 2026 16:01:28 +1100
Subject: [PATCH 129/170] docs(#3088): extract fs.copy, fix api node param
 optionality, move legacy api to legacy.lua

---
 doc/nvim-tree-lua.txt               | 92 +++++++++++++++--------------
 lua/nvim-tree/_meta/api/fs.lua      | 54 ++++-------------
 lua/nvim-tree/_meta/api/fs/copy.lua | 34 +++++++++++
 lua/nvim-tree/_meta/api/marks.lua   |  2 +-
 lua/nvim-tree/_meta/api/node.lua    |  2 +-
 lua/nvim-tree/_meta/api/tree.lua    |  4 +-
 lua/nvim-tree/api-impl.lua          | 32 ----------
 lua/nvim-tree/api.lua               |  3 +-
 lua/nvim-tree/legacy.lua            | 41 +++++++++++++
 scripts/gen_vimdoc_config.lua       |  1 +
 10 files changed, 142 insertions(+), 123 deletions(-)
 create mode 100644 lua/nvim-tree/_meta/api/fs/copy.lua

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 17efacf369f..26649dba5df 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -2457,36 +2457,6 @@ API: fs                                                     *nvim-tree-api-fs*
 clear_clipboard()                         *nvim_tree.api.fs.clear_clipboard()*
     Clear the nvim-tree clipboard.
 
-copy.absolute_path({node})             *nvim_tree.api.fs.copy.absolute_path()*
-    Copy the absolute path to the system clipboard.
-
-    Parameters: ~
-      • {node}  (`nvim_tree.api.Node`)
-
-copy.basename({node})                       *nvim_tree.api.fs.copy.basename()*
-    Copy the name with extension omitted to the system clipboard.
-
-    Parameters: ~
-      • {node}  (`nvim_tree.api.Node`)
-
-copy.filename({node})                       *nvim_tree.api.fs.copy.filename()*
-    Copy the name to the system clipboard.
-
-    Parameters: ~
-      • {node}  (`nvim_tree.api.Node`)
-
-copy.node({node})                               *nvim_tree.api.fs.copy.node()*
-    Copy to the nvim-tree clipboard.
-
-    Parameters: ~
-      • {node}  (`nvim_tree.api.Node`)
-
-copy.relative_path({node})             *nvim_tree.api.fs.copy.relative_path()*
-    Copy the path relative to the tree root to the system clipboard.
-
-    Parameters: ~
-      • {node}  (`nvim_tree.api.Node`)
-
 create({node})                                     *nvim_tree.api.fs.create()*
     Prompt to create a file or directory.
 
@@ -2497,13 +2467,13 @@ create({node})                                     *nvim_tree.api.fs.create()*
     Multiple directories/files may be created e.g. `"foo/bar/baz"`
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node`)
+      • {node}  (`nvim_tree.api.Node?`)
 
 cut({node})                                           *nvim_tree.api.fs.cut()*
     Cut to the nvim-tree clipboard.
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node`)
+      • {node}  (`nvim_tree.api.Node?`)
 
 paste({node})                                       *nvim_tree.api.fs.paste()*
     Paste from the nvim-tree clipboard.
@@ -2511,7 +2481,7 @@ paste({node})                                       *nvim_tree.api.fs.paste()*
     If {node} is a file it will pasted in the parent directory.
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node`)
+      • {node}  (`nvim_tree.api.Node?`)
 
 print_clipboard()                         *nvim_tree.api.fs.print_clipboard()*
     Print the contents of the nvim-tree clipboard.
@@ -2520,43 +2490,77 @@ remove({node})                                     *nvim_tree.api.fs.remove()*
     Delete from the file system.
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node`)
+      • {node}  (`nvim_tree.api.Node?`)
 
 rename({node})                                     *nvim_tree.api.fs.rename()*
     Prompt to rename by name.
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node`)
+      • {node}  (`nvim_tree.api.Node?`)
 
 rename_basename({node})                   *nvim_tree.api.fs.rename_basename()*
     Prompt to rename by name with extension omitted.
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node`)
+      • {node}  (`nvim_tree.api.Node?`)
 
 rename_full({node})                           *nvim_tree.api.fs.rename_full()*
     Prompt to rename by absolute path.
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node`)
+      • {node}  (`nvim_tree.api.Node?`)
 
 rename_node({node})                           *nvim_tree.api.fs.rename_node()*
     Prompt to rename.
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node`)
+      • {node}  (`nvim_tree.api.Node?`)
 
 rename_sub({node})                             *nvim_tree.api.fs.rename_sub()*
     Prompt to rename by absolute path with name omitted.
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node`)
+      • {node}  (`nvim_tree.api.Node?`)
 
 trash({node})                                       *nvim_tree.api.fs.trash()*
     Trash as per |nvim_tree.config.trash|
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node`)
+      • {node}  (`nvim_tree.api.Node?`)
+
+
+==============================================================================
+API: fs.copy                                           *nvim-tree-api-fs-copy*
+
+absolute_path({node})                  *nvim_tree.api.fs.copy.absolute_path()*
+    Copy the absolute path to the system clipboard.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`)
+
+basename({node})                            *nvim_tree.api.fs.copy.basename()*
+    Copy the name with extension omitted to the system clipboard.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`)
+
+filename({node})                            *nvim_tree.api.fs.copy.filename()*
+    Copy the name to the system clipboard.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`)
+
+node({node})                                    *nvim_tree.api.fs.copy.node()*
+    Copy to the nvim-tree clipboard.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`)
+
+relative_path({node})                  *nvim_tree.api.fs.copy.relative_path()*
+    Copy the path relative to the tree root to the system clipboard.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`)
 
 
 ==============================================================================
@@ -2636,7 +2640,7 @@ toggle({node})                                  *nvim_tree.api.marks.toggle()*
     Toggle mark.
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node`) file or directory
+      • {node}  (`nvim_tree.api.Node?`) file or directory
 
 
 ==============================================================================
@@ -2647,7 +2651,7 @@ buffer.delete({node}, {opts})             *nvim_tree.api.node.buffer.delete()*
     |:bdelete|!
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node`) file
+      • {node}  (`nvim_tree.api.Node?`) file
       • {opts}  (`table?`)
                 • {force}? (`boolean`, default: false) Proceed even if the
                   buffer is modified.
@@ -2976,14 +2980,14 @@ change_root_to_node({node})         *nvim_tree.api.tree.change_root_to_node()*
     Change the tree's root to a folder node or the parent of a file node.
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node`) directory or file
+      • {node}  (`nvim_tree.api.Node?`) directory or file
 
                                   *nvim_tree.api.tree.change_root_to_parent()*
 change_root_to_parent({node})
     Change the tree's root to the parent of a node.
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node`) directory or file
+      • {node}  (`nvim_tree.api.Node?`) directory or file
 
 close()                                           *nvim_tree.api.tree.close()*
     Close the tree, affecting all tabs as per |nvim_tree.config.tab.sync|
diff --git a/lua/nvim-tree/_meta/api/fs.lua b/lua/nvim-tree/_meta/api/fs.lua
index 1cac6e00409..b038f43c91d 100644
--- a/lua/nvim-tree/_meta/api/fs.lua
+++ b/lua/nvim-tree/_meta/api/fs.lua
@@ -1,43 +1,13 @@
 ---@meta
 local nvim_tree = { api = { fs = {} } }
 
+nvim_tree.api.fs.copy = require("nvim-tree._meta.api.fs.copy");
+
 ---
 ---Clear the nvim-tree clipboard.
 ---
 function nvim_tree.api.fs.clear_clipboard() end
 
-nvim_tree.api.fs.copy = {}
-
----
----Copy the absolute path to the system clipboard.
----
----@param node nvim_tree.api.Node
-function nvim_tree.api.fs.copy.absolute_path(node) end
-
----
----Copy the name with extension omitted to the system clipboard.
----
----@param node nvim_tree.api.Node
-function nvim_tree.api.fs.copy.basename(node) end
-
----
----Copy the name to the system clipboard.
----
----@param node nvim_tree.api.Node
-function nvim_tree.api.fs.copy.filename(node) end
-
----
----Copy to the nvim-tree clipboard.
----
----@param node nvim_tree.api.Node
-function nvim_tree.api.fs.copy.node(node) end
-
----
----Copy the path relative to the tree root to the system clipboard.
----
----@param node nvim_tree.api.Node
-function nvim_tree.api.fs.copy.relative_path(node) end
-
 ---
 ---Prompt to create a file or directory.
 ---
@@ -47,13 +17,13 @@ function nvim_tree.api.fs.copy.relative_path(node) end
 ---
 ---Multiple directories/files may be created e.g. `"foo/bar/baz"`
 ---
----@param node nvim_tree.api.Node
+---@param node? nvim_tree.api.Node
 function nvim_tree.api.fs.create(node) end
 
 ---
 ---Cut to the nvim-tree clipboard.
 ---
----@param node nvim_tree.api.Node
+---@param node? nvim_tree.api.Node
 function nvim_tree.api.fs.cut(node) end
 
 ---
@@ -61,7 +31,7 @@ function nvim_tree.api.fs.cut(node) end
 ---
 ---If {node} is a file it will pasted in the parent directory.
 ---
----@param node nvim_tree.api.Node
+---@param node? nvim_tree.api.Node
 function nvim_tree.api.fs.paste(node) end
 
 ---
@@ -72,43 +42,43 @@ function nvim_tree.api.fs.print_clipboard() end
 ---
 ---Delete from the file system.
 ---
----@param node nvim_tree.api.Node
+---@param node? nvim_tree.api.Node
 function nvim_tree.api.fs.remove(node) end
 
 ---
 ---Prompt to rename by name.
 ---
----@param node nvim_tree.api.Node
+---@param node? nvim_tree.api.Node
 function nvim_tree.api.fs.rename(node) end
 
 ---
 ---Prompt to rename by name with extension omitted.
 ---
----@param node nvim_tree.api.Node
+---@param node? nvim_tree.api.Node
 function nvim_tree.api.fs.rename_basename(node) end
 
 ---
 ---Prompt to rename by absolute path.
 ---
----@param node nvim_tree.api.Node
+---@param node? nvim_tree.api.Node
 function nvim_tree.api.fs.rename_full(node) end
 
 ---
 ---Prompt to rename.
 ---
----@param node nvim_tree.api.Node
+---@param node? nvim_tree.api.Node
 function nvim_tree.api.fs.rename_node(node) end
 
 ---
 ---Prompt to rename by absolute path with name omitted.
 ---
----@param node nvim_tree.api.Node
+---@param node? nvim_tree.api.Node
 function nvim_tree.api.fs.rename_sub(node) end
 
 ---
 ---Trash as per |nvim_tree.config.trash|
 ---
----@param node nvim_tree.api.Node
+---@param node? nvim_tree.api.Node
 function nvim_tree.api.fs.trash(node) end
 
 return nvim_tree.api.fs
diff --git a/lua/nvim-tree/_meta/api/fs/copy.lua b/lua/nvim-tree/_meta/api/fs/copy.lua
new file mode 100644
index 00000000000..6dd682583af
--- /dev/null
+++ b/lua/nvim-tree/_meta/api/fs/copy.lua
@@ -0,0 +1,34 @@
+---@meta
+local nvim_tree = { api = { fs = { copy = {} } } }
+
+---
+---Copy the absolute path to the system clipboard.
+---
+---@param node? nvim_tree.api.Node
+function nvim_tree.api.fs.copy.absolute_path(node) end
+
+---
+---Copy the name with extension omitted to the system clipboard.
+---
+---@param node? nvim_tree.api.Node
+function nvim_tree.api.fs.copy.basename(node) end
+
+---
+---Copy the name to the system clipboard.
+---
+---@param node? nvim_tree.api.Node
+function nvim_tree.api.fs.copy.filename(node) end
+
+---
+---Copy to the nvim-tree clipboard.
+---
+---@param node? nvim_tree.api.Node
+function nvim_tree.api.fs.copy.node(node) end
+
+---
+---Copy the path relative to the tree root to the system clipboard.
+---
+---@param node? nvim_tree.api.Node
+function nvim_tree.api.fs.copy.relative_path(node) end
+
+return nvim_tree.api.fs.copy
diff --git a/lua/nvim-tree/_meta/api/marks.lua b/lua/nvim-tree/_meta/api/marks.lua
index bb555a96fd0..332ff304c99 100644
--- a/lua/nvim-tree/_meta/api/marks.lua
+++ b/lua/nvim-tree/_meta/api/marks.lua
@@ -16,7 +16,7 @@ function nvim_tree.api.marks.list() end
 ---
 ---Toggle mark.
 ---
----@param node nvim_tree.api.Node file or directory
+---@param node? nvim_tree.api.Node file or directory
 function nvim_tree.api.marks.toggle(node) end
 
 ---
diff --git a/lua/nvim-tree/_meta/api/node.lua b/lua/nvim-tree/_meta/api/node.lua
index 9db6a93c295..686e3112269 100644
--- a/lua/nvim-tree/_meta/api/node.lua
+++ b/lua/nvim-tree/_meta/api/node.lua
@@ -18,7 +18,7 @@ nvim_tree.api.node.buffer = {}
 ---
 ---Deletes node's related buffer, if one exists. Executes [:bdelete] or [:bdelete]!
 ---
----@param node nvim_tree.api.Node file
+---@param node? nvim_tree.api.Node file
 ---@param opts? nvim_tree.api.node.buffer.RemoveOpts
 function nvim_tree.api.node.buffer.delete(node, opts) end
 
diff --git a/lua/nvim-tree/_meta/api/tree.lua b/lua/nvim-tree/_meta/api/tree.lua
index 54c2185f905..cde9d454e6b 100644
--- a/lua/nvim-tree/_meta/api/tree.lua
+++ b/lua/nvim-tree/_meta/api/tree.lua
@@ -115,13 +115,13 @@ function nvim_tree.api.tree.change_root(path) end
 ---
 ---Change the tree's root to a folder node or the parent of a file node.
 ---
----@param node nvim_tree.api.Node directory or file
+---@param node? nvim_tree.api.Node directory or file
 function nvim_tree.api.tree.change_root_to_node(node) end
 
 ---
 ---Change the tree's root to the parent of a node.
 ---
----@param node nvim_tree.api.Node directory or file
+---@param node? nvim_tree.api.Node directory or file
 function nvim_tree.api.tree.change_root_to_parent(node) end
 
 ---
diff --git a/lua/nvim-tree/api-impl.lua b/lua/nvim-tree/api-impl.lua
index 8a977fdff33..875acfa30f0 100644
--- a/lua/nvim-tree/api-impl.lua
+++ b/lua/nvim-tree/api-impl.lua
@@ -304,36 +304,4 @@ return function(api)
   ---See :help nvim-tree-decorators
   ---@type nvim_tree.api.decorator.UserDecorator
   api.decorator.UserDecorator = UserDecorator --[[@as nvim_tree.api.decorator.UserDecorator]]
-
-
-  --
-  --Legacy API mappings
-  --
-  api.git = {
-    reload = api.tree.reload_git,
-  }
-
-  api.live_filter = {
-    start = api.filter.live.start,
-    clear = api.filter.live.clear,
-  }
-  api.tree.toggle_enable_filters = api.filter.toggle
-  api.tree.toggle_gitignore_filter = api.filter.git.ignored.toggle
-  api.tree.toggle_git_clean_filter = api.filter.git.clean.toggle
-  api.tree.toggle_no_buffer_filter = api.filter.no_buffer.toggle
-  api.tree.toggle_custom_filter = api.filter.custom.toggle
-  api.tree.toggle_hidden_filter = api.filter.dotfiles.toggle
-  api.tree.toggle_no_bookmark_filter = api.filter.no_bookmark.toggle
-
-  api.config = {
-    mappings = {
-      get_keymap = api.map.get_keymap,
-      get_keymap_default = api.map.get_keymap_default,
-      default_on_attach = api.map.default_on_attach,
-    }
-  }
-
-  api.diagnostics = {
-    hi_test = api.health.hi_test,
-  }
 end
diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index 181a9aa6b79..6c55d39e9de 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -49,8 +49,9 @@ api.tree = require("nvim-tree._meta.api.tree")
 
 
 --
---Hydrate the implementations
+--Map implementations
 --
 require("nvim-tree.api-impl")(api)
+require("nvim-tree.legacy").map_api(api)
 
 return api
diff --git a/lua/nvim-tree/legacy.lua b/lua/nvim-tree/legacy.lua
index 842700ba36b..265260159d5 100644
--- a/lua/nvim-tree/legacy.lua
+++ b/lua/nvim-tree/legacy.lua
@@ -2,6 +2,10 @@ local notify = require("nvim-tree.notify")
 
 local M = {}
 
+--
+--Functions
+--
+
 --- Create empty sub-tables if not present
 ---@param tbl table to create empty inside of
 ---@param path string dot separated string of sub-tables
@@ -50,6 +54,10 @@ local function move(src, src_path, src_pos, dst, dst_path, dst_pos, remove)
   end
 end
 
+--
+--Config
+--
+
 -- silently move, please add to help nvim-tree-legacy-opts
 local function refactored(opts)
   -- 2022/06/20
@@ -151,4 +159,37 @@ function M.migrate_legacy_options(opts)
   removed(opts)
 end
 
+--
+--API
+--
+
+---Create new api entries pointing legacy functions to current
+---@param api table
+function M.map_api(api)
+  api.config = api.config or {}
+  api.config.mappings = api.config.mappings or {}
+  api.config.mappings.get_keymap = api.map.get_keymap
+  api.config.mappings.get_keymap_default = api.map.get_keymap_default
+  api.config.mappings.default_on_attach = api.map.default_on_attach
+
+  api.git = api.git or {}
+  api.git.reload = api.tree.reload_git
+
+  api.live_filter = api.live_filter or {}
+  api.live_filter.start = api.filter.live.start
+  api.live_filter.clear = api.filter.live.clear
+
+  api.tree = api.tree or {}
+  api.tree.toggle_enable_filters = api.filter.toggle
+  api.tree.toggle_gitignore_filter = api.filter.git.ignored.toggle
+  api.tree.toggle_git_clean_filter = api.filter.git.clean.toggle
+  api.tree.toggle_no_buffer_filter = api.filter.no_buffer.toggle
+  api.tree.toggle_custom_filter = api.filter.custom.toggle
+  api.tree.toggle_hidden_filter = api.filter.dotfiles.toggle
+  api.tree.toggle_no_bookmark_filter = api.filter.no_bookmark.toggle
+
+  api.diagnostics = api.diagnostics or {}
+  api.diagnostics.hi_test = api.health.hi_test
+end
+
 return M
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index 9e82e185985..c0be9d080f4 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -43,6 +43,7 @@ local srcs = {
   { helptag = "nvim-tree-api-events",                 section = "API: events",                 path = "./lua/nvim_tree/_meta/api/events.lua", },
   { helptag = "nvim-tree-api-filter",                 section = "API: filter",                 path = "./lua/nvim_tree/_meta/api/filter.lua", },
   { helptag = "nvim-tree-api-fs",                     section = "API: fs",                     path = "./lua/nvim_tree/_meta/api/fs.lua", },
+  { helptag = "nvim-tree-api-fs-copy",                section = "API: fs.copy",                path = "./lua/nvim_tree/_meta/api/fs/copy.lua", },
   { helptag = "nvim-tree-api-health",                 section = "API: health",                 path = "./lua/nvim_tree/_meta/api/health.lua", },
   { helptag = "nvim-tree-api-map",                    section = "API: map",                    path = "./lua/nvim_tree/_meta/api/map.lua", },
   { helptag = "nvim-tree-api-marks",                  section = "API: marks",                  path = "./lua/nvim_tree/_meta/api/marks.lua", },

From 02ce4fbd21fcf5a97e07f7f648688669bd469dc4 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Fri, 23 Jan 2026 17:25:00 +1100
Subject: [PATCH 130/170] docs(#3088): correct optionality of
 nvim_tree.config.view.width fields

---
 lua/nvim-tree/_meta/api/tree.lua | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/lua/nvim-tree/_meta/api/tree.lua b/lua/nvim-tree/_meta/api/tree.lua
index cde9d454e6b..7898942b11f 100644
--- a/lua/nvim-tree/_meta/api/tree.lua
+++ b/lua/nvim-tree/_meta/api/tree.lua
@@ -98,13 +98,13 @@ function nvim_tree.api.tree.resize(opts) end
 ---@inlinedoc
 ---
 ---New [nvim_tree.config.view] {width} value.
----@field width nvim_tree.config.view.width.spec|nvim_tree.config.view.width
+---@field width? nvim_tree.config.view.width.spec|nvim_tree.config.view.width
 ---
 ---Set the width.
----@field absolute integer
+---@field absolute? integer
 ---
 ---Increase or decrease the width.
----@field relative integer
+---@field relative? integer
 
 ---
 ---Change the tree's root to a path.

From 3bafec9c180324c98f37e418dcb0e38f0526db42 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Fri, 23 Jan 2026 18:38:45 +1100
Subject: [PATCH 131/170] docs(#3088): hydrate API before setup with error
 functions, with some hydrated with their concrete function, wrap removal TODO

---
 doc/nvim-tree-lua.txt      |  6 ++--
 lua/nvim-tree.lua          |  3 ++
 lua/nvim-tree/api-impl.lua | 69 ++++++++++++++++++++++++++++++--------
 lua/nvim-tree/api.lua      |  7 ++--
 4 files changed, 64 insertions(+), 21 deletions(-)

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 26649dba5df..9af82ddba53 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -3108,11 +3108,11 @@ resize({opts})                                   *nvim_tree.api.tree.resize()*
 
     Parameters: ~
       • {opts}  (`table?`) optional
-                • {width}
+                • {width}?
                   (`nvim_tree.config.view.width.spec|nvim_tree.config.view.width`)
                   New |nvim_tree.config.view| {width} value.
-                • {absolute} (`integer`) Set the width.
-                • {relative} (`integer`) Increase or decrease the width.
+                • {absolute}? (`integer`) Set the width.
+                • {relative}? (`integer`) Increase or decrease the width.
 
 search_node()                               *nvim_tree.api.tree.search_node()*
     Open the search dialogue.
diff --git a/lua/nvim-tree.lua b/lua/nvim-tree.lua
index eb6b20621e9..71d28d19b7a 100644
--- a/lua/nvim-tree.lua
+++ b/lua/nvim-tree.lua
@@ -1,3 +1,4 @@
+local api = require("nvim-tree.api")
 local log = require("nvim-tree.log")
 local view = require("nvim-tree.view")
 local utils = require("nvim-tree.utils")
@@ -793,6 +794,8 @@ function M.setup(conf)
 
   vim.g.NvimTreeSetup = 1
   vim.api.nvim_exec_autocmds("User", { pattern = "NvimTreeSetup" })
+
+  require("nvim-tree.api-impl").hydrate_after_setup(api)
 end
 
 vim.g.NvimTreeRequired = 1
diff --git a/lua/nvim-tree/api-impl.lua b/lua/nvim-tree/api-impl.lua
index 875acfa30f0..f304dff529a 100644
--- a/lua/nvim-tree/api-impl.lua
+++ b/lua/nvim-tree/api-impl.lua
@@ -14,8 +14,55 @@ local FileLinkNode = require("nvim-tree.node.file-link")
 local RootNode = require("nvim-tree.node.root")
 local UserDecorator = require("nvim-tree.renderer.decorator.user")
 
--- hydrates meta api definitions with implementations
-return function(api)
+local M = {}
+
+---Walk the api, setting all functions to the error notification
+---@param t table
+local function hydrate_notify(t)
+  for k, v in pairs(t) do
+    if type(v) == "function" then
+      t[k] = function() notify.error("nvim-tree setup not called") end
+    elseif type(v) == "table" then
+      hydrate_notify(v)
+    end
+  end
+end
+
+---Hydrates meta api definition functions with a function.
+---- Default: return "nvim-tree setup not called".
+---- Exceptions: concrete implementation for API that can be called before setup.
+---Call it once when api is first required
+---@param api table
+function M.hydrate_init(api)
+  --
+  -- Hydrate all with the error function
+  --
+  hydrate_notify(api)
+
+  --
+  -- Rehydrate implementations that may be called before setup
+  --
+  api.events.subscribe = events.subscribe
+  api.events.Event = events.Event
+
+  api.map.default_on_attach = keymap.default_on_attach
+
+  api.decorator = {}
+  ---Create a decorator class by calling :extend()
+  ---See :help nvim-tree-decorators
+  ---@type nvim_tree.api.decorator.UserDecorator
+  api.decorator.UserDecorator = UserDecorator --[[@as nvim_tree.api.decorator.UserDecorator]]
+
+  --
+  -- Map legacy to above.
+  --
+  require("nvim-tree.legacy").map_api(api)
+end
+
+---Hydrates all API functions with concrete implementations.
+---Call this after nvim-tree setup
+---@param api table
+function M.hydrate_after_setup(api)
   ---Print error when setup not called.
   ---@param fn fun(...): any
   ---@return fun(...): any
@@ -253,9 +300,6 @@ return function(api)
   api.node.expand = wrap_node(actions.tree.modifiers.expand.node)
   api.node.collapse = wrap_node(actions.tree.modifiers.collapse.node)
 
-  ---@class ApiNodeDeleteWipeBufferOpts
-  ---@field force boolean|nil default false
-
   api.node.buffer.delete = wrap_node(function(node, opts)
     actions.node.buffer.delete(node, opts)
   end)
@@ -265,9 +309,6 @@ return function(api)
 
   api.tree.reload_git = wrap_explorer("reload_git")
 
-  api.events.subscribe = events.subscribe
-  api.events.Event = events.Event
-
   api.filter.live.start = wrap_explorer_member("live_filter", "start_filtering")
   api.filter.live.clear = wrap_explorer_member("live_filter", "clear_filter")
   api.filter.toggle = wrap_explorer_member("filters", "toggle")
@@ -291,7 +332,6 @@ return function(api)
 
   api.map.get_keymap = wrap(keymap.get_keymap)
   api.map.get_keymap_default = wrap(keymap.get_keymap_default)
-  api.map.default_on_attach = keymap.default_on_attach
 
   api.health.hi_test = wrap(appearance_hi_test)
 
@@ -299,9 +339,10 @@ return function(api)
     return require("nvim-tree.commands").get()
   end)
 
-  api.decorator = {}
-  ---Create a decorator class by calling :extend()
-  ---See :help nvim-tree-decorators
-  ---@type nvim_tree.api.decorator.UserDecorator
-  api.decorator.UserDecorator = UserDecorator --[[@as nvim_tree.api.decorator.UserDecorator]]
+  --
+  -- Remap legacy to above
+  --
+  require("nvim-tree.legacy").map_api(api)
 end
+
+return M
diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index 6c55d39e9de..943510987cd 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -35,7 +35,7 @@ local api = {}
 
 
 --
---Load the (empty) meta definitions
+-- Load the (empty) meta definitions
 --
 api.commands = require("nvim-tree._meta.api.commands")
 api.events = require("nvim-tree._meta.api.events")
@@ -49,9 +49,8 @@ api.tree = require("nvim-tree._meta.api.tree")
 
 
 --
---Map implementations
+-- Map implementations
 --
-require("nvim-tree.api-impl")(api)
-require("nvim-tree.legacy").map_api(api)
+require("nvim-tree.api-impl").hydrate_init(api)
 
 return api

From 4cbe0d75e73446829352693e521b699c519e5179 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Fri, 23 Jan 2026 18:46:14 +1100
Subject: [PATCH 132/170] docs(#3088): remove api impl error wrap

---
 lua/nvim-tree/api-impl.lua | 64 ++++++++++++++------------------------
 1 file changed, 24 insertions(+), 40 deletions(-)

diff --git a/lua/nvim-tree/api-impl.lua b/lua/nvim-tree/api-impl.lua
index f304dff529a..567eb40d2b4 100644
--- a/lua/nvim-tree/api-impl.lua
+++ b/lua/nvim-tree/api-impl.lua
@@ -63,30 +63,18 @@ end
 ---Call this after nvim-tree setup
 ---@param api table
 function M.hydrate_after_setup(api)
-  ---Print error when setup not called.
-  ---@param fn fun(...): any
-  ---@return fun(...): any
-  local function wrap(fn)
-    return function(...)
-      if vim.g.NvimTreeSetup == 1 then
-        return fn(...)
-      else
-        notify.error("nvim-tree setup not called")
-      end
-    end
-  end
 
   ---Invoke a method on the singleton explorer.
   ---Print error when setup not called.
   ---@param explorer_method string explorer method name
   ---@return fun(...): any
   local function wrap_explorer(explorer_method)
-    return wrap(function(...)
+    return function(...)
       local explorer = core.get_explorer()
       if explorer then
         return explorer[explorer_method](explorer, ...)
       end
-    end)
+    end
   end
 
   ---Inject the node as the first argument if present otherwise do nothing.
@@ -119,12 +107,12 @@ function M.hydrate_after_setup(api)
   ---@return fun(...): any
   local function wrap_explorer_member_args(explorer_member, member_method, ...)
     local method_args = ...
-    return wrap(function(...)
+    return function(...)
       local explorer = core.get_explorer()
       if explorer then
         return explorer[explorer_member][member_method](explorer[explorer_member], method_args, ...)
       end
-    end)
+    end
   end
 
   ---Invoke a member's method on the singleton explorer.
@@ -133,28 +121,26 @@ function M.hydrate_after_setup(api)
   ---@param member_method string method name to invoke on member
   ---@return fun(...): any
   local function wrap_explorer_member(explorer_member, member_method)
-    return wrap(function(...)
+    return function(...)
       local explorer = core.get_explorer()
       if explorer then
         return explorer[explorer_member][member_method](explorer[explorer_member], ...)
       end
-    end)
+    end
   end
 
-  api.tree.open = wrap(actions.tree.open.fn)
+  api.tree.open = actions.tree.open.fn
   api.tree.focus = api.tree.open
 
-  api.tree.toggle = wrap(actions.tree.toggle.fn)
-  api.tree.close = wrap(view.close)
-  api.tree.close_in_this_tab = wrap(view.close_this_tab_only)
-  api.tree.close_in_all_tabs = wrap(view.close_all_tabs)
+  api.tree.toggle = actions.tree.toggle.fn
+  api.tree.close = view.close
+  api.tree.close_in_this_tab = view.close_this_tab_only
+  api.tree.close_in_all_tabs = view.close_all_tabs
   api.tree.reload = wrap_explorer("reload_explorer")
 
-  api.tree.resize = wrap(actions.tree.resize.fn)
+  api.tree.resize = actions.tree.resize.fn
 
-  api.tree.change_root = wrap(function(...)
-    require("nvim-tree").change_dir(...)
-  end)
+  api.tree.change_root = require("nvim-tree").change_dir
 
   api.tree.change_root_to_node = wrap_node(function(node)
     if node.name == ".." or node:is(RootNode) then
@@ -177,18 +163,18 @@ function M.hydrate_after_setup(api)
   api.tree.get_node_under_cursor = wrap_explorer("get_node_at_cursor")
   api.tree.get_nodes = wrap_explorer("get_nodes")
 
-  api.tree.find_file = wrap(actions.tree.find_file.fn)
-  api.tree.search_node = wrap(actions.finders.search_node.fn)
+  api.tree.find_file = actions.tree.find_file.fn
+  api.tree.search_node = actions.finders.search_node.fn
 
-  api.tree.collapse_all = wrap(actions.tree.modifiers.collapse.all)
+  api.tree.collapse_all = actions.tree.modifiers.collapse.all
 
   api.tree.expand_all = wrap_node(actions.tree.modifiers.expand.all)
-  api.tree.toggle_help = wrap(help.toggle)
-  api.tree.is_tree_buf = wrap(utils.is_nvim_tree_buf)
+  api.tree.toggle_help = help.toggle
+  api.tree.is_tree_buf = utils.is_nvim_tree_buf
 
-  api.tree.is_visible = wrap(view.is_visible)
+  api.tree.is_visible = view.is_visible
 
-  api.tree.winid = wrap(view.winid)
+  api.tree.winid = view.winid
 
   api.fs.create = wrap_node_or_nil(actions.fs.create_file.fn)
   api.fs.remove = wrap_node(actions.fs.remove_file.fn)
@@ -330,14 +316,12 @@ function M.hydrate_after_setup(api)
   api.marks.navigate.prev = wrap_explorer_member("marks", "navigate_prev")
   api.marks.navigate.select = wrap_explorer_member("marks", "navigate_select")
 
-  api.map.get_keymap = wrap(keymap.get_keymap)
-  api.map.get_keymap_default = wrap(keymap.get_keymap_default)
+  api.map.get_keymap = keymap.get_keymap
+  api.map.get_keymap_default = keymap.get_keymap_default
 
-  api.health.hi_test = wrap(appearance_hi_test)
+  api.health.hi_test = appearance_hi_test
 
-  api.commands.get = wrap(function()
-    return require("nvim-tree.commands").get()
-  end)
+  api.commands.get = require("nvim-tree.commands").get
 
   --
   -- Remap legacy to above

From 6b38f1c8cb54ecb7eea354277896f32e75ddd821 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sat, 24 Jan 2026 14:46:16 +1100
Subject: [PATCH 133/170] docs(#3088): split api pre and post, add more
 comments

---
 lua/nvim-tree.lua          |   2 +-
 lua/nvim-tree/api-impl.lua | 332 -------------------------------------
 lua/nvim-tree/api.lua      |   2 +-
 3 files changed, 2 insertions(+), 334 deletions(-)
 delete mode 100644 lua/nvim-tree/api-impl.lua

diff --git a/lua/nvim-tree.lua b/lua/nvim-tree.lua
index 71d28d19b7a..1b758311f8f 100644
--- a/lua/nvim-tree.lua
+++ b/lua/nvim-tree.lua
@@ -795,7 +795,7 @@ function M.setup(conf)
   vim.g.NvimTreeSetup = 1
   vim.api.nvim_exec_autocmds("User", { pattern = "NvimTreeSetup" })
 
-  require("nvim-tree.api-impl").hydrate_after_setup(api)
+  require("nvim-tree.api.impl.post")(api)
 end
 
 vim.g.NvimTreeRequired = 1
diff --git a/lua/nvim-tree/api-impl.lua b/lua/nvim-tree/api-impl.lua
deleted file mode 100644
index 567eb40d2b4..00000000000
--- a/lua/nvim-tree/api-impl.lua
+++ /dev/null
@@ -1,332 +0,0 @@
-local core = require("nvim-tree.core")
-local view = require("nvim-tree.view")
-local utils = require("nvim-tree.utils")
-local actions = require("nvim-tree.actions")
-local appearance_hi_test = require("nvim-tree.appearance.hi-test")
-local events = require("nvim-tree.events")
-local help = require("nvim-tree.help")
-local keymap = require("nvim-tree.keymap")
-local notify = require("nvim-tree.notify")
-
-local DirectoryNode = require("nvim-tree.node.directory")
-local FileNode = require("nvim-tree.node.file")
-local FileLinkNode = require("nvim-tree.node.file-link")
-local RootNode = require("nvim-tree.node.root")
-local UserDecorator = require("nvim-tree.renderer.decorator.user")
-
-local M = {}
-
----Walk the api, setting all functions to the error notification
----@param t table
-local function hydrate_notify(t)
-  for k, v in pairs(t) do
-    if type(v) == "function" then
-      t[k] = function() notify.error("nvim-tree setup not called") end
-    elseif type(v) == "table" then
-      hydrate_notify(v)
-    end
-  end
-end
-
----Hydrates meta api definition functions with a function.
----- Default: return "nvim-tree setup not called".
----- Exceptions: concrete implementation for API that can be called before setup.
----Call it once when api is first required
----@param api table
-function M.hydrate_init(api)
-  --
-  -- Hydrate all with the error function
-  --
-  hydrate_notify(api)
-
-  --
-  -- Rehydrate implementations that may be called before setup
-  --
-  api.events.subscribe = events.subscribe
-  api.events.Event = events.Event
-
-  api.map.default_on_attach = keymap.default_on_attach
-
-  api.decorator = {}
-  ---Create a decorator class by calling :extend()
-  ---See :help nvim-tree-decorators
-  ---@type nvim_tree.api.decorator.UserDecorator
-  api.decorator.UserDecorator = UserDecorator --[[@as nvim_tree.api.decorator.UserDecorator]]
-
-  --
-  -- Map legacy to above.
-  --
-  require("nvim-tree.legacy").map_api(api)
-end
-
----Hydrates all API functions with concrete implementations.
----Call this after nvim-tree setup
----@param api table
-function M.hydrate_after_setup(api)
-
-  ---Invoke a method on the singleton explorer.
-  ---Print error when setup not called.
-  ---@param explorer_method string explorer method name
-  ---@return fun(...): any
-  local function wrap_explorer(explorer_method)
-    return function(...)
-      local explorer = core.get_explorer()
-      if explorer then
-        return explorer[explorer_method](explorer, ...)
-      end
-    end
-  end
-
-  ---Inject the node as the first argument if present otherwise do nothing.
-  ---@param fn fun(node: Node, ...): any
-  ---@return fun(node: Node?, ...): any
-  local function wrap_node(fn)
-    return function(node, ...)
-      node = node or wrap_explorer("get_node_at_cursor")()
-      if node then
-        return fn(node, ...)
-      end
-    end
-  end
-
-  ---Inject the node or nil as the first argument if absent.
-  ---@param fn fun(node: Node?, ...): any
-  ---@return fun(node: Node?, ...): any
-  local function wrap_node_or_nil(fn)
-    return function(node, ...)
-      node = node or wrap_explorer("get_node_at_cursor")()
-      return fn(node, ...)
-    end
-  end
-
-  ---Invoke a member's method on the singleton explorer.
-  ---Print error when setup not called.
-  ---@param explorer_member string explorer member name
-  ---@param member_method string method name to invoke on member
-  ---@param ... any passed to method
-  ---@return fun(...): any
-  local function wrap_explorer_member_args(explorer_member, member_method, ...)
-    local method_args = ...
-    return function(...)
-      local explorer = core.get_explorer()
-      if explorer then
-        return explorer[explorer_member][member_method](explorer[explorer_member], method_args, ...)
-      end
-    end
-  end
-
-  ---Invoke a member's method on the singleton explorer.
-  ---Print error when setup not called.
-  ---@param explorer_member string explorer member name
-  ---@param member_method string method name to invoke on member
-  ---@return fun(...): any
-  local function wrap_explorer_member(explorer_member, member_method)
-    return function(...)
-      local explorer = core.get_explorer()
-      if explorer then
-        return explorer[explorer_member][member_method](explorer[explorer_member], ...)
-      end
-    end
-  end
-
-  api.tree.open = actions.tree.open.fn
-  api.tree.focus = api.tree.open
-
-  api.tree.toggle = actions.tree.toggle.fn
-  api.tree.close = view.close
-  api.tree.close_in_this_tab = view.close_this_tab_only
-  api.tree.close_in_all_tabs = view.close_all_tabs
-  api.tree.reload = wrap_explorer("reload_explorer")
-
-  api.tree.resize = actions.tree.resize.fn
-
-  api.tree.change_root = require("nvim-tree").change_dir
-
-  api.tree.change_root_to_node = wrap_node(function(node)
-    if node.name == ".." or node:is(RootNode) then
-      actions.root.change_dir.fn("..")
-      return
-    end
-
-    if node:is(FileNode) and node.parent ~= nil then
-      actions.root.change_dir.fn(node.parent:last_group_node().absolute_path)
-      return
-    end
-
-    if node:is(DirectoryNode) then
-      actions.root.change_dir.fn(node:last_group_node().absolute_path)
-      return
-    end
-  end)
-
-  api.tree.change_root_to_parent = wrap_node(wrap_explorer("dir_up"))
-  api.tree.get_node_under_cursor = wrap_explorer("get_node_at_cursor")
-  api.tree.get_nodes = wrap_explorer("get_nodes")
-
-  api.tree.find_file = actions.tree.find_file.fn
-  api.tree.search_node = actions.finders.search_node.fn
-
-  api.tree.collapse_all = actions.tree.modifiers.collapse.all
-
-  api.tree.expand_all = wrap_node(actions.tree.modifiers.expand.all)
-  api.tree.toggle_help = help.toggle
-  api.tree.is_tree_buf = utils.is_nvim_tree_buf
-
-  api.tree.is_visible = view.is_visible
-
-  api.tree.winid = view.winid
-
-  api.fs.create = wrap_node_or_nil(actions.fs.create_file.fn)
-  api.fs.remove = wrap_node(actions.fs.remove_file.fn)
-  api.fs.trash = wrap_node(actions.fs.trash.fn)
-  api.fs.rename_node = wrap_node(actions.fs.rename_file.fn(":t"))
-  api.fs.rename = wrap_node(actions.fs.rename_file.fn(":t"))
-  api.fs.rename_sub = wrap_node(actions.fs.rename_file.fn(":p:h"))
-  api.fs.rename_basename = wrap_node(actions.fs.rename_file.fn(":t:r"))
-  api.fs.rename_full = wrap_node(actions.fs.rename_file.fn(":p"))
-  api.fs.cut = wrap_node(wrap_explorer_member("clipboard", "cut"))
-  api.fs.paste = wrap_node(wrap_explorer_member("clipboard", "paste"))
-  api.fs.clear_clipboard = wrap_explorer_member("clipboard", "clear_clipboard")
-  api.fs.print_clipboard = wrap_explorer_member("clipboard", "print_clipboard")
-  api.fs.copy.node = wrap_node(wrap_explorer_member("clipboard", "copy"))
-  api.fs.copy.absolute_path = wrap_node(wrap_explorer_member("clipboard", "copy_absolute_path"))
-  api.fs.copy.filename = wrap_node(wrap_explorer_member("clipboard", "copy_filename"))
-  api.fs.copy.basename = wrap_node(wrap_explorer_member("clipboard", "copy_basename"))
-  api.fs.copy.relative_path = wrap_node(wrap_explorer_member("clipboard", "copy_path"))
-  ---
-  ---@class NodeEditOpts
-  ---@field quit_on_open boolean|nil default false
-  ---@field focus boolean|nil default true
-
-  ---@param mode string
-  ---@param node Node
-  ---@param edit_opts NodeEditOpts?
-  local function edit(mode, node, edit_opts)
-    local file_link = node:as(FileLinkNode)
-    local path = file_link and file_link.link_to or node.absolute_path
-    local cur_tabpage = vim.api.nvim_get_current_tabpage()
-
-    actions.node.open_file.fn(mode, path)
-
-    edit_opts = edit_opts or {}
-
-    local mode_unsupported_quit_on_open = mode == "drop" or mode == "tab_drop" or mode == "edit_in_place"
-    if not mode_unsupported_quit_on_open and edit_opts.quit_on_open then
-      view.close(cur_tabpage)
-    end
-
-    local mode_unsupported_focus = mode == "drop" or mode == "tab_drop" or mode == "edit_in_place"
-    local focus = edit_opts.focus == nil or edit_opts.focus == true
-    if not mode_unsupported_focus and not focus then
-      -- if mode == "tabnew" a new tab will be opened and we need to focus back to the previous tab
-      if mode == "tabnew" then
-        vim.cmd(":tabprev")
-      end
-      view.focus()
-    end
-  end
-
-  ---@param mode string
-  ---@param toggle_group boolean?
-  ---@return fun(node: Node, edit_opts: NodeEditOpts?)
-  local function open_or_expand_or_dir_up(mode, toggle_group)
-    ---@param node Node
-    ---@param edit_opts NodeEditOpts?
-    return function(node, edit_opts)
-      local root = node:as(RootNode)
-      local dir = node:as(DirectoryNode)
-
-      if root or node.name == ".." then
-        actions.root.change_dir.fn("..")
-      elseif dir then
-        dir:expand_or_collapse(toggle_group)
-      elseif not toggle_group then
-        edit(mode, node, edit_opts)
-      end
-    end
-  end
-
-  api.node.open.edit = wrap_node(open_or_expand_or_dir_up("edit"))
-  api.node.open.drop = wrap_node(open_or_expand_or_dir_up("drop"))
-  api.node.open.tab_drop = wrap_node(open_or_expand_or_dir_up("tab_drop"))
-  api.node.open.replace_tree_buffer = wrap_node(open_or_expand_or_dir_up("edit_in_place"))
-  api.node.open.no_window_picker = wrap_node(open_or_expand_or_dir_up("edit_no_picker"))
-  api.node.open.vertical = wrap_node(open_or_expand_or_dir_up("vsplit"))
-  api.node.open.vertical_no_picker = wrap_node(open_or_expand_or_dir_up("vsplit_no_picker"))
-  api.node.open.horizontal = wrap_node(open_or_expand_or_dir_up("split"))
-  api.node.open.horizontal_no_picker = wrap_node(open_or_expand_or_dir_up("split_no_picker"))
-  api.node.open.tab = wrap_node(open_or_expand_or_dir_up("tabnew"))
-  api.node.open.toggle_group_empty = wrap_node(open_or_expand_or_dir_up("toggle_group_empty", true))
-  api.node.open.preview = wrap_node(open_or_expand_or_dir_up("preview"))
-  api.node.open.preview_no_picker = wrap_node(open_or_expand_or_dir_up("preview_no_picker"))
-
-  api.node.show_info_popup = wrap_node(actions.node.file_popup.toggle_file_info)
-  api.node.run.cmd = wrap_node(actions.node.run_command.run_file_command)
-  api.node.run.system = wrap_node(actions.node.system_open.fn)
-
-  api.node.navigate.sibling.next = wrap_node(actions.moves.sibling.fn("next"))
-  api.node.navigate.sibling.prev = wrap_node(actions.moves.sibling.fn("prev"))
-  api.node.navigate.sibling.first = wrap_node(actions.moves.sibling.fn("first"))
-  api.node.navigate.sibling.last = wrap_node(actions.moves.sibling.fn("last"))
-  api.node.navigate.parent = wrap_node(actions.moves.parent.fn(false))
-  api.node.navigate.parent_close = wrap_node(actions.moves.parent.fn(true))
-  api.node.navigate.git.next = wrap_node(actions.moves.item.fn({ where = "next", what = "git" }))
-  api.node.navigate.git.next_skip_gitignored = wrap_node(actions.moves.item.fn({ where = "next", what = "git", skip_gitignored = true }))
-  api.node.navigate.git.next_recursive = wrap_node(actions.moves.item.fn({ where = "next", what = "git", recurse = true }))
-  api.node.navigate.git.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "git" }))
-  api.node.navigate.git.prev_skip_gitignored = wrap_node(actions.moves.item.fn({ where = "prev", what = "git", skip_gitignored = true }))
-  api.node.navigate.git.prev_recursive = wrap_node(actions.moves.item.fn({ where = "prev", what = "git", recurse = true }))
-  api.node.navigate.diagnostics.next = wrap_node(actions.moves.item.fn({ where = "next", what = "diag" }))
-  api.node.navigate.diagnostics.next_recursive = wrap_node(actions.moves.item.fn({ where = "next", what = "diag", recurse = true }))
-  api.node.navigate.diagnostics.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "diag" }))
-  api.node.navigate.diagnostics.prev_recursive = wrap_node(actions.moves.item.fn({ where = "prev", what = "diag", recurse = true }))
-  api.node.navigate.opened.next = wrap_node(actions.moves.item.fn({ where = "next", what = "opened" }))
-  api.node.navigate.opened.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "opened" }))
-
-  api.node.expand = wrap_node(actions.tree.modifiers.expand.node)
-  api.node.collapse = wrap_node(actions.tree.modifiers.collapse.node)
-
-  api.node.buffer.delete = wrap_node(function(node, opts)
-    actions.node.buffer.delete(node, opts)
-  end)
-  api.node.buffer.wipe = wrap_node(function(node, opts)
-    actions.node.buffer.wipe(node, opts)
-  end)
-
-  api.tree.reload_git = wrap_explorer("reload_git")
-
-  api.filter.live.start = wrap_explorer_member("live_filter", "start_filtering")
-  api.filter.live.clear = wrap_explorer_member("live_filter", "clear_filter")
-  api.filter.toggle = wrap_explorer_member("filters", "toggle")
-  api.filter.git.ignored.toggle = wrap_explorer_member_args("filters", "toggle", "git_ignored")
-  api.filter.git.clean.toggle = wrap_explorer_member_args("filters", "toggle", "git_clean")
-  api.filter.no_buffer.toggle = wrap_explorer_member_args("filters", "toggle", "no_buffer")
-  api.filter.custom.toggle = wrap_explorer_member_args("filters", "toggle", "custom")
-  api.filter.dotfiles.toggle = wrap_explorer_member_args("filters", "toggle", "dotfiles")
-  api.filter.no_bookmark.toggle = wrap_explorer_member_args("filters", "toggle", "no_bookmark")
-
-  api.marks.get = wrap_node(wrap_explorer_member("marks", "get"))
-  api.marks.list = wrap_explorer_member("marks", "list")
-  api.marks.toggle = wrap_node(wrap_explorer_member("marks", "toggle"))
-  api.marks.clear = wrap_explorer_member("marks", "clear")
-  api.marks.bulk.delete = wrap_explorer_member("marks", "bulk_delete")
-  api.marks.bulk.trash = wrap_explorer_member("marks", "bulk_trash")
-  api.marks.bulk.move = wrap_explorer_member("marks", "bulk_move")
-  api.marks.navigate.next = wrap_explorer_member("marks", "navigate_next")
-  api.marks.navigate.prev = wrap_explorer_member("marks", "navigate_prev")
-  api.marks.navigate.select = wrap_explorer_member("marks", "navigate_select")
-
-  api.map.get_keymap = keymap.get_keymap
-  api.map.get_keymap_default = keymap.get_keymap_default
-
-  api.health.hi_test = appearance_hi_test
-
-  api.commands.get = require("nvim-tree.commands").get
-
-  --
-  -- Remap legacy to above
-  --
-  require("nvim-tree.legacy").map_api(api)
-end
-
-return M
diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index 943510987cd..ce0788d6d03 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -51,6 +51,6 @@ api.tree = require("nvim-tree._meta.api.tree")
 --
 -- Map implementations
 --
-require("nvim-tree.api-impl").hydrate_init(api)
+require("nvim-tree.api.impl.pre")(api)
 
 return api

From ba4f507f25b89e82d4eedfd0214a34563458d195 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sat, 24 Jan 2026 14:46:25 +1100
Subject: [PATCH 134/170] docs(#3088): split api pre and post, add more
 comments

---
 lua/nvim-tree/api/impl/post.lua | 291 ++++++++++++++++++++++++++++++++
 lua/nvim-tree/api/impl/pre.lua  |  54 ++++++
 2 files changed, 345 insertions(+)
 create mode 100644 lua/nvim-tree/api/impl/post.lua
 create mode 100644 lua/nvim-tree/api/impl/pre.lua

diff --git a/lua/nvim-tree/api/impl/post.lua b/lua/nvim-tree/api/impl/post.lua
new file mode 100644
index 00000000000..e200c6260a1
--- /dev/null
+++ b/lua/nvim-tree/api/impl/post.lua
@@ -0,0 +1,291 @@
+local core = require("nvim-tree.core")
+local view = require("nvim-tree.view")
+local utils = require("nvim-tree.utils")
+local actions = require("nvim-tree.actions")
+local appearance_hi_test = require("nvim-tree.appearance.hi-test")
+local help = require("nvim-tree.help")
+local keymap = require("nvim-tree.keymap")
+
+local DirectoryNode = require("nvim-tree.node.directory")
+local FileNode = require("nvim-tree.node.file")
+local FileLinkNode = require("nvim-tree.node.file-link")
+local RootNode = require("nvim-tree.node.root")
+
+---Hydrate all implementations barring those that were called during hydrate_pre
+---@param api table
+local function hydrate_post(api)
+  ---Invoke a method on the singleton explorer.
+  ---Print error when setup not called.
+  ---@param explorer_method string explorer method name
+  ---@return fun(...): any
+  local function wrap_explorer(explorer_method)
+    return function(...)
+      local explorer = core.get_explorer()
+      if explorer then
+        return explorer[explorer_method](explorer, ...)
+      end
+    end
+  end
+
+  ---Inject the node as the first argument if present otherwise do nothing.
+  ---@param fn fun(node: Node, ...): any
+  ---@return fun(node: Node?, ...): any
+  local function wrap_node(fn)
+    return function(node, ...)
+      node = node or wrap_explorer("get_node_at_cursor")()
+      if node then
+        return fn(node, ...)
+      end
+    end
+  end
+
+  ---Inject the node or nil as the first argument if absent.
+  ---@param fn fun(node: Node?, ...): any
+  ---@return fun(node: Node?, ...): any
+  local function wrap_node_or_nil(fn)
+    return function(node, ...)
+      node = node or wrap_explorer("get_node_at_cursor")()
+      return fn(node, ...)
+    end
+  end
+
+  ---Invoke a member's method on the singleton explorer.
+  ---Print error when setup not called.
+  ---@param explorer_member string explorer member name
+  ---@param member_method string method name to invoke on member
+  ---@param ... any passed to method
+  ---@return fun(...): any
+  local function wrap_explorer_member_args(explorer_member, member_method, ...)
+    local method_args = ...
+    return function(...)
+      local explorer = core.get_explorer()
+      if explorer then
+        return explorer[explorer_member][member_method](explorer[explorer_member], method_args, ...)
+      end
+    end
+  end
+
+  ---Invoke a member's method on the singleton explorer.
+  ---Print error when setup not called.
+  ---@param explorer_member string explorer member name
+  ---@param member_method string method name to invoke on member
+  ---@return fun(...): any
+  local function wrap_explorer_member(explorer_member, member_method)
+    return function(...)
+      local explorer = core.get_explorer()
+      if explorer then
+        return explorer[explorer_member][member_method](explorer[explorer_member], ...)
+      end
+    end
+  end
+
+  api.tree.open = actions.tree.open.fn
+  api.tree.focus = api.tree.open
+
+  api.tree.toggle = actions.tree.toggle.fn
+  api.tree.close = view.close
+  api.tree.close_in_this_tab = view.close_this_tab_only
+  api.tree.close_in_all_tabs = view.close_all_tabs
+  api.tree.reload = wrap_explorer("reload_explorer")
+
+  api.tree.resize = actions.tree.resize.fn
+
+  api.tree.change_root = require("nvim-tree").change_dir
+
+  api.tree.change_root_to_node = wrap_node(function(node)
+    if node.name == ".." or node:is(RootNode) then
+      actions.root.change_dir.fn("..")
+      return
+    end
+
+    if node:is(FileNode) and node.parent ~= nil then
+      actions.root.change_dir.fn(node.parent:last_group_node().absolute_path)
+      return
+    end
+
+    if node:is(DirectoryNode) then
+      actions.root.change_dir.fn(node:last_group_node().absolute_path)
+      return
+    end
+  end)
+
+  api.tree.change_root_to_parent = wrap_node(wrap_explorer("dir_up"))
+  api.tree.get_node_under_cursor = wrap_explorer("get_node_at_cursor")
+  api.tree.get_nodes = wrap_explorer("get_nodes")
+
+  api.tree.find_file = actions.tree.find_file.fn
+  api.tree.search_node = actions.finders.search_node.fn
+
+  api.tree.collapse_all = actions.tree.modifiers.collapse.all
+
+  api.tree.expand_all = wrap_node(actions.tree.modifiers.expand.all)
+  api.tree.toggle_help = help.toggle
+  api.tree.is_tree_buf = utils.is_nvim_tree_buf
+
+  api.tree.is_visible = view.is_visible
+
+  api.tree.winid = view.winid
+
+  api.fs.create = wrap_node_or_nil(actions.fs.create_file.fn)
+  api.fs.remove = wrap_node(actions.fs.remove_file.fn)
+  api.fs.trash = wrap_node(actions.fs.trash.fn)
+  api.fs.rename_node = wrap_node(actions.fs.rename_file.fn(":t"))
+  api.fs.rename = wrap_node(actions.fs.rename_file.fn(":t"))
+  api.fs.rename_sub = wrap_node(actions.fs.rename_file.fn(":p:h"))
+  api.fs.rename_basename = wrap_node(actions.fs.rename_file.fn(":t:r"))
+  api.fs.rename_full = wrap_node(actions.fs.rename_file.fn(":p"))
+  api.fs.cut = wrap_node(wrap_explorer_member("clipboard", "cut"))
+  api.fs.paste = wrap_node(wrap_explorer_member("clipboard", "paste"))
+  api.fs.clear_clipboard = wrap_explorer_member("clipboard", "clear_clipboard")
+  api.fs.print_clipboard = wrap_explorer_member("clipboard", "print_clipboard")
+  api.fs.copy.node = wrap_node(wrap_explorer_member("clipboard", "copy"))
+  api.fs.copy.absolute_path = wrap_node(wrap_explorer_member("clipboard", "copy_absolute_path"))
+  api.fs.copy.filename = wrap_node(wrap_explorer_member("clipboard", "copy_filename"))
+  api.fs.copy.basename = wrap_node(wrap_explorer_member("clipboard", "copy_basename"))
+  api.fs.copy.relative_path = wrap_node(wrap_explorer_member("clipboard", "copy_path"))
+  ---
+  ---@class NodeEditOpts
+  ---@field quit_on_open boolean|nil default false
+  ---@field focus boolean|nil default true
+
+  ---@param mode string
+  ---@param node Node
+  ---@param edit_opts NodeEditOpts?
+  local function edit(mode, node, edit_opts)
+    local file_link = node:as(FileLinkNode)
+    local path = file_link and file_link.link_to or node.absolute_path
+    local cur_tabpage = vim.api.nvim_get_current_tabpage()
+
+    actions.node.open_file.fn(mode, path)
+
+    edit_opts = edit_opts or {}
+
+    local mode_unsupported_quit_on_open = mode == "drop" or mode == "tab_drop" or mode == "edit_in_place"
+    if not mode_unsupported_quit_on_open and edit_opts.quit_on_open then
+      view.close(cur_tabpage)
+    end
+
+    local mode_unsupported_focus = mode == "drop" or mode == "tab_drop" or mode == "edit_in_place"
+    local focus = edit_opts.focus == nil or edit_opts.focus == true
+    if not mode_unsupported_focus and not focus then
+      -- if mode == "tabnew" a new tab will be opened and we need to focus back to the previous tab
+      if mode == "tabnew" then
+        vim.cmd(":tabprev")
+      end
+      view.focus()
+    end
+  end
+
+  ---@param mode string
+  ---@param toggle_group boolean?
+  ---@return fun(node: Node, edit_opts: NodeEditOpts?)
+  local function open_or_expand_or_dir_up(mode, toggle_group)
+    ---@param node Node
+    ---@param edit_opts NodeEditOpts?
+    return function(node, edit_opts)
+      local root = node:as(RootNode)
+      local dir = node:as(DirectoryNode)
+
+      if root or node.name == ".." then
+        actions.root.change_dir.fn("..")
+      elseif dir then
+        dir:expand_or_collapse(toggle_group)
+      elseif not toggle_group then
+        edit(mode, node, edit_opts)
+      end
+    end
+  end
+
+  api.node.open.edit = wrap_node(open_or_expand_or_dir_up("edit"))
+  api.node.open.drop = wrap_node(open_or_expand_or_dir_up("drop"))
+  api.node.open.tab_drop = wrap_node(open_or_expand_or_dir_up("tab_drop"))
+  api.node.open.replace_tree_buffer = wrap_node(open_or_expand_or_dir_up("edit_in_place"))
+  api.node.open.no_window_picker = wrap_node(open_or_expand_or_dir_up("edit_no_picker"))
+  api.node.open.vertical = wrap_node(open_or_expand_or_dir_up("vsplit"))
+  api.node.open.vertical_no_picker = wrap_node(open_or_expand_or_dir_up("vsplit_no_picker"))
+  api.node.open.horizontal = wrap_node(open_or_expand_or_dir_up("split"))
+  api.node.open.horizontal_no_picker = wrap_node(open_or_expand_or_dir_up("split_no_picker"))
+  api.node.open.tab = wrap_node(open_or_expand_or_dir_up("tabnew"))
+  api.node.open.toggle_group_empty = wrap_node(open_or_expand_or_dir_up("toggle_group_empty", true))
+  api.node.open.preview = wrap_node(open_or_expand_or_dir_up("preview"))
+  api.node.open.preview_no_picker = wrap_node(open_or_expand_or_dir_up("preview_no_picker"))
+
+  api.node.show_info_popup = wrap_node(actions.node.file_popup.toggle_file_info)
+  api.node.run.cmd = wrap_node(actions.node.run_command.run_file_command)
+  api.node.run.system = wrap_node(actions.node.system_open.fn)
+
+  api.node.navigate.sibling.next = wrap_node(actions.moves.sibling.fn("next"))
+  api.node.navigate.sibling.prev = wrap_node(actions.moves.sibling.fn("prev"))
+  api.node.navigate.sibling.first = wrap_node(actions.moves.sibling.fn("first"))
+  api.node.navigate.sibling.last = wrap_node(actions.moves.sibling.fn("last"))
+  api.node.navigate.parent = wrap_node(actions.moves.parent.fn(false))
+  api.node.navigate.parent_close = wrap_node(actions.moves.parent.fn(true))
+  api.node.navigate.git.next = wrap_node(actions.moves.item.fn({ where = "next", what = "git" }))
+  api.node.navigate.git.next_skip_gitignored = wrap_node(actions.moves.item.fn({ where = "next", what = "git", skip_gitignored = true }))
+  api.node.navigate.git.next_recursive = wrap_node(actions.moves.item.fn({ where = "next", what = "git", recurse = true }))
+  api.node.navigate.git.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "git" }))
+  api.node.navigate.git.prev_skip_gitignored = wrap_node(actions.moves.item.fn({ where = "prev", what = "git", skip_gitignored = true }))
+  api.node.navigate.git.prev_recursive = wrap_node(actions.moves.item.fn({ where = "prev", what = "git", recurse = true }))
+  api.node.navigate.diagnostics.next = wrap_node(actions.moves.item.fn({ where = "next", what = "diag" }))
+  api.node.navigate.diagnostics.next_recursive = wrap_node(actions.moves.item.fn({ where = "next", what = "diag", recurse = true }))
+  api.node.navigate.diagnostics.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "diag" }))
+  api.node.navigate.diagnostics.prev_recursive = wrap_node(actions.moves.item.fn({ where = "prev", what = "diag", recurse = true }))
+  api.node.navigate.opened.next = wrap_node(actions.moves.item.fn({ where = "next", what = "opened" }))
+  api.node.navigate.opened.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "opened" }))
+
+  api.node.expand = wrap_node(actions.tree.modifiers.expand.node)
+  api.node.collapse = wrap_node(actions.tree.modifiers.collapse.node)
+
+  api.node.buffer.delete = wrap_node(function(node, opts)
+    actions.node.buffer.delete(node, opts)
+  end)
+  api.node.buffer.wipe = wrap_node(function(node, opts)
+    actions.node.buffer.wipe(node, opts)
+  end)
+
+  api.tree.reload_git = wrap_explorer("reload_git")
+
+  api.filter.live.start = wrap_explorer_member("live_filter", "start_filtering")
+  api.filter.live.clear = wrap_explorer_member("live_filter", "clear_filter")
+  api.filter.toggle = wrap_explorer_member("filters", "toggle")
+  api.filter.git.ignored.toggle = wrap_explorer_member_args("filters", "toggle", "git_ignored")
+  api.filter.git.clean.toggle = wrap_explorer_member_args("filters", "toggle", "git_clean")
+  api.filter.no_buffer.toggle = wrap_explorer_member_args("filters", "toggle", "no_buffer")
+  api.filter.custom.toggle = wrap_explorer_member_args("filters", "toggle", "custom")
+  api.filter.dotfiles.toggle = wrap_explorer_member_args("filters", "toggle", "dotfiles")
+  api.filter.no_bookmark.toggle = wrap_explorer_member_args("filters", "toggle", "no_bookmark")
+
+  api.marks.get = wrap_node(wrap_explorer_member("marks", "get"))
+  api.marks.list = wrap_explorer_member("marks", "list")
+  api.marks.toggle = wrap_node(wrap_explorer_member("marks", "toggle"))
+  api.marks.clear = wrap_explorer_member("marks", "clear")
+  api.marks.bulk.delete = wrap_explorer_member("marks", "bulk_delete")
+  api.marks.bulk.trash = wrap_explorer_member("marks", "bulk_trash")
+  api.marks.bulk.move = wrap_explorer_member("marks", "bulk_move")
+  api.marks.navigate.next = wrap_explorer_member("marks", "navigate_next")
+  api.marks.navigate.prev = wrap_explorer_member("marks", "navigate_prev")
+  api.marks.navigate.select = wrap_explorer_member("marks", "navigate_select")
+
+  api.map.get_keymap = keymap.get_keymap
+  api.map.get_keymap_default = keymap.get_keymap_default
+
+  api.health.hi_test = appearance_hi_test
+
+  api.commands.get = require("nvim-tree.commands").get
+end
+
+---Hydrates all API functions with concrete implementations.
+---All "nvim-tree setup not called" error functions will be replaced.
+---
+---Call this after nvim-tree setup
+---
+---This is expensive as there are many cascading requires and is avoided
+---until after setup has been called, so that the user may require API cheaply.
+---@param api table
+return function(api)
+  -- All concrete implementations
+  hydrate_post(api)
+
+  -- (Re)hydrate any legacy by mapping to function set above
+  require("nvim-tree.legacy").map_api(api)
+end
diff --git a/lua/nvim-tree/api/impl/pre.lua b/lua/nvim-tree/api/impl/pre.lua
new file mode 100644
index 00000000000..db7c08fce1b
--- /dev/null
+++ b/lua/nvim-tree/api/impl/pre.lua
@@ -0,0 +1,54 @@
+local events = require("nvim-tree.events")
+local keymap = require("nvim-tree.keymap")
+local notify = require("nvim-tree.notify")
+
+local UserDecorator = require("nvim-tree.renderer.decorator.user")
+
+---Walk the api, hydrating all functions with the error notification
+---@param t table api root or sub-module
+local function hydrate_notify(t)
+  for k, v in pairs(t) do
+    if type(v) == "function" then
+      t[k] = function()
+        notify.error("nvim-tree setup not called")
+      end
+    elseif type(v) == "table" then
+      hydrate_notify(v)
+    end
+  end
+end
+
+---Hydrate implementations that may be called pre setup
+---@param api table
+local function hydrate_pre(api)
+  api.events.subscribe = events.subscribe
+  api.events.Event = events.Event
+
+  api.map.default_on_attach = keymap.default_on_attach
+
+  api.decorator = {}
+  ---Create a decorator class by calling :extend()
+  ---See :help nvim-tree-decorators
+  ---@type nvim_tree.api.decorator.UserDecorator
+  api.decorator.UserDecorator = UserDecorator --[[@as nvim_tree.api.decorator.UserDecorator]]
+end
+
+--Hydrates meta api empty definition functions with a new function:
+-- - Default: error notification "nvim-tree setup not called".
+-- - Exceptions: concrete implementation for API that can be called before setup.
+--
+--Call it once when api is first required
+--
+--This should not include any requires beyond that which is absolutely essential,
+--as the user should be able to require api cheaply.
+---@param api table
+return function(api)
+  -- Default: error
+  hydrate_notify(api)
+
+  -- Exceptions: may be called
+  hydrate_pre(api)
+
+  -- Hydrate any legacy by mapping to function set above
+  require("nvim-tree.legacy").map_api(api)
+end

From a79a49530b988f3140abb394c85cf0d653cbb7e9 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sat, 24 Jan 2026 14:57:25 +1100
Subject: [PATCH 135/170] docs(#3088): extract post impl functions, lazy some
 requires

---
 lua/nvim-tree/api/impl/post.lua | 236 +++++++++++++++-----------------
 1 file changed, 114 insertions(+), 122 deletions(-)

diff --git a/lua/nvim-tree/api/impl/post.lua b/lua/nvim-tree/api/impl/post.lua
index e200c6260a1..5ed890ba378 100644
--- a/lua/nvim-tree/api/impl/post.lua
+++ b/lua/nvim-tree/api/impl/post.lua
@@ -1,84 +1,131 @@
-local core = require("nvim-tree.core")
 local view = require("nvim-tree.view")
-local utils = require("nvim-tree.utils")
 local actions = require("nvim-tree.actions")
-local appearance_hi_test = require("nvim-tree.appearance.hi-test")
-local help = require("nvim-tree.help")
-local keymap = require("nvim-tree.keymap")
 
 local DirectoryNode = require("nvim-tree.node.directory")
 local FileNode = require("nvim-tree.node.file")
 local FileLinkNode = require("nvim-tree.node.file-link")
 local RootNode = require("nvim-tree.node.root")
 
----Hydrate all implementations barring those that were called during hydrate_pre
----@param api table
-local function hydrate_post(api)
-  ---Invoke a method on the singleton explorer.
-  ---Print error when setup not called.
-  ---@param explorer_method string explorer method name
-  ---@return fun(...): any
-  local function wrap_explorer(explorer_method)
-    return function(...)
-      local explorer = core.get_explorer()
-      if explorer then
-        return explorer[explorer_method](explorer, ...)
-      end
+---Invoke a method on the singleton explorer.
+---Print error when setup not called.
+---@param explorer_method string explorer method name
+---@return fun(...): any
+local function wrap_explorer(explorer_method)
+  return function(...)
+    local explorer = require("nvim-tree.core").get_explorer()
+    if explorer then
+      return explorer[explorer_method](explorer, ...)
     end
   end
+end
 
-  ---Inject the node as the first argument if present otherwise do nothing.
-  ---@param fn fun(node: Node, ...): any
-  ---@return fun(node: Node?, ...): any
-  local function wrap_node(fn)
-    return function(node, ...)
-      node = node or wrap_explorer("get_node_at_cursor")()
-      if node then
-        return fn(node, ...)
-      end
+---Inject the node as the first argument if present otherwise do nothing.
+---@param fn fun(node: Node, ...): any
+---@return fun(node: Node?, ...): any
+local function wrap_node(fn)
+  return function(node, ...)
+    node = node or wrap_explorer("get_node_at_cursor")()
+    if node then
+      return fn(node, ...)
     end
   end
+end
+
+---Inject the node or nil as the first argument if absent.
+---@param fn fun(node: Node?, ...): any
+---@return fun(node: Node?, ...): any
+local function wrap_node_or_nil(fn)
+  return function(node, ...)
+    node = node or wrap_explorer("get_node_at_cursor")()
+    return fn(node, ...)
+  end
+end
 
-  ---Inject the node or nil as the first argument if absent.
-  ---@param fn fun(node: Node?, ...): any
-  ---@return fun(node: Node?, ...): any
-  local function wrap_node_or_nil(fn)
-    return function(node, ...)
-      node = node or wrap_explorer("get_node_at_cursor")()
-      return fn(node, ...)
+---Invoke a member's method on the singleton explorer.
+---Print error when setup not called.
+---@param explorer_member string explorer member name
+---@param member_method string method name to invoke on member
+---@param ... any passed to method
+---@return fun(...): any
+local function wrap_explorer_member_args(explorer_member, member_method, ...)
+  local method_args = ...
+  return function(...)
+    local explorer = require("nvim-tree.core").get_explorer()
+    if explorer then
+      return explorer[explorer_member][member_method](explorer[explorer_member], method_args, ...)
     end
   end
+end
 
-  ---Invoke a member's method on the singleton explorer.
-  ---Print error when setup not called.
-  ---@param explorer_member string explorer member name
-  ---@param member_method string method name to invoke on member
-  ---@param ... any passed to method
-  ---@return fun(...): any
-  local function wrap_explorer_member_args(explorer_member, member_method, ...)
-    local method_args = ...
-    return function(...)
-      local explorer = core.get_explorer()
-      if explorer then
-        return explorer[explorer_member][member_method](explorer[explorer_member], method_args, ...)
-      end
+---Invoke a member's method on the singleton explorer.
+---Print error when setup not called.
+---@param explorer_member string explorer member name
+---@param member_method string method name to invoke on member
+---@return fun(...): any
+local function wrap_explorer_member(explorer_member, member_method)
+  return function(...)
+    local explorer = require("nvim-tree.core").get_explorer()
+    if explorer then
+      return explorer[explorer_member][member_method](explorer[explorer_member], ...)
     end
   end
+end
 
-  ---Invoke a member's method on the singleton explorer.
-  ---Print error when setup not called.
-  ---@param explorer_member string explorer member name
-  ---@param member_method string method name to invoke on member
-  ---@return fun(...): any
-  local function wrap_explorer_member(explorer_member, member_method)
-    return function(...)
-      local explorer = core.get_explorer()
-      if explorer then
-        return explorer[explorer_member][member_method](explorer[explorer_member], ...)
-      end
+---@class NodeEditOpts
+---@field quit_on_open boolean|nil default false
+---@field focus boolean|nil default true
+
+---@param mode string
+---@param node Node
+---@param edit_opts NodeEditOpts?
+local function edit(mode, node, edit_opts)
+  local file_link = node:as(FileLinkNode)
+  local path = file_link and file_link.link_to or node.absolute_path
+  local cur_tabpage = vim.api.nvim_get_current_tabpage()
+
+  actions.node.open_file.fn(mode, path)
+
+  edit_opts = edit_opts or {}
+
+  local mode_unsupported_quit_on_open = mode == "drop" or mode == "tab_drop" or mode == "edit_in_place"
+  if not mode_unsupported_quit_on_open and edit_opts.quit_on_open then
+    view.close(cur_tabpage)
+  end
+
+  local mode_unsupported_focus = mode == "drop" or mode == "tab_drop" or mode == "edit_in_place"
+  local focus = edit_opts.focus == nil or edit_opts.focus == true
+  if not mode_unsupported_focus and not focus then
+    -- if mode == "tabnew" a new tab will be opened and we need to focus back to the previous tab
+    if mode == "tabnew" then
+      vim.cmd(":tabprev")
     end
+    view.focus()
   end
+end
 
+---@param mode string
+---@param toggle_group boolean?
+---@return fun(node: Node, edit_opts: NodeEditOpts?)
+local function open_or_expand_or_dir_up(mode, toggle_group)
+  ---@param node Node
+  ---@param edit_opts NodeEditOpts?
+  return function(node, edit_opts)
+    local root = node:as(RootNode)
+    local dir = node:as(DirectoryNode)
+
+    if root or node.name == ".." then
+      actions.root.change_dir.fn("..")
+    elseif dir then
+      dir:expand_or_collapse(toggle_group)
+    elseif not toggle_group then
+      edit(mode, node, edit_opts)
+    end
+  end
+end
+
+---Hydrate all implementations barring those that were called during hydrate_pre
+---@param api table
+local function hydrate_post(api)
   api.tree.open = actions.tree.open.fn
   api.tree.focus = api.tree.open
 
@@ -119,8 +166,8 @@ local function hydrate_post(api)
   api.tree.collapse_all = actions.tree.modifiers.collapse.all
 
   api.tree.expand_all = wrap_node(actions.tree.modifiers.expand.all)
-  api.tree.toggle_help = help.toggle
-  api.tree.is_tree_buf = utils.is_nvim_tree_buf
+  api.tree.toggle_help = function() require("nvim-tree.help").toggle() end
+  api.tree.is_tree_buf = function() require("nvim-tree.utils").is_nvim_tree_buf() end
 
   api.tree.is_visible = view.is_visible
 
@@ -143,58 +190,6 @@ local function hydrate_post(api)
   api.fs.copy.filename = wrap_node(wrap_explorer_member("clipboard", "copy_filename"))
   api.fs.copy.basename = wrap_node(wrap_explorer_member("clipboard", "copy_basename"))
   api.fs.copy.relative_path = wrap_node(wrap_explorer_member("clipboard", "copy_path"))
-  ---
-  ---@class NodeEditOpts
-  ---@field quit_on_open boolean|nil default false
-  ---@field focus boolean|nil default true
-
-  ---@param mode string
-  ---@param node Node
-  ---@param edit_opts NodeEditOpts?
-  local function edit(mode, node, edit_opts)
-    local file_link = node:as(FileLinkNode)
-    local path = file_link and file_link.link_to or node.absolute_path
-    local cur_tabpage = vim.api.nvim_get_current_tabpage()
-
-    actions.node.open_file.fn(mode, path)
-
-    edit_opts = edit_opts or {}
-
-    local mode_unsupported_quit_on_open = mode == "drop" or mode == "tab_drop" or mode == "edit_in_place"
-    if not mode_unsupported_quit_on_open and edit_opts.quit_on_open then
-      view.close(cur_tabpage)
-    end
-
-    local mode_unsupported_focus = mode == "drop" or mode == "tab_drop" or mode == "edit_in_place"
-    local focus = edit_opts.focus == nil or edit_opts.focus == true
-    if not mode_unsupported_focus and not focus then
-      -- if mode == "tabnew" a new tab will be opened and we need to focus back to the previous tab
-      if mode == "tabnew" then
-        vim.cmd(":tabprev")
-      end
-      view.focus()
-    end
-  end
-
-  ---@param mode string
-  ---@param toggle_group boolean?
-  ---@return fun(node: Node, edit_opts: NodeEditOpts?)
-  local function open_or_expand_or_dir_up(mode, toggle_group)
-    ---@param node Node
-    ---@param edit_opts NodeEditOpts?
-    return function(node, edit_opts)
-      local root = node:as(RootNode)
-      local dir = node:as(DirectoryNode)
-
-      if root or node.name == ".." then
-        actions.root.change_dir.fn("..")
-      elseif dir then
-        dir:expand_or_collapse(toggle_group)
-      elseif not toggle_group then
-        edit(mode, node, edit_opts)
-      end
-    end
-  end
 
   api.node.open.edit = wrap_node(open_or_expand_or_dir_up("edit"))
   api.node.open.drop = wrap_node(open_or_expand_or_dir_up("drop"))
@@ -236,12 +231,8 @@ local function hydrate_post(api)
   api.node.expand = wrap_node(actions.tree.modifiers.expand.node)
   api.node.collapse = wrap_node(actions.tree.modifiers.collapse.node)
 
-  api.node.buffer.delete = wrap_node(function(node, opts)
-    actions.node.buffer.delete(node, opts)
-  end)
-  api.node.buffer.wipe = wrap_node(function(node, opts)
-    actions.node.buffer.wipe(node, opts)
-  end)
+  api.node.buffer.delete = wrap_node(function(node, opts) actions.node.buffer.delete(node, opts) end)
+  api.node.buffer.wipe = wrap_node(function(node, opts) actions.node.buffer.wipe(node, opts) end)
 
   api.tree.reload_git = wrap_explorer("reload_git")
 
@@ -266,12 +257,13 @@ local function hydrate_post(api)
   api.marks.navigate.prev = wrap_explorer_member("marks", "navigate_prev")
   api.marks.navigate.select = wrap_explorer_member("marks", "navigate_select")
 
-  api.map.get_keymap = keymap.get_keymap
-  api.map.get_keymap_default = keymap.get_keymap_default
+  api.map.get_keymap = function() require("nvim-tree.keymap").get_keymap() end
+  api.map.get_keymap_default = function() require("nvim-tree.keymap").get_keymap_default() end
 
-  api.health.hi_test = appearance_hi_test
+  api.health.hi_test = function() require("nvim-tree.appearance.hi-test")() end
 
-  api.commands.get = require("nvim-tree.commands").get
+  -- TODO #3231 this should be OK pre
+  api.commands.get = function() require("nvim-tree.commands").get() end
 end
 
 ---Hydrates all API functions with concrete implementations.

From c6ea6c5be1aab9792fa45e1a749e6bc90d58a6bc Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sat, 24 Jan 2026 15:39:49 +1100
Subject: [PATCH 136/170] docs(#3088): lazy api impl requires

---
 lua/nvim-tree/api/impl/post.lua | 127 +++++++++++++++-----------------
 lua/nvim-tree/api/impl/pre.lua  |  25 +++++--
 2 files changed, 76 insertions(+), 76 deletions(-)

diff --git a/lua/nvim-tree/api/impl/post.lua b/lua/nvim-tree/api/impl/post.lua
index b8f42f5d8ba..413dabb6f34 100644
--- a/lua/nvim-tree/api/impl/post.lua
+++ b/lua/nvim-tree/api/impl/post.lua
@@ -1,12 +1,7 @@
-local view = require("nvim-tree.view")
-local actions = require("nvim-tree.actions")
-
-local DirectoryNode = require("nvim-tree.node.directory")
-local FileLinkNode = require("nvim-tree.node.file-link")
-local RootNode = require("nvim-tree.node.root")
+--This file should have no requires. Everything must be lazy loaded.
+--The user must be able to require api cheaply and run setup cheaply.
 
 ---Invoke a method on the singleton explorer.
----Print error when setup not called.
 ---@param explorer_method string explorer method name
 ---@return fun(...): any
 local function wrap_explorer(explorer_method)
@@ -41,7 +36,6 @@ local function wrap_node_or_nil(fn)
 end
 
 ---Invoke a member's method on the singleton explorer.
----Print error when setup not called.
 ---@param explorer_member string explorer member name
 ---@param member_method string method name to invoke on member
 ---@param ... any passed to method
@@ -57,7 +51,6 @@ local function wrap_explorer_member_args(explorer_member, member_method, ...)
 end
 
 ---Invoke a member's method on the singleton explorer.
----Print error when setup not called.
 ---@param explorer_member string explorer member name
 ---@param member_method string method name to invoke on member
 ---@return fun(...): any
@@ -78,7 +71,10 @@ end
 ---@param node Node
 ---@param edit_opts NodeEditOpts?
 local function edit(mode, node, edit_opts)
-  local file_link = node:as(FileLinkNode)
+  local actions = require("nvim-tree.actions")
+  local view = require("nvim-tree.view")
+
+  local file_link = node:as(require("nvim-tree.node.file-link"))
   local path = file_link and file_link.link_to or node.absolute_path
   local cur_tabpage = vim.api.nvim_get_current_tabpage()
 
@@ -109,11 +105,11 @@ local function open_or_expand_or_dir_up(mode, toggle_group)
   ---@param node Node
   ---@param edit_opts NodeEditOpts?
   return function(node, edit_opts)
-    local root = node:as(RootNode)
-    local dir = node:as(DirectoryNode)
+    local root = node:as(require("nvim-tree.node.root"))
+    local dir = node:as(require("nvim-tree.node.directory"))
 
     if root or node.name == ".." then
-      actions.root.change_dir.fn("..")
+      require("nvim-tree.actions").root.change_dir.fn("..")
     elseif dir then
       dir:expand_or_collapse(toggle_group)
     elseif not toggle_group then
@@ -125,45 +121,45 @@ end
 ---Hydrate all implementations barring those that were called during hydrate_pre
 ---@param api table
 local function hydrate_post(api)
-  api.tree.open = actions.tree.open.fn
+  api.tree.open = function(...) require("nvim-tree.actions").tree.open.fn(...) end
   api.tree.focus = api.tree.open
 
-  api.tree.toggle = actions.tree.toggle.fn
-  api.tree.close = view.close
-  api.tree.close_in_this_tab = view.close_this_tab_only
-  api.tree.close_in_all_tabs = view.close_all_tabs
+  api.tree.toggle = function(...) require("nvim-tree.actions").tree.toggle.fn(...) end
+  api.tree.close = function(...) require("nvim-tree.view").close(...) end
+  api.tree.close_in_this_tab = function() require("nvim-tree.view").close_this_tab_only() end
+  api.tree.close_in_all_tabs = function() require("nvim-tree.view").close_all_tabs() end
   api.tree.reload = wrap_explorer("reload_explorer")
 
-  api.tree.resize = actions.tree.resize.fn
+  api.tree.resize = function(...) require("nvim-tree.actions").tree.resize.fn(...) end
 
-  api.tree.change_root = require("nvim-tree").change_dir
+  api.tree.change_root = function(...) require("nvim-tree").change_dir(...) end
 
   api.tree.change_root_to_node = wrap_node(wrap_explorer("change_dir_to_node"))
   api.tree.change_root_to_parent = wrap_node(wrap_explorer("dir_up"))
   api.tree.get_node_under_cursor = wrap_explorer("get_node_at_cursor")
   api.tree.get_nodes = wrap_explorer("get_nodes")
 
-  api.tree.find_file = actions.tree.find_file.fn
-  api.tree.search_node = actions.finders.search_node.fn
+  api.tree.find_file = function(...) require("nvim-tree.actions").tree.find_file.fn(...) end
+  api.tree.search_node = function() require("nvim-tree.actions").finders.search_node.fn() end
 
-  api.tree.collapse_all = actions.tree.modifiers.collapse.all
+  api.tree.collapse_all = function(...) require("nvim-tree.actions").tree.modifiers.collapse.all(...) end
 
-  api.tree.expand_all = wrap_node(actions.tree.modifiers.expand.all)
+  api.tree.expand_all = wrap_node(require("nvim-tree.actions").tree.modifiers.expand.all)
   api.tree.toggle_help = function() require("nvim-tree.help").toggle() end
-  api.tree.is_tree_buf = function() require("nvim-tree.utils").is_nvim_tree_buf() end
+  api.tree.is_tree_buf = function(...) require("nvim-tree.utils").is_nvim_tree_buf(...) end
 
-  api.tree.is_visible = view.is_visible
+  api.tree.is_visible = function(...) require("nvim-tree.view").is_visible(...) end
 
-  api.tree.winid = view.winid
+  api.tree.winid = function(...) require("nvim-tree.view").winid(...) end
 
-  api.fs.create = wrap_node_or_nil(actions.fs.create_file.fn)
-  api.fs.remove = wrap_node(actions.fs.remove_file.fn)
-  api.fs.trash = wrap_node(actions.fs.trash.fn)
-  api.fs.rename_node = wrap_node(actions.fs.rename_file.fn(":t"))
-  api.fs.rename = wrap_node(actions.fs.rename_file.fn(":t"))
-  api.fs.rename_sub = wrap_node(actions.fs.rename_file.fn(":p:h"))
-  api.fs.rename_basename = wrap_node(actions.fs.rename_file.fn(":t:r"))
-  api.fs.rename_full = wrap_node(actions.fs.rename_file.fn(":p"))
+  api.fs.create = wrap_node_or_nil(require("nvim-tree.actions").fs.create_file.fn)
+  api.fs.remove = wrap_node(require("nvim-tree.actions").fs.remove_file.fn)
+  api.fs.trash = wrap_node(require("nvim-tree.actions").fs.trash.fn)
+  api.fs.rename_node = wrap_node(require("nvim-tree.actions").fs.rename_file.fn(":t"))
+  api.fs.rename = wrap_node(require("nvim-tree.actions").fs.rename_file.fn(":t"))
+  api.fs.rename_sub = wrap_node(require("nvim-tree.actions").fs.rename_file.fn(":p:h"))
+  api.fs.rename_basename = wrap_node(require("nvim-tree.actions").fs.rename_file.fn(":t:r"))
+  api.fs.rename_full = wrap_node(require("nvim-tree.actions").fs.rename_file.fn(":p"))
   api.fs.cut = wrap_node(wrap_explorer_member("clipboard", "cut"))
   api.fs.paste = wrap_node(wrap_explorer_member("clipboard", "paste"))
   api.fs.clear_clipboard = wrap_explorer_member("clipboard", "clear_clipboard")
@@ -188,34 +184,34 @@ local function hydrate_post(api)
   api.node.open.preview = wrap_node(open_or_expand_or_dir_up("preview"))
   api.node.open.preview_no_picker = wrap_node(open_or_expand_or_dir_up("preview_no_picker"))
 
-  api.node.show_info_popup = wrap_node(actions.node.file_popup.toggle_file_info)
-  api.node.run.cmd = wrap_node(actions.node.run_command.run_file_command)
-  api.node.run.system = wrap_node(actions.node.system_open.fn)
-
-  api.node.navigate.sibling.next = wrap_node(actions.moves.sibling.fn("next"))
-  api.node.navigate.sibling.prev = wrap_node(actions.moves.sibling.fn("prev"))
-  api.node.navigate.sibling.first = wrap_node(actions.moves.sibling.fn("first"))
-  api.node.navigate.sibling.last = wrap_node(actions.moves.sibling.fn("last"))
-  api.node.navigate.parent = wrap_node(actions.moves.parent.fn(false))
-  api.node.navigate.parent_close = wrap_node(actions.moves.parent.fn(true))
-  api.node.navigate.git.next = wrap_node(actions.moves.item.fn({ where = "next", what = "git" }))
-  api.node.navigate.git.next_skip_gitignored = wrap_node(actions.moves.item.fn({ where = "next", what = "git", skip_gitignored = true }))
-  api.node.navigate.git.next_recursive = wrap_node(actions.moves.item.fn({ where = "next", what = "git", recurse = true }))
-  api.node.navigate.git.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "git" }))
-  api.node.navigate.git.prev_skip_gitignored = wrap_node(actions.moves.item.fn({ where = "prev", what = "git", skip_gitignored = true }))
-  api.node.navigate.git.prev_recursive = wrap_node(actions.moves.item.fn({ where = "prev", what = "git", recurse = true }))
-  api.node.navigate.diagnostics.next = wrap_node(actions.moves.item.fn({ where = "next", what = "diag" }))
-  api.node.navigate.diagnostics.next_recursive = wrap_node(actions.moves.item.fn({ where = "next", what = "diag", recurse = true }))
-  api.node.navigate.diagnostics.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "diag" }))
-  api.node.navigate.diagnostics.prev_recursive = wrap_node(actions.moves.item.fn({ where = "prev", what = "diag", recurse = true }))
-  api.node.navigate.opened.next = wrap_node(actions.moves.item.fn({ where = "next", what = "opened" }))
-  api.node.navigate.opened.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "opened" }))
-
-  api.node.expand = wrap_node(actions.tree.modifiers.expand.node)
-  api.node.collapse = wrap_node(actions.tree.modifiers.collapse.node)
-
-  api.node.buffer.delete = wrap_node(function(node, opts) actions.node.buffer.delete(node, opts) end)
-  api.node.buffer.wipe = wrap_node(function(node, opts) actions.node.buffer.wipe(node, opts) end)
+  api.node.show_info_popup = wrap_node(require("nvim-tree.actions").node.file_popup.toggle_file_info)
+  api.node.run.cmd = wrap_node(require("nvim-tree.actions").node.run_command.run_file_command)
+  api.node.run.system = wrap_node(require("nvim-tree.actions").node.system_open.fn)
+
+  api.node.navigate.sibling.next = wrap_node(require("nvim-tree.actions").moves.sibling.fn("next"))
+  api.node.navigate.sibling.prev = wrap_node(require("nvim-tree.actions").moves.sibling.fn("prev"))
+  api.node.navigate.sibling.first = wrap_node(require("nvim-tree.actions").moves.sibling.fn("first"))
+  api.node.navigate.sibling.last = wrap_node(require("nvim-tree.actions").moves.sibling.fn("last"))
+  api.node.navigate.parent = wrap_node(require("nvim-tree.actions").moves.parent.fn(false))
+  api.node.navigate.parent_close = wrap_node(require("nvim-tree.actions").moves.parent.fn(true))
+  api.node.navigate.git.next = wrap_node(require("nvim-tree.actions").moves.item.fn({ where = "next", what = "git" }))
+  api.node.navigate.git.next_skip_gitignored = wrap_node(require("nvim-tree.actions").moves.item.fn({ where = "next", what = "git", skip_gitignored = true }))
+  api.node.navigate.git.next_recursive = wrap_node(require("nvim-tree.actions").moves.item.fn({ where = "next", what = "git", recurse = true }))
+  api.node.navigate.git.prev = wrap_node(require("nvim-tree.actions").moves.item.fn({ where = "prev", what = "git" }))
+  api.node.navigate.git.prev_skip_gitignored = wrap_node(require("nvim-tree.actions").moves.item.fn({ where = "prev", what = "git", skip_gitignored = true }))
+  api.node.navigate.git.prev_recursive = wrap_node(require("nvim-tree.actions").moves.item.fn({ where = "prev", what = "git", recurse = true }))
+  api.node.navigate.diagnostics.next = wrap_node(require("nvim-tree.actions").moves.item.fn({ where = "next", what = "diag" }))
+  api.node.navigate.diagnostics.next_recursive = wrap_node(require("nvim-tree.actions").moves.item.fn({ where = "next", what = "diag", recurse = true }))
+  api.node.navigate.diagnostics.prev = wrap_node(require("nvim-tree.actions").moves.item.fn({ where = "prev", what = "diag" }))
+  api.node.navigate.diagnostics.prev_recursive = wrap_node(require("nvim-tree.actions").moves.item.fn({ where = "prev", what = "diag", recurse = true }))
+  api.node.navigate.opened.next = wrap_node(require("nvim-tree.actions").moves.item.fn({ where = "next", what = "opened" }))
+  api.node.navigate.opened.prev = wrap_node(require("nvim-tree.actions").moves.item.fn({ where = "prev", what = "opened" }))
+
+  api.node.expand = wrap_node(require("nvim-tree.actions").tree.modifiers.expand.node)
+  api.node.collapse = wrap_node(require("nvim-tree.actions").tree.modifiers.collapse.node)
+
+  api.node.buffer.delete = wrap_node(function(node, opts) require("nvim-tree.actions").node.buffer.delete(node, opts) end)
+  api.node.buffer.wipe = wrap_node(function(node, opts) require("nvim-tree.actions").node.buffer.wipe(node, opts) end)
 
   api.tree.reload_git = wrap_explorer("reload_git")
 
@@ -242,11 +238,6 @@ local function hydrate_post(api)
 
   api.map.get_keymap = function() require("nvim-tree.keymap").get_keymap() end
   api.map.get_keymap_default = function() require("nvim-tree.keymap").get_keymap_default() end
-
-  api.health.hi_test = function() require("nvim-tree.appearance.hi-test")() end
-
-  -- TODO #3231 this should be OK pre
-  api.commands.get = function() require("nvim-tree.commands").get() end
 end
 
 ---Hydrates all API functions with concrete implementations.
diff --git a/lua/nvim-tree/api/impl/pre.lua b/lua/nvim-tree/api/impl/pre.lua
index db7c08fce1b..0027c4fbd79 100644
--- a/lua/nvim-tree/api/impl/pre.lua
+++ b/lua/nvim-tree/api/impl/pre.lua
@@ -1,3 +1,6 @@
+--This file should have no requires barring the essentials.
+--Everything must be as lazily loaded as possible.
+--The user must be able to require api cheaply and run setup cheaply.
 local events = require("nvim-tree.events")
 local keymap = require("nvim-tree.keymap")
 local notify = require("nvim-tree.notify")
@@ -6,14 +9,14 @@ local UserDecorator = require("nvim-tree.renderer.decorator.user")
 
 ---Walk the api, hydrating all functions with the error notification
 ---@param t table api root or sub-module
-local function hydrate_notify(t)
+local function hydrate_error(t)
   for k, v in pairs(t) do
     if type(v) == "function" then
       t[k] = function()
         notify.error("nvim-tree setup not called")
       end
     elseif type(v) == "table" then
-      hydrate_notify(v)
+      hydrate_error(v)
     end
   end
 end
@@ -21,8 +24,18 @@ end
 ---Hydrate implementations that may be called pre setup
 ---@param api table
 local function hydrate_pre(api)
-  api.events.subscribe = events.subscribe
+  --
+  -- May be lazily requried on execution
+  --
+  api.commands.get = function() require("nvim-tree.commands").get() end
+
+  api.health.hi_test = function() require("nvim-tree.appearance.hi-test")() end
+
+  --
+  -- Must be eagerly required or common
+  --
   api.events.Event = events.Event
+  api.events.subscribe = events.subscribe
 
   api.map.default_on_attach = keymap.default_on_attach
 
@@ -36,15 +49,11 @@ end
 --Hydrates meta api empty definition functions with a new function:
 -- - Default: error notification "nvim-tree setup not called".
 -- - Exceptions: concrete implementation for API that can be called before setup.
---
 --Call it once when api is first required
---
---This should not include any requires beyond that which is absolutely essential,
---as the user should be able to require api cheaply.
 ---@param api table
 return function(api)
   -- Default: error
-  hydrate_notify(api)
+  hydrate_error(api)
 
   -- Exceptions: may be called
   hydrate_pre(api)

From 728e85106e9fdce13adb6c5c1485882b1b9ab1d7 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sat, 24 Jan 2026 15:51:16 +1100
Subject: [PATCH 137/170] Revert "docs(#3088): lazy api impl requires"

This reverts commit c6ea6c5be1aab9792fa45e1a749e6bc90d58a6bc.
---
 lua/nvim-tree/api/impl/post.lua | 127 +++++++++++++++++---------------
 lua/nvim-tree/api/impl/pre.lua  |  25 ++-----
 2 files changed, 76 insertions(+), 76 deletions(-)

diff --git a/lua/nvim-tree/api/impl/post.lua b/lua/nvim-tree/api/impl/post.lua
index 413dabb6f34..b8f42f5d8ba 100644
--- a/lua/nvim-tree/api/impl/post.lua
+++ b/lua/nvim-tree/api/impl/post.lua
@@ -1,7 +1,12 @@
---This file should have no requires. Everything must be lazy loaded.
---The user must be able to require api cheaply and run setup cheaply.
+local view = require("nvim-tree.view")
+local actions = require("nvim-tree.actions")
+
+local DirectoryNode = require("nvim-tree.node.directory")
+local FileLinkNode = require("nvim-tree.node.file-link")
+local RootNode = require("nvim-tree.node.root")
 
 ---Invoke a method on the singleton explorer.
+---Print error when setup not called.
 ---@param explorer_method string explorer method name
 ---@return fun(...): any
 local function wrap_explorer(explorer_method)
@@ -36,6 +41,7 @@ local function wrap_node_or_nil(fn)
 end
 
 ---Invoke a member's method on the singleton explorer.
+---Print error when setup not called.
 ---@param explorer_member string explorer member name
 ---@param member_method string method name to invoke on member
 ---@param ... any passed to method
@@ -51,6 +57,7 @@ local function wrap_explorer_member_args(explorer_member, member_method, ...)
 end
 
 ---Invoke a member's method on the singleton explorer.
+---Print error when setup not called.
 ---@param explorer_member string explorer member name
 ---@param member_method string method name to invoke on member
 ---@return fun(...): any
@@ -71,10 +78,7 @@ end
 ---@param node Node
 ---@param edit_opts NodeEditOpts?
 local function edit(mode, node, edit_opts)
-  local actions = require("nvim-tree.actions")
-  local view = require("nvim-tree.view")
-
-  local file_link = node:as(require("nvim-tree.node.file-link"))
+  local file_link = node:as(FileLinkNode)
   local path = file_link and file_link.link_to or node.absolute_path
   local cur_tabpage = vim.api.nvim_get_current_tabpage()
 
@@ -105,11 +109,11 @@ local function open_or_expand_or_dir_up(mode, toggle_group)
   ---@param node Node
   ---@param edit_opts NodeEditOpts?
   return function(node, edit_opts)
-    local root = node:as(require("nvim-tree.node.root"))
-    local dir = node:as(require("nvim-tree.node.directory"))
+    local root = node:as(RootNode)
+    local dir = node:as(DirectoryNode)
 
     if root or node.name == ".." then
-      require("nvim-tree.actions").root.change_dir.fn("..")
+      actions.root.change_dir.fn("..")
     elseif dir then
       dir:expand_or_collapse(toggle_group)
     elseif not toggle_group then
@@ -121,45 +125,45 @@ end
 ---Hydrate all implementations barring those that were called during hydrate_pre
 ---@param api table
 local function hydrate_post(api)
-  api.tree.open = function(...) require("nvim-tree.actions").tree.open.fn(...) end
+  api.tree.open = actions.tree.open.fn
   api.tree.focus = api.tree.open
 
-  api.tree.toggle = function(...) require("nvim-tree.actions").tree.toggle.fn(...) end
-  api.tree.close = function(...) require("nvim-tree.view").close(...) end
-  api.tree.close_in_this_tab = function() require("nvim-tree.view").close_this_tab_only() end
-  api.tree.close_in_all_tabs = function() require("nvim-tree.view").close_all_tabs() end
+  api.tree.toggle = actions.tree.toggle.fn
+  api.tree.close = view.close
+  api.tree.close_in_this_tab = view.close_this_tab_only
+  api.tree.close_in_all_tabs = view.close_all_tabs
   api.tree.reload = wrap_explorer("reload_explorer")
 
-  api.tree.resize = function(...) require("nvim-tree.actions").tree.resize.fn(...) end
+  api.tree.resize = actions.tree.resize.fn
 
-  api.tree.change_root = function(...) require("nvim-tree").change_dir(...) end
+  api.tree.change_root = require("nvim-tree").change_dir
 
   api.tree.change_root_to_node = wrap_node(wrap_explorer("change_dir_to_node"))
   api.tree.change_root_to_parent = wrap_node(wrap_explorer("dir_up"))
   api.tree.get_node_under_cursor = wrap_explorer("get_node_at_cursor")
   api.tree.get_nodes = wrap_explorer("get_nodes")
 
-  api.tree.find_file = function(...) require("nvim-tree.actions").tree.find_file.fn(...) end
-  api.tree.search_node = function() require("nvim-tree.actions").finders.search_node.fn() end
+  api.tree.find_file = actions.tree.find_file.fn
+  api.tree.search_node = actions.finders.search_node.fn
 
-  api.tree.collapse_all = function(...) require("nvim-tree.actions").tree.modifiers.collapse.all(...) end
+  api.tree.collapse_all = actions.tree.modifiers.collapse.all
 
-  api.tree.expand_all = wrap_node(require("nvim-tree.actions").tree.modifiers.expand.all)
+  api.tree.expand_all = wrap_node(actions.tree.modifiers.expand.all)
   api.tree.toggle_help = function() require("nvim-tree.help").toggle() end
-  api.tree.is_tree_buf = function(...) require("nvim-tree.utils").is_nvim_tree_buf(...) end
+  api.tree.is_tree_buf = function() require("nvim-tree.utils").is_nvim_tree_buf() end
 
-  api.tree.is_visible = function(...) require("nvim-tree.view").is_visible(...) end
+  api.tree.is_visible = view.is_visible
 
-  api.tree.winid = function(...) require("nvim-tree.view").winid(...) end
+  api.tree.winid = view.winid
 
-  api.fs.create = wrap_node_or_nil(require("nvim-tree.actions").fs.create_file.fn)
-  api.fs.remove = wrap_node(require("nvim-tree.actions").fs.remove_file.fn)
-  api.fs.trash = wrap_node(require("nvim-tree.actions").fs.trash.fn)
-  api.fs.rename_node = wrap_node(require("nvim-tree.actions").fs.rename_file.fn(":t"))
-  api.fs.rename = wrap_node(require("nvim-tree.actions").fs.rename_file.fn(":t"))
-  api.fs.rename_sub = wrap_node(require("nvim-tree.actions").fs.rename_file.fn(":p:h"))
-  api.fs.rename_basename = wrap_node(require("nvim-tree.actions").fs.rename_file.fn(":t:r"))
-  api.fs.rename_full = wrap_node(require("nvim-tree.actions").fs.rename_file.fn(":p"))
+  api.fs.create = wrap_node_or_nil(actions.fs.create_file.fn)
+  api.fs.remove = wrap_node(actions.fs.remove_file.fn)
+  api.fs.trash = wrap_node(actions.fs.trash.fn)
+  api.fs.rename_node = wrap_node(actions.fs.rename_file.fn(":t"))
+  api.fs.rename = wrap_node(actions.fs.rename_file.fn(":t"))
+  api.fs.rename_sub = wrap_node(actions.fs.rename_file.fn(":p:h"))
+  api.fs.rename_basename = wrap_node(actions.fs.rename_file.fn(":t:r"))
+  api.fs.rename_full = wrap_node(actions.fs.rename_file.fn(":p"))
   api.fs.cut = wrap_node(wrap_explorer_member("clipboard", "cut"))
   api.fs.paste = wrap_node(wrap_explorer_member("clipboard", "paste"))
   api.fs.clear_clipboard = wrap_explorer_member("clipboard", "clear_clipboard")
@@ -184,34 +188,34 @@ local function hydrate_post(api)
   api.node.open.preview = wrap_node(open_or_expand_or_dir_up("preview"))
   api.node.open.preview_no_picker = wrap_node(open_or_expand_or_dir_up("preview_no_picker"))
 
-  api.node.show_info_popup = wrap_node(require("nvim-tree.actions").node.file_popup.toggle_file_info)
-  api.node.run.cmd = wrap_node(require("nvim-tree.actions").node.run_command.run_file_command)
-  api.node.run.system = wrap_node(require("nvim-tree.actions").node.system_open.fn)
-
-  api.node.navigate.sibling.next = wrap_node(require("nvim-tree.actions").moves.sibling.fn("next"))
-  api.node.navigate.sibling.prev = wrap_node(require("nvim-tree.actions").moves.sibling.fn("prev"))
-  api.node.navigate.sibling.first = wrap_node(require("nvim-tree.actions").moves.sibling.fn("first"))
-  api.node.navigate.sibling.last = wrap_node(require("nvim-tree.actions").moves.sibling.fn("last"))
-  api.node.navigate.parent = wrap_node(require("nvim-tree.actions").moves.parent.fn(false))
-  api.node.navigate.parent_close = wrap_node(require("nvim-tree.actions").moves.parent.fn(true))
-  api.node.navigate.git.next = wrap_node(require("nvim-tree.actions").moves.item.fn({ where = "next", what = "git" }))
-  api.node.navigate.git.next_skip_gitignored = wrap_node(require("nvim-tree.actions").moves.item.fn({ where = "next", what = "git", skip_gitignored = true }))
-  api.node.navigate.git.next_recursive = wrap_node(require("nvim-tree.actions").moves.item.fn({ where = "next", what = "git", recurse = true }))
-  api.node.navigate.git.prev = wrap_node(require("nvim-tree.actions").moves.item.fn({ where = "prev", what = "git" }))
-  api.node.navigate.git.prev_skip_gitignored = wrap_node(require("nvim-tree.actions").moves.item.fn({ where = "prev", what = "git", skip_gitignored = true }))
-  api.node.navigate.git.prev_recursive = wrap_node(require("nvim-tree.actions").moves.item.fn({ where = "prev", what = "git", recurse = true }))
-  api.node.navigate.diagnostics.next = wrap_node(require("nvim-tree.actions").moves.item.fn({ where = "next", what = "diag" }))
-  api.node.navigate.diagnostics.next_recursive = wrap_node(require("nvim-tree.actions").moves.item.fn({ where = "next", what = "diag", recurse = true }))
-  api.node.navigate.diagnostics.prev = wrap_node(require("nvim-tree.actions").moves.item.fn({ where = "prev", what = "diag" }))
-  api.node.navigate.diagnostics.prev_recursive = wrap_node(require("nvim-tree.actions").moves.item.fn({ where = "prev", what = "diag", recurse = true }))
-  api.node.navigate.opened.next = wrap_node(require("nvim-tree.actions").moves.item.fn({ where = "next", what = "opened" }))
-  api.node.navigate.opened.prev = wrap_node(require("nvim-tree.actions").moves.item.fn({ where = "prev", what = "opened" }))
-
-  api.node.expand = wrap_node(require("nvim-tree.actions").tree.modifiers.expand.node)
-  api.node.collapse = wrap_node(require("nvim-tree.actions").tree.modifiers.collapse.node)
-
-  api.node.buffer.delete = wrap_node(function(node, opts) require("nvim-tree.actions").node.buffer.delete(node, opts) end)
-  api.node.buffer.wipe = wrap_node(function(node, opts) require("nvim-tree.actions").node.buffer.wipe(node, opts) end)
+  api.node.show_info_popup = wrap_node(actions.node.file_popup.toggle_file_info)
+  api.node.run.cmd = wrap_node(actions.node.run_command.run_file_command)
+  api.node.run.system = wrap_node(actions.node.system_open.fn)
+
+  api.node.navigate.sibling.next = wrap_node(actions.moves.sibling.fn("next"))
+  api.node.navigate.sibling.prev = wrap_node(actions.moves.sibling.fn("prev"))
+  api.node.navigate.sibling.first = wrap_node(actions.moves.sibling.fn("first"))
+  api.node.navigate.sibling.last = wrap_node(actions.moves.sibling.fn("last"))
+  api.node.navigate.parent = wrap_node(actions.moves.parent.fn(false))
+  api.node.navigate.parent_close = wrap_node(actions.moves.parent.fn(true))
+  api.node.navigate.git.next = wrap_node(actions.moves.item.fn({ where = "next", what = "git" }))
+  api.node.navigate.git.next_skip_gitignored = wrap_node(actions.moves.item.fn({ where = "next", what = "git", skip_gitignored = true }))
+  api.node.navigate.git.next_recursive = wrap_node(actions.moves.item.fn({ where = "next", what = "git", recurse = true }))
+  api.node.navigate.git.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "git" }))
+  api.node.navigate.git.prev_skip_gitignored = wrap_node(actions.moves.item.fn({ where = "prev", what = "git", skip_gitignored = true }))
+  api.node.navigate.git.prev_recursive = wrap_node(actions.moves.item.fn({ where = "prev", what = "git", recurse = true }))
+  api.node.navigate.diagnostics.next = wrap_node(actions.moves.item.fn({ where = "next", what = "diag" }))
+  api.node.navigate.diagnostics.next_recursive = wrap_node(actions.moves.item.fn({ where = "next", what = "diag", recurse = true }))
+  api.node.navigate.diagnostics.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "diag" }))
+  api.node.navigate.diagnostics.prev_recursive = wrap_node(actions.moves.item.fn({ where = "prev", what = "diag", recurse = true }))
+  api.node.navigate.opened.next = wrap_node(actions.moves.item.fn({ where = "next", what = "opened" }))
+  api.node.navigate.opened.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "opened" }))
+
+  api.node.expand = wrap_node(actions.tree.modifiers.expand.node)
+  api.node.collapse = wrap_node(actions.tree.modifiers.collapse.node)
+
+  api.node.buffer.delete = wrap_node(function(node, opts) actions.node.buffer.delete(node, opts) end)
+  api.node.buffer.wipe = wrap_node(function(node, opts) actions.node.buffer.wipe(node, opts) end)
 
   api.tree.reload_git = wrap_explorer("reload_git")
 
@@ -238,6 +242,11 @@ local function hydrate_post(api)
 
   api.map.get_keymap = function() require("nvim-tree.keymap").get_keymap() end
   api.map.get_keymap_default = function() require("nvim-tree.keymap").get_keymap_default() end
+
+  api.health.hi_test = function() require("nvim-tree.appearance.hi-test")() end
+
+  -- TODO #3231 this should be OK pre
+  api.commands.get = function() require("nvim-tree.commands").get() end
 end
 
 ---Hydrates all API functions with concrete implementations.
diff --git a/lua/nvim-tree/api/impl/pre.lua b/lua/nvim-tree/api/impl/pre.lua
index 0027c4fbd79..db7c08fce1b 100644
--- a/lua/nvim-tree/api/impl/pre.lua
+++ b/lua/nvim-tree/api/impl/pre.lua
@@ -1,6 +1,3 @@
---This file should have no requires barring the essentials.
---Everything must be as lazily loaded as possible.
---The user must be able to require api cheaply and run setup cheaply.
 local events = require("nvim-tree.events")
 local keymap = require("nvim-tree.keymap")
 local notify = require("nvim-tree.notify")
@@ -9,14 +6,14 @@ local UserDecorator = require("nvim-tree.renderer.decorator.user")
 
 ---Walk the api, hydrating all functions with the error notification
 ---@param t table api root or sub-module
-local function hydrate_error(t)
+local function hydrate_notify(t)
   for k, v in pairs(t) do
     if type(v) == "function" then
       t[k] = function()
         notify.error("nvim-tree setup not called")
       end
     elseif type(v) == "table" then
-      hydrate_error(v)
+      hydrate_notify(v)
     end
   end
 end
@@ -24,18 +21,8 @@ end
 ---Hydrate implementations that may be called pre setup
 ---@param api table
 local function hydrate_pre(api)
-  --
-  -- May be lazily requried on execution
-  --
-  api.commands.get = function() require("nvim-tree.commands").get() end
-
-  api.health.hi_test = function() require("nvim-tree.appearance.hi-test")() end
-
-  --
-  -- Must be eagerly required or common
-  --
-  api.events.Event = events.Event
   api.events.subscribe = events.subscribe
+  api.events.Event = events.Event
 
   api.map.default_on_attach = keymap.default_on_attach
 
@@ -49,11 +36,15 @@ end
 --Hydrates meta api empty definition functions with a new function:
 -- - Default: error notification "nvim-tree setup not called".
 -- - Exceptions: concrete implementation for API that can be called before setup.
+--
 --Call it once when api is first required
+--
+--This should not include any requires beyond that which is absolutely essential,
+--as the user should be able to require api cheaply.
 ---@param api table
 return function(api)
   -- Default: error
-  hydrate_error(api)
+  hydrate_notify(api)
 
   -- Exceptions: may be called
   hydrate_pre(api)

From 49b0b8017553055c84a15fcf3ca8ab3b216de28a Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sat, 24 Jan 2026 16:17:50 +1100
Subject: [PATCH 138/170] docs(#3088): minimise api pre following tests

---
 lua/nvim-tree/_meta/api/events.lua |  2 --
 lua/nvim-tree/api/impl/post.lua    |  6 -----
 lua/nvim-tree/api/impl/pre.lua     | 35 ++++++++++++++++++++----------
 3 files changed, 23 insertions(+), 20 deletions(-)

diff --git a/lua/nvim-tree/_meta/api/events.lua b/lua/nvim-tree/_meta/api/events.lua
index 846598f6543..7e79e1c2c65 100644
--- a/lua/nvim-tree/_meta/api/events.lua
+++ b/lua/nvim-tree/_meta/api/events.lua
@@ -8,6 +8,4 @@ local nvim_tree = { api = { events = {} } }
 ---@param callback fun(payload: table?)
 function nvim_tree.api.events.subscribe(event_type, callback) end
 
-nvim_tree.api.events.Event = require("nvim-tree.events").Event
-
 return nvim_tree.api.events
diff --git a/lua/nvim-tree/api/impl/post.lua b/lua/nvim-tree/api/impl/post.lua
index b8f42f5d8ba..59bb54bbd5a 100644
--- a/lua/nvim-tree/api/impl/post.lua
+++ b/lua/nvim-tree/api/impl/post.lua
@@ -241,12 +241,6 @@ local function hydrate_post(api)
   api.marks.navigate.select = wrap_explorer_member("marks", "navigate_select")
 
   api.map.get_keymap = function() require("nvim-tree.keymap").get_keymap() end
-  api.map.get_keymap_default = function() require("nvim-tree.keymap").get_keymap_default() end
-
-  api.health.hi_test = function() require("nvim-tree.appearance.hi-test")() end
-
-  -- TODO #3231 this should be OK pre
-  api.commands.get = function() require("nvim-tree.commands").get() end
 end
 
 ---Hydrates all API functions with concrete implementations.
diff --git a/lua/nvim-tree/api/impl/pre.lua b/lua/nvim-tree/api/impl/pre.lua
index db7c08fce1b..44a815b7bc8 100644
--- a/lua/nvim-tree/api/impl/pre.lua
+++ b/lua/nvim-tree/api/impl/pre.lua
@@ -1,19 +1,23 @@
-local events = require("nvim-tree.events")
-local keymap = require("nvim-tree.keymap")
-local notify = require("nvim-tree.notify")
+--This file should have minimal requires that are cheap and have no dependencies or are already required.
+--Everything must be as lazily loaded as possible: the user must be able to require api cheaply.
 
-local UserDecorator = require("nvim-tree.renderer.decorator.user")
+local commands = require("nvim-tree.commands") -- already required by plugin.lua
+local events = require("nvim-tree.events")     -- needed for event registration pre-setup
+local keymap = require("nvim-tree.keymap")     -- needed for default on attach
+local notify = require("nvim-tree.notify")     -- already required by events and others
+
+local UserDecorator = require("nvim-tree.renderer.decorator.user") -- TODO #3241
 
 ---Walk the api, hydrating all functions with the error notification
 ---@param t table api root or sub-module
-local function hydrate_notify(t)
+local function hydrate_error(t)
   for k, v in pairs(t) do
     if type(v) == "function" then
       t[k] = function()
         notify.error("nvim-tree setup not called")
       end
     elseif type(v) == "table" then
-      hydrate_notify(v)
+      hydrate_error(v)
     end
   end
 end
@@ -21,10 +25,21 @@ end
 ---Hydrate implementations that may be called pre setup
 ---@param api table
 local function hydrate_pre(api)
-  api.events.subscribe = events.subscribe
+  --
+  -- May be lazily requried on execution
+  --
+  api.health.hi_test = function() require("nvim-tree.appearance.hi-test")() end
+
+  --
+  -- Essential or already required elsewhere
+  --
+  api.commands.get = commands.get
+
   api.events.Event = events.Event
+  api.events.subscribe = events.subscribe
 
   api.map.default_on_attach = keymap.default_on_attach
+  api.map.get_keymap_default = keymap.get_keymap_default
 
   api.decorator = {}
   ---Create a decorator class by calling :extend()
@@ -36,15 +51,11 @@ end
 --Hydrates meta api empty definition functions with a new function:
 -- - Default: error notification "nvim-tree setup not called".
 -- - Exceptions: concrete implementation for API that can be called before setup.
---
 --Call it once when api is first required
---
---This should not include any requires beyond that which is absolutely essential,
---as the user should be able to require api cheaply.
 ---@param api table
 return function(api)
   -- Default: error
-  hydrate_notify(api)
+  hydrate_error(api)
 
   -- Exceptions: may be called
   hydrate_pre(api)

From b3e8a6332393f0bea1047c6fc4e89f31c5905957 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sat, 24 Jan 2026 16:49:30 +1100
Subject: [PATCH 139/170] docs(#3088): move node classes under api with logical
 order

---
 doc/nvim-tree-lua.txt                         | 136 +++++++++---------
 lua/nvim-tree/_meta/api/classes01.lua         |  21 +++
 .../_meta/api/{classes.lua => classes02.lua}  |  16 +--
 lua/nvim-tree/api.lua                         |   2 +-
 scripts/gen_vimdoc_config.lua                 |  13 +-
 5 files changed, 103 insertions(+), 85 deletions(-)
 create mode 100644 lua/nvim-tree/_meta/api/classes01.lua
 rename lua/nvim-tree/_meta/api/{classes.lua => classes02.lua} (63%)

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 9af82ddba53..1a62995a01f 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -2379,9 +2379,9 @@ Example invocation of the `reload` function in the `tree` module: >lua
     api.tree.reload()
 <
 
-Generally, functions accepting a {node} as their first argument will use the
-node under the cursor when that argument is not present or nil. e.g. the
-following are functionally identical: >lua
+Generally, functions accepting a |nvim_tree.api.Node| as their first argument
+will use the node under the cursor when that argument is not present or nil.
+e.g. the following are functionally identical: >lua
 
     api.node.open.edit(nil, { focus = true })
 
@@ -2390,6 +2390,74 @@ following are functionally identical: >lua
 
 
 
+
+
+Base Node class:
+
+
+*nvim_tree.api.Node*
+    Base Node, Abstract
+
+    Fields: ~
+      • {type}            (`"file"|"directory"|"link"`) uv.fs_stat.result.type
+      • {absolute_path}   (`string`)
+      • {executable}      (`boolean`)
+      • {fs_stat}?        (`uv.fs_stat.result`)
+      • {git_status}?     (`GitNodeStatus`)
+      • {hidden}          (`boolean`)
+      • {name}            (`string`)
+      • {parent}?         (`nvim_tree.api.DirectoryNode`)
+      • {diag_severity}?  (`lsp.DiagnosticSeverity`)
+
+
+
+
+
+Node subclasses:
+
+
+*nvim_tree.api.DirectoryLinkNode*
+    Extends: |nvim_tree.api.DirectoryNode|
+
+    DirectoryLink
+
+*nvim_tree.api.DirectoryNode*
+    Extends: |nvim_tree.api.Node|
+
+    Directory
+
+    Fields: ~
+      • {has_children}  (`boolean`)
+      • {nodes}         (`nvim_tree.api.Node[]`)
+      • {open}          (`boolean`)
+
+*nvim_tree.api.FileLinkNode*
+    Extends: |nvim_tree.api.FileNode|
+
+    File Link
+
+*nvim_tree.api.FileNode*
+    Extends: |nvim_tree.api.Node|
+
+    File
+
+    Fields: ~
+      • {extension}  (`string`)
+
+*nvim_tree.api.LinkNode*
+    Link mixin
+
+    Fields: ~
+      • {link_to}         (`string`)
+      • {fs_stat_target}  (`uv.fs_stat.result`)
+
+*nvim_tree.api.RootNode*
+    Extends: |nvim_tree.api.DirectoryNode|
+
+    Root Directory
+
+
+
 ==============================================================================
 API: commands                                         *nvim-tree-api-commands*
 
@@ -3149,66 +3217,4 @@ winid({opts})                                     *nvim_tree.api.tree.winid()*
         (`integer?`) |window-ID|, nil if tree is not visible.
 
 
-==============================================================================
-API: Classes                                           *nvim-tree-api-classes*
-
-Classes shared by multiple API modules.
-
-
-*nvim_tree.api.DirectoryLinkNode*
-    Extends: |nvim_tree.api.DirectoryNode|
-
-    DirectoryLink
-
-*nvim_tree.api.DirectoryNode*
-    Extends: |nvim_tree.api.Node|
-
-    Directory
-
-    Fields: ~
-      • {has_children}  (`boolean`)
-      • {nodes}         (`nvim_tree.api.Node[]`)
-      • {open}          (`boolean`)
-
-*nvim_tree.api.FileLinkNode*
-    Extends: |nvim_tree.api.FileNode|
-
-    File Link
-
-*nvim_tree.api.FileNode*
-    Extends: |nvim_tree.api.Node|
-
-    File
-
-    Fields: ~
-      • {extension}  (`string`)
-
-*nvim_tree.api.LinkNode*
-    Link mixin
-
-    Fields: ~
-      • {link_to}         (`string`)
-      • {fs_stat_target}  (`uv.fs_stat.result`)
-
-*nvim_tree.api.Node*
-    Base Node, Abstract
-
-    Fields: ~
-      • {type}           (`"file"|"directory"|"link"`) uv.fs_stat.result.type
-      • {absolute_path}  (`string`)
-      • {executable}     (`boolean`)
-      • {fs_stat}        (`uv.fs_stat.result?`)
-      • {git_status}     (`GitNodeStatus?`)
-      • {hidden}         (`boolean`)
-      • {name}           (`string`)
-      • {parent}         (`nvim_tree.api.DirectoryNode?`)
-      • {diag_severity}  (`lsp.DiagnosticSeverity?`)
-
-*nvim_tree.api.RootNode*
-    Extends: |nvim_tree.api.DirectoryNode|
-
-    Root Directory
-
-
-
  vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:
diff --git a/lua/nvim-tree/_meta/api/classes01.lua b/lua/nvim-tree/_meta/api/classes01.lua
new file mode 100644
index 00000000000..c3509bddc6a
--- /dev/null
+++ b/lua/nvim-tree/_meta/api/classes01.lua
@@ -0,0 +1,21 @@
+---@meta
+
+-- TODO #3088 document these
+
+---@brief
+---Base Node class:
+---
+
+---
+---Base Node, Abstract
+---
+---@class nvim_tree.api.Node
+---@field type "file" | "directory" | "link" uv.fs_stat.result.type
+---@field absolute_path string
+---@field executable boolean
+---@field fs_stat? uv.fs_stat.result
+---@field git_status? GitNodeStatus
+---@field hidden boolean
+---@field name string
+---@field parent? nvim_tree.api.DirectoryNode
+---@field diag_severity? lsp.DiagnosticSeverity
diff --git a/lua/nvim-tree/_meta/api/classes.lua b/lua/nvim-tree/_meta/api/classes02.lua
similarity index 63%
rename from lua/nvim-tree/_meta/api/classes.lua
rename to lua/nvim-tree/_meta/api/classes02.lua
index 44b869f5a6e..82a412861e8 100644
--- a/lua/nvim-tree/_meta/api/classes.lua
+++ b/lua/nvim-tree/_meta/api/classes02.lua
@@ -3,23 +3,9 @@
 -- TODO #3088 document these
 
 ---@brief
----Classes shared by multiple API modules.
+---Node subclasses:
 ---
 
----
----Base Node, Abstract
----
----@class nvim_tree.api.Node
----@field type "file" | "directory" | "link" uv.fs_stat.result.type
----@field absolute_path string
----@field executable boolean
----@field fs_stat uv.fs_stat.result?
----@field git_status GitNodeStatus?
----@field hidden boolean
----@field name string
----@field parent nvim_tree.api.DirectoryNode?
----@field diag_severity lsp.DiagnosticSeverity?
-
 ---
 ---File
 ---
diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index ce0788d6d03..a915fe1b054 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -25,7 +25,7 @@ local api = {}
 ---local api = require("nvim-tree.api")
 ---api.tree.reload()
 ---```
----Generally, functions accepting a {node} as their first argument will use the node under the cursor when that argument is not present or nil. e.g. the following are functionally identical:
+---Generally, functions accepting a [nvim_tree.api.Node] as their first argument will use the node under the cursor when that argument is not present or nil. e.g. the following are functionally identical:
 ---```lua
 ---
 ---api.node.open.edit(nil, { focus = true })
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index c0be9d080f4..d38148db1aa 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -6,8 +6,9 @@
 ---@field helptag string must be globally unique
 ---@field section string arbitrary
 ---@field path string relative to root
----@field file_name string? generated from path
----@field name string? override generated name
+---@field file_name? string generated from path
+---@field name? string override generated name
+---@field append_only? boolean follows previous section
 
 ---Help txt is deleted from first tag down and generated content is appended.
 ---@type Src[]
@@ -39,6 +40,10 @@ local srcs = {
 
   { helptag = "nvim-tree-api",                        section = "API",                         path = "./lua/nvim_tree/api.lua", },
 
+  -- logically ordered classes with no section
+  { helptag = "xxx",                                  section = "XXX",                         path = "./lua/nvim_tree/_meta/api/classes01.lua",              append_only = true, },
+  { helptag = "xxx",                                  section = "XXX",                         path = "./lua/nvim_tree/_meta/api/classes02.lua",              append_only = true, },
+
   { helptag = "nvim-tree-api-commands",               section = "API: commands",               path = "./lua/nvim_tree/_meta/api/commands.lua", },
   { helptag = "nvim-tree-api-events",                 section = "API: events",                 path = "./lua/nvim_tree/_meta/api/events.lua", },
   { helptag = "nvim-tree-api-filter",                 section = "API: filter",                 path = "./lua/nvim_tree/_meta/api/filter.lua", },
@@ -51,8 +56,6 @@ local srcs = {
   { helptag = "nvim-tree-api-node-navigate",          section = "API: node.navigate",          path = "./lua/nvim_tree/_meta/api/node/navigate.lua", },
   { helptag = "nvim-tree-api-node-open",              section = "API: node.open",              path = "./lua/nvim_tree/_meta/api/node/open.lua", },
   { helptag = "nvim-tree-api-tree",                   section = "API: tree",                   path = "./lua/nvim_tree/_meta/api/tree.lua", },
-
-  { helptag = "nvim-tree-api-classes",                section = "API: Classes",                path = "./lua/nvim_tree/_meta/api/classes.lua", },
 }
 
 -- hydrate file names
@@ -80,6 +83,8 @@ local config = {
     -- path
     files = vim.tbl_map(function(src) return src.path end, srcs),
 
+    append_only = vim.tbl_map(function(src) return src.append_only and src.file_name or nil end, srcs),
+
     section_fmt = function(name)
       print(string.format("section_fmt name=%s", name))
       return srcs_by_name[name] and srcs_by_name[name].section or

From 9e6ce3abe5ae85a5a388da162ddde57ce7452d5a Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sun, 25 Jan 2026 15:47:44 +1100
Subject: [PATCH 140/170] docs(#3088): document node and git classes, namespace
 internal and external git classes, redact node subclasses

---
 doc/nvim-tree-lua.txt                    |  90 ++++++------------
 lua/nvim-tree/_meta/api.lua              | 112 +++++++++++++++++++++++
 lua/nvim-tree/_meta/api/classes01.lua    |  21 -----
 lua/nvim-tree/_meta/api/classes02.lua    |  43 ---------
 lua/nvim-tree/api.lua                    |  35 -------
 lua/nvim-tree/explorer/filters.lua       |   4 +-
 lua/nvim-tree/explorer/init.lua          |  10 +-
 lua/nvim-tree/git/init.lua               |  44 ++++-----
 lua/nvim-tree/git/runner.lua             |  10 +-
 lua/nvim-tree/git/utils.lua              |  18 ++--
 lua/nvim-tree/node/directory-link.lua    |   2 +-
 lua/nvim-tree/node/directory.lua         |   4 +-
 lua/nvim-tree/node/file-link.lua         |   2 +-
 lua/nvim-tree/node/file.lua              |   4 +-
 lua/nvim-tree/node/init.lua              |   6 +-
 lua/nvim-tree/renderer/decorator/git.lua |   6 +-
 scripts/gen_vimdoc_config.lua            |   6 +-
 17 files changed, 194 insertions(+), 223 deletions(-)
 create mode 100644 lua/nvim-tree/_meta/api.lua
 delete mode 100644 lua/nvim-tree/_meta/api/classes01.lua
 delete mode 100644 lua/nvim-tree/_meta/api/classes02.lua

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 1a62995a01f..f1b78130d55 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -2389,72 +2389,42 @@ e.g. the following are functionally identical: >lua
 <
 
 
-
-
-
-Base Node class:
-
-
 *nvim_tree.api.Node*
-    Base Node, Abstract
-
-    Fields: ~
-      • {type}            (`"file"|"directory"|"link"`) uv.fs_stat.result.type
-      • {absolute_path}   (`string`)
-      • {executable}      (`boolean`)
-      • {fs_stat}?        (`uv.fs_stat.result`)
-      • {git_status}?     (`GitNodeStatus`)
-      • {hidden}          (`boolean`)
-      • {name}            (`string`)
-      • {parent}?         (`nvim_tree.api.DirectoryNode`)
-      • {diag_severity}?  (`lsp.DiagnosticSeverity`)
-
-
-
-
-
-Node subclasses:
-
+    The Node class is a data class. Instances may be provided by API functions
+    for use as a:
+    • handle to pass back to API functions e.g. |nvim_tree.api.node.run.cmd()|
+    • reference in callbacks e.g. |nvim_tree.config.sort.Sorter| {sorter}
 
-*nvim_tree.api.DirectoryLinkNode*
-    Extends: |nvim_tree.api.DirectoryNode|
-
-    DirectoryLink
-
-*nvim_tree.api.DirectoryNode*
-    Extends: |nvim_tree.api.Node|
-
-    Directory
-
-    Fields: ~
-      • {has_children}  (`boolean`)
-      • {nodes}         (`nvim_tree.api.Node[]`)
-      • {open}          (`boolean`)
-
-*nvim_tree.api.FileLinkNode*
-    Extends: |nvim_tree.api.FileNode|
-
-    File Link
-
-*nvim_tree.api.FileNode*
-    Extends: |nvim_tree.api.Node|
-
-    File
+    Please do not mutate the contents of any Node object.
 
     Fields: ~
-      • {extension}  (`string`)
-
-*nvim_tree.api.LinkNode*
-    Link mixin
+      • {type}            (`"file"|"directory"|"link"`) see |uv.fs_stat()|
+                          {type}
+      • {absolute_path}   (`string`) of the file or directory
+      • {executable}      (`boolean`) file is executable
+      • {fs_stat}?        (`uv.fs_stat.result`) at time of last tree display,
+                          see |uv.fs_stat()|
+      • {git_status}      (`nvim_tree.git.Status?`) for files and directories
+      • {hidden}          (`boolean`) node is not visible in the tree
+      • {name}            (`string`) file or directory name
+      • {parent}?         (`nvim_tree.api.DirectoryNode`) parent directory,
+                          nil for root
+      • {diag_severity}?  (`lsp.DiagnosticSeverity`) diagnostic status
+
+*nvim_tree.git.Status*
+    Git statuses for a single node.
+
+    `nvim_tree.git.XY`: 2 character string, see `man 1 git-status` "Short
+    Format"
+
+    {dir} status is derived from its contents:
+    • `direct`: inherited from child files
+    • `indirect`: inherited from child directories
 
     Fields: ~
-      • {link_to}         (`string`)
-      • {fs_stat_target}  (`uv.fs_stat.result`)
-
-*nvim_tree.api.RootNode*
-    Extends: |nvim_tree.api.DirectoryNode|
-
-    Root Directory
+      • {file}?  (`nvim_tree.git.XY`) status of a file node
+      • {dir}?   (`table<"direct"|"indirect", nvim_tree.git.XY[]>`) direct
+                 inclusive-or indirect status
 
 
 
diff --git a/lua/nvim-tree/_meta/api.lua b/lua/nvim-tree/_meta/api.lua
new file mode 100644
index 00000000000..5f7e4f55c0a
--- /dev/null
+++ b/lua/nvim-tree/_meta/api.lua
@@ -0,0 +1,112 @@
+---@meta
+error("Cannot require a meta file")
+
+---@brief
+---nvim-tree exposes a public API. This is non breaking, with additions made as necessary.
+---
+---Please do not require or use modules other than `nvim-tree.api`, as internal modules will change without notice.
+---
+---The API is separated into multiple modules:
+---
+---- [nvim-tree-api-commands]
+---- [nvim-tree-api-events]
+---- [nvim-tree-api-filter]
+---- [nvim-tree-api-fs]
+---- [nvim-tree-api-health]
+---- [nvim-tree-api-map]
+---- [nvim-tree-api-marks]
+---- [nvim-tree-api-node]
+---- [nvim-tree-api-tree]
+---
+---Modules are accessed via `api..`
+---
+---Example invocation of the `reload` function in the `tree` module:
+---```lua
+---
+---local api = require("nvim-tree.api")
+---api.tree.reload()
+---```
+---Generally, functions accepting a [nvim_tree.api.Node] as their first argument will use the node under the cursor when that argument is not present or nil. e.g. the following are functionally identical:
+---```lua
+---
+---api.node.open.edit(nil, { focus = true })
+---
+---api.node.open.edit(api.tree.get_node_under_cursor(), { focus = true })
+---```
+
+
+---The Node class is a data class. Instances may be provided by API functions for use as a:
+---- handle to pass back to API functions e.g. [nvim_tree.api.node.run.cmd()]
+---- reference in callbacks e.g. [nvim_tree.config.sort.Sorter] {sorter}
+---
+---Please do not mutate the contents of any Node object.
+---
+---@class nvim_tree.api.Node
+---@field absolute_path string of the file or directory
+---@field name string file or directory name
+---@field parent? nvim_tree.api.DirectoryNode parent directory, nil for root
+---@field type "file" | "directory" | "link" [uv.fs_stat()] {type}
+---@field executable boolean file is executable
+---@field fs_stat? uv.fs_stat.result at time of last tree display, see [uv.fs_stat()]
+---@field git_status nvim_tree.git.Status? for files and directories
+---@field diag_severity? lsp.DiagnosticSeverity diagnostic status
+---@field hidden boolean node is not visible in the tree
+
+
+---
+---Git statuses for a single node.
+---
+---`nvim_tree.git.XY`: 2 character string, see `man 1 git-status` "Short Format"
+---@alias nvim_tree.git.XY string
+---
+---{dir} status is derived from its contents:
+---- `direct`: inherited from child files
+---- `indirect`: inherited from child directories
+---
+---@class nvim_tree.git.Status
+---@field file? nvim_tree.git.XY status of a file node
+---@field dir? table<"direct" | "indirect", nvim_tree.git.XY[]> direct inclusive-or indirect status
+
+
+
+
+-- Following are exact as that prevents them from having documentation generated.
+-- They are not ready for public exposure as:
+-- - They are not classic classes
+-- - They are only used in a few locations: api.tree.get_nodes and UserDecorator
+
+---
+---File
+---
+---@class (exact) nvim_tree.api.FileNode: nvim_tree.api.Node
+---@field extension string
+
+---
+---Directory
+---
+---@class (exact) nvim_tree.api.DirectoryNode: nvim_tree.api.Node
+---@field has_children boolean
+---@field nodes nvim_tree.api.Node[]
+---@field open boolean
+
+---
+---Root Directory
+---
+---@class (exact) nvim_tree.api.RootNode: nvim_tree.api.DirectoryNode
+
+---
+---Link mixin
+---
+---@class (exact) nvim_tree.api.LinkNode
+---@field link_to string
+---@field fs_stat_target uv.fs_stat.result
+
+---
+---File Link
+---
+---@class (exact) nvim_tree.api.FileLinkNode: nvim_tree.api.FileNode, nvim_tree.api.LinkNode
+
+---
+---DirectoryLink
+---
+---@class (exact) nvim_tree.api.DirectoryLinkNode: nvim_tree.api.DirectoryNode, nvim_tree.api.LinkNode
diff --git a/lua/nvim-tree/_meta/api/classes01.lua b/lua/nvim-tree/_meta/api/classes01.lua
deleted file mode 100644
index c3509bddc6a..00000000000
--- a/lua/nvim-tree/_meta/api/classes01.lua
+++ /dev/null
@@ -1,21 +0,0 @@
----@meta
-
--- TODO #3088 document these
-
----@brief
----Base Node class:
----
-
----
----Base Node, Abstract
----
----@class nvim_tree.api.Node
----@field type "file" | "directory" | "link" uv.fs_stat.result.type
----@field absolute_path string
----@field executable boolean
----@field fs_stat? uv.fs_stat.result
----@field git_status? GitNodeStatus
----@field hidden boolean
----@field name string
----@field parent? nvim_tree.api.DirectoryNode
----@field diag_severity? lsp.DiagnosticSeverity
diff --git a/lua/nvim-tree/_meta/api/classes02.lua b/lua/nvim-tree/_meta/api/classes02.lua
deleted file mode 100644
index 82a412861e8..00000000000
--- a/lua/nvim-tree/_meta/api/classes02.lua
+++ /dev/null
@@ -1,43 +0,0 @@
----@meta
-
--- TODO #3088 document these
-
----@brief
----Node subclasses:
----
-
----
----File
----
----@class nvim_tree.api.FileNode: nvim_tree.api.Node
----@field extension string
-
----
----Directory
----
----@class nvim_tree.api.DirectoryNode: nvim_tree.api.Node
----@field has_children boolean
----@field nodes nvim_tree.api.Node[]
----@field open boolean
-
----
----Root Directory
----
----@class nvim_tree.api.RootNode: nvim_tree.api.DirectoryNode
-
----
----Link mixin
----
----@class nvim_tree.api.LinkNode
----@field link_to string
----@field fs_stat_target uv.fs_stat.result
-
----
----File Link
----
----@class nvim_tree.api.FileLinkNode: nvim_tree.api.FileNode, nvim_tree.api.LinkNode
-
----
----DirectoryLink
----
----@class nvim_tree.api.DirectoryLinkNode: nvim_tree.api.DirectoryNode, nvim_tree.api.LinkNode
diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index a915fe1b054..5542583b21c 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -1,39 +1,5 @@
 local api = {}
 
----@brief
----nvim-tree exposes a public API. This is non breaking, with additions made as necessary.
----
----Please do not require or use modules other than `nvim-tree.api`, as internal modules will change without notice.
----
----The API is separated into multiple modules:
----
----- [nvim-tree-api-commands]
----- [nvim-tree-api-events]
----- [nvim-tree-api-filter]
----- [nvim-tree-api-fs]
----- [nvim-tree-api-health]
----- [nvim-tree-api-map]
----- [nvim-tree-api-marks]
----- [nvim-tree-api-node]
----- [nvim-tree-api-tree]
----
----Modules are accessed via `api..`
----
----Example invocation of the `reload` function in the `tree` module:
----```lua
----
----local api = require("nvim-tree.api")
----api.tree.reload()
----```
----Generally, functions accepting a [nvim_tree.api.Node] as their first argument will use the node under the cursor when that argument is not present or nil. e.g. the following are functionally identical:
----```lua
----
----api.node.open.edit(nil, { focus = true })
----
----api.node.open.edit(api.tree.get_node_under_cursor(), { focus = true })
----```
-
-
 --
 -- Load the (empty) meta definitions
 --
@@ -47,7 +13,6 @@ api.marks = require("nvim-tree._meta.api.marks")
 api.node = require("nvim-tree._meta.api.node")
 api.tree = require("nvim-tree._meta.api.tree")
 
-
 --
 -- Map implementations
 --
diff --git a/lua/nvim-tree/explorer/filters.lua b/lua/nvim-tree/explorer/filters.lua
index 7ec5a6abf8e..bd9f7ee1e09 100644
--- a/lua/nvim-tree/explorer/filters.lua
+++ b/lua/nvim-tree/explorer/filters.lua
@@ -65,7 +65,7 @@ end
 ---Check if the given path is git clean/ignored
 ---@private
 ---@param path string Absolute path
----@param project GitProject from prepare
+---@param project nvim_tree.git.Project from prepare
 ---@return boolean
 function Filters:git(path, project)
   if type(project) ~= "table" or type(project.files) ~= "table" or type(project.dirs) ~= "table" then
@@ -193,7 +193,7 @@ function Filters:custom(path)
 end
 
 ---Prepare arguments for should_filter. This is done prior to should_filter for efficiency reasons.
----@param project GitProject? optional results of git.load_projects(...)
+---@param project nvim_tree.git.Project? optional results of git.load_projects(...)
 ---@return table
 --- project: reference
 --- bufinfo: empty unless no_buffer set: vim.fn.getbufinfo { buflisted = 1 }
diff --git a/lua/nvim-tree/explorer/init.lua b/lua/nvim-tree/explorer/init.lua
index cee3b4f0ca4..7b8a7911d45 100644
--- a/lua/nvim-tree/explorer/init.lua
+++ b/lua/nvim-tree/explorer/init.lua
@@ -200,7 +200,7 @@ function Explorer:expand_dir_node(node)
 end
 
 ---@param node DirectoryNode
----@param project GitProject?
+---@param project nvim_tree.git.Project?
 ---@return Node[]?
 function Explorer:reload(node, project)
   local cwd = node.link_to or node.absolute_path
@@ -358,7 +358,7 @@ end
 ---@private
 ---@param nodes_by_path Node[]
 ---@param node_ignored boolean
----@param project GitProject?
+---@param project nvim_tree.git.Project?
 ---@return fun(node: Node): Node
 function Explorer:update_git_statuses(nodes_by_path, node_ignored, project)
   return function(node)
@@ -373,7 +373,7 @@ end
 ---@param handle uv.uv_fs_t
 ---@param cwd string
 ---@param node DirectoryNode
----@param project GitProject
+---@param project nvim_tree.git.Project
 ---@param parent Explorer
 function Explorer:populate_children(handle, cwd, node, project, parent)
   local node_ignored = node:is_git_ignored()
@@ -432,7 +432,7 @@ end
 
 ---@private
 ---@param node DirectoryNode
----@param project GitProject
+---@param project nvim_tree.git.Project
 ---@param parent Explorer
 ---@return Node[]|nil
 function Explorer:explore(node, project, parent)
@@ -467,7 +467,7 @@ function Explorer:explore(node, project, parent)
 end
 
 ---@private
----@param projects GitProject[]
+---@param projects nvim_tree.git.Project[]
 function Explorer:refresh_nodes(projects)
   Iterator.builder({ self })
     :applier(function(n)
diff --git a/lua/nvim-tree/git/init.lua b/lua/nvim-tree/git/init.lua
index 6277a6a4f78..2ad0243ed06 100644
--- a/lua/nvim-tree/git/init.lua
+++ b/lua/nvim-tree/git/init.lua
@@ -7,34 +7,26 @@ local Watcher = require("nvim-tree.watcher").Watcher
 local Iterator = require("nvim-tree.iterators.node-iterator")
 local DirectoryNode = require("nvim-tree.node.directory")
 
----Git short format status xy
----@alias GitXY string
-
 -- Git short-format status
----@alias GitPathXY table
+---@alias nvim_tree.git.PathXY table
 
 -- Git short-format statuses
----@alias GitPathXYs table
-
----Git short-format statuses for a single node
----@class (exact) GitNodeStatus
----@field file GitXY?
----@field dir table<"direct" | "indirect", GitXY[]>?
+---@alias nvim_tree.git.PathXYs table
 
 ---Git state for an entire repo
----@class (exact) GitProject
----@field files GitProjectFiles?
----@field dirs GitProjectDirs?
+---@class (exact) nvim_tree.git.Project
+---@field files nvim_tree.git.ProjectFiles?
+---@field dirs nvim_tree.git.ProjectDirs?
 ---@field watcher Watcher?
 
----@alias GitProjectFiles GitPathXY
----@alias GitProjectDirs table<"direct" | "indirect", GitPathXYs>
+---@alias nvim_tree.git.ProjectFiles nvim_tree.git.PathXY
+---@alias nvim_tree.git.ProjectDirs table<"direct" | "indirect", nvim_tree.git.PathXYs>
 
 local M = {
   config = {},
 
   ---all projects keyed by toplevel
-  ---@type table
+  ---@type table
   _projects_by_toplevel = {},
 
   ---index of paths inside toplevels, false when not inside a project
@@ -58,8 +50,8 @@ local WATCHED_FILES = {
 
 ---@param toplevel string|nil
 ---@param path string|nil
----@param project GitProject
----@param project_files GitProjectFiles?
+---@param project nvim_tree.git.Project
+---@param project_files nvim_tree.git.ProjectFiles?
 local function reload_git_project(toplevel, path, project, project_files)
   if path then
     for p in pairs(project.files) do
@@ -77,7 +69,7 @@ end
 
 --- Is this path in a known ignored directory?
 ---@param path string
----@param project GitProject
+---@param project nvim_tree.git.Project
 ---@return boolean
 local function path_ignored_in_project(path, project)
   if not path or not project then
@@ -94,7 +86,7 @@ local function path_ignored_in_project(path, project)
   return false
 end
 
----@return GitProject[] maybe empty
+---@return nvim_tree.git.Project[] maybe empty
 function M.reload_all_projects()
   if not M.config.git.enable then
     return {}
@@ -112,7 +104,7 @@ end
 ---@param path string? optional path to update only
 ---@param callback function?
 function M.reload_project(toplevel, path, callback)
-  local project = M._projects_by_toplevel[toplevel] --[[@as GitProject]]
+  local project = M._projects_by_toplevel[toplevel] --[[@as nvim_tree.git.Project]]
 
   if not toplevel or not project or not M.config.git.enable then
     if callback then
@@ -138,7 +130,7 @@ function M.reload_project(toplevel, path, callback)
   }
 
   if callback then
-    ---@param path_xy GitPathXY
+    ---@param path_xy nvim_tree.git.PathXY
     args.callback = function(path_xy)
       reload_git_project(toplevel, path, project, path_xy)
       callback()
@@ -152,7 +144,7 @@ end
 
 --- Retrieve a known project
 ---@param toplevel string?
----@return GitProject? project
+---@return nvim_tree.git.Project? project
 function M.get_project(toplevel)
   return M._projects_by_toplevel[toplevel]
 end
@@ -265,7 +257,7 @@ end
 --- Load the project status for a path. Does nothing when no toplevel for path.
 --- Only fetches project status when unknown, otherwise returns existing.
 ---@param path string absolute
----@return GitProject maybe empty
+---@return nvim_tree.git.Project maybe empty
 function M.load_project(path)
   if not M.config.git.enable then
     return {}
@@ -329,7 +321,7 @@ function M.load_project(path)
 end
 
 ---@param dir DirectoryNode
----@param project GitProject?
+---@param project nvim_tree.git.Project?
 ---@param root string?
 function M.update_parent_projects(dir, project, root)
   while project and dir do
@@ -378,7 +370,7 @@ function M.refresh_dir(dir)
 end
 
 ---@param dir DirectoryNode?
----@param projects GitProject[]
+---@param projects nvim_tree.git.Project[]
 function M.reload_node_status(dir, projects)
   dir = dir and dir:as(DirectoryNode)
   if not dir or #dir.nodes == 0 then
diff --git a/lua/nvim-tree/git/runner.lua b/lua/nvim-tree/git/runner.lua
index 0c540575198..938d10fa0e0 100644
--- a/lua/nvim-tree/git/runner.lua
+++ b/lua/nvim-tree/git/runner.lua
@@ -10,8 +10,8 @@ local Class = require("nvim-tree.classic")
 ---@field private list_untracked boolean
 ---@field private list_ignored boolean
 ---@field private timeout integer
----@field private callback fun(path_xy: GitPathXY)?
----@field private path_xy GitPathXY
+---@field private callback fun(path_xy: nvim_tree.git.PathXY)?
+---@field private path_xy nvim_tree.git.PathXY
 ---@field private rc integer? -- -1 indicates timeout
 local GitRunner = Class:extend()
 
@@ -24,7 +24,7 @@ local GitRunner = Class:extend()
 ---@field list_untracked boolean
 ---@field list_ignored boolean
 ---@field timeout integer
----@field callback fun(path_xy: GitPathXY)?
+---@field callback fun(path_xy: nvim_tree.git.PathXY)?
 
 local timeouts = 0
 local MAX_TIMEOUTS = 5
@@ -229,7 +229,7 @@ end
 
 ---Return nil when callback present
 ---@private
----@return GitPathXY?
+---@return nvim_tree.git.PathXY?
 function GitRunner:execute()
   local async = self.callback ~= nil
   local profile = log.profile_start("git %s job %s %s", async and "async" or "sync", self.toplevel, self.path)
@@ -263,7 +263,7 @@ end
 ---Static method to run a git process, which will be killed if it takes more than timeout
 ---Return nil when callback present
 ---@param args GitRunnerArgs
----@return GitPathXY?
+---@return nvim_tree.git.PathXY?
 function GitRunner:run(args)
   local runner = GitRunner(args)
 
diff --git a/lua/nvim-tree/git/utils.lua b/lua/nvim-tree/git/utils.lua
index 1e3444c70f4..ca2bf0f6132 100644
--- a/lua/nvim-tree/git/utils.lua
+++ b/lua/nvim-tree/git/utils.lua
@@ -104,11 +104,11 @@ local function nil_insert(t, k)
   return t
 end
 
----@param project_files GitProjectFiles
+---@param project_files nvim_tree.git.ProjectFiles
 ---@param cwd string|nil
----@return GitProjectDirs
+---@return nvim_tree.git.ProjectDirs
 function M.project_files_to_project_dirs(project_files, cwd)
-  ---@type GitProjectDirs
+  ---@type nvim_tree.git.ProjectDirs
   local project_dirs = {}
 
   project_dirs.direct = {}
@@ -145,12 +145,12 @@ end
 
 ---Git file status for an absolute path
 ---@param parent_ignored boolean
----@param project GitProject?
+---@param project nvim_tree.git.Project?
 ---@param path string
 ---@param path_fallback string? alternative file path when no other file status
----@return GitNodeStatus
+---@return nvim_tree.git.Status
 function M.git_status_file(parent_ignored, project, path, path_fallback)
-  ---@type GitNodeStatus
+  ---@type nvim_tree.git.Status
   local ns
 
   if parent_ignored then
@@ -170,12 +170,12 @@ end
 
 ---Git file and directory status for an absolute path
 ---@param parent_ignored boolean
----@param project GitProject?
+---@param project nvim_tree.git.Project?
 ---@param path string
 ---@param path_fallback string? alternative file path when no other file status
----@return GitNodeStatus?
+---@return nvim_tree.git.Status?
 function M.git_status_dir(parent_ignored, project, path, path_fallback)
-  ---@type GitNodeStatus?
+  ---@type nvim_tree.git.Status?
   local ns
 
   if parent_ignored then
diff --git a/lua/nvim-tree/node/directory-link.lua b/lua/nvim-tree/node/directory-link.lua
index 8b365047819..6d503ad6d40 100644
--- a/lua/nvim-tree/node/directory-link.lua
+++ b/lua/nvim-tree/node/directory-link.lua
@@ -33,7 +33,7 @@ end
 
 ---Update the directory git_status of link target and the file status of the link itself
 ---@param parent_ignored boolean
----@param project GitProject?
+---@param project nvim_tree.git.Project?
 function DirectoryLinkNode:update_git_status(parent_ignored, project)
   self.git_status = git_utils.git_status_dir(parent_ignored, project, self.link_to, self.absolute_path)
 end
diff --git a/lua/nvim-tree/node/directory.lua b/lua/nvim-tree/node/directory.lua
index da1599cbdc5..ac66d1a8072 100644
--- a/lua/nvim-tree/node/directory.lua
+++ b/lua/nvim-tree/node/directory.lua
@@ -52,12 +52,12 @@ end
 
 ---Update the git_status of the directory
 ---@param parent_ignored boolean
----@param project GitProject?
+---@param project nvim_tree.git.Project?
 function DirectoryNode:update_git_status(parent_ignored, project)
   self.git_status = git_utils.git_status_dir(parent_ignored, project, self.absolute_path, nil)
 end
 
----@return GitXY[]?
+---@return nvim_tree.git.XY[]?
 function DirectoryNode:get_git_xy()
   if not self.git_status or not self.explorer.opts.git.show_on_dirs then
     return nil
diff --git a/lua/nvim-tree/node/file-link.lua b/lua/nvim-tree/node/file-link.lua
index b13c88f0d6b..6cb83e0343a 100644
--- a/lua/nvim-tree/node/file-link.lua
+++ b/lua/nvim-tree/node/file-link.lua
@@ -26,7 +26,7 @@ end
 
 ---Update the git_status of the target otherwise the link itself
 ---@param parent_ignored boolean
----@param project GitProject?
+---@param project nvim_tree.git.Project?
 function FileLinkNode:update_git_status(parent_ignored, project)
   self.git_status = git_utils.git_status_file(parent_ignored, project, self.link_to, self.absolute_path)
 end
diff --git a/lua/nvim-tree/node/file.lua b/lua/nvim-tree/node/file.lua
index 6e160409c29..bba1621e21b 100644
--- a/lua/nvim-tree/node/file.lua
+++ b/lua/nvim-tree/node/file.lua
@@ -36,12 +36,12 @@ end
 
 ---Update the GitStatus of the file
 ---@param parent_ignored boolean
----@param project GitProject?
+---@param project nvim_tree.git.Project?
 function FileNode:update_git_status(parent_ignored, project)
   self.git_status = git_utils.git_status_file(parent_ignored, project, self.absolute_path, nil)
 end
 
----@return GitXY[]?
+---@return nvim_tree.git.XY[]?
 function FileNode:get_git_xy()
   if not self.git_status then
     return nil
diff --git a/lua/nvim-tree/node/init.lua b/lua/nvim-tree/node/init.lua
index da0dcc5b0eb..4e51fd0b07b 100644
--- a/lua/nvim-tree/node/init.lua
+++ b/lua/nvim-tree/node/init.lua
@@ -8,7 +8,7 @@ local Class = require("nvim-tree.classic")
 ---@field absolute_path string
 ---@field executable boolean
 ---@field fs_stat uv.fs_stat.result?
----@field git_status GitNodeStatus?
+---@field git_status nvim_tree.git.Status?
 ---@field hidden boolean
 ---@field name string
 ---@field parent DirectoryNode?
@@ -45,13 +45,13 @@ end
 ---Update the git_status of the node
 ---Abstract
 ---@param parent_ignored boolean
----@param project GitProject?
+---@param project nvim_tree.git.Project?
 function Node:update_git_status(parent_ignored, project)
   self:nop(parent_ignored, project)
 end
 
 ---Short-format statuses
----@return GitXY[]?
+---@return nvim_tree.git.XY[]?
 function Node:get_git_xy()
 end
 
diff --git a/lua/nvim-tree/renderer/decorator/git.lua b/lua/nvim-tree/renderer/decorator/git.lua
index 41a5d2fdf25..c117b16959d 100644
--- a/lua/nvim-tree/renderer/decorator/git.lua
+++ b/lua/nvim-tree/renderer/decorator/git.lua
@@ -9,13 +9,13 @@ local DirectoryNode = require("nvim-tree.node.directory")
 ---@alias GitStatusStrings "deleted" | "ignored" | "renamed" | "staged" | "unmerged" | "unstaged" | "untracked"
 
 ---@alias GitIconsByStatus table human status
----@alias GitIconsByXY table porcelain status
+---@alias GitIconsByXY table porcelain status
 ---@alias GitGlyphsByStatus table from opts
 
 ---@class (exact) GitDecorator: Decorator
 ---@field private explorer Explorer
----@field private file_hl_by_xy table?
----@field private folder_hl_by_xy table?
+---@field private file_hl_by_xy table?
+---@field private folder_hl_by_xy table?
 ---@field private icons_by_status GitIconsByStatus?
 ---@field private icons_by_xy GitIconsByXY?
 local GitDecorator = Decorator:extend()
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index d38148db1aa..2c208cb7127 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -38,11 +38,7 @@ local srcs = {
 
   { helptag = "nvim-tree-config-default",             section = "Config: Default",             path = "./lua/nvim_tree/_meta/config/default.lua", },
 
-  { helptag = "nvim-tree-api",                        section = "API",                         path = "./lua/nvim_tree/api.lua", },
-
-  -- logically ordered classes with no section
-  { helptag = "xxx",                                  section = "XXX",                         path = "./lua/nvim_tree/_meta/api/classes01.lua",              append_only = true, },
-  { helptag = "xxx",                                  section = "XXX",                         path = "./lua/nvim_tree/_meta/api/classes02.lua",              append_only = true, },
+  { helptag = "nvim-tree-api",                        section = "API",                         path = "./lua/nvim_tree/_meta/api.lua", },
 
   { helptag = "nvim-tree-api-commands",               section = "API: commands",               path = "./lua/nvim_tree/_meta/api/commands.lua", },
   { helptag = "nvim-tree-api-events",                 section = "API: events",                 path = "./lua/nvim_tree/_meta/api/events.lua", },

From f71ff50edf0773a3539da996210ed0dc941566aa Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sun, 25 Jan 2026 16:20:26 +1100
Subject: [PATCH 141/170] docs(#3088): fix merge issue

---
 doc/nvim-tree-lua.txt           | 11 +++++------
 lua/nvim-tree/api/impl/post.lua |  2 +-
 2 files changed, 6 insertions(+), 7 deletions(-)

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index f1b78130d55..f499a32ca7b 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -2398,18 +2398,17 @@ e.g. the following are functionally identical: >lua
     Please do not mutate the contents of any Node object.
 
     Fields: ~
-      • {type}            (`"file"|"directory"|"link"`) see |uv.fs_stat()|
-                          {type}
       • {absolute_path}   (`string`) of the file or directory
+      • {name}            (`string`) file or directory name
+      • {parent}?         (`nvim_tree.api.DirectoryNode`) parent directory,
+                          nil for root
+      • {type}            (`"file"|"directory"|"link"`) |uv.fs_stat()| {type}
       • {executable}      (`boolean`) file is executable
       • {fs_stat}?        (`uv.fs_stat.result`) at time of last tree display,
                           see |uv.fs_stat()|
       • {git_status}      (`nvim_tree.git.Status?`) for files and directories
-      • {hidden}          (`boolean`) node is not visible in the tree
-      • {name}            (`string`) file or directory name
-      • {parent}?         (`nvim_tree.api.DirectoryNode`) parent directory,
-                          nil for root
       • {diag_severity}?  (`lsp.DiagnosticSeverity`) diagnostic status
+      • {hidden}          (`boolean`) node is not visible in the tree
 
 *nvim_tree.git.Status*
     Git statuses for a single node.
diff --git a/lua/nvim-tree/api/impl/post.lua b/lua/nvim-tree/api/impl/post.lua
index 59bb54bbd5a..9bd690018d2 100644
--- a/lua/nvim-tree/api/impl/post.lua
+++ b/lua/nvim-tree/api/impl/post.lua
@@ -113,7 +113,7 @@ local function open_or_expand_or_dir_up(mode, toggle_group)
     local dir = node:as(DirectoryNode)
 
     if root or node.name == ".." then
-      actions.root.change_dir.fn("..")
+      wrap_explorer("change_dir")("..")
     elseif dir then
       dir:expand_or_collapse(toggle_group)
     elseif not toggle_group then

From 11f96e1ccd4f68d4793b6dae7f80d400c11c5668 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sun, 25 Jan 2026 16:48:18 +1100
Subject: [PATCH 142/170] docs(#3088): tidy pre comments

---
 lua/nvim-tree/api/impl/pre.lua | 22 ++++++++++++++++------
 1 file changed, 16 insertions(+), 6 deletions(-)

diff --git a/lua/nvim-tree/api/impl/pre.lua b/lua/nvim-tree/api/impl/pre.lua
index 44a815b7bc8..f185781dd5a 100644
--- a/lua/nvim-tree/api/impl/pre.lua
+++ b/lua/nvim-tree/api/impl/pre.lua
@@ -6,7 +6,7 @@ local events = require("nvim-tree.events")     -- needed for event registration
 local keymap = require("nvim-tree.keymap")     -- needed for default on attach
 local notify = require("nvim-tree.notify")     -- already required by events and others
 
-local UserDecorator = require("nvim-tree.renderer.decorator.user") -- TODO #3241
+local UserDecorator = require("nvim-tree.renderer.decorator.user")
 
 ---Walk the api, hydrating all functions with the error notification
 ---@param t table api root or sub-module
@@ -25,22 +25,32 @@ end
 ---Hydrate implementations that may be called pre setup
 ---@param api table
 local function hydrate_pre(api)
+  --
+  -- Essential
+  --
+  api.events.Event = events.Event
+  api.events.subscribe = events.subscribe
+
+  api.map.default_on_attach = keymap.default_on_attach
+
+
   --
   -- May be lazily requried on execution
   --
   api.health.hi_test = function() require("nvim-tree.appearance.hi-test")() end
 
+
   --
-  -- Essential or already required elsewhere
+  -- Already required elsewhere
   --
   api.commands.get = commands.get
 
-  api.events.Event = events.Event
-  api.events.subscribe = events.subscribe
-
-  api.map.default_on_attach = keymap.default_on_attach
   api.map.get_keymap_default = keymap.get_keymap_default
 
+
+  --
+  -- TODO #3241
+  --
   api.decorator = {}
   ---Create a decorator class by calling :extend()
   ---See :help nvim-tree-decorators

From 63e367980c478b029b7e6244ebab9df21961b00c Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sun, 25 Jan 2026 17:14:21 +1100
Subject: [PATCH 143/170] docs(#3088): collapse node and fs submodules

---
 doc/nvim-tree-lua.txt                     | 177 +++++++++---------
 lua/nvim-tree/_meta/api/fs.lua            |  34 +++-
 lua/nvim-tree/_meta/api/fs/copy.lua       |  34 ----
 lua/nvim-tree/_meta/api/node.lua          | 218 +++++++++++++++++++++-
 lua/nvim-tree/_meta/api/node/navigate.lua | 120 ------------
 lua/nvim-tree/_meta/api/node/open.lua     | 101 ----------
 scripts/gen_vimdoc_config.lua             |   3 -
 7 files changed, 334 insertions(+), 353 deletions(-)
 delete mode 100644 lua/nvim-tree/_meta/api/fs/copy.lua
 delete mode 100644 lua/nvim-tree/_meta/api/node/navigate.lua
 delete mode 100644 lua/nvim-tree/_meta/api/node/open.lua

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index f499a32ca7b..c2c8a59592c 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -2494,6 +2494,36 @@ API: fs                                                     *nvim-tree-api-fs*
 clear_clipboard()                         *nvim_tree.api.fs.clear_clipboard()*
     Clear the nvim-tree clipboard.
 
+copy.absolute_path({node})             *nvim_tree.api.fs.copy.absolute_path()*
+    Copy the absolute path to the system clipboard.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`)
+
+copy.basename({node})                       *nvim_tree.api.fs.copy.basename()*
+    Copy the name with extension omitted to the system clipboard.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`)
+
+copy.filename({node})                       *nvim_tree.api.fs.copy.filename()*
+    Copy the name to the system clipboard.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`)
+
+copy.node({node})                               *nvim_tree.api.fs.copy.node()*
+    Copy to the nvim-tree clipboard.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`)
+
+copy.relative_path({node})             *nvim_tree.api.fs.copy.relative_path()*
+    Copy the path relative to the tree root to the system clipboard.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`)
+
 create({node})                                     *nvim_tree.api.fs.create()*
     Prompt to create a file or directory.
 
@@ -2566,40 +2596,6 @@ trash({node})                                       *nvim_tree.api.fs.trash()*
       • {node}  (`nvim_tree.api.Node?`)
 
 
-==============================================================================
-API: fs.copy                                           *nvim-tree-api-fs-copy*
-
-absolute_path({node})                  *nvim_tree.api.fs.copy.absolute_path()*
-    Copy the absolute path to the system clipboard.
-
-    Parameters: ~
-      • {node}  (`nvim_tree.api.Node?`)
-
-basename({node})                            *nvim_tree.api.fs.copy.basename()*
-    Copy the name with extension omitted to the system clipboard.
-
-    Parameters: ~
-      • {node}  (`nvim_tree.api.Node?`)
-
-filename({node})                            *nvim_tree.api.fs.copy.filename()*
-    Copy the name to the system clipboard.
-
-    Parameters: ~
-      • {node}  (`nvim_tree.api.Node?`)
-
-node({node})                                    *nvim_tree.api.fs.copy.node()*
-    Copy to the nvim-tree clipboard.
-
-    Parameters: ~
-      • {node}  (`nvim_tree.api.Node?`)
-
-relative_path({node})                  *nvim_tree.api.fs.copy.relative_path()*
-    Copy the path relative to the tree root to the system clipboard.
-
-    Parameters: ~
-      • {node}  (`nvim_tree.api.Node?`)
-
-
 ==============================================================================
 API: health                                             *nvim-tree-api-health*
 
@@ -2723,38 +2719,15 @@ expand({node}, {opts})                           *nvim_tree.api.node.expand()*
                   Return `true` if `node` should be expanded.
                   `expansion_count` is the total number of folders expanded.
 
-run.cmd({node})                                 *nvim_tree.api.node.run.cmd()*
-    Enter |cmdline| with the full path of the node and the cursor at the start
-    of the line.
-
-    Parameters: ~
-      • {node}  (`nvim_tree.api.Node?`) directory or file
-
-run.system({node})                           *nvim_tree.api.node.run.system()*
-    Execute |nvim_tree.config.system_open|.
-
-    Parameters: ~
-      • {node}  (`nvim_tree.api.Node?`) directory or file
-
-show_info_popup({node})                 *nvim_tree.api.node.show_info_popup()*
-    Open a popup window showing: fullpath, size, accessed, modified, created.
-
-    Parameters: ~
-      • {node}  (`nvim_tree.api.Node?`) directory or file
-
-
-==============================================================================
-API: node.navigate                               *nvim-tree-api-node-navigate*
-
                               *nvim_tree.api.node.navigate.diagnostics.next()*
-diagnostics.next({node})
+navigate.diagnostics.next({node})
     Navigate to the next item showing diagnostic status.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                     *nvim_tree.api.node.navigate.diagnostics.next_recursive()*
-diagnostics.next_recursive({node})
+navigate.diagnostics.next_recursive({node})
     Navigate to the next item showing diagnostic status, recursively. Needs
     |nvim_tree.config.diagnostics| {show_on_dirs}
 
@@ -2762,28 +2735,28 @@ diagnostics.next_recursive({node})
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                               *nvim_tree.api.node.navigate.diagnostics.prev()*
-diagnostics.prev({node})
+navigate.diagnostics.prev({node})
     Navigate to the previous item showing diagnostic status.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                     *nvim_tree.api.node.navigate.diagnostics.prev_recursive()*
-diagnostics.prev_recursive({node})
+navigate.diagnostics.prev_recursive({node})
     Navigate to the previous item showing diagnostic status, recursively.
     Needs |nvim_tree.config.diagnostics| {show_on_dirs}
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
-git.next({node})                      *nvim_tree.api.node.navigate.git.next()*
+navigate.git.next({node})             *nvim_tree.api.node.navigate.git.next()*
     Navigate to the next item showing git status.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                             *nvim_tree.api.node.navigate.git.next_recursive()*
-git.next_recursive({node})
+navigate.git.next_recursive({node})
     Navigate to the next item showing git status, recursively. Needs
     |nvim_tree.config.git| {show_on_dirs}
 
@@ -2791,20 +2764,20 @@ git.next_recursive({node})
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                       *nvim_tree.api.node.navigate.git.next_skip_gitignored()*
-git.next_skip_gitignored({node})
+navigate.git.next_skip_gitignored({node})
     Navigate to the next item showing git status, skipping `.gitignore`
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
-git.prev({node})                      *nvim_tree.api.node.navigate.git.prev()*
+navigate.git.prev({node})             *nvim_tree.api.node.navigate.git.prev()*
     Navigate to the previous item showing git status.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                             *nvim_tree.api.node.navigate.git.prev_recursive()*
-git.prev_recursive({node})
+navigate.git.prev_recursive({node})
     Navigate to the previous item showing git status, recursively. Needs
     |nvim_tree.config.git| {show_on_dirs}
 
@@ -2812,65 +2785,68 @@ git.prev_recursive({node})
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                       *nvim_tree.api.node.navigate.git.prev_skip_gitignored()*
-git.prev_skip_gitignored({node})
+navigate.git.prev_skip_gitignored({node})
     Navigate to the previous item showing git status, skipping `.gitignore`
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
-opened.next({node})                *nvim_tree.api.node.navigate.opened.next()*
+                                   *nvim_tree.api.node.navigate.opened.next()*
+navigate.opened.next({node})
     Navigate to the next |bufloaded()| file.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
-opened.prev({node})                *nvim_tree.api.node.navigate.opened.prev()*
+                                   *nvim_tree.api.node.navigate.opened.prev()*
+navigate.opened.prev({node})
     Navigate to the previous |bufloaded()| file.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
-parent({node})                          *nvim_tree.api.node.navigate.parent()*
+navigate.parent({node})                 *nvim_tree.api.node.navigate.parent()*
     Navigate to the parent directory of the node.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
-parent_close({node})              *nvim_tree.api.node.navigate.parent_close()*
+                                  *nvim_tree.api.node.navigate.parent_close()*
+navigate.parent_close({node})
     Navigate to the parent directory of the node, closing it.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
-sibling.first({node})            *nvim_tree.api.node.navigate.sibling.first()*
+                                 *nvim_tree.api.node.navigate.sibling.first()*
+navigate.sibling.first({node})
     Navigate to the first node in the current node's folder.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
-sibling.last({node})              *nvim_tree.api.node.navigate.sibling.last()*
+                                  *nvim_tree.api.node.navigate.sibling.last()*
+navigate.sibling.last({node})
     Navigate to the last node in the current node's folder.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
-sibling.next({node})              *nvim_tree.api.node.navigate.sibling.next()*
+                                  *nvim_tree.api.node.navigate.sibling.next()*
+navigate.sibling.next({node})
     Navigate to the next node in the current node's folder, wraps.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
-sibling.prev({node})              *nvim_tree.api.node.navigate.sibling.prev()*
+                                  *nvim_tree.api.node.navigate.sibling.prev()*
+navigate.sibling.prev({node})
     Navigate to the previous node in the current node's folder, wraps.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
-
-==============================================================================
-API: node.open                                       *nvim-tree-api-node-open*
-
-edit({node}, {opts})                          *nvim_tree.api.node.open.edit()*
+open.edit({node}, {opts})                     *nvim_tree.api.node.open.edit()*
     • file: open as per |nvim_tree.config.actions.open_file|
     • directory: expand or collapse
     • root: change directory up
@@ -2883,7 +2859,7 @@ edit({node}, {opts})                          *nvim_tree.api.node.open.edit()*
                 • {focus}? (`boolean`, default: false) Keep focus in the tree
                   when opening the file.
 
-horizontal({node}, {opts})              *nvim_tree.api.node.open.horizontal()*
+open.horizontal({node}, {opts})         *nvim_tree.api.node.open.horizontal()*
     Open file in a new horizontal split.
 
     Parameters: ~
@@ -2895,7 +2871,7 @@ horizontal({node}, {opts})              *nvim_tree.api.node.open.horizontal()*
                   when opening the file.
 
                               *nvim_tree.api.node.open.horizontal_no_picker()*
-horizontal_no_picker({node}, {opts})
+open.horizontal_no_picker({node}, {opts})
     Open file in a new horizontal split without using the window picker.
 
     Parameters: ~
@@ -2907,7 +2883,7 @@ horizontal_no_picker({node}, {opts})
                   when opening the file.
 
                                   *nvim_tree.api.node.open.no_window_picker()*
-no_window_picker({node}, {opts})
+open.no_window_picker({node}, {opts})
     Open file without using the window picker.
 
     Parameters: ~
@@ -2918,7 +2894,7 @@ no_window_picker({node}, {opts})
                 • {focus}? (`boolean`, default: false) Keep focus in the tree
                   when opening the file.
 
-preview({node}, {opts})                    *nvim_tree.api.node.open.preview()*
+open.preview({node}, {opts})               *nvim_tree.api.node.open.preview()*
     Open file with |'bufhidden'| set to `delete`.
 
     Parameters: ~
@@ -2930,7 +2906,7 @@ preview({node}, {opts})                    *nvim_tree.api.node.open.preview()*
                   when opening the file.
 
                                  *nvim_tree.api.node.open.preview_no_picker()*
-preview_no_picker({node}, {opts})
+open.preview_no_picker({node}, {opts})
     Open file with |'bufhidden'| set to `delete` without using the window
     picker.
 
@@ -2943,13 +2919,13 @@ preview_no_picker({node}, {opts})
                   when opening the file.
 
                                *nvim_tree.api.node.open.replace_tree_buffer()*
-replace_tree_buffer({node})
+open.replace_tree_buffer({node})
     Open file in place: in the nvim-tree window.
 
     Parameters: ~
       • {node}  (`nvim_tree.api.Node?`) file
 
-tab({node}, {opts})                            *nvim_tree.api.node.open.tab()*
+open.tab({node}, {opts})                       *nvim_tree.api.node.open.tab()*
     Open file in a new tab.
 
     Parameters: ~
@@ -2960,7 +2936,7 @@ tab({node}, {opts})                            *nvim_tree.api.node.open.tab()*
                 • {focus}? (`boolean`, default: false) Keep focus in the tree
                   when opening the file.
 
-tab_drop({node})                          *nvim_tree.api.node.open.tab_drop()*
+open.tab_drop({node})                     *nvim_tree.api.node.open.tab_drop()*
     Switch to tab containing window with selected file if it exists. Open file
     in new tab otherwise.
 
@@ -2968,7 +2944,7 @@ tab_drop({node})                          *nvim_tree.api.node.open.tab_drop()*
       • {node}  (`nvim_tree.api.Node?`) directory or file
 
                                 *nvim_tree.api.node.open.toggle_group_empty()*
-toggle_group_empty({node}, {opts})
+open.toggle_group_empty({node}, {opts})
     Toggle |nvim_tree.config.renderer| {group_empty} for a directory. Needs
     {group_empty} set.
 
@@ -2980,7 +2956,7 @@ toggle_group_empty({node}, {opts})
                 • {focus}? (`boolean`, default: false) Keep focus in the tree
                   when opening the file.
 
-vertical({node}, {opts})                  *nvim_tree.api.node.open.vertical()*
+open.vertical({node}, {opts})             *nvim_tree.api.node.open.vertical()*
     Open file in a new vertical split.
 
     Parameters: ~
@@ -2992,7 +2968,7 @@ vertical({node}, {opts})                  *nvim_tree.api.node.open.vertical()*
                   when opening the file.
 
                                 *nvim_tree.api.node.open.vertical_no_picker()*
-vertical_no_picker({node}, {opts})
+open.vertical_no_picker({node}, {opts})
     Open file in a new vertical split without using the window picker.
 
     Parameters: ~
@@ -3003,6 +2979,25 @@ vertical_no_picker({node}, {opts})
                 • {focus}? (`boolean`, default: false) Keep focus in the tree
                   when opening the file.
 
+run.cmd({node})                                 *nvim_tree.api.node.run.cmd()*
+    Enter |cmdline| with the full path of the node and the cursor at the start
+    of the line.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
+
+run.system({node})                           *nvim_tree.api.node.run.system()*
+    Execute |nvim_tree.config.system_open|.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
+
+show_info_popup({node})                 *nvim_tree.api.node.show_info_popup()*
+    Open a popup window showing: fullpath, size, accessed, modified, created.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory or file
+
 
 ==============================================================================
 API: tree                                                 *nvim-tree-api-tree*
diff --git a/lua/nvim-tree/_meta/api/fs.lua b/lua/nvim-tree/_meta/api/fs.lua
index b038f43c91d..2ef16644823 100644
--- a/lua/nvim-tree/_meta/api/fs.lua
+++ b/lua/nvim-tree/_meta/api/fs.lua
@@ -1,13 +1,43 @@
 ---@meta
 local nvim_tree = { api = { fs = {} } }
 
-nvim_tree.api.fs.copy = require("nvim-tree._meta.api.fs.copy");
-
 ---
 ---Clear the nvim-tree clipboard.
 ---
 function nvim_tree.api.fs.clear_clipboard() end
 
+nvim_tree.api.fs.copy = {}
+
+---
+---Copy the absolute path to the system clipboard.
+---
+---@param node? nvim_tree.api.Node
+function nvim_tree.api.fs.copy.absolute_path(node) end
+
+---
+---Copy the name with extension omitted to the system clipboard.
+---
+---@param node? nvim_tree.api.Node
+function nvim_tree.api.fs.copy.basename(node) end
+
+---
+---Copy the name to the system clipboard.
+---
+---@param node? nvim_tree.api.Node
+function nvim_tree.api.fs.copy.filename(node) end
+
+---
+---Copy to the nvim-tree clipboard.
+---
+---@param node? nvim_tree.api.Node
+function nvim_tree.api.fs.copy.node(node) end
+
+---
+---Copy the path relative to the tree root to the system clipboard.
+---
+---@param node? nvim_tree.api.Node
+function nvim_tree.api.fs.copy.relative_path(node) end
+
 ---
 ---Prompt to create a file or directory.
 ---
diff --git a/lua/nvim-tree/_meta/api/fs/copy.lua b/lua/nvim-tree/_meta/api/fs/copy.lua
deleted file mode 100644
index 6dd682583af..00000000000
--- a/lua/nvim-tree/_meta/api/fs/copy.lua
+++ /dev/null
@@ -1,34 +0,0 @@
----@meta
-local nvim_tree = { api = { fs = { copy = {} } } }
-
----
----Copy the absolute path to the system clipboard.
----
----@param node? nvim_tree.api.Node
-function nvim_tree.api.fs.copy.absolute_path(node) end
-
----
----Copy the name with extension omitted to the system clipboard.
----
----@param node? nvim_tree.api.Node
-function nvim_tree.api.fs.copy.basename(node) end
-
----
----Copy the name to the system clipboard.
----
----@param node? nvim_tree.api.Node
-function nvim_tree.api.fs.copy.filename(node) end
-
----
----Copy to the nvim-tree clipboard.
----
----@param node? nvim_tree.api.Node
-function nvim_tree.api.fs.copy.node(node) end
-
----
----Copy the path relative to the tree root to the system clipboard.
----
----@param node? nvim_tree.api.Node
-function nvim_tree.api.fs.copy.relative_path(node) end
-
-return nvim_tree.api.fs.copy
diff --git a/lua/nvim-tree/_meta/api/node.lua b/lua/nvim-tree/_meta/api/node.lua
index 686e3112269..e6652bebc1b 100644
--- a/lua/nvim-tree/_meta/api/node.lua
+++ b/lua/nvim-tree/_meta/api/node.lua
@@ -1,8 +1,104 @@
 ---@meta
 local nvim_tree = { api = { node = {} } }
 
-nvim_tree.api.node.navigate = require("nvim-tree._meta.api.node.navigate");
-nvim_tree.api.node.open = require("nvim-tree._meta.api.node.open");
+nvim_tree.api.node.open = {}
+
+---
+---@class nvim_tree.api.node.open.Opts
+---@inlinedoc
+---
+---Quits the tree when opening the file.
+---(default: false)
+---@field quit_on_open? boolean
+---
+---Keep focus in the tree when opening the file.
+---(default: false)
+---@field focus? boolean
+
+
+---
+---- file: open as per [nvim_tree.config.actions.open_file]
+---- directory: expand or collapse
+---- root: change directory up
+---
+---@param node? nvim_tree.api.Node directory or file
+---@param opts? nvim_tree.api.node.open.Opts optional
+function nvim_tree.api.node.open.edit(node, opts) end
+
+---
+---Open file in a new horizontal split.
+---
+---@param node? nvim_tree.api.Node file
+---@param opts? nvim_tree.api.node.open.Opts optional
+function nvim_tree.api.node.open.horizontal(node, opts) end
+
+---
+---Open file in a new horizontal split without using the window picker.
+---
+---@param node? nvim_tree.api.Node file
+---@param opts? nvim_tree.api.node.open.Opts optional
+function nvim_tree.api.node.open.horizontal_no_picker(node, opts) end
+
+---
+---Open file without using the window picker.
+---
+---@param node? nvim_tree.api.Node file
+---@param opts? nvim_tree.api.node.open.Opts optional
+function nvim_tree.api.node.open.no_window_picker(node, opts) end
+
+---
+---Open file with ['bufhidden'] set to `delete`.
+---
+---@param node? nvim_tree.api.Node directory or file
+---@param opts? nvim_tree.api.node.open.Opts optional
+function nvim_tree.api.node.open.preview(node, opts) end
+
+---
+---Open file with ['bufhidden'] set to `delete` without using the window picker.
+---
+---@param node? nvim_tree.api.Node directory or file
+---@param opts? nvim_tree.api.node.open.Opts optional
+function nvim_tree.api.node.open.preview_no_picker(node, opts) end
+
+---
+---Open file in place: in the nvim-tree window.
+---
+---@param node? nvim_tree.api.Node file
+function nvim_tree.api.node.open.replace_tree_buffer(node) end
+
+---
+---Open file in a new tab.
+---
+---@param node? nvim_tree.api.Node directory or file
+---@param opts? nvim_tree.api.node.open.Opts optional
+function nvim_tree.api.node.open.tab(node, opts) end
+
+---
+---Switch to tab containing window with selected file if it exists. Open file in new tab otherwise.
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.open.tab_drop(node) end
+
+---
+---Toggle [nvim_tree.config.renderer] {group_empty} for a directory. Needs {group_empty} set.
+---
+---@param node? nvim_tree.api.Node directory
+---@param opts? nvim_tree.api.node.open.Opts optional
+function nvim_tree.api.node.open.toggle_group_empty(node, opts) end
+
+---
+---Open file in a new vertical split.
+---
+---@param node? nvim_tree.api.Node file
+---@param opts? nvim_tree.api.node.open.Opts optional
+function nvim_tree.api.node.open.vertical(node, opts) end
+
+---
+---Open file in a new vertical split without using the window picker.
+---
+---@param node? nvim_tree.api.Node file
+---@param opts? nvim_tree.api.node.open.Opts optional
+function nvim_tree.api.node.open.vertical_no_picker(node, opts) end
 
 ---
 ---@class nvim_tree.api.node.buffer.RemoveOpts
@@ -57,6 +153,124 @@ function nvim_tree.api.node.expand(node, opts) end
 ---@field expand_until? fun(expansion_count: integer, node: Node): boolean
 
 
+nvim_tree.api.node.navigate = {}
+
+---
+---Navigate to the parent directory of the node.
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.parent(node) end
+
+---
+---Navigate to the parent directory of the node, closing it.
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.parent_close(node) end
+
+nvim_tree.api.node.navigate.diagnostics = {}
+
+---
+---Navigate to the next item showing diagnostic status.
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.diagnostics.next(node) end
+
+---
+---Navigate to the next item showing diagnostic status, recursively. Needs [nvim_tree.config.diagnostics] {show_on_dirs}
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.diagnostics.next_recursive(node) end
+
+---
+---Navigate to the previous item showing diagnostic status.
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.diagnostics.prev(node) end
+
+---
+---Navigate to the previous item showing diagnostic status, recursively. Needs [nvim_tree.config.diagnostics] {show_on_dirs}
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.diagnostics.prev_recursive(node) end
+
+nvim_tree.api.node.navigate.git = {}
+
+---
+---Navigate to the next item showing git status.
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.git.next(node) end
+
+---
+---Navigate to the next item showing git status, recursively. Needs [nvim_tree.config.git] {show_on_dirs}
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.git.next_recursive(node) end
+
+---
+---Navigate to the next item showing git status, skipping `.gitignore`
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.git.next_skip_gitignored(node) end
+
+---
+---Navigate to the previous item showing git status.
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.git.prev(node) end
+
+---
+---Navigate to the previous item showing git status, recursively. Needs [nvim_tree.config.git] {show_on_dirs}
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.git.prev_recursive(node) end
+
+---
+---Navigate to the previous item showing git status, skipping `.gitignore`
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.git.prev_skip_gitignored(node) end
+
+nvim_tree.api.node.navigate.opened = {}
+
+---
+---Navigate to the next [bufloaded()] file.
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.opened.next(node) end
+
+---
+---Navigate to the previous [bufloaded()] file.
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.opened.prev(node) end
+
+nvim_tree.api.node.navigate.sibling = {}
+
+---
+---Navigate to the first node in the current node's folder.
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.sibling.first(node) end
+
+---
+---Navigate to the last node in the current node's folder.
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.sibling.last(node) end
+
+---
+---Navigate to the next node in the current node's folder, wraps.
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.sibling.next(node) end
+
+---
+---Navigate to the previous node in the current node's folder, wraps.
+---
+---@param node? nvim_tree.api.Node directory or file
+function nvim_tree.api.node.navigate.sibling.prev(node) end
+
 nvim_tree.api.node.run = {}
 
 ---
diff --git a/lua/nvim-tree/_meta/api/node/navigate.lua b/lua/nvim-tree/_meta/api/node/navigate.lua
deleted file mode 100644
index b398b1b88fd..00000000000
--- a/lua/nvim-tree/_meta/api/node/navigate.lua
+++ /dev/null
@@ -1,120 +0,0 @@
----@meta
-local nvim_tree = { api = { node = { navigate = {}, } } }
-
----
----Navigate to the parent directory of the node.
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.parent(node) end
-
----
----Navigate to the parent directory of the node, closing it.
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.parent_close(node) end
-
-nvim_tree.api.node.navigate.diagnostics = {}
-
----
----Navigate to the next item showing diagnostic status.
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.diagnostics.next(node) end
-
----
----Navigate to the next item showing diagnostic status, recursively. Needs [nvim_tree.config.diagnostics] {show_on_dirs}
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.diagnostics.next_recursive(node) end
-
----
----Navigate to the previous item showing diagnostic status.
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.diagnostics.prev(node) end
-
----
----Navigate to the previous item showing diagnostic status, recursively. Needs [nvim_tree.config.diagnostics] {show_on_dirs}
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.diagnostics.prev_recursive(node) end
-
-nvim_tree.api.node.navigate.git = {}
-
----
----Navigate to the next item showing git status.
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.git.next(node) end
-
----
----Navigate to the next item showing git status, recursively. Needs [nvim_tree.config.git] {show_on_dirs}
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.git.next_recursive(node) end
-
----
----Navigate to the next item showing git status, skipping `.gitignore`
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.git.next_skip_gitignored(node) end
-
----
----Navigate to the previous item showing git status.
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.git.prev(node) end
-
----
----Navigate to the previous item showing git status, recursively. Needs [nvim_tree.config.git] {show_on_dirs}
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.git.prev_recursive(node) end
-
----
----Navigate to the previous item showing git status, skipping `.gitignore`
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.git.prev_skip_gitignored(node) end
-
-nvim_tree.api.node.navigate.opened = {}
-
----
----Navigate to the next [bufloaded()] file.
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.opened.next(node) end
-
----
----Navigate to the previous [bufloaded()] file.
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.opened.prev(node) end
-
-nvim_tree.api.node.navigate.sibling = {}
-
----
----Navigate to the first node in the current node's folder.
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.sibling.first(node) end
-
----
----Navigate to the last node in the current node's folder.
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.sibling.last(node) end
-
----
----Navigate to the next node in the current node's folder, wraps.
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.sibling.next(node) end
-
----
----Navigate to the previous node in the current node's folder, wraps.
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.navigate.sibling.prev(node) end
-
-return nvim_tree.api.node.navigate
diff --git a/lua/nvim-tree/_meta/api/node/open.lua b/lua/nvim-tree/_meta/api/node/open.lua
deleted file mode 100644
index 1b33bf2346e..00000000000
--- a/lua/nvim-tree/_meta/api/node/open.lua
+++ /dev/null
@@ -1,101 +0,0 @@
----@meta
-local nvim_tree = { api = { node = { open = {}, } } }
-
----
----@class nvim_tree.api.node.open.Opts
----@inlinedoc
----
----Quits the tree when opening the file.
----(default: false)
----@field quit_on_open? boolean
----
----Keep focus in the tree when opening the file.
----(default: false)
----@field focus? boolean
-
-
----
----- file: open as per [nvim_tree.config.actions.open_file]
----- directory: expand or collapse
----- root: change directory up
----
----@param node? nvim_tree.api.Node directory or file
----@param opts? nvim_tree.api.node.open.Opts optional
-function nvim_tree.api.node.open.edit(node, opts) end
-
----
----Open file in a new horizontal split.
----
----@param node? nvim_tree.api.Node file
----@param opts? nvim_tree.api.node.open.Opts optional
-function nvim_tree.api.node.open.horizontal(node, opts) end
-
----
----Open file in a new horizontal split without using the window picker.
----
----@param node? nvim_tree.api.Node file
----@param opts? nvim_tree.api.node.open.Opts optional
-function nvim_tree.api.node.open.horizontal_no_picker(node, opts) end
-
----
----Open file without using the window picker.
----
----@param node? nvim_tree.api.Node file
----@param opts? nvim_tree.api.node.open.Opts optional
-function nvim_tree.api.node.open.no_window_picker(node, opts) end
-
----
----Open file with ['bufhidden'] set to `delete`.
----
----@param node? nvim_tree.api.Node directory or file
----@param opts? nvim_tree.api.node.open.Opts optional
-function nvim_tree.api.node.open.preview(node, opts) end
-
----
----Open file with ['bufhidden'] set to `delete` without using the window picker.
----
----@param node? nvim_tree.api.Node directory or file
----@param opts? nvim_tree.api.node.open.Opts optional
-function nvim_tree.api.node.open.preview_no_picker(node, opts) end
-
----
----Open file in place: in the nvim-tree window.
----
----@param node? nvim_tree.api.Node file
-function nvim_tree.api.node.open.replace_tree_buffer(node) end
-
----
----Open file in a new tab.
----
----@param node? nvim_tree.api.Node directory or file
----@param opts? nvim_tree.api.node.open.Opts optional
-function nvim_tree.api.node.open.tab(node, opts) end
-
----
----Switch to tab containing window with selected file if it exists. Open file in new tab otherwise.
----
----@param node? nvim_tree.api.Node directory or file
-function nvim_tree.api.node.open.tab_drop(node) end
-
----
----Toggle [nvim_tree.config.renderer] {group_empty} for a directory. Needs {group_empty} set.
----
----@param node? nvim_tree.api.Node directory
----@param opts? nvim_tree.api.node.open.Opts optional
-function nvim_tree.api.node.open.toggle_group_empty(node, opts) end
-
----
----Open file in a new vertical split.
----
----@param node? nvim_tree.api.Node file
----@param opts? nvim_tree.api.node.open.Opts optional
-function nvim_tree.api.node.open.vertical(node, opts) end
-
----
----Open file in a new vertical split without using the window picker.
----
----@param node? nvim_tree.api.Node file
----@param opts? nvim_tree.api.node.open.Opts optional
-function nvim_tree.api.node.open.vertical_no_picker(node, opts) end
-
-return nvim_tree.api.node.open
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index 2c208cb7127..5482d24c4d7 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -44,13 +44,10 @@ local srcs = {
   { helptag = "nvim-tree-api-events",                 section = "API: events",                 path = "./lua/nvim_tree/_meta/api/events.lua", },
   { helptag = "nvim-tree-api-filter",                 section = "API: filter",                 path = "./lua/nvim_tree/_meta/api/filter.lua", },
   { helptag = "nvim-tree-api-fs",                     section = "API: fs",                     path = "./lua/nvim_tree/_meta/api/fs.lua", },
-  { helptag = "nvim-tree-api-fs-copy",                section = "API: fs.copy",                path = "./lua/nvim_tree/_meta/api/fs/copy.lua", },
   { helptag = "nvim-tree-api-health",                 section = "API: health",                 path = "./lua/nvim_tree/_meta/api/health.lua", },
   { helptag = "nvim-tree-api-map",                    section = "API: map",                    path = "./lua/nvim_tree/_meta/api/map.lua", },
   { helptag = "nvim-tree-api-marks",                  section = "API: marks",                  path = "./lua/nvim_tree/_meta/api/marks.lua", },
   { helptag = "nvim-tree-api-node",                   section = "API: node",                   path = "./lua/nvim_tree/_meta/api/node.lua", },
-  { helptag = "nvim-tree-api-node-navigate",          section = "API: node.navigate",          path = "./lua/nvim_tree/_meta/api/node/navigate.lua", },
-  { helptag = "nvim-tree-api-node-open",              section = "API: node.open",              path = "./lua/nvim_tree/_meta/api/node/open.lua", },
   { helptag = "nvim-tree-api-tree",                   section = "API: tree",                   path = "./lua/nvim_tree/_meta/api/tree.lua", },
 }
 

From 338e95a71cbb8ef02e10fd8718305dde4a1507b1 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sun, 25 Jan 2026 17:49:24 +1100
Subject: [PATCH 144/170] docs(#3088): move api help and classes back into
 api.lua

---
 lua/nvim-tree/_meta/api.lua     | 112 --------------------------------
 lua/nvim-tree/_meta/classes.lua |  43 ++++++++++++
 lua/nvim-tree/api.lua           |  76 +++++++++++++++++++++-
 lua/nvim-tree/api/impl/post.lua |  16 +++--
 lua/nvim-tree/api/impl/pre.lua  |  12 ++--
 scripts/gen_vimdoc_config.lua   |   2 +-
 6 files changed, 136 insertions(+), 125 deletions(-)
 delete mode 100644 lua/nvim-tree/_meta/api.lua
 create mode 100644 lua/nvim-tree/_meta/classes.lua

diff --git a/lua/nvim-tree/_meta/api.lua b/lua/nvim-tree/_meta/api.lua
deleted file mode 100644
index 5f7e4f55c0a..00000000000
--- a/lua/nvim-tree/_meta/api.lua
+++ /dev/null
@@ -1,112 +0,0 @@
----@meta
-error("Cannot require a meta file")
-
----@brief
----nvim-tree exposes a public API. This is non breaking, with additions made as necessary.
----
----Please do not require or use modules other than `nvim-tree.api`, as internal modules will change without notice.
----
----The API is separated into multiple modules:
----
----- [nvim-tree-api-commands]
----- [nvim-tree-api-events]
----- [nvim-tree-api-filter]
----- [nvim-tree-api-fs]
----- [nvim-tree-api-health]
----- [nvim-tree-api-map]
----- [nvim-tree-api-marks]
----- [nvim-tree-api-node]
----- [nvim-tree-api-tree]
----
----Modules are accessed via `api..`
----
----Example invocation of the `reload` function in the `tree` module:
----```lua
----
----local api = require("nvim-tree.api")
----api.tree.reload()
----```
----Generally, functions accepting a [nvim_tree.api.Node] as their first argument will use the node under the cursor when that argument is not present or nil. e.g. the following are functionally identical:
----```lua
----
----api.node.open.edit(nil, { focus = true })
----
----api.node.open.edit(api.tree.get_node_under_cursor(), { focus = true })
----```
-
-
----The Node class is a data class. Instances may be provided by API functions for use as a:
----- handle to pass back to API functions e.g. [nvim_tree.api.node.run.cmd()]
----- reference in callbacks e.g. [nvim_tree.config.sort.Sorter] {sorter}
----
----Please do not mutate the contents of any Node object.
----
----@class nvim_tree.api.Node
----@field absolute_path string of the file or directory
----@field name string file or directory name
----@field parent? nvim_tree.api.DirectoryNode parent directory, nil for root
----@field type "file" | "directory" | "link" [uv.fs_stat()] {type}
----@field executable boolean file is executable
----@field fs_stat? uv.fs_stat.result at time of last tree display, see [uv.fs_stat()]
----@field git_status nvim_tree.git.Status? for files and directories
----@field diag_severity? lsp.DiagnosticSeverity diagnostic status
----@field hidden boolean node is not visible in the tree
-
-
----
----Git statuses for a single node.
----
----`nvim_tree.git.XY`: 2 character string, see `man 1 git-status` "Short Format"
----@alias nvim_tree.git.XY string
----
----{dir} status is derived from its contents:
----- `direct`: inherited from child files
----- `indirect`: inherited from child directories
----
----@class nvim_tree.git.Status
----@field file? nvim_tree.git.XY status of a file node
----@field dir? table<"direct" | "indirect", nvim_tree.git.XY[]> direct inclusive-or indirect status
-
-
-
-
--- Following are exact as that prevents them from having documentation generated.
--- They are not ready for public exposure as:
--- - They are not classic classes
--- - They are only used in a few locations: api.tree.get_nodes and UserDecorator
-
----
----File
----
----@class (exact) nvim_tree.api.FileNode: nvim_tree.api.Node
----@field extension string
-
----
----Directory
----
----@class (exact) nvim_tree.api.DirectoryNode: nvim_tree.api.Node
----@field has_children boolean
----@field nodes nvim_tree.api.Node[]
----@field open boolean
-
----
----Root Directory
----
----@class (exact) nvim_tree.api.RootNode: nvim_tree.api.DirectoryNode
-
----
----Link mixin
----
----@class (exact) nvim_tree.api.LinkNode
----@field link_to string
----@field fs_stat_target uv.fs_stat.result
-
----
----File Link
----
----@class (exact) nvim_tree.api.FileLinkNode: nvim_tree.api.FileNode, nvim_tree.api.LinkNode
-
----
----DirectoryLink
----
----@class (exact) nvim_tree.api.DirectoryLinkNode: nvim_tree.api.DirectoryNode, nvim_tree.api.LinkNode
diff --git a/lua/nvim-tree/_meta/classes.lua b/lua/nvim-tree/_meta/classes.lua
new file mode 100644
index 00000000000..859c457a8e7
--- /dev/null
+++ b/lua/nvim-tree/_meta/classes.lua
@@ -0,0 +1,43 @@
+---@meta
+error("Cannot require a meta file")
+
+
+-- These node subclasses are not ready for public exposure as they are:
+-- - not classic classes
+-- - only used in a few locations: api.tree.get_nodes and UserDecorator
+
+---
+---File
+---
+---@class (exact) nvim_tree.api.FileNode: nvim_tree.api.Node
+---@field extension string
+
+---
+---Directory
+---
+---@class (exact) nvim_tree.api.DirectoryNode: nvim_tree.api.Node
+---@field has_children boolean
+---@field nodes nvim_tree.api.Node[]
+---@field open boolean
+
+---
+---Root Directory
+---
+---@class (exact) nvim_tree.api.RootNode: nvim_tree.api.DirectoryNode
+
+---
+---Link mixin
+---
+---@class (exact) nvim_tree.api.LinkNode
+---@field link_to string
+---@field fs_stat_target uv.fs_stat.result
+
+---
+---File Link
+---
+---@class (exact) nvim_tree.api.FileLinkNode: nvim_tree.api.FileNode, nvim_tree.api.LinkNode
+
+---
+---DirectoryLink
+---
+---@class (exact) nvim_tree.api.DirectoryLinkNode: nvim_tree.api.DirectoryNode, nvim_tree.api.LinkNode
diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index 5542583b21c..f9d5b4a17a7 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -1,5 +1,75 @@
 local api = {}
 
+---@brief
+---nvim-tree exposes a public API. This is non breaking, with additions made as necessary.
+---
+---Please do not require or use modules other than `nvim-tree.api`, as internal modules will change without notice.
+---
+---The API is separated into multiple modules:
+---
+---- [nvim-tree-api-commands]
+---- [nvim-tree-api-events]
+---- [nvim-tree-api-filter]
+---- [nvim-tree-api-fs]
+---- [nvim-tree-api-health]
+---- [nvim-tree-api-map]
+---- [nvim-tree-api-marks]
+---- [nvim-tree-api-node]
+---- [nvim-tree-api-tree]
+---
+---Modules are accessed via `api..`
+---
+---Example invocation of the `reload` function in the `tree` module:
+---```lua
+---
+---local api = require("nvim-tree.api")
+---api.tree.reload()
+---```
+---Generally, functions accepting a [nvim_tree.api.Node] as their first argument will use the node under the cursor when that argument is not present or nil. e.g. the following are functionally identical:
+---```lua
+---
+---api.node.open.edit(nil, { focus = true })
+---
+---api.node.open.edit(api.tree.get_node_under_cursor(), { focus = true })
+---```
+
+
+
+---The Node class is a data class. Instances may be provided by API functions for use as a:
+---- handle to pass back to API functions e.g. [nvim_tree.api.node.run.cmd()]
+---- reference in callbacks e.g. [nvim_tree.config.sort.Sorter] {sorter}
+---
+---Please do not mutate the contents of any Node object.
+---
+---@class nvim_tree.api.Node
+---@field absolute_path string of the file or directory
+---@field name string file or directory name
+---@field parent? nvim_tree.api.DirectoryNode parent directory, nil for root
+---@field type "file" | "directory" | "link" [uv.fs_stat()] {type}
+---@field executable boolean file is executable
+---@field fs_stat? uv.fs_stat.result at time of last tree display, see [uv.fs_stat()]
+---@field git_status nvim_tree.git.Status? for files and directories
+---@field diag_severity? lsp.DiagnosticSeverity diagnostic status
+---@field hidden boolean node is not visible in the tree
+
+
+
+---
+---Git statuses for a single node.
+---
+---`nvim_tree.git.XY`: 2 character string, see `man 1 git-status` "Short Format"
+---@alias nvim_tree.git.XY string
+---
+---{dir} status is derived from its contents:
+---- `direct`: inherited from child files
+---- `indirect`: inherited from child directories
+---
+---@class nvim_tree.git.Status
+---@field file? nvim_tree.git.XY status of a file node
+---@field dir? table<"direct" | "indirect", nvim_tree.git.XY[]> direct inclusive-or indirect status
+
+
+
 --
 -- Load the (empty) meta definitions
 --
@@ -13,9 +83,13 @@ api.marks = require("nvim-tree._meta.api.marks")
 api.node = require("nvim-tree._meta.api.node")
 api.tree = require("nvim-tree._meta.api.tree")
 
+
+
 --
--- Map implementations
+-- Map before-setup implementations, most throw an error notification "nvim-tree setup not called".
 --
 require("nvim-tree.api.impl.pre")(api)
 
+
+
 return api
diff --git a/lua/nvim-tree/api/impl/post.lua b/lua/nvim-tree/api/impl/post.lua
index 9bd690018d2..218a9482641 100644
--- a/lua/nvim-tree/api/impl/post.lua
+++ b/lua/nvim-tree/api/impl/post.lua
@@ -1,3 +1,11 @@
+---Hydrates all API functions with concrete implementations.
+---All "nvim-tree setup not called" error functions from pre.lua will be replaced.
+---
+---Call this after nvim-tree setup
+---
+---This is expensive as there are many cascading requires and is avoided
+---until after setup has been called, so that the user may require API cheaply.
+
 local view = require("nvim-tree.view")
 local actions = require("nvim-tree.actions")
 
@@ -243,13 +251,7 @@ local function hydrate_post(api)
   api.map.get_keymap = function() require("nvim-tree.keymap").get_keymap() end
 end
 
----Hydrates all API functions with concrete implementations.
----All "nvim-tree setup not called" error functions will be replaced.
----
----Call this after nvim-tree setup
----
----This is expensive as there are many cascading requires and is avoided
----until after setup has been called, so that the user may require API cheaply.
+---Re-hydrate api
 ---@param api table
 return function(api)
   -- All concrete implementations
diff --git a/lua/nvim-tree/api/impl/pre.lua b/lua/nvim-tree/api/impl/pre.lua
index f185781dd5a..830485f2ee5 100644
--- a/lua/nvim-tree/api/impl/pre.lua
+++ b/lua/nvim-tree/api/impl/pre.lua
@@ -1,4 +1,11 @@
+--Hydrates meta api empty definition functions with a new function:
+-- - Default: error notification "nvim-tree setup not called".
+-- - Exceptions: concrete implementation for API that can be called before setup.
+--
+--Call it once when api is first required
+--
 --This file should have minimal requires that are cheap and have no dependencies or are already required.
+--
 --Everything must be as lazily loaded as possible: the user must be able to require api cheaply.
 
 local commands = require("nvim-tree.commands") -- already required by plugin.lua
@@ -58,10 +65,7 @@ local function hydrate_pre(api)
   api.decorator.UserDecorator = UserDecorator --[[@as nvim_tree.api.decorator.UserDecorator]]
 end
 
---Hydrates meta api empty definition functions with a new function:
--- - Default: error notification "nvim-tree setup not called".
--- - Exceptions: concrete implementation for API that can be called before setup.
---Call it once when api is first required
+---Hydrate api
 ---@param api table
 return function(api)
   -- Default: error
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index 5482d24c4d7..962869655fb 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -38,7 +38,7 @@ local srcs = {
 
   { helptag = "nvim-tree-config-default",             section = "Config: Default",             path = "./lua/nvim_tree/_meta/config/default.lua", },
 
-  { helptag = "nvim-tree-api",                        section = "API",                         path = "./lua/nvim_tree/_meta/api.lua", },
+  { helptag = "nvim-tree-api",                        section = "API",                         path = "./lua/nvim_tree/api.lua", },
 
   { helptag = "nvim-tree-api-commands",               section = "API: commands",               path = "./lua/nvim_tree/_meta/api/commands.lua", },
   { helptag = "nvim-tree-api-events",                 section = "API: events",                 path = "./lua/nvim_tree/_meta/api/events.lua", },

From b4b9b2022519bdc27197e2df256a499eeb1ca103 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sun, 25 Jan 2026 18:33:00 +1100
Subject: [PATCH 145/170] docs(#3088): resize command calls api, not view

---
 doc/nvim-tree-lua.txt      | 10 ++++++++--
 lua/nvim-tree/commands.lua |  7 ++++++-
 2 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index c2c8a59592c..23192e39320 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -281,9 +281,15 @@ All commands execute public API.
 
   require("nvim-tree.api").health.hi_test()
 <
-*:NvimTreeResize*
+*:NvimTreeResize*                          |nvim_tree.api.tree.resize()| >lua
 
-Columns integer argument is absolute (e.g. `40`) or a delta (e.g. `-5`, `+5`)
+  local sign = c.args:sub(1, 1)
+  if sign == "+" or sign == "-" then
+    require("nvim-tree.api").tree.resize({ relative = tonumber(c.args) })
+  else
+    require("nvim-tree.api").tree.resize({ absolute = tonumber(c.args) })
+  end
+<
 
 ==============================================================================
 Setup                                                        *nvim-tree-setup*
diff --git a/lua/nvim-tree/commands.lua b/lua/nvim-tree/commands.lua
index 093254707bd..1f788127aa9 100644
--- a/lua/nvim-tree/commands.lua
+++ b/lua/nvim-tree/commands.lua
@@ -109,7 +109,12 @@ local CMDS = {
       bar = true,
     },
     command = function(c)
-      require("nvim-tree.view").resize(c.args)
+      local sign = c.args:sub(1, 1)
+      if sign == "+" or sign == "-" then
+        require("nvim-tree.api").tree.resize({ relative = tonumber(c.args) })
+      else
+        require("nvim-tree.api").tree.resize({ absolute = tonumber(c.args) })
+      end
     end,
   },
   {

From d8558bb369d47fa62c95a65ae3e1eccf6be00288 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Mon, 26 Jan 2026 14:42:24 +1100
Subject: [PATCH 146/170] docs(#3088): tidy api map names

---
 README.md                       |  2 +-
 doc/nvim-tree-lua.txt           | 38 ++++++++++++++++-----------------
 lua/nvim-tree/_meta/api/map.lua | 12 +++++++----
 lua/nvim-tree/api/impl/pre.lua  |  2 +-
 lua/nvim-tree/help.lua          |  2 +-
 lua/nvim-tree/keymap.lua        | 12 +++++------
 lua/nvim-tree/legacy.lua        |  6 +++---
 scripts/help-update.sh          | 22 +++++++++----------
 8 files changed, 50 insertions(+), 46 deletions(-)

diff --git a/README.md b/README.md
index 2a9e68813d6..5bcb3d58fa3 100644
--- a/README.md
+++ b/README.md
@@ -97,7 +97,7 @@ local function my_on_attach(bufnr)
   end
 
   -- default mappings
-  api.map.default_on_attach(bufnr)
+  api.map.on_attach.default(bufnr)
 
   -- custom mappings
   vim.keymap.set('n', '', api.tree.change_root_to_parent,        opts('Up'))
diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 23192e39320..2dbdbaea99d 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -179,7 +179,7 @@ via |nvim_tree.config| {on_attach} e.g. >lua
     end
 
     -- default mappings
-    api.map.default_on_attach(bufnr)
+    api.map.on_attach.default(bufnr)
 
     -- custom mappings
     vim.keymap.set("n", "", api.tree.change_root_to_parent,        opts("Up"))
@@ -348,7 +348,7 @@ The `on_attach` function is passed the `bufnr` of nvim-tree. Use
     vim.keymap.set("n", "", api.node.open.replace_tree_buffer,     opts("Open: In Place"))
     ---
     -- OR use all default mappings
-    api.map.default_on_attach.default_on_attach(bufnr)
+    api.map.on_attach.default.on_attach_default(bufnr)
 
     -- remove a default
     vim.keymap.del("n", "", { buffer = bufnr })
@@ -397,7 +397,7 @@ You are encouraged to copy these to your {on_attach} function. >lua
     return { desc = "nvim-tree: " .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true }
   end
 
-  -- BEGIN_DEFAULT_ON_ATTACH
+  -- BEGIN_ON_ATTACH_DEFAULT
   vim.keymap.set("n", "",          api.tree.change_root_to_node,       opts("CD"))
   vim.keymap.set("n", "",          api.node.open.replace_tree_buffer,  opts("Open: In Place"))
   vim.keymap.set("n", "",          api.node.show_info_popup,           opts("Info"))
@@ -457,10 +457,10 @@ You are encouraged to copy these to your {on_attach} function. >lua
   vim.keymap.set("n", "Y",              api.fs.copy.relative_path,          opts("Copy Relative Path"))
   vim.keymap.set("n", "<2-LeftMouse>",  api.node.open.edit,                 opts("Open"))
   vim.keymap.set("n", "<2-RightMouse>", api.tree.change_root_to_node,       opts("CD"))
-  -- END_DEFAULT_ON_ATTACH
+  -- END_ON_ATTACH_DEFAULT
 <
 Alternatively, you may apply these default mappings from your
-|nvim_tree.config| {on_attach} via |nvim_tree.api.map.default_on_attach()| e.g. >lua
+|nvim_tree.config| {on_attach} via |nvim_tree.api.map.on_attach.default()| e.g. >lua
 
   local function my_on_attach(bufnr)
     local api = require("nvim-tree.api")
@@ -469,7 +469,7 @@ Alternatively, you may apply these default mappings from your
       return { desc = "nvim-tree: " .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true }
     end
 
-    api.map.default_on_attach.default_on_attach(bufnr)
+    api.map.on_attach.default.on_attach_default(bufnr)
 
     -- your removals and mappings go here
   end
@@ -1011,9 +1011,9 @@ Legacy: API                                             *nvim-tree-legacy-api*
 Some API functions have been refactored however the previous function will
 continue to be available.
 
-`api.config.mappings.get_keymap`         |nvim_tree.api.map.get_keymap()|
-`api.config.mappings.get_keymap_default` |nvim_tree.api.map.get_keymap_default()|
-`api.config.mappings.default_on_attach`  |nvim_tree.api.map.default_on_attach()|
+`api.config.mappings.get_keymap`         |nvim_tree.api.map.keymap.current()|
+`api.config.mappings.get_keymap_default` |nvim_tree.api.map.keymap.default()|
+`api.config.mappings.default_on_attach`  |nvim_tree.api.map.on_attach.default()|
 
 `api.diagnostics.hi_test`                |nvim_tree.api.health.hi_test()|
 
@@ -2615,14 +2615,7 @@ hi_test()                                     *nvim_tree.api.health.hi_test()*
 ==============================================================================
 API: map                                                   *nvim-tree-api-map*
 
-default_on_attach({bufnr})             *nvim_tree.api.map.default_on_attach()*
-    Apply all |nvim-tree-mappings-default|. Call from your |nvim_tree.config|
-    {on_attach}.
-
-    Parameters: ~
-      • {bufnr}  (`integer`) use the `bufnr` passed to {on_attach}
-
-get_keymap()                                  *nvim_tree.api.map.get_keymap()*
+keymap.current()                          *nvim_tree.api.map.keymap.current()*
     Retrieve all buffer local mappings for nvim-tree. These are the mappings
     that are applied by |nvim_tree.config| {on_attach}, which may include
     default mappings.
@@ -2630,13 +2623,20 @@ get_keymap()                                  *nvim_tree.api.map.get_keymap()*
     Return: ~
         (`vim.api.keyset.get_keymap[]`)
 
-get_keymap_default()                  *nvim_tree.api.map.get_keymap_default()*
+keymap.default()                          *nvim_tree.api.map.keymap.default()*
     Retrieves the buffer local mappings for nvim-tree that are applied by
-    |nvim_tree.api.map.default_on_attach()|
+    |nvim_tree.api.map.on_attach.default()|
 
     Return: ~
         (`vim.api.keyset.get_keymap[]`)
 
+on_attach.default({bufnr})             *nvim_tree.api.map.on_attach.default()*
+    Apply all |nvim-tree-mappings-default|. Call from your |nvim_tree.config|
+    {on_attach}.
+
+    Parameters: ~
+      • {bufnr}  (`integer`) use the `bufnr` passed to {on_attach}
+
 
 ==============================================================================
 API: marks                                               *nvim-tree-api-marks*
diff --git a/lua/nvim-tree/_meta/api/map.lua b/lua/nvim-tree/_meta/api/map.lua
index 58dc3f1f8d8..8273183eed7 100644
--- a/lua/nvim-tree/_meta/api/map.lua
+++ b/lua/nvim-tree/_meta/api/map.lua
@@ -1,22 +1,26 @@
 ---@meta
 local nvim_tree = { api = { map = {} } }
 
+nvim_tree.api.map.keymap = {}
+
 ---
 ---Retrieve all buffer local mappings for nvim-tree. These are the mappings that are applied by [nvim_tree.config] {on_attach}, which may include default mappings.
 ---
 ---@return vim.api.keyset.get_keymap[]
-function nvim_tree.api.map.get_keymap() end
+function nvim_tree.api.map.keymap.current() end
 
 ---
---- Retrieves the buffer local mappings for nvim-tree that are applied by [nvim_tree.api.map.default_on_attach()]
+--- Retrieves the buffer local mappings for nvim-tree that are applied by [nvim_tree.api.map.on_attach.default()]
 ---
 ---@return vim.api.keyset.get_keymap[]
-function nvim_tree.api.map.get_keymap_default() end
+function nvim_tree.api.map.keymap.default() end
+
+nvim_tree.api.map.on_attach = {}
 
 ---
 ---Apply all [nvim-tree-mappings-default]. Call from your [nvim_tree.config] {on_attach}.
 ---
 ---@param bufnr integer use the `bufnr` passed to {on_attach}
-function nvim_tree.api.map.default_on_attach(bufnr) end
+function nvim_tree.api.map.on_attach.default(bufnr) end
 
 return nvim_tree.api.map
diff --git a/lua/nvim-tree/api/impl/pre.lua b/lua/nvim-tree/api/impl/pre.lua
index 830485f2ee5..b34a93dbbf3 100644
--- a/lua/nvim-tree/api/impl/pre.lua
+++ b/lua/nvim-tree/api/impl/pre.lua
@@ -38,7 +38,7 @@ local function hydrate_pre(api)
   api.events.Event = events.Event
   api.events.subscribe = events.subscribe
 
-  api.map.default_on_attach = keymap.default_on_attach
+  api.map.on_attach.default = keymap.on_attach_default
 
 
   --
diff --git a/lua/nvim-tree/help.lua b/lua/nvim-tree/help.lua
index a5a0dbd6b4a..f5a971e3546 100644
--- a/lua/nvim-tree/help.lua
+++ b/lua/nvim-tree/help.lua
@@ -45,7 +45,7 @@ local function tidy_lhs(lhs)
 end
 
 --- Remove prefix 'nvim-tree: '
---- Hardcoded to keep default_on_attach simple
+--- Hardcoded to keep on_attach_default simple
 ---@param desc string
 ---@return string
 local function tidy_desc(desc)
diff --git a/lua/nvim-tree/keymap.lua b/lua/nvim-tree/keymap.lua
index 09481b0b831..64326b86ea3 100644
--- a/lua/nvim-tree/keymap.lua
+++ b/lua/nvim-tree/keymap.lua
@@ -1,7 +1,7 @@
 local M = {}
 
 --- Apply mappings to a scratch buffer and return buffer local mappings
----@param fn fun(bufnr: integer) on_attach or default_on_attach
+---@param fn fun(bufnr: integer) on_attach or on_attach_default
 ---@return table as per vim.api.nvim_buf_get_keymap
 local function generate_keymap(fn)
   -- create an unlisted scratch buffer
@@ -26,11 +26,11 @@ end
 
 ---@return table
 function M.get_keymap_default()
-  return generate_keymap(M.default_on_attach)
+  return generate_keymap(M.on_attach_default)
 end
 
 ---@param bufnr integer
-function M.default_on_attach(bufnr)
+function M.on_attach_default(bufnr)
   local api = require("nvim-tree.api")
 
   local function opts(desc)
@@ -43,7 +43,7 @@ function M.default_on_attach(bufnr)
     }
   end
 
-  -- BEGIN_DEFAULT_ON_ATTACH
+  -- BEGIN_ON_ATTACH_DEFAULT
   vim.keymap.set("n", "",          api.tree.change_root_to_node,       opts("CD"))
   vim.keymap.set("n", "",          api.node.open.replace_tree_buffer,  opts("Open: In Place"))
   vim.keymap.set("n", "",          api.node.show_info_popup,           opts("Info"))
@@ -103,12 +103,12 @@ function M.default_on_attach(bufnr)
   vim.keymap.set("n", "Y",              api.fs.copy.relative_path,          opts("Copy Relative Path"))
   vim.keymap.set("n", "<2-LeftMouse>",  api.node.open.edit,                 opts("Open"))
   vim.keymap.set("n", "<2-RightMouse>", api.tree.change_root_to_node,       opts("CD"))
-  -- END_DEFAULT_ON_ATTACH
+  -- END_ON_ATTACH_DEFAULT
 end
 
 function M.setup(opts)
   if type(opts.on_attach) ~= "function" then
-    M.on_attach = M.default_on_attach
+    M.on_attach = M.on_attach_default
   else
     M.on_attach = opts.on_attach
   end
diff --git a/lua/nvim-tree/legacy.lua b/lua/nvim-tree/legacy.lua
index 265260159d5..294050d58a8 100644
--- a/lua/nvim-tree/legacy.lua
+++ b/lua/nvim-tree/legacy.lua
@@ -168,9 +168,9 @@ end
 function M.map_api(api)
   api.config = api.config or {}
   api.config.mappings = api.config.mappings or {}
-  api.config.mappings.get_keymap = api.map.get_keymap
-  api.config.mappings.get_keymap_default = api.map.get_keymap_default
-  api.config.mappings.default_on_attach = api.map.default_on_attach
+  api.config.mappings.get_keymap = api.map.keymap.current
+  api.config.mappings.get_keymap_default = api.map.keymap.default
+  api.config.mappings.default_on_attach = api.map.on_attach.default
 
   api.git = api.git or {}
   api.git.reload = api.tree.reload_git
diff --git a/scripts/help-update.sh b/scripts/help-update.sh
index f37bd3f637b..a367feb9e81 100755
--- a/scripts/help-update.sh
+++ b/scripts/help-update.sh
@@ -1,6 +1,6 @@
 #!/usr/bin/env sh
 
-# run after changing default config or keymap.lua M.default_on_attach
+# run after changing default config or keymap.lua M.on_attach_default
 # scrapes and updates nvim-tree-lua.txt
 # run from repository root: scripts/help-update.sh  OR  make help-update
 
@@ -25,25 +25,25 @@ sed -i -e "/${inject}/r /tmp/DEFAULT_OPTS.6.lua" -e "/${inject}/d" doc/nvim-tree
 # Inject default mappings
 #
 
-begin="BEGIN_DEFAULT_ON_ATTACH"
-end="END_DEFAULT_ON_ATTACH"
+begin="BEGIN_ON_ATTACH_DEFAULT"
+end="END_ON_ATTACH_DEFAULT"
 
-# scrape DEFAULT_ON_ATTACH, indented at 2
-sed -n -e "/${begin}/,/${end}/{ /${begin}/d; /${end}/d; p; }" lua/nvim-tree/keymap.lua > /tmp/DEFAULT_ON_ATTACH.lua
+# scrape ON_ATTACH_DEFAULT, indented at 2
+sed -n -e "/${begin}/,/${end}/{ /${begin}/d; /${end}/d; p; }" lua/nvim-tree/keymap.lua > /tmp/ON_ATTACH_DEFAULT.lua
 
 # help lua
-sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/DEFAULT_ON_ATTACH.lua
+sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/ON_ATTACH_DEFAULT.lua
            }; /${end}/p; d; }" doc/nvim-tree-lua.txt
 
 # help human
-echo > /tmp/DEFAULT_ON_ATTACH.help
+echo > /tmp/ON_ATTACH_DEFAULT.help
 sed -E "s/^ *vim.keymap.set\(\"n\", \"(.*)\",.*api(.*),.*opts\(\"(.*)\".*$/'\`\1\`' '\3' '|nvim_tree.api\2()|'/g
-" /tmp/DEFAULT_ON_ATTACH.lua | while read -r line
+" /tmp/ON_ATTACH_DEFAULT.lua | while read -r line
 do
-	eval "printf '%-17.17s %-26.26s %s\n' ${line}" >> /tmp/DEFAULT_ON_ATTACH.help
+	eval "printf '%-17.17s %-26.26s %s\n' ${line}" >> /tmp/ON_ATTACH_DEFAULT.help
 done
-echo >> /tmp/DEFAULT_ON_ATTACH.help
+echo >> /tmp/ON_ATTACH_DEFAULT.help
 begin="Show the mappings:"
 end="======"
-sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/DEFAULT_ON_ATTACH.help
+sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/ON_ATTACH_DEFAULT.help
            }; /${end}/p; d; }" doc/nvim-tree-lua.txt

From cbd6fa24d612c33eeecb489609b280321d656066 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Mon, 26 Jan 2026 15:48:16 +1100
Subject: [PATCH 147/170] docs(#3088): revert api.git refactor, provide
 deprecated api meta

---
 doc/nvim-tree-lua.txt            | 14 +++++---
 lua/nvim-tree/_meta/api/_git.lua |  9 +++++
 lua/nvim-tree/_meta/api/tree.lua |  5 ---
 lua/nvim-tree/api.lua            |  9 +++++
 lua/nvim-tree/api/impl/post.lua  |  2 +-
 lua/nvim-tree/api/impl/pre.lua   |  4 +--
 lua/nvim-tree/legacy.lua         | 58 ++++++++++++++++++++++++++++----
 scripts/gen_vimdoc_config.lua    | 11 ++++--
 8 files changed, 89 insertions(+), 23 deletions(-)
 create mode 100644 lua/nvim-tree/_meta/api/_git.lua

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 2dbdbaea99d..feb3006e50e 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -1017,8 +1017,6 @@ continue to be available.
 
 `api.diagnostics.hi_test`                |nvim_tree.api.health.hi_test()|
 
-`api.git.reload`                         |nvim_tree.api.tree.reload_git()|
-
 `api.live_filter.start`                  |nvim_tree.api.filter.live.start()|
 `api.live_filter.clear`                  |nvim_tree.api.filter.live.clear()|
 
@@ -2371,6 +2369,7 @@ The API is separated into multiple modules:
 • |nvim-tree-api-events|
 • |nvim-tree-api-filter|
 • |nvim-tree-api-fs|
+• |nvim-tree-api-git|
 • |nvim-tree-api-health|
 • |nvim-tree-api-map|
 • |nvim-tree-api-marks|
@@ -2602,6 +2601,14 @@ trash({node})                                       *nvim_tree.api.fs.trash()*
       • {node}  (`nvim_tree.api.Node?`)
 
 
+==============================================================================
+API: git                                                   *nvim-tree-api-git*
+
+                               *nvim_tree.api._git.nvim_tree.api.git.reload()*
+nvim_tree.api.git.reload()
+    Update the git status of the entire tree.
+
+
 ==============================================================================
 API: health                                             *nvim-tree-api-health*
 
@@ -3131,9 +3138,6 @@ open({opts})                                       *nvim_tree.api.tree.open()*
 reload()                                         *nvim_tree.api.tree.reload()*
     Refresh the tree. Does nothing if closed.
 
-reload_git()                                 *nvim_tree.api.tree.reload_git()*
-    Update the git status of the entire tree.
-
 resize({opts})                                   *nvim_tree.api.tree.resize()*
     Resize the tree, persisting the new size. Resets to
     |nvim_tree.config.view| {width} when no {opts} provided.
diff --git a/lua/nvim-tree/_meta/api/_git.lua b/lua/nvim-tree/_meta/api/_git.lua
new file mode 100644
index 00000000000..9abf98e5f06
--- /dev/null
+++ b/lua/nvim-tree/_meta/api/_git.lua
@@ -0,0 +1,9 @@
+---@meta
+local nvim_tree = { api = { git = {  } } }
+
+---
+---Update the git status of the entire tree.
+---
+function nvim_tree.api.git.reload() end
+
+return nvim_tree.api.config
diff --git a/lua/nvim-tree/_meta/api/tree.lua b/lua/nvim-tree/_meta/api/tree.lua
index 7898942b11f..38587a2355c 100644
--- a/lua/nvim-tree/_meta/api/tree.lua
+++ b/lua/nvim-tree/_meta/api/tree.lua
@@ -228,9 +228,4 @@ function nvim_tree.api.tree.winid(opts) end
 ---[tab-ID] 0 or nil for current.
 ---@field tabpage? integer
 
----
----Update the git status of the entire tree.
----
-function nvim_tree.api.tree.reload_git() end
-
 return nvim_tree.api.tree
diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index f9d5b4a17a7..a2245b6400c 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -11,6 +11,7 @@ local api = {}
 ---- [nvim-tree-api-events]
 ---- [nvim-tree-api-filter]
 ---- [nvim-tree-api-fs]
+---- [nvim-tree-api-git]
 ---- [nvim-tree-api-health]
 ---- [nvim-tree-api-map]
 ---- [nvim-tree-api-marks]
@@ -69,6 +70,7 @@ local api = {}
 ---@field dir? table<"direct" | "indirect", nvim_tree.git.XY[]> direct inclusive-or indirect status
 
 
+-- TODO #3088 add nvim_tree.api class
 
 --
 -- Load the (empty) meta definitions
@@ -77,6 +79,7 @@ api.commands = require("nvim-tree._meta.api.commands")
 api.events = require("nvim-tree._meta.api.events")
 api.filter = require("nvim-tree._meta.api.filter")
 api.fs = require("nvim-tree._meta.api.fs")
+api.git = require("nvim-tree._meta.api._git")
 api.health = require("nvim-tree._meta.api.health")
 api.map = require("nvim-tree._meta.api.map")
 api.marks = require("nvim-tree._meta.api.marks")
@@ -84,6 +87,12 @@ api.node = require("nvim-tree._meta.api.node")
 api.tree = require("nvim-tree._meta.api.tree")
 
 
+---
+---@nodoc
+---Legacy meta definitions
+---
+api = require("nvim-tree.legacy").api_meta(api)
+
 
 --
 -- Map before-setup implementations, most throw an error notification "nvim-tree setup not called".
diff --git a/lua/nvim-tree/api/impl/post.lua b/lua/nvim-tree/api/impl/post.lua
index 218a9482641..45fcf0e3314 100644
--- a/lua/nvim-tree/api/impl/post.lua
+++ b/lua/nvim-tree/api/impl/post.lua
@@ -258,5 +258,5 @@ return function(api)
   hydrate_post(api)
 
   -- (Re)hydrate any legacy by mapping to function set above
-  require("nvim-tree.legacy").map_api(api)
+  require("nvim-tree.legacy").api_map(api)
 end
diff --git a/lua/nvim-tree/api/impl/pre.lua b/lua/nvim-tree/api/impl/pre.lua
index b34a93dbbf3..8df356584f3 100644
--- a/lua/nvim-tree/api/impl/pre.lua
+++ b/lua/nvim-tree/api/impl/pre.lua
@@ -30,7 +30,6 @@ local function hydrate_error(t)
 end
 
 ---Hydrate implementations that may be called pre setup
----@param api table
 local function hydrate_pre(api)
   --
   -- Essential
@@ -66,7 +65,6 @@ local function hydrate_pre(api)
 end
 
 ---Hydrate api
----@param api table
 return function(api)
   -- Default: error
   hydrate_error(api)
@@ -75,5 +73,5 @@ return function(api)
   hydrate_pre(api)
 
   -- Hydrate any legacy by mapping to function set above
-  require("nvim-tree.legacy").map_api(api)
+  require("nvim-tree.legacy").api_map(api)
 end
diff --git a/lua/nvim-tree/legacy.lua b/lua/nvim-tree/legacy.lua
index 294050d58a8..6a281a3f80d 100644
--- a/lua/nvim-tree/legacy.lua
+++ b/lua/nvim-tree/legacy.lua
@@ -163,18 +163,14 @@ end
 --API
 --
 
----Create new api entries pointing legacy functions to current
----@param api table
-function M.map_api(api)
+---Silently create new api entries pointing legacy functions to current
+function M.api_map(api)
   api.config = api.config or {}
   api.config.mappings = api.config.mappings or {}
   api.config.mappings.get_keymap = api.map.keymap.current
   api.config.mappings.get_keymap_default = api.map.keymap.default
   api.config.mappings.default_on_attach = api.map.on_attach.default
 
-  api.git = api.git or {}
-  api.git.reload = api.tree.reload_git
-
   api.live_filter = api.live_filter or {}
   api.live_filter.start = api.filter.live.start
   api.live_filter.clear = api.filter.live.clear
@@ -192,4 +188,54 @@ function M.map_api(api)
   api.diagnostics.hi_test = api.health.hi_test
 end
 
+---Add meta definitions for deprecated API
+function M.api_meta(api)
+  ---@deprecated nvim_tree.api.filter.toggle
+  function api.tree.toggle_enable_filters() end
+
+  ---@deprecated nvim_tree.api.filter.git.ignored.toggle
+  function api.tree.toggle_gitignore_filter() end
+
+  ---@deprecated nvim_tree.api.filter.git.clean.toggle
+  function api.tree.toggle_git_clean_filter() end
+
+  ---@deprecated nvim_tree.api.filter.no_buffer.toggle
+  function api.tree.toggle_no_buffer_filter() end
+
+  ---@deprecated nvim_tree.api.filter.custom.toggle
+  function api.tree.toggle_custom_filter() end
+
+  ---@deprecated nvim_tree.api.filter.dotfiles.toggle
+  function api.tree.toggle_hidden_filter() end
+
+  ---@deprecated nvim_tree.api.filter.no_bookmark.toggle
+  function api.tree.toggle_no_bookmark_filter() end
+
+  api.config = { mappings = {} }
+
+  ---@deprecated nvim_tree.api.map.keymap.current
+  function api.config.mappings.get_keymap() end
+
+  ---@deprecated nvim_tree.api.map.keymap.default
+  function api.config.mappings.get_keymap_default() end
+
+  ---@deprecated nvim_tree.api.map.on_attach.default
+  function api.config.mappings.default_on_attach(_) end
+
+  api.live_filter = {}
+
+  ---@deprecated nvim_tree.api.filter.live.start
+  function api.live_filter.start() end
+
+  ---@deprecated nvim_tree.api.filter.live.clear
+  function api.live_filter.clear() end
+
+  api.diagnostics = {}
+
+  ---@deprecated nvim_tree.api.health.hi_test
+  function api.diagnostics.hi_test() end
+
+  return api
+end
+
 return M
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index 962869655fb..691fe69bde8 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -44,6 +44,8 @@ local srcs = {
   { helptag = "nvim-tree-api-events",                 section = "API: events",                 path = "./lua/nvim_tree/_meta/api/events.lua", },
   { helptag = "nvim-tree-api-filter",                 section = "API: filter",                 path = "./lua/nvim_tree/_meta/api/filter.lua", },
   { helptag = "nvim-tree-api-fs",                     section = "API: fs",                     path = "./lua/nvim_tree/_meta/api/fs.lua", },
+  -- TODO #3088 come up with a solution to avoid filename clashes
+  { helptag = "nvim-tree-api-git",                    section = "API: git",                    path = "./lua/nvim_tree/_meta/api/_git.lua", },
   { helptag = "nvim-tree-api-health",                 section = "API: health",                 path = "./lua/nvim_tree/_meta/api/health.lua", },
   { helptag = "nvim-tree-api-map",                    section = "API: map",                    path = "./lua/nvim_tree/_meta/api/map.lua", },
   { helptag = "nvim-tree-api-marks",                  section = "API: marks",                  path = "./lua/nvim_tree/_meta/api/marks.lua", },
@@ -101,10 +103,13 @@ local config = {
 
         -- remove the API prefix from the left aligned function name
         -- this will cascade into fn_helptag_fmt, which will apply the module prefix anyway
+
+        -- TODO #3088 come up with a solution to avoid filename clashes
+        ---@diagnostic disable-next-line: unused-local
         local name, replaced = fun.name:gsub("^" .. module .. "%.", "", 1)
-        if (replaced ~= 1) then
-          error(string.format("function name does not start with module: %s", vim.inspect(fun)))
-        end
+        -- if (replaced ~= 1) then
+        --   error(string.format("function name does not start with module: %s", vim.inspect(fun)))
+        -- end
 
         print(string.format("fn_xform name: %s -> %s", fun.name, name))
 

From e460df41a47ff102a1de02889a0a8055b8afc8db Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Tue, 27 Jan 2026 12:31:47 +1100
Subject: [PATCH 148/170] docs(#3088): add deprecated api @see

---
 lua/nvim-tree/legacy.lua | 37 +++++++++++++++++++++++++------------
 1 file changed, 25 insertions(+), 12 deletions(-)

diff --git a/lua/nvim-tree/legacy.lua b/lua/nvim-tree/legacy.lua
index 6a281a3f80d..5c6af931c50 100644
--- a/lua/nvim-tree/legacy.lua
+++ b/lua/nvim-tree/legacy.lua
@@ -190,49 +190,62 @@ end
 
 ---Add meta definitions for deprecated API
 function M.api_meta(api)
-  ---@deprecated nvim_tree.api.filter.toggle
+  ---@deprecated
+  ---@see nvim_tree.api.filter.toggle
   function api.tree.toggle_enable_filters() end
 
-  ---@deprecated nvim_tree.api.filter.git.ignored.toggle
+  ---@deprecated
+  ---@see nvim_tree.api.filter.git.ignored.toggle
   function api.tree.toggle_gitignore_filter() end
 
-  ---@deprecated nvim_tree.api.filter.git.clean.toggle
+  ---@deprecated
+  ---@see nvim_tree.api.filter.git.clean.toggle
   function api.tree.toggle_git_clean_filter() end
 
-  ---@deprecated nvim_tree.api.filter.no_buffer.toggle
+  ---@deprecated
+  ---@see nvim_tree.api.filter.no_buffer.toggle
   function api.tree.toggle_no_buffer_filter() end
 
-  ---@deprecated nvim_tree.api.filter.custom.toggle
+  ---@deprecated
+  ---@see nvim_tree.api.filter.custom.toggle
   function api.tree.toggle_custom_filter() end
 
-  ---@deprecated nvim_tree.api.filter.dotfiles.toggle
+  ---@deprecated
+  ---@see nvim_tree.api.filter.dotfiles.toggle
   function api.tree.toggle_hidden_filter() end
 
-  ---@deprecated nvim_tree.api.filter.no_bookmark.toggle
+  ---@deprecated
+  ---@see nvim_tree.api.filter.no_bookmark.toggle
   function api.tree.toggle_no_bookmark_filter() end
 
   api.config = { mappings = {} }
 
-  ---@deprecated nvim_tree.api.map.keymap.current
+  ---@deprecated
+  ---@see nvim_tree.api.map.keymap.current
   function api.config.mappings.get_keymap() end
 
-  ---@deprecated nvim_tree.api.map.keymap.default
+  ---@deprecated
+  ---@see nvim_tree.api.map.keymap.default
   function api.config.mappings.get_keymap_default() end
 
   ---@deprecated nvim_tree.api.map.on_attach.default
+  ---@see nvim_tree.api.map.on_attach.default
   function api.config.mappings.default_on_attach(_) end
 
   api.live_filter = {}
 
-  ---@deprecated nvim_tree.api.filter.live.start
+  ---@deprecated
+  ---@see nvim_tree.api.filter.live.start
   function api.live_filter.start() end
 
-  ---@deprecated nvim_tree.api.filter.live.clear
+  ---@deprecated
+  ---@see nvim_tree.api.filter.live.clear
   function api.live_filter.clear() end
 
   api.diagnostics = {}
 
-  ---@deprecated nvim_tree.api.health.hi_test
+  ---@deprecated
+  ---@see nvim_tree.api.health.hi_test
   function api.diagnostics.hi_test() end
 
   return api

From ee06bf260d643229fc9da62cea46ebfd09b681d5 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Tue, 27 Jan 2026 12:42:54 +1100
Subject: [PATCH 149/170] docs(#3088): class fixes following merge, disable
 luacheck on scripts

---
 Makefile                         | 1 -
 lua/nvim-tree/_meta/api/_git.lua | 2 +-
 lua/nvim-tree/explorer/init.lua  | 6 +++---
 lua/nvim-tree/node/directory.lua | 2 +-
 lua/nvim-tree/node/init.lua      | 2 +-
 5 files changed, 6 insertions(+), 7 deletions(-)

diff --git a/Makefile b/Makefile
index 30f712ed6a6..4ec53e0bb4a 100644
--- a/Makefile
+++ b/Makefile
@@ -14,7 +14,6 @@ check: luals
 #
 luacheck:
 	luacheck --codes --quiet lua --exclude-files "**/_meta/**"
-	luacheck --codes --quiet scripts
 
 style-check:
 	scripts/luals-check.sh codestyle-check
diff --git a/lua/nvim-tree/_meta/api/_git.lua b/lua/nvim-tree/_meta/api/_git.lua
index 9abf98e5f06..a982a0d9389 100644
--- a/lua/nvim-tree/_meta/api/_git.lua
+++ b/lua/nvim-tree/_meta/api/_git.lua
@@ -1,5 +1,5 @@
 ---@meta
-local nvim_tree = { api = { git = {  } } }
+local nvim_tree = { api = { git = {} } }
 
 ---
 ---Update the git status of the entire tree.
diff --git a/lua/nvim-tree/explorer/init.lua b/lua/nvim-tree/explorer/init.lua
index a72e16d47dd..532684e74fb 100644
--- a/lua/nvim-tree/explorer/init.lua
+++ b/lua/nvim-tree/explorer/init.lua
@@ -689,7 +689,7 @@ end
 
 ---Expand the directory node or the root
 ---@param node Node
----@param expand_opts ApiTreeExpandOpts?
+---@param expand_opts? nvim_tree.api.node.expand.Opts
 function Explorer:expand_all(node, expand_opts)
   if node then
     node:expand(expand_opts)
@@ -699,8 +699,8 @@ function Explorer:expand_all(node, expand_opts)
 end
 
 ---Expand the directory node or parent node
----@param node Node
----@param expand_opts ApiTreeExpandOpts?
+---@param node? Node
+---@param expand_opts? nvim_tree.api.node.expand.Opts
 function Explorer:expand_node(node, expand_opts)
   if not node then
     return
diff --git a/lua/nvim-tree/node/directory.lua b/lua/nvim-tree/node/directory.lua
index 57850835e1c..d53718085f9 100644
--- a/lua/nvim-tree/node/directory.lua
+++ b/lua/nvim-tree/node/directory.lua
@@ -354,7 +354,7 @@ local function descend_until_empty(_, node)
   return not should_exclude
 end
 
----@param expand_opts ApiTreeExpandOpts?
+---@param expand_opts? nvim_tree.api.node.expand.Opts
 function DirectoryNode:expand(expand_opts)
   local expansion_count = 0
 
diff --git a/lua/nvim-tree/node/init.lua b/lua/nvim-tree/node/init.lua
index 545e56275c4..ef6f4e8757b 100644
--- a/lua/nvim-tree/node/init.lua
+++ b/lua/nvim-tree/node/init.lua
@@ -151,7 +151,7 @@ function Node:should_expand(_expansion_count, _should_descend)
   return false
 end
 
----@param expand_opts ApiTreeExpandOpts?
+---@param expand_opts? nvim_tree.api.node.expand.Opts
 function Node:expand(expand_opts)
   if self.parent then
     self.parent:expand(expand_opts)

From 7785196538804c4a8421425e1312dc26495ab497 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Tue, 27 Jan 2026 12:51:44 +1100
Subject: [PATCH 150/170] docs(#3088): Node:should_expand nops

---
 lua/nvim-tree/node/init.lua | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/lua/nvim-tree/node/init.lua b/lua/nvim-tree/node/init.lua
index ef6f4e8757b..5aaf4fb094a 100644
--- a/lua/nvim-tree/node/init.lua
+++ b/lua/nvim-tree/node/init.lua
@@ -144,10 +144,11 @@ function Node:clone(api_nodes)
   return clone
 end
 
----@param _expansion_count integer
----@param _should_descend fun(expansion_count: integer, node: Node): boolean
+---@param expansion_count integer
+---@param should_descend fun(expansion_count: integer, node: Node): boolean
 ---@return boolean
-function Node:should_expand(_expansion_count, _should_descend)
+function Node:should_expand(expansion_count, should_descend)
+  self:nop(expansion_count, should_descend)
   return false
 end
 

From ce74883c22e102932ff8a21d1501c9a03c55835a Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Tue, 27 Jan 2026 14:28:16 +1100
Subject: [PATCH 151/170] docs(#3088): fix _git return

---
 lua/nvim-tree/_meta/api/_git.lua | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lua/nvim-tree/_meta/api/_git.lua b/lua/nvim-tree/_meta/api/_git.lua
index a982a0d9389..0e9ea872d13 100644
--- a/lua/nvim-tree/_meta/api/_git.lua
+++ b/lua/nvim-tree/_meta/api/_git.lua
@@ -6,4 +6,4 @@ local nvim_tree = { api = { git = {} } }
 ---
 function nvim_tree.api.git.reload() end
 
-return nvim_tree.api.config
+return nvim_tree.api.git

From 86f0d817b08469fa760e0a3c7078f417a0472c06 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Tue, 27 Jan 2026 17:02:16 +1100
Subject: [PATCH 152/170] docs(#3088): add meta for legacy api

---
 lua/nvim-tree/_meta/api/deprecated.lua | 34 ++++++++++++++
 lua/nvim-tree/_meta/api/filter.lua     |  6 ++-
 lua/nvim-tree/_meta/api/tree.lua       | 23 ++++++++++
 lua/nvim-tree/api.lua                  | 35 +++++++-------
 lua/nvim-tree/legacy.lua               | 63 --------------------------
 5 files changed, 79 insertions(+), 82 deletions(-)
 create mode 100644 lua/nvim-tree/_meta/api/deprecated.lua

diff --git a/lua/nvim-tree/_meta/api/deprecated.lua b/lua/nvim-tree/_meta/api/deprecated.lua
new file mode 100644
index 00000000000..621bf2821d1
--- /dev/null
+++ b/lua/nvim-tree/_meta/api/deprecated.lua
@@ -0,0 +1,34 @@
+---@meta
+
+-- Deprecated top level API modules.
+-- Remember to add mappings in legacy.lua `api_map`
+
+local M = {}
+
+M.config = {}
+
+M.config.mappings = {}
+
+---@deprecated use `nvim_tree.api.map.keymap.current()`
+function M.config.mappings.get_keymap() end
+
+---@deprecated use `nvim_tree.api.map.keymap.default()`
+function M.config.mappings.get_keymap_default() end
+
+---@deprecated use `nvim_tree.api.map.on_attach.default()`
+function M.config.mappings.default_on_attach(bufnr) end
+
+M.live_filter = {}
+
+---@deprecated use `nvim_tree.api.filter.live.start()`
+function M.live_filter.start() end
+
+---@deprecated use `nvim_tree.api.filter.live.clear()`
+function M.live_filter.clear() end
+
+M.diagnostics = {}
+
+---@deprecated use `nvim_tree.api.health.hi_test()`
+function M.diagnostics.hi_test() end
+
+return M
diff --git a/lua/nvim-tree/_meta/api/filter.lua b/lua/nvim-tree/_meta/api/filter.lua
index d28172f483d..93b187a64cb 100644
--- a/lua/nvim-tree/_meta/api/filter.lua
+++ b/lua/nvim-tree/_meta/api/filter.lua
@@ -18,13 +18,17 @@ function nvim_tree.api.filter.live.start() end
 ---
 function nvim_tree.api.filter.live.clear() end
 
-nvim_tree.api.filter.git = { clean = {}, ignored = {} }
+nvim_tree.api.filter.git = {}
+
+nvim_tree.api.filter.git.clean = {}
 
 ---
 ---Toggle [nvim_tree.config.filters] {git_clean} filter.
 ---
 function nvim_tree.api.filter.git.clean.toggle() end
 
+nvim_tree.api.filter.git.ignored = {}
+
 ---
 ---Toggle [nvim_tree.config.filters] {git_ignored} filter.
 ---
diff --git a/lua/nvim-tree/_meta/api/tree.lua b/lua/nvim-tree/_meta/api/tree.lua
index 38587a2355c..c2ebe460bed 100644
--- a/lua/nvim-tree/_meta/api/tree.lua
+++ b/lua/nvim-tree/_meta/api/tree.lua
@@ -228,4 +228,27 @@ function nvim_tree.api.tree.winid(opts) end
 ---[tab-ID] 0 or nil for current.
 ---@field tabpage? integer
 
+
+---@deprecated use `nvim_tree.api.filter.toggle()`
+function nvim_tree.api.tree.toggle_enable_filters() end
+
+---@deprecated use `nvim_tree.api.filter.git.ignored.toggle()`
+function nvim_tree.api.tree.toggle_gitignore_filter() end
+
+---@deprecated use `nvim_tree.api.filter.git.clean.toggle()`
+function nvim_tree.api.tree.toggle_git_clean_filter() end
+
+---@deprecated use `nvim_tree.api.filter.no_buffer.toggle()`
+function nvim_tree.api.tree.toggle_no_buffer_filter() end
+
+---@deprecated use `nvim_tree.api.filter.custom.toggle()`
+function nvim_tree.api.tree.toggle_custom_filter() end
+
+---@deprecated use `nvim_tree.api.filter.dotfiles.toggle()`
+function nvim_tree.api.tree.toggle_hidden_filter() end
+
+---@deprecated use `nvim_tree.api.filter.no_bookmark.toggle()`
+function nvim_tree.api.tree.toggle_no_bookmark_filter() end
+
+
 return nvim_tree.api.tree
diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index a2245b6400c..dc2661d2894 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -1,5 +1,3 @@
-local api = {}
-
 ---@brief
 ---nvim-tree exposes a public API. This is non breaking, with additions made as necessary.
 ---
@@ -70,28 +68,29 @@ local api = {}
 ---@field dir? table<"direct" | "indirect", nvim_tree.git.XY[]> direct inclusive-or indirect status
 
 
--- TODO #3088 add nvim_tree.api class
 
 --
 -- Load the (empty) meta definitions
 --
-api.commands = require("nvim-tree._meta.api.commands")
-api.events = require("nvim-tree._meta.api.events")
-api.filter = require("nvim-tree._meta.api.filter")
-api.fs = require("nvim-tree._meta.api.fs")
-api.git = require("nvim-tree._meta.api._git")
-api.health = require("nvim-tree._meta.api.health")
-api.map = require("nvim-tree._meta.api.map")
-api.marks = require("nvim-tree._meta.api.marks")
-api.node = require("nvim-tree._meta.api.node")
-api.tree = require("nvim-tree._meta.api.tree")
-
 
----
+---nvim-tree Public API
+---@class nvim_tree.api
 ---@nodoc
----Legacy meta definitions
----
-api = require("nvim-tree.legacy").api_meta(api)
+local api = {
+  commands = require("nvim-tree._meta.api.commands"),
+  config = require("nvim-tree._meta.api.deprecated").config,
+  diagnostics = require("nvim-tree._meta.api.deprecated").diagnostics,
+  events = require("nvim-tree._meta.api.events"),
+  filter = require("nvim-tree._meta.api.filter"),
+  fs = require("nvim-tree._meta.api.fs"),
+  git = require("nvim-tree._meta.api._git"),
+  health = require("nvim-tree._meta.api.health"),
+  live_filter = require("nvim-tree._meta.api.deprecated").live_filter,
+  map = require("nvim-tree._meta.api.map"),
+  marks = require("nvim-tree._meta.api.marks"),
+  node = require("nvim-tree._meta.api.node"),
+  tree = require("nvim-tree._meta.api.tree"),
+}
 
 
 --
diff --git a/lua/nvim-tree/legacy.lua b/lua/nvim-tree/legacy.lua
index 5c6af931c50..72aad9e3d85 100644
--- a/lua/nvim-tree/legacy.lua
+++ b/lua/nvim-tree/legacy.lua
@@ -188,67 +188,4 @@ function M.api_map(api)
   api.diagnostics.hi_test = api.health.hi_test
 end
 
----Add meta definitions for deprecated API
-function M.api_meta(api)
-  ---@deprecated
-  ---@see nvim_tree.api.filter.toggle
-  function api.tree.toggle_enable_filters() end
-
-  ---@deprecated
-  ---@see nvim_tree.api.filter.git.ignored.toggle
-  function api.tree.toggle_gitignore_filter() end
-
-  ---@deprecated
-  ---@see nvim_tree.api.filter.git.clean.toggle
-  function api.tree.toggle_git_clean_filter() end
-
-  ---@deprecated
-  ---@see nvim_tree.api.filter.no_buffer.toggle
-  function api.tree.toggle_no_buffer_filter() end
-
-  ---@deprecated
-  ---@see nvim_tree.api.filter.custom.toggle
-  function api.tree.toggle_custom_filter() end
-
-  ---@deprecated
-  ---@see nvim_tree.api.filter.dotfiles.toggle
-  function api.tree.toggle_hidden_filter() end
-
-  ---@deprecated
-  ---@see nvim_tree.api.filter.no_bookmark.toggle
-  function api.tree.toggle_no_bookmark_filter() end
-
-  api.config = { mappings = {} }
-
-  ---@deprecated
-  ---@see nvim_tree.api.map.keymap.current
-  function api.config.mappings.get_keymap() end
-
-  ---@deprecated
-  ---@see nvim_tree.api.map.keymap.default
-  function api.config.mappings.get_keymap_default() end
-
-  ---@deprecated nvim_tree.api.map.on_attach.default
-  ---@see nvim_tree.api.map.on_attach.default
-  function api.config.mappings.default_on_attach(_) end
-
-  api.live_filter = {}
-
-  ---@deprecated
-  ---@see nvim_tree.api.filter.live.start
-  function api.live_filter.start() end
-
-  ---@deprecated
-  ---@see nvim_tree.api.filter.live.clear
-  function api.live_filter.clear() end
-
-  api.diagnostics = {}
-
-  ---@deprecated
-  ---@see nvim_tree.api.health.hi_test
-  function api.diagnostics.hi_test() end
-
-  return api
-end
-
 return M

From 23e59fdee7279fcc5825035d00ce21fcbace1752 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Tue, 27 Jan 2026 17:27:18 +1100
Subject: [PATCH 153/170] docs(#3088): mark deprecated api modules, use proper
 namespacing for deprecateds

---
 lua/nvim-tree/_meta/api/deprecated.lua | 25 ++++++++++++-------------
 lua/nvim-tree/_meta/api/tree.lua       |  1 -
 lua/nvim-tree/api.lua                  |  8 +++++---
 3 files changed, 17 insertions(+), 17 deletions(-)

diff --git a/lua/nvim-tree/_meta/api/deprecated.lua b/lua/nvim-tree/_meta/api/deprecated.lua
index 621bf2821d1..fdd4b88e85a 100644
--- a/lua/nvim-tree/_meta/api/deprecated.lua
+++ b/lua/nvim-tree/_meta/api/deprecated.lua
@@ -1,34 +1,33 @@
 ---@meta
-
 -- Deprecated top level API modules.
 -- Remember to add mappings in legacy.lua `api_map`
 
-local M = {}
+local nvim_tree = { api = {} }
 
-M.config = {}
+nvim_tree.api.config = {}
 
-M.config.mappings = {}
+nvim_tree.api.config.mappings = {}
 
 ---@deprecated use `nvim_tree.api.map.keymap.current()`
-function M.config.mappings.get_keymap() end
+function nvim_tree.api.config.mappings.get_keymap() end
 
 ---@deprecated use `nvim_tree.api.map.keymap.default()`
-function M.config.mappings.get_keymap_default() end
+function nvim_tree.api.config.mappings.get_keymap_default() end
 
 ---@deprecated use `nvim_tree.api.map.on_attach.default()`
-function M.config.mappings.default_on_attach(bufnr) end
+function nvim_tree.api.config.mappings.default_on_attach(bufnr) end
 
-M.live_filter = {}
+nvim_tree.api.live_filter = {}
 
 ---@deprecated use `nvim_tree.api.filter.live.start()`
-function M.live_filter.start() end
+function nvim_tree.api.live_filter.start() end
 
 ---@deprecated use `nvim_tree.api.filter.live.clear()`
-function M.live_filter.clear() end
+function nvim_tree.api.live_filter.clear() end
 
-M.diagnostics = {}
+nvim_tree.api.diagnostics = {}
 
 ---@deprecated use `nvim_tree.api.health.hi_test()`
-function M.diagnostics.hi_test() end
+function nvim_tree.api.diagnostics.hi_test() end
 
-return M
+return nvim_tree.api
diff --git a/lua/nvim-tree/_meta/api/tree.lua b/lua/nvim-tree/_meta/api/tree.lua
index c2ebe460bed..db77950c1ec 100644
--- a/lua/nvim-tree/_meta/api/tree.lua
+++ b/lua/nvim-tree/_meta/api/tree.lua
@@ -250,5 +250,4 @@ function nvim_tree.api.tree.toggle_hidden_filter() end
 ---@deprecated use `nvim_tree.api.filter.no_bookmark.toggle()`
 function nvim_tree.api.tree.toggle_no_bookmark_filter() end
 
-
 return nvim_tree.api.tree
diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index dc2661d2894..f1d533f6f5f 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -72,24 +72,26 @@
 --
 -- Load the (empty) meta definitions
 --
+local deprecated = require("nvim-tree._meta.api.deprecated")
 
 ---nvim-tree Public API
 ---@class nvim_tree.api
 ---@nodoc
 local api = {
   commands = require("nvim-tree._meta.api.commands"),
-  config = require("nvim-tree._meta.api.deprecated").config,
-  diagnostics = require("nvim-tree._meta.api.deprecated").diagnostics,
   events = require("nvim-tree._meta.api.events"),
   filter = require("nvim-tree._meta.api.filter"),
   fs = require("nvim-tree._meta.api.fs"),
   git = require("nvim-tree._meta.api._git"),
   health = require("nvim-tree._meta.api.health"),
-  live_filter = require("nvim-tree._meta.api.deprecated").live_filter,
   map = require("nvim-tree._meta.api.map"),
   marks = require("nvim-tree._meta.api.marks"),
   node = require("nvim-tree._meta.api.node"),
   tree = require("nvim-tree._meta.api.tree"),
+
+  config = deprecated.config, ---@deprecated
+  diagnostics = deprecated.diagnostics, ---@deprecated
+  live_filter = deprecated.live_filter, ---@deprecated
 }
 
 

From ff0184a26018837ede43e4637d084eeff9b35713 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Wed, 28 Jan 2026 18:14:35 +1100
Subject: [PATCH 154/170] docs(#3088): gen_vimdoc now uses full paths, requires
 a patch for a FIXME

---
 doc/nvim-tree-lua.txt                         |  51 +-------
 lua/nvim-tree/_meta/api/{_git.lua => git.lua} |   0
 lua/nvim-tree/api.lua                         |   2 +-
 scripts/gen_vimdoc.sh                         |   4 +-
 scripts/gen_vimdoc_config.lua                 | 122 ++++++++----------
 5 files changed, 55 insertions(+), 124 deletions(-)
 rename lua/nvim-tree/_meta/api/{_git.lua => git.lua} (100%)

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 1fedbd33e12..c852f2c1c18 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -1231,8 +1231,6 @@ Config                                                      *nvim-tree-config*
       • {log}?                                 (`nvim_tree.config.log`)
                                                |nvim_tree.config.log|
 
-
-
 ==============================================================================
 Config: sort                                           *nvim-tree-config-sort*
 
@@ -1271,8 +1269,6 @@ Config: sort                                           *nvim-tree-config-sort*
                           folders. Has no effect when {sorter} is a function.
                           Overrides {folders_first}.
 
-
-
 ==============================================================================
 Config: view                                           *nvim-tree-config-view*
 
@@ -1357,8 +1353,6 @@ Config: view                                           *nvim-tree-config-view*
       • {padding}?         (`nvim_tree.config.view.width.spec`, default: `1`)
                            Extra padding to the right.
 
-
-
 ==============================================================================
 Config: renderer                                   *nvim-tree-config-renderer*
 
@@ -1533,8 +1527,6 @@ Config: renderer                                   *nvim-tree-config-renderer*
                           • {bottom}? (`string`) (default: `"─"`)
                           • {none}? (`string`) (default: `" "`)
 
-
-
 ==============================================================================
 Config: hijack_directories               *nvim-tree-config-hijack-directories*
 
@@ -1551,8 +1543,6 @@ Config: hijack_directories               *nvim-tree-config-hijack-directories*
       • {auto_open}?  (`boolean`, default: `true`) Open if the tree was
                       previously closed.
 
-
-
 ==============================================================================
 Config: update_focused_file             *nvim-tree-config-update-focused-file*
 
@@ -1583,8 +1573,6 @@ Config: update_focused_file             *nvim-tree-config-update-focused-file*
                         tree if the file isn't found under the current root
                         directory.
 
-
-
 ==============================================================================
 Config: system_open                             *nvim-tree-config-system-open*
 
@@ -1607,8 +1595,6 @@ Config: system_open                             *nvim-tree-config-system-open*
                  windows) Optional argument list. Leave empty for OS specific
                  default.
 
-
-
 ==============================================================================
 Config: git                                             *nvim-tree-config-git*
 
@@ -1641,8 +1627,6 @@ Config: git                                             *nvim-tree-config-git*
       • {cygwin_support}?     (`boolean`, default: `false`) Use `cygpath` if
                               available to resolve paths for git.
 
-
-
 ==============================================================================
 Config: diagnostics                             *nvim-tree-config-diagnostics*
 
@@ -1675,8 +1659,6 @@ Config: diagnostics                             *nvim-tree-config-diagnostics*
                               • {warning}? (`string`) (default: `""` )
                               • {error}? (`string`) (default: `""` )
 
-
-
 ==============================================================================
 Config: modified                                   *nvim-tree-config-modified*
 
@@ -1697,8 +1679,6 @@ Config: modified                                   *nvim-tree-config-modified*
                               indication on open directories. Requires
                               {show_on_dirs}.
 
-
-
 ==============================================================================
 Config: filters                                     *nvim-tree-config-filters*
 
@@ -1752,8 +1732,6 @@ Config: filters                                     *nvim-tree-config-filters*
                         (default: `{}`)
       • {exclude}?      (`string[]`) (default: `{}`)
 
-
-
 ==============================================================================
 Config: live_filter                             *nvim-tree-config-live-filter*
 
@@ -1770,8 +1748,6 @@ Config: live_filter                             *nvim-tree-config-live-filter*
       • {always_show_folders}?  (`boolean`, default: `true`) Whether to filter
                                 folders or not.
 
-
-
 ==============================================================================
 Config: filesystem_watchers             *nvim-tree-config-filesystem-watchers*
 
@@ -1805,8 +1781,6 @@ Config: filesystem_watchers             *nvim-tree-config-filesystem-watchers*
                            directory after {max_events} consecutive events
                            with an interval < {debounce_delay}.
 
-
-
 ==============================================================================
 Config: actions                                     *nvim-tree-config-actions*
 
@@ -1928,8 +1902,6 @@ Config: actions                                     *nvim-tree-config-actions*
                          displays a file when removing that file from the
                          tree.
 
-
-
 ==============================================================================
 Config: trash                                         *nvim-tree-config-trash*
 
@@ -1943,8 +1915,6 @@ Config: trash                                         *nvim-tree-config-trash*
     Fields: ~
       • {cmd}?  (`string`) (default: `"gio trash"` or `"trash"`)
 
-
-
 ==============================================================================
 Config: tab                                             *nvim-tree-config-tab*
 
@@ -1964,8 +1934,6 @@ Config: tab                                             *nvim-tree-config-tab*
       • {ignore}?  (`string[]`, default: `{}`) List of filetypes or buffer
                    names on new tab that will prevent `open` and `close`
 
-
-
 ==============================================================================
 Config: notify                                       *nvim-tree-config-notify*
 
@@ -1983,8 +1951,6 @@ Config: notify                                       *nvim-tree-config-notify*
       • {absolute_path}?  (`boolean`, default: `true`) Use absolute paths in
                           FS action notifications, otherwise item names.
 
-
-
 ==============================================================================
 Config: bookmarks                                 *nvim-tree-config-bookmarks*
 
@@ -1997,8 +1963,6 @@ Config: bookmarks                                 *nvim-tree-config-bookmarks*
     Fields: ~
       • {persist}?  (`boolean|string`) (default: `false`)
 
-
-
 ==============================================================================
 Config: help                                           *nvim-tree-config-help*
 
@@ -2007,8 +1971,6 @@ Config: help                                           *nvim-tree-config-help*
     Fields: ~
       • {sort_by}?  (`"key"|"desc"`, default: `"key"`) Alphabetically.
 
-
-
 ==============================================================================
 Config: ui                                               *nvim-tree-config-ui*
 
@@ -2027,8 +1989,6 @@ Config: ui                                               *nvim-tree-config-ui*
       • {default_yes}?  (`boolean`, default: `false`) If `true` the prompt
                         will be `Y/n`, otherwise `y/N`
 
-
-
 ==============================================================================
 Config: experimental                           *nvim-tree-config-experimental*
 
@@ -2038,8 +1998,6 @@ Config: experimental                           *nvim-tree-config-experimental*
     In the event of a problem please disable the experiment and raise an
     issue.
 
-
-
 ==============================================================================
 Config: log                                             *nvim-tree-config-log*
 
@@ -2074,8 +2032,6 @@ Config: log                                             *nvim-tree-config-log*
                         |nvim_tree.config.filesystem_watchers| processing,
                         verbose.
 
-
-
 ==============================================================================
 Config: Default                                     *nvim-tree-config-default*
 
@@ -2367,8 +2323,6 @@ Following is the default configuration, see |nvim_tree.config| for details. >lua
     }
 <
 
-
-
 ==============================================================================
 API                                                            *nvim-tree-api*
 
@@ -2444,8 +2398,6 @@ e.g. the following are functionally identical: >lua
       • {dir}?   (`table<"direct"|"indirect", nvim_tree.git.XY[]>`) direct
                  inclusive-or indirect status
 
-
-
 ==============================================================================
 API: commands                                         *nvim-tree-api-commands*
 
@@ -2618,8 +2570,7 @@ trash({node})                                       *nvim_tree.api.fs.trash()*
 ==============================================================================
 API: git                                                   *nvim-tree-api-git*
 
-                               *nvim_tree.api._git.nvim_tree.api.git.reload()*
-nvim_tree.api.git.reload()
+reload()                                          *nvim_tree.api.git.reload()*
     Update the git status of the entire tree.
 
 
diff --git a/lua/nvim-tree/_meta/api/_git.lua b/lua/nvim-tree/_meta/api/git.lua
similarity index 100%
rename from lua/nvim-tree/_meta/api/_git.lua
rename to lua/nvim-tree/_meta/api/git.lua
diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index f1d533f6f5f..e88b19d1f0a 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -82,7 +82,7 @@ local api = {
   events = require("nvim-tree._meta.api.events"),
   filter = require("nvim-tree._meta.api.filter"),
   fs = require("nvim-tree._meta.api.fs"),
-  git = require("nvim-tree._meta.api._git"),
+  git = require("nvim-tree._meta.api.git"),
   health = require("nvim-tree._meta.api.health"),
   map = require("nvim-tree._meta.api.map"),
   marks = require("nvim-tree._meta.api.marks"),
diff --git a/scripts/gen_vimdoc.sh b/scripts/gen_vimdoc.sh
index e9bb69dda88..2b46bd71585 100755
--- a/scripts/gen_vimdoc.sh
+++ b/scripts/gen_vimdoc.sh
@@ -59,8 +59,8 @@ export LUA_PATH="${DIR_NVIM_SRC}/src/?.lua;${DIR_NVT}/scripts/?.lua"
 
 # gen_vimdoc.lua doesn't like dashes in lua module names
 #   -> use nvim_tree instead of nvim-tree
-mkdir -pv "${DIR_WORK}/lua"
-ln -sv "${DIR_NVT}/lua/nvim-tree" "${DIR_WORK}/lua/nvim_tree"
+mkdir -pv "${DIR_WORK}/runtime/lua"
+ln -sv "${DIR_NVT}/lua/nvim-tree" "${DIR_WORK}/runtime/lua/nvim_tree"
 
 # generate
 cd "${DIR_WORK}" && pwd
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index 691fe69bde8..05303980449 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -6,64 +6,55 @@
 ---@field helptag string must be globally unique
 ---@field section string arbitrary
 ---@field path string relative to root
----@field file_name? string generated from path
----@field name? string override generated name
----@field append_only? boolean follows previous section
 
 ---Help txt is deleted from first tag down and generated content is appended.
+local pre = "runtime/lua/nvim_tree/"
 ---@type Src[]
 local srcs = {
-  { helptag = "nvim-tree-config",                     section = "Config",                      path = "./lua/nvim_tree/_meta/config.lua", },
-  { helptag = "nvim-tree-config-sort",                section = "Config: sort",                path = "./lua/nvim_tree/_meta/config/sort.lua", },
-  { helptag = "nvim-tree-config-view",                section = "Config: view",                path = "./lua/nvim_tree/_meta/config/view.lua", },
-  { helptag = "nvim-tree-config-renderer",            section = "Config: renderer",            path = "./lua/nvim_tree/_meta/config/renderer.lua", },
-  { helptag = "nvim-tree-config-hijack-directories",  section = "Config: hijack_directories",  path = "./lua/nvim_tree/_meta/config/hijack_directories.lua", },
-  { helptag = "nvim-tree-config-update-focused-file", section = "Config: update_focused_file", path = "./lua/nvim_tree/_meta/config/update_focused_file.lua", },
-  { helptag = "nvim-tree-config-system-open",         section = "Config: system_open",         path = "./lua/nvim_tree/_meta/config/system_open.lua", },
-  { helptag = "nvim-tree-config-git",                 section = "Config: git",                 path = "./lua/nvim_tree/_meta/config/git.lua", },
-  { helptag = "nvim-tree-config-diagnostics",         section = "Config: diagnostics",         path = "./lua/nvim_tree/_meta/config/diagnostics.lua", },
-  { helptag = "nvim-tree-config-modified",            section = "Config: modified",            path = "./lua/nvim_tree/_meta/config/modified.lua", },
-  { helptag = "nvim-tree-config-filters",             section = "Config: filters",             path = "./lua/nvim_tree/_meta/config/filters.lua", },
-  { helptag = "nvim-tree-config-live-filter",         section = "Config: live_filter",         path = "./lua/nvim_tree/_meta/config/live_filter.lua", },
-  { helptag = "nvim-tree-config-filesystem-watchers", section = "Config: filesystem_watchers", path = "./lua/nvim_tree/_meta/config/filesystem_watchers.lua", },
-  { helptag = "nvim-tree-config-actions",             section = "Config: actions",             path = "./lua/nvim_tree/_meta/config/actions.lua", },
-  { helptag = "nvim-tree-config-trash",               section = "Config: trash",               path = "./lua/nvim_tree/_meta/config/trash.lua", },
-  { helptag = "nvim-tree-config-tab",                 section = "Config: tab",                 path = "./lua/nvim_tree/_meta/config/tab.lua", },
-  { helptag = "nvim-tree-config-notify",              section = "Config: notify",              path = "./lua/nvim_tree/_meta/config/notify.lua", },
-  { helptag = "nvim-tree-config-bookmarks",           section = "Config: bookmarks",           path = "./lua/nvim_tree/_meta/config/bookmarks.lua", },
-  { helptag = "nvim-tree-config-help",                section = "Config: help",                path = "./lua/nvim_tree/_meta/config/help.lua", },
-  { helptag = "nvim-tree-config-ui",                  section = "Config: ui",                  path = "./lua/nvim_tree/_meta/config/ui.lua",                  name = "UI", },
-  { helptag = "nvim-tree-config-experimental",        section = "Config: experimental",        path = "./lua/nvim_tree/_meta/config/experimental.lua", },
-  { helptag = "nvim-tree-config-log",                 section = "Config: log",                 path = "./lua/nvim_tree/_meta/config/log.lua", },
-
-  { helptag = "nvim-tree-config-default",             section = "Config: Default",             path = "./lua/nvim_tree/_meta/config/default.lua", },
-
-  { helptag = "nvim-tree-api",                        section = "API",                         path = "./lua/nvim_tree/api.lua", },
-
-  { helptag = "nvim-tree-api-commands",               section = "API: commands",               path = "./lua/nvim_tree/_meta/api/commands.lua", },
-  { helptag = "nvim-tree-api-events",                 section = "API: events",                 path = "./lua/nvim_tree/_meta/api/events.lua", },
-  { helptag = "nvim-tree-api-filter",                 section = "API: filter",                 path = "./lua/nvim_tree/_meta/api/filter.lua", },
-  { helptag = "nvim-tree-api-fs",                     section = "API: fs",                     path = "./lua/nvim_tree/_meta/api/fs.lua", },
-  -- TODO #3088 come up with a solution to avoid filename clashes
-  { helptag = "nvim-tree-api-git",                    section = "API: git",                    path = "./lua/nvim_tree/_meta/api/_git.lua", },
-  { helptag = "nvim-tree-api-health",                 section = "API: health",                 path = "./lua/nvim_tree/_meta/api/health.lua", },
-  { helptag = "nvim-tree-api-map",                    section = "API: map",                    path = "./lua/nvim_tree/_meta/api/map.lua", },
-  { helptag = "nvim-tree-api-marks",                  section = "API: marks",                  path = "./lua/nvim_tree/_meta/api/marks.lua", },
-  { helptag = "nvim-tree-api-node",                   section = "API: node",                   path = "./lua/nvim_tree/_meta/api/node.lua", },
-  { helptag = "nvim-tree-api-tree",                   section = "API: tree",                   path = "./lua/nvim_tree/_meta/api/tree.lua", },
+  { helptag = "nvim-tree-config",                     section = "Config",                      path = pre .. "_meta/config.lua", },
+  { helptag = "nvim-tree-config-sort",                section = "Config: sort",                path = pre .. "_meta/config/sort.lua", },
+  { helptag = "nvim-tree-config-view",                section = "Config: view",                path = pre .. "_meta/config/view.lua", },
+  { helptag = "nvim-tree-config-renderer",            section = "Config: renderer",            path = pre .. "_meta/config/renderer.lua", },
+  { helptag = "nvim-tree-config-hijack-directories",  section = "Config: hijack_directories",  path = pre .. "_meta/config/hijack_directories.lua", },
+  { helptag = "nvim-tree-config-update-focused-file", section = "Config: update_focused_file", path = pre .. "_meta/config/update_focused_file.lua", },
+  { helptag = "nvim-tree-config-system-open",         section = "Config: system_open",         path = pre .. "_meta/config/system_open.lua", },
+  { helptag = "nvim-tree-config-git",                 section = "Config: git",                 path = pre .. "_meta/config/git.lua", },
+  { helptag = "nvim-tree-config-diagnostics",         section = "Config: diagnostics",         path = pre .. "_meta/config/diagnostics.lua", },
+  { helptag = "nvim-tree-config-modified",            section = "Config: modified",            path = pre .. "_meta/config/modified.lua", },
+  { helptag = "nvim-tree-config-filters",             section = "Config: filters",             path = pre .. "_meta/config/filters.lua", },
+  { helptag = "nvim-tree-config-live-filter",         section = "Config: live_filter",         path = pre .. "_meta/config/live_filter.lua", },
+  { helptag = "nvim-tree-config-filesystem-watchers", section = "Config: filesystem_watchers", path = pre .. "_meta/config/filesystem_watchers.lua", },
+  { helptag = "nvim-tree-config-actions",             section = "Config: actions",             path = pre .. "_meta/config/actions.lua", },
+  { helptag = "nvim-tree-config-trash",               section = "Config: trash",               path = pre .. "_meta/config/trash.lua", },
+  { helptag = "nvim-tree-config-tab",                 section = "Config: tab",                 path = pre .. "_meta/config/tab.lua", },
+  { helptag = "nvim-tree-config-notify",              section = "Config: notify",              path = pre .. "_meta/config/notify.lua", },
+  { helptag = "nvim-tree-config-bookmarks",           section = "Config: bookmarks",           path = pre .. "_meta/config/bookmarks.lua", },
+  { helptag = "nvim-tree-config-help",                section = "Config: help",                path = pre .. "_meta/config/help.lua", },
+  { helptag = "nvim-tree-config-ui",                  section = "Config: ui",                  path = pre .. "_meta/config/ui.lua", },
+  { helptag = "nvim-tree-config-experimental",        section = "Config: experimental",        path = pre .. "_meta/config/experimental.lua", },
+  { helptag = "nvim-tree-config-log",                 section = "Config: log",                 path = pre .. "_meta/config/log.lua", },
+
+  { helptag = "nvim-tree-config-default",             section = "Config: Default",             path = pre .. "_meta/config/default.lua", },
+
+  { helptag = "nvim-tree-api",                        section = "API",                         path = pre .. "api.lua", },
+
+  { helptag = "nvim-tree-api-commands",               section = "API: commands",               path = pre .. "_meta/api/commands.lua", },
+  { helptag = "nvim-tree-api-events",                 section = "API: events",                 path = pre .. "_meta/api/events.lua", },
+  { helptag = "nvim-tree-api-filter",                 section = "API: filter",                 path = pre .. "_meta/api/filter.lua", },
+  { helptag = "nvim-tree-api-fs",                     section = "API: fs",                     path = pre .. "_meta/api/fs.lua", },
+  { helptag = "nvim-tree-api-git",                    section = "API: git",                    path = pre .. "_meta/api/git.lua", },
+  { helptag = "nvim-tree-api-health",                 section = "API: health",                 path = pre .. "_meta/api/health.lua", },
+  { helptag = "nvim-tree-api-map",                    section = "API: map",                    path = pre .. "_meta/api/map.lua", },
+  { helptag = "nvim-tree-api-marks",                  section = "API: marks",                  path = pre .. "_meta/api/marks.lua", },
+  { helptag = "nvim-tree-api-node",                   section = "API: node",                   path = pre .. "_meta/api/node.lua", },
+  { helptag = "nvim-tree-api-tree",                   section = "API: tree",                   path = pre .. "_meta/api/tree.lua", },
 }
 
--- hydrate file names
-for _, m in ipairs(srcs) do
-  m.file_name = vim.fn.fnamemodify(m.path, ":t")
-end
-
---name is derived by the generator as the file name with the first letter capitalised
---except for some like UI which are overridden in srcs
+--name is derived by the generator as the path with the first letter capitalised and the extension stripped
 ---@type table
 local srcs_by_name = {}
 for _, m in ipairs(srcs) do
-  local name = m.name or m.file_name:gsub(".lua", ""):gsub("^%l", string.upper)
+  local name = m.path:gsub("^%l", string.upper):gsub(".lua$", "")
   srcs_by_name[name] = m
 end
 
@@ -72,46 +63,35 @@ local config = {
   all = {
     filename = "nvim-tree-lua.txt",
 
-    -- source file name is used to set order
-    section_order = vim.tbl_map(function(src) return src.file_name end, srcs),
+    -- path, ordered
+    section_order = vim.tbl_map(function(src) return src.path end, srcs),
 
-    -- path
+    -- path, unordered
     files = vim.tbl_map(function(src) return src.path end, srcs),
 
-    append_only = vim.tbl_map(function(src) return src.append_only and src.file_name or nil end, srcs),
-
+    -- lookup by name
     section_fmt = function(name)
-      print(string.format("section_fmt name=%s", name))
-      return srcs_by_name[name] and srcs_by_name[name].section or
-        error(string.format("unknown name %s passed to section_fmt", name))
+      return srcs_by_name[name] and srcs_by_name[name].section or error(string.format("\nUnknown name passed to section_fmt: '%s'", name))
     end,
 
+    -- lookup by name
     helptag_fmt = function(name)
-      print(string.format("helptag_fmt name=%s", name))
-      return srcs_by_name[name] and srcs_by_name[name].helptag or
-        error(string.format("unknown name %s passed to helptag_fmt", name))
+      return srcs_by_name[name] and srcs_by_name[name].helptag or error(string.format("\nUnknown name passed to helptag_fmt: '%s'", name))
     end,
 
     -- optional, no default xform
     fn_xform = function(fun)
-      print(string.format("fn_xform fun=%s", vim.inspect(fun)))
-
       if (fun.module) then
         -- generator doesn't strip meta
         -- also cascades into fn_helptag_fmt
         local module = fun.module:gsub("._meta", "", 1)
 
-        -- remove the API prefix from the left aligned function name
+        -- remove the API module from the left aligned function name
         -- this will cascade into fn_helptag_fmt, which will apply the module prefix anyway
-
-        -- TODO #3088 come up with a solution to avoid filename clashes
-        ---@diagnostic disable-next-line: unused-local
         local name, replaced = fun.name:gsub("^" .. module .. "%.", "", 1)
-        -- if (replaced ~= 1) then
-        --   error(string.format("function name does not start with module: %s", vim.inspect(fun)))
-        -- end
-
-        print(string.format("fn_xform name: %s -> %s", fun.name, name))
+        if (replaced ~= 1) then
+          error(string.format("\nFunction name does not start with\nmodule='%s'\nfun=%s", module, vim.inspect(fun)))
+        end
 
         fun.module = module
         fun.name = name

From ebb99093d2e2214abd13fc0dd3cbd4ed901ec254 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Wed, 28 Jan 2026 18:21:20 +1100
Subject: [PATCH 155/170] docs(#3088): add vim_gendoc patches

---
 doc/nvim-tree-lua.txt                | 48 ++++++++++++++++++++++++++++
 scripts/gen_vimdoc.lua.0.11.patch    | 14 ++++++++
 scripts/gen_vimdoc.lua.nightly.patch | 16 ++++++++++
 3 files changed, 78 insertions(+)
 create mode 100644 scripts/gen_vimdoc.lua.0.11.patch
 create mode 100644 scripts/gen_vimdoc.lua.nightly.patch

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index c852f2c1c18..7b3d3eb07ab 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -1231,6 +1231,8 @@ Config                                                      *nvim-tree-config*
       • {log}?                                 (`nvim_tree.config.log`)
                                                |nvim_tree.config.log|
 
+
+
 ==============================================================================
 Config: sort                                           *nvim-tree-config-sort*
 
@@ -1269,6 +1271,8 @@ Config: sort                                           *nvim-tree-config-sort*
                           folders. Has no effect when {sorter} is a function.
                           Overrides {folders_first}.
 
+
+
 ==============================================================================
 Config: view                                           *nvim-tree-config-view*
 
@@ -1353,6 +1357,8 @@ Config: view                                           *nvim-tree-config-view*
       • {padding}?         (`nvim_tree.config.view.width.spec`, default: `1`)
                            Extra padding to the right.
 
+
+
 ==============================================================================
 Config: renderer                                   *nvim-tree-config-renderer*
 
@@ -1527,6 +1533,8 @@ Config: renderer                                   *nvim-tree-config-renderer*
                           • {bottom}? (`string`) (default: `"─"`)
                           • {none}? (`string`) (default: `" "`)
 
+
+
 ==============================================================================
 Config: hijack_directories               *nvim-tree-config-hijack-directories*
 
@@ -1543,6 +1551,8 @@ Config: hijack_directories               *nvim-tree-config-hijack-directories*
       • {auto_open}?  (`boolean`, default: `true`) Open if the tree was
                       previously closed.
 
+
+
 ==============================================================================
 Config: update_focused_file             *nvim-tree-config-update-focused-file*
 
@@ -1573,6 +1583,8 @@ Config: update_focused_file             *nvim-tree-config-update-focused-file*
                         tree if the file isn't found under the current root
                         directory.
 
+
+
 ==============================================================================
 Config: system_open                             *nvim-tree-config-system-open*
 
@@ -1595,6 +1607,8 @@ Config: system_open                             *nvim-tree-config-system-open*
                  windows) Optional argument list. Leave empty for OS specific
                  default.
 
+
+
 ==============================================================================
 Config: git                                             *nvim-tree-config-git*
 
@@ -1627,6 +1641,8 @@ Config: git                                             *nvim-tree-config-git*
       • {cygwin_support}?     (`boolean`, default: `false`) Use `cygpath` if
                               available to resolve paths for git.
 
+
+
 ==============================================================================
 Config: diagnostics                             *nvim-tree-config-diagnostics*
 
@@ -1659,6 +1675,8 @@ Config: diagnostics                             *nvim-tree-config-diagnostics*
                               • {warning}? (`string`) (default: `""` )
                               • {error}? (`string`) (default: `""` )
 
+
+
 ==============================================================================
 Config: modified                                   *nvim-tree-config-modified*
 
@@ -1679,6 +1697,8 @@ Config: modified                                   *nvim-tree-config-modified*
                               indication on open directories. Requires
                               {show_on_dirs}.
 
+
+
 ==============================================================================
 Config: filters                                     *nvim-tree-config-filters*
 
@@ -1732,6 +1752,8 @@ Config: filters                                     *nvim-tree-config-filters*
                         (default: `{}`)
       • {exclude}?      (`string[]`) (default: `{}`)
 
+
+
 ==============================================================================
 Config: live_filter                             *nvim-tree-config-live-filter*
 
@@ -1748,6 +1770,8 @@ Config: live_filter                             *nvim-tree-config-live-filter*
       • {always_show_folders}?  (`boolean`, default: `true`) Whether to filter
                                 folders or not.
 
+
+
 ==============================================================================
 Config: filesystem_watchers             *nvim-tree-config-filesystem-watchers*
 
@@ -1781,6 +1805,8 @@ Config: filesystem_watchers             *nvim-tree-config-filesystem-watchers*
                            directory after {max_events} consecutive events
                            with an interval < {debounce_delay}.
 
+
+
 ==============================================================================
 Config: actions                                     *nvim-tree-config-actions*
 
@@ -1902,6 +1928,8 @@ Config: actions                                     *nvim-tree-config-actions*
                          displays a file when removing that file from the
                          tree.
 
+
+
 ==============================================================================
 Config: trash                                         *nvim-tree-config-trash*
 
@@ -1915,6 +1943,8 @@ Config: trash                                         *nvim-tree-config-trash*
     Fields: ~
       • {cmd}?  (`string`) (default: `"gio trash"` or `"trash"`)
 
+
+
 ==============================================================================
 Config: tab                                             *nvim-tree-config-tab*
 
@@ -1934,6 +1964,8 @@ Config: tab                                             *nvim-tree-config-tab*
       • {ignore}?  (`string[]`, default: `{}`) List of filetypes or buffer
                    names on new tab that will prevent `open` and `close`
 
+
+
 ==============================================================================
 Config: notify                                       *nvim-tree-config-notify*
 
@@ -1951,6 +1983,8 @@ Config: notify                                       *nvim-tree-config-notify*
       • {absolute_path}?  (`boolean`, default: `true`) Use absolute paths in
                           FS action notifications, otherwise item names.
 
+
+
 ==============================================================================
 Config: bookmarks                                 *nvim-tree-config-bookmarks*
 
@@ -1963,6 +1997,8 @@ Config: bookmarks                                 *nvim-tree-config-bookmarks*
     Fields: ~
       • {persist}?  (`boolean|string`) (default: `false`)
 
+
+
 ==============================================================================
 Config: help                                           *nvim-tree-config-help*
 
@@ -1971,6 +2007,8 @@ Config: help                                           *nvim-tree-config-help*
     Fields: ~
       • {sort_by}?  (`"key"|"desc"`, default: `"key"`) Alphabetically.
 
+
+
 ==============================================================================
 Config: ui                                               *nvim-tree-config-ui*
 
@@ -1989,6 +2027,8 @@ Config: ui                                               *nvim-tree-config-ui*
       • {default_yes}?  (`boolean`, default: `false`) If `true` the prompt
                         will be `Y/n`, otherwise `y/N`
 
+
+
 ==============================================================================
 Config: experimental                           *nvim-tree-config-experimental*
 
@@ -1998,6 +2038,8 @@ Config: experimental                           *nvim-tree-config-experimental*
     In the event of a problem please disable the experiment and raise an
     issue.
 
+
+
 ==============================================================================
 Config: log                                             *nvim-tree-config-log*
 
@@ -2032,6 +2074,8 @@ Config: log                                             *nvim-tree-config-log*
                         |nvim_tree.config.filesystem_watchers| processing,
                         verbose.
 
+
+
 ==============================================================================
 Config: Default                                     *nvim-tree-config-default*
 
@@ -2323,6 +2367,8 @@ Following is the default configuration, see |nvim_tree.config| for details. >lua
     }
 <
 
+
+
 ==============================================================================
 API                                                            *nvim-tree-api*
 
@@ -2398,6 +2444,8 @@ e.g. the following are functionally identical: >lua
       • {dir}?   (`table<"direct"|"indirect", nvim_tree.git.XY[]>`) direct
                  inclusive-or indirect status
 
+
+
 ==============================================================================
 API: commands                                         *nvim-tree-api-commands*
 
diff --git a/scripts/gen_vimdoc.lua.0.11.patch b/scripts/gen_vimdoc.lua.0.11.patch
new file mode 100644
index 00000000000..2d4dbac15c9
--- /dev/null
+++ b/scripts/gen_vimdoc.lua.0.11.patch
@@ -0,0 +1,14 @@
+diff --git a/src/gen/gen_vimdoc.lua b/src/gen/gen_vimdoc.lua
+index 68912cf0b5..f3990cd9a6 100755
+--- a/src/gen/gen_vimdoc.lua
++++ b/src/gen/gen_vimdoc.lua
+@@ -1003,8 +1003,7 @@ local function gen_target(cfg)
+       end
+     end
+     -- FIXME: Using f_base will confuse `_meta/protocol.lua` with `protocol.lua`
+-    local f_base = vim.fs.basename(f)
+-    sections[f_base] = make_section(f_base, cfg, briefs_txt, funs_txt)
++    sections[f] = make_section(f, cfg, briefs_txt, funs_txt)
+   end
+ 
+   local first_section_tag = sections[cfg.section_order[1]].help_tag
diff --git a/scripts/gen_vimdoc.lua.nightly.patch b/scripts/gen_vimdoc.lua.nightly.patch
new file mode 100644
index 00000000000..3f7152662bb
--- /dev/null
+++ b/scripts/gen_vimdoc.lua.nightly.patch
@@ -0,0 +1,16 @@
+diff --git a/src/gen/gen_vimdoc.lua b/src/gen/gen_vimdoc.lua
+index e90158d502..df09bc37ee 100755
+--- a/src/gen/gen_vimdoc.lua
++++ b/src/gen/gen_vimdoc.lua
+@@ -1084,9 +1084,8 @@ local function gen_target(cfg)
+     print('    Processing file:', f)
+ 
+     -- FIXME: Using f_base will confuse `_meta/protocol.lua` with `protocol.lua`
+-    local f_base = vim.fs.basename(f)
+-    sections[f_base] = make_section(
+-      f_base,
++    sections[f] = make_section(
++      f,
+       cfg,
+       briefs,
+       render_funs(funs, all_classes, cfg),

From 784632264332028ee9c514bd6df06358b0521169 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 29 Jan 2026 10:12:39 +1100
Subject: [PATCH 156/170] Revert "docs(#3088): add vim_gendoc patches"

This reverts commit ebb99093d2e2214abd13fc0dd3cbd4ed901ec254.
---
 doc/nvim-tree-lua.txt                | 48 ----------------------------
 scripts/gen_vimdoc.lua.0.11.patch    | 14 --------
 scripts/gen_vimdoc.lua.nightly.patch | 16 ----------
 3 files changed, 78 deletions(-)
 delete mode 100644 scripts/gen_vimdoc.lua.0.11.patch
 delete mode 100644 scripts/gen_vimdoc.lua.nightly.patch

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 7b3d3eb07ab..c852f2c1c18 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -1231,8 +1231,6 @@ Config                                                      *nvim-tree-config*
       • {log}?                                 (`nvim_tree.config.log`)
                                                |nvim_tree.config.log|
 
-
-
 ==============================================================================
 Config: sort                                           *nvim-tree-config-sort*
 
@@ -1271,8 +1269,6 @@ Config: sort                                           *nvim-tree-config-sort*
                           folders. Has no effect when {sorter} is a function.
                           Overrides {folders_first}.
 
-
-
 ==============================================================================
 Config: view                                           *nvim-tree-config-view*
 
@@ -1357,8 +1353,6 @@ Config: view                                           *nvim-tree-config-view*
       • {padding}?         (`nvim_tree.config.view.width.spec`, default: `1`)
                            Extra padding to the right.
 
-
-
 ==============================================================================
 Config: renderer                                   *nvim-tree-config-renderer*
 
@@ -1533,8 +1527,6 @@ Config: renderer                                   *nvim-tree-config-renderer*
                           • {bottom}? (`string`) (default: `"─"`)
                           • {none}? (`string`) (default: `" "`)
 
-
-
 ==============================================================================
 Config: hijack_directories               *nvim-tree-config-hijack-directories*
 
@@ -1551,8 +1543,6 @@ Config: hijack_directories               *nvim-tree-config-hijack-directories*
       • {auto_open}?  (`boolean`, default: `true`) Open if the tree was
                       previously closed.
 
-
-
 ==============================================================================
 Config: update_focused_file             *nvim-tree-config-update-focused-file*
 
@@ -1583,8 +1573,6 @@ Config: update_focused_file             *nvim-tree-config-update-focused-file*
                         tree if the file isn't found under the current root
                         directory.
 
-
-
 ==============================================================================
 Config: system_open                             *nvim-tree-config-system-open*
 
@@ -1607,8 +1595,6 @@ Config: system_open                             *nvim-tree-config-system-open*
                  windows) Optional argument list. Leave empty for OS specific
                  default.
 
-
-
 ==============================================================================
 Config: git                                             *nvim-tree-config-git*
 
@@ -1641,8 +1627,6 @@ Config: git                                             *nvim-tree-config-git*
       • {cygwin_support}?     (`boolean`, default: `false`) Use `cygpath` if
                               available to resolve paths for git.
 
-
-
 ==============================================================================
 Config: diagnostics                             *nvim-tree-config-diagnostics*
 
@@ -1675,8 +1659,6 @@ Config: diagnostics                             *nvim-tree-config-diagnostics*
                               • {warning}? (`string`) (default: `""` )
                               • {error}? (`string`) (default: `""` )
 
-
-
 ==============================================================================
 Config: modified                                   *nvim-tree-config-modified*
 
@@ -1697,8 +1679,6 @@ Config: modified                                   *nvim-tree-config-modified*
                               indication on open directories. Requires
                               {show_on_dirs}.
 
-
-
 ==============================================================================
 Config: filters                                     *nvim-tree-config-filters*
 
@@ -1752,8 +1732,6 @@ Config: filters                                     *nvim-tree-config-filters*
                         (default: `{}`)
       • {exclude}?      (`string[]`) (default: `{}`)
 
-
-
 ==============================================================================
 Config: live_filter                             *nvim-tree-config-live-filter*
 
@@ -1770,8 +1748,6 @@ Config: live_filter                             *nvim-tree-config-live-filter*
       • {always_show_folders}?  (`boolean`, default: `true`) Whether to filter
                                 folders or not.
 
-
-
 ==============================================================================
 Config: filesystem_watchers             *nvim-tree-config-filesystem-watchers*
 
@@ -1805,8 +1781,6 @@ Config: filesystem_watchers             *nvim-tree-config-filesystem-watchers*
                            directory after {max_events} consecutive events
                            with an interval < {debounce_delay}.
 
-
-
 ==============================================================================
 Config: actions                                     *nvim-tree-config-actions*
 
@@ -1928,8 +1902,6 @@ Config: actions                                     *nvim-tree-config-actions*
                          displays a file when removing that file from the
                          tree.
 
-
-
 ==============================================================================
 Config: trash                                         *nvim-tree-config-trash*
 
@@ -1943,8 +1915,6 @@ Config: trash                                         *nvim-tree-config-trash*
     Fields: ~
       • {cmd}?  (`string`) (default: `"gio trash"` or `"trash"`)
 
-
-
 ==============================================================================
 Config: tab                                             *nvim-tree-config-tab*
 
@@ -1964,8 +1934,6 @@ Config: tab                                             *nvim-tree-config-tab*
       • {ignore}?  (`string[]`, default: `{}`) List of filetypes or buffer
                    names on new tab that will prevent `open` and `close`
 
-
-
 ==============================================================================
 Config: notify                                       *nvim-tree-config-notify*
 
@@ -1983,8 +1951,6 @@ Config: notify                                       *nvim-tree-config-notify*
       • {absolute_path}?  (`boolean`, default: `true`) Use absolute paths in
                           FS action notifications, otherwise item names.
 
-
-
 ==============================================================================
 Config: bookmarks                                 *nvim-tree-config-bookmarks*
 
@@ -1997,8 +1963,6 @@ Config: bookmarks                                 *nvim-tree-config-bookmarks*
     Fields: ~
       • {persist}?  (`boolean|string`) (default: `false`)
 
-
-
 ==============================================================================
 Config: help                                           *nvim-tree-config-help*
 
@@ -2007,8 +1971,6 @@ Config: help                                           *nvim-tree-config-help*
     Fields: ~
       • {sort_by}?  (`"key"|"desc"`, default: `"key"`) Alphabetically.
 
-
-
 ==============================================================================
 Config: ui                                               *nvim-tree-config-ui*
 
@@ -2027,8 +1989,6 @@ Config: ui                                               *nvim-tree-config-ui*
       • {default_yes}?  (`boolean`, default: `false`) If `true` the prompt
                         will be `Y/n`, otherwise `y/N`
 
-
-
 ==============================================================================
 Config: experimental                           *nvim-tree-config-experimental*
 
@@ -2038,8 +1998,6 @@ Config: experimental                           *nvim-tree-config-experimental*
     In the event of a problem please disable the experiment and raise an
     issue.
 
-
-
 ==============================================================================
 Config: log                                             *nvim-tree-config-log*
 
@@ -2074,8 +2032,6 @@ Config: log                                             *nvim-tree-config-log*
                         |nvim_tree.config.filesystem_watchers| processing,
                         verbose.
 
-
-
 ==============================================================================
 Config: Default                                     *nvim-tree-config-default*
 
@@ -2367,8 +2323,6 @@ Following is the default configuration, see |nvim_tree.config| for details. >lua
     }
 <
 
-
-
 ==============================================================================
 API                                                            *nvim-tree-api*
 
@@ -2444,8 +2398,6 @@ e.g. the following are functionally identical: >lua
       • {dir}?   (`table<"direct"|"indirect", nvim_tree.git.XY[]>`) direct
                  inclusive-or indirect status
 
-
-
 ==============================================================================
 API: commands                                         *nvim-tree-api-commands*
 
diff --git a/scripts/gen_vimdoc.lua.0.11.patch b/scripts/gen_vimdoc.lua.0.11.patch
deleted file mode 100644
index 2d4dbac15c9..00000000000
--- a/scripts/gen_vimdoc.lua.0.11.patch
+++ /dev/null
@@ -1,14 +0,0 @@
-diff --git a/src/gen/gen_vimdoc.lua b/src/gen/gen_vimdoc.lua
-index 68912cf0b5..f3990cd9a6 100755
---- a/src/gen/gen_vimdoc.lua
-+++ b/src/gen/gen_vimdoc.lua
-@@ -1003,8 +1003,7 @@ local function gen_target(cfg)
-       end
-     end
-     -- FIXME: Using f_base will confuse `_meta/protocol.lua` with `protocol.lua`
--    local f_base = vim.fs.basename(f)
--    sections[f_base] = make_section(f_base, cfg, briefs_txt, funs_txt)
-+    sections[f] = make_section(f, cfg, briefs_txt, funs_txt)
-   end
- 
-   local first_section_tag = sections[cfg.section_order[1]].help_tag
diff --git a/scripts/gen_vimdoc.lua.nightly.patch b/scripts/gen_vimdoc.lua.nightly.patch
deleted file mode 100644
index 3f7152662bb..00000000000
--- a/scripts/gen_vimdoc.lua.nightly.patch
+++ /dev/null
@@ -1,16 +0,0 @@
-diff --git a/src/gen/gen_vimdoc.lua b/src/gen/gen_vimdoc.lua
-index e90158d502..df09bc37ee 100755
---- a/src/gen/gen_vimdoc.lua
-+++ b/src/gen/gen_vimdoc.lua
-@@ -1084,9 +1084,8 @@ local function gen_target(cfg)
-     print('    Processing file:', f)
- 
-     -- FIXME: Using f_base will confuse `_meta/protocol.lua` with `protocol.lua`
--    local f_base = vim.fs.basename(f)
--    sections[f_base] = make_section(
--      f_base,
-+    sections[f] = make_section(
-+      f,
-       cfg,
-       briefs,
-       render_funs(funs, all_classes, cfg),

From 4f7e35cbfc0762c8116998be2e9ea948743cb201 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 29 Jan 2026 10:13:51 +1100
Subject: [PATCH 157/170] Revert "docs(#3088): gen_vimdoc now uses full paths,
 requires a patch for a FIXME"

This reverts commit ff0184a26018837ede43e4637d084eeff9b35713.
---
 doc/nvim-tree-lua.txt                         |  51 +++++++-
 lua/nvim-tree/_meta/api/{git.lua => _git.lua} |   0
 lua/nvim-tree/api.lua                         |   2 +-
 scripts/gen_vimdoc.sh                         |   4 +-
 scripts/gen_vimdoc_config.lua                 | 122 ++++++++++--------
 5 files changed, 124 insertions(+), 55 deletions(-)
 rename lua/nvim-tree/_meta/api/{git.lua => _git.lua} (100%)

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index c852f2c1c18..1fedbd33e12 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -1231,6 +1231,8 @@ Config                                                      *nvim-tree-config*
       • {log}?                                 (`nvim_tree.config.log`)
                                                |nvim_tree.config.log|
 
+
+
 ==============================================================================
 Config: sort                                           *nvim-tree-config-sort*
 
@@ -1269,6 +1271,8 @@ Config: sort                                           *nvim-tree-config-sort*
                           folders. Has no effect when {sorter} is a function.
                           Overrides {folders_first}.
 
+
+
 ==============================================================================
 Config: view                                           *nvim-tree-config-view*
 
@@ -1353,6 +1357,8 @@ Config: view                                           *nvim-tree-config-view*
       • {padding}?         (`nvim_tree.config.view.width.spec`, default: `1`)
                            Extra padding to the right.
 
+
+
 ==============================================================================
 Config: renderer                                   *nvim-tree-config-renderer*
 
@@ -1527,6 +1533,8 @@ Config: renderer                                   *nvim-tree-config-renderer*
                           • {bottom}? (`string`) (default: `"─"`)
                           • {none}? (`string`) (default: `" "`)
 
+
+
 ==============================================================================
 Config: hijack_directories               *nvim-tree-config-hijack-directories*
 
@@ -1543,6 +1551,8 @@ Config: hijack_directories               *nvim-tree-config-hijack-directories*
       • {auto_open}?  (`boolean`, default: `true`) Open if the tree was
                       previously closed.
 
+
+
 ==============================================================================
 Config: update_focused_file             *nvim-tree-config-update-focused-file*
 
@@ -1573,6 +1583,8 @@ Config: update_focused_file             *nvim-tree-config-update-focused-file*
                         tree if the file isn't found under the current root
                         directory.
 
+
+
 ==============================================================================
 Config: system_open                             *nvim-tree-config-system-open*
 
@@ -1595,6 +1607,8 @@ Config: system_open                             *nvim-tree-config-system-open*
                  windows) Optional argument list. Leave empty for OS specific
                  default.
 
+
+
 ==============================================================================
 Config: git                                             *nvim-tree-config-git*
 
@@ -1627,6 +1641,8 @@ Config: git                                             *nvim-tree-config-git*
       • {cygwin_support}?     (`boolean`, default: `false`) Use `cygpath` if
                               available to resolve paths for git.
 
+
+
 ==============================================================================
 Config: diagnostics                             *nvim-tree-config-diagnostics*
 
@@ -1659,6 +1675,8 @@ Config: diagnostics                             *nvim-tree-config-diagnostics*
                               • {warning}? (`string`) (default: `""` )
                               • {error}? (`string`) (default: `""` )
 
+
+
 ==============================================================================
 Config: modified                                   *nvim-tree-config-modified*
 
@@ -1679,6 +1697,8 @@ Config: modified                                   *nvim-tree-config-modified*
                               indication on open directories. Requires
                               {show_on_dirs}.
 
+
+
 ==============================================================================
 Config: filters                                     *nvim-tree-config-filters*
 
@@ -1732,6 +1752,8 @@ Config: filters                                     *nvim-tree-config-filters*
                         (default: `{}`)
       • {exclude}?      (`string[]`) (default: `{}`)
 
+
+
 ==============================================================================
 Config: live_filter                             *nvim-tree-config-live-filter*
 
@@ -1748,6 +1770,8 @@ Config: live_filter                             *nvim-tree-config-live-filter*
       • {always_show_folders}?  (`boolean`, default: `true`) Whether to filter
                                 folders or not.
 
+
+
 ==============================================================================
 Config: filesystem_watchers             *nvim-tree-config-filesystem-watchers*
 
@@ -1781,6 +1805,8 @@ Config: filesystem_watchers             *nvim-tree-config-filesystem-watchers*
                            directory after {max_events} consecutive events
                            with an interval < {debounce_delay}.
 
+
+
 ==============================================================================
 Config: actions                                     *nvim-tree-config-actions*
 
@@ -1902,6 +1928,8 @@ Config: actions                                     *nvim-tree-config-actions*
                          displays a file when removing that file from the
                          tree.
 
+
+
 ==============================================================================
 Config: trash                                         *nvim-tree-config-trash*
 
@@ -1915,6 +1943,8 @@ Config: trash                                         *nvim-tree-config-trash*
     Fields: ~
       • {cmd}?  (`string`) (default: `"gio trash"` or `"trash"`)
 
+
+
 ==============================================================================
 Config: tab                                             *nvim-tree-config-tab*
 
@@ -1934,6 +1964,8 @@ Config: tab                                             *nvim-tree-config-tab*
       • {ignore}?  (`string[]`, default: `{}`) List of filetypes or buffer
                    names on new tab that will prevent `open` and `close`
 
+
+
 ==============================================================================
 Config: notify                                       *nvim-tree-config-notify*
 
@@ -1951,6 +1983,8 @@ Config: notify                                       *nvim-tree-config-notify*
       • {absolute_path}?  (`boolean`, default: `true`) Use absolute paths in
                           FS action notifications, otherwise item names.
 
+
+
 ==============================================================================
 Config: bookmarks                                 *nvim-tree-config-bookmarks*
 
@@ -1963,6 +1997,8 @@ Config: bookmarks                                 *nvim-tree-config-bookmarks*
     Fields: ~
       • {persist}?  (`boolean|string`) (default: `false`)
 
+
+
 ==============================================================================
 Config: help                                           *nvim-tree-config-help*
 
@@ -1971,6 +2007,8 @@ Config: help                                           *nvim-tree-config-help*
     Fields: ~
       • {sort_by}?  (`"key"|"desc"`, default: `"key"`) Alphabetically.
 
+
+
 ==============================================================================
 Config: ui                                               *nvim-tree-config-ui*
 
@@ -1989,6 +2027,8 @@ Config: ui                                               *nvim-tree-config-ui*
       • {default_yes}?  (`boolean`, default: `false`) If `true` the prompt
                         will be `Y/n`, otherwise `y/N`
 
+
+
 ==============================================================================
 Config: experimental                           *nvim-tree-config-experimental*
 
@@ -1998,6 +2038,8 @@ Config: experimental                           *nvim-tree-config-experimental*
     In the event of a problem please disable the experiment and raise an
     issue.
 
+
+
 ==============================================================================
 Config: log                                             *nvim-tree-config-log*
 
@@ -2032,6 +2074,8 @@ Config: log                                             *nvim-tree-config-log*
                         |nvim_tree.config.filesystem_watchers| processing,
                         verbose.
 
+
+
 ==============================================================================
 Config: Default                                     *nvim-tree-config-default*
 
@@ -2323,6 +2367,8 @@ Following is the default configuration, see |nvim_tree.config| for details. >lua
     }
 <
 
+
+
 ==============================================================================
 API                                                            *nvim-tree-api*
 
@@ -2398,6 +2444,8 @@ e.g. the following are functionally identical: >lua
       • {dir}?   (`table<"direct"|"indirect", nvim_tree.git.XY[]>`) direct
                  inclusive-or indirect status
 
+
+
 ==============================================================================
 API: commands                                         *nvim-tree-api-commands*
 
@@ -2570,7 +2618,8 @@ trash({node})                                       *nvim_tree.api.fs.trash()*
 ==============================================================================
 API: git                                                   *nvim-tree-api-git*
 
-reload()                                          *nvim_tree.api.git.reload()*
+                               *nvim_tree.api._git.nvim_tree.api.git.reload()*
+nvim_tree.api.git.reload()
     Update the git status of the entire tree.
 
 
diff --git a/lua/nvim-tree/_meta/api/git.lua b/lua/nvim-tree/_meta/api/_git.lua
similarity index 100%
rename from lua/nvim-tree/_meta/api/git.lua
rename to lua/nvim-tree/_meta/api/_git.lua
diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index e88b19d1f0a..f1d533f6f5f 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -82,7 +82,7 @@ local api = {
   events = require("nvim-tree._meta.api.events"),
   filter = require("nvim-tree._meta.api.filter"),
   fs = require("nvim-tree._meta.api.fs"),
-  git = require("nvim-tree._meta.api.git"),
+  git = require("nvim-tree._meta.api._git"),
   health = require("nvim-tree._meta.api.health"),
   map = require("nvim-tree._meta.api.map"),
   marks = require("nvim-tree._meta.api.marks"),
diff --git a/scripts/gen_vimdoc.sh b/scripts/gen_vimdoc.sh
index 2b46bd71585..e9bb69dda88 100755
--- a/scripts/gen_vimdoc.sh
+++ b/scripts/gen_vimdoc.sh
@@ -59,8 +59,8 @@ export LUA_PATH="${DIR_NVIM_SRC}/src/?.lua;${DIR_NVT}/scripts/?.lua"
 
 # gen_vimdoc.lua doesn't like dashes in lua module names
 #   -> use nvim_tree instead of nvim-tree
-mkdir -pv "${DIR_WORK}/runtime/lua"
-ln -sv "${DIR_NVT}/lua/nvim-tree" "${DIR_WORK}/runtime/lua/nvim_tree"
+mkdir -pv "${DIR_WORK}/lua"
+ln -sv "${DIR_NVT}/lua/nvim-tree" "${DIR_WORK}/lua/nvim_tree"
 
 # generate
 cd "${DIR_WORK}" && pwd
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index 05303980449..691fe69bde8 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -6,55 +6,64 @@
 ---@field helptag string must be globally unique
 ---@field section string arbitrary
 ---@field path string relative to root
+---@field file_name? string generated from path
+---@field name? string override generated name
+---@field append_only? boolean follows previous section
 
 ---Help txt is deleted from first tag down and generated content is appended.
-local pre = "runtime/lua/nvim_tree/"
 ---@type Src[]
 local srcs = {
-  { helptag = "nvim-tree-config",                     section = "Config",                      path = pre .. "_meta/config.lua", },
-  { helptag = "nvim-tree-config-sort",                section = "Config: sort",                path = pre .. "_meta/config/sort.lua", },
-  { helptag = "nvim-tree-config-view",                section = "Config: view",                path = pre .. "_meta/config/view.lua", },
-  { helptag = "nvim-tree-config-renderer",            section = "Config: renderer",            path = pre .. "_meta/config/renderer.lua", },
-  { helptag = "nvim-tree-config-hijack-directories",  section = "Config: hijack_directories",  path = pre .. "_meta/config/hijack_directories.lua", },
-  { helptag = "nvim-tree-config-update-focused-file", section = "Config: update_focused_file", path = pre .. "_meta/config/update_focused_file.lua", },
-  { helptag = "nvim-tree-config-system-open",         section = "Config: system_open",         path = pre .. "_meta/config/system_open.lua", },
-  { helptag = "nvim-tree-config-git",                 section = "Config: git",                 path = pre .. "_meta/config/git.lua", },
-  { helptag = "nvim-tree-config-diagnostics",         section = "Config: diagnostics",         path = pre .. "_meta/config/diagnostics.lua", },
-  { helptag = "nvim-tree-config-modified",            section = "Config: modified",            path = pre .. "_meta/config/modified.lua", },
-  { helptag = "nvim-tree-config-filters",             section = "Config: filters",             path = pre .. "_meta/config/filters.lua", },
-  { helptag = "nvim-tree-config-live-filter",         section = "Config: live_filter",         path = pre .. "_meta/config/live_filter.lua", },
-  { helptag = "nvim-tree-config-filesystem-watchers", section = "Config: filesystem_watchers", path = pre .. "_meta/config/filesystem_watchers.lua", },
-  { helptag = "nvim-tree-config-actions",             section = "Config: actions",             path = pre .. "_meta/config/actions.lua", },
-  { helptag = "nvim-tree-config-trash",               section = "Config: trash",               path = pre .. "_meta/config/trash.lua", },
-  { helptag = "nvim-tree-config-tab",                 section = "Config: tab",                 path = pre .. "_meta/config/tab.lua", },
-  { helptag = "nvim-tree-config-notify",              section = "Config: notify",              path = pre .. "_meta/config/notify.lua", },
-  { helptag = "nvim-tree-config-bookmarks",           section = "Config: bookmarks",           path = pre .. "_meta/config/bookmarks.lua", },
-  { helptag = "nvim-tree-config-help",                section = "Config: help",                path = pre .. "_meta/config/help.lua", },
-  { helptag = "nvim-tree-config-ui",                  section = "Config: ui",                  path = pre .. "_meta/config/ui.lua", },
-  { helptag = "nvim-tree-config-experimental",        section = "Config: experimental",        path = pre .. "_meta/config/experimental.lua", },
-  { helptag = "nvim-tree-config-log",                 section = "Config: log",                 path = pre .. "_meta/config/log.lua", },
-
-  { helptag = "nvim-tree-config-default",             section = "Config: Default",             path = pre .. "_meta/config/default.lua", },
-
-  { helptag = "nvim-tree-api",                        section = "API",                         path = pre .. "api.lua", },
-
-  { helptag = "nvim-tree-api-commands",               section = "API: commands",               path = pre .. "_meta/api/commands.lua", },
-  { helptag = "nvim-tree-api-events",                 section = "API: events",                 path = pre .. "_meta/api/events.lua", },
-  { helptag = "nvim-tree-api-filter",                 section = "API: filter",                 path = pre .. "_meta/api/filter.lua", },
-  { helptag = "nvim-tree-api-fs",                     section = "API: fs",                     path = pre .. "_meta/api/fs.lua", },
-  { helptag = "nvim-tree-api-git",                    section = "API: git",                    path = pre .. "_meta/api/git.lua", },
-  { helptag = "nvim-tree-api-health",                 section = "API: health",                 path = pre .. "_meta/api/health.lua", },
-  { helptag = "nvim-tree-api-map",                    section = "API: map",                    path = pre .. "_meta/api/map.lua", },
-  { helptag = "nvim-tree-api-marks",                  section = "API: marks",                  path = pre .. "_meta/api/marks.lua", },
-  { helptag = "nvim-tree-api-node",                   section = "API: node",                   path = pre .. "_meta/api/node.lua", },
-  { helptag = "nvim-tree-api-tree",                   section = "API: tree",                   path = pre .. "_meta/api/tree.lua", },
+  { helptag = "nvim-tree-config",                     section = "Config",                      path = "./lua/nvim_tree/_meta/config.lua", },
+  { helptag = "nvim-tree-config-sort",                section = "Config: sort",                path = "./lua/nvim_tree/_meta/config/sort.lua", },
+  { helptag = "nvim-tree-config-view",                section = "Config: view",                path = "./lua/nvim_tree/_meta/config/view.lua", },
+  { helptag = "nvim-tree-config-renderer",            section = "Config: renderer",            path = "./lua/nvim_tree/_meta/config/renderer.lua", },
+  { helptag = "nvim-tree-config-hijack-directories",  section = "Config: hijack_directories",  path = "./lua/nvim_tree/_meta/config/hijack_directories.lua", },
+  { helptag = "nvim-tree-config-update-focused-file", section = "Config: update_focused_file", path = "./lua/nvim_tree/_meta/config/update_focused_file.lua", },
+  { helptag = "nvim-tree-config-system-open",         section = "Config: system_open",         path = "./lua/nvim_tree/_meta/config/system_open.lua", },
+  { helptag = "nvim-tree-config-git",                 section = "Config: git",                 path = "./lua/nvim_tree/_meta/config/git.lua", },
+  { helptag = "nvim-tree-config-diagnostics",         section = "Config: diagnostics",         path = "./lua/nvim_tree/_meta/config/diagnostics.lua", },
+  { helptag = "nvim-tree-config-modified",            section = "Config: modified",            path = "./lua/nvim_tree/_meta/config/modified.lua", },
+  { helptag = "nvim-tree-config-filters",             section = "Config: filters",             path = "./lua/nvim_tree/_meta/config/filters.lua", },
+  { helptag = "nvim-tree-config-live-filter",         section = "Config: live_filter",         path = "./lua/nvim_tree/_meta/config/live_filter.lua", },
+  { helptag = "nvim-tree-config-filesystem-watchers", section = "Config: filesystem_watchers", path = "./lua/nvim_tree/_meta/config/filesystem_watchers.lua", },
+  { helptag = "nvim-tree-config-actions",             section = "Config: actions",             path = "./lua/nvim_tree/_meta/config/actions.lua", },
+  { helptag = "nvim-tree-config-trash",               section = "Config: trash",               path = "./lua/nvim_tree/_meta/config/trash.lua", },
+  { helptag = "nvim-tree-config-tab",                 section = "Config: tab",                 path = "./lua/nvim_tree/_meta/config/tab.lua", },
+  { helptag = "nvim-tree-config-notify",              section = "Config: notify",              path = "./lua/nvim_tree/_meta/config/notify.lua", },
+  { helptag = "nvim-tree-config-bookmarks",           section = "Config: bookmarks",           path = "./lua/nvim_tree/_meta/config/bookmarks.lua", },
+  { helptag = "nvim-tree-config-help",                section = "Config: help",                path = "./lua/nvim_tree/_meta/config/help.lua", },
+  { helptag = "nvim-tree-config-ui",                  section = "Config: ui",                  path = "./lua/nvim_tree/_meta/config/ui.lua",                  name = "UI", },
+  { helptag = "nvim-tree-config-experimental",        section = "Config: experimental",        path = "./lua/nvim_tree/_meta/config/experimental.lua", },
+  { helptag = "nvim-tree-config-log",                 section = "Config: log",                 path = "./lua/nvim_tree/_meta/config/log.lua", },
+
+  { helptag = "nvim-tree-config-default",             section = "Config: Default",             path = "./lua/nvim_tree/_meta/config/default.lua", },
+
+  { helptag = "nvim-tree-api",                        section = "API",                         path = "./lua/nvim_tree/api.lua", },
+
+  { helptag = "nvim-tree-api-commands",               section = "API: commands",               path = "./lua/nvim_tree/_meta/api/commands.lua", },
+  { helptag = "nvim-tree-api-events",                 section = "API: events",                 path = "./lua/nvim_tree/_meta/api/events.lua", },
+  { helptag = "nvim-tree-api-filter",                 section = "API: filter",                 path = "./lua/nvim_tree/_meta/api/filter.lua", },
+  { helptag = "nvim-tree-api-fs",                     section = "API: fs",                     path = "./lua/nvim_tree/_meta/api/fs.lua", },
+  -- TODO #3088 come up with a solution to avoid filename clashes
+  { helptag = "nvim-tree-api-git",                    section = "API: git",                    path = "./lua/nvim_tree/_meta/api/_git.lua", },
+  { helptag = "nvim-tree-api-health",                 section = "API: health",                 path = "./lua/nvim_tree/_meta/api/health.lua", },
+  { helptag = "nvim-tree-api-map",                    section = "API: map",                    path = "./lua/nvim_tree/_meta/api/map.lua", },
+  { helptag = "nvim-tree-api-marks",                  section = "API: marks",                  path = "./lua/nvim_tree/_meta/api/marks.lua", },
+  { helptag = "nvim-tree-api-node",                   section = "API: node",                   path = "./lua/nvim_tree/_meta/api/node.lua", },
+  { helptag = "nvim-tree-api-tree",                   section = "API: tree",                   path = "./lua/nvim_tree/_meta/api/tree.lua", },
 }
 
---name is derived by the generator as the path with the first letter capitalised and the extension stripped
+-- hydrate file names
+for _, m in ipairs(srcs) do
+  m.file_name = vim.fn.fnamemodify(m.path, ":t")
+end
+
+--name is derived by the generator as the file name with the first letter capitalised
+--except for some like UI which are overridden in srcs
 ---@type table
 local srcs_by_name = {}
 for _, m in ipairs(srcs) do
-  local name = m.path:gsub("^%l", string.upper):gsub(".lua$", "")
+  local name = m.name or m.file_name:gsub(".lua", ""):gsub("^%l", string.upper)
   srcs_by_name[name] = m
 end
 
@@ -63,35 +72,46 @@ local config = {
   all = {
     filename = "nvim-tree-lua.txt",
 
-    -- path, ordered
-    section_order = vim.tbl_map(function(src) return src.path end, srcs),
+    -- source file name is used to set order
+    section_order = vim.tbl_map(function(src) return src.file_name end, srcs),
 
-    -- path, unordered
+    -- path
     files = vim.tbl_map(function(src) return src.path end, srcs),
 
-    -- lookup by name
+    append_only = vim.tbl_map(function(src) return src.append_only and src.file_name or nil end, srcs),
+
     section_fmt = function(name)
-      return srcs_by_name[name] and srcs_by_name[name].section or error(string.format("\nUnknown name passed to section_fmt: '%s'", name))
+      print(string.format("section_fmt name=%s", name))
+      return srcs_by_name[name] and srcs_by_name[name].section or
+        error(string.format("unknown name %s passed to section_fmt", name))
     end,
 
-    -- lookup by name
     helptag_fmt = function(name)
-      return srcs_by_name[name] and srcs_by_name[name].helptag or error(string.format("\nUnknown name passed to helptag_fmt: '%s'", name))
+      print(string.format("helptag_fmt name=%s", name))
+      return srcs_by_name[name] and srcs_by_name[name].helptag or
+        error(string.format("unknown name %s passed to helptag_fmt", name))
     end,
 
     -- optional, no default xform
     fn_xform = function(fun)
+      print(string.format("fn_xform fun=%s", vim.inspect(fun)))
+
       if (fun.module) then
         -- generator doesn't strip meta
         -- also cascades into fn_helptag_fmt
         local module = fun.module:gsub("._meta", "", 1)
 
-        -- remove the API module from the left aligned function name
+        -- remove the API prefix from the left aligned function name
         -- this will cascade into fn_helptag_fmt, which will apply the module prefix anyway
+
+        -- TODO #3088 come up with a solution to avoid filename clashes
+        ---@diagnostic disable-next-line: unused-local
         local name, replaced = fun.name:gsub("^" .. module .. "%.", "", 1)
-        if (replaced ~= 1) then
-          error(string.format("\nFunction name does not start with\nmodule='%s'\nfun=%s", module, vim.inspect(fun)))
-        end
+        -- if (replaced ~= 1) then
+        --   error(string.format("function name does not start with module: %s", vim.inspect(fun)))
+        -- end
+
+        print(string.format("fn_xform name: %s -> %s", fun.name, name))
 
         fun.module = module
         fun.name = name

From a67526658820f13d0c89b1364bb2be7c4c8767f6 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 29 Jan 2026 11:53:00 +1100
Subject: [PATCH 158/170] docs(#3088): split gen_vimdoc_config into chunks to
 avoid filename clashes, as gen_vimdoc keys sections by filename

---
 doc/nvim-tree-lua.txt                         |   3 +-
 lua/nvim-tree/_meta/api/{_git.lua => git.lua} |   0
 scripts/gen_vimdoc.sh                         |   4 +-
 scripts/gen_vimdoc_config.lua                 | 180 +++++++++---------
 4 files changed, 96 insertions(+), 91 deletions(-)
 rename lua/nvim-tree/_meta/api/{_git.lua => git.lua} (100%)

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 1fedbd33e12..7b3d3eb07ab 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -2618,8 +2618,7 @@ trash({node})                                       *nvim_tree.api.fs.trash()*
 ==============================================================================
 API: git                                                   *nvim-tree-api-git*
 
-                               *nvim_tree.api._git.nvim_tree.api.git.reload()*
-nvim_tree.api.git.reload()
+reload()                                          *nvim_tree.api.git.reload()*
     Update the git status of the entire tree.
 
 
diff --git a/lua/nvim-tree/_meta/api/_git.lua b/lua/nvim-tree/_meta/api/git.lua
similarity index 100%
rename from lua/nvim-tree/_meta/api/_git.lua
rename to lua/nvim-tree/_meta/api/git.lua
diff --git a/scripts/gen_vimdoc.sh b/scripts/gen_vimdoc.sh
index e9bb69dda88..2b46bd71585 100755
--- a/scripts/gen_vimdoc.sh
+++ b/scripts/gen_vimdoc.sh
@@ -59,8 +59,8 @@ export LUA_PATH="${DIR_NVIM_SRC}/src/?.lua;${DIR_NVT}/scripts/?.lua"
 
 # gen_vimdoc.lua doesn't like dashes in lua module names
 #   -> use nvim_tree instead of nvim-tree
-mkdir -pv "${DIR_WORK}/lua"
-ln -sv "${DIR_NVT}/lua/nvim-tree" "${DIR_WORK}/lua/nvim_tree"
+mkdir -pv "${DIR_WORK}/runtime/lua"
+ln -sv "${DIR_NVT}/lua/nvim-tree" "${DIR_WORK}/runtime/lua/nvim_tree"
 
 # generate
 cd "${DIR_WORK}" && pwd
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index 691fe69bde8..9ea7bba13e4 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -6,96 +6,109 @@
 ---@field helptag string must be globally unique
 ---@field section string arbitrary
 ---@field path string relative to root
----@field file_name? string generated from path
----@field name? string override generated name
----@field append_only? boolean follows previous section
 
----Help txt is deleted from first tag down and generated content is appended.
----@type Src[]
-local srcs = {
-  { helptag = "nvim-tree-config",                     section = "Config",                      path = "./lua/nvim_tree/_meta/config.lua", },
-  { helptag = "nvim-tree-config-sort",                section = "Config: sort",                path = "./lua/nvim_tree/_meta/config/sort.lua", },
-  { helptag = "nvim-tree-config-view",                section = "Config: view",                path = "./lua/nvim_tree/_meta/config/view.lua", },
-  { helptag = "nvim-tree-config-renderer",            section = "Config: renderer",            path = "./lua/nvim_tree/_meta/config/renderer.lua", },
-  { helptag = "nvim-tree-config-hijack-directories",  section = "Config: hijack_directories",  path = "./lua/nvim_tree/_meta/config/hijack_directories.lua", },
-  { helptag = "nvim-tree-config-update-focused-file", section = "Config: update_focused_file", path = "./lua/nvim_tree/_meta/config/update_focused_file.lua", },
-  { helptag = "nvim-tree-config-system-open",         section = "Config: system_open",         path = "./lua/nvim_tree/_meta/config/system_open.lua", },
-  { helptag = "nvim-tree-config-git",                 section = "Config: git",                 path = "./lua/nvim_tree/_meta/config/git.lua", },
-  { helptag = "nvim-tree-config-diagnostics",         section = "Config: diagnostics",         path = "./lua/nvim_tree/_meta/config/diagnostics.lua", },
-  { helptag = "nvim-tree-config-modified",            section = "Config: modified",            path = "./lua/nvim_tree/_meta/config/modified.lua", },
-  { helptag = "nvim-tree-config-filters",             section = "Config: filters",             path = "./lua/nvim_tree/_meta/config/filters.lua", },
-  { helptag = "nvim-tree-config-live-filter",         section = "Config: live_filter",         path = "./lua/nvim_tree/_meta/config/live_filter.lua", },
-  { helptag = "nvim-tree-config-filesystem-watchers", section = "Config: filesystem_watchers", path = "./lua/nvim_tree/_meta/config/filesystem_watchers.lua", },
-  { helptag = "nvim-tree-config-actions",             section = "Config: actions",             path = "./lua/nvim_tree/_meta/config/actions.lua", },
-  { helptag = "nvim-tree-config-trash",               section = "Config: trash",               path = "./lua/nvim_tree/_meta/config/trash.lua", },
-  { helptag = "nvim-tree-config-tab",                 section = "Config: tab",                 path = "./lua/nvim_tree/_meta/config/tab.lua", },
-  { helptag = "nvim-tree-config-notify",              section = "Config: notify",              path = "./lua/nvim_tree/_meta/config/notify.lua", },
-  { helptag = "nvim-tree-config-bookmarks",           section = "Config: bookmarks",           path = "./lua/nvim_tree/_meta/config/bookmarks.lua", },
-  { helptag = "nvim-tree-config-help",                section = "Config: help",                path = "./lua/nvim_tree/_meta/config/help.lua", },
-  { helptag = "nvim-tree-config-ui",                  section = "Config: ui",                  path = "./lua/nvim_tree/_meta/config/ui.lua",                  name = "UI", },
-  { helptag = "nvim-tree-config-experimental",        section = "Config: experimental",        path = "./lua/nvim_tree/_meta/config/experimental.lua", },
-  { helptag = "nvim-tree-config-log",                 section = "Config: log",                 path = "./lua/nvim_tree/_meta/config/log.lua", },
-
-  { helptag = "nvim-tree-config-default",             section = "Config: Default",             path = "./lua/nvim_tree/_meta/config/default.lua", },
+local pre = "runtime/lua/nvim_tree/"
 
-  { helptag = "nvim-tree-api",                        section = "API",                         path = "./lua/nvim_tree/api.lua", },
+---@type Src[]
+local srcs_config = {
+  { helptag = "nvim-tree-config",                     section = "Config",                      path = pre .. "_meta/config.lua", },
+
+  { helptag = "nvim-tree-config-sort",                section = "Config: sort",                path = pre .. "_meta/config/sort.lua", },
+  { helptag = "nvim-tree-config-view",                section = "Config: view",                path = pre .. "_meta/config/view.lua", },
+  { helptag = "nvim-tree-config-renderer",            section = "Config: renderer",            path = pre .. "_meta/config/renderer.lua", },
+  { helptag = "nvim-tree-config-hijack-directories",  section = "Config: hijack_directories",  path = pre .. "_meta/config/hijack_directories.lua", },
+  { helptag = "nvim-tree-config-update-focused-file", section = "Config: update_focused_file", path = pre .. "_meta/config/update_focused_file.lua", },
+  { helptag = "nvim-tree-config-system-open",         section = "Config: system_open",         path = pre .. "_meta/config/system_open.lua", },
+  { helptag = "nvim-tree-config-git",                 section = "Config: git",                 path = pre .. "_meta/config/git.lua", },
+  { helptag = "nvim-tree-config-diagnostics",         section = "Config: diagnostics",         path = pre .. "_meta/config/diagnostics.lua", },
+  { helptag = "nvim-tree-config-modified",            section = "Config: modified",            path = pre .. "_meta/config/modified.lua", },
+  { helptag = "nvim-tree-config-filters",             section = "Config: filters",             path = pre .. "_meta/config/filters.lua", },
+  { helptag = "nvim-tree-config-live-filter",         section = "Config: live_filter",         path = pre .. "_meta/config/live_filter.lua", },
+  { helptag = "nvim-tree-config-filesystem-watchers", section = "Config: filesystem_watchers", path = pre .. "_meta/config/filesystem_watchers.lua", },
+  { helptag = "nvim-tree-config-actions",             section = "Config: actions",             path = pre .. "_meta/config/actions.lua", },
+  { helptag = "nvim-tree-config-trash",               section = "Config: trash",               path = pre .. "_meta/config/trash.lua", },
+  { helptag = "nvim-tree-config-tab",                 section = "Config: tab",                 path = pre .. "_meta/config/tab.lua", },
+  { helptag = "nvim-tree-config-notify",              section = "Config: notify",              path = pre .. "_meta/config/notify.lua", },
+  { helptag = "nvim-tree-config-bookmarks",           section = "Config: bookmarks",           path = pre .. "_meta/config/bookmarks.lua", },
+  { helptag = "nvim-tree-config-help",                section = "Config: help",                path = pre .. "_meta/config/help.lua", },
+  { helptag = "nvim-tree-config-ui",                  section = "Config: ui",                  path = pre .. "_meta/config/ui.lua", },
+  { helptag = "nvim-tree-config-experimental",        section = "Config: experimental",        path = pre .. "_meta/config/experimental.lua", },
+  { helptag = "nvim-tree-config-log",                 section = "Config: log",                 path = pre .. "_meta/config/log.lua", },
+
+  { helptag = "nvim-tree-config-default",             section = "Config: Default",             path = pre .. "_meta/config/default.lua", },
+
+  { helptag = "nvim-tree-api",                        section = "API Placeholder",             path = pre .. "api.lua", },
+}
 
-  { helptag = "nvim-tree-api-commands",               section = "API: commands",               path = "./lua/nvim_tree/_meta/api/commands.lua", },
-  { helptag = "nvim-tree-api-events",                 section = "API: events",                 path = "./lua/nvim_tree/_meta/api/events.lua", },
-  { helptag = "nvim-tree-api-filter",                 section = "API: filter",                 path = "./lua/nvim_tree/_meta/api/filter.lua", },
-  { helptag = "nvim-tree-api-fs",                     section = "API: fs",                     path = "./lua/nvim_tree/_meta/api/fs.lua", },
-  -- TODO #3088 come up with a solution to avoid filename clashes
-  { helptag = "nvim-tree-api-git",                    section = "API: git",                    path = "./lua/nvim_tree/_meta/api/_git.lua", },
-  { helptag = "nvim-tree-api-health",                 section = "API: health",                 path = "./lua/nvim_tree/_meta/api/health.lua", },
-  { helptag = "nvim-tree-api-map",                    section = "API: map",                    path = "./lua/nvim_tree/_meta/api/map.lua", },
-  { helptag = "nvim-tree-api-marks",                  section = "API: marks",                  path = "./lua/nvim_tree/_meta/api/marks.lua", },
-  { helptag = "nvim-tree-api-node",                   section = "API: node",                   path = "./lua/nvim_tree/_meta/api/node.lua", },
-  { helptag = "nvim-tree-api-tree",                   section = "API: tree",                   path = "./lua/nvim_tree/_meta/api/tree.lua", },
+---@type Src[]
+local srcs_api = {
+  { helptag = "nvim-tree-api",          section = "API",           path = pre .. "api.lua", },
+
+  { helptag = "nvim-tree-api-commands", section = "API: commands", path = pre .. "_meta/api/commands.lua", },
+  { helptag = "nvim-tree-api-events",   section = "API: events",   path = pre .. "_meta/api/events.lua", },
+  { helptag = "nvim-tree-api-filter",   section = "API: filter",   path = pre .. "_meta/api/filter.lua", },
+  { helptag = "nvim-tree-api-fs",       section = "API: fs",       path = pre .. "_meta/api/fs.lua", },
+  { helptag = "nvim-tree-api-git",      section = "API: git",      path = pre .. "_meta/api/git.lua", },
+  { helptag = "nvim-tree-api-health",   section = "API: health",   path = pre .. "_meta/api/health.lua", },
+  { helptag = "nvim-tree-api-map",      section = "API: map",      path = pre .. "_meta/api/map.lua", },
+  { helptag = "nvim-tree-api-marks",    section = "API: marks",    path = pre .. "_meta/api/marks.lua", },
+  { helptag = "nvim-tree-api-node",     section = "API: node",     path = pre .. "_meta/api/node.lua", },
+  { helptag = "nvim-tree-api-tree",     section = "API: tree",     path = pre .. "_meta/api/tree.lua", },
 }
 
--- hydrate file names
-for _, m in ipairs(srcs) do
-  m.file_name = vim.fn.fnamemodify(m.path, ":t")
+---Map paths to file names
+---File names are the unique key that gen_vimdoc.lua uses
+---@param srcs Src[]
+---@return string[] file names
+local function section_order(srcs)
+  return vim.tbl_map(function(src)
+    return vim.fn.fnamemodify(src.path, ":t")
+  end, srcs)
 end
 
---name is derived by the generator as the file name with the first letter capitalised
---except for some like UI which are overridden in srcs
----@type table
-local srcs_by_name = {}
-for _, m in ipairs(srcs) do
-  local name = m.name or m.file_name:gsub(".lua", ""):gsub("^%l", string.upper)
-  srcs_by_name[name] = m
+---Extract paths
+---@param srcs Src[]
+---@return string[] file names
+local function files(srcs)
+  return vim.tbl_map(function(src)
+    return src.path
+  end, srcs)
+end
+
+---Find a Src or error.
+---Name is the (sometimes specifically hardcoded) mangled case filename with .lua stripped
+---@param name string
+---@param srcs Src[]
+---@return Src?
+local function src_by_name(name, srcs)
+  for _, s in ipairs(srcs) do
+    if s.path:match(name:lower() .. ".lua$") then
+      return s
+    end
+  end
+  error(string.format("\n\nPath for lower, extension stripped file name='%s' not found in\nsrcs=%s\n", name, vim.inspect(srcs)))
 end
 
 -- @type table
-local config = {
-  all = {
+return {
+  -- Config
+  {
     filename = "nvim-tree-lua.txt",
+    section_order = section_order(srcs_config),
+    files = files(srcs_config),
+    section_fmt = function(name) return src_by_name(name, srcs_config).section end,
+    helptag_fmt = function(name) return src_by_name(name, srcs_config).helptag end,
+  },
+  -- API
+  {
+    filename = "nvim-tree-lua.txt",
+    section_order = section_order(srcs_api),
+    files = files(srcs_api),
+    section_fmt = function(name) return src_by_name(name, srcs_api).section end,
+    helptag_fmt = function(name) return src_by_name(name, srcs_api).helptag end,
 
-    -- source file name is used to set order
-    section_order = vim.tbl_map(function(src) return src.file_name end, srcs),
-
-    -- path
-    files = vim.tbl_map(function(src) return src.path end, srcs),
-
-    append_only = vim.tbl_map(function(src) return src.append_only and src.file_name or nil end, srcs),
-
-    section_fmt = function(name)
-      print(string.format("section_fmt name=%s", name))
-      return srcs_by_name[name] and srcs_by_name[name].section or
-        error(string.format("unknown name %s passed to section_fmt", name))
-    end,
-
-    helptag_fmt = function(name)
-      print(string.format("helptag_fmt name=%s", name))
-      return srcs_by_name[name] and srcs_by_name[name].helptag or
-        error(string.format("unknown name %s passed to helptag_fmt", name))
-    end,
-
-    -- optional, no default xform
+    -- optional, no default xform to override
     fn_xform = function(fun)
-      print(string.format("fn_xform fun=%s", vim.inspect(fun)))
-
       if (fun.module) then
         -- generator doesn't strip meta
         -- also cascades into fn_helptag_fmt
@@ -103,15 +116,10 @@ local config = {
 
         -- remove the API prefix from the left aligned function name
         -- this will cascade into fn_helptag_fmt, which will apply the module prefix anyway
-
-        -- TODO #3088 come up with a solution to avoid filename clashes
-        ---@diagnostic disable-next-line: unused-local
         local name, replaced = fun.name:gsub("^" .. module .. "%.", "", 1)
-        -- if (replaced ~= 1) then
-        --   error(string.format("function name does not start with module: %s", vim.inspect(fun)))
-        -- end
-
-        print(string.format("fn_xform name: %s -> %s", fun.name, name))
+        if (replaced ~= 1) then
+          error(string.format("\n\nfun.name='%s' does not start with _meta stripped module='%s'\nfun=%s", fun.name, module, vim.inspect(fun)))
+        end
 
         fun.module = module
         fun.name = name
@@ -119,5 +127,3 @@ local config = {
     end,
   }
 }
-
-return config

From c6c5286282d3daaa0ec3ee070625eece05196a0c Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 29 Jan 2026 13:28:29 +1100
Subject: [PATCH 159/170] docs(#3088): move legacy api into api.impl.legacy,
 fixes following testing

---
 lua/nvim-tree/api.lua             |  2 +-
 lua/nvim-tree/api/impl/legacy.lua | 25 +++++++++++++++++++++
 lua/nvim-tree/api/impl/post.lua   | 17 ++++++++------
 lua/nvim-tree/api/impl/pre.lua    |  6 +++--
 lua/nvim-tree/legacy.lua          | 37 -------------------------------
 scripts/gen_vimdoc_config.lua     |  7 ++++--
 6 files changed, 45 insertions(+), 49 deletions(-)
 create mode 100644 lua/nvim-tree/api/impl/legacy.lua

diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua
index f1d533f6f5f..e88b19d1f0a 100644
--- a/lua/nvim-tree/api.lua
+++ b/lua/nvim-tree/api.lua
@@ -82,7 +82,7 @@ local api = {
   events = require("nvim-tree._meta.api.events"),
   filter = require("nvim-tree._meta.api.filter"),
   fs = require("nvim-tree._meta.api.fs"),
-  git = require("nvim-tree._meta.api._git"),
+  git = require("nvim-tree._meta.api.git"),
   health = require("nvim-tree._meta.api.health"),
   map = require("nvim-tree._meta.api.map"),
   marks = require("nvim-tree._meta.api.marks"),
diff --git a/lua/nvim-tree/api/impl/legacy.lua b/lua/nvim-tree/api/impl/legacy.lua
new file mode 100644
index 00000000000..51924b4f365
--- /dev/null
+++ b/lua/nvim-tree/api/impl/legacy.lua
@@ -0,0 +1,25 @@
+---Silently create new api entries pointing legacy functions to current
+---@param api table not properly typed to prevent LSP from referencing implementations
+return function(api)
+  api.config = api.config or {}
+  api.config.mappings = api.config.mappings or {}
+  api.config.mappings.get_keymap = api.map.keymap.current
+  api.config.mappings.get_keymap_default = api.map.keymap.default
+  api.config.mappings.default_on_attach = api.map.on_attach.default
+
+  api.live_filter = api.live_filter or {}
+  api.live_filter.start = api.filter.live.start
+  api.live_filter.clear = api.filter.live.clear
+
+  api.tree = api.tree or {}
+  api.tree.toggle_enable_filters = api.filter.toggle
+  api.tree.toggle_gitignore_filter = api.filter.git.ignored.toggle
+  api.tree.toggle_git_clean_filter = api.filter.git.clean.toggle
+  api.tree.toggle_no_buffer_filter = api.filter.no_buffer.toggle
+  api.tree.toggle_custom_filter = api.filter.custom.toggle
+  api.tree.toggle_hidden_filter = api.filter.dotfiles.toggle
+  api.tree.toggle_no_bookmark_filter = api.filter.no_bookmark.toggle
+
+  api.diagnostics = api.diagnostics or {}
+  api.diagnostics.hi_test = api.health.hi_test
+end
diff --git a/lua/nvim-tree/api/impl/post.lua b/lua/nvim-tree/api/impl/post.lua
index 3f9793694d3..2aa5a3caec3 100644
--- a/lua/nvim-tree/api/impl/post.lua
+++ b/lua/nvim-tree/api/impl/post.lua
@@ -6,8 +6,11 @@
 ---This is expensive as there are many cascading requires and is avoided
 ---until after setup has been called, so that the user may require API cheaply.
 
-local view = require("nvim-tree.view")
 local actions = require("nvim-tree.actions")
+local help = require("nvim-tree.help")
+local keymap = require("nvim-tree.keymap")
+local utils = require("nvim-tree.utils")
+local view = require("nvim-tree.view")
 
 local DirectoryNode = require("nvim-tree.node.directory")
 local FileLinkNode = require("nvim-tree.node.file-link")
@@ -131,7 +134,7 @@ local function open_or_expand_or_dir_up(mode, toggle_group)
 end
 
 ---Hydrate all implementations barring those that were called during hydrate_pre
----@param api table
+---@param api table not properly typed to prevent LSP from referencing implementations
 local function hydrate_post(api)
   api.tree.open = actions.tree.open.fn
   api.tree.focus = api.tree.open
@@ -157,8 +160,8 @@ local function hydrate_post(api)
   api.tree.collapse_all = actions.tree.collapse.all
 
   api.tree.expand_all = wrap_node(wrap_explorer("expand_all"))
-  api.tree.toggle_help = function() require("nvim-tree.help").toggle() end
-  api.tree.is_tree_buf = function() require("nvim-tree.utils").is_nvim_tree_buf() end
+  api.tree.toggle_help = help.toggle
+  api.tree.is_tree_buf = utils.is_nvim_tree_buf
 
   api.tree.is_visible = view.is_visible
 
@@ -248,15 +251,15 @@ local function hydrate_post(api)
   api.marks.navigate.prev = wrap_explorer_member("marks", "navigate_prev")
   api.marks.navigate.select = wrap_explorer_member("marks", "navigate_select")
 
-  api.map.get_keymap = function() require("nvim-tree.keymap").get_keymap() end
+  api.map.keymap.current = keymap.get_keymap
 end
 
 ---Re-hydrate api
----@param api table
+---@param api table not properly typed to prevent LSP from referencing implementations
 return function(api)
   -- All concrete implementations
   hydrate_post(api)
 
   -- (Re)hydrate any legacy by mapping to function set above
-  require("nvim-tree.legacy").api_map(api)
+  require("nvim-tree.api.impl.legacy")(api)
 end
diff --git a/lua/nvim-tree/api/impl/pre.lua b/lua/nvim-tree/api/impl/pre.lua
index 8df356584f3..7ad25ecb41f 100644
--- a/lua/nvim-tree/api/impl/pre.lua
+++ b/lua/nvim-tree/api/impl/pre.lua
@@ -30,6 +30,7 @@ local function hydrate_error(t)
 end
 
 ---Hydrate implementations that may be called pre setup
+---@param api table not properly typed to prevent LSP from referencing implementations
 local function hydrate_pre(api)
   --
   -- Essential
@@ -51,7 +52,7 @@ local function hydrate_pre(api)
   --
   api.commands.get = commands.get
 
-  api.map.get_keymap_default = keymap.get_keymap_default
+  api.map.keymap.default = keymap.get_keymap_default
 
 
   --
@@ -65,6 +66,7 @@ local function hydrate_pre(api)
 end
 
 ---Hydrate api
+---@param api table not properly typed to prevent LSP from referencing implementations
 return function(api)
   -- Default: error
   hydrate_error(api)
@@ -73,5 +75,5 @@ return function(api)
   hydrate_pre(api)
 
   -- Hydrate any legacy by mapping to function set above
-  require("nvim-tree.legacy").api_map(api)
+  require("nvim-tree.api.impl.legacy")(api)
 end
diff --git a/lua/nvim-tree/legacy.lua b/lua/nvim-tree/legacy.lua
index 72aad9e3d85..842700ba36b 100644
--- a/lua/nvim-tree/legacy.lua
+++ b/lua/nvim-tree/legacy.lua
@@ -2,10 +2,6 @@ local notify = require("nvim-tree.notify")
 
 local M = {}
 
---
---Functions
---
-
 --- Create empty sub-tables if not present
 ---@param tbl table to create empty inside of
 ---@param path string dot separated string of sub-tables
@@ -54,10 +50,6 @@ local function move(src, src_path, src_pos, dst, dst_path, dst_pos, remove)
   end
 end
 
---
---Config
---
-
 -- silently move, please add to help nvim-tree-legacy-opts
 local function refactored(opts)
   -- 2022/06/20
@@ -159,33 +151,4 @@ function M.migrate_legacy_options(opts)
   removed(opts)
 end
 
---
---API
---
-
----Silently create new api entries pointing legacy functions to current
-function M.api_map(api)
-  api.config = api.config or {}
-  api.config.mappings = api.config.mappings or {}
-  api.config.mappings.get_keymap = api.map.keymap.current
-  api.config.mappings.get_keymap_default = api.map.keymap.default
-  api.config.mappings.default_on_attach = api.map.on_attach.default
-
-  api.live_filter = api.live_filter or {}
-  api.live_filter.start = api.filter.live.start
-  api.live_filter.clear = api.filter.live.clear
-
-  api.tree = api.tree or {}
-  api.tree.toggle_enable_filters = api.filter.toggle
-  api.tree.toggle_gitignore_filter = api.filter.git.ignored.toggle
-  api.tree.toggle_git_clean_filter = api.filter.git.clean.toggle
-  api.tree.toggle_no_buffer_filter = api.filter.no_buffer.toggle
-  api.tree.toggle_custom_filter = api.filter.custom.toggle
-  api.tree.toggle_hidden_filter = api.filter.dotfiles.toggle
-  api.tree.toggle_no_bookmark_filter = api.filter.no_bookmark.toggle
-
-  api.diagnostics = api.diagnostics or {}
-  api.diagnostics.hi_test = api.health.hi_test
-end
-
 return M
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index 9ea7bba13e4..d5d7bf4636f 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -2,6 +2,9 @@
 --Returned config is injected into the above.
 --See gen_vimdoc.sh
 
+--gen_vimdoc keys by filename:   -- FIXME: Using f_base will confuse `_meta/protocol.lua` with `protocol.lua`
+--Hence we must ensure that filenames are unique within each nvim.gen_vimdoc.Config[]
+
 ---@class (exact) Src
 ---@field helptag string must be globally unique
 ---@field section string arbitrary
@@ -37,7 +40,7 @@ local srcs_config = {
 
   { helptag = "nvim-tree-config-default",             section = "Config: Default",             path = pre .. "_meta/config/default.lua", },
 
-  { helptag = "nvim-tree-api",                        section = "API Placeholder",             path = pre .. "api.lua", },
+  { helptag = "nvim-tree-api",                        section = "placeholder for next Config", path = pre .. "api.lua", },
 }
 
 ---@type Src[]
@@ -89,7 +92,7 @@ local function src_by_name(name, srcs)
   error(string.format("\n\nPath for lower, extension stripped file name='%s' not found in\nsrcs=%s\n", name, vim.inspect(srcs)))
 end
 
--- @type table
+-- @type nvim.gen_vimdoc.Config[]
 return {
   -- Config
   {

From 1a7457b412f603ec0318842e1885bdc819c0bf85 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 29 Jan 2026 13:40:52 +1100
Subject: [PATCH 160/170] docs(#3088): remove merge leftover

---
 .../actions/tree/modifiers/expand.lua         | 165 ------------------
 1 file changed, 165 deletions(-)
 delete mode 100644 lua/nvim-tree/actions/tree/modifiers/expand.lua

diff --git a/lua/nvim-tree/actions/tree/modifiers/expand.lua b/lua/nvim-tree/actions/tree/modifiers/expand.lua
deleted file mode 100644
index 14409011ef3..00000000000
--- a/lua/nvim-tree/actions/tree/modifiers/expand.lua
+++ /dev/null
@@ -1,165 +0,0 @@
-local core = require("nvim-tree.core")
-local Iterator = require("nvim-tree.iterators.node-iterator")
-local notify = require("nvim-tree.notify")
-
-local FileNode = require("nvim-tree.node.file")
-local DirectoryNode = require("nvim-tree.node.directory")
-
-local M = {}
-
----@param list string[]
----@return table
-local function to_lookup_table(list)
-  local table = {}
-  for _, element in ipairs(list) do
-    table[element] = true
-  end
-
-  return table
-end
-
----@param node DirectoryNode
-local function expand(node)
-  node = node:last_group_node()
-  node.open = true
-  if #node.nodes == 0 then
-    core.get_explorer():expand_dir_node(node)
-  end
-end
-
----@param should_descend fun(expansion_count: integer, node: Node): boolean
----@return fun(expansion_count: integer, node: Node): boolean
-local function limit_folder_discovery(should_descend)
-  return function(expansion_count, node)
-    local should_halt = expansion_count >= M.MAX_FOLDER_DISCOVERY
-    if should_halt then
-      notify.warn("expansion iteration was halted after " .. M.MAX_FOLDER_DISCOVERY .. " discovered folders")
-      return false
-    end
-
-    return should_descend(expansion_count, node)
-  end
-end
-
----@param _ integer expansion_count
----@param node Node
----@return boolean
-local function descend_until_empty(_, node)
-  local dir = node:as(DirectoryNode)
-  if not dir then
-    return false
-  end
-
-  local should_exclude = M.EXCLUDE[dir.name]
-  return not should_exclude
-end
-
----@param expansion_count integer
----@param node Node
----@param should_descend fun(expansion_count: integer, node: Node): boolean
----@return boolean
-local function should_expand(expansion_count, node, should_descend)
-  local dir = node:as(DirectoryNode)
-  if not dir then
-    return false
-  end
-
-  if not dir.open and should_descend(expansion_count, node) then
-    if #node.nodes == 0 then
-      core.get_explorer():expand_dir_node(dir) -- populate node.group_next
-    end
-
-    if dir.group_next then
-      local expand_next = should_expand(expansion_count, dir.group_next, should_descend)
-      if expand_next then
-        dir.open = true
-      end
-      return expand_next
-    else
-      return true
-    end
-  end
-  return false
-end
-
-
----@param should_descend fun(expansion_count: integer, node: Node): boolean
----@return fun(node): any
-local function gen_iterator(should_descend)
-  local expansion_count = 0
-
-  return function(parent)
-    if parent.parent and parent.nodes and not parent.open then
-      expansion_count = expansion_count + 1
-      expand(parent)
-    end
-
-    Iterator.builder(parent.nodes)
-      :hidden()
-      :applier(function(node)
-        if should_expand(expansion_count, node, should_descend) then
-          expansion_count = expansion_count + 1
-          node = node:as(DirectoryNode)
-          if node then
-            expand(node)
-          end
-        end
-      end)
-      :recursor(function(node)
-        if not should_descend(expansion_count, node) then
-          return nil
-        end
-
-        if node.group_next then
-          return { node.group_next }
-        end
-
-        if node.open and node.nodes then
-          return node.nodes
-        end
-
-        return nil
-      end)
-      :iterate()
-  end
-end
-
----@param node? Node
----@param expand_opts? nvim_tree.api.node.expand.Opts
-local function expand_node(node, expand_opts)
-  if not node then
-    return
-  end
-  local descend_until = limit_folder_discovery((expand_opts and expand_opts.expand_until) or descend_until_empty)
-  gen_iterator(descend_until)(node)
-
-  local explorer = core.get_explorer()
-  if explorer then
-    explorer.renderer:draw()
-  end
-end
-
----Expand the directory node or the root
----@param node Node
----@param expand_opts nvim_tree.api.node.expand.Opts?
-function M.all(node, expand_opts)
-  expand_node(node and node:as(DirectoryNode) or core.get_explorer(), expand_opts)
-end
-
----Expand the directory node or parent node
----@param node? Node
----@param expand_opts? nvim_tree.api.node.expand.Opts
-function M.node(node, expand_opts)
-  if not node then
-    return
-  end
-
-  expand_node(node:is(FileNode) and node.parent or node:as(DirectoryNode), expand_opts)
-end
-
-function M.setup(opts)
-  M.MAX_FOLDER_DISCOVERY = opts.actions.expand_all.max_folder_discovery
-  M.EXCLUDE = to_lookup_table(opts.actions.expand_all.exclude)
-end
-
-return M

From 1dd53f073b6c844930863ccf480f2ba51c6c27dc Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 29 Jan 2026 13:41:01 +1100
Subject: [PATCH 161/170] docs(#3088): tidy contrib

---
 CONTRIBUTING.md | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e16c20402a2..33c23cd9268 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -125,8 +125,9 @@ end
 
 When adding to or changing:
 1. Default config
-2. `config` classes
-3. `on_attach` default mappings
+2. `Config` classes
+3. `keymap.on_attach_default`
+4. Any API
 
 You must generate help documentation. This requires neovim stable sources. You will be promted with instructions on fetching and referencing the source.
 
@@ -136,8 +137,10 @@ make help-update
 
 This will:
 1. Update config defaults in `*nvim-tree-setup*`
-2. Regenerate from `*nvim-tree-config*` to the end of the file, see `gen_vimdoc.sh`
-3. Update default mappings in `*nvim-tree-mappings-default*` and `*nvim-tree-quickstart-help*`
+2. Update default mappings in `*nvim-tree-mappings-default*` and `*nvim-tree-quickstart-help*`
+3. Regenerate from `*nvim-tree-config*` to the end of the file, see `gen_vimdoc.sh`
+  - Config classes
+  - API classes and functions
 
 Commit or stage your changes then run:
 ```sh

From 1853d325e96d001b75aa58315e91512d0245ee81 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 29 Jan 2026 13:56:49 +1100
Subject: [PATCH 162/170] docs(#3088): clarify backwards compatibility

---
 doc/nvim-tree-lua.txt | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 7b3d3eb07ab..d79c4e9fca0 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -986,9 +986,7 @@ keep using |netrw| without its browser features please ensure:
 ==============================================================================
 Legacy                                                      *nvim-tree-legacy*
 
-Breaking refactors have been made however the legacy versions will be silently
-migrated and used.
-There are no plans to remove this migration.
+Backwards compatible, silent refactors have been done.
 
 ==============================================================================
 Legacy: Config                                       *nvim-tree-legacy-config*
@@ -1012,8 +1010,7 @@ needed.
 ==============================================================================
 Legacy: API                                             *nvim-tree-legacy-api*
 
-Some API functions have been refactored however the previous function will
-continue to be available.
+Deprecated API with unchanged function signature:
 
 `api.config.mappings.get_keymap`         |nvim_tree.api.map.keymap.current()|
 `api.config.mappings.get_keymap_default` |nvim_tree.api.map.keymap.default()|

From 984378f139b6829d142d864f1e62891d1c7d6041 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Fri, 30 Jan 2026 12:36:28 +1100
Subject: [PATCH 163/170] docs(#3088): clarify help generation in contributing

---
 CONTRIBUTING.md       | 69 ++++++++++++++++++++++++++++---------------
 doc/nvim-tree-lua.txt |  1 +
 scripts/gen_vimdoc.sh |  5 +++-
 3 files changed, 51 insertions(+), 24 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 33c23cd9268..e1f704eddb6 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -60,7 +60,7 @@ make lint
 ## style
 
 1. Runs lua language server `codestyle-check` only, using `.luarc.json` settings
-1. Runs `scripts/doc-comments.sh` to validate annotated documentation
+1. Runs `scripts/doc-comments.sh` to normalise annotated documentation
 
 ```sh
 make style
@@ -86,11 +86,11 @@ Assumes `$VIMRUNTIME` is `/usr/share/nvim/runtime`. Adjust as necessary e.g.
 VIMRUNTIME="/my/path/to/runtime" make check
 ```
 
-If `lua-language-server` is not available or `--check` doesn't function (e.g. Arch Linux 3.9.1-1) you can manually install it as per `ci.yml` e.g.
+If `lua-language-server` is not available or `--check` doesn't function (e.g. Arch Linux 3.9.1-1) you can manually install it as per `ci.yml` using its current `luals_version` e.g.
 
 ```sh
 mkdir luals
-curl -L "https://github.com/LuaLS/lua-language-server/releases/download/3.9.1/lua-language-server-3.9.1-linux-x64.tar.gz" | tar zx --directory luals
+curl -L "https://github.com/LuaLS/lua-language-server/releases/download/3.15.0/lua-language-server-3.15.0-linux-x64.tar.gz" | tar zx --directory luals
 
 PATH="luals/bin:${PATH}" make check
 ```
@@ -119,39 +119,62 @@ else
 end
 ```
 
-# Documentation
+# :help Documentation
 
-## Config And Mappings
+Please update or add to `doc/nvim-tree-lua.txt` as needed.
 
-When adding to or changing:
-1. Default config
-2. `Config` classes
-3. `keymap.on_attach_default`
-4. Any API
+## Generated Content
 
-You must generate help documentation. This requires neovim stable sources. You will be promted with instructions on fetching and referencing the source.
+`doc/nvim-tree-lua.txt` content starting at `*nvim-tree-config*` will be replaced with generated content. Do not manually edit that content.
+
+### API and Config
+
+Help is generated for:
+- `nvim_tree.config` classes from `lua/nvim-tree/_meta/config/`
+- `nvim_tree.api` functions from `lua/nvim-tree/_meta/api/`
+
+Please add or update documentation when you make changes, see `:help dev-lua-doc` for docstring format.
+
+`scripts/gen_vimdoc_config.lua` contains the manifest of help sources.
+
+### Config And Mappings
+
+Help is updated for:
+- Default keymap at `keymap.on_attach_default`
+- Default config at `--- default-config-start`
+
+## Updating And Generating
+
+Nvim sources are required. You will be prompted with instructions on fetching and using the sources.
+
+See comments at the start of each script for complete details.
 
 ```sh
 make help-update
 ```
 
-This will:
-1. Update config defaults in `*nvim-tree-setup*`
-2. Update default mappings in `*nvim-tree-mappings-default*` and `*nvim-tree-quickstart-help*`
-3. Regenerate from `*nvim-tree-config*` to the end of the file, see `gen_vimdoc.sh`
-  - Config classes
-  - API classes and functions
+- `scripts/help-update.sh`
+  - Update config defaults `*nvim-tree-setup*`
+  - Update default mappings:
+    - `*nvim-tree-mappings-default*`
+    - `*nvim-tree-quickstart-help*`
+
+- `scripts/gen_vimdoc.sh`
+  - Remove content starting at `*nvim-tree-config*`
+  - Generate config classes `*nvim-tree-config*`
+  - Generate API `*nvim-tree-api*`
+
+## Checking And Linting
+
+This is run in CI. Commit or stage your changes and run:
 
-Commit or stage your changes then run:
 ```sh
 make help-check
 ```
 
-This will re-run `help-update` and check that there are no diffs. It will also lint the documentation, see `lintdoc.sh`
-
-## API
-
-When adding or changing API please update :help nvim-tree-api
+- Re-runs `make help-update`
+- Checks that `git diff` is empty, to ensure that all content has been generated. This is why a stage or commit is necessary.
+- Lints `doc/nvim-tree-lua.txt` using `scripts/lintdoc.sh` to check for no broken links etc.
 
 # Windows
 
diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index d79c4e9fca0..b8f089191d9 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -7,6 +7,7 @@ Help tag prefixes:
   • |nvim-tree-mappings|
   • |nvim-tree-config|
 • `nvim_tree.`  API and classes e.g.
+  • |nvim_tree.api.node.navigate.parent()|
   • |nvim_tree.config.filesystem_watchers|
 
 ==============================================================================
diff --git a/scripts/gen_vimdoc.sh b/scripts/gen_vimdoc.sh
index 2b46bd71585..93d7e171708 100755
--- a/scripts/gen_vimdoc.sh
+++ b/scripts/gen_vimdoc.sh
@@ -4,7 +4,9 @@
 #
 # Doesn't require Nvim to have been built.
 #
-# Shims our moudules into gen_vimdoc_config.lua, replacing Nvim's.
+# Generated from nvim-tree sources defined in scripts/gen_vimdoc_config.lua
+#
+# Shims our sources into src/gen/gen_vimdoc.lua replacing Nvim's.
 #
 # There are some hardcoded expectations which we work around as commented.
 
@@ -39,6 +41,7 @@ Please:
   mkdir -p ${DIR_NVIM_SRC_DEF}
   curl -L 'https://github.com/neovim/neovim/archive/refs/tags/stable.tar.gz' | tar zx --directory $(dirname "${DIR_NVIM_SRC_DEF}")
   export DIR_NVIM_SRC=/tmp/src/neovim-stable
+
 EOM
 exit 1
 fi

From 9b962b508d5e38bf55979fac143b673cd7e9ba0f Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Fri, 30 Jan 2026 12:37:28 +1100
Subject: [PATCH 164/170] docs(#3088): contributing index

---
 CONTRIBUTING.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e1f704eddb6..2ff501d57a8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -18,9 +18,10 @@ markdown-toc --maxdepth=2 -i CONTRIBUTING.md
   * [check](#check)
 - [Diagnostics](#diagnostics)
 - [Backwards Compatibility](#backwards-compatibility)
-- [Documentation](#documentation)
-  * [Config And Mappings](#config-and-mappings)
-  * [API](#api)
+- [:help Documentation](#help-documentation)
+  * [Generated Content](#generated-content)
+  * [Updating And Generating](#updating-and-generating)
+  * [Checking And Linting](#checking-and-linting)
 - [Windows](#windows)
 - [Pull Request](#pull-request)
   * [Subject](#subject)

From 6be2074de6c0d687f72d971d69385eceae990b13 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Fri, 30 Jan 2026 13:24:55 +1100
Subject: [PATCH 165/170] docs(#3088): help-update.sh -> help-defaults.sh now
 using a /tmp file to prevent runaway FS updates

---
 Makefile                                     |  2 +-
 scripts/{help-update.sh => help-defaults.sh} | 21 ++++++++++++++++----
 2 files changed, 18 insertions(+), 5 deletions(-)
 rename scripts/{help-update.sh => help-defaults.sh} (78%)

diff --git a/Makefile b/Makefile
index 4ec53e0bb4a..46be8932d53 100644
--- a/Makefile
+++ b/Makefile
@@ -35,7 +35,7 @@ style-fix:
 #
 help-update:
 	scripts/gen_vimdoc.sh
-	scripts/help-update.sh
+	scripts/help-defaults.sh
 
 #
 # CI
diff --git a/scripts/help-update.sh b/scripts/help-defaults.sh
similarity index 78%
rename from scripts/help-update.sh
rename to scripts/help-defaults.sh
index a367feb9e81..11ffefe4cc0 100755
--- a/scripts/help-update.sh
+++ b/scripts/help-defaults.sh
@@ -2,7 +2,15 @@
 
 # run after changing default config or keymap.lua M.on_attach_default
 # scrapes and updates nvim-tree-lua.txt
-# run from repository root: scripts/help-update.sh  OR  make help-update
+# run from repository root: scripts/help-defaults.sh  OR  make help-update
+
+set -e
+
+#
+# Operate on a temporary file as sed -i writes the file thousands of times.
+#
+WIP="/tmp/nvim-tree-lua.txt"
+cp "doc/nvim-tree-lua.txt" "${WIP}"
 
 
 #
@@ -19,7 +27,7 @@ sed -n -e "/${begin}/,/${end}/{ /${begin}/d; /${end}/d; p; }" lua/nvim-tree.lua
 sed -e "s/^  /      /" /tmp/DEFAULT_OPTS.2.lua > /tmp/DEFAULT_OPTS.6.lua
 
 # inject then remove the placeholder
-sed -i -e "/${inject}/r /tmp/DEFAULT_OPTS.6.lua" -e "/${inject}/d" doc/nvim-tree-lua.txt
+sed -i -e "/${inject}/r /tmp/DEFAULT_OPTS.6.lua" -e "/${inject}/d" "${WIP}"
 
 #
 # Inject default mappings
@@ -33,7 +41,7 @@ sed -n -e "/${begin}/,/${end}/{ /${begin}/d; /${end}/d; p; }" lua/nvim-tree/keym
 
 # help lua
 sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/ON_ATTACH_DEFAULT.lua
-           }; /${end}/p; d; }" doc/nvim-tree-lua.txt
+           }; /${end}/p; d; }" "${WIP}"
 
 # help human
 echo > /tmp/ON_ATTACH_DEFAULT.help
@@ -46,4 +54,9 @@ echo >> /tmp/ON_ATTACH_DEFAULT.help
 begin="Show the mappings:"
 end="======"
 sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/ON_ATTACH_DEFAULT.help
-           }; /${end}/p; d; }" doc/nvim-tree-lua.txt
+           }; /${end}/p; d; }" "${WIP}"
+
+#
+# complete
+#
+mv "${WIP}" "doc/nvim-tree-lua.txt"

From 7d277fe7809e5ac5c2a7857e9d8269a3fb81fba6 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Fri, 30 Jan 2026 13:26:36 +1100
Subject: [PATCH 166/170] docs(#3088): help-update.sh -> help-defaults.sh now
 using a /tmp file to prevent runaway FS updates

---
 CONTRIBUTING.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2ff501d57a8..8c94daaf282 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -154,8 +154,8 @@ See comments at the start of each script for complete details.
 make help-update
 ```
 
-- `scripts/help-update.sh`
-  - Update config defaults `*nvim-tree-setup*`
+- `scripts/help-defaults.sh`
+  - Update config defaults `*nvim-tree-config-default*`
   - Update default mappings:
     - `*nvim-tree-mappings-default*`
     - `*nvim-tree-quickstart-help*`

From 033bfd3980b398eaa34826e907180c99ed88e6b6 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Fri, 30 Jan 2026 13:32:44 +1100
Subject: [PATCH 167/170] docs(#3088): CI runs make lintdoc to avoid muddying
 help-check with unnecessary build and possible Nvim lint failures

---
 .github/workflows/ci.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 86b0b49d32e..cfdd24e2329 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -82,6 +82,6 @@ jobs:
           mkdir -p "${DIR_NVIM_SRC}"
           curl -L "https://github.com/neovim/neovim/archive/refs/tags/${{ matrix.nvim_version }}.tar.gz" | tar zx --directory "${DIR_NVIM_SRC}/.."
           cd "${DIR_NVIM_SRC}"
-          make
+          make lintdoc
 
       - run: make help-check

From d0a1426b122618c88900995fe0661e04f6ab1418 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sat, 31 Jan 2026 13:40:28 +1100
Subject: [PATCH 168/170] docs(#3088): unify help and readme, clarify some
 wording

---
 README.md                                  | 163 +++++++++++++--------
 doc/nvim-tree-lua.txt                      |  22 +--
 lua/nvim-tree/_meta/classes.lua            |   1 +
 lua/nvim-tree/_meta/config/log.lua         |   2 +-
 lua/nvim-tree/_meta/config/system_open.lua |   2 +-
 5 files changed, 113 insertions(+), 77 deletions(-)

diff --git a/README.md b/README.md
index 5bcb3d58fa3..2f31c72b1c7 100644
--- a/README.md
+++ b/README.md
@@ -32,50 +32,55 @@ Questions and general support: [Discussions](https://github.com/nvim-tree/nvim-t
 
 [nvim-web-devicons](https://github.com/nvim-tree/nvim-web-devicons) is optional and used to display file icons. It requires a [patched font](https://www.nerdfonts.com/). Your terminal emulator must be configured to use that font, usually "Hack Nerd Font"
 
-## Install
+## Installing
 
-Please install via your preferred package manager. See [Installation](https://github.com/nvim-tree/nvim-tree.lua/wiki/Installation) for specific package manager instructions.
-
-`nvim-tree/nvim-tree.lua`
+Please install via your preferred package manager. See [Installation](https://github.com/nvim-tree/nvim-tree.lua/wiki/Installation) for some specific package manager instructions.
 
 Major or minor versions may be specified via tags: `v` e.g. `v1` or `v.` e.g. `v1.23`
 
-`nvim-tree/nvim-web-devicons` optional, for file icons
+## Quick Start
 
-Disabling [netrw](https://neovim.io/doc/user/pi_netrw.html) is strongly advised, see [:help nvim-tree-netrw](doc/nvim-tree-lua.txt)
+Install the plugins via your package manager:
+  `"nvim-tree/nvim-tree.lua"`
+  `"nvim-tree/nvim-web-devicons"`
 
-## Quick Start
+Disabling [netrw](https://neovim.io/doc/user/pi_netrw.html) is strongly advised, see [:help nvim-tree-netrw](doc/nvim-tree-lua.txt)
 
 ### Setup
 
-Setup the plugin in your `init.lua`
+Setup the plugin in your `init.lua`.
+
+See [:help nvim-tree-setup](doc/nvim-tree-lua.txt) and [:help nvim-tree-config-default](doc/nvim-tree-lua.txt)
 
 ```lua
--- disable netrw at the very start of your init.lua
-vim.g.loaded_netrw = 1
-vim.g.loaded_netrwPlugin = 1
-
--- optionally enable 24-bit colour
-vim.opt.termguicolors = true
-
--- empty setup using defaults
-require("nvim-tree").setup()
-
--- OR setup with some options
-require("nvim-tree").setup({
-  sort = {
-    sorter = "case_sensitive",
-  },
-  view = {
-    width = 30,
-  },
-  renderer = {
-    group_empty = true,
-  },
-  filters = {
-    dotfiles = true,
-  },
-})
+  -- disable netrw at the very start of your init.lua
+  vim.g.loaded_netrw = 1
+  vim.g.loaded_netrwPlugin = 1
+
+  -- optionally enable 24-bit colour
+  vim.opt.termguicolors = true
+
+  -- empty setup using defaults
+  require("nvim-tree").setup()
+
+  -- OR setup with a config
+
+  ---@type nvim_tree.config
+  local config = {
+    sort = {
+      sorter = "case_sensitive",
+    },
+    view = {
+      width = 30,
+    },
+    renderer = {
+      group_empty = true,
+    },
+    filters = {
+      dotfiles = true,
+    },
+  }
+  require("nvim-tree").setup(config)
 ```
 
 ### Help
@@ -86,33 +91,35 @@ Show the mappings:  `g?`
 
 ### Custom Mappings
 
-[:help nvim-tree-mappings-default](doc/nvim-tree-lua.txt) are applied by default however you may customise via |nvim-tree.on_attach| e.g.
+[:help nvim-tree-mappings-default](doc/nvim-tree-lua.txt) are applied by default however you may customise via [:help nvim_tree.config](doc/nvim-tree-lua.txt) `{on_attach}` e.g.
 
 ```lua
-local function my_on_attach(bufnr)
-  local api = require "nvim-tree.api"
+  local function my_on_attach(bufnr)
+    local api = require "nvim-tree.api"
 
-  local function opts(desc)
-    return { desc = "nvim-tree: " .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true }
-  end
+    local function opts(desc)
+      return { desc = "nvim-tree: " .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true }
+    end
 
-  -- default mappings
-  api.map.on_attach.default(bufnr)
+    -- default mappings
+    api.map.on_attach.default(bufnr)
 
-  -- custom mappings
-  vim.keymap.set('n', '', api.tree.change_root_to_parent,        opts('Up'))
-  vim.keymap.set('n', '?',     api.tree.toggle_help,                  opts('Help'))
-end
+    -- custom mappings
+    vim.keymap.set("n", "", api.tree.change_root_to_parent,        opts("Up"))
+    vim.keymap.set("n", "?",     api.tree.toggle_help,                  opts("Help"))
+  end
 
--- pass to setup along with your other options
-require("nvim-tree").setup {
-  ---
-  on_attach = my_on_attach,
-  ---
-}
+  -- pass to setup along with your other config
+  require("nvim-tree").setup({
+    ---
+    on_attach = my_on_attach,
+    ---
+  })
 ```
 
-### Highlight
+### Highlight Groups
+
+See [:help nvim-tree-highlight-groups](doc/nvim-tree-lua.txt)
 
 Run `:NvimTreeHiTest` to show all the highlights that nvim-tree uses.
 
@@ -120,28 +127,55 @@ They can be customised before or after setup is called and will be immediately
 applied at runtime. e.g.
 
 ```lua
-vim.cmd([[
-    :hi      NvimTreeExecFile    guifg=#ffa0a0
-    :hi      NvimTreeSpecialFile guifg=#ff80ff gui=underline
-    :hi      NvimTreeSymlink     guifg=Yellow  gui=italic
-    :hi link NvimTreeImageFile   Title
-]])
+  vim.cmd([[
+      :hi      NvimTreeExecFile    guifg=#ffa0a0
+      :hi      NvimTreeSpecialFile guifg=#ff80ff gui=underline
+      :hi      NvimTreeSymlink     guifg=Yellow  gui=italic
+      :hi link NvimTreeImageFile   Title
+  ]])
 ```
-See [:help nvim-tree-highlight](doc/nvim-tree-lua.txt) for details.
 
 ## Commands
 
 See [:help nvim-tree-commands](doc/nvim-tree-lua.txt)
 
-Basic commands:
+Some commands may be executed with a bang `!` or take a `path` string argument.
+
+All commands execute public API.
 
-`:NvimTreeToggle` Open or close the tree. Takes an optional path argument.
+Some basic commands:
 
-`:NvimTreeFocus` Open the tree if it is closed, and then focus on the tree.
+`:NvimTreeFocus`                           [:help nvim_tree.api.tree.open()](doc/nvim-tree-lua.txt)
+```lua
+  require("nvim-tree.api").tree.open()
+```
+
+`:NvimTreeToggle`                          [:help nvim_tree.api.tree.toggle()](doc/nvim-tree-lua.txt)
+```lua
+  require("nvim-tree.api").tree.toggle({
+    path = "",
+    find_file = false,
+    update_root = false,
+    focus = true,
+  })
+```
 
-`:NvimTreeFindFile` Move the cursor in the tree for the current buffer, opening folders if needed.
+`:NvimTreeFindFile`                        [:help nvim_tree.api.tree.find_file()](doc/nvim-tree-lua.txt)
+```lua
+  require("nvim-tree.api").tree.find_file({
+    open = true,
+    update_root = "",
+    focus = true,
+  })
+```
+
+`:NvimTreeCollapse`                        [:help nvim_tree.api.tree.collapse_all()](doc/nvim-tree-lua.txt)
 
-`:NvimTreeCollapse` Collapses the nvim-tree recursively.
+```lua
+  require("nvim-tree.api").tree.collapse_all({
+    keep_buffers = false
+  })
+```
 
 ## Roadmap
 
@@ -155,6 +189,7 @@ Development is focused on:
 * Quality of Life improvements
 * API / Events
 * Enhancements to existing features
+- Multi-instance capabilities
 
 ## API
 
diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index b8f089191d9..87a2abaf910 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -187,7 +187,7 @@ via |nvim_tree.config| {on_attach} e.g. >lua
     vim.keymap.set("n", "?",     api.tree.toggle_help,                  opts("Help"))
   end
 
-  -- pass to setup along with your other options
+  -- pass to setup along with your other config
   require("nvim-tree").setup({
     ---
     on_attach = my_on_attach,
@@ -202,19 +202,19 @@ Run |:NvimTreeHiTest| to show all the highlights that nvim-tree uses.
 They can be customised before or after setup is called and will be immediately
 applied at runtime. e.g. >lua
 
-    vim.cmd([[
-        :hi      NvimTreeExecFile    guifg=#ffa0a0
-        :hi      NvimTreeSpecialFile guifg=#ff80ff gui=underline
-        :hi      NvimTreeSymlink     guifg=Yellow  gui=italic
-        :hi link NvimTreeImageFile   Title
-    ]])
+  vim.cmd([[
+      :hi      NvimTreeExecFile    guifg=#ffa0a0
+      :hi      NvimTreeSpecialFile guifg=#ff80ff gui=underline
+      :hi      NvimTreeSymlink     guifg=Yellow  gui=italic
+      :hi link NvimTreeImageFile   Title
+  ]])
 <
 See |nvim-tree-highlight-groups| for details.
 
 ==============================================================================
 Commands                                                  *nvim-tree-commands*
 
-Commands may be executed with a `` (`!`) or take a `path` string argument.
+Some commands may be executed with a || `!` or take a `path` string argument.
 
 All commands execute public API.
 
@@ -1596,8 +1596,8 @@ Config: system_open                             *nvim-tree-config-system-open*
       • macOS: `open`
       • Windows: `cmd`
 
-    Once nvim-tree minimum Nvim version is updated to 0.10, these options will
-    no longer be necessary and will be removed.
+    Once nvim-tree minimum Nvim version is updated to 0.10, this configuration
+    will no longer be necessary and will be removed.
 
     Fields: ~
       • {cmd}?   (`string`) The open command itself
@@ -2059,7 +2059,7 @@ Config: log                                             *nvim-tree-config-log*
       • {all}?          (`boolean`, default: `false`) Everything.
       • {profile}?      (`boolean`, default: `false`) Timing of some
                         operations.
-      • {config}?       (`boolean`, default: `false`) Options and mappings, at
+      • {config}?       (`boolean`, default: `false`) Config and mappings, at
                         startup.
       • {copy_paste}?   (`boolean`, default: `false`) File copy and paste
                         actions.
diff --git a/lua/nvim-tree/_meta/classes.lua b/lua/nvim-tree/_meta/classes.lua
index 859c457a8e7..7de002916c6 100644
--- a/lua/nvim-tree/_meta/classes.lua
+++ b/lua/nvim-tree/_meta/classes.lua
@@ -2,6 +2,7 @@
 error("Cannot require a meta file")
 
 
+-- TODO #2688
 -- These node subclasses are not ready for public exposure as they are:
 -- - not classic classes
 -- - only used in a few locations: api.tree.get_nodes and UserDecorator
diff --git a/lua/nvim-tree/_meta/config/log.lua b/lua/nvim-tree/_meta/config/log.lua
index 396e25ef626..357a164a8cf 100644
--- a/lua/nvim-tree/_meta/config/log.lua
+++ b/lua/nvim-tree/_meta/config/log.lua
@@ -28,7 +28,7 @@ error("Cannot require a meta file")
 ---(default: `false`)
 ---@field profile? boolean
 ---
----Options and mappings, at startup.
+---Config and mappings, at startup.
 ---(default: `false`)
 ---@field config? boolean
 ---
diff --git a/lua/nvim-tree/_meta/config/system_open.lua b/lua/nvim-tree/_meta/config/system_open.lua
index 114bdf6501d..44f6ceed413 100644
--- a/lua/nvim-tree/_meta/config/system_open.lua
+++ b/lua/nvim-tree/_meta/config/system_open.lua
@@ -12,7 +12,7 @@ error("Cannot require a meta file")
 ---   - macOS: `open`
 ---   - Windows: `cmd`
 ---
----Once nvim-tree minimum Nvim version is updated to 0.10, these options will no longer be necessary and will be removed.
+---Once nvim-tree minimum Nvim version is updated to 0.10, this configuration will no longer be necessary and will be removed.
 ---
 ---@class nvim_tree.config.system_open
 ---

From 6cf83d716f7aa63da1cd29874b764b3fa022f38e Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sat, 31 Jan 2026 13:42:53 +1100
Subject: [PATCH 169/170] docs(#3088): test a readme toc

---
 README.md | 33 ++++++++++++++++++++++++++++-----
 1 file changed, 28 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 2f31c72b1c7..e5088dceda2 100644
--- a/README.md
+++ b/README.md
@@ -26,6 +26,29 @@ Take a look at the [wiki](https://github.com/nvim-tree/nvim-tree.lua/wiki) for S
 
 Questions and general support: [Discussions](https://github.com/nvim-tree/nvim-tree.lua/discussions)
 
+
+
+
+
+- [Requirements](#requirements)
+- [Installing](#installing)
+- [Quick Start](#quick-start)
+  * [Setup](#setup)
+  * [Help](#help)
+  * [Custom Mappings](#custom-mappings)
+  * [Highlight Groups](#highlight-groups)
+- [Commands](#commands)
+- [Roadmap](#roadmap)
+- [API](#api)
+- [Contributing](#contributing)
+- [Screenshots](#screenshots)
+- [Team](#team)
+
+
+
 ## Requirements
 
 [neovim >=0.9.0](https://github.com/neovim/neovim/wiki/Installing-Neovim)
@@ -184,11 +207,11 @@ nvim-tree is stable and new major features will not be added. The focus is on ex
 Users are encouraged to add their own custom features via the public [API](#api).
 
 Development is focused on:
-* Bug fixes
-* Performance
-* Quality of Life improvements
-* API / Events
-* Enhancements to existing features
+- Bug fixes
+- Performance
+- Quality of Life improvements
+- API / Events
+- Enhancements to existing features
 - Multi-instance capabilities
 
 ## API

From c076f3f5b20d3dd3c765be63f5d9ca62b2eacd7f Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Sat, 31 Jan 2026 13:45:34 +1100
Subject: [PATCH 170/170] docs(#3088): test a readme toc

---
 README.md | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index e5088dceda2..70d6adf2ce5 100644
--- a/README.md
+++ b/README.md
@@ -49,19 +49,19 @@ markdown-toc --maxdepth=2 -i README.md
 
 
 
-## Requirements
+# Requirements
 
 [neovim >=0.9.0](https://github.com/neovim/neovim/wiki/Installing-Neovim)
 
 [nvim-web-devicons](https://github.com/nvim-tree/nvim-web-devicons) is optional and used to display file icons. It requires a [patched font](https://www.nerdfonts.com/). Your terminal emulator must be configured to use that font, usually "Hack Nerd Font"
 
-## Installing
+# Installing
 
 Please install via your preferred package manager. See [Installation](https://github.com/nvim-tree/nvim-tree.lua/wiki/Installation) for some specific package manager instructions.
 
 Major or minor versions may be specified via tags: `v` e.g. `v1` or `v.` e.g. `v1.23`
 
-## Quick Start
+# Quick Start
 
 Install the plugins via your package manager:
   `"nvim-tree/nvim-tree.lua"`
@@ -69,7 +69,7 @@ Install the plugins via your package manager:
 
 Disabling [netrw](https://neovim.io/doc/user/pi_netrw.html) is strongly advised, see [:help nvim-tree-netrw](doc/nvim-tree-lua.txt)
 
-### Setup
+## Setup
 
 Setup the plugin in your `init.lua`.
 
@@ -106,13 +106,13 @@ See [:help nvim-tree-setup](doc/nvim-tree-lua.txt) and [:help nvim-tree-config-d
   require("nvim-tree").setup(config)
 ```
 
-### Help
+## Help
 
 Open the tree:  `:NvimTreeOpen`
 
 Show the mappings:  `g?`
 
-### Custom Mappings
+## Custom Mappings
 
 [:help nvim-tree-mappings-default](doc/nvim-tree-lua.txt) are applied by default however you may customise via [:help nvim_tree.config](doc/nvim-tree-lua.txt) `{on_attach}` e.g.
 
@@ -140,7 +140,7 @@ Show the mappings:  `g?`
   })
 ```
 
-### Highlight Groups
+## Highlight Groups
 
 See [:help nvim-tree-highlight-groups](doc/nvim-tree-lua.txt)
 
@@ -158,7 +158,7 @@ applied at runtime. e.g.
   ]])
 ```
 
-## Commands
+# Commands
 
 See [:help nvim-tree-commands](doc/nvim-tree-lua.txt)
 
@@ -200,7 +200,7 @@ Some basic commands:
   })
 ```
 
-## Roadmap
+# Roadmap
 
 nvim-tree is stable and new major features will not be added. The focus is on existing user experience.
 
@@ -214,7 +214,7 @@ Development is focused on:
 - Enhancements to existing features
 - Multi-instance capabilities
 
-## API
+# API
 
 nvim-tree exposes a public API. This is non breaking, with additions made as necessary. See [:help nvim-tree-api](doc/nvim-tree-lua.txt)
 
@@ -224,19 +224,19 @@ Please raise a [feature request](https://github.com/nvim-tree/nvim-tree.lua/issu
 
 You may also subscribe to events that nvim-tree will dispatch in a variety of situations, see [:help nvim-tree-events](doc/nvim-tree-lua.txt)
 
-## Contributing
+# Contributing
 
 PRs are always welcome. See [CONTRIBUTING](CONTRIBUTING.md) and [wiki: Development](https://github.com/nvim-tree/nvim-tree.lua/wiki/Development) to get started.
 
 See [bug](https://github.com/nvim-tree/nvim-tree.lua/issues?q=is%3Aissue+is%3Aopen+label%3Abug) and [PR Please](https://github.com/nvim-tree/nvim-tree.lua/issues?q=is%3Aopen+is%3Aissue+label%3A%22PR+please%22) issues if you are looking for some work to get you started.
 
-## Screenshots
+# Screenshots
 
 See [Showcases](https://github.com/nvim-tree/nvim-tree.lua/wiki/Showcases) wiki page for examples of user's configurations with sources.
 
 Please add your own!
 
-## Team
+# Team
 
 * [@alex-courtis](https://github.com/alex-courtis) Arch Linux
 * [@gegoune](https://github.com/gegoune) macOS