From f994f619cdfe63939199fc0b9c36cf82caa949d1 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sun, 4 Jan 2026 15:18:29 +1100 Subject: [PATCH 01/40] 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 25883fd35d80a67083c6981005dc488b4fb1848a Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sun, 4 Jan 2026 16:25:31 +1100 Subject: [PATCH 02/40] 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 6aadaf3dc27..d8aad66ca72 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -45,6 +45,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| @@ -949,6 +950,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", @@ -2955,13 +2957,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* @@ -3444,5 +3446,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 0395699443d6f7fe5ca85055567da7ff01b4f8d5 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sun, 4 Jan 2026 16:47:10 +1100 Subject: [PATCH 03/40] 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 6a867ffc62c581a601dd40da2710bc7252f5e40d Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Mon, 5 Jan 2026 12:15:07 +1100 Subject: [PATCH 04/40] 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 dc0178b4a18..4f78a9b5084 100644 --- a/lua/nvim-tree.lua +++ b/lua/nvim-tree.lua @@ -621,7 +621,7 @@ local ACCEPTED_ENUMS = { }, } ----@param conf table|nil +---@param conf? nvim_tree.Config local function validate_options(conf) local msg @@ -726,7 +726,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 a8c1c9a0ae2..bb1d746a72c 100644 --- a/lua/nvim-tree/view.lua +++ b/lua/nvim-tree/view.lua @@ -437,7 +437,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 @@ -486,7 +486,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 fbfb09ff6762b5c4c6763cb78bdf07c4050f7995 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Mon, 5 Jan 2026 13:04:58 +1100 Subject: [PATCH 05/40] 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 d8aad66ca72..047dfc15a76 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -45,7 +45,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| @@ -3446,7 +3445,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 7634f72843956a180229cdabdb5d5fdc4a0ff936 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Mon, 5 Jan 2026 13:58:07 +1100 Subject: [PATCH 06/40] 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 047dfc15a76..300436c9c2f 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| @@ -3445,7 +3445,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* @@ -4262,6 +4262,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 aa24290a6555cc697522dcb7c14fecf6ea5de472 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Mon, 5 Jan 2026 15:30:00 +1100 Subject: [PATCH 07/40] 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 300436c9c2f..73af30ec7dc 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3525,101 +3525,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* @@ -4153,15 +4162,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 7c69cb50f724d050ee05bbda1616f9222f609e85 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Mon, 5 Jan 2026 15:51:49 +1100 Subject: [PATCH 08/40] 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 73af30ec7dc..c3cfc42d787 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3502,25 +3502,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* @@ -3766,12 +3785,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 2b5ab0789ccbddf8d5682aeeed9b54c221a67f47 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Mon, 5 Jan 2026 16:23:40 +1100 Subject: [PATCH 09/40] 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 c3cfc42d787..afff31b6548 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3450,96 +3450,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 0bcd9b5e69c46f932b581bdbcc73104f38ed81c9 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Mon, 5 Jan 2026 16:48:37 +1100 Subject: [PATCH 10/40] 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 afff31b6548..cb16ed8fb31 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3785,12 +3785,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* @@ -3822,17 +3826,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* @@ -4145,30 +4151,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 814dd26a94203cfdb42a429587168991967099cc Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Mon, 5 Jan 2026 17:31:32 +1100 Subject: [PATCH 11/40] 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 cb16ed8fb31..4f861aeca95 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3681,21 +3681,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* @@ -3787,8 +3793,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 @@ -3797,33 +3805,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 9b9263aded03d1160d8d6e3473ea75aadf0d30b2 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 11:53:34 +1100 Subject: [PATCH 12/40] 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 4f861aeca95..ad8c3ec8a8b 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3445,7 +3445,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* @@ -3780,16 +3780,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 @@ -4121,33 +4111,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: ~ @@ -4298,6 +4261,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 7653a99ab78d08fc1b7b942e1d57c1936260cd84 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 12:45:20 +1100 Subject: [PATCH 13/40] 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 374e56b453a4817d8ae1187a3ddd17130b59ece0 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 13:21:45 +1100 Subject: [PATCH 14/40] 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 ad8c3ec8a8b..557a0d4e16a 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3533,114 +3533,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: ~ @@ -4297,14 +4189,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 901c84fdfe3dbb556d890a77b68182a0d84b8046 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 13:26:52 +1100 Subject: [PATCH 15/40] 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 557a0d4e16a..644a99586eb 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3717,21 +3717,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: ~ @@ -4203,6 +4188,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 49045217c6032c32793f0c10ab097a31fe74db23 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 13:28:41 +1100 Subject: [PATCH 16/40] 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 644a99586eb..57f0e3cbbef 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3672,20 +3672,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` @@ -4208,6 +4194,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 3c51b1da4ef5761f0369ed968cde1e13cb8dd707 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 13:39:57 +1100 Subject: [PATCH 17/40] 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 57f0e3cbbef..18c78b4a375 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3572,29 +3572,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: ~ @@ -4212,6 +4189,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 d78692f1dd4c109531674ae350b5e23522277a72 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 13:44:01 +1100 Subject: [PATCH 18/40] 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 18c78b4a375..6b2a8e88a20 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3978,15 +3978,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: ~ @@ -4332,6 +4323,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 ec52820720232a18846f44c7607d4873d7feac61 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 13:49:14 +1100 Subject: [PATCH 19/40] 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 6b2a8e88a20..cbbb8d348a5 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3961,23 +3961,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: ~ @@ -4146,7 +4129,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` @@ -4193,8 +4176,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. @@ -4338,6 +4320,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 d9d970768f199a6451a2b16736921a1acb3d757f Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 13:51:36 +1100 Subject: [PATCH 20/40] 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 cbbb8d348a5..bfffebbfaf6 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3961,21 +3961,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: ~ @@ -4342,6 +4327,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 dca593b6f4123a9efdc9bf55b49092e8dfbb2dd6 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 13:53:20 +1100 Subject: [PATCH 21/40] 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 bfffebbfaf6..0a2b47e7b46 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3649,37 +3649,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: ~ @@ -4347,6 +4316,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 9dc17adc0f9d51af439fe37fbb12d72d4e1757bc Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 14:00:26 +1100 Subject: [PATCH 22/40] 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 0a2b47e7b46..168f159c435 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3649,21 +3649,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: ~ @@ -4296,6 +4281,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 4db3f9aea4f1ffe3a7000d92d5575af46b8be83c Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 14:15:30 +1100 Subject: [PATCH 23/40] 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 168f159c435..236fd9ff987 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3905,16 +3905,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: ~ @@ -4064,6 +4054,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 41cedf810b5781176a5d5f850a0300807369201a Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 14:36:44 +1100 Subject: [PATCH 24/40] 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 236fd9ff987..c0901a0d47b 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3641,14 +3641,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: ~ @@ -4226,8 +4218,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. @@ -4312,6 +4304,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 88154e28c21d98d073fa68b86bfedb9b93c8f55b Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 14:37:19 +1100 Subject: [PATCH 25/40] 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 c0901a0d47b..5b0560ccaba 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -4305,7 +4305,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 ea6dde70f987a5259cc3b03ce23c87231c092d8e Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 15:04:44 +1100 Subject: [PATCH 26/40] 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 5b0560ccaba..de755243fa8 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -4310,12 +4310,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 389259ba66bce44c28e3383f7e2cb235307d6324 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 15:32:19 +1100 Subject: [PATCH 27/40] 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 de755243fa8..cc413eb3ce7 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3533,45 +3533,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: ~ @@ -4068,6 +4029,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 dd7bd2ecf2b26b4c1f843c372c178a27208754c7 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 15:39:05 +1100 Subject: [PATCH 28/40] 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 cc413eb3ce7..440335bf82e 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -4378,156 +4378,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 db105af19e928f4e1cfe526f8b365f500c491baa Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 18:23:45 +1100 Subject: [PATCH 29/40] 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 440335bf82e..f1e1ed71719 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3533,50 +3533,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: ~ @@ -4090,6 +4046,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 297451ab110e4869b22814691820369e25126e9b Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Tue, 6 Jan 2026 18:29:15 +1100 Subject: [PATCH 30/40] 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 f1e1ed71719..c4d46d7e122 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -4145,8 +4145,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 6b1e838bd27997ebb974de546f22147fed9a261a Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Fri, 9 Jan 2026 17:28:38 +1100 Subject: [PATCH 31/40] 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 c4d46d7e122..9836682f269 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3533,31 +3533,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: ~ @@ -3985,6 +3960,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* @@ -4129,25 +4136,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 5833b2a4ea25809c9e00f574a96184084347e36d Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Fri, 9 Jan 2026 17:56:27 +1100 Subject: [PATCH 32/40] 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 9836682f269..cce488ab877 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3789,35 +3789,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: ~ @@ -3938,6 +3909,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 5877d20a6fd41c2578487a824a6da8b5cb280e7e Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sat, 10 Jan 2026 13:34:04 +1100 Subject: [PATCH 33/40] 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 cce488ab877..dd65917ebf4 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3863,31 +3863,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 048a5533df56705d839207f7d342c9cc6750d90a Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sat, 10 Jan 2026 15:06:54 +1100 Subject: [PATCH 34/40] 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 dd65917ebf4..dd74db4bf2e 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3448,6 +3448,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 @@ -3789,74 +3790,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` - ============================================================================== @@ -3899,6 +3832,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* @@ -4213,14 +4231,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 360d40519fb120ddedc60da86a48bc1b08c9c4eb Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sat, 10 Jan 2026 15:18:23 +1100 Subject: [PATCH 35/40] 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 dd74db4bf2e..31e3bfef392 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3838,17 +3838,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 @@ -3876,7 +3876,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| @@ -3907,12 +3907,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 e7733eef2d6ca82f8e8724ca9d5a55260fd563f8 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sat, 10 Jan 2026 16:12:43 +1100 Subject: [PATCH 36/40] 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 4f78a9b5084..d8ec57270a1 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 32b7a3c152e29f8e733ed8a159a8f5a0e1f11a01 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sat, 10 Jan 2026 16:22:36 +1100 Subject: [PATCH 37/40] 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 31e3bfef392..bbf479a5fc5 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3453,10 +3453,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. @@ -3478,12 +3477,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. @@ -3562,7 +3561,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"` @@ -3798,7 +3797,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` @@ -3819,7 +3818,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?`) @@ -3855,9 +3854,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 / @@ -3870,12 +3869,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`) @@ -3945,7 +3943,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. @@ -4039,26 +4037,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: ) @@ -4217,7 +4206,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: ~ @@ -4231,7 +4220,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 @@ -4251,7 +4240,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 @@ -4298,7 +4287,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 @@ -4331,7 +4320,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 @@ -4403,7 +4392,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 4b0458c64e6d8bc4a730bce10bd770b4a38fb3f6 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sat, 10 Jan 2026 17:20:48 +1100 Subject: [PATCH 38/40] 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 bbf479a5fc5..d0f7d519e73 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3660,48 +3660,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* @@ -3712,36 +3701,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 fa035d0dcbd0c8cb17a490a8c4a2bb24fae8501c Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sun, 11 Jan 2026 16:04:00 +1100 Subject: [PATCH 39/40] 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 d0f7d519e73..c3e850a8303 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3667,30 +3667,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* @@ -4040,10 +4040,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 e08b7dfe11ff392d0930724a139df06589f7eac7 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sun, 11 Jan 2026 16:49:39 +1100 Subject: [PATCH 40/40] 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 c3e850a8303..f85dab8e72c 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -3451,7 +3451,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, @@ -3534,48 +3534,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 @@ -3817,7 +3824,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. @@ -3894,7 +3901,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* @@ -3939,7 +3946,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. @@ -4006,8 +4013,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 @@ -4119,7 +4126,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: `{}`) @@ -4164,7 +4171,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. @@ -4262,7 +4269,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)