From 7eb61f53ae45835c08310b086fb4d55894a7abfa Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sun, 4 Jan 2026 15:18:29 +1100 Subject: [PATCH 01/96] 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 02/96] 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 03/96] 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 04/96] 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 05/96] 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 06/96] 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 07/96] 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 08/96] 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 09/96] 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 10/96] 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 11/96] 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 12/96] 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 13/96] 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 14/96] 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 15/96] 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 16/96] 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 17/96] 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 18/96] 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 19/96] 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 20/96] 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 21/96] 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 22/96] 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 23/96] 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 24/96] 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 25/96] 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 26/96] 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 27/96] 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 28/96] 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 29/96] 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 30/96] 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 31/96] 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 32/96] 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 33/96] 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 34/96] 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 35/96] 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 36/96] 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 37/96] 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 38/96] 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 39/96] 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 40/96] 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 41/96] 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 42/96] 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 43/96] 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 44/96] 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 45/96] 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 46/96] 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 47/96] 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 48/96] 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 49/96] 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 50/96] 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 51/96] 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 52/96] 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 53/96] 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 54/96] 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 55/96] 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 56/96] 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 57/96] 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 58/96] 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 59/96] 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 60/96] 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 61/96] 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 62/96] 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 63/96] 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 64/96] 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 65/96] 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 66/96] 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 67/96] 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 68/96] 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 69/96] 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 70/96] 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 71/96] 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 72/96] 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 73/96] 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 74/96] 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 75/96] 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 76/96] 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 77/96] 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 78/96] 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 79/96] 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 80/96] 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 81/96] 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 dc536aa43e4acabfd4b7ecf3b1091743ba6cdeb1 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Tue, 20 Jan 2026 16:19:08 +1100
Subject: [PATCH 82/96] 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 83/96] 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 84/96] 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 85/96] 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 86/96] 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 87/96] 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 88/96] 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 89/96] 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 bf3bda8023dc2d3f372df4abe742f4f37551f72f Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 22 Jan 2026 08:10:21 +1100
Subject: [PATCH 90/96] docs(#2934): tidy gitignore

---
 .gitignore | 1 -
 1 file changed, 1 deletion(-)

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
 *~

From ca2c70ff85a67656a8dfb82f21223fc74a11905e Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 22 Jan 2026 09:48:49 +1100
Subject: [PATCH 91/96] docs(#2934): tidy formatting

---
 Makefile                                           | 2 +-
 lua/nvim-tree.lua                                  | 2 +-
 lua/nvim-tree/_meta/config/experimental.lua        | 1 -
 lua/nvim-tree/_meta/config/filesystem_watchers.lua | 2 +-
 lua/nvim-tree/_meta/config/filters.lua             | 2 +-
 scripts/lintdoc.sh                                 | 1 -
 6 files changed, 4 insertions(+), 6 deletions(-)

diff --git a/Makefile b/Makefile
index 187dce385c0..78caba54713 100644
--- a/Makefile
+++ b/Makefile
@@ -44,7 +44,7 @@ help-update:
 #
 help-check: help-update
 	git diff --ignore-blank-lines --exit-code doc/nvim-tree-lua.txt
-	@scripts/lintdoc.sh
+	scripts/lintdoc.sh
 
 
 .PHONY: all lint style check luacheck style-check style-doc luals style-fix help-update help-check
diff --git a/lua/nvim-tree.lua b/lua/nvim-tree.lua
index b7ab856c0f0..eb6b20621e9 100644
--- a/lua/nvim-tree.lua
+++ b/lua/nvim-tree.lua
@@ -534,7 +534,7 @@ local DEFAULT_OPTS = { -- default-config-start
       watcher = false,
     },
   },
-}-- default-config-end
+} -- 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/experimental.lua b/lua/nvim-tree/_meta/config/experimental.lua
index ee46529632a..da8467cf0a3 100644
--- a/lua/nvim-tree/_meta/config/experimental.lua
+++ b/lua/nvim-tree/_meta/config/experimental.lua
@@ -14,4 +14,3 @@ error("Cannot require a meta file")
 --Buffers opened by nvim-tree will use with relative paths instead of absolute.
 --(default: false)
 --@field relative_path? boolean
-
diff --git a/lua/nvim-tree/_meta/config/filesystem_watchers.lua b/lua/nvim-tree/_meta/config/filesystem_watchers.lua
index 1db15b985fb..a9b6d19afd1 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")
 ---
 ---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}. 
+---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.
diff --git a/lua/nvim-tree/_meta/config/filters.lua b/lua/nvim-tree/_meta/config/filters.lua
index 812233e6bb2..37dc67b5840 100644
--- a/lua/nvim-tree/_meta/config/filters.lua
+++ b/lua/nvim-tree/_meta/config/filters.lua
@@ -57,4 +57,4 @@ error("Cannot require a meta file")
 ---@field custom? string[]|(fun(absolute_path: string): boolean)
 ---
 ---(default: `{}`)
----@field exclude? string[] 
+---@field exclude? string[]
diff --git a/scripts/lintdoc.sh b/scripts/lintdoc.sh
index 6b5b0a88d77..0b7c2bf150c 100755
--- a/scripts/lintdoc.sh
+++ b/scripts/lintdoc.sh
@@ -19,7 +19,6 @@ 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

From cbf864ee42c9b1efa3f12160981409b34af426b1 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 22 Jan 2026 11:57:00 +1100
Subject: [PATCH 92/96] docs(#2934): lint and check scripts, rewrite luals
 check script following upstream changes

---
 Makefile                      |  9 ++---
 scripts/gen_vimdoc_config.lua |  3 +-
 scripts/luals-check.sh        | 66 ++++++++++++++++++++---------------
 3 files changed, 44 insertions(+), 34 deletions(-)

diff --git a/Makefile b/Makefile
index 78caba54713..c9ef8a0119e 100644
--- a/Makefile
+++ b/Makefile
@@ -12,18 +12,19 @@ check: luals
 #
 # subtasks
 #
+# TODO #3241 ensure that decorator is checked - all meta should be valid
 luacheck:
-	luacheck --codes --quiet lua --exclude-files "**/_meta/**"
+	luacheck --codes --quiet lua --exclude-files "**/_meta/api_decorator.lua"
+	luacheck --codes --quiet scripts
 
-# --diagnosis-as-error does not function for workspace, hence we post-process the output
 style-check:
-	@scripts/luals-check.sh codestyle-check
+	scripts/luals-check.sh codestyle-check
 
 style-doc:
 	scripts/doc-comments.sh
 
 luals:
-	@scripts/luals-check.sh
+	scripts/luals-check.sh
 
 #
 # fixes
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index 3de0c684c3f..7ad5acdccf8 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -52,8 +52,7 @@ for _, m in ipairs(srcs) do
   srcs_by_name[name] = m
 end
 
----@diagnostic disable-next-line: undefined-doc-name
---- @type table
+-- @type table
 local config = {
   all = {
     filename = "nvim-tree-lua.txt",
diff --git a/scripts/luals-check.sh b/scripts/luals-check.sh
index 5c611b18b98..a57b4546403 100755
--- a/scripts/luals-check.sh
+++ b/scripts/luals-check.sh
@@ -1,55 +1,65 @@
 #!/usr/bin/env sh
 
-# Performs a lua-language-server check on all files.
-# luals-out/check.json will be produced on any issues, returning 1.
-# Outputs only check.json to stdout, all other messages to stderr, to allow jq etc.
+# Performs a lua-language-server check on all lua files.
 # $VIMRUNTIME specifies neovim runtime path, defaults to "/usr/share/nvim/runtime" if unset.
 #
 # Call with codestyle-check param to enable only codestyle-check
+#
+# lua-language-server is inconsisent about which parameters must be absolute paths therefore we pass every path as absolute
+
+if [ $# -eq 1 ] && [ "${1}" != "codestyle-check" ] || [ $# -gt 1 ] ; then
+	echo "usage: ${0} [codestyle-check]" 1>&2
+	exit 1
+fi
+
+DIR_NVT="${PWD}"
+
+if [ ! -f "${DIR_NVT}/scripts/luals-check.sh" ]; then
+	echo "Must be run from nvim-tree root" 1>&2
+	exit 1
+fi
 
 if [ -z "${VIMRUNTIME}" ]; then
 	export VIMRUNTIME="/usr/share/nvim/runtime"
+	echo "Defaulting to VIMRUNTIME=${VIMRUNTIME}"
+fi
+
+if [ ! -d "${VIMRUNTIME}" ]; then
+	echo "\$VIMRUNTIME=${VIMRUNTIME} not found" 1>&2
+	exit 1
 fi
 
-DIR_SRC="${PWD}/lua"
-DIR_OUT="${PWD}/luals-out"
-FILE_LUARC="${DIR_OUT}/luarc.json"
+DIR_OUT="${DIR_NVT}/luals-out"
+LUARC="${DIR_OUT}/luarc.json"
+RC=0
 
-# clear output
+# clear previous output
 rm -rf "${DIR_OUT}"
 mkdir "${DIR_OUT}"
 
+# create the luarc.json for the requested check
 case "${1}" in
 	"codestyle-check")
 		jq \
 			'.diagnostics.neededFileStatus[] = "None" | .diagnostics.neededFileStatus."codestyle-check" = "Any"' \
-			"${PWD}/.luarc.json" > "${FILE_LUARC}"
+			"${DIR_NVT}/.luarc.json" > "${LUARC}"
 
 		;;
 	*)
-		cp "${PWD}/.luarc.json" "${FILE_LUARC}"
+		cp "${DIR_NVT}/.luarc.json" "${LUARC}"
 		;;
 esac
 
-# execute inside lua directory to prevent luals itself from being checked
-OUT=$(lua-language-server --check="${DIR_SRC}" --configpath="${FILE_LUARC}" --checklevel=Information --logpath="${DIR_OUT}" --loglevel=error)
-RC=$?
-
-echo "${OUT}" >&2
+for SRC in lua scripts; do
+	DIR_SRC="${DIR_NVT}/${SRC}"
+	FILE_OUT="${DIR_OUT}/out.${SRC}.log"
+	echo "Checking ${SRC}/"
 
-if [ $RC -ne 0 ]; then
-	echo "failed with RC=$RC"
-	exit $RC
-fi
+	lua-language-server --check="${DIR_SRC}" --configpath="${LUARC}" --checklevel=Information --logpath="${DIR_OUT}" --loglevel=error 2>&1 | tee "${FILE_OUT}"
 
-# any output is a fail
-case "${OUT}" in
-	*Diagnosis\ completed,\ no\ problems\ found*)
-		exit 0
-		;;
-	*)
-		cat "${DIR_OUT}/check.json"
-		exit 1
-		;;
-esac
+	if ! grep --quiet "Diagnosis completed, no problems found" "${FILE_OUT}"; then
+		RC=1
+	fi
+done
 
+exit "${RC}"

From b25b8fcb79610c3951c7ba2bdef5c9c01067c90d Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 22 Jan 2026 12:05:29 +1100
Subject: [PATCH 93/96] docs(#2934): script tidying

---
 CONTRIBUTING.md       | 1 -
 scripts/gen_vimdoc.sh | 2 +-
 scripts/lintdoc.sh    | 4 +++-
 3 files changed, 4 insertions(+), 3 deletions(-)

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/scripts/gen_vimdoc.sh b/scripts/gen_vimdoc.sh
index 8af3aa0b49a..e9bb69dda88 100755
--- a/scripts/gen_vimdoc.sh
+++ b/scripts/gen_vimdoc.sh
@@ -19,7 +19,7 @@ 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"
+	echo "Must be run from nvim-tree root" 1>&2
 	exit 1
 fi
 
diff --git a/scripts/lintdoc.sh b/scripts/lintdoc.sh
index 0b7c2bf150c..7edcc5d1519 100755
--- a/scripts/lintdoc.sh
+++ b/scripts/lintdoc.sh
@@ -22,7 +22,7 @@ DIR_NVT="${PWD}"
 DIR_NVIM_SRC_DEF="/tmp/src/neovim-stable"
 
 if [ ! -f "${DIR_NVT}/scripts/lintdoc.sh" ]; then
-	echo "Must be run from nvim-tree root"
+	echo "Must be run from nvim-tree root" 1>&2
 	exit 1
 fi
 
@@ -38,6 +38,8 @@ if [ ! -d "${DIR_NVIM_SRC}" ]; then
 
 Nvim source is required to run ${0}
 
+The "make lintdoc" target will be executed, which needs to compile Nvim first.
+
 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}")

From fca4dbf70a0e9ecb8acce5db5e39c49ef3ee7b85 Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 22 Jan 2026 12:06:20 +1100
Subject: [PATCH 94/96] docs(#2934): add a temporary codestyle violation to
 test scripts

---
 lua/nvim-tree/_meta/api.lua | 2 +-
 lua/nvim-tree/enum.lua      | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/lua/nvim-tree/_meta/api.lua b/lua/nvim-tree/_meta/api.lua
index d6847940781..f4becf7ea0c 100644
--- a/lua/nvim-tree/_meta/api.lua
+++ b/lua/nvim-tree/_meta/api.lua
@@ -1,5 +1,5 @@
 ---@meta
-error("Cannot require a meta file")
+ error("Cannot require a meta file")
 
 --
 -- Nodes
diff --git a/lua/nvim-tree/enum.lua b/lua/nvim-tree/enum.lua
index e99082282ac..4910aa84964 100644
--- a/lua/nvim-tree/enum.lua
+++ b/lua/nvim-tree/enum.lua
@@ -1,4 +1,4 @@
-local M = {}
+ local M = {}
 
 ---Reason for filter in filter.lua
 ---@enum FILTER_REASON

From 595bc69e3d8833ed32d293043b5509103ff1f05e Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 22 Jan 2026 12:09:06 +1100
Subject: [PATCH 95/96] Revert "docs(#2934): add a temporary codestyle
 violation to test scripts"

This reverts commit fca4dbf70a0e9ecb8acce5db5e39c49ef3ee7b85.
---
 lua/nvim-tree/_meta/api.lua | 2 +-
 lua/nvim-tree/enum.lua      | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/lua/nvim-tree/_meta/api.lua b/lua/nvim-tree/_meta/api.lua
index f4becf7ea0c..d6847940781 100644
--- a/lua/nvim-tree/_meta/api.lua
+++ b/lua/nvim-tree/_meta/api.lua
@@ -1,5 +1,5 @@
 ---@meta
- error("Cannot require a meta file")
+error("Cannot require a meta file")
 
 --
 -- Nodes
diff --git a/lua/nvim-tree/enum.lua b/lua/nvim-tree/enum.lua
index 4910aa84964..e99082282ac 100644
--- a/lua/nvim-tree/enum.lua
+++ b/lua/nvim-tree/enum.lua
@@ -1,4 +1,4 @@
- local M = {}
+local M = {}
 
 ---Reason for filter in filter.lua
 ---@enum FILTER_REASON

From b9b75d3771e926cefa170a07f20dbc150776b45f Mon Sep 17 00:00:00 2001
From: Alexander Courtis 
Date: Thu, 22 Jan 2026 12:21:56 +1100
Subject: [PATCH 96/96] docs(#2934): remove class from config section headers

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

diff --git a/Makefile b/Makefile
index c9ef8a0119e..d04e92e94d1 100644
--- a/Makefile
+++ b/Makefile
@@ -44,8 +44,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/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index 7256cca56ac..477bce1392f 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -1850,7 +1850,7 @@ Example of function that can be passed: >lua
 <
 
 ==============================================================================
-Class: config                                               *nvim-tree-config*
+Config                                                      *nvim-tree-config*
 
 *nvim_tree.config*
     Arguments to pass to |nvim-tree-setup|.
@@ -1956,7 +1956,7 @@ Class: config                                               *nvim-tree-config*
 
 
 ==============================================================================
-Class: config.sort                                     *nvim-tree-config-sort*
+Config: sort                                           *nvim-tree-config-sort*
 
 *nvim_tree.config.sort*
     Sort files within a directory.
@@ -1996,7 +1996,7 @@ Class: config.sort                                     *nvim-tree-config-sort*
 
 
 ==============================================================================
-Class: config.view                                     *nvim-tree-config-view*
+Config: view                                           *nvim-tree-config-view*
 
 *nvim_tree.config.view*
     Configures the dimensions and appearance of the nvim-tree window.
@@ -2082,7 +2082,7 @@ Class: config.view                                     *nvim-tree-config-view*
 
 
 ==============================================================================
-Class: config.renderer                             *nvim-tree-config-renderer*
+Config: renderer                                   *nvim-tree-config-renderer*
 
 *nvim_tree.config.renderer*
     Controls the appearance of the tree.
@@ -2258,7 +2258,7 @@ Class: config.renderer                             *nvim-tree-config-renderer*
 
 
 ==============================================================================
-Class: config.hijack_directories         *nvim-tree-config-hijack-directories*
+Config: hijack_directories               *nvim-tree-config-hijack-directories*
 
 *nvim_tree.config.hijack_directories*
     Hijack directory buffers by replacing the directory buffer with the tree.
@@ -2276,7 +2276,7 @@ Class: config.hijack_directories         *nvim-tree-config-hijack-directories*
 
 
 ==============================================================================
-Class: config.update_focused_file       *nvim-tree-config-update-focused-file*
+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.
@@ -2308,7 +2308,7 @@ Class: config.update_focused_file       *nvim-tree-config-update-focused-file*
 
 
 ==============================================================================
-Class: config.system_open                       *nvim-tree-config-system-open*
+Config: system_open                             *nvim-tree-config-system-open*
 
 *nvim_tree.config.system_open*
     Open files or directories via the OS.
@@ -2332,7 +2332,7 @@ Class: config.system_open                       *nvim-tree-config-system-open*
 
 
 ==============================================================================
-Class: config.git                                       *nvim-tree-config-git*
+Config: git                                             *nvim-tree-config-git*
 
 *nvim_tree.config.git*
     Git operations are run in the background thus status may not immediately
@@ -2366,7 +2366,7 @@ Class: config.git                                       *nvim-tree-config-git*
 
 
 ==============================================================================
-Class: config.diagnostics                       *nvim-tree-config-diagnostics*
+Config: diagnostics                             *nvim-tree-config-diagnostics*
 
 *nvim_tree.config.diagnostics*
     Integrate with |lsp| or COC diagnostics.
@@ -2400,7 +2400,7 @@ Class: config.diagnostics                       *nvim-tree-config-diagnostics*
 
 
 ==============================================================================
-Class: config.modified                             *nvim-tree-config-modified*
+Config: modified                                   *nvim-tree-config-modified*
 
 *nvim_tree.config.modified*
     Indicate which files have unsaved modification. To see modified status in
@@ -2422,7 +2422,7 @@ Class: config.modified                             *nvim-tree-config-modified*
 
 
 ==============================================================================
-Class: config.filters                               *nvim-tree-config-filters*
+Config: filters                                     *nvim-tree-config-filters*
 
 *nvim_tree.config.filters*
     Filters may be applied to the tree to exlude the display of
@@ -2477,7 +2477,7 @@ Class: config.filters                               *nvim-tree-config-filters*
 
 
 ==============================================================================
-Class: config.live_filter                       *nvim-tree-config-live-filter*
+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
@@ -2495,7 +2495,7 @@ Class: config.live_filter                       *nvim-tree-config-live-filter*
 
 
 ==============================================================================
-Class: config.filesystem_watchers       *nvim-tree-config-filesystem-watchers*
+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
@@ -2521,7 +2521,7 @@ Class: config.filesystem_watchers       *nvim-tree-config-filesystem-watchers*
 
 
 ==============================================================================
-Class: config.actions                               *nvim-tree-config-actions*
+Config: actions                                     *nvim-tree-config-actions*
 
 *nvim_tree.config.actions*
 
@@ -2644,7 +2644,7 @@ Class: config.actions                               *nvim-tree-config-actions*
 
 
 ==============================================================================
-Class: config.trash                                   *nvim-tree-config-trash*
+Config: trash                                         *nvim-tree-config-trash*
 
 *nvim_tree.config.trash*
     Files may be trashed via an external command that must be installed on
@@ -2659,7 +2659,7 @@ Class: config.trash                                   *nvim-tree-config-trash*
 
 
 ==============================================================================
-Class: config.tab                                       *nvim-tree-config-tab*
+Config: tab                                             *nvim-tree-config-tab*
 
 *nvim_tree.config.tab*
 
@@ -2680,7 +2680,7 @@ Class: config.tab                                       *nvim-tree-config-tab*
 
 
 ==============================================================================
-Class: config.notify                                 *nvim-tree-config-notify*
+Config: notify                                       *nvim-tree-config-notify*
 
 *nvim_tree.config.notify*
     nvim-tree |vim.log.levels|
@@ -2699,7 +2699,7 @@ Class: config.notify                                 *nvim-tree-config-notify*
 
 
 ==============================================================================
-Class: config.bookmarks                           *nvim-tree-config-bookmarks*
+Config: bookmarks                                 *nvim-tree-config-bookmarks*
 
 *nvim_tree.config.bookmarks*
     Optionally {persist} bookmarks to a json file:
@@ -2713,7 +2713,7 @@ Class: config.bookmarks                           *nvim-tree-config-bookmarks*
 
 
 ==============================================================================
-Class: config.help                                     *nvim-tree-config-help*
+Config: help                                           *nvim-tree-config-help*
 
 *nvim_tree.config.help*
 
@@ -2723,7 +2723,7 @@ Class: config.help                                     *nvim-tree-config-help*
 
 
 ==============================================================================
-Class: config.ui                                         *nvim-tree-config-ui*
+Config: ui                                               *nvim-tree-config-ui*
 
 *nvim_tree.config.ui*
 
@@ -2743,7 +2743,7 @@ Class: config.ui                                         *nvim-tree-config-ui*
 
 
 ==============================================================================
-Class: config.experimental                     *nvim-tree-config-experimental*
+Config: experimental                           *nvim-tree-config-experimental*
 
 *nvim_tree.config.experimental*
     Experimental features that may become default or optional functionality.
@@ -2754,7 +2754,7 @@ Class: config.experimental                     *nvim-tree-config-experimental*
 
 
 ==============================================================================
-Class: config.log                                       *nvim-tree-config-log*
+Config: log                                             *nvim-tree-config-log*
 
 *nvim_tree.config.log*
     Log to a file `nvim-tree.log` in |stdpath()| `log`, usually
@@ -2790,7 +2790,7 @@ Class: config.log                                       *nvim-tree-config-log*
 
 
 ==============================================================================
-Config: default                                     *nvim-tree-default-config*
+Config: Default                                     *nvim-tree-default-config*
 
 Following is the default configuration, see |nvim_tree.config| for details. >lua
 
diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua
index 7ad5acdccf8..1b730a299c0 100644
--- a/scripts/gen_vimdoc_config.lua
+++ b/scripts/gen_vimdoc_config.lua
@@ -12,30 +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-default-config",             section = "Config: default",                   path = "./lua/nvim_tree/_meta/config/default.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-default-config",             section = "Config: Default",             path = "./lua/nvim_tree/_meta/config/default.lua", },
 }
 
 -- hydrate file names