diff --git a/.luacheckrc b/.luacheckrc index 267d0ce54ce..9155f6f4386 100644 --- a/.luacheckrc +++ b/.luacheckrc @@ -5,6 +5,7 @@ M.self = false M.ignore = { "631", -- max_line_length + "212", -- TODO #3088 make luacheck understand @meta } -- Global objects defined by the C code diff --git a/Makefile b/Makefile index 9b3b00cc71a..f8feb7fa15d 100644 --- a/Makefile +++ b/Makefile @@ -43,8 +43,8 @@ help-update: # --ignore-blank-lines is used as nightly has removed unnecessary blank lines that stable (0.11.5) currently inserts # help-check: help-update - git diff --ignore-blank-lines --exit-code doc/nvim-tree-lua.txt @scripts/lintdoc.sh + git diff --ignore-blank-lines --exit-code doc/nvim-tree-lua.txt .PHONY: all lint style check luacheck style-check style-doc luals style-fix help-update help-check diff --git a/README.md b/README.md index 057ebf9db96..2a9e68813d6 100644 --- a/README.md +++ b/README.md @@ -97,7 +97,7 @@ local function my_on_attach(bufnr) end -- default mappings - api.config.mappings.default_on_attach(bufnr) + api.map.default_on_attach(bufnr) -- custom mappings vim.keymap.set('n', '', api.tree.change_root_to_parent, opts('Up')) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index b055e7dabac..d7dbd9ec510 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -95,65 +95,65 @@ Open the tree: `:NvimTreeOpen` Show the mappings: `g?` -`` CD |nvim-tree-api.tree.change_root_to_node()| -`` Open: In Place |nvim-tree-api.node.open.replace_tree_buffer()| -`` Info |nvim-tree-api.node.show_info_popup()| -`` Rename: Omit Filename |nvim-tree-api.fs.rename_sub()| -`` Open: New Tab |nvim-tree-api.node.open.tab()| -`` Open: Vertical Split |nvim-tree-api.node.open.vertical()| -`` Open: Horizontal Split |nvim-tree-api.node.open.horizontal()| -`` Close Directory |nvim-tree-api.node.navigate.parent_close()| -`` Open |nvim-tree-api.node.open.edit()| -`` Delete |nvim-tree-api.fs.remove()| -`` Open Preview |nvim-tree-api.node.open.preview()| -`>` Next Sibling |nvim-tree-api.node.navigate.sibling.next()| -`<` Previous Sibling |nvim-tree-api.node.navigate.sibling.prev()| -`.` Run Command |nvim-tree-api.node.run.cmd()| -`-` Up |nvim-tree-api.tree.change_root_to_parent()| -`a` Create File Or Directory |nvim-tree-api.fs.create()| -`bd` Delete Bookmarked |nvim-tree-api.marks.bulk.delete()| -`bt` Trash Bookmarked |nvim-tree-api.marks.bulk.trash()| -`bmv` Move Bookmarked |nvim-tree-api.marks.bulk.move()| -`B` Toggle Filter: No Buffer |nvim-tree-api.tree.toggle_no_buffer_filter()| -`c` Copy |nvim-tree-api.fs.copy.node()| -`C` Toggle Filter: Git Clean |nvim-tree-api.tree.toggle_git_clean_filter()| -`[c` Prev Git |nvim-tree-api.node.navigate.git.prev()| -`]c` Next Git |nvim-tree-api.node.navigate.git.next()| -`d` Delete |nvim-tree-api.fs.remove()| -`D` Trash |nvim-tree-api.fs.trash()| -`E` Expand All |nvim-tree-api.tree.expand_all()| -`e` Rename: Basename |nvim-tree-api.fs.rename_basename()| -`]e` Next Diagnostic |nvim-tree-api.node.navigate.diagnostics.next()| -`[e` Prev Diagnostic |nvim-tree-api.node.navigate.diagnostics.prev()| -`F` Live Filter: Clear |nvim-tree-api.live_filter.clear()| -`f` Live Filter: Start |nvim-tree-api.live_filter.start()| -`g?` Help |nvim-tree-api.tree.toggle_help()| -`gy` Copy Absolute Path |nvim-tree-api.fs.copy.absolute_path()| -`ge` Copy Basename |nvim-tree-api.fs.copy.basename()| -`H` Toggle Filter: Dotfiles |nvim-tree-api.tree.toggle_hidden_filter()| -`I` Toggle Filter: Git Ignore |nvim-tree-api.tree.toggle_gitignore_filter()| -`J` Last Sibling |nvim-tree-api.node.navigate.sibling.last()| -`K` First Sibling |nvim-tree-api.node.navigate.sibling.first()| -`L` Toggle Group Empty |nvim-tree-api.node.open.toggle_group_empty()| -`M` Toggle Filter: No Bookmark |nvim-tree-api.tree.toggle_no_bookmark_filter()| -`m` Toggle Bookmark |nvim-tree-api.marks.toggle()| -`o` Open |nvim-tree-api.node.open.edit()| -`O` Open: No Window Picker |nvim-tree-api.node.open.no_window_picker()| -`p` Paste |nvim-tree-api.fs.paste()| -`P` Parent Directory |nvim-tree-api.node.navigate.parent()| -`q` Close |nvim-tree-api.tree.close()| -`r` Rename |nvim-tree-api.fs.rename()| -`R` Refresh |nvim-tree-api.tree.reload()| -`s` Run System |nvim-tree-api.node.run.system()| -`S` Search |nvim-tree-api.tree.search_node()| -`u` Rename: Full Path |nvim-tree-api.fs.rename_full()| -`U` Toggle Filter: Hidden |nvim-tree-api.tree.toggle_custom_filter()| -`W` Collapse All |nvim-tree-api.tree.collapse_all()| -`x` Cut |nvim-tree-api.fs.cut()| -`y` Copy Name |nvim-tree-api.fs.copy.filename()| -`Y` Copy Relative Path |nvim-tree-api.fs.copy.relative_path()| -`<2-LeftMouse>` Open |nvim-tree-api.node.open.edit()| -`<2-RightMouse>` CD |nvim-tree-api.tree.change_root_to_node()| +`` CD |nvim_tree.api.tree.change_root_to_node()| +`` Open: In Place |nvim_tree.api.node.open.replace_tree_buffer()| +`` Info |nvim_tree.api.node.show_info_popup()| +`` Rename: Omit Filename |nvim_tree.api.fs.rename_sub()| +`` Open: New Tab |nvim_tree.api.node.open.tab()| +`` Open: Vertical Split |nvim_tree.api.node.open.vertical()| +`` Open: Horizontal Split |nvim_tree.api.node.open.horizontal()| +`` Close Directory |nvim_tree.api.node.navigate.parent_close()| +`` Open |nvim_tree.api.node.open.edit()| +`` Delete |nvim_tree.api.fs.remove()| +`` Open Preview |nvim_tree.api.node.open.preview()| +`>` Next Sibling |nvim_tree.api.node.navigate.sibling.next()| +`<` Previous Sibling |nvim_tree.api.node.navigate.sibling.prev()| +`.` Run Command |nvim_tree.api.node.run.cmd()| +`-` Up |nvim_tree.api.tree.change_root_to_parent()| +`a` Create File Or Directory |nvim_tree.api.fs.create()| +`bd` Delete Bookmarked |nvim_tree.api.marks.bulk.delete()| +`bt` Trash Bookmarked |nvim_tree.api.marks.bulk.trash()| +`bmv` Move Bookmarked |nvim_tree.api.marks.bulk.move()| +`B` Toggle Filter: No Buffer |nvim_tree.api.tree.toggle_no_buffer_filter()| +`c` Copy |nvim_tree.api.fs.copy.node()| +`C` Toggle Filter: Git Clean |nvim_tree.api.tree.toggle_git_clean_filter()| +`[c` Prev Git |nvim_tree.api.node.navigate.git.prev()| +`]c` Next Git |nvim_tree.api.node.navigate.git.next()| +`d` Delete |nvim_tree.api.fs.remove()| +`D` Trash |nvim_tree.api.fs.trash()| +`E` Expand All |nvim_tree.api.tree.expand_all()| +`e` Rename: Basename |nvim_tree.api.fs.rename_basename()| +`]e` Next Diagnostic |nvim_tree.api.node.navigate.diagnostics.next()| +`[e` Prev Diagnostic |nvim_tree.api.node.navigate.diagnostics.prev()| +`F` Live Filter: Clear |nvim_tree.api.filter.live_filter.clear()| +`f` Live Filter: Start |nvim_tree.api.filter.live_filter.start()| +`g?` Help |nvim_tree.api.tree.toggle_help()| +`gy` Copy Absolute Path |nvim_tree.api.fs.copy.absolute_path()| +`ge` Copy Basename |nvim_tree.api.fs.copy.basename()| +`H` Toggle Filter: Dotfiles |nvim_tree.api.tree.toggle_hidden_filter()| +`I` Toggle Filter: Git Ignore |nvim_tree.api.tree.toggle_gitignore_filter()| +`J` Last Sibling |nvim_tree.api.node.navigate.sibling.last()| +`K` First Sibling |nvim_tree.api.node.navigate.sibling.first()| +`L` Toggle Group Empty |nvim_tree.api.node.open.toggle_group_empty()| +`M` Toggle Filter: No Bookmark |nvim_tree.api.tree.toggle_no_bookmark_filter()| +`m` Toggle Bookmark |nvim_tree.api.marks.toggle()| +`o` Open |nvim_tree.api.node.open.edit()| +`O` Open: No Window Picker |nvim_tree.api.node.open.no_window_picker()| +`p` Paste |nvim_tree.api.fs.paste()| +`P` Parent Directory |nvim_tree.api.node.navigate.parent()| +`q` Close |nvim_tree.api.tree.close()| +`r` Rename |nvim_tree.api.fs.rename()| +`R` Refresh |nvim_tree.api.tree.reload()| +`s` Run System |nvim_tree.api.node.run.system()| +`S` Search |nvim_tree.api.tree.search_node()| +`u` Rename: Full Path |nvim_tree.api.fs.rename_full()| +`U` Toggle Filter: Hidden |nvim_tree.api.tree.toggle_custom_filter()| +`W` Collapse All |nvim_tree.api.tree.collapse_all()| +`x` Cut |nvim_tree.api.fs.cut()| +`y` Copy Name |nvim_tree.api.fs.copy.filename()| +`Y` Copy Relative Path |nvim_tree.api.fs.copy.relative_path()| +`<2-LeftMouse>` Open |nvim_tree.api.node.open.edit()| +`<2-RightMouse>` CD |nvim_tree.api.tree.change_root_to_node()| ============================================================================== Quickstart: Custom Mappings *nvim-tree-quickstart-custom-mappings* @@ -169,7 +169,7 @@ via |nvim_tree.Config| {on_attach} e.g. >lua end -- default mappings - api.config.mappings.default_on_attach(bufnr) + api.map.default_on_attach(bufnr) -- custom mappings vim.keymap.set("n", "", api.tree.change_root_to_parent, opts("Up")) @@ -203,104 +203,75 @@ See |nvim-tree-highlight-groups| for details. ============================================================================== Commands *nvim-tree-commands* -*:NvimTreeOpen* +Commands may be executed with a `` (`!`) or take a `` string argument. - Opens the tree. See |nvim-tree-api.tree.open()| +*:NvimTreeOpen* |nvim_tree.api.tree.open()| >lua - Calls: `api.tree.open({ path = "" })` - -*:NvimTreeClose* - - Closes the tree. See |nvim-tree-api.tree.close()| - - Calls: `api.tree.close()` - -*:NvimTreeToggle* - - Open or close the tree. See |nvim-tree-api.tree.toggle()| - - Calls: `api.tree.toggle({ path = "", find_file = false, update_root = false, focus = true, })` - -*:NvimTreeFocus* - - Open the tree if it is closed, and then focus on the tree. - - See |nvim-tree-api.tree.open()| - - Calls: `api.tree.open()` - -*:NvimTreeRefresh* - - Refresh the tree. See |nvim-tree-api.tree.reload()| - - Calls: `api.tree.reload()` - -*:NvimTreeFindFile* - - The command will change the cursor in the tree for the current bufname. - - It will also open the leafs of the tree leading to the file in the buffer - (if you opened a file with something else than the NvimTree, like `fzf` or - `:split`) - - Invoke with a bang `:NvimTreeFindFile!` to update the root. - - See |nvim-tree-api.tree.find_file()| - - Calls: `api.tree.find_file({ update_root = , open = true, focus = true, })` + require("nvim-tree.api").tree.open({ + path = "" + }) +< +*:NvimTreeClose* |nvim_tree.api.tree.close()| >lua -*:NvimTreeFindFileToggle* + require("nvim-tree.api").tree.close() +< +*:NvimTreeToggle* |nvim_tree.api.tree.toggle()| >lua - close the tree or change the cursor in the tree for the current bufname, - similar to combination of |:NvimTreeToggle| and |:NvimTreeFindFile|. Takes an - optional path argument. + require("nvim-tree.api").tree.toggle({ + path = "", + find_file = false, + update_root = false, + focus = true, + }) +< +*:NvimTreeFocus* |nvim_tree.api.tree.open()| >lua - Invoke with a bang `:NvimTreeFindFileToggle!` to update the root. + require("nvim-tree.api").tree.open() +< +*:NvimTreeRefresh* |nvim_tree.api.tree.reload()| >lua - See |nvim-tree-api.tree.toggle()| + require("nvim-tree.api").tree.reload() +< +*:NvimTreeFindFile* |nvim_tree.api.tree.find_file()| >lua - Calls: `api.tree.toggle({ path = "", update_root = , find_file = true, focus = true, })` + require("nvim-tree.api").tree.find_file({ + open = true, + update_root = "", + focus = true, + }) +< +*:NvimTreeFindFileToggle* |nvim_tree.api.tree.toggle()| >lua -*:NvimTreeClipboard* + require("nvim-tree.api").tree.toggle({ + path = "", + find_file = true, + update_root = "", + focus = true, + }) +< +*:NvimTreeClipboard* |nvim_tree.api.fs.print_clipboard()| >lua - Print clipboard content for both cut and copy + require("nvim-tree.api").fs.print_clipboard() +< +*:NvimTreeCollapse* |nvim_tree.api.tree.collapse_all()| >lua - See |nvim-tree-api.fs.print_clipboard()| + require("nvim-tree.api").tree.collapse_all({ + keep_buffers = false + }) +< +*:NvimTreeCollapseKeepBuffers* |nvim_tree.api.tree.collapse_all()| >lua - Calls: `api.fs.print_clipboard()` + require("nvim-tree.api").tree.collapse_all({ + keep_buffers = true + }) +< +*:NvimTreeHiTest* |nvim_tree.api.health.hi_test()| >lua + require("nvim-tree.api").health.hi_test() +< *:NvimTreeResize* - Resize the NvimTree window to the given size. Example: `:NvimTreeResize 50` - resizes the window to the width of 50. If the size starts with "+" or "-" it - adds or removes the given value to the current window width. - Example `:NvimTreeResize -20` removes the value 20 from the current width. And - `:NvimTreeResize +20` adds the value 20 to the current width. - -*:NvimTreeCollapse* - - Collapses the nvim-tree recursively. - - See |nvim-tree-api.tree.collapse_all()| - - Calls: `api.tree.collapse_all({ keep_buffers = false })` - -*:NvimTreeCollapseKeepBuffers* - - Collapses the nvim-tree recursively, but keep the directories open, which are - used in an open buffer. - - See |nvim-tree-api.tree.collapse_all()| - - Calls: `api.tree.collapse_all({ keep_buffers = true })` - -*:NvimTreeHiTest* - - Show nvim-tree highlight groups similar to `:so $VIMRUNTIME/syntax/hitest.vim` - - See |nvim-tree-api.diagnostics.hi_test()| - - Calls: `api.diagnostics.hi_test()` +Columns integer argument is absolute (e.g. `40`) or a delta (e.g. `-5`, `+5`) ============================================================================== Setup *nvim-tree-setup* @@ -604,2468 +575,2397 @@ Following is the default configuration. See |nvim_tree.Config| for details. >lua < ============================================================================== -API *nvim-tree-api* - -Nvim-tree's public API can be used to access features. e.g. >lua - local api = require("nvim-tree.api") - api.tree.toggle() -< -This module exposes stable functionalities, it is advised to use this in order -to avoid breaking configurations due to internal breaking changes. +Mappings *nvim-tree-mappings* -The api is separated in multiple modules, which can be accessed with -`api..` +Mappings are set via the |nvim_tree.Config| {on_attach} function, which is run upon +creating the nvim-tree buffer. Mappings are usually |nvim-tree-api| functions +however may be your own. -Functions accepting {node} as their first argument will use the node under the -cursor when that argument is not present or nil. +When {on_attach} is not a function, |nvim-tree-mappings-default| will be used. -============================================================================== -API: Tree *nvim-tree-api.tree* +Active mappings may be viewed via HELP, default `g?`. The mapping's description +is used when displaying HELP. -tree.open({opts}) *nvim-tree-api.tree.open()* - Open the tree, focusing it if already open. +The `on_attach` function is passed the `bufnr` of nvim-tree. Use +|vim.keymap.set()| or |nvim_set_keymap()| to define mappings as usual. e.g. >lua - Parameters: ~ - • {opts} (table) optional parameters - - Options: ~ - • {path} (string) root directory for the tree - • {current_window} (boolean) open the tree in the current window - • {winid} (number) open the tree in the specified |winid|, - overrides {current_window} - • {find_file} (boolean) find the current buffer - • {update_root} (boolean) requires {find_file}, see - |nvim_tree.Config.UpdateFocusedFile| {update_root} - -tree.toggle({opts}) *nvim-tree-api.tree.toggle()* - Open or close the tree. + local function my_on_attach(bufnr) + local api = require("nvim-tree.api") - Parameters: ~ - • {opts} (table) optional parameters - - Options: ~ - • {path} (string) root directory for the tree - • {current_window} (boolean) open the tree in the current window - • {winid} (number) open the tree in the specified |winid|, - overrides {current_window} - • {find_file} (boolean) find the current buffer - • {update_root} (boolean) requires {find_file}, see - |nvim_tree.Config.UpdateFocusedFile| {update_root} - • {focus} (boolean) focus the tree when opening, default true - -tree.close() *nvim-tree-api.tree.close()* - Close the tree, affecting all tabs as per |nvim_tree.Config.Tab.Sync| {close} - -tree.close_in_this_tab() *nvim-tree-api.tree.close_in_this_tab()* - Close the tree in this tab only. + local function opts(desc) + return { desc = "nvim-tree: " .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true } + end -tree.close_in_all_tabs() *nvim-tree-api.tree.close_in_all_tabs()* - Close the tree in all tabs. + -- copy default mappings here from defaults in next section + vim.keymap.set("n", "", api.tree.change_root_to_node, opts("CD")) + vim.keymap.set("n", "", api.node.open.replace_tree_buffer, opts("Open: In Place")) + --- + -- OR use all default mappings + api.map.default_on_attach(bufnr) -tree.focus() *nvim-tree-api.tree.focus()* - Focus the tree, opening it if necessary. - Retained for compatibility, use |nvim-tree-api.tree.open()| with no arguments instead. + -- remove a default + vim.keymap.del("n", "", { buffer = bufnr }) -tree.reload() *nvim-tree-api.tree.reload()* - Refresh the tree. Does nothing if closed. + -- override a default + vim.keymap.set("n", "", api.tree.reload, opts("Refresh")) -tree.resize({opts}) *nvim-tree-api.tree.resize()* - Resize the tree, persisting the new size. - Resets to |nvim_tree.Config.View| {width} when no {opts} provided. - See |:NvimTreeResize| + -- add your mappings + vim.keymap.set("n", "?", api.tree.toggle_help, opts("Help")) + --- + end - Parameters: ~ - • {opts} (table) optional parameters + require("nvim-tree").setup({ + --- + on_attach = my_on_attach, + --- + }) +< +Single left mouse mappings can be achieved via ``. - Options: ~ - • {width} (table) new |nvim_tree.Config.View| {width} value - • {absolute} (number) set the width - • {relative} (number) increase or decrease the width +Single right / middle mouse mappings will require changes to |'mousemodel'| or |'mouse'|. - Only one option is supported, in the priority order above. - {absolute} and {relative} do nothing when {width} is a function. +|vim.keymap.set()| {rhs} is a `(function|string)` thus it may be necessary to +define your own function to map complex functionality e.g. >lua -tree.change_root({path}) *nvim-tree-api.tree.change_root()* - Change the tree's root to a path. + local function print_node_path() + local api = require("nvim-tree.api") + local node = api.tree.get_node_under_cursor() + print(node.absolute_path) + end - Parameters: ~ - • {path} (string) absolute or relative path + -- on_attach + vim.keymap.set("n", "", print_node_path, opts("Print Path")) +< +============================================================================== +Mappings: Default *nvim-tree-mappings-default* - *nvim-tree-api.tree.change_root_to_node()* -tree.change_root_to_node({node}) - Change the tree's root to a folder node or the parent of a file node. +In the absence of an |nvim_tree.Config| {on_attach} function, the following +defaults will be applied. - Parameters: ~ - • {node} (Node) folder or file +You are encouraged to copy these to your {on_attach} function. >lua - *nvim-tree-api.tree.change_root_to_parent()* -tree.change_root_to_parent({node}) - Change the tree's root to the parent of a node. + local api = require("nvim-tree.api") - Parameters: ~ - • {node} (Node) folder or file + local function opts(desc) + return { desc = "nvim-tree: " .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true } + end -tree.get_node_under_cursor() *nvim-tree-api.tree.get_node_under_cursor()* - Retrieve the currently focused node. + -- BEGIN_DEFAULT_ON_ATTACH + vim.keymap.set("n", "", api.tree.change_root_to_node, opts("CD")) + vim.keymap.set("n", "", api.node.open.replace_tree_buffer, opts("Open: In Place")) + vim.keymap.set("n", "", api.node.show_info_popup, opts("Info")) + vim.keymap.set("n", "", api.fs.rename_sub, opts("Rename: Omit Filename")) + vim.keymap.set("n", "", api.node.open.tab, opts("Open: New Tab")) + vim.keymap.set("n", "", api.node.open.vertical, opts("Open: Vertical Split")) + vim.keymap.set("n", "", api.node.open.horizontal, opts("Open: Horizontal Split")) + vim.keymap.set("n", "", api.node.navigate.parent_close, opts("Close Directory")) + vim.keymap.set("n", "", api.node.open.edit, opts("Open")) + vim.keymap.set("n", "", api.fs.remove, opts("Delete")) + vim.keymap.set("n", "", api.node.open.preview, opts("Open Preview")) + vim.keymap.set("n", ">", api.node.navigate.sibling.next, opts("Next Sibling")) + vim.keymap.set("n", "<", api.node.navigate.sibling.prev, opts("Previous Sibling")) + vim.keymap.set("n", ".", api.node.run.cmd, opts("Run Command")) + vim.keymap.set("n", "-", api.tree.change_root_to_parent, opts("Up")) + vim.keymap.set("n", "a", api.fs.create, opts("Create File Or Directory")) + vim.keymap.set("n", "bd", api.marks.bulk.delete, opts("Delete Bookmarked")) + vim.keymap.set("n", "bt", api.marks.bulk.trash, opts("Trash Bookmarked")) + vim.keymap.set("n", "bmv", api.marks.bulk.move, opts("Move Bookmarked")) + vim.keymap.set("n", "B", api.tree.toggle_no_buffer_filter, opts("Toggle Filter: No Buffer")) + vim.keymap.set("n", "c", api.fs.copy.node, opts("Copy")) + vim.keymap.set("n", "C", api.tree.toggle_git_clean_filter, opts("Toggle Filter: Git Clean")) + vim.keymap.set("n", "[c", api.node.navigate.git.prev, opts("Prev Git")) + vim.keymap.set("n", "]c", api.node.navigate.git.next, opts("Next Git")) + vim.keymap.set("n", "d", api.fs.remove, opts("Delete")) + vim.keymap.set("n", "D", api.fs.trash, opts("Trash")) + vim.keymap.set("n", "E", api.tree.expand_all, opts("Expand All")) + vim.keymap.set("n", "e", api.fs.rename_basename, opts("Rename: Basename")) + vim.keymap.set("n", "]e", api.node.navigate.diagnostics.next, opts("Next Diagnostic")) + vim.keymap.set("n", "[e", api.node.navigate.diagnostics.prev, opts("Prev Diagnostic")) + vim.keymap.set("n", "F", api.filter.live_filter.clear, opts("Live Filter: Clear")) + vim.keymap.set("n", "f", api.filter.live_filter.start, opts("Live Filter: Start")) + vim.keymap.set("n", "g?", api.tree.toggle_help, opts("Help")) + vim.keymap.set("n", "gy", api.fs.copy.absolute_path, opts("Copy Absolute Path")) + vim.keymap.set("n", "ge", api.fs.copy.basename, opts("Copy Basename")) + vim.keymap.set("n", "H", api.tree.toggle_hidden_filter, opts("Toggle Filter: Dotfiles")) + vim.keymap.set("n", "I", api.tree.toggle_gitignore_filter, opts("Toggle Filter: Git Ignore")) + vim.keymap.set("n", "J", api.node.navigate.sibling.last, opts("Last Sibling")) + vim.keymap.set("n", "K", api.node.navigate.sibling.first, opts("First Sibling")) + vim.keymap.set("n", "L", api.node.open.toggle_group_empty, opts("Toggle Group Empty")) + vim.keymap.set("n", "M", api.tree.toggle_no_bookmark_filter, opts("Toggle Filter: No Bookmark")) + vim.keymap.set("n", "m", api.marks.toggle, opts("Toggle Bookmark")) + vim.keymap.set("n", "o", api.node.open.edit, opts("Open")) + vim.keymap.set("n", "O", api.node.open.no_window_picker, opts("Open: No Window Picker")) + vim.keymap.set("n", "p", api.fs.paste, opts("Paste")) + vim.keymap.set("n", "P", api.node.navigate.parent, opts("Parent Directory")) + vim.keymap.set("n", "q", api.tree.close, opts("Close")) + vim.keymap.set("n", "r", api.fs.rename, opts("Rename")) + vim.keymap.set("n", "R", api.tree.reload, opts("Refresh")) + vim.keymap.set("n", "s", api.node.run.system, opts("Run System")) + vim.keymap.set("n", "S", api.tree.search_node, opts("Search")) + vim.keymap.set("n", "u", api.fs.rename_full, opts("Rename: Full Path")) + vim.keymap.set("n", "U", api.tree.toggle_custom_filter, opts("Toggle Filter: Hidden")) + vim.keymap.set("n", "W", api.tree.collapse_all, opts("Collapse All")) + vim.keymap.set("n", "x", api.fs.cut, opts("Cut")) + vim.keymap.set("n", "y", api.fs.copy.filename, opts("Copy Name")) + vim.keymap.set("n", "Y", api.fs.copy.relative_path, opts("Copy Relative Path")) + vim.keymap.set("n", "<2-LeftMouse>", api.node.open.edit, opts("Open")) + vim.keymap.set("n", "<2-RightMouse>", api.tree.change_root_to_node, opts("CD")) + -- END_DEFAULT_ON_ATTACH +< +Alternatively, you may apply these default mappings from your |nvim_tree.Config| {on_attach} via +|nvim_tree.api.map.default_on_attach()| e.g. >lua - Return: ~ - node or nil if tree is not visible + local function my_on_attach(bufnr) + local api = require("nvim-tree.api") -tree.get_nodes() *nvim-tree-api.tree.get_nodes()* - Retrieve a hierarchical list of all the nodes. This is a cloned list for - reference purposes only and should not be passed into other API functions. + local function opts(desc) + return { desc = "nvim-tree: " .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true } + end - Return: ~ - table of nodes + api.map.default_on_attach(bufnr) -tree.find_file({opts}) *nvim-tree-api.tree.find_file()* - Find and focus a file or folder in the tree. Finds current buffer unless - otherwise specified. + -- your removals and mappings go here + end +< - Parameters: ~ - • {opts} (table) optional parameters +============================================================================== +Icons And Highlighting *nvim-tree-icons-highlighting* - Options: ~ - • {buf} (string|number) absolute/relative path OR bufnr to find - • {open} (boolean) open the tree if necessary - • {current_window} (boolean) requires {open}, open in the current window - • {winid} (number) open the tree in the specified |winid|, - overrides {current_window} - • {update_root} (boolean) see |nvim_tree.Config.UpdateFocusedFile| {update_root} - • {focus} (boolean) focus the tree +Icons may be displayed before files and directories. -tree.search_node() *nvim-tree-api.tree.search_node()* - Open the search dialogue as per the search_node action. +Additional icons and highlighting may be displayed to indicate various states +for files and and directories. -tree.collapse_all({opts}) *nvim-tree-api.tree.collapse_all()* - Collapse the tree. +Highlighting is additive, with higher precedence overriding lower. - Parameters: ~ - • {opts} (table) optional parameters +|nvim_tree.Config.Renderer| {decorators} controls which highlighting is +applied and its precedence. See |nvim-tree-decorators| for information on +creating custom decorators. +< +`ICON` + Enable via |nvim_tree.Config.Renderer.Icons.Show - Options: ~ - • {keep_buffers} (boolean) do not collapse nodes with open buffers. +`REQUIRES` + Feature must be enabled to show icons and highlighting. -tree.expand_all({node}, {opts}) *nvim-tree-api.tree.expand_all()* - Recursively expand all nodes under the tree root or specified folder. +`PLACEMENT` *nvim_tree.Config.Renderer.Icons.Placement* + Where to place the icon: |nvim_tree.Config.Renderer.Icons| {_placement} + • `before`: before file/folder, after the file/folders icons + • `after`: after file/folder + • `signcolumn`: far left, requires |nvim_tree.Config.View| {signcolumn}. + • `right_align`: far right - Parameters: ~ - • {node} (Node|nil) folder - • {opts} (ApiTreeExpandOpts) optional parameters +`HIGHLIGHT` *nvim_tree.Config.Renderer.Highlight* + What should be highlighted: |nvim_tree.Config.Renderer| {highlight_} + • `none`: no highlighting + • `icon`: icon only + • `name`: name only + • `all`: icon and name - Options: ~ - • {expand_until} ((fun(expansion_count: integer, node: Node?): boolean)?) - Return true if {node} should be expanded. - {expansion_count} is the total number of folders expanded. +`DEVICONS` + Glyphs and their colors will be overridden by optional plugin: + `nvim-tree/nvim-web-devicons` |nvim_tree.Config.Renderer.Icons.WebDevicons| - *nvim-tree-api.tree.toggle_enable_filters()* -tree.toggle_enable_filters() - Toggle |nvim_tree.Config.Filters| {enable} all filters. +`GLYPHS` + Icon glyphs definitions. - *nvim-tree-api.tree.toggle_gitignore_filter()* -tree.toggle_gitignore_filter() - Toggle |nvim_tree.Config.Filters| {git_ignored} filter. +`GROUPS` + Applicable highlight groups: |nvim-tree-highlight-groups| - *nvim-tree-api.tree.toggle_git_clean_filter()* -tree.toggle_git_clean_filter() - Toggle |nvim_tree.Config.Filters| {git_clean} filter. +Some defaults noted. In ascending order of default highlight precedence: - *nvim-tree-api.tree.toggle_no_buffer_filter()* -tree.toggle_no_buffer_filter() - Toggle |nvim_tree.Config.Filters| {no_buffer} filter. +`WHAT ICON REQUIRES PLACEMENT HIGHLIGHT GLYPHS DEVICONS GROUPS` +File Icon {file} Y - - - |nvim_tree.Config.Renderer.Icons.Glyphs| {default} Y `NvimTreeNormal`, `NvimTreeFileIcon` +Folder Icon {folder} Y - - - |nvim_tree.Config.Renderer.Icons.Glyphs.Folder| Y `NvimTree*FolderName`, `NvimTree*FolderIcon` +Git Status {git} Y |nvim_tree.Config.Git| {git_placement} `"before"` {highlight_git} `"none"` |nvim_tree.Config.Renderer.Icons.Glyphs.Git| N `NvimTreeGit*` +|bufloaded()| - - - {highlight_opened_files}`"none"` - N ` NvimTreeOpened*` +Dotfiles {hidden} N - {hidden_placement} `"after"` {highlight_hidden} `"none"` |nvim_tree.Config.Renderer.Icons.Glyphs| {hidden} N `NvimTreeHidden*` +|'modified'| {modified} Y |nvim_tree.Config.Modified| {modified_placement} `"after"` {highlight_modified} `"none"` |nvim_tree.Config.Renderer.Icons.Glyphs| {modified} N `NvimTreeModified*` +Bookmarked {bookmarks} Y - {bookmarks_placement} `"signcolumn"` {highlight_bookmarks} `"none"` |nvim_tree.Config.Renderer.Icons.Glyphs| {bookmark} N `NvimTreeBookmark*` +Diag Status {diagnostics}Y |nvim_tree.Config.Diagnostics| {diagnostics_placement}`"signcolumn"` {highlight_diagnostics} `"none" ` |nvim_tree.Config.Diagnostics.Icons| N `NvimTreeDiagnostic*` +Cut/Copied - - - {highlight_clipboard} `"name"` - N `NvimTreeCutHL`, `NvimTreeCopiedHL` - *nvim-tree-api.tree.toggle_no_bookmark_filter()* -tree.toggle_no_bookmark_filter() - Toggle |nvim_tree.Config.Filters| {no_bookmark} filter. - *nvim-tree-api.tree.toggle_custom_filter()* -tree.toggle_custom_filter() - Toggle |nvim_tree.Config.Filters| {custom} filter. +============================================================================== +Highlight Groups *nvim-tree-highlight-groups* - *nvim-tree-api.tree.toggle_hidden_filter()* -tree.toggle_hidden_filter() - Toggle |nvim_tree.Config.Filters| {dotfiles} filter. +All the following highlight groups can be configured by hand. Aside from +`NvimTreeWindowPicker`, it is not advised to colorize the background of these +groups. -tree.toggle_help() *nvim-tree-api.tree.toggle_help()* - Toggle help view. - -tree.is_tree_buf({bufnr}) *nvim-tree-api.tree.is_tree_buf()* - Checks if a buffer is an nvim-tree. - - Parameters: ~ - • {bufnr} (number|nil) buffer handle, 0 or nil for current buffer +Example |:highlight| >vim + :hi NvimTreeSymlink guifg=blue gui=bold,underline +< +It is recommended to enable |'termguicolors'| for the more pleasant 24-bit +colours. - Return: ~ - (boolean) buffer is an nvim-tree buffer +To view the nvim-tree highlight groups run |:NvimTreeHiTest| -tree.is_visible({opts}) *nvim-tree-api.tree.is_visible()* - Checks if nvim-tree is visible on the current, specified or any tab. +To view all active highlight groups run `:so $VIMRUNTIME/syntax/hitest.vim` +as per |:highlight| - Parameters: ~ - • {opts} (table) optional parameters +The `*HL` groups are additive as per |nvim_tree.Config.Renderer| precedence. +Only present attributes will clobber each other. +In this example a modified, opened file will have magenta text, with cyan +undercurl: >vim + :hi NvimTreeOpenedHL guifg=magenta guisp=red gui=underline + :hi NvimTreeModifiedFileHL guisp=cyan gui=undercurl +< +To prevent usage of a highlight: - Options: ~ - • {tabpage} (number) as per |nvim_get_current_tabpage()| - • {any_tabpage} (boolean) visible on any tab, default false +- Before setup: link the group to `Normal` e.g. >vim + :hi NvimTreeExecFile Normal +< +- After setup: link it to `NONE`, to override the default link e.g. >lua + :hi! link NvimTreeExecFile NONE +< +============================================================================== +Highlight Groups: Default *nvim-tree-highlight-groups-default* - Return: ~ - (boolean) nvim-tree is visible +|:highlight-link| `default` or |:highlight-default| define the groups on setup: -tree.winid({opts}) *nvim-tree-api.tree.winid()* - Retrieve the winid of the open tree. +Standard: > + NvimTreeNormal Normal + NvimTreeNormalFloat NormalFloat + NvimTreeNormalNC NormalFloat - Parameters: ~ - • {opts} (table) optional parameters + NvimTreeLineNr LineNr + NvimTreeWinSeparator WinSeparator + NvimTreeEndOfBuffer EndOfBuffer + NvimTreePopup Normal + NvimTreeSignColumn NvimTreeNormal - Options: ~ - • {tabpage} (number|nil) tabpage, 0 or nil for current, default nil + NvimTreeCursorColumn CursorColumn + NvimTreeCursorLine CursorLine + NvimTreeCursorLineNr CursorLineNr - Return: ~ - (number) winid or nil if tree is not visible + NvimTreeStatusLine StatusLine + NvimTreeStatusLineNC StatusLineNC +< +File Text: > + NvimTreeExecFile SpellCap + NvimTreeImageFile SpellCap + NvimTreeSpecialFile SpellCap + NvimTreeSymlink SpellCap +< +Folder Text: > + NvimTreeRootFolder Title + NvimTreeFolderName Directory + NvimTreeEmptyFolderName Directory + NvimTreeOpenedFolderName Directory + NvimTreeSymlinkFolderName Directory +< +File Icons: > + NvimTreeFileIcon NvimTreeNormal + NvimTreeSymlinkIcon NvimTreeNormal +< +Folder Icons: > + NvimTreeFolderIcon guifg=#8094b4 ctermfg=Blue + NvimTreeOpenedFolderIcon NvimTreeFolderIcon + NvimTreeClosedFolderIcon NvimTreeFolderIcon + NvimTreeFolderArrowClosed NvimTreeIndentMarker + NvimTreeFolderArrowOpen NvimTreeIndentMarker +< +Indent: > + NvimTreeIndentMarker NvimTreeFileIcon +< +Picker: > + NvimTreeWindowPicker guifg=#ededed guibg=#4493c8 gui=bold ctermfg=White ctermbg=Cyan +< +Live Filter: > + NvimTreeLiveFilterPrefix PreProc + NvimTreeLiveFilterValue ModeMsg +< +Clipboard: > + NvimTreeCopiedHL SpellRare + NvimTreeCutHL SpellBad +< +Bookmarks: > + NvimTreeBookmarkIcon NvimTreeFolderIcon + NvimTreeBookmarkHL SpellLocal +< +Modified: > + NvimTreeModifiedIcon Type + NvimTreeModifiedFileHL NvimTreeModifiedIcon + NvimTreeModifiedFolderHL NvimTreeModifiedIcon +Hidden: > + NvimTreeModifiedIcon Conceal + NvimTreeModifiedFileHL NvimTreeHiddenIcon + NvimTreeModifiedFolderHL NvimTreeHiddenFileHL +< +Hidden Display: > + NvimTreeHiddenDisplay Conceal +< +Opened: > + NvimTreeOpenedHL Special +< +Git Icon: > + NvimTreeGitDeletedIcon Statement + NvimTreeGitDirtyIcon Statement + NvimTreeGitIgnoredIcon Comment + NvimTreeGitMergeIcon Constant + NvimTreeGitNewIcon PreProc + NvimTreeGitRenamedIcon PreProc + NvimTreeGitStagedIcon Constant +< +Git File File Highlight: > + NvimTreeGitFileDeletedHL NvimTreeGitDeletedIcon + NvimTreeGitFileDirtyHL NvimTreeGitDirtyIcon + NvimTreeGitFileIgnoredHL NvimTreeGitIgnoredIcon + NvimTreeGitFileMergeHL NvimTreeGitMergeIcon + NvimTreeGitFileNewHL NvimTreeGitNewIcon + NvimTreeGitFileRenamedHL NvimTreeGitRenamedIcon + NvimTreeGitFileStagedHL NvimTreeGitStagedIcon +< +Git Folder Folder Highlight: > + NvimTreeGitFolderDeletedHL NvimTreeGitFileDeletedHL + NvimTreeGitFolderDirtyHL NvimTreeGitFileDirtyHL + NvimTreeGitFolderIgnoredHL NvimTreeGitFileIgnoredHL + NvimTreeGitFolderMergeHL NvimTreeGitFileMergeHL + NvimTreeGitFolderNewHL NvimTreeGitFileNewHL + NvimTreeGitFolderRenamedHL NvimTreeGitFileRenamedHL + NvimTreeGitFolderStagedHL NvimTreeGitFileStagedHL +< +Diagnostics Icon: > + NvimTreeDiagnosticErrorIcon DiagnosticError + NvimTreeDiagnosticWarnIcon DiagnosticWarn + NvimTreeDiagnosticInfoIcon DiagnosticInfo + NvimTreeDiagnosticHintIcon DiagnosticHint +< +Diagnostics File Highlight: > + NvimTreeDiagnosticErrorFileHL DiagnosticUnderlineError + NvimTreeDiagnosticWarnFileHL DiagnosticUnderlineWarn + NvimTreeDiagnosticInfoFileHL DiagnosticUnderlineInfo + NvimTreeDiagnosticHintFileHL DiagnosticUnderlineHint +< +Diagnostics Folder Highlight: > + NvimTreeDiagnosticErrorFolderHL NvimTreeDiagnosticErrorFileHL + NvimTreeDiagnosticWarnFolderHL NvimTreeDiagnosticWarnFileHL + NvimTreeDiagnosticInfoFolderHL NvimTreeDiagnosticInfoFileHL + NvimTreeDiagnosticHintFolderHL NvimTreeDiagnosticHintFileHL +< ============================================================================== -API: File System *nvim-tree-api.fs* - -fs.create({node}) *nvim-tree-api.fs.create()* - Prompt to create a file or directory. Use a trailing `/` for a directory. - Multiple directories/files may be created e.g. `foo/bar/baz` - - Parameters: ~ - • {node} (Node|nil) parent, uses the parent of a file. - -fs.remove({node}) *nvim-tree-api.fs.remove()* - Delete a file or folder from the file system. - - Parameters: ~ - • {node} (Node|nil) file or folder +Events *nvim-tree-events* -fs.trash({node}) *nvim-tree-api.fs.trash()* - Trash a file or folder as per |nvim_tree.Config.Trash| +nvim-tree will dispatch events whenever an action is made. These events can be +subscribed to through handler functions. This allows for even further +customization of nvim-tree. - Parameters: ~ - • {node} (Node|nil) file or folder +A handler for an event is just a function which receives one argument, the +payload of the event. The payload is different for each event type. Refer +to |nvim_tree_registering_handlers| for more information. -fs.rename_node({node}) *nvim-tree-api.fs.rename_node()* - Prompt to rename a file or folder. +*nvim_tree_registering_handlers* - Parameters: ~ - • {node} (Node|nil) file or folder +Handlers are registered by calling |nvim_tree.api.events.subscribe()| function +with an |nvim_tree_events_kind|. -fs.rename({node}) *nvim-tree-api.fs.rename()* - Prompt to rename a file or folder by name. +e.g. handler for node renamed: >lua - Parameters: ~ - • {node} (Node|nil) file or folder + local api = require("nvim-tree.api") + local Event = api.events.Event -fs.rename_basename({node}) *nvim-tree-api.fs.rename_basename()* - Prompt to rename a file or folder by name with extension omitted. + api.events.subscribe(Event.NodeRenamed, function(data) + print("Node renamed from " .. data.old_name .. " to " .. data.new_name) + end) +< +*nvim_tree_events_kind* - Parameters: ~ - • {node} (Node|nil) file or folder +- Event.Ready + When NvimTree has been initialized. + • Note: Handler takes no parameter. -fs.rename_sub({node}) *nvim-tree-api.fs.rename_sub()* - Prompt to rename a file or folder by absolute path with name omitted. +- Event.TreePreOpen + Invoked before the window and buffer for NvimTree are created + or opened. Before `Event.TreeOpen` + • Note: Handler takes no parameter. - Parameters: ~ - • {node} (Node|nil) file or folder +- Event.TreeOpen + Invoked after the NvimTree is opened. + • Note: Handler takes no parameter. -fs.rename_full({node}) *nvim-tree-api.fs.rename_full()* - Prompt to rename a file or folder by absolute path. +- Event.TreeClose + Invoked after the NvimTree is closed, but before the window is + closed. Dispatched on |WinClosed| event for NvimTree window. + • Note: Handler takes no parameter. - Parameters: ~ - • {node} (Node|nil) file or folder +- Event.Resize - When NvimTree is resized. + handler parameters: ~ + size: `number` size of the view in columns. -fs.cut({node}) *nvim-tree-api.fs.cut()* - Cut a file or folder to the nvim-tree clipboard. +- Event.WillRenameNode + • Note: A node can either be a file or a directory. + handler parameters: ~ + {old_name} `{string}` Absolute path to the old node location. + {new_name} `{string}` Absolute path to the new node location. - Parameters: ~ - • {node} (Node|nil) file or folder +- Event.NodeRenamed + • Note: A node can either be a file or a directory. + handler parameters: ~ + {old_name} `{string}` Absolute path to the old node location. + {new_name} `{string}` Absolute path to the new node location. -fs.paste({node}) *nvim-tree-api.fs.paste()* - Paste a file or folder from the nvim-tree clipboard. +- Event.FileCreated + handler parameters: ~ + {fname} `{string}` Absolute path to the created file - Parameters: ~ - • {node} (Node|nil) destination folder, uses the parent of a file. +- Event.WillCreateFile + handler parameters: ~ + {fname} `{string}` Absolute path to the file to be + created -fs.copy.node({node}) *nvim-tree-api.fs.copy.node()* - Copy a file or folder from the nvim-tree clipboard. +- Event.FileRemoved + handler parameters: ~ + {fname} `{string}` Absolute path to the removed file. - Parameters: ~ - • {node} (Node|nil) file or folder +- Event.WillRemoveFile + handler parameters: ~ + {fname} `{string}` Absolute path to the file to be + removed -fs.copy.absolute_path({node}) *nvim-tree-api.fs.copy.absolute_path()* - Copy the absolute path of a file or folder to the system clipboard. +- Event.FolderCreated + handler parameters: ~ + {folder_name} `{string}` Absolute path to the created folder. - Parameters: ~ - • {node} (Node|nil) file or folder +- Event.FolderRemoved + handler parameters: ~ + {folder_name} `{string}` Absolute path to the removed folder. -fs.copy.basename({node}) *nvim-tree-api.fs.copy.basename()* - Copy the name of a file or folder with extension omitted to the system - clipboard. +- Event.TreeAttachedPost + Invoked after the tree's buffer has been created and mappings + have been applied: |nvim-tree-mappings| or |nvim_tree.Config| {on_attach} + handler parameters: ~ + {buf} `{number} `API buffer handle (buffer number) - Parameters: ~ - • {node} (Node|nil) file or folder +- Event.TreeRendered + Invoked every time the tree is redrawn. Normally this event + happens after `Event.TreeOpen` except that handlers of this + one will have access to the tree buffer populated with the + final content. + handler parameters: ~ + {bufnr} `{number} `API buffer handle (buffer number) + {winnr} `{number} `API window handle (window number) -fs.copy.filename({node}) *nvim-tree-api.fs.copy.filename()* - Copy the name of a file or folder to the system clipboard. +*nvim_tree_events_startup* - Parameters: ~ - • {node} (Node|nil) file or folder +There are two special startup events in the form of User autocommands: -fs.copy.relative_path({node}) *nvim-tree-api.fs.copy.relative_path()* - Copy the path of a file or folder relative to the tree root to the system - clipboard. +`NvimTreeRequired` first `require("nvim-tree")` +`NvimTreeSetup` `setup({})` completed - Parameters: ~ - • {node} (Node|nil) file or folder +Immediately before firing: a global variable of the same name will be set to a +value of 1. -fs.clear_clipboard() *nvim-tree-api.fs.clear_clipboard()* - Clear the nvim-tree clipboard. - -fs.print_clipboard() *nvim-tree-api.fs.print_clipboard()* - Print the contents of the nvim-tree clipboard. +Example subscription: >lua + vim.api.nvim_create_autocmd("User", { + pattern = "NvimTreeRequired", + callback = function(data) + --- + end, + }) +< ============================================================================== -API: Node *nvim-tree-api.node* - -node.open.edit({node}, {opts}) *nvim-tree-api.node.open.edit()* - File: open as per |nvim_tree.Config.Actions.OpenFile| - Folder: expand or collapse - Root: change directory up - - Parameters: ~ - • {node} (Node|nil) file or folder - • {opts} (table) optional parameters - - Options: ~ - • {quit_on_open} (boolean) quits the tree when opening the file - • {focus} (boolean) keep focus in the tree when opening the file - - *nvim-tree-api.node.open.replace_tree_buffer()* -node.open.replace_tree_buffer({node}) - |nvim-tree-api.node.open.edit()|, file will be opened in place: in the - nvim-tree window. - - *nvim-tree-api.node.open.no_window_picker()* -node.open.no_window_picker({node}, {opts}) - |nvim-tree-api.node.open.edit()|, window picker will be bypassed. - - Parameters: ~ - • {node} (Node|nil) file or folder - • {opts} (table) optional parameters - - Options: ~ - • {quit_on_open} (boolean) quits the tree when opening the file - • {focus} (boolean) keep focus in the tree when opening the file - -node.open.vertical({node}, {opts}) *nvim-tree-api.node.open.vertical()* - |nvim-tree-api.node.open.edit()|, file will be opened in a new vertical split. - - Parameters: ~ - • {node} (Node|nil) file or folder - • {opts} (table) optional parameters - - Options: ~ - • {quit_on_open} (boolean) quits the tree when opening the file - • {focus} (boolean) keep focus in the tree when opening the file - - *nvim-tree-api.node.open.vertical_no_picker()* -node.open.vertical_no_picker({node}, {opts}) - |nvim-tree-api.node.open.vertical()|, window picker will be bypassed. - - Parameters: ~ - • {node} (Node|nil) file or folder - • {opts} (table) optional parameters - - Options: ~ - • {quit_on_open} (boolean) quits the tree when opening the file - • {focus} (boolean) keep focus in the tree when opening the file +Prompts *nvim-tree-prompts* -node.open.horizontal({node}, {opts}) *nvim-tree-api.node.open.horizontal()* - |nvim-tree-api.node.open.edit()|, file will be opened in a new horizontal split. +Some NvimTree actions use the builtin |vim.ui.select()| prompt API for +confirmations when the |nvim_tree.Config| {select_prompts} option is set. - Parameters: ~ - • {node} (Node|nil) file or folder - • {opts} (table) optional parameters +The API accepts the optional `kind` key as part of the {opts} parameter, which +can can be used to identify the type of prompt, to allow user side +configurations for different types of prompts. - Options: ~ - • {quit_on_open} (boolean) quits the tree when opening the file - • {focus} (boolean) keep focus in the tree when opening the file +- `nvimtree_overwrite_rename` + overwrite or rename during |nvim_tree.api.fs.paste()| - *nvim-tree-api.node.open.horizontal_no_picker()* -node.open.horizontal_no_picker({node}, {opts}) - |nvim-tree-api.node.open.horizontal()|, window picker will be bypassed. +- `nvimtree_remove` + delete during |nvim_tree.api.fs.remove()| - Parameters: ~ - • {node} (Node|nil) file or folder - • {opts} (table) optional parameters +- `nvimtree_trash` + send to trash during |nvim_tree.api.fs.trash()| - Options: ~ - • {quit_on_open} (boolean) quits the tree when opening the file - • {focus} (boolean) keep focus in the tree when opening the file +- `nvimtree_bulk_delete` + delete all bookmarked during |nvim_tree.api.marks.bulk.delete()| - *nvim-tree-api.node.open.toggle_group_empty()* -node.open.toggle_group_empty({node}, {opts}) - Toggle |nvim_tree.Config.Renderer| {group_empty} for a specific folder. - Does nothing on files. - Needs |nvim_tree.Config.Renderer| {group_empty} set. +- `nvimtree_bulk_trash` + send all bookmarked to trash during |nvim_tree.api.marks.bulk.trash()| - Parameters: ~ - • {node} (Node|nil) file or folder - • {opts} (table) optional parameters +============================================================================== +Decorators *nvim-tree-decorators* - Options: ~ - • {quit_on_open} (boolean) quits the tree when opening the file - • {focus} (boolean) keep focus in the tree when opening the file +Highlighting and icons for nodes are provided by Decorators. You may provide +your own in addition to the builtin decorators. -node.open.drop({node}) *nvim-tree-api.node.open.drop()* - Switch to window with selected file if it exists. - Open file otherwise. - See: `:h :drop`. +Decorators may: +- Add icons +- Set highlight group for the name or icons +- Override node icon - File: open file using `:drop` - Folder: expand or collapse - Root: change directory up +Create a `nvim_tree.api.decorator.UserDecorator` class and register it with +precedence via |nvim_tree.Config.Renderer| {decorators} -node.open.tab({node}, {opts}) *nvim-tree-api.node.open.tab()* - |nvim-tree-api.node.open.edit()|, file will be opened in a new tab. +See |nvim-tree-decorator-example| - Parameters: ~ - • {node} (Node|nil) file or folder - • {opts} (table) optional parameters +============================================================================== +Decorators: Example *nvim-tree-decorator-example* - Options: ~ - • {quit_on_open} (boolean) quits the tree when opening the file - • {focus} (boolean) keep focus in the tree when opening the file +A decorator class for nodes named "example", overridind all builtin decorators +except for Cut. - *nvim-tree-api.node.open.tab_drop()* -node.open.tab_drop({node}) - Switch to tab containing window with selected file if it exists. - Open file in new tab otherwise. +- Highlights node name with `IncSearch` +- Creates two icons `"1"` and `"2"` placed after the node name, highlighted with + `DiffAdd` and `DiffText` +- Replaces the node icon with `"N"`, highlighted with `Error ` - File: open file using `tab :drop` - Folder: expand or collapse - Root: change directory up +Create a class file `~/.config/nvim/lua/my-decorator.lua` -node.open.preview({node}, {opts}) *nvim-tree-api.node.open.preview()* - |nvim-tree-api.node.open.edit()|, file buffer will have |'bufhidden'| set to `delete`. +Require and register it during |nvim-tree-setup|: +>lua + local MyDecorator = require("my-decorator") - Parameters: ~ - • {node} (Node|nil) file or folder - • {opts} (table) optional parameters + require("nvim-tree").setup({ + renderer = { + decorators = { + "Git", + "Open", + "Hidden", + "Modified", + "Bookmark", + "Diagnostics", + "Copied", + MyDecorator, + "Cut", + }, + }, + }) +< +Contents of `my-decorator.lua`: +>lua + ---@class (exact) MyDecorator: nvim_tree.api.decorator.UserDecorator + ---@field private my_icon1 nvim_tree.api.HighlightedString + ---@field private my_icon2 nvim_tree.api.HighlightedString + ---@field private my_icon_node nvim_tree.api.HighlightedString + ---@field private my_highlight_group string + local MyDecorator = require("nvim-tree.api").decorator.UserDecorator:extend() - Options: ~ - • {quit_on_open} (boolean) quits the tree when opening the file - • {focus} (boolean) keep focus in the tree when opening the file + ---Mandatory constructor :new() will be called once per tree render, with no arguments. + function MyDecorator:new() + self.enabled = true + self.highlight_range = "name" + self.icon_placement = "after" - *nvim-tree-api.node.open.preview_no_picker()* -node.open.preview_no_picker({node}, {opts}) - |nvim-tree-api.node.open.edit()|, file buffer will have |'bufhidden'| set to `delete`. - window picker will be bypassed. + -- create your icons and highlights once, applied to every node + self.my_icon1 = { str = "1", hl = { "DiffAdd" } } + self.my_icon2 = { str = "2", hl = { "DiffText" } } + self.my_icon_node = { str = "N", hl = { "Error" } } + self.my_highlight_group = "IncSearch" - Parameters: ~ - • {node} (Node|nil) file or folder - • {opts} (table) optional parameters - - Options: ~ - • {quit_on_open} (boolean) quits the tree when opening the file - • {focus} (boolean) keep focus in the tree when opening the file - -node.navigate.git.next({node}) *nvim-tree-api.node.navigate.git.next()* - Navigate to the next item showing git status. - - *nvim-tree-api.node.navigate.git.next_recursive()* -node.navigate.git.next_recursive({node}) - Alternative to |nvim-tree-api.node.navigate.git.next()| that navigates to - the next file showing git status, recursively. - Needs |nvim_tree.Config.Git| {show_on_dirs} set. - - *nvim-tree-api.node.navigate.git.next_skip_gitignored()* -node.navigate.git.next_skip_gitignored({node}) - Same as |nvim-tree-api.node.navigate.git.next()|, but skips gitignored files. - -node.navigate.git.prev({node}) *nvim-tree-api.node.navigate.git.prev()* - Navigate to the previous item showing git status. - - *nvim-tree-api.node.navigate.git.prev_recursive()* -node.navigate.git.prev_recursive({node}) - Alternative to |nvim-tree-api.node.navigate.git.prev()| that navigates to - the previous file showing git status, recursively. - Needs |nvim_tree.Config.Git| {show_on_dirs} set. - - *nvim-tree-api.node.navigate.git.prev_skip_gitignored()* -node.navigate.git.prev_skip_gitignored({node}) - same as |nvim-tree-api.node.navigate.git.prev()|, but skips gitignored files. - - *nvim-tree-api.node.navigate.diagnostics.next()* -node.navigate.diagnostics.next({node}) - Navigate to the next item showing diagnostic status. - - *nvim-tree-api.node.navigate.diagnostics.next_recursive()* -node.navigate.diagnostics.next_recursive({node}) - Alternative to |nvim-tree-api.node.navigate.diagnostics.next()| that - navigates to the next file showing diagnostic status, recursively. - Needs |nvim_tree.Config.Diagnostics| {show_on_dirs} set. - - *nvim-tree-api.node.navigate.diagnostics.prev()* -node.navigate.diagnostics.prev({node}) - Navigate to the next item showing diagnostic status. - - *nvim-tree-api.node.navigate.diagnostics.prev_recursive()* -node.navigate.diagnostics.prev_recursive({node}) - Alternative to |nvim-tree-api.node.navigate.diagnostics.prev()| that - navigates to the previous file showing diagnostic status, recursively. - Needs |nvim_tree.Config.Diagnostics| {show_on_dirs} set. - - *nvim-tree-api.node.navigate.opened.next()* -node.navigate.opened.next({node}) - Navigate to the next |bufloaded()| item. - See |nvim_tree.Config.Renderer| {highlight_opened_files} - - *nvim-tree-api.node.navigate.opened.prev()* -node.navigate.opened.prev({node}) - Navigate to the previous |bufloaded()| item. - See |nvim_tree.Config.Renderer| {highlight_opened_files} - - *nvim-tree-api.node.navigate.sibling.next()* -node.navigate.sibling.next({node}) - Navigate to the next node in the current node's folder, wraps. - - *nvim-tree-api.node.navigate.sibling.prev()* -node.navigate.sibling.prev({node}) - Navigate to the previous node in the current node's folder, wraps. - - *nvim-tree-api.node.navigate.sibling.first()* -node.navigate.sibling.first({node}) - Navigate to the first node in the current node's folder. - - *nvim-tree-api.node.navigate.sibling.last()* -node.navigate.sibling.last({node}) - Navigate to the last node in the current node's folder. - - *nvim-tree-api.node.navigate.parent()* -node.navigate.parent({node}) - Navigate to the parent folder of the current node. - - *nvim-tree-api.node.navigate.parent_close()* -node.navigate.parent_close({node}) - |nvim-tree-api.node.navigate.parent()|, closing that folder. - -node.show_info_popup({node}) *nvim-tree-api.node.show_info_popup()* - Open a popup window showing: fullpath, size, accessed, modified, created. - -node.run.cmd({node}) *nvim-tree-api.node.run.cmd()* - Enter |cmdline| with the full path of the node and the cursor at the start - of the line. - -node.run.system({node}) *nvim-tree-api.node.run.system()* - Execute |nvim_tree.Config.SystemOpen| - -node.buffer.delete({node}, {opts}) *nvim-tree-api.node.buffer.delete()* - Deletes node's related buffer, if one exists. - Executes |:bdelete| or |:bdelete|! + -- Define the icon signs only once + -- Only needed if you are using icon_placement = "signcolumn" + -- self:define_sign(self.my_icon1) + -- self:define_sign(self.my_icon2) + end - Parameters: ~ - • {node} (Node|nil) file or folder - • {opts} (table) optional parameters + ---Override node icon + ---@param node nvim_tree.api.Node + ---@return nvim_tree.api.HighlightedString? icon_node + function MyDecorator:icon_node(node) + if node.name == "example" then + return self.my_icon_node + else + return nil + end + end - Options: ~ - • {force} (boolean) delete even if buffer is modified, default false + ---Return two icons for DecoratorIconPlacement "after" + ---@param node nvim_tree.api.Node + ---@return nvim_tree.api.HighlightedString[]? icons + function MyDecorator:icons(node) + if node.name == "example" then + return { self.my_icon1, self.my_icon2, } + else + return nil + end + end -node.buffer.wipe({node}, {opts}) *nvim-tree-api.node.buffer.wipe()* - Wipes node's related buffer, if one exists. - Executes |:bwipe| or |:bwipe|! + ---Exactly one highlight group for DecoratorHighlightRange "name" + ---@param node nvim_tree.api.Node + ---@return string? highlight_group + function MyDecorator:highlight_group(node) + if node.name == "example" then + return self.my_highlight_group + else + return nil + end + end - Parameters: ~ - • {node} (Node|nil) file or folder - • {opts} (table) optional parameters + return MyDecorator +< +============================================================================== +OS Specific Restrictions *nvim-tree-os-specific* - Options: ~ - • {force} (boolean) wipe even if buffer is modified, default false +Windows WSL and PowerShell +- Trash is synchronized +- Executable file detection is disabled as this is non-performant and can + freeze Nvim +- Some filesystem watcher error related to permissions will not be reported -node.expand({node}, {opts}) *nvim-tree-api.node.expand()* - Recursively expand all nodes under a directory or a file's parent - directory. +============================================================================== +netrw *nvim-tree-netrw* - Parameters: ~ - • {node} (Node|nil) file or folder - • {opts} (ApiTreeExpandOpts) optional parameters +|netrw| is a standard Nvim plugin that is enabled by default. It provides, +amongst other functionality, a file/directory browser. - Options: ~ - • {expand_until} ((fun(expansion_count: integer, node: Node?): boolean)?) - Return true if {node} should be expanded. - {expansion_count} is the total number of folders expanded. +It interferes with nvim-tree and the intended user experience is nvim-tree +replacing the |netrw| browser. -node.collapse({node}, {opts}) *nvim-tree-api.node.collapse()* - Collapse the tree under a directory or a file's parent directory. +It is strongly recommended to disable |netrw|. As it is a bundled plugin it +must be disabled manually at the start of your `init.lua` as per |netrw-noload|: >lua - Parameters: ~ - • {node} (Node|nil) file or folder - • {opts} (table) optional parameters + vim.g.loaded_netrw = 1 + vim.g.loaded_netrwPlugin = 1 +< +There are many |netrw| features beyond the file browser. If you want to +keep using |netrw| without its browser features please ensure: - Options: ~ - • {keep_buffers} (boolean) do not collapse nodes with open buffers. +|nvim_tree.Config| {disable_netrw}` = false` +|nvim_tree.Config| {hijack_netrw}` = true` ============================================================================== -API: Git *nvim-tree-api.git* +Legacy *nvim-tree-legacy* -git.reload() *nvim-tree-api.git.reload()* - Update the git status of the entire tree. +Breaking refactors have been made however the legacy versions will be silently +migrated and used. +There are no plans to remove this migration. ============================================================================== -API: Events *nvim-tree-api.events* - - *nvim-tree-api.events.subscribe()* -events.subscribe({event_type}, {callback}) - Register a handler for an event, see |nvim-tree-events| +Legacy: Config *nvim-tree-legacy-config* - Parameters: ~ - • {event_type} (string) |nvim-tree-api.events.Event| - • {callback} (function) see |nvim_tree_events_kind| for parameters - -events.Event *nvim-tree-api.events.Event* - String enum: |nvim_tree_events_kind| +Legacy config is translated to the current, making type and value changes as +needed. +`update_cwd` |nvim_tree.Config| {sync_root_with_cwd} +`update_focused_file.update_cwd` |nvim_tree.Config.UpdateFocusedFile| {update_root} +`open_on_tab` |nvim_tree.Config.Tab.Sync| {open} +`ignore_buf_on_tab_change` |nvim_tree.Config.Tab.Sync| {ignore} +`renderer.root_folder_modifier` |nvim_tree.Config.Renderer| {root_folder_label} +`update_focused_file.debounce_delay` |nvim_tree.Config.View| {debounce_delay} +`trash.require_confirm` |nvim_tree.Config.UI.Confirm| {trash} +`view.adaptive_size` |nvim_tree.Config.View| {width} +`sort_by` |nvim_tree.Config.Sort| {sorter} +`git.ignore` |nvim_tree.Config.Filters| {git_ignored} +`renderer.icons.webdev_colors` |nvim_tree.Config.Renderer.Icons.WebDevicons.File| {color} +`renderer.icons.padding` |nvim_tree.Config.Renderer.Icons.Padding| {icon} ============================================================================== -API: Live Filter *nvim-tree-api.live_filter* +Legacy: API *nvim-tree-legacy-api* -live_filter.start() *nvim-tree-api.live_filter.start()* - Enter |nvim-tree-api.live_filter| mode. - Opens an input window with |filetype| `"NvimTreeFilter"` +Some API functions have been refactored however the previous function will +continue to be available. -live_filter.clear() *nvim-tree-api.live_filter.clear()* - Exit |nvim-tree-api.live_filter| mode. +`api.config.mappings.get_keymap` |nvim_tree.api.map.get_keymap()| +`api.config.mappings.get_keymap_default` |nvim_tree.api.map.get_keymap_default()| +`api.config.mappings.default_on_attach` |nvim_tree.api.map.default_on_attach()| -============================================================================== -API: Marks *nvim-tree-api.marks* - -marks.get({node}) *nvim-tree-api.marks.get()* - Return the node if it is marked. - - Parameters: ~ - • {node} (Node) folder or file +`api.diagnostics.hi_test` |nvim_tree.api.health.hi_test()| -marks.list() *nvim-tree-api.marks.list()* - Retrieve all marked nodes. +`api.git.reload` |nvim_tree.api.tree.reload_git()| - Return: ~ - (table) marked nodes +`api.live_filter.start` |nvim_tree.api.filter.live_filter.start()| +`api.live_filter.clear` |nvim_tree.api.filter.live_filter.clear()| -marks.toggle({node}) *nvim-tree-api.marks.toggle()* - Toggle node mark. +============================================================================== +Legacy: Highlight *nvim-tree-legacy-highlight* - Parameters: ~ - • {node} (Node) folder or file +Legacy highlight group are still obeyed when they are defined and the current +highlight group is not, hard linking as follows: > -marks.clear() *nvim-tree-api.marks.clear()* - Clear all marks. + NvimTreeModifiedIcon NvimTreeModifiedFile + NvimTreeOpenedHL NvimTreeOpenedFile + NvimTreeBookmarkIcon NvimTreeBookmark -marks.bulk.delete() *nvim-tree-api.marks.bulk.delete()* - Delete all marked. Optionally prompts. + NvimTreeGitDeletedIcon NvimTreeGitDeleted + NvimTreeGitDirtyIcon NvimTreeGitDirty + NvimTreeGitIgnoredIcon NvimTreeGitIgnored + NvimTreeGitMergeIcon NvimTreeGitMerge + NvimTreeGitNewIcon NvimTreeGitNew + NvimTreeGitRenamedIcon NvimTreeGitRenamed + NvimTreeGitStagedIcon NvimTreeGitStaged -marks.bulk.trash() *nvim-tree-api.marks.bulk.trash()* - Trash all marked. Optionally prompts. + NvimTreeGitFileDeletedHL NvimTreeFileDeleted + NvimTreeGitFileDirtyHL NvimTreeFileDirty + NvimTreeGitFileIgnoredHL NvimTreeFileIgnored + NvimTreeGitFileMergeHL NvimTreeFileMerge + NvimTreeGitFileNewHL NvimTreeFileNew + NvimTreeGitFileRenamedHL NvimTreeFileRenamed + NvimTreeGitFileStagedHL NvimTreeFileStaged -marks.bulk.move() *nvim-tree-api.marks.bulk.move()* - Prompts for a directory to move all marked nodes into. + NvimTreeGitFolderDeletedHL NvimTreeFolderDeleted + NvimTreeGitFolderDirtyHL NvimTreeFolderDirty + NvimTreeGitFolderIgnoredHL NvimTreeFolderIgnored + NvimTreeGitFolderMergeHL NvimTreeFolderMerge + NvimTreeGitFolderNewHL NvimTreeFolderNew + NvimTreeGitFolderRenamedHL NvimTreeFolderRenamed + NvimTreeGitFolderStagedHL NvimTreeFolderStaged -marks.navigate.next() *nvim-tree-api.marks.navigate.next()* - Navigate to the next marked node, wraps. - Opens files as per |nvim_tree.Config.Actions.OpenFile| - Works best with |nvim_tree.Config.UpdateFocusedFile| enabled. + NvimTreeLspDiagnosticsError NvimTreeDiagnosticErrorIcon + NvimTreeLspDiagnosticsWarning NvimTreeDiagnosticWarnIcon + NvimTreeLspDiagnosticsInformation NvimTreeDiagnosticInfoIcon + NvimTreeLspDiagnosticsHint NvimTreeDiagnosticHintIcon -marks.navigate.prev() *nvim-tree-api.marks.navigate.prev()* - As per |nvim-tree-api.marks.navigate.next()| + NvimTreeLspDiagnosticsErrorText NvimTreeDiagnosticErrorFileHL + NvimTreeLspDiagnosticsWarningText NvimTreeDiagnosticWarnFileHL + NvimTreeLspDiagnosticsInformationText NvimTreeDiagnosticInfoFileHL + NvimTreeLspDiagnosticsHintText NvimTreeDiagnosticHintFileHL -marks.navigate.select() *nvim-tree-api.marks.navigate.select()* - Prompts for selection of a marked node, sorted by absolute paths. - A folder will be focused, a file will be opened. + NvimTreeLspDiagnosticsErrorFolderText NvimTreeDiagnosticErrorFolderHL + NvimTreeLspDiagnosticsWarningFolderText NvimTreeDiagnosticWarnFolderHL + NvimTreeLspDiagnosticsInformationFolderText NvimTreeDiagnosticInfoFolderHL + NvimTreeLspDiagnosticsHintFolderText NvimTreeDiagnosticHintFolderHL +< ============================================================================== -API: Config *nvim-tree-api.config* - - *nvim-tree-api.config.mappings.default_on_attach()* -config.mappings.default_on_attach({bufnr}) - Set all |nvim-tree-mappings-default|. Call from your |nvim_tree.Config| {on_attach} - - Parameters: ~ - • {bufnr} (number) nvim-tree buffer number passed to |nvim_tree.Config| {on_attach} +Hidden Display *nvim-tree-hidden-display* - *nvim-tree-api.config.mappings.get_keymap()* -config.mappings.get_keymap() - Retrieves all buffer local mappings for nvim-tree. - These are the mappings that are applied by |nvim_tree.Config| {on_attach}, which - may include default mappings. +Show a summary of hidden files below the tree highlighted with `NvimTreeHiddenDisplay - Return: ~ - (table) as per |nvim_buf_get_keymap()| +Configure via |nvim_tree.Config.Renderer| {hidden_display} - *nvim-tree-api.config.mappings.get_keymap_default()* -config.mappings.get_keymap_default() - Retrieves the buffer local mappings for nvim-tree that are applied by - |nvim-tree-api.config.mappings.default_on_attach()| + *nvim_tree.Config.Renderer.HiddenDisplay* + • `none`: disabled + • `simple`: show how many hidden files are in a folder + • `all`: show how many hidden and the number of hidden files by reason + • `fun(hidden_stats: table): string`: returns a summary of hidden stats - Return: ~ - (table) as per |nvim_buf_get_keymap()| +Example `"all"`: +If a folder has 14 hidden items for various reasons, the display might show: > + (14 total git: 5, dotfile: 9) +< +If a function is provided, it receives a table `hidden_stats` where keys are +reasons and values are the count of hidden files for that reason. + +The `hidden_stats` argument is structured as follows, where is the number +of hidden files related to the field: > + hidden_stats = { + bookmark = , + buf = , + custom = , + dotfile = , + git = , + live_filter = , + } +< +Example of function that can be passed: >lua + function(hidden_stats) + local total_count = 0 + for reason, count in pairs(hidden_stats) do + total_count = total_count + count + end + + if total_count > 0 then + return "(" .. tostring(total_count) .. " hidden)" + end + return nil + end +< ============================================================================== -API: Commands *nvim-tree-api.commands* +Class: Config *nvim-tree-config* -commands.get() *nvim-tree-api.commands.get()* - Retrieve all commands, see |nvim-tree-commands| +*nvim_tree.Config* + Arguments to pass to |nvim-tree-setup|. - Return: ~ - (table) array containing |nvim_create_user_command()| parameters: - • {name} (string) - • {command} (function) - • {opts} (table) + When a value is not present/nil, the default will be used. -============================================================================== -API: Diagnostics *nvim-tree-api.diagnostics* + They can be validated by |lsp| when passed directly e.g. >lua + require("nvim-tree").setup({ + hijack_cursor = true, + }) +< -diagnostics.hi_test() *nvim-tree-api.diagnostics.hi_test()* - Open a new buffer displaying all nvim-tree highlight groups, their link - chain and concrete definition. + or as a typed variable e.g. >lua + ---@type nvim_tree.Config + local config = { + hijack_cursor = true, + } + require("nvim-tree").setup(config) +< - Similar to `:so $VIMRUNTIME/syntax/hitest.vim` as per |:highlight| + {on_attach} Runs when creating the nvim-tree buffer. Use this to set your + |nvim-tree-mappings|. When not a function, |nvim-tree-mappings-default| + will be used. -============================================================================== -Mappings *nvim-tree-mappings* + {hijack_cursor} keep the cursor on the first letter of the filename when + moving in the tree. -Mappings are set via the |nvim_tree.Config| {on_attach} function, which is run upon -creating the nvim-tree buffer. Mappings are usually |nvim-tree-api| functions -however may be your own. + {auto_reload_on_write} reload the explorer every time a buffer is written + to. -When {on_attach} is not a function, |nvim-tree-mappings-default| will be used. + {disable_netrw} completely disables |netrw|, see |nvim-tree-netrw| for + details. It is strongly advised to eagerly disable netrw, due to race + conditions at vim startup. -Active mappings may be viewed via HELP, default `g?`. The mapping's description -is used when displaying HELP. + {hijack_netrw} hijacks netrw windows, ignored when {disable_netrw}. -The `on_attach` function is passed the `bufnr` of nvim-tree. Use -|vim.keymap.set()| or |nvim_set_keymap()| to define mappings as usual. e.g. >lua + {hijack_unnamed_buffer_when_opening} opens in place of the unnamed buffer + if it's empty. - local function my_on_attach(bufnr) - local api = require("nvim-tree.api") + {root_dirs} preferred root directories, requires + |nvim_tree.Config.UpdateFocusedFile.UpdateRoot|. - local function opts(desc) - return { desc = "nvim-tree: " .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true } - end + {prefer_startup_root} prefer startup root directory when updating root + directory of the tree. Requires + |nvim_tree.Config.UpdateFocusedFile.UpdateRoot|. - -- copy default mappings here from defaults in next section - vim.keymap.set("n", "", api.tree.change_root_to_node, opts("CD")) - vim.keymap.set("n", "", api.node.open.replace_tree_buffer, opts("Open: In Place")) - --- - -- OR use all default mappings - api.config.mappings.default_on_attach(bufnr) + {sync_root_with_cwd} changes the tree root directory on |DirChanged| and + refreshes the tree. - -- remove a default - vim.keymap.del("n", "", { buffer = bufnr }) + {reload_on_bufenter} automatically reloads the tree on |BufEnter| + nvim-tree. - -- override a default - vim.keymap.set("n", "", api.tree.reload, opts("Refresh")) + {respect_buf_cwd} changes the |current-directory| of nvim-tree to that of + new buffer's when opening nvim-tree. - -- add your mappings - vim.keymap.set("n", "?", api.tree.toggle_help, opts("Help")) - --- - end + {select_prompts} uses |vim.ui.select()| style prompts. Necessary when + using a UI prompt decorator such as dressing.nvim or + telescope-ui-select.nvim - require("nvim-tree").setup({ - --- - on_attach = my_on_attach, - --- - }) -< -Single left mouse mappings can be achieved via ``. + Fields: ~ + • {on_attach}? (`"default"|(fun(bufnr: integer))`) + (default: `default`) + • {hijack_cursor}? (`boolean`) (default: `false`) + • {auto_reload_on_write}? (`boolean`) (default: `true`) + • {disable_netrw}? (`boolean`) (default: `false`) + • {hijack_netrw}? (`boolean`) (default: `true`) + • {hijack_unnamed_buffer_when_opening}? (`boolean`) (default: `false`) + • {root_dirs}? (`string[]`) (default: `{}`) + • {prefer_startup_root}? (`boolean`) (default: `false`) + • {sync_root_with_cwd}? (`boolean`) (default: `false`) + • {reload_on_bufenter}? (`boolean`) (default: `false`) + • {respect_buf_cwd}? (`boolean`) (default: `false`) + • {select_prompts}? (`boolean`) (default: `false`) + • {sort}? (`nvim_tree.Config.Sort`) + |nvim_tree.Config.Sort| + • {view}? (`nvim_tree.Config.View`) + |nvim_tree.Config.View| + • {renderer}? (`nvim_tree.Config.Renderer`) + |nvim_tree.Config.Renderer| + • {hijack_directories}? (`nvim_tree.Config.HijackDirectories`) + |nvim_tree.Config.HijackDirectories| + • {update_focused_file}? (`nvim_tree.Config.UpdateFocusedFile`) + |nvim_tree.Config.UpdateFocusedFile| + • {system_open}? (`nvim_tree.Config.SystemOpen`) + |nvim_tree.Config.SystemOpen| + • {git}? (`nvim_tree.Config.Git`) + |nvim_tree.Config.Git| + • {diagnostics}? (`nvim_tree.Config.Diagnostics`) + |nvim_tree.Config.Diagnostics| + • {modified}? (`nvim_tree.Config.Modified`) + |nvim_tree.Config.Modified| + • {filters}? (`nvim_tree.Config.Filters`) + |nvim_tree.Config.Filters| + • {live_filter}? (`nvim_tree.Config.LiveFilter`) + |nvim_tree.Config.LiveFilter| + • {filesystem_watchers}? (`nvim_tree.Config.FilesystemWatchers`) + |nvim_tree.Config.FilesystemWatchers| + • {actions}? (`nvim_tree.Config.Actions`) + |nvim_tree.Config.Actions| + • {trash}? (`nvim_tree.Config.Trash`) + |nvim_tree.Config.Trash| + • {tab}? (`nvim_tree.Config.Tab`) + |nvim_tree.Config.Tab| + • {bookmarks}? (`nvim_tree.Config.Bookmarks`) + |nvim_tree.Config.Bookmarks| + • {notify}? (`nvim_tree.Config.Notify`) + |nvim_tree.Config.Notify| + • {help}? (`nvim_tree.Config.Help`) + |nvim_tree.Config.Help| + • {ui}? (`nvim_tree.Config.UI`) + |nvim_tree.Config.UI| + • {experimental}? (`nvim_tree.Config.Experimental`) + |nvim_tree.Config.Experimental| + • {log}? (`nvim_tree.Config.Log`) + |nvim_tree.Config.Log| -Single right / middle mouse mappings will require changes to |'mousemodel'| or |'mouse'|. -|vim.keymap.set()| {rhs} is a `(function|string)` thus it may be necessary to -define your own function to map complex functionality e.g. >lua - local function print_node_path() - local api = require("nvim-tree.api") - local node = api.tree.get_node_under_cursor() - print(node.absolute_path) - end +============================================================================== +Class: Config.Sort *nvim-tree-config-sort* - -- on_attach - vim.keymap.set("n", "", print_node_path, opts("Print Path")) +*nvim_tree.Config.Sort* + Sort files within a directory. + + {sorter} presets *nvim_tree.Config.Sort.Sorter* + • `"name"` + • `"case_sensitive"` name + • `"modification_time"` + • `"extension"` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz` + • `"suffix"` uses the last e.g. `foo.tar.gz` -> `.gz` + • `"filetype"` |filetype| + + {sorter} may be a function that is passed a list of `nvim_tree.api.Node` + to be sorted in place e.g. >lua + + ---Sort by name length + ---@param nodes nvim_tree.api.Node[] + ---@return nvim_tree.Config.Sort.Sorter? + local sorter = function(nodes) + table.sort(nodes, function(a, b) + return #a.name < #b.name + end) + end < + + {sorter} may be a function that returns a |nvim_tree.Config.Sort.Sorter| + + Fields: ~ + • {sorter}? (`nvim_tree.Config.Sort.Sorter|(fun(nodes: nvim_tree.api.Node[]): nvim_tree.Config.Sort.Sorter?)`) + (default: `"name"`) + • {folders_first}? (`boolean`, default: `true`) Sort folders before + files. Has no effect when {sorter} is a function. + • {files_first}? (`boolean`, default: `false`) Sort files before + folders. Has no effect when {sorter} is a function. + Overrides {folders_first}. + + + ============================================================================== -Mappings: Default *nvim-tree-mappings-default* +Class: Config.View *nvim-tree-config-view* -In the absence of an |nvim_tree.Config| {on_attach} function, the following -defaults will be applied. +*nvim_tree.Config.View* + Configures the dimensions and appearance of the nvim-tree window. -You are encouraged to copy these to your {on_attach} function. >lua + The window is "docked" at the left by default, however may be configured + to float: |nvim_tree.Config.View.Float| - local api = require("nvim-tree.api") + {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. - local function opts(desc) - return { desc = "nvim-tree: " .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true } - end + *nvim_tree.Config.View.WidthSpec* + • `string`: `x%` string e.g. `30%` + • `integer`: number of columns + • `function`: returns one of the above - -- BEGIN_DEFAULT_ON_ATTACH - vim.keymap.set("n", "", api.tree.change_root_to_node, opts("CD")) - vim.keymap.set("n", "", api.node.open.replace_tree_buffer, opts("Open: In Place")) - vim.keymap.set("n", "", api.node.show_info_popup, opts("Info")) - vim.keymap.set("n", "", api.fs.rename_sub, opts("Rename: Omit Filename")) - vim.keymap.set("n", "", api.node.open.tab, opts("Open: New Tab")) - vim.keymap.set("n", "", api.node.open.vertical, opts("Open: Vertical Split")) - vim.keymap.set("n", "", api.node.open.horizontal, opts("Open: Horizontal Split")) - vim.keymap.set("n", "", api.node.navigate.parent_close, opts("Close Directory")) - vim.keymap.set("n", "", api.node.open.edit, opts("Open")) - vim.keymap.set("n", "", api.fs.remove, opts("Delete")) - vim.keymap.set("n", "", api.node.open.preview, opts("Open Preview")) - vim.keymap.set("n", ">", api.node.navigate.sibling.next, opts("Next Sibling")) - vim.keymap.set("n", "<", api.node.navigate.sibling.prev, opts("Previous Sibling")) - vim.keymap.set("n", ".", api.node.run.cmd, opts("Run Command")) - vim.keymap.set("n", "-", api.tree.change_root_to_parent, opts("Up")) - vim.keymap.set("n", "a", api.fs.create, opts("Create File Or Directory")) - vim.keymap.set("n", "bd", api.marks.bulk.delete, opts("Delete Bookmarked")) - vim.keymap.set("n", "bt", api.marks.bulk.trash, opts("Trash Bookmarked")) - vim.keymap.set("n", "bmv", api.marks.bulk.move, opts("Move Bookmarked")) - vim.keymap.set("n", "B", api.tree.toggle_no_buffer_filter, opts("Toggle Filter: No Buffer")) - vim.keymap.set("n", "c", api.fs.copy.node, opts("Copy")) - vim.keymap.set("n", "C", api.tree.toggle_git_clean_filter, opts("Toggle Filter: Git Clean")) - vim.keymap.set("n", "[c", api.node.navigate.git.prev, opts("Prev Git")) - vim.keymap.set("n", "]c", api.node.navigate.git.next, opts("Next Git")) - vim.keymap.set("n", "d", api.fs.remove, opts("Delete")) - vim.keymap.set("n", "D", api.fs.trash, opts("Trash")) - vim.keymap.set("n", "E", api.tree.expand_all, opts("Expand All")) - vim.keymap.set("n", "e", api.fs.rename_basename, opts("Rename: Basename")) - vim.keymap.set("n", "]e", api.node.navigate.diagnostics.next, opts("Next Diagnostic")) - vim.keymap.set("n", "[e", api.node.navigate.diagnostics.prev, opts("Prev Diagnostic")) - vim.keymap.set("n", "F", api.live_filter.clear, opts("Live Filter: Clear")) - vim.keymap.set("n", "f", api.live_filter.start, opts("Live Filter: Start")) - vim.keymap.set("n", "g?", api.tree.toggle_help, opts("Help")) - vim.keymap.set("n", "gy", api.fs.copy.absolute_path, opts("Copy Absolute Path")) - vim.keymap.set("n", "ge", api.fs.copy.basename, opts("Copy Basename")) - vim.keymap.set("n", "H", api.tree.toggle_hidden_filter, opts("Toggle Filter: Dotfiles")) - vim.keymap.set("n", "I", api.tree.toggle_gitignore_filter, opts("Toggle Filter: Git Ignore")) - vim.keymap.set("n", "J", api.node.navigate.sibling.last, opts("Last Sibling")) - vim.keymap.set("n", "K", api.node.navigate.sibling.first, opts("First Sibling")) - vim.keymap.set("n", "L", api.node.open.toggle_group_empty, opts("Toggle Group Empty")) - vim.keymap.set("n", "M", api.tree.toggle_no_bookmark_filter, opts("Toggle Filter: No Bookmark")) - vim.keymap.set("n", "m", api.marks.toggle, opts("Toggle Bookmark")) - vim.keymap.set("n", "o", api.node.open.edit, opts("Open")) - vim.keymap.set("n", "O", api.node.open.no_window_picker, opts("Open: No Window Picker")) - vim.keymap.set("n", "p", api.fs.paste, opts("Paste")) - vim.keymap.set("n", "P", api.node.navigate.parent, opts("Parent Directory")) - vim.keymap.set("n", "q", api.tree.close, opts("Close")) - vim.keymap.set("n", "r", api.fs.rename, opts("Rename")) - vim.keymap.set("n", "R", api.tree.reload, opts("Refresh")) - vim.keymap.set("n", "s", api.node.run.system, opts("Run System")) - vim.keymap.set("n", "S", api.tree.search_node, opts("Search")) - vim.keymap.set("n", "u", api.fs.rename_full, opts("Rename: Full Path")) - vim.keymap.set("n", "U", api.tree.toggle_custom_filter, opts("Toggle Filter: Hidden")) - vim.keymap.set("n", "W", api.tree.collapse_all, opts("Collapse All")) - vim.keymap.set("n", "x", api.fs.cut, opts("Cut")) - vim.keymap.set("n", "y", api.fs.copy.filename, opts("Copy Name")) - vim.keymap.set("n", "Y", api.fs.copy.relative_path, opts("Copy Relative Path")) - vim.keymap.set("n", "<2-LeftMouse>", api.node.open.edit, opts("Open")) - vim.keymap.set("n", "<2-RightMouse>", api.tree.change_root_to_node, opts("CD")) - -- END_DEFAULT_ON_ATTACH + Fields: ~ + • {centralize_selection}? (`boolean`, default: `false`) When + entering nvim-tree, reposition the + view so that the current node is + initially centralized, see |zz|. + • {cursorline}? (`boolean`, default: `true`) + |'cursorline'| + • {cursorlineopt}? (`string`, default: `both`) + |'cursorlineopt'| + • {debounce_delay}? (`integer`, default: `15`) Idle + milliseconds before some reload / + refresh operations. Increase if you + experience performance issues around + screen refresh. + • {side}? (`"left"|"right"`) (default: `"left"`) + • {preserve_window_proportions}? (`boolean`, default: `false`) + Preserves window proportions when + opening a file. If `false`, the height + and width of windows other than + nvim-tree will be equalized. + • {number}? (`boolean`, default: `false`) + |'number'| + • {relativenumber}? (`boolean`, default: `false`) + |'relativenumber'| + • {signcolumn}? (`"yes"|"auto"|"no"`, default: + `"yes"`) |'signcolumn'| + • {width}? (`nvim_tree.Config.View.WidthSpec|nvim_tree.Config.View.Width`) + (default: `30`) + • {float}? (`nvim_tree.Config.View.Float`) + |nvim_tree.Config.View.Float| + +*nvim_tree.Config.View.Float* + Configure floating window behaviour + + {open_win_config} is passed to |nvim_open_win()|, default: >lua + { + relative = "editor", + border = "rounded", + width = 30, + height = 30, + row = 1, + col = 1, + } < -Alternatively, you may apply these default mappings from your |nvim_tree.Config| {on_attach} via -|nvim-tree-api.config.mappings.default_on_attach()| e.g. >lua - local function my_on_attach(bufnr) - local api = require("nvim-tree.api") + 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: + `{ relative = "editor", border = "rounded", width = 30, height = 30, row = 1, col = 1, }`) - local function opts(desc) - return { desc = "nvim-tree: " .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true } - end +*nvim_tree.Config.View.Width* + Configure dynamic width based on longest line. - api.config.mappings.default_on_attach(bufnr) + Fields: ~ + • {min}? (`nvim_tree.Config.View.WidthSpec`) (default: `30`) + • {max}? (`nvim_tree.Config.View.WidthSpec`, default: `-1`) + -1 for unbounded. + • {lines_excluded}? (`("root")[]`, default: `{ "root" }`) Exclude these + lines when computing width. + • {padding}? (`nvim_tree.Config.View.WidthSpec`, default: `1`) + Extra padding to the right. - -- your removals and mappings go here - end -< -============================================================================== -Icons And Highlighting *nvim-tree-icons-highlighting* -Icons may be displayed before files and directories. +============================================================================== +Class: Config.Renderer *nvim-tree-config-renderer* -Additional icons and highlighting may be displayed to indicate various states -for files and and directories. +*nvim_tree.Config.Renderer* + Controls the appearance of the tree. -Highlighting is additive, with higher precedence overriding lower. + See |nvim-tree-icons-highlighting| for {highlight_} and {decorators} + fields. -|nvim_tree.Config.Renderer| {decorators} controls which highlighting is -applied and its precedence. See |nvim-tree-decorators| for information on -creating custom decorators. + {root_folder_label} has 3 forms: + • `string`: |filename-modifiers| format string, default `":~:s?$?/..?"` + • `boolean`: `true` to disable + • `fun(root_cwd: string): string`: return a literal string from root's + absolute path e.g. >lua + my_root_folder_label = function(path) + return ".../" .. vim.fn.fnamemodify(path, ":t") + end < -`ICON` - Enable via |nvim_tree.Config.Renderer.Icons.Show -`REQUIRES` - Feature must be enabled to show icons and highlighting. + Fields: ~ + • {add_trailing}? (`boolean`, default: `false`) Appends a + trailing slash to folder and symlink folder + target names. + • {group_empty}? (`boolean|(fun(relative_path: string): string)`, default: `false`) + Compact folders that only contain a single + folder into one node. Function variant + takes the relative path of grouped folders + and returns a string to be displayed. + • {full_name}? (`boolean`, default: `false`) Display nodes + whose name length is wider than the width + of nvim-tree window in floating window. + • {root_folder_label}? (`string|boolean|(fun(root_cwd: string): string)`) + (default: `":~:s?$?/..?"`) + • {indent_width}? (`integer`, default: `2`) Number of spaces + for each tree nesting level. Minimum 1. + • {hidden_display}? (`nvim_tree.Config.Renderer.HiddenDisplay`, default: `none`) + |nvim-tree-hidden-display| + • {symlink_destination}? (`boolean`, default: `true`) Appends an + arrow followed by the target of the + symlink. + • {decorators}? (`(string|nvim_tree.api.decorator.UserDecorator)[]`) + (default: + `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) + • {highlight_git}? (`nvim_tree.Config.Renderer.Highlight`) + (default: `"none"`) + • {highlight_opened_files}? (`nvim_tree.Config.Renderer.Highlight`) + (default: `"none"`) + • {highlight_hidden}? (`nvim_tree.Config.Renderer.Highlight`) + (default: `"none"`) + • {highlight_modified}? (`nvim_tree.Config.Renderer.Highlight`) + (default: `"none"`) + • {highlight_bookmarks}? (`nvim_tree.Config.Renderer.Highlight`) + (default: `"none"`) + • {highlight_diagnostics}? (`nvim_tree.Config.Renderer.Highlight`) + (default: `"none"`) + • {highlight_clipboard}? (`nvim_tree.Config.Renderer.Highlight`) + (default: `"name"`) + • {special_files}? (`string[]`, default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }`) + Highlight special files and directories + with `NvimTreeSpecial*`. + • {indent_markers}? (`nvim_tree.Config.Renderer.IndentMarkers`) + |nvim_tree.Config.Renderer.IndentMarkers| + • {icons}? (`nvim_tree.Config.Renderer.Icons`) + |nvim_tree.Config.Renderer.Icons| -`PLACEMENT` *nvim_tree.Config.Renderer.Icons.Placement* - Where to place the icon: |nvim_tree.Config.Renderer.Icons| {_placement} - • `before`: before file/folder, after the file/folders icons - • `after`: after file/folder - • `signcolumn`: far left, requires |nvim_tree.Config.View| {signcolumn}. - • `right_align`: far right +*nvim_tree.Config.Renderer.Icons* + Icons and separators -`HIGHLIGHT` *nvim_tree.Config.Renderer.Highlight* - What should be highlighted: |nvim_tree.Config.Renderer| {highlight_} - • `none`: no highlighting - • `icon`: icon only - • `name`: name only - • `all`: icon and name + See |nvim-tree-icons-highlighting| for: {_placement} fields. -`DEVICONS` - Glyphs and their colors will be overridden by optional plugin: - `nvim-tree/nvim-web-devicons` |nvim_tree.Config.Renderer.Icons.WebDevicons| + Fields: ~ + • {git_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`) + (default: `before`) + • {hidden_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`) + (default: `after`) + • {modified_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`) + (default: `after`) + • {bookmarks_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`) + (default: `signcolumn`) + • {diagnostics_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`) + (default: `signcolumn`) + • {padding}? (`table`) + *nvim_tree.Config.Renderer.Icons.Padding* + • {icon}? (`string`, default: `" "`) Between + icon and filename. + • {folder_arrow}? (`string`, default: `" "`) + Between folder arrow icon and file/folder + icon. + • {symlink_arrow}? (`string`, default: `" ➛ "`) Separator + between symlink source and target. + • {show}? (`nvim_tree.Config.Renderer.Icons.Show`) + |nvim_tree.Config.Renderer.Icons.Show| + • {glyphs}? (`nvim_tree.Config.Renderer.Icons.Glyphs`) + |nvim_tree.Config.Renderer.Icons.Glyphs| + • {web_devicons}? (`nvim_tree.Config.Renderer.Icons.WebDevicons`) + |nvim_tree.Config.Renderer.Icons.WebDevicons| -`GLYPHS` - Icon glyphs definitions. +*nvim_tree.Config.Renderer.Icons.Glyphs* + See |nvim-tree-icons-highlighting|. -`GROUPS` - Applicable highlight groups: |nvim-tree-highlight-groups| + Glyphs that appear in the sign column must have length <= 2 -Some defaults noted. In ascending order of default highlight precedence: + Fields: ~ + • {default}? (`string`, default: `""`) Files + • {symlink}? (`string`) (default: `""`) + • {bookmark}? (`string`) (default: `"󰆤"`) + • {modified}? (`string`) (default: `"●"`) + • {hidden}? (`string`) (default: `"󰜌"`) + • {folder}? (`table`) *nvim_tree.Config.Renderer.Icons.Glyphs.Folder* + • {arrow_closed}? (`string`) (default: left arrow) + • {arrow_open}? (`string`) (default: down arrow) + • {default}? (`string`) (default: `""`) + • {open}? (`string`) (default: `""`) + • {empty}? (`string`) (default: `""`) + • {empty_open}? (`string`) (default: `""`) + • {symlink}? (`string`) (default: `""`) + • {symlink_open}? (`string`) (default: `""`) + • {git}? (`table`) *nvim_tree.Config.Renderer.Icons.Glyphs.Git* + • {unstaged}? (`string`) (default: `"✗"`) + • {staged}? (`string`) (default: `"✓"`) + • {unmerged}? (`string`) (default: `""`) + • {renamed}? (`string`) (default: `"➜"`) + • {untracked}? (`string`) (default: `"★"`) + • {deleted}? (`string`) (default: `""`) + • {ignored}? (`string`) (default: `"◌"`) -`WHAT ICON REQUIRES PLACEMENT HIGHLIGHT GLYPHS DEVICONS GROUPS` -File Icon {file} Y - - - |nvim_tree.Config.Renderer.Icons.Glyphs| {default} Y `NvimTreeNormal`, `NvimTreeFileIcon` -Folder Icon {folder} Y - - - |nvim_tree.Config.Renderer.Icons.Glyphs.Folder| Y `NvimTree*FolderName`, `NvimTree*FolderIcon` -Git Status {git} Y |nvim_tree.Config.Git| {git_placement} `"before"` {highlight_git} `"none"` |nvim_tree.Config.Renderer.Icons.Glyphs.Git| N `NvimTreeGit*` -|bufloaded()| - - - {highlight_opened_files}`"none"` - N ` NvimTreeOpened*` -Dotfiles {hidden} N - {hidden_placement} `"after"` {highlight_hidden} `"none"` |nvim_tree.Config.Renderer.Icons.Glyphs| {hidden} N `NvimTreeHidden*` -|'modified'| {modified} Y |nvim_tree.Config.Modified| {modified_placement} `"after"` {highlight_modified} `"none"` |nvim_tree.Config.Renderer.Icons.Glyphs| {modified} N `NvimTreeModified*` -Bookmarked {bookmarks} Y - {bookmarks_placement} `"signcolumn"` {highlight_bookmarks} `"none"` |nvim_tree.Config.Renderer.Icons.Glyphs| {bookmark} N `NvimTreeBookmark*` -Diag Status {diagnostics}Y |nvim_tree.Config.Diagnostics| {diagnostics_placement}`"signcolumn"` {highlight_diagnostics} `"none" ` |nvim_tree.Config.Diagnostics.Icons| N `NvimTreeDiagnostic*` -Cut/Copied - - - {highlight_clipboard} `"name"` - N `NvimTreeCutHL`, `NvimTreeCopiedHL` +*nvim_tree.Config.Renderer.Icons.Show* + See |nvim-tree-icons-highlighting|. + Fields: ~ + • {file}? (`boolean`) (default: `true`) + • {folder}? (`boolean`) (default: `true`) + • {git}? (`boolean`) (default: `true`) + • {modified}? (`boolean`) (default: `true`) + • {hidden}? (`boolean`) (default: `false`) + • {diagnostics}? (`boolean`) (default: `true`) + • {bookmarks}? (`boolean`) (default: `true`) + • {folder_arrow}? (`boolean`, default: `true`) Show a small arrow + before the folder node. Arrow will be a part of the + node when using + |nvim_tree.Config.Renderer.IndentMarkers|. -============================================================================== -Highlight Groups *nvim-tree-highlight-groups* +*nvim_tree.Config.Renderer.Icons.WebDevicons* + Configure optional plugin `nvim-tree/nvim-web-devicons`, see + |nvim-tree-icons-highlighting|. -All the following highlight groups can be configured by hand. Aside from -`NvimTreeWindowPicker`, it is not advised to colorize the background of these -groups. + Fields: ~ + • {file}? (`table`) + *nvim_tree.Config.Renderer.Icons.WebDevicons.File* + • {enable}? (`boolean`) (default: `true`) + • {color}? (`boolean`) (default: `true`) + • {folder}? (`table`) + *nvim_tree.Config.Renderer.Icons.WebDevicons.Folder* + • {enable}? (`boolean`) (default: `false`) + • {color}? (`boolean`) (default: `true`) -Example |:highlight| >vim - :hi NvimTreeSymlink guifg=blue gui=bold,underline -< -It is recommended to enable |'termguicolors'| for the more pleasant 24-bit -colours. +*nvim_tree.Config.Renderer.IndentMarkers* -To view the nvim-tree highlight groups run |:NvimTreeHiTest| + Fields: ~ + • {enable}? (`boolean`, default: `false`) Display indent markers + when folders are open. + • {inline_arrows}? (`boolean`, default: `true`) Display folder arrows + in the same column as indent marker when using + |nvim_tree.Config.Renderer.Icons.Padding| + {folder_arrow} + • {icons}? (`table`) + *nvim_tree.Config.Renderer.IndentMarkers.Icons* + Before the file/directory, length 1. + • {corner}? (`string`) (default: `"└"`) + • {edge}? (`string`) (default: `"│"`) + • {item}? (`string`) (default: `"│"`) + • {bottom}? (`string`) (default: `"─"`) + • {none}? (`string`) (default: `" "`) -To view all active highlight groups run `:so $VIMRUNTIME/syntax/hitest.vim` -as per |:highlight| -The `*HL` groups are additive as per |nvim_tree.Config.Renderer| precedence. -Only present attributes will clobber each other. -In this example a modified, opened file will have magenta text, with cyan -undercurl: >vim - :hi NvimTreeOpenedHL guifg=magenta guisp=red gui=underline - :hi NvimTreeModifiedFileHL guisp=cyan gui=undercurl -< -To prevent usage of a highlight: -- Before setup: link the group to `Normal` e.g. >vim - :hi NvimTreeExecFile Normal -< -- After setup: link it to `NONE`, to override the default link e.g. >lua - :hi! link NvimTreeExecFile NONE -< ============================================================================== -Highlight Groups: Default *nvim-tree-highlight-groups-default* +Class: Config.HijackDirectories *nvim-tree-config-hijack-directories* -|:highlight-link| `default` or |:highlight-default| define the groups on setup: +*nvim_tree.Config.HijackDirectories* + Hijack directory buffers by replacing the directory buffer with the tree. -Standard: > - NvimTreeNormal Normal - NvimTreeNormalFloat NormalFloat - NvimTreeNormalNC NormalFloat + Disable this option if you use vim-dirvish or dirbuf.nvim. - NvimTreeLineNr LineNr - NvimTreeWinSeparator WinSeparator - NvimTreeEndOfBuffer EndOfBuffer - NvimTreePopup Normal - NvimTreeSignColumn NvimTreeNormal + 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. - NvimTreeCursorColumn CursorColumn - NvimTreeCursorLine CursorLine - NvimTreeCursorLineNr CursorLineNr - NvimTreeStatusLine StatusLine - NvimTreeStatusLineNC StatusLineNC -< -File Text: > - NvimTreeExecFile SpellCap - NvimTreeImageFile SpellCap - NvimTreeSpecialFile SpellCap - NvimTreeSymlink SpellCap -< -Folder Text: > - NvimTreeRootFolder Title - NvimTreeFolderName Directory - NvimTreeEmptyFolderName Directory - NvimTreeOpenedFolderName Directory - NvimTreeSymlinkFolderName Directory -< -File Icons: > - NvimTreeFileIcon NvimTreeNormal - NvimTreeSymlinkIcon NvimTreeNormal -< -Folder Icons: > - NvimTreeFolderIcon guifg=#8094b4 ctermfg=Blue - NvimTreeOpenedFolderIcon NvimTreeFolderIcon - NvimTreeClosedFolderIcon NvimTreeFolderIcon - NvimTreeFolderArrowClosed NvimTreeIndentMarker - NvimTreeFolderArrowOpen NvimTreeIndentMarker -< -Indent: > - NvimTreeIndentMarker NvimTreeFileIcon -< -Picker: > - NvimTreeWindowPicker guifg=#ededed guibg=#4493c8 gui=bold ctermfg=White ctermbg=Cyan -< -Live Filter: > - NvimTreeLiveFilterPrefix PreProc - NvimTreeLiveFilterValue ModeMsg -< -Clipboard: > - NvimTreeCopiedHL SpellRare - NvimTreeCutHL SpellBad -< -Bookmarks: > - NvimTreeBookmarkIcon NvimTreeFolderIcon - NvimTreeBookmarkHL SpellLocal -< -Modified: > - NvimTreeModifiedIcon Type - NvimTreeModifiedFileHL NvimTreeModifiedIcon - NvimTreeModifiedFolderHL NvimTreeModifiedIcon -Hidden: > - NvimTreeModifiedIcon Conceal - NvimTreeModifiedFileHL NvimTreeHiddenIcon - NvimTreeModifiedFolderHL NvimTreeHiddenFileHL -< -Hidden Display: > - NvimTreeHiddenDisplay Conceal -< -Opened: > - NvimTreeOpenedHL Special -< -Git Icon: > - NvimTreeGitDeletedIcon Statement - NvimTreeGitDirtyIcon Statement - NvimTreeGitIgnoredIcon Comment - NvimTreeGitMergeIcon Constant - NvimTreeGitNewIcon PreProc - NvimTreeGitRenamedIcon PreProc - NvimTreeGitStagedIcon Constant -< -Git File File Highlight: > - NvimTreeGitFileDeletedHL NvimTreeGitDeletedIcon - NvimTreeGitFileDirtyHL NvimTreeGitDirtyIcon - NvimTreeGitFileIgnoredHL NvimTreeGitIgnoredIcon - NvimTreeGitFileMergeHL NvimTreeGitMergeIcon - NvimTreeGitFileNewHL NvimTreeGitNewIcon - NvimTreeGitFileRenamedHL NvimTreeGitRenamedIcon - NvimTreeGitFileStagedHL NvimTreeGitStagedIcon -< -Git Folder Folder Highlight: > - NvimTreeGitFolderDeletedHL NvimTreeGitFileDeletedHL - NvimTreeGitFolderDirtyHL NvimTreeGitFileDirtyHL - NvimTreeGitFolderIgnoredHL NvimTreeGitFileIgnoredHL - NvimTreeGitFolderMergeHL NvimTreeGitFileMergeHL - NvimTreeGitFolderNewHL NvimTreeGitFileNewHL - NvimTreeGitFolderRenamedHL NvimTreeGitFileRenamedHL - NvimTreeGitFolderStagedHL NvimTreeGitFileStagedHL -< -Diagnostics Icon: > - NvimTreeDiagnosticErrorIcon DiagnosticError - NvimTreeDiagnosticWarnIcon DiagnosticWarn - NvimTreeDiagnosticInfoIcon DiagnosticInfo - NvimTreeDiagnosticHintIcon DiagnosticHint -< -Diagnostics File Highlight: > - NvimTreeDiagnosticErrorFileHL DiagnosticUnderlineError - NvimTreeDiagnosticWarnFileHL DiagnosticUnderlineWarn - NvimTreeDiagnosticInfoFileHL DiagnosticUnderlineInfo - NvimTreeDiagnosticHintFileHL DiagnosticUnderlineHint -< -Diagnostics Folder Highlight: > - NvimTreeDiagnosticErrorFolderHL NvimTreeDiagnosticErrorFileHL - NvimTreeDiagnosticWarnFolderHL NvimTreeDiagnosticWarnFileHL - NvimTreeDiagnosticInfoFolderHL NvimTreeDiagnosticInfoFileHL - NvimTreeDiagnosticHintFolderHL NvimTreeDiagnosticHintFileHL -< ============================================================================== -Events *nvim-tree-events* +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}? (`boolean|(fun(args: vim.api.keyset.create_autocmd.callback_args): boolean)`, default: `false`) + A function called on |BufEnter| that returns true if + the file should not be focused when opening. -nvim-tree will dispatch events whenever an action is made. These events can be -subscribed to through handler functions. This allows for even further -customization of nvim-tree. +*nvim_tree.Config.UpdateFocusedFile.UpdateRoot* + Update the root directory of the tree if the file is not under the current + root directory. -A handler for an event is just a function which receives one argument, the -payload of the event. The payload is different for each event type. Refer -to |nvim_tree_registering_handlers| for more information. + Prefers vim's cwd and |nvim_tree.Config| {root_dirs}, falling back to the + directory containing the file. -*nvim_tree_registering_handlers* + Requires |nvim_tree.Config.UpdateFocusedFile| -Handlers are registered by calling |nvim-tree-api.events.subscribe()| -function with an |nvim-tree-api.events.Event| + 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. -e.g. handler for node renamed: >lua - local api = require("nvim-tree.api") - local Event = api.events.Event - api.events.subscribe(Event.NodeRenamed, function(data) - print("Node renamed from " .. data.old_name .. " to " .. data.new_name) - end) -< -*nvim_tree_events_kind* +============================================================================== +Class: Config.SystemOpen *nvim-tree-config-system-open* -- Event.Ready - When NvimTree has been initialized. - • Note: Handler takes no parameter. +*nvim_tree.Config.SystemOpen* + Open files or directories via the OS. -- Event.TreePreOpen - Invoked before the window and buffer for NvimTree are created - or opened. Before `Event.TreeOpen` - • Note: Handler takes no parameter. + Nvim: + • `>=` 0.10 uses |vim.ui.open()| unless {cmd} is specified + • `<` 0.10 calls external {cmd}: + • UNIX: `xdg-open` + • macOS: `open` + • Windows: `cmd` -- Event.TreeOpen - Invoked after the NvimTree is opened. - • Note: Handler takes no parameter. + Once nvim-tree minimum Nvim version is updated to 0.10, these options will + no longer be necessary and will be removed. -- Event.TreeClose - Invoked after the NvimTree is closed, but before the window is - closed. Dispatched on |WinClosed| event for NvimTree window. - • Note: Handler takes no parameter. + Fields: ~ + • {cmd}? (`string`) The open command itself + • {args}? (`string[]`, default: `{}` or `{ "/c", "start", '""' }` on + windows) Optional argument list. Leave empty for OS specific + default. -- Event.Resize - When NvimTree is resized. - handler parameters: ~ - size: `number` size of the view in columns. -- Event.WillRenameNode - • Note: A node can either be a file or a directory. - handler parameters: ~ - {old_name} `{string}` Absolute path to the old node location. - {new_name} `{string}` Absolute path to the new node location. -- Event.NodeRenamed - • Note: A node can either be a file or a directory. - handler parameters: ~ - {old_name} `{string}` Absolute path to the old node location. - {new_name} `{string}` Absolute path to the new node location. +============================================================================== +Class: Config.Git *nvim-tree-config-git* -- Event.FileCreated - handler parameters: ~ - {fname} `{string}` Absolute path to the created file +*nvim_tree.Config.Git* + Git operations are run in the background thus status may not immediately + appear. -- Event.WillCreateFile - handler parameters: ~ - {fname} `{string}` Absolute path to the file to be - created + Processes will be killed if they exceed {timeout} ms. Git integration will + be disabled following 5 timeouts and you will be notified. -- Event.FileRemoved - handler parameters: ~ - {fname} `{string}` Absolute path to the removed file. + Git integration may be disabled for git top-level directories via + {disable_for_dirs}: + • A list of relative paths evaluated with |fnamemodify()| `:p` OR + • A function that is passed an absolute path and returns `true` to disable -- Event.WillRemoveFile - handler parameters: ~ - {fname} `{string}` Absolute path to the file to be - removed + See |nvim-tree-icons-highlighting|. -- Event.FolderCreated - handler parameters: ~ - {folder_name} `{string}` Absolute path to the created folder. + 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. + Requires {show_on_dirs}. + • {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. -- Event.FolderRemoved - handler parameters: ~ - {folder_name} `{string}` Absolute path to the removed folder. -- Event.TreeAttachedPost - Invoked after the tree's buffer has been created and mappings - have been applied: |nvim-tree-mappings| or |nvim_tree.Config| {on_attach} - handler parameters: ~ - {buf} `{number} `API buffer handle (buffer number) -- Event.TreeRendered - Invoked every time the tree is redrawn. Normally this event - happens after `Event.TreeOpen` except that handlers of this - one will have access to the tree buffer populated with the - final content. - handler parameters: ~ - {bufnr} `{number} `API buffer handle (buffer number) - {winnr} `{number} `API window handle (window number) +============================================================================== +Class: Config.Diagnostics *nvim-tree-config-diagnostics* -*nvim_tree_events_startup* +*nvim_tree.Config.Diagnostics* + Integrate with |lsp| or COC diagnostics. -There are two special startup events in the form of User autocommands: + See |nvim-tree-icons-highlighting|. -`NvimTreeRequired` first `require("nvim-tree")` -`NvimTreeSetup` `setup({})` completed + 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. Requires + {show_on_dirs}. + • {diagnostic_opts}? (`boolean`, default: `false`) Global + |vim.diagnostic.Opts| overrides {severity} and + {icons} + • {severity}? (`table`) + *nvim_tree.Config.Diagnostics.Severity* + • {min}? (`vim.diagnostic.Severity`, default: + HINT) |vim.diagnostic.severity| + • {max}? (`vim.diagnostic.Severity`, default: + ERROR) |vim.diagnostic.severity| + • {icons}? (`table`) *nvim_tree.Config.Diagnostics.Icons* + • {hint}? (`string`) (default: `""` ) + • {info}? (`string`) (default: `""` ) + • {warning}? (`string`) (default: `""` ) + • {error}? (`string`) (default: `""` ) -Immediately before firing: a global variable of the same name will be set to a -value of 1. -Example subscription: >lua - vim.api.nvim_create_autocmd("User", { - pattern = "NvimTreeRequired", - callback = function(data) - --- - end, - }) -< ============================================================================== -Prompts *nvim-tree-prompts* +Class: Config.Modified *nvim-tree-config-modified* -Some NvimTree actions use the builtin |vim.ui.select()| prompt API for -confirmations when the |nvim_tree.Config| {select_prompts} option is set. +*nvim_tree.Config.Modified* + Indicate which files have unsaved modification. To see modified status in + the tree you will need: + • |nvim_tree.Config.Renderer.Icons.Show| {modified} OR + • |nvim_tree.Config.Renderer| {highlight_modified} -The API accepts the optional `kind` key as part of the {opts} parameter, which -can can be used to identify the type of prompt, to allow user side -configurations for different types of prompts. + See |nvim-tree-icons-highlighting|. -- `nvimtree_overwrite_rename` - overwrite or rename during |nvim-tree-api.fs.paste()| + 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. Requires + {show_on_dirs}. -- `nvimtree_remove` - delete during |nvim-tree-api.fs.remove()| -- `nvimtree_trash` - send to trash during |nvim-tree-api.fs.trash()| -- `nvimtree_bulk_delete` - delete all bookmarked during |nvim-tree-api.marks.bulk.delete()| +============================================================================== +Class: Config.Filters *nvim-tree-config-filters* -- `nvimtree_bulk_trash` - send all bookmarked to trash during |nvim-tree-api.marks.bulk.trash()| +*nvim_tree.Config.Filters* + Filters may be applied to the tree to exlude the display of + file/directories. -============================================================================== -Decorators *nvim-tree-decorators* + Multiple filters may be applied at once. -Highlighting and icons for nodes are provided by Decorators. You may provide -your own in addition to the builtin decorators. + Filters can be set at startup or toggled live via API with default + mappings. -Decorators may: -- Add icons -- Set highlight group for the name or icons -- Override node icon + `I `{git_ignored}` `|nvim_tree.api.tree.toggle_gitignore_filter()| + Ignore files based on `.gitignore`. Requires |nvim_tree.Config.Git| + + `H `{dotfiles}` `|nvim_tree.api.tree.toggle_hidden_filter()| + Filter dotfiles: files/directories starting with a `.` + + `C `{git_clean}` `|nvim_tree.api.tree.toggle_git_clean_filter()| + Filter files with no git status. `.gitignore` files will not be filtered + when {git_ignored}, as they are effectively dirty. + + `B `{no_buffer}` `|nvim_tree.api.tree.toggle_no_buffer_filter()| + Filter files that have no |buflisted()| buffer. For performance reasons + buffer delete/wipe may not be immediately shown. A reload or filesystem + event will always result in an update. + + `M `{no_bookmark}` `|nvim_tree.api.tree.toggle_no_bookmark_filter()| + Filter files that are not bookmarked. Enabling this is not useful as there + is no means yet to persist bookmarks. + + `U `{custom}` `|nvim_tree.api.tree.toggle_custom_filter()| + Disable specific file/directory names via: + • a list of backslash escaped |vim.regex| strings e.g. `"^\\.git""` + • a function passed the absolute path of the directory. + + 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}. + + 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: `{}`) -Create a `nvim_tree.api.decorator.UserDecorator` class and register it with -precedence via |nvim_tree.Config.Renderer| {decorators} -See |nvim-tree-decorator-example| ============================================================================== -Decorators: Example *nvim-tree-decorator-example* +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| -A decorator class for nodes named "example", overridind all builtin decorators -except for Cut. + This feature is bound to the `f` key by default. The filter can be cleared + with the `F` key by default. -- Highlights node name with `IncSearch` -- Creates two icons `"1"` and `"2"` placed after the node name, highlighted with - `DiffAdd` and `DiffText` -- Replaces the node icon with `"N"`, highlighted with `Error ` + 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. -Create a class file `~/.config/nvim/lua/my-decorator.lua` -Require and register it during |nvim-tree-setup|: ->lua - local MyDecorator = require("my-decorator") - require("nvim-tree").setup({ - renderer = { - decorators = { - "Git", - "Open", - "Hidden", - "Modified", - "Bookmark", - "Diagnostics", - "Copied", - MyDecorator, - "Cut", - }, - }, - }) -< -Contents of `my-decorator.lua`: ->lua - ---@class (exact) MyDecorator: nvim_tree.api.decorator.UserDecorator - ---@field private my_icon1 nvim_tree.api.HighlightedString - ---@field private my_icon2 nvim_tree.api.HighlightedString - ---@field private my_icon_node nvim_tree.api.HighlightedString - ---@field private my_highlight_group string - local MyDecorator = require("nvim-tree.api").decorator.UserDecorator:extend() +============================================================================== +Class: Config.FilesystemWatchers *nvim-tree-config-filesystem-watchers* - ---Mandatory constructor :new() will be called once per tree render, with no arguments. - function MyDecorator:new() - self.enabled = true - self.highlight_range = "name" - self.icon_placement = "after" +*nvim_tree.Config.FilesystemWatchers* + Use file system watchers (libuv `uv_fs_event_t`) to monitor the filesystem + for changes and update the tree. - -- create your icons and highlights once, applied to every node - self.my_icon1 = { str = "1", hl = { "DiffAdd" } } - self.my_icon2 = { str = "2", hl = { "DiffText" } } - self.my_icon_node = { str = "N", hl = { "Error" } } - self.my_highlight_group = "IncSearch" + With this feature, the tree will be partially updated on specific + directory changes, resulting in better performance. - -- Define the icon signs only once - -- Only needed if you are using icon_placement = "signcolumn" - -- self:define_sign(self.my_icon1) - -- self:define_sign(self.my_icon2) - end + 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. - ---Override node icon - ---@param node nvim_tree.api.Node - ---@return nvim_tree.api.HighlightedString? icon_node - function MyDecorator:icon_node(node) - if node.name == "example" then - return self.my_icon_node - else - return nil - end - end + 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. - ---Return two icons for DecoratorIconPlacement "after" - ---@param node nvim_tree.api.Node - ---@return nvim_tree.api.HighlightedString[]? icons - function MyDecorator:icons(node) - if node.name == "example" then - return { self.my_icon1, self.my_icon2, } - else - return nil - end - end - ---Exactly one highlight group for DecoratorHighlightRange "name" - ---@param node nvim_tree.api.Node - ---@return string? highlight_group - function MyDecorator:highlight_group(node) - if node.name == "example" then - return self.my_highlight_group - else - return nil - end - end - return MyDecorator -< ============================================================================== -OS Specific Restrictions *nvim-tree-os-specific* +Class: Config.Actions *nvim-tree-config-actions* -Windows WSL and PowerShell -- Trash is synchronized -- Executable file detection is disabled as this is non-performant and can - freeze Nvim -- Some filesystem watcher error related to permissions will not be reported +*nvim_tree.Config.Actions* -============================================================================== -netrw *nvim-tree-netrw* + 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| -|netrw| is a standard Nvim plugin that is enabled by default. It provides, -amongst other functionality, a file/directory browser. +*nvim_tree.Config.Actions.ChangeDir* + vim |current-directory| behaviour -It interferes with nvim-tree and the intended user experience is nvim-tree -replacing the |netrw| browser. + 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. -It is strongly recommended to disable |netrw|. As it is a bundled plugin it -must be disabled manually at the start of your `init.lua` as per |netrw-noload|: >lua +*nvim_tree.Config.Actions.ExpandAll* + Configure |nvim_tree.api.tree.expand_all()| and + |nvim_tree.api.node.expand()| - vim.g.loaded_netrw = 1 - vim.g.loaded_netrwPlugin = 1 -< -There are many |netrw| features beyond the file browser. If you want to -keep using |netrw| without its browser features please ensure: + Fields: ~ + • {max_folder_discovery}? (`integer`, default: `300`) Limit the number + of folders being explored when expanding + every folder. Avoids hanging Nvim when + running this action on very large folders. + • {exclude}? (`string[]`, default: `{}`) A list of + directories that should not be expanded + automatically e.g + `{ ".git", "target", "build" }` -|nvim_tree.Config| {disable_netrw}` = false` -|nvim_tree.Config| {hijack_netrw}` = true` +*nvim_tree.Config.Actions.FilePopup* + {file_popup} floating window. -============================================================================== -Legacy *nvim-tree-legacy* + {open_win_config} is passed to |nvim_open_win()|, default: >lua + { + col = 1, + row = 1, + relative = "cursor", + border = "shadow", + style = "minimal", + } +< -Breaking refactors have been made however the legacy versions will be silently -migrated and used. -There are no plans to remove this migration. + You shouldn't define {width} and {height} values here. They will be + overridden to fit the file_popup content. -============================================================================== -Legacy: Config *nvim-tree-legacy-opts* + Fields: ~ + • {open_win_config}? (`vim.api.keyset.win_config`) (default: + `{ col = 1, row = 1, relative = "cursor", border = "shadow", style = "minimal", }`) -Legacy config is translated to the current, making type and value changes as -needed. +*nvim_tree.Config.Actions.OpenFile* + Opening files. -`update_cwd` |nvim_tree.Config| {sync_root_with_cwd} -`update_focused_file.update_cwd` |nvim_tree.Config.UpdateFocusedFile| {update_root} -`open_on_tab` |nvim_tree.Config.Tab.Sync| {open} -`ignore_buf_on_tab_change` |nvim_tree.Config.Tab.Sync| {ignore} -`renderer.root_folder_modifier` |nvim_tree.Config.Renderer| {root_folder_label} -`update_focused_file.debounce_delay` |nvim_tree.Config.View| {debounce_delay} -`trash.require_confirm` |nvim_tree.Config.UI.Confirm| {trash} -`view.adaptive_size` |nvim_tree.Config.View| {width} -`sort_by` |nvim_tree.Config.Sort| {sorter} -`git.ignore` |nvim_tree.Config.Filters| {git_ignored} -`renderer.icons.webdev_colors` |nvim_tree.Config.Renderer.Icons.WebDevicons.File| {color} -`renderer.icons.padding` |nvim_tree.Config.Renderer.Icons.Padding| {icon} + 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| -============================================================================== -Legacy: Highlight *nvim-tree-legacy-highlight* +*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. -Legacy highlight group are still obeyed when they are defined and the current -highlight group is not, hard linking as follows: > + When it is not enabled the file will open in the window from which you + last opened the tree, obeying {exclude} - NvimTreeModifiedIcon NvimTreeModifiedFile - NvimTreeOpenedHL NvimTreeOpenedFile - NvimTreeBookmarkIcon NvimTreeBookmark + You may define a {picker} function that should return the window id that + will open the node, or `nil` if an invalid window is picked or user + cancelled the action. The picker may create a new window. - NvimTreeGitDeletedIcon NvimTreeGitDeleted - NvimTreeGitDirtyIcon NvimTreeGitDirty - NvimTreeGitIgnoredIcon NvimTreeGitIgnored - NvimTreeGitMergeIcon NvimTreeGitMerge - NvimTreeGitNewIcon NvimTreeGitNew - NvimTreeGitRenamedIcon NvimTreeGitRenamed - NvimTreeGitStagedIcon NvimTreeGitStaged + Fields: ~ + • {enable}? (`boolean`) (default: `true`) + • {picker}? (`"default"|(fun(): integer)`, default: `"default"`) + Change the default window picker or define your own. + • {chars}? (`string`, default: + `"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"`) Identifier + characters to use. + • {exclude}? (`nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude`) + |nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude| - NvimTreeGitFileDeletedHL NvimTreeFileDeleted - NvimTreeGitFileDirtyHL NvimTreeFileDirty - NvimTreeGitFileIgnoredHL NvimTreeFileIgnored - NvimTreeGitFileMergeHL NvimTreeFileMerge - NvimTreeGitFileNewHL NvimTreeFileNew - NvimTreeGitFileRenamedHL NvimTreeFileRenamed - NvimTreeGitFileStagedHL NvimTreeFileStaged +*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 - NvimTreeGitFolderDeletedHL NvimTreeFolderDeleted - NvimTreeGitFolderDirtyHL NvimTreeFolderDirty - NvimTreeGitFolderIgnoredHL NvimTreeFolderIgnored - NvimTreeGitFolderMergeHL NvimTreeFolderMerge - NvimTreeGitFolderNewHL NvimTreeFolderNew - NvimTreeGitFolderRenamedHL NvimTreeFolderRenamed - NvimTreeGitFolderStagedHL NvimTreeFolderStaged + Fields: ~ + • {filetype}? (`string[]`) (default: + `{ "notify", "lazy", "qf", "diff", "fugitive", "fugitiveblame", }`) + • {buftype}? (`string[]`) (default: + `{ "nofile", "terminal", "help", }`) - NvimTreeLspDiagnosticsError NvimTreeDiagnosticErrorIcon - NvimTreeLspDiagnosticsWarning NvimTreeDiagnosticWarnIcon - NvimTreeLspDiagnosticsInformation NvimTreeDiagnosticInfoIcon - NvimTreeLspDiagnosticsHint NvimTreeDiagnosticHintIcon +*nvim_tree.Config.Actions.RemoveFile* + Removing files. + + Fields: ~ + • {close_window}? (`boolean`, default: `true`) Close any window that + displays a file when removing that file from the + tree. - NvimTreeLspDiagnosticsErrorText NvimTreeDiagnosticErrorFileHL - NvimTreeLspDiagnosticsWarningText NvimTreeDiagnosticWarnFileHL - NvimTreeLspDiagnosticsInformationText NvimTreeDiagnosticInfoFileHL - NvimTreeLspDiagnosticsHintText NvimTreeDiagnosticHintFileHL - NvimTreeLspDiagnosticsErrorFolderText NvimTreeDiagnosticErrorFolderHL - NvimTreeLspDiagnosticsWarningFolderText NvimTreeDiagnosticWarnFolderHL - NvimTreeLspDiagnosticsInformationFolderText NvimTreeDiagnosticInfoFolderHL - NvimTreeLspDiagnosticsHintFolderText NvimTreeDiagnosticHintFolderHL -< ============================================================================== -Hidden Display *nvim-tree-hidden-display* +Class: Config.Trash *nvim-tree-config-trash* -Show a summary of hidden files below the tree highlighted with `NvimTreeHiddenDisplay +*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 -Configure via |nvim_tree.Config.Renderer| {hidden_display} + Fields: ~ + • {cmd}? (`string`) (default: `"gio trash"` or `"trash"`) - *nvim_tree.Config.Renderer.HiddenDisplay* - • `none`: disabled - • `simple`: show how many hidden files are in a folder - • `all`: show how many hidden and the number of hidden files by reason - • `fun(hidden_stats: table): string`: returns a summary of hidden stats -Example `"all"`: -If a folder has 14 hidden items for various reasons, the display might show: > - (14 total git: 5, dotfile: 9) -< -If a function is provided, it receives a table `hidden_stats` where keys are -reasons and values are the count of hidden files for that reason. -The `hidden_stats` argument is structured as follows, where is the number -of hidden files related to the field: > - hidden_stats = { - bookmark = , - buf = , - custom = , - dotfile = , - git = , - live_filter = , - } -< -Example of function that can be passed: >lua - function(hidden_stats) - local total_count = 0 - for reason, count in pairs(hidden_stats) do - total_count = total_count + count - end +============================================================================== +Class: Config.Tab *nvim-tree-config-tab* - if total_count > 0 then - return "(" .. tostring(total_count) .. " hidden)" - end - return nil - end -< +*nvim_tree.Config.Tab* -============================================================================== -Class: Config *nvim-tree-config* + Fields: ~ + • {sync}? (`nvim_tree.Config.Tab.Sync`) |nvim_tree.Config.Tab.Sync| -*nvim_tree.Config* - Arguments to pass to |nvim-tree-setup|. +*nvim_tree.Config.Tab.Sync* - When a value is not present/nil, the default will be used. + 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` - They can be validated by |lsp| when passed directly e.g. >lua - require("nvim-tree").setup({ - hijack_cursor = true, - }) -< - or as a typed variable e.g. >lua - ---@type nvim_tree.Config - local config = { - hijack_cursor = true, - } - require("nvim-tree").setup(config) -< - {on_attach} Runs when creating the nvim-tree buffer. Use this to set your - |nvim-tree-mappings|. When not a function, |nvim-tree-mappings-default| - will be used. +============================================================================== +Class: Config.Notify *nvim-tree-config-notify* - {hijack_cursor} keep the cursor on the first letter of the filename when - moving in the tree. +*nvim_tree.Config.Notify* + nvim-tree |vim.log.levels| + • `ERROR`: hard errors e.g. failure to read from the file system. + • `WARN`: non-fatal errors e.g. unable to system open a file. + • `INFO`: information only e.g. file copy path confirmation. + • `DEBUG`: information for troubleshooting, e.g. failures in some window + closing operations. - {auto_reload_on_write} reload the explorer every time a buffer is written - to. + Fields: ~ + • {threshold}? (`vim.log.levels`, default: `vim.log.levels.INFO`) + Specify minimum notification |vim.log.levels| + • {absolute_path}? (`boolean`, default: `true`) Use absolute paths in + FS action notifications, otherwise item names. - {disable_netrw} completely disables |netrw|, see |nvim-tree-netrw| for - details. It is strongly advised to eagerly disable netrw, due to race - conditions at vim startup. - {hijack_netrw} hijacks netrw windows, ignored when {disable_netrw}. - {hijack_unnamed_buffer_when_opening} opens in place of the unnamed buffer - if it's empty. +============================================================================== +Class: Config.Bookmarks *nvim-tree-config-bookmarks* - {root_dirs} preferred root directories, requires - |nvim_tree.Config.UpdateFocusedFile.UpdateRoot|. +*nvim_tree.Config.Bookmarks* + Optionally {persist} bookmarks to a json file: + • `true` use default: `stdpath("data") .. "/nvim-tree-bookmarks.json"` + • `false` do not persist + • `string` absolute path of your choice - {prefer_startup_root} prefer startup root directory when updating root - directory of the tree. Requires - |nvim_tree.Config.UpdateFocusedFile.UpdateRoot|. + Fields: ~ + • {persist}? (`boolean|string`) (default: `false`) - {sync_root_with_cwd} changes the tree root directory on |DirChanged| and - refreshes the tree. - {reload_on_bufenter} automatically reloads the tree on |BufEnter| - nvim-tree. - {respect_buf_cwd} changes the |current-directory| of nvim-tree to that of - new buffer's when opening nvim-tree. +============================================================================== +Class: Config.Help *nvim-tree-config-help* - {select_prompts} uses |vim.ui.select()| style prompts. Necessary when - using a UI prompt decorator such as dressing.nvim or - telescope-ui-select.nvim +*nvim_tree.Config.Help* + Configure help window, default mapping `g?` + + *nvim_tree.Config.Help.SortBy* + • `"key"`: alphabetically by keymap + • `"desc"`: alphabetically by description Fields: ~ - • {on_attach}? (`"default"|(fun(bufnr: integer))`) - (default: `default`) - • {hijack_cursor}? (`boolean`) (default: `false`) - • {auto_reload_on_write}? (`boolean`) (default: `true`) - • {disable_netrw}? (`boolean`) (default: `false`) - • {hijack_netrw}? (`boolean`) (default: `true`) - • {hijack_unnamed_buffer_when_opening}? (`boolean`) (default: `false`) - • {root_dirs}? (`string[]`) (default: `{}`) - • {prefer_startup_root}? (`boolean`) (default: `false`) - • {sync_root_with_cwd}? (`boolean`) (default: `false`) - • {reload_on_bufenter}? (`boolean`) (default: `false`) - • {respect_buf_cwd}? (`boolean`) (default: `false`) - • {select_prompts}? (`boolean`) (default: `false`) - • {sort}? (`nvim_tree.Config.Sort`) - |nvim_tree.Config.Sort| - • {view}? (`nvim_tree.Config.View`) - |nvim_tree.Config.View| - • {renderer}? (`nvim_tree.Config.Renderer`) - |nvim_tree.Config.Renderer| - • {hijack_directories}? (`nvim_tree.Config.HijackDirectories`) - |nvim_tree.Config.HijackDirectories| - • {update_focused_file}? (`nvim_tree.Config.UpdateFocusedFile`) - |nvim_tree.Config.UpdateFocusedFile| - • {system_open}? (`nvim_tree.Config.SystemOpen`) - |nvim_tree.Config.SystemOpen| - • {git}? (`nvim_tree.Config.Git`) - |nvim_tree.Config.Git| - • {diagnostics}? (`nvim_tree.Config.Diagnostics`) - |nvim_tree.Config.Diagnostics| - • {modified}? (`nvim_tree.Config.Modified`) - |nvim_tree.Config.Modified| - • {filters}? (`nvim_tree.Config.Filters`) - |nvim_tree.Config.Filters| - • {live_filter}? (`nvim_tree.Config.LiveFilter`) - |nvim_tree.Config.LiveFilter| - • {filesystem_watchers}? (`nvim_tree.Config.FilesystemWatchers`) - |nvim_tree.Config.FilesystemWatchers| - • {actions}? (`nvim_tree.Config.Actions`) - |nvim_tree.Config.Actions| - • {trash}? (`nvim_tree.Config.Trash`) - |nvim_tree.Config.Trash| - • {tab}? (`nvim_tree.Config.Tab`) - |nvim_tree.Config.Tab| - • {bookmarks}? (`nvim_tree.Config.Bookmarks`) - |nvim_tree.Config.Bookmarks| - • {notify}? (`nvim_tree.Config.Notify`) - |nvim_tree.Config.Notify| - • {help}? (`nvim_tree.Config.Help`) - |nvim_tree.Config.Help| - • {ui}? (`nvim_tree.Config.UI`) - |nvim_tree.Config.UI| - • {experimental}? (`nvim_tree.Config.Experimental`) - |nvim_tree.Config.Experimental| - • {log}? (`nvim_tree.Config.Log`) - |nvim_tree.Config.Log| + • {sort_by}? (`nvim_tree.Config.Help.SortBy`, default: `"key"`) + |nvim_tree.Config.Help.SortBy| ============================================================================== -Class: Config.Sort *nvim-tree-config-sort* - -*nvim_tree.Config.Sort* - Sort files within a directory. - - {sorter} presets *nvim_tree.Config.Sort.Sorter* - • `"name"` - • `"case_sensitive"` name - • `"modification_time"` - • `"extension"` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz` - • `"suffix"` uses the last e.g. `foo.tar.gz` -> `.gz` - • `"filetype"` |filetype| +Class: Config.UI *nvim-tree-config-ui* - {sorter} may be a function that is passed a list of `nvim_tree.api.Node` - to be sorted in place e.g. >lua +*nvim_tree.Config.UI* - ---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 -< + Fields: ~ + • {confirm}? (`nvim_tree.Config.UI.Confirm`) + |nvim_tree.Config.UI.Confirm| - {sorter} may be a function that returns a |nvim_tree.Config.Sort.Sorter| +*nvim_tree.Config.UI.Confirm* + Confirmation prompts. Fields: ~ - • {sorter}? (`nvim_tree.Config.Sort.Sorter|(fun(nodes: nvim_tree.api.Node[]): nvim_tree.Config.Sort.Sorter?)`) - (default: `"name"`) - • {folders_first}? (`boolean`, default: `true`) Sort folders before - files. Has no effect when {sorter} is a function. - • {files_first}? (`boolean`, default: `false`) Sort files before - folders. Has no effect when {sorter} is a function. - Overrides {folders_first}. + • {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` ============================================================================== -Class: Config.View *nvim-tree-config-view* - -*nvim_tree.Config.View* - Configures the dimensions and appearance of the nvim-tree window. +Class: Config.Experimental *nvim-tree-config-experimental* - The window is "docked" at the left by default, however may be configured - to float: |nvim_tree.Config.View.Float| +*nvim_tree.Config.Experimental* + Experimental features that may become default or optional functionality. - {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. + In the event of a problem please disable the experiment and raise an + issue. - *nvim_tree.Config.View.WidthSpec* - • `string`: `x%` string e.g. `30%` - • `integer`: number of columns - • `function`: returns one of the above - Fields: ~ - • {centralize_selection}? (`boolean`, default: `false`) When - entering nvim-tree, reposition the - view so that the current node is - initially centralized, see |zz|. - • {cursorline}? (`boolean`, default: `true`) - |'cursorline'| - • {cursorlineopt}? (`string`, default: `both`) - |'cursorlineopt'| - • {debounce_delay}? (`integer`, default: `15`) Idle - milliseconds before some reload / - refresh operations. Increase if you - experience performance issues around - screen refresh. - • {side}? (`"left"|"right"`) (default: `"left"`) - • {preserve_window_proportions}? (`boolean`, default: `false`) - Preserves window proportions when - opening a file. If `false`, the height - and width of windows other than - nvim-tree will be equalized. - • {number}? (`boolean`, default: `false`) - |'number'| - • {relativenumber}? (`boolean`, default: `false`) - |'relativenumber'| - • {signcolumn}? (`"yes"|"auto"|"no"`, default: - `"yes"`) |'signcolumn'| - • {width}? (`nvim_tree.Config.View.WidthSpec|nvim_tree.Config.View.Width`) - (default: `30`) - • {float}? (`nvim_tree.Config.View.Float`) - |nvim_tree.Config.View.Float| -*nvim_tree.Config.View.Float* - Configure floating window behaviour +============================================================================== +Class: Config.Log *nvim-tree-config-log* - {open_win_config} is passed to |nvim_open_win()|, default: >lua - { - relative = "editor", - border = "rounded", - width = 30, - height = 30, - row = 1, - col = 1, - } -< +*nvim_tree.Config.Log* + Log to a file `nvim-tree.log` in |stdpath()| `log`, usually + `${XDG_STATE_HOME}/nvim` 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: - `{ relative = "editor", border = "rounded", width = 30, height = 30, row = 1, col = 1, }`) + • {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.View.Width* - Configure dynamic width based on longest line. +*nvim_tree.Config.Log.Types* + Specify which information to log. Fields: ~ - • {min}? (`nvim_tree.Config.View.WidthSpec`) (default: `30`) - • {max}? (`nvim_tree.Config.View.WidthSpec`, default: `-1`) - -1 for unbounded. - • {lines_excluded}? (`("root")[]`, default: `{ "root" }`) Exclude these - lines when computing width. - • {padding}? (`nvim_tree.Config.View.WidthSpec`, default: `1`) - Extra padding to the right. + • {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. ============================================================================== -Class: Config.Renderer *nvim-tree-config-renderer* +Lua module: nvim_tree.api *nvim-tree-api* -*nvim_tree.Config.Renderer* - Controls the appearance of the tree. +nvim-tree exposes a public API. This is non breaking, with additions made as +necessary. - See |nvim-tree-icons-highlighting| for {highlight_} and {decorators} - fields. +Please do not require or use modules other than `nvim-tree.api`, as internal +modules are not stable and will change without notice. - {root_folder_label} has 3 forms: - • `string`: |filename-modifiers| format string, default `":~:s?$?/..?"` - • `boolean`: `true` to disable - • `fun(root_cwd: string): string`: return a literal string from root's - absolute path e.g. >lua - my_root_folder_label = function(path) - return ".../" .. vim.fn.fnamemodify(path, ":t") - end +The API is separated into multiple modules, which can be accessed via the +parent `nvim-tree.api` or via `nvim-tree.api.`. The following examples +are equivalent: >lua + + local api = require("nvim-tree.api") + api.tree.reload() + + local tree = require("nvim-tree.api.tree") + tree.reload() < - Fields: ~ - • {add_trailing}? (`boolean`, default: `false`) Appends a - trailing slash to folder and symlink folder - target names. - • {group_empty}? (`boolean|(fun(relative_path: string): string)`, default: `false`) - Compact folders that only contain a single - folder into one node. Function variant - takes the relative path of grouped folders - and returns a string to be displayed. - • {full_name}? (`boolean`, default: `false`) Display nodes - whose name length is wider than the width - of nvim-tree window in floating window. - • {root_folder_label}? (`string|boolean|(fun(root_cwd: string): string)`) - (default: `":~:s?$?/..?"`) - • {indent_width}? (`integer`, default: `2`) Number of spaces - for each tree nesting level. Minimum 1. - • {hidden_display}? (`nvim_tree.Config.Renderer.HiddenDisplay`, default: `none`) - |nvim-tree-hidden-display| - • {symlink_destination}? (`boolean`, default: `true`) Appends an - arrow followed by the target of the - symlink. - • {decorators}? (`(string|nvim_tree.api.decorator.UserDecorator)[]`) - (default: - `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) - • {highlight_git}? (`nvim_tree.Config.Renderer.Highlight`) - (default: `"none"`) - • {highlight_opened_files}? (`nvim_tree.Config.Renderer.Highlight`) - (default: `"none"`) - • {highlight_hidden}? (`nvim_tree.Config.Renderer.Highlight`) - (default: `"none"`) - • {highlight_modified}? (`nvim_tree.Config.Renderer.Highlight`) - (default: `"none"`) - • {highlight_bookmarks}? (`nvim_tree.Config.Renderer.Highlight`) - (default: `"none"`) - • {highlight_diagnostics}? (`nvim_tree.Config.Renderer.Highlight`) - (default: `"none"`) - • {highlight_clipboard}? (`nvim_tree.Config.Renderer.Highlight`) - (default: `"name"`) - • {special_files}? (`string[]`, default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }`) - Highlight special files and directories - with `NvimTreeSpecial*`. - • {indent_markers}? (`nvim_tree.Config.Renderer.IndentMarkers`) - |nvim_tree.Config.Renderer.IndentMarkers| - • {icons}? (`nvim_tree.Config.Renderer.Icons`) - |nvim_tree.Config.Renderer.Icons| +Generally, functions accepting {node} as their first argument will use the +node under the cursor when that argument is not present or nil. e.g. the +following are functionally identical: >lua -*nvim_tree.Config.Renderer.Icons* - Icons and separators + api.node.open.edit(nil, { focus = true }) - See |nvim-tree-icons-highlighting| for: {_placement} fields. + api.node.open.edit(api.tree.get_node_under_cursor(), { focus = true }) +< + + +*nvim_tree.api.DirectoryLinkNode* + Extends: |nvim_tree.api.DirectoryNode| + + DirectoryLink + +*nvim_tree.api.DirectoryNode* + Extends: |nvim_tree.api.Node| + + Directory Fields: ~ - • {git_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`) - (default: `before`) - • {hidden_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`) - (default: `after`) - • {modified_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`) - (default: `after`) - • {bookmarks_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`) - (default: `signcolumn`) - • {diagnostics_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`) - (default: `signcolumn`) - • {padding}? (`table`) - *nvim_tree.Config.Renderer.Icons.Padding* - • {icon}? (`string`, default: `" "`) Between - icon and filename. - • {folder_arrow}? (`string`, default: `" "`) - Between folder arrow icon and file/folder - icon. - • {symlink_arrow}? (`string`, default: `" ➛ "`) Separator - between symlink source and target. - • {show}? (`nvim_tree.Config.Renderer.Icons.Show`) - |nvim_tree.Config.Renderer.Icons.Show| - • {glyphs}? (`nvim_tree.Config.Renderer.Icons.Glyphs`) - |nvim_tree.Config.Renderer.Icons.Glyphs| - • {web_devicons}? (`nvim_tree.Config.Renderer.Icons.WebDevicons`) - |nvim_tree.Config.Renderer.Icons.WebDevicons| + • {has_children} (`boolean`) + • {nodes} (`nvim_tree.api.Node[]`) + • {open} (`boolean`) -*nvim_tree.Config.Renderer.Icons.Glyphs* - See |nvim-tree-icons-highlighting|. +*nvim_tree.api.FileLinkNode* + Extends: |nvim_tree.api.FileNode| - Glyphs that appear in the sign column must have length <= 2 + File Link + +*nvim_tree.api.FileNode* + Extends: |nvim_tree.api.Node| + + File Fields: ~ - • {default}? (`string`, default: `""`) Files - • {symlink}? (`string`) (default: `""`) - • {bookmark}? (`string`) (default: `"󰆤"`) - • {modified}? (`string`) (default: `"●"`) - • {hidden}? (`string`) (default: `"󰜌"`) - • {folder}? (`table`) *nvim_tree.Config.Renderer.Icons.Glyphs.Folder* - • {arrow_closed}? (`string`) (default: left arrow) - • {arrow_open}? (`string`) (default: down arrow) - • {default}? (`string`) (default: `""`) - • {open}? (`string`) (default: `""`) - • {empty}? (`string`) (default: `""`) - • {empty_open}? (`string`) (default: `""`) - • {symlink}? (`string`) (default: `""`) - • {symlink_open}? (`string`) (default: `""`) - • {git}? (`table`) *nvim_tree.Config.Renderer.Icons.Glyphs.Git* - • {unstaged}? (`string`) (default: `"✗"`) - • {staged}? (`string`) (default: `"✓"`) - • {unmerged}? (`string`) (default: `""`) - • {renamed}? (`string`) (default: `"➜"`) - • {untracked}? (`string`) (default: `"★"`) - • {deleted}? (`string`) (default: `""`) - • {ignored}? (`string`) (default: `"◌"`) + • {extension} (`string`) -*nvim_tree.Config.Renderer.Icons.Show* - See |nvim-tree-icons-highlighting|. +*nvim_tree.api.LinkNode* + Link mixin Fields: ~ - • {file}? (`boolean`) (default: `true`) - • {folder}? (`boolean`) (default: `true`) - • {git}? (`boolean`) (default: `true`) - • {modified}? (`boolean`) (default: `true`) - • {hidden}? (`boolean`) (default: `false`) - • {diagnostics}? (`boolean`) (default: `true`) - • {bookmarks}? (`boolean`) (default: `true`) - • {folder_arrow}? (`boolean`, default: `true`) Show a small arrow - before the folder node. Arrow will be a part of the - node when using - |nvim_tree.Config.Renderer.IndentMarkers|. + • {link_to} (`string`) + • {fs_stat_target} (`uv.fs_stat.result`) + +*nvim_tree.api.Node* + Base Node, Abstract + + Fields: ~ + • {type} (`"file"|"directory"|"link"`) uv.fs_stat.result.type + • {absolute_path} (`string`) + • {executable} (`boolean`) + • {fs_stat} (`uv.fs_stat.result?`) + • {git_status} (`GitNodeStatus?`) + • {hidden} (`boolean`) + • {name} (`string`) + • {parent} (`nvim_tree.api.DirectoryNode?`) + • {diag_severity} (`lsp.DiagnosticSeverity?`) + +*nvim_tree.api.RootNode* + Extends: |nvim_tree.api.DirectoryNode| + + Root Directory + + -*nvim_tree.Config.Renderer.Icons.WebDevicons* - Configure optional plugin `nvim-tree/nvim-web-devicons`, see - |nvim-tree-icons-highlighting|. +============================================================================== +Lua module: nvim_tree.api.commands *nvim-tree-api-commands* + +*nvim_tree.api.commands.Command* + Arguments for |nvim_create_user_command()| Fields: ~ - • {file}? (`table`) - *nvim_tree.Config.Renderer.Icons.WebDevicons.File* - • {enable}? (`boolean`) (default: `true`) - • {color}? (`boolean`) (default: `true`) - • {folder}? (`table`) - *nvim_tree.Config.Renderer.Icons.WebDevicons.Folder* - • {enable}? (`boolean`) (default: `false`) - • {color}? (`boolean`) (default: `true`) + • {name} (`string`) + • {command} (`fun(args: vim.api.keyset.create_user_command.command_args)`) + • {opts} (`vim.api.keyset.user_command`) -*nvim_tree.Config.Renderer.IndentMarkers* - Fields: ~ - • {enable}? (`boolean`, default: `false`) Display indent markers - when folders are open. - • {inline_arrows}? (`boolean`, default: `true`) Display folder arrows - in the same column as indent marker when using - |nvim_tree.Config.Renderer.Icons.Padding| - {folder_arrow} - • {icons}? (`table`) - *nvim_tree.Config.Renderer.IndentMarkers.Icons* - Before the file/directory, length 1. - • {corner}? (`string`) (default: `"└"`) - • {edge}? (`string`) (default: `"│"`) - • {item}? (`string`) (default: `"│"`) - • {bottom}? (`string`) (default: `"─"`) - • {none}? (`string`) (default: `" "`) +get() *nvim_tree.api.commands.get()* + Retrieve all nvim-tree commands, see |nvim-tree-commands| + Return: ~ + (`nvim_tree.api.commands.Command[]`) ============================================================================== -Class: Config.HijackDirectories *nvim-tree-config-hijack-directories* +Lua module: nvim_tree.api.events *nvim-tree-api-events* -*nvim_tree.Config.HijackDirectories* - Hijack directory buffers by replacing the directory buffer with the tree. +subscribe({event_type}, {callback}) *nvim_tree.api.events.subscribe()* + Register a handler for an event, see |nvim-tree-events|. - Disable this option if you use vim-dirvish or dirbuf.nvim. + Parameters: ~ + • {event_type} (`string`) |nvim_tree_events_kind| + • {callback} (`fun(payload: table?)`) - 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. +============================================================================== +Lua module: nvim_tree.api.filter *nvim-tree-api-filter* +live_filter.clear() *nvim_tree.api.filter.live_filter.clear()* + Exit live filter mode. + +live_filter.start() *nvim_tree.api.filter.live_filter.start()* + Enter live filter mode. Opens an input window with |filetype| + `NvimTreeFilter` ============================================================================== -Class: Config.UpdateFocusedFile *nvim-tree-config-update-focused-file* +Lua module: nvim_tree.api.fs *nvim-tree-api-fs* -*nvim_tree.Config.UpdateFocusedFile* - Update the focused file on |BufEnter|, uncollapsing folders recursively. +clear_clipboard() *nvim_tree.api.fs.clear_clipboard()* + Clear the nvim-tree clipboard. - Fields: ~ - • {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`) - A function called on |BufEnter| that returns true if - the file should not be focused when opening. +copy.absolute_path({node}) *nvim_tree.api.fs.copy.absolute_path()* + Copy the absolute path to the system clipboard. -*nvim_tree.Config.UpdateFocusedFile.UpdateRoot* - Update the root directory of the tree if the file is not under the current - root directory. + Parameters: ~ + • {node} (`nvim_tree.api.Node`) - Prefers vim's cwd and |nvim_tree.Config| {root_dirs}, falling back to the - directory containing the file. +copy.basename({node}) *nvim_tree.api.fs.copy.basename()* + Copy the name with extension omitted to the system clipboard. - Requires |nvim_tree.Config.UpdateFocusedFile| + Parameters: ~ + • {node} (`nvim_tree.api.Node`) - 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. +copy.filename({node}) *nvim_tree.api.fs.copy.filename()* + Copy the name to the system clipboard. + Parameters: ~ + • {node} (`nvim_tree.api.Node`) +copy.node({node}) *nvim_tree.api.fs.copy.node()* + Copy to the nvim-tree clipboard. -============================================================================== -Class: Config.SystemOpen *nvim-tree-config-system-open* + Parameters: ~ + • {node} (`nvim_tree.api.Node`) -*nvim_tree.Config.SystemOpen* - Open files or directories via the OS. +copy.relative_path({node}) *nvim_tree.api.fs.copy.relative_path()* + Copy the path relative to the tree root to the system clipboard. - Nvim: - • `>=` 0.10 uses |vim.ui.open()| unless {cmd} is specified - • `<` 0.10 calls external {cmd}: - • UNIX: `xdg-open` - • macOS: `open` - • Windows: `cmd` + Parameters: ~ + • {node} (`nvim_tree.api.Node`) - Once nvim-tree minimum Nvim version is updated to 0.10, these options will - no longer be necessary and will be removed. +create({node}) *nvim_tree.api.fs.create()* + Prompt to create a file or directory. - Fields: ~ - • {cmd}? (`string`) The open command itself - • {args}? (`string[]`, default: `{}` or `{ "/c", "start", '""' }` on - windows) Optional argument list. Leave empty for OS specific - default. + When {node} is a file it will be created in the parent directory. + Use a trailing `"/"` to create a directory e.g. `"foo/"` + Multiple directories/files may be created e.g. `"foo/bar/baz"` -============================================================================== -Class: Config.Git *nvim-tree-config-git* + Parameters: ~ + • {node} (`nvim_tree.api.Node`) -*nvim_tree.Config.Git* - Git operations are run in the background thus status may not immediately - appear. +cut({node}) *nvim_tree.api.fs.cut()* + Cut to the nvim-tree clipboard. - Processes will be killed if they exceed {timeout} ms. Git integration will - be disabled following 5 timeouts and you will be notified. + Parameters: ~ + • {node} (`nvim_tree.api.Node`) - 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 +paste({node}) *nvim_tree.api.fs.paste()* + Paste from the nvim-tree clipboard. - See |nvim-tree-icons-highlighting|. + If {node} is a file it will pasted in the parent directory. - 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. - Requires {show_on_dirs}. - • {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. + Parameters: ~ + • {node} (`nvim_tree.api.Node`) +print_clipboard() *nvim_tree.api.fs.print_clipboard()* + Print the contents of the nvim-tree clipboard. +remove({node}) *nvim_tree.api.fs.remove()* + Delete from the file system. -============================================================================== -Class: Config.Diagnostics *nvim-tree-config-diagnostics* + Parameters: ~ + • {node} (`nvim_tree.api.Node`) -*nvim_tree.Config.Diagnostics* - Integrate with |lsp| or COC diagnostics. +rename({node}) *nvim_tree.api.fs.rename()* + Prompt to rename by name. - See |nvim-tree-icons-highlighting|. + Parameters: ~ + • {node} (`nvim_tree.api.Node`) - 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. Requires - {show_on_dirs}. - • {diagnostic_opts}? (`boolean`, default: `false`) Global - |vim.diagnostic.Opts| overrides {severity} and - {icons} - • {severity}? (`table`) - *nvim_tree.Config.Diagnostics.Severity* - • {min}? (`vim.diagnostic.Severity`, default: - HINT) |vim.diagnostic.severity| - • {max}? (`vim.diagnostic.Severity`, default: - ERROR) |vim.diagnostic.severity| - • {icons}? (`table`) *nvim_tree.Config.Diagnostics.Icons* - • {hint}? (`string`) (default: `""` ) - • {info}? (`string`) (default: `""` ) - • {warning}? (`string`) (default: `""` ) - • {error}? (`string`) (default: `""` ) +rename_basename({node}) *nvim_tree.api.fs.rename_basename()* + Prompt to rename by name with extension omitted. + + Parameters: ~ + • {node} (`nvim_tree.api.Node`) + +rename_full({node}) *nvim_tree.api.fs.rename_full()* + Prompt to rename by absolute path. + + Parameters: ~ + • {node} (`nvim_tree.api.Node`) + +rename_node({node}) *nvim_tree.api.fs.rename_node()* + Prompt to rename. + + Parameters: ~ + • {node} (`nvim_tree.api.Node`) + +rename_sub({node}) *nvim_tree.api.fs.rename_sub()* + Prompt to rename by absolute path with name omitted. + + Parameters: ~ + • {node} (`nvim_tree.api.Node`) + +trash({node}) *nvim_tree.api.fs.trash()* + Trash as per |nvim_tree.Config.Trash| + Parameters: ~ + • {node} (`nvim_tree.api.Node`) ============================================================================== -Class: Config.Modified *nvim-tree-config-modified* +Lua module: nvim_tree.api.health *nvim-tree-api-health* -*nvim_tree.Config.Modified* - Indicate which files have unsaved modification. To see modified status in - the tree you will need: - • |nvim_tree.Config.Renderer.Icons.Show| {modified} OR - • |nvim_tree.Config.Renderer| {highlight_modified} +hi_test() *nvim_tree.api.health.hi_test()* + Open a new buffer displaying all nvim-tree highlight groups, their link + chain and concrete definition. - See |nvim-tree-icons-highlighting|. + Similar to `:so $VIMRUNTIME/syntax/hitest.vim` as per |:highlight| - 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. Requires - {show_on_dirs}. +============================================================================== +Lua module: nvim_tree.api.map *nvim-tree-api-map* + +default_on_attach({bufnr}) *nvim_tree.api.map.default_on_attach()* + Apply all |nvim-tree-mappings-default|. Call from your |nvim_tree.Config| + {on_attach}. + + Parameters: ~ + • {bufnr} (`integer`) use the `bufnr` passed to {on_attach} + +get_keymap() *nvim_tree.api.map.get_keymap()* + Retrieve all buffer local mappings for nvim-tree. These are the mappings + that are applied by |nvim_tree.Config| {on_attach}, which may include + default mappings. + + Return: ~ + (`vim.api.keyset.get_keymap[]`) + +get_keymap_default() *nvim_tree.api.map.get_keymap_default()* + Retrieves the buffer local mappings for nvim-tree that are applied by + |nvim_tree.api.map.default_on_attach()| + + Return: ~ + (`vim.api.keyset.get_keymap[]`) ============================================================================== -Class: Config.Filters *nvim-tree-config-filters* +Lua module: nvim_tree.api.marks *nvim-tree-api-marks* -*nvim_tree.Config.Filters* - Filters may be applied to the tree to exlude the display of - file/directories. +bulk.delete() *nvim_tree.api.marks.bulk.delete()* + Delete all marked, prompting if |nvim_tree.Config.UI.Confirm| {remove} - Multiple filters may be applied at once. +bulk.move() *nvim_tree.api.marks.bulk.move()* + Prompts for a directory to move all marked nodes into. - Filters can be set at startup or toggled live via API with default - mappings. +bulk.trash() *nvim_tree.api.marks.bulk.trash()* + Delete all marked, prompting if |nvim_tree.Config.UI.Confirm| {trash} - `I `{git_ignored}` `|nvim-tree-api.tree.toggle_gitignore_filter()| - Ignore files based on `.gitignore`. Requires |nvim_tree.Config.Git| +clear() *nvim_tree.api.marks.clear()* + Clear all marks. - `H `{dotfiles}` `|nvim-tree-api.tree.toggle_hidden_filter()| - Filter dotfiles: files/directories starting with a `.` +get() *nvim_tree.api.marks.get()* + Return the node if it is marked. - `C `{git_clean}` `|nvim-tree-api.tree.toggle_git_clean_filter()| - Filter files with no git status. `.gitignore` files will not be filtered - when {git_ignored}, as they are effectively dirty. + Return: ~ + (`nvim_tree.api.Node?`) - `B `{no_buffer}` `|nvim-tree-api.tree.toggle_no_buffer_filter()| - Filter files that have no |buflisted()| buffer. For performance reasons - buffer delete/wipe may not be immediately shown. A reload or filesystem - event will always result in an update. +list() *nvim_tree.api.marks.list()* + Retrieve all marked nodes. - `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. + Return: ~ + (`nvim_tree.api.Node[]`) - `U `{custom}` `|nvim-tree-api.tree.toggle_custom_filter()| - Disable specific file/directory names via: - • a list of backslash escaped |vim.regex| strings e.g. `"^\\.git""` - • a function passed the absolute path of the directory. +navigate.next() *nvim_tree.api.marks.navigate.next()* + Navigate to the next marked node, wraps. - All filters including live filter may be disabled via {enable} and toggled - with |nvim-tree-api.tree.toggle_enable_filters()| +navigate.prev() *nvim_tree.api.marks.navigate.prev()* + Navigate to the previous marked node, wraps. - Files/directories may be {exclude}d from filtering: they will always be - shown, overriding {git_ignored}, {dotfiles} and {custom}. +navigate.select() *nvim_tree.api.marks.navigate.select()* + Prompts for selection of a marked node, sorted by absolute paths. A folder + will be focused, a file will be opened. - 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: `{}`) +toggle({node}) *nvim_tree.api.marks.toggle()* + Toggle mark. + Parameters: ~ + • {node} (`nvim_tree.api.Node`) file or directory ============================================================================== -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| +Lua module: nvim_tree.api.node *nvim-tree-api-node* - This feature is bound to the `f` key by default. The filter can be cleared - with the `F` key by default. +*ApiNodeDeleteWipeBufferOpts* 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. + • {force} (`boolean?`) default false +*NodeEditOpts* + Fields: ~ + • {quit_on_open} (`boolean?`) default false + • {focus} (`boolean?`) default true -============================================================================== -Class: Config.FilesystemWatchers *nvim-tree-config-filesystem-watchers* -*nvim_tree.Config.FilesystemWatchers* - Use file system watchers (libuv `uv_fs_event_t`) to monitor the filesystem - for changes and update the tree. +nvim_tree.api.node.buffer.delete() *nvim_tree.api.node.buffer.delete()* - With this feature, the tree will be partially updated on specific - directory changes, resulting in better performance. +nvim_tree.api.node.buffer.wipe() *nvim_tree.api.node.buffer.wipe()* - Watchers may be disabled for absolute directory paths via {ignore_dirs}. - • A list of |vim.regex| to match a path, backslash escaped e.g. - `"my-proj/\\.build$"` OR - • A function that is passed an absolute path and returns `true` to disable - This may be useful when a path is not in `.gitignore` or git integration - is disabled. +nvim_tree.api.node.collapse() *nvim_tree.api.node.collapse()* + +nvim_tree.api.node.expand() *nvim_tree.api.node.expand()* - 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. + *nvim_tree.api.node.navigate.diagnostics.next()* +nvim_tree.api.node.navigate.diagnostics.next() + *nvim_tree.api.node.navigate.diagnostics.next_recursive()* +nvim_tree.api.node.navigate.diagnostics.next_recursive() + *nvim_tree.api.node.navigate.diagnostics.prev()* +nvim_tree.api.node.navigate.diagnostics.prev() -============================================================================== -Class: Config.Actions *nvim-tree-config-actions* + *nvim_tree.api.node.navigate.diagnostics.prev_recursive()* +nvim_tree.api.node.navigate.diagnostics.prev_recursive() -*nvim_tree.Config.Actions* + *nvim_tree.api.node.navigate.git.next()* +nvim_tree.api.node.navigate.git.next() - 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.api.node.navigate.git.next_recursive()* +nvim_tree.api.node.navigate.git.next_recursive() -*nvim_tree.Config.Actions.ChangeDir* - vim |current-directory| behaviour + *nvim_tree.api.node.navigate.git.next_skip_gitignored()* +nvim_tree.api.node.navigate.git.next_skip_gitignored() - 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.api.node.navigate.git.prev()* +nvim_tree.api.node.navigate.git.prev() -*nvim_tree.Config.Actions.ExpandAll* - Configure |nvim-tree-api.tree.expand_all()| and - |nvim-tree-api.node.expand()| + *nvim_tree.api.node.navigate.git.prev_recursive()* +nvim_tree.api.node.navigate.git.prev_recursive() - Fields: ~ - • {max_folder_discovery}? (`integer`, default: `300`) Limit the number - of folders being explored when expanding - every folder. Avoids hanging Nvim when - running this action on very large folders. - • {exclude}? (`string[]`, default: `{}`) A list of - directories that should not be expanded - automatically e.g - `{ ".git", "target", "build" }` + *nvim_tree.api.node.navigate.git.prev_skip_gitignored()* +nvim_tree.api.node.navigate.git.prev_skip_gitignored() -*nvim_tree.Config.Actions.FilePopup* - {file_popup} floating window. + *nvim_tree.api.node.navigate.opened.next()* +nvim_tree.api.node.navigate.opened.next() - {open_win_config} is passed to |nvim_open_win()|, default: >lua - { - col = 1, - row = 1, - relative = "cursor", - border = "shadow", - style = "minimal", - } -< + *nvim_tree.api.node.navigate.opened.prev()* +nvim_tree.api.node.navigate.opened.prev() - You shouldn't define {width} and {height} values here. They will be - overridden to fit the file_popup content. + *nvim_tree.api.node.navigate.parent()* +nvim_tree.api.node.navigate.parent() - Fields: ~ - • {open_win_config}? (`vim.api.keyset.win_config`) (default: - `{ col = 1, row = 1, relative = "cursor", border = "shadow", style = "minimal", }`) + *nvim_tree.api.node.navigate.parent_close()* +nvim_tree.api.node.navigate.parent_close() -*nvim_tree.Config.Actions.OpenFile* - Opening files. + *nvim_tree.api.node.navigate.sibling.first()* +nvim_tree.api.node.navigate.sibling.first() - 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.api.node.navigate.sibling.last()* +nvim_tree.api.node.navigate.sibling.last() -*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. + *nvim_tree.api.node.navigate.sibling.next()* +nvim_tree.api.node.navigate.sibling.next() - When it is not enabled the file will open in the window from which you - last opened the tree, obeying {exclude} + *nvim_tree.api.node.navigate.sibling.prev()* +nvim_tree.api.node.navigate.sibling.prev() - You may define a {picker} function that should return the window id that - will open the node, or `nil` if an invalid window is picked or user - cancelled the action. The picker may create a new window. +nvim_tree.api.node.open.drop() *nvim_tree.api.node.open.drop()* - Fields: ~ - • {enable}? (`boolean`) (default: `true`) - • {picker}? (`"default"|(fun(): integer)`, default: `"default"`) - Change the default window picker or define your own. - • {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.api.node.open.edit() *nvim_tree.api.node.open.edit()* -*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 + *nvim_tree.api.node.open.horizontal()* +nvim_tree.api.node.open.horizontal() - Fields: ~ - • {filetype}? (`string[]`) (default: - `{ "notify", "lazy", "qf", "diff", "fugitive", "fugitiveblame", }`) - • {buftype}? (`string[]`) (default: - `{ "nofile", "terminal", "help", }`) + *nvim_tree.api.node.open.horizontal_no_picker()* +nvim_tree.api.node.open.horizontal_no_picker() -*nvim_tree.Config.Actions.RemoveFile* - Removing files. + *nvim_tree.api.node.open.no_window_picker()* +nvim_tree.api.node.open.no_window_picker() - Fields: ~ - • {close_window}? (`boolean`, default: `true`) Close any window that - displays a file when removing that file from the - tree. +nvim_tree.api.node.open.preview() *nvim_tree.api.node.open.preview()* + *nvim_tree.api.node.open.preview_no_picker()* +nvim_tree.api.node.open.preview_no_picker() + *nvim_tree.api.node.open.replace_tree_buffer()* +nvim_tree.api.node.open.replace_tree_buffer() -============================================================================== -Class: Config.Trash *nvim-tree-config-trash* +nvim_tree.api.node.open.tab() *nvim_tree.api.node.open.tab()* -*nvim_tree.Config.Trash* - Files may be trashed via an external command that must be installed on - your system. - • linux: `gio trash`, from linux package `glib2` - • macOS: `trash`, from homebrew package `trash` - • windows: `trash`, requires `trash-cli` or similar +nvim_tree.api.node.open.tab_drop() *nvim_tree.api.node.open.tab_drop()* - Fields: ~ - • {cmd}? (`string`) (default: `"gio trash"` or `"trash"`) + *nvim_tree.api.node.open.toggle_group_empty()* +nvim_tree.api.node.open.toggle_group_empty() + +nvim_tree.api.node.open.vertical() *nvim_tree.api.node.open.vertical()* + + *nvim_tree.api.node.open.vertical_no_picker()* +nvim_tree.api.node.open.vertical_no_picker() +nvim_tree.api.node.run.cmd() *nvim_tree.api.node.run.cmd()* + +nvim_tree.api.node.run.system() *nvim_tree.api.node.run.system()* + + *nvim_tree.api.node.show_info_popup()* +nvim_tree.api.node.show_info_popup() ============================================================================== -Class: Config.Tab *nvim-tree-config-tab* +Lua module: nvim_tree.api.tree *nvim-tree-api-tree* -*nvim_tree.Config.Tab* +change_root({path}) *nvim_tree.api.tree.change_root()* + Change the tree's root to a path. - Fields: ~ - • {sync}? (`nvim_tree.Config.Tab.Sync`) |nvim_tree.Config.Tab.Sync| + Parameters: ~ + • {path} (`string?`) absolute or relative path. -*nvim_tree.Config.Tab.Sync* +change_root_to_node({node}) *nvim_tree.api.tree.change_root_to_node()* + Change the tree's root to a folder node or the parent of a file node. - 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` + Parameters: ~ + • {node} (`nvim_tree.api.Node`) directory or file + *nvim_tree.api.tree.change_root_to_parent()* +change_root_to_parent({node}) + Change the tree's root to the parent of a node. + Parameters: ~ + • {node} (`nvim_tree.api.Node`) directory or file -============================================================================== -Class: Config.Notify *nvim-tree-config-notify* +close() *nvim_tree.api.tree.close()* + Close the tree, affecting all tabs as per |nvim_tree.Config.Tab.Sync| + {close} -*nvim_tree.Config.Notify* - nvim-tree |vim.log.levels| - • `ERROR`: hard errors e.g. failure to read from the file system. - • `WARN`: non-fatal errors e.g. unable to system open a file. - • `INFO`: information only e.g. file copy path confirmation. - • `DEBUG`: information for troubleshooting, e.g. failures in some window - closing operations. +close_in_all_tabs() *nvim_tree.api.tree.close_in_all_tabs()* + Close the tree in all tabs. - Fields: ~ - • {threshold}? (`vim.log.levels`, default: `vim.log.levels.INFO`) - Specify minimum notification |vim.log.levels| - • {absolute_path}? (`boolean`, default: `true`) Use absolute paths in - FS action notifications, otherwise item names. +close_in_this_tab() *nvim_tree.api.tree.close_in_this_tab()* + Close the tree in this tab only. +collapse_all({opts}) *nvim_tree.api.tree.collapse_all()* + Collapse the tree. + Parameters: ~ + • {opts} (`table?`) optional + • {keep_buffers}? (`boolean`, default: false) Do not collapse + nodes with open buffers. -============================================================================== -Class: Config.Bookmarks *nvim-tree-config-bookmarks* +expand_all({node}, {opts}) *nvim_tree.api.tree.expand_all()* + Recursively expand all nodes under the tree root or specified folder. -*nvim_tree.Config.Bookmarks* - Optionally {persist} bookmarks to a json file: - • `true` use default: `stdpath("data") .. "/nvim-tree-bookmarks.json"` - • `false` do not persist - • `string` absolute path of your choice + Parameters: ~ + • {node} (`nvim_tree.api.Node?`) directory + • {opts} (`table?`) optional + • {expand_until}? + (`fun(expansion_count: integer, node: Node): boolean`) + Return `true` if `node` should be expanded. + `expansion_count` is the total number of folders expanded. + +find_file({opts}) *nvim_tree.api.tree.find_file()* + Find and focus a file or folder in the tree. Finds current buffer unless + otherwise specified. - Fields: ~ - • {persist}? (`boolean|string`) (default: `false`) + Parameters: ~ + • {opts} (`table?`) optional + • {buf}? (`string|integer`) Absolute/relative path OR `bufnr` + to find. + • {open}? (`boolean`, default: false) Open the tree if + necessary. + • {current_window}? (`boolean`, default: false) Requires + {open}: open in the current window. + • {winid}? (`integer`) Open the tree in the specified + |window-ID|, overrides {current_window} + • {update_root}? (`boolean`, default: false) Update root after + find, see |nvim_tree.Config.UpdateFocusedFile| {update_root} + • {focus}? (`boolean`, default: false) Focus the tree window. + +focus() *nvim_tree.api.tree.focus()* + Focus the tree, opening it if necessary. Retained for compatibility, use + |nvim_tree.api.tree.open()| with no arguments instead. + +get_node_under_cursor() *nvim_tree.api.tree.get_node_under_cursor()* + Retrieve the currently focused node. + Return: ~ + (`nvim_tree.api.Node?`) nil if tree is not visible. +get_nodes() *nvim_tree.api.tree.get_nodes()* + Retrieve a hierarchical list of all the nodes. -============================================================================== -Class: Config.Help *nvim-tree-config-help* + Return: ~ + (`nvim_tree.api.Node[]`) -*nvim_tree.Config.Help* - Configure help window, default mapping `g?` +is_tree_buf({bufnr}) *nvim_tree.api.tree.is_tree_buf()* + Checks if a buffer is an nvim-tree. - *nvim_tree.Config.Help.SortBy* - • `"key"`: alphabetically by keymap - • `"desc"`: alphabetically by description + Parameters: ~ + • {bufnr} (`integer?`) 0 or nil for current buffer. - Fields: ~ - • {sort_by}? (`nvim_tree.Config.Help.SortBy`, default: `"key"`) - |nvim_tree.Config.Help.SortBy| + Return: ~ + (`boolean`) +is_visible({opts}) *nvim_tree.api.tree.is_visible()* + Checks if nvim-tree is visible on the current, specified or any tab. + Parameters: ~ + • {opts} (`table?`) optional + • {tabpage}? (`integer`) |tab-ID| 0 or nil for current. + • {any_tabpage}? (`boolean`, default: false) Visible on any + tab. -============================================================================== -Class: Config.UI *nvim-tree-config-ui* + Return: ~ + (`boolean`) -*nvim_tree.Config.UI* +open({opts}) *nvim_tree.api.tree.open()* + Open the tree, focusing it if already open. - Fields: ~ - • {confirm}? (`nvim_tree.Config.UI.Confirm`) - |nvim_tree.Config.UI.Confirm| + Parameters: ~ + • {opts} (`table?`) optional + • {path}? (`string`) Root directory for the tree + • {current_window}? (`boolean`, default: false) Open the tree + in the current window + • {winid}? (`integer`) Open the tree in the specified + |window-ID|, overrides {current_window} + • {find_file}? (`boolean`, default: false) Find the current + buffer. + • {update_root}? (`boolean`, default: false) Update root + following {find_file}, see + |nvim_tree.Config.UpdateFocusedFile| {update_root} + +reload() *nvim_tree.api.tree.reload()* + Refresh the tree. Does nothing if closed. -*nvim_tree.Config.UI.Confirm* - Confirmation prompts. +reload_git() *nvim_tree.api.tree.reload_git()* + Update the git status of the entire tree. - 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` +resize({opts}) *nvim_tree.api.tree.resize()* + Resize the tree, persisting the new size. Resets to + |nvim_tree.Config.View| {width} when no {opts} provided. + Only one option is supported, priority order: {width}, {absolute}, + {relative}. + {absolute} and {relative} do nothing when |nvim_tree.Config.View| {width} + is a function. -============================================================================== -Class: Config.Experimental *nvim-tree-config-experimental* + Parameters: ~ + • {opts} (`table?`) optional + • {width} + (`nvim_tree.Config.View.WidthSpec|nvim_tree.Config.View.Width`) + New |nvim_tree.Config.View| {width} value. + • {absolute} (`integer`) Set the width. + • {relative} (`integer`) Increase or decrease the width. -*nvim_tree.Config.Experimental* - Experimental features that may become default or optional functionality. +search_node() *nvim_tree.api.tree.search_node()* + Open the search dialogue. - In the event of a problem please disable the experiment and raise an - issue. +toggle({opts}) *nvim_tree.api.tree.toggle()* + Open or close the tree. + Parameters: ~ + • {opts} (`table?`) optional + • {path}? (`string`) Root directory for the tree + • {current_window}? (`boolean`, default: false) Open the tree + in the current window + • {winid}? (`integer`) Open the tree in the specified + |window-ID|, overrides {current_window} + • {find_file}? (`boolean`, default: false) Find the current + buffer. + • {update_root}? (`boolean`, default: false) Update root + following {find_file}, see + |nvim_tree.Config.UpdateFocusedFile| {update_root} + • {focus}? (`boolean`, default: true) Focus the tree when + opening. + +toggle_custom_filter() *nvim_tree.api.tree.toggle_custom_filter()* + Toggle |nvim_tree.Config.Filters| {custom} filter. +toggle_enable_filters() *nvim_tree.api.tree.toggle_enable_filters()* + Toggle |nvim_tree.Config.Filters| {enable} all filters. -============================================================================== -Class: Config.Log *nvim-tree-config-log* + *nvim_tree.api.tree.toggle_git_clean_filter()* +toggle_git_clean_filter() + Toggle |nvim_tree.Config.Filters| {git_clean} filter. -*nvim_tree.Config.Log* - Log to a file `nvim-tree.log` in |stdpath()| `log`, usually - `${XDG_STATE_HOME}/nvim` + *nvim_tree.api.tree.toggle_gitignore_filter()* +toggle_gitignore_filter() + Toggle |nvim_tree.Config.Filters| {git_ignored} filter. - 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| +toggle_help() *nvim_tree.api.tree.toggle_help()* + Toggle help view. -*nvim_tree.Config.Log.Types* - Specify which information to log. +toggle_hidden_filter() *nvim_tree.api.tree.toggle_hidden_filter()* + Toggle |nvim_tree.Config.Filters| {dotfiles} filter. - 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.api.tree.toggle_no_bookmark_filter()* +toggle_no_bookmark_filter() + Toggle |nvim_tree.Config.Filters| {no_bookmark} filter. + + *nvim_tree.api.tree.toggle_no_buffer_filter()* +toggle_no_buffer_filter() + Toggle |nvim_tree.Config.Filters| {no_buffer} filter. +winid({opts}) *nvim_tree.api.tree.winid()* + Retrieve the window of the open tree. + + Parameters: ~ + • {opts} (`table?`) optional + • {tabpage}? (`integer`) |tab-ID| 0 or nil for current. + + Return: ~ + (`integer?`) |window-ID|, nil if tree is not visible. vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: diff --git a/lua/nvim-tree/_meta/api.lua b/lua/nvim-tree/_meta/api.lua deleted file mode 100644 index d6847940781..00000000000 --- a/lua/nvim-tree/_meta/api.lua +++ /dev/null @@ -1,51 +0,0 @@ ----@meta -error("Cannot require a meta file") - --- --- Nodes --- - ----Base Node, Abstract ----@class (exact) nvim_tree.api.Node ----@field type "file" | "directory" | "link" uv.fs_stat.result.type ----@field absolute_path string ----@field executable boolean ----@field fs_stat uv.fs_stat.result? ----@field git_status GitNodeStatus? ----@field hidden boolean ----@field name string ----@field parent nvim_tree.api.DirectoryNode? ----@field diag_severity lsp.DiagnosticSeverity? - ----File ----@class (exact) nvim_tree.api.FileNode: nvim_tree.api.Node ----@field extension string - ----Directory ----@class (exact) nvim_tree.api.DirectoryNode: nvim_tree.api.Node ----@field has_children boolean ----@field nodes nvim_tree.api.Node[] ----@field open boolean - ----Root Directory ----@class (exact) nvim_tree.api.RootNode: nvim_tree.api.DirectoryNode - ----Link mixin ----@class (exact) nvim_tree.api.LinkNode ----@field link_to string ----@field fs_stat_target uv.fs_stat.result - ----File Link ----@class (exact) nvim_tree.api.FileLinkNode: nvim_tree.api.FileNode, nvim_tree.api.LinkNode - ----DirectoryLink ----@class (exact) nvim_tree.api.DirectoryLinkNode: nvim_tree.api.DirectoryNode, nvim_tree.api.LinkNode - --- --- Various Types --- - ----A string for rendering, with optional highlight groups to apply to it ----@class (exact) nvim_tree.api.HighlightedString ----@field str string ----@field hl string[] diff --git a/lua/nvim-tree/_meta/api_decorator.lua b/lua/nvim-tree/_meta/api_decorator.lua index d85fe02fff0..4acca3a9acf 100644 --- a/lua/nvim-tree/_meta/api_decorator.lua +++ b/lua/nvim-tree/_meta/api_decorator.lua @@ -12,6 +12,11 @@ local nvim_tree = { api = { decorator = {} } } ---Names of builtin decorators or your decorator classes. Builtins are ordered lowest to highest priority. ---@alias nvim_tree.api.decorator.Name "Git" | "Opened" | "Hidden" | "Modified" | "Bookmarks" | "Diagnostics" | "Copied" | "Cut" | nvim_tree.api.decorator.UserDecorator +---A string for rendering, with optional highlight groups to apply to it +---@class (exact) nvim_tree.api.HighlightedString +---@field str string +---@field hl string[] + ---Custom decorator, see :help nvim-tree-decorators --- ---@class (exact) nvim_tree.api.decorator.UserDecorator diff --git a/lua/nvim-tree/_meta/config/actions.lua b/lua/nvim-tree/_meta/config/actions.lua index e65fe4d79c4..d741752c365 100644 --- a/lua/nvim-tree/_meta/config/actions.lua +++ b/lua/nvim-tree/_meta/config/actions.lua @@ -43,7 +43,7 @@ error("Cannot require a meta file") ----Configure [nvim-tree-api.tree.expand_all()] and [nvim-tree-api.node.expand()] +---Configure [nvim_tree.api.tree.expand_all()] and [nvim_tree.api.node.expand()] ---@class nvim_tree.Config.Actions.ExpandAll --- ---Limit the number of folders being explored when expanding every folder. Avoids hanging Nvim when running this action on very large folders. diff --git a/lua/nvim-tree/_meta/config/filters.lua b/lua/nvim-tree/_meta/config/filters.lua index 93de5d64733..35e17d40469 100644 --- a/lua/nvim-tree/_meta/config/filters.lua +++ b/lua/nvim-tree/_meta/config/filters.lua @@ -9,27 +9,27 @@ error("Cannot require a meta file") --- ---Filters can be set at startup or toggled live via API with default mappings. --- ----`I `{git_ignored}` `|nvim-tree-api.tree.toggle_gitignore_filter()| +---`I `{git_ignored}` `|nvim_tree.api.tree.toggle_gitignore_filter()| ---Ignore files based on `.gitignore`. Requires |nvim_tree.Config.Git| --- ----`H `{dotfiles}` `|nvim-tree-api.tree.toggle_hidden_filter()| +---`H `{dotfiles}` `|nvim_tree.api.tree.toggle_hidden_filter()| ---Filter dotfiles: files/directories starting with a `.` --- ----`C `{git_clean}` `|nvim-tree-api.tree.toggle_git_clean_filter()| +---`C `{git_clean}` `|nvim_tree.api.tree.toggle_git_clean_filter()| ---Filter files with no git status. `.gitignore` files will not be filtered when {git_ignored}, as they are effectively dirty. --- ----`B `{no_buffer}` `|nvim-tree-api.tree.toggle_no_buffer_filter()| +---`B `{no_buffer}` `|nvim_tree.api.tree.toggle_no_buffer_filter()| ---Filter files that have no |buflisted()| buffer. For performance reasons buffer delete/wipe may not be immediately shown. A reload or filesystem event will always result in an update. --- ----`M `{no_bookmark}` `|nvim-tree-api.tree.toggle_no_bookmark_filter()| +---`M `{no_bookmark}` `|nvim_tree.api.tree.toggle_no_bookmark_filter()| ---Filter files that are not bookmarked. Enabling this is not useful as there is no means yet to persist bookmarks. --- ----`U `{custom}` `|nvim-tree-api.tree.toggle_custom_filter()| +---`U `{custom}` `|nvim_tree.api.tree.toggle_custom_filter()| ---Disable specific file/directory names via: ---- a list of backslash escaped |vim.regex| strings e.g. `"^\\.git""` ---- a function passed the absolute path of the directory. --- ----All filters including live filter may be disabled via {enable} and toggled with |nvim-tree-api.tree.toggle_enable_filters()| +---All filters including live filter may be disabled via {enable} and toggled with |nvim_tree.api.tree.toggle_enable_filters()| --- ---Files/directories may be {exclude}d from filtering: they will always be shown, overriding {git_ignored}, {dotfiles} and {custom}. ---@class nvim_tree.Config.Filters diff --git a/lua/nvim-tree/actions/tree/find-file.lua b/lua/nvim-tree/actions/tree/find-file.lua index 8a05bf6db45..231a56a2bb2 100644 --- a/lua/nvim-tree/actions/tree/find-file.lua +++ b/lua/nvim-tree/actions/tree/find-file.lua @@ -6,7 +6,7 @@ local finders_find_file = require("nvim-tree.actions.finders.find-file") local M = {} --- Find file or buffer ----@param opts ApiTreeFindFileOpts|nil|boolean legacy -> opts.buf +---@param opts nvim_tree.api.tree.find_file.Opts|nil|boolean legacy -> opts.buf function M.fn(opts) -- legacy arguments if type(opts) == "string" then diff --git a/lua/nvim-tree/actions/tree/modifiers/collapse.lua b/lua/nvim-tree/actions/tree/modifiers/collapse.lua index 51a15f3d464..614a62fb8b7 100644 --- a/lua/nvim-tree/actions/tree/modifiers/collapse.lua +++ b/lua/nvim-tree/actions/tree/modifiers/collapse.lua @@ -26,7 +26,7 @@ end ---Collapse a node, root if nil ---@param node Node? ----@param opts ApiCollapseOpts +---@param opts nvim_tree.api.tree.collapse.Opts local function collapse(node, opts) local explorer = core.get_explorer() if not explorer then @@ -60,7 +60,7 @@ local function collapse(node, opts) end ----@param opts ApiCollapseOpts|boolean|nil legacy -> opts.keep_buffers +---@param opts nvim_tree.api.tree.collapse.Opts|boolean|nil legacy -> opts.keep_buffers function M.all(opts) -- legacy arguments if type(opts) == "boolean" then @@ -73,7 +73,7 @@ function M.all(opts) end ---@param node Node ----@param opts ApiCollapseOpts? +---@param opts nvim_tree.api.tree.collapse.Opts? function M.node(node, opts) collapse(node, opts or {}) end diff --git a/lua/nvim-tree/actions/tree/modifiers/expand.lua b/lua/nvim-tree/actions/tree/modifiers/expand.lua index 44e3fa67baa..0fe725fd1dc 100644 --- a/lua/nvim-tree/actions/tree/modifiers/expand.lua +++ b/lua/nvim-tree/actions/tree/modifiers/expand.lua @@ -125,7 +125,7 @@ local function gen_iterator(should_descend) end ---@param node Node? ----@param expand_opts ApiTreeExpandOpts? +---@param expand_opts nvim_tree.api.tree.expand.Opts? local function expand_node(node, expand_opts) if not node then return @@ -141,14 +141,14 @@ end ---Expand the directory node or the root ---@param node Node ----@param expand_opts ApiTreeExpandOpts? +---@param expand_opts nvim_tree.api.tree.expand.Opts? function M.all(node, expand_opts) expand_node(node and node:as(DirectoryNode) or core.get_explorer(), expand_opts) end ---Expand the directory node or parent node ---@param node Node ----@param expand_opts ApiTreeExpandOpts? +---@param expand_opts nvim_tree.api.tree.expand.Opts? function M.node(node, expand_opts) if not node then return diff --git a/lua/nvim-tree/actions/tree/open.lua b/lua/nvim-tree/actions/tree/open.lua index ff2da837b87..48f7d93c7f0 100644 --- a/lua/nvim-tree/actions/tree/open.lua +++ b/lua/nvim-tree/actions/tree/open.lua @@ -5,7 +5,7 @@ local finders_find_file = require("nvim-tree.actions.finders.find-file") local M = {} ---Open the tree, focusing if already open. ----@param opts ApiTreeOpenOpts|nil|string legacy -> opts.path +---@param opts nvim_tree.api.tree.open.Opts|nil|string legacy -> opts.path function M.fn(opts) -- legacy arguments if type(opts) == "string" then diff --git a/lua/nvim-tree/actions/tree/resize.lua b/lua/nvim-tree/actions/tree/resize.lua index e8d4e950729..77bb379ea61 100644 --- a/lua/nvim-tree/actions/tree/resize.lua +++ b/lua/nvim-tree/actions/tree/resize.lua @@ -3,7 +3,7 @@ local view = require("nvim-tree.view") local M = {} ---Resize the tree, persisting the new size. ----@param opts ApiTreeResizeOpts|nil +---@param opts nvim_tree.api.tree.resize.Opts|nil function M.fn(opts) if opts == nil then -- reset to config values diff --git a/lua/nvim-tree/actions/tree/toggle.lua b/lua/nvim-tree/actions/tree/toggle.lua index 10aa978467e..6fefe089593 100644 --- a/lua/nvim-tree/actions/tree/toggle.lua +++ b/lua/nvim-tree/actions/tree/toggle.lua @@ -5,7 +5,7 @@ local finders_find_file = require("nvim-tree.actions.finders.find-file") local M = {} ---Toggle the tree. ----@param opts ApiTreeToggleOpts|nil|boolean legacy -> opts.find_file +---@param opts nvim_tree.api.tree.toggle.Opts|nil|boolean legacy -> opts.find_file ---@param no_focus string|nil legacy -> opts.focus ---@param cwd boolean|nil legacy -> opts.path ---@param bang boolean|nil legacy -> opts.update_root diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua index e5a109142f1..bdb0beab289 100644 --- a/lua/nvim-tree/api.lua +++ b/lua/nvim-tree/api.lua @@ -1,377 +1,117 @@ -local core = require("nvim-tree.core") -local view = require("nvim-tree.view") -local utils = require("nvim-tree.utils") -local actions = require("nvim-tree.actions") -local appearance_hi_test = require("nvim-tree.appearance.hi-test") -local events = require("nvim-tree.events") -local help = require("nvim-tree.help") -local keymap = require("nvim-tree.keymap") -local notify = require("nvim-tree.notify") +-- TODO #3088 rename this to nvim-tree/api.lua -local DirectoryNode = require("nvim-tree.node.directory") -local FileNode = require("nvim-tree.node.file") -local FileLinkNode = require("nvim-tree.node.file-link") -local RootNode = require("nvim-tree.node.root") -local UserDecorator = require("nvim-tree.renderer.decorator.user") - -local Api = { - tree = {}, - node = { - navigate = { - sibling = {}, - git = {}, - diagnostics = {}, - opened = {}, - }, - run = {}, - open = {}, - buffer = {}, - }, - events = {}, - marks = { - bulk = {}, - navigate = {}, - }, - fs = { - copy = {}, - }, - git = {}, - live_filter = {}, - config = { - mappings = {}, - }, - commands = {}, - diagnostics = {}, - decorator = {}, -} - ----Print error when setup not called. ----@param fn fun(...): any ----@return fun(...): any -local function wrap(fn) - return function(...) - if vim.g.NvimTreeSetup == 1 then - return fn(...) - else - notify.error("nvim-tree setup not called") - end - end -end - ----Invoke a method on the singleton explorer. ----Print error when setup not called. ----@param explorer_method string explorer method name ----@return fun(...): any -local function wrap_explorer(explorer_method) - return wrap(function(...) - local explorer = core.get_explorer() - if explorer then - return explorer[explorer_method](explorer, ...) - end - end) -end - ----Inject the node as the first argument if present otherwise do nothing. ----@param fn fun(node: Node, ...): any ----@return fun(node: Node?, ...): any -local function wrap_node(fn) - return function(node, ...) - node = node or wrap_explorer("get_node_at_cursor")() - if node then - return fn(node, ...) - end - end -end - ----Inject the node or nil as the first argument if absent. ----@param fn fun(node: Node?, ...): any ----@return fun(node: Node?, ...): any -local function wrap_node_or_nil(fn) - return function(node, ...) - node = node or wrap_explorer("get_node_at_cursor")() - return fn(node, ...) - end -end - ----Invoke a member's method on the singleton explorer. ----Print error when setup not called. ----@param explorer_member string explorer member name ----@param member_method string method name to invoke on member ----@param ... any passed to method ----@return fun(...): any -local function wrap_explorer_member_args(explorer_member, member_method, ...) - local method_args = ... - return wrap(function(...) - local explorer = core.get_explorer() - if explorer then - return explorer[explorer_member][member_method](explorer[explorer_member], method_args, ...) - end - end) -end - ----Invoke a member's method on the singleton explorer. ----Print error when setup not called. ----@param explorer_member string explorer member name ----@param member_method string method name to invoke on member ----@return fun(...): any -local function wrap_explorer_member(explorer_member, member_method) - return wrap(function(...) - local explorer = core.get_explorer() - if explorer then - return explorer[explorer_member][member_method](explorer[explorer_member], ...) - end - end) -end - ----@class ApiTreeOpenOpts ----@field path string|nil path ----@field current_window boolean|nil default false ----@field winid number|nil ----@field find_file boolean|nil default false ----@field update_root boolean|nil default false - -Api.tree.open = wrap(actions.tree.open.fn) -Api.tree.focus = Api.tree.open - ----@class ApiTreeToggleOpts ----@field path string|nil ----@field current_window boolean|nil default false ----@field winid number|nil ----@field find_file boolean|nil default false ----@field update_root boolean|nil default false ----@field focus boolean|nil default true - -Api.tree.toggle = wrap(actions.tree.toggle.fn) -Api.tree.close = wrap(view.close) -Api.tree.close_in_this_tab = wrap(view.close_this_tab_only) -Api.tree.close_in_all_tabs = wrap(view.close_all_tabs) -Api.tree.reload = wrap_explorer("reload_explorer") - ----@class ApiTreeResizeOpts ----@field width string|function|number|table|nil ----@field absolute number|nil ----@field relative number|nil - -Api.tree.resize = wrap(actions.tree.resize.fn) - -Api.tree.change_root = wrap(function(...) - require("nvim-tree").change_dir(...) -end) - -Api.tree.change_root_to_node = wrap_node(function(node) - if node.name == ".." or node:is(RootNode) then - actions.root.change_dir.fn("..") - return - end - - if node:is(FileNode) and node.parent ~= nil then - actions.root.change_dir.fn(node.parent:last_group_node().absolute_path) - return - end - - if node:is(DirectoryNode) then - actions.root.change_dir.fn(node:last_group_node().absolute_path) - return - end -end) - -Api.tree.change_root_to_parent = wrap_node(wrap_explorer("dir_up")) -Api.tree.get_node_under_cursor = wrap_explorer("get_node_at_cursor") -Api.tree.get_nodes = wrap_explorer("get_nodes") - ----@class ApiTreeFindFileOpts ----@field buf string|number|nil ----@field open boolean|nil default false ----@field current_window boolean|nil default false ----@field winid number|nil ----@field update_root boolean|nil default false ----@field focus boolean|nil default false - -Api.tree.find_file = wrap(actions.tree.find_file.fn) -Api.tree.search_node = wrap(actions.finders.search_node.fn) - ----@class ApiCollapseOpts ----@field keep_buffers boolean|nil default false - -Api.tree.collapse_all = wrap(actions.tree.modifiers.collapse.all) - ----@class ApiTreeExpandOpts ----@field expand_until (fun(expansion_count: integer, node: Node): boolean)|nil - -Api.tree.expand_all = wrap_node(actions.tree.modifiers.expand.all) -Api.tree.toggle_enable_filters = wrap_explorer_member("filters", "toggle") -Api.tree.toggle_gitignore_filter = wrap_explorer_member_args("filters", "toggle", "git_ignored") -Api.tree.toggle_git_clean_filter = wrap_explorer_member_args("filters", "toggle", "git_clean") -Api.tree.toggle_no_buffer_filter = wrap_explorer_member_args("filters", "toggle", "no_buffer") -Api.tree.toggle_custom_filter = wrap_explorer_member_args("filters", "toggle", "custom") -Api.tree.toggle_hidden_filter = wrap_explorer_member_args("filters", "toggle", "dotfiles") -Api.tree.toggle_no_bookmark_filter = wrap_explorer_member_args("filters", "toggle", "no_bookmark") -Api.tree.toggle_help = wrap(help.toggle) -Api.tree.is_tree_buf = wrap(utils.is_nvim_tree_buf) - ----@class ApiTreeIsVisibleOpts ----@field tabpage number|nil ----@field any_tabpage boolean|nil default false - -Api.tree.is_visible = wrap(view.is_visible) - ----@class ApiTreeWinIdOpts ----@field tabpage number|nil default nil - -Api.tree.winid = wrap(view.winid) - -Api.fs.create = wrap_node_or_nil(actions.fs.create_file.fn) -Api.fs.remove = wrap_node(actions.fs.remove_file.fn) -Api.fs.trash = wrap_node(actions.fs.trash.fn) -Api.fs.rename_node = wrap_node(actions.fs.rename_file.fn(":t")) -Api.fs.rename = wrap_node(actions.fs.rename_file.fn(":t")) -Api.fs.rename_sub = wrap_node(actions.fs.rename_file.fn(":p:h")) -Api.fs.rename_basename = wrap_node(actions.fs.rename_file.fn(":t:r")) -Api.fs.rename_full = wrap_node(actions.fs.rename_file.fn(":p")) -Api.fs.cut = wrap_node(wrap_explorer_member("clipboard", "cut")) -Api.fs.paste = wrap_node(wrap_explorer_member("clipboard", "paste")) -Api.fs.clear_clipboard = wrap_explorer_member("clipboard", "clear_clipboard") -Api.fs.print_clipboard = wrap_explorer_member("clipboard", "print_clipboard") -Api.fs.copy.node = wrap_node(wrap_explorer_member("clipboard", "copy")) -Api.fs.copy.absolute_path = wrap_node(wrap_explorer_member("clipboard", "copy_absolute_path")) -Api.fs.copy.filename = wrap_node(wrap_explorer_member("clipboard", "copy_filename")) -Api.fs.copy.basename = wrap_node(wrap_explorer_member("clipboard", "copy_basename")) -Api.fs.copy.relative_path = wrap_node(wrap_explorer_member("clipboard", "copy_path")) +---@brief +---nvim-tree exposes a public API. This is non breaking, with additions made as necessary. --- ----@class NodeEditOpts ----@field quit_on_open boolean|nil default false ----@field focus boolean|nil default true - ----@param mode string ----@param node Node ----@param edit_opts NodeEditOpts? -local function edit(mode, node, edit_opts) - local file_link = node:as(FileLinkNode) - local path = file_link and file_link.link_to or node.absolute_path - local cur_tabpage = vim.api.nvim_get_current_tabpage() - - actions.node.open_file.fn(mode, path) - - edit_opts = edit_opts or {} - - local mode_unsupported_quit_on_open = mode == "drop" or mode == "tab_drop" or mode == "edit_in_place" - if not mode_unsupported_quit_on_open and edit_opts.quit_on_open then - view.close(cur_tabpage) - end - - local mode_unsupported_focus = mode == "drop" or mode == "tab_drop" or mode == "edit_in_place" - local focus = edit_opts.focus == nil or edit_opts.focus == true - if not mode_unsupported_focus and not focus then - -- if mode == "tabnew" a new tab will be opened and we need to focus back to the previous tab - if mode == "tabnew" then - vim.cmd(":tabprev") - end - view.focus() - end -end - ----@param mode string ----@param toggle_group boolean? ----@return fun(node: Node, edit_opts: NodeEditOpts?) -local function open_or_expand_or_dir_up(mode, toggle_group) - ---@param node Node - ---@param edit_opts NodeEditOpts? - return function(node, edit_opts) - local root = node:as(RootNode) - local dir = node:as(DirectoryNode) - - if root or node.name == ".." then - actions.root.change_dir.fn("..") - elseif dir then - dir:expand_or_collapse(toggle_group) - elseif not toggle_group then - edit(mode, node, edit_opts) - end - end -end - -Api.node.open.edit = wrap_node(open_or_expand_or_dir_up("edit")) -Api.node.open.drop = wrap_node(open_or_expand_or_dir_up("drop")) -Api.node.open.tab_drop = wrap_node(open_or_expand_or_dir_up("tab_drop")) -Api.node.open.replace_tree_buffer = wrap_node(open_or_expand_or_dir_up("edit_in_place")) -Api.node.open.no_window_picker = wrap_node(open_or_expand_or_dir_up("edit_no_picker")) -Api.node.open.vertical = wrap_node(open_or_expand_or_dir_up("vsplit")) -Api.node.open.vertical_no_picker = wrap_node(open_or_expand_or_dir_up("vsplit_no_picker")) -Api.node.open.horizontal = wrap_node(open_or_expand_or_dir_up("split")) -Api.node.open.horizontal_no_picker = wrap_node(open_or_expand_or_dir_up("split_no_picker")) -Api.node.open.tab = wrap_node(open_or_expand_or_dir_up("tabnew")) -Api.node.open.toggle_group_empty = wrap_node(open_or_expand_or_dir_up("toggle_group_empty", true)) -Api.node.open.preview = wrap_node(open_or_expand_or_dir_up("preview")) -Api.node.open.preview_no_picker = wrap_node(open_or_expand_or_dir_up("preview_no_picker")) - -Api.node.show_info_popup = wrap_node(actions.node.file_popup.toggle_file_info) -Api.node.run.cmd = wrap_node(actions.node.run_command.run_file_command) -Api.node.run.system = wrap_node(actions.node.system_open.fn) - -Api.node.navigate.sibling.next = wrap_node(actions.moves.sibling.fn("next")) -Api.node.navigate.sibling.prev = wrap_node(actions.moves.sibling.fn("prev")) -Api.node.navigate.sibling.first = wrap_node(actions.moves.sibling.fn("first")) -Api.node.navigate.sibling.last = wrap_node(actions.moves.sibling.fn("last")) -Api.node.navigate.parent = wrap_node(actions.moves.parent.fn(false)) -Api.node.navigate.parent_close = wrap_node(actions.moves.parent.fn(true)) -Api.node.navigate.git.next = wrap_node(actions.moves.item.fn({ where = "next", what = "git" })) -Api.node.navigate.git.next_skip_gitignored = wrap_node(actions.moves.item.fn({ where = "next", what = "git", skip_gitignored = true })) -Api.node.navigate.git.next_recursive = wrap_node(actions.moves.item.fn({ where = "next", what = "git", recurse = true })) -Api.node.navigate.git.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "git" })) -Api.node.navigate.git.prev_skip_gitignored = wrap_node(actions.moves.item.fn({ where = "prev", what = "git", skip_gitignored = true })) -Api.node.navigate.git.prev_recursive = wrap_node(actions.moves.item.fn({ where = "prev", what = "git", recurse = true })) -Api.node.navigate.diagnostics.next = wrap_node(actions.moves.item.fn({ where = "next", what = "diag" })) -Api.node.navigate.diagnostics.next_recursive = wrap_node(actions.moves.item.fn({ where = "next", what = "diag", recurse = true })) -Api.node.navigate.diagnostics.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "diag" })) -Api.node.navigate.diagnostics.prev_recursive = wrap_node(actions.moves.item.fn({ where = "prev", what = "diag", recurse = true })) -Api.node.navigate.opened.next = wrap_node(actions.moves.item.fn({ where = "next", what = "opened" })) -Api.node.navigate.opened.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "opened" })) +---Please do not require or use modules other than `nvim-tree.api`, as internal modules are not stable and will change without notice. +--- +---The API is separated into multiple modules, which can be accessed via the parent `nvim-tree.api` or via `nvim-tree.api.`. The following examples are equivalent: +---```lua +--- +---local api = require("nvim-tree.api") +---api.tree.reload() +--- +---local tree = require("nvim-tree.api.tree") +---tree.reload() +---``` +--- +---Generally, functions accepting {node} as their first argument will use the node under the cursor when that argument is not present or nil. e.g. the following are functionally identical: +---```lua +--- +---api.node.open.edit(nil, { focus = true }) +--- +---api.node.open.edit(api.tree.get_node_under_cursor(), { focus = true }) +---``` -Api.node.expand = wrap_node(actions.tree.modifiers.expand.node) -Api.node.collapse = wrap_node(actions.tree.modifiers.collapse.node) +--- +---Base Node, Abstract +--- +---@class nvim_tree.api.Node +---@field type "file" | "directory" | "link" uv.fs_stat.result.type +---@field absolute_path string +---@field executable boolean +---@field fs_stat uv.fs_stat.result? +---@field git_status GitNodeStatus? +---@field hidden boolean +---@field name string +---@field parent nvim_tree.api.DirectoryNode? +---@field diag_severity lsp.DiagnosticSeverity? ----@class ApiNodeDeleteWipeBufferOpts ----@field force boolean|nil default false +--- +---File +--- +---@class nvim_tree.api.FileNode: nvim_tree.api.Node +---@field extension string -Api.node.buffer.delete = wrap_node(function(node, opts) - actions.node.buffer.delete(node, opts) -end) -Api.node.buffer.wipe = wrap_node(function(node, opts) - actions.node.buffer.wipe(node, opts) -end) +--- +---Directory +--- +---@class nvim_tree.api.DirectoryNode: nvim_tree.api.Node +---@field has_children boolean +---@field nodes nvim_tree.api.Node[] +---@field open boolean -Api.git.reload = wrap_explorer("reload_git") +--- +---Root Directory +--- +---@class nvim_tree.api.RootNode: nvim_tree.api.DirectoryNode -Api.events.subscribe = events.subscribe -Api.events.Event = events.Event +--- +---Link mixin +--- +---@class nvim_tree.api.LinkNode +---@field link_to string +---@field fs_stat_target uv.fs_stat.result -Api.live_filter.start = wrap_explorer_member("live_filter", "start_filtering") -Api.live_filter.clear = wrap_explorer_member("live_filter", "clear_filter") +--- +---File Link +--- +---@class nvim_tree.api.FileLinkNode: nvim_tree.api.FileNode, nvim_tree.api.LinkNode -Api.marks.get = wrap_node(wrap_explorer_member("marks", "get")) -Api.marks.list = wrap_explorer_member("marks", "list") -Api.marks.toggle = wrap_node(wrap_explorer_member("marks", "toggle")) -Api.marks.clear = wrap_explorer_member("marks", "clear") -Api.marks.bulk.delete = wrap_explorer_member("marks", "bulk_delete") -Api.marks.bulk.trash = wrap_explorer_member("marks", "bulk_trash") -Api.marks.bulk.move = wrap_explorer_member("marks", "bulk_move") -Api.marks.navigate.next = wrap_explorer_member("marks", "navigate_next") -Api.marks.navigate.prev = wrap_explorer_member("marks", "navigate_prev") -Api.marks.navigate.select = wrap_explorer_member("marks", "navigate_select") +--- +---DirectoryLink +--- +---@class nvim_tree.api.DirectoryLinkNode: nvim_tree.api.DirectoryNode, nvim_tree.api.LinkNode + +local api = { + events = require("nvim-tree.api.events"), + filter = require("nvim-tree.api.filter"), + fs = require("nvim-tree.api.fs"), + health = require("nvim-tree.api.health"), + map = require("nvim-tree.api.map"), + marks = require("nvim-tree.api.marks"), + node = require("nvim-tree.api.node"), + tree = require("nvim-tree.api.tree"), +} -Api.config.mappings.get_keymap = wrap(keymap.get_keymap) -Api.config.mappings.get_keymap_default = wrap(keymap.get_keymap_default) -Api.config.mappings.default_on_attach = keymap.default_on_attach -Api.diagnostics.hi_test = wrap(appearance_hi_test) +-- +--Legacy mappings +-- +api.git = { + reload = api.tree.reload_git, +} +api.live_filter = { + start = api.filter.live_filter.start, + clear = api.filter.live_filter.clear, +} +api.config = { + mappings = { + get_keymap = api.map.get_keymap, + get_keymap_default = api.map.get_keymap_default, + default_on_attach = api.map.default_on_attach, + } +} +api.diagnostics = { + hi_test = api.health.hi_test, +} -Api.commands.get = wrap(function() - return require("nvim-tree.commands").get() -end) +-- TODO #3241 create a proper decorator API +api.decorator = {} ---Create a decorator class by calling :extend() ---See :help nvim-tree-decorators ---@type nvim_tree.api.decorator.UserDecorator -Api.decorator.UserDecorator = UserDecorator --[[@as nvim_tree.api.decorator.UserDecorator]] +api.decorator.UserDecorator = require("nvim-tree.renderer.decorator.user") --[[@as nvim_tree.api.decorator.UserDecorator]] -return Api +return api diff --git a/lua/nvim-tree/api/commands.lua b/lua/nvim-tree/api/commands.lua new file mode 100644 index 00000000000..b5414f0c7e2 --- /dev/null +++ b/lua/nvim-tree/api/commands.lua @@ -0,0 +1,21 @@ +---@meta +local nvim_tree = { api = { commands = {} } } + +--- +---Arguments for [nvim_create_user_command()] +--- +---@class nvim_tree.api.commands.Command +--- +---@field name string +---@field command fun(args: vim.api.keyset.create_user_command.command_args) +---@field opts vim.api.keyset.user_command + +--- +---Retrieve all nvim-tree commands, see [nvim-tree-commands] +--- +---@return nvim_tree.api.commands.Command[] +function nvim_tree.api.commands.get() end + +require("nvim-tree.api.impl").commands(nvim_tree.api.commands) + +return nvim_tree.api.commands diff --git a/lua/nvim-tree/api/events.lua b/lua/nvim-tree/api/events.lua new file mode 100644 index 00000000000..7877b14fc63 --- /dev/null +++ b/lua/nvim-tree/api/events.lua @@ -0,0 +1,18 @@ +---@meta + +local events = require("nvim-tree.events") + +local nvim_tree = { api = { events = {} } } + +--- +---Register a handler for an event, see [nvim-tree-events]. +--- +---@param event_type string [nvim_tree_events_kind] +---@param callback fun(payload: table?) +function nvim_tree.api.events.subscribe(event_type, callback) end + +nvim_tree.api.events.Event = events.Event + +require("nvim-tree.api.impl").events(nvim_tree.api.events) + +return nvim_tree.api.events diff --git a/lua/nvim-tree/api/filter.lua b/lua/nvim-tree/api/filter.lua new file mode 100644 index 00000000000..784a9d7622d --- /dev/null +++ b/lua/nvim-tree/api/filter.lua @@ -0,0 +1,16 @@ +---@meta +local nvim_tree = { api = { filter = { live_filter = {} } } } + +--- +---Enter live filter mode. Opens an input window with [filetype] `NvimTreeFilter` +--- +function nvim_tree.api.filter.live_filter.start() end + +--- +---Exit live filter mode. +--- +function nvim_tree.api.filter.live_filter.clear() end + +require("nvim-tree.api.impl").filter(nvim_tree.api.filter) + +return nvim_tree.api.filter diff --git a/lua/nvim-tree/api/fs.lua b/lua/nvim-tree/api/fs.lua new file mode 100644 index 00000000000..206ab393e55 --- /dev/null +++ b/lua/nvim-tree/api/fs.lua @@ -0,0 +1,114 @@ +---@meta +local nvim_tree = { api = { fs = { copy = {} } } } + +--- +---Clear the nvim-tree clipboard. +--- +function nvim_tree.api.fs.clear_clipboard() end + +--- +---Copy the absolute path to the system clipboard. +--- +---@param node nvim_tree.api.Node +function nvim_tree.api.fs.copy.absolute_path(node) end + +--- +---Copy the name with extension omitted to the system clipboard. +--- +---@param node nvim_tree.api.Node +function nvim_tree.api.fs.copy.basename(node) end + +--- +---Copy the name to the system clipboard. +--- +---@param node nvim_tree.api.Node +function nvim_tree.api.fs.copy.filename(node) end + +--- +---Copy to the nvim-tree clipboard. +--- +---@param node nvim_tree.api.Node +function nvim_tree.api.fs.copy.node(node) end + +--- +---Copy the path relative to the tree root to the system clipboard. +--- +---@param node nvim_tree.api.Node +function nvim_tree.api.fs.copy.relative_path(node) end + +--- +---Prompt to create a file or directory. +--- +---When {node} is a file it will be created in the parent directory. +--- +---Use a trailing `"/"` to create a directory e.g. `"foo/"` +--- +---Multiple directories/files may be created e.g. `"foo/bar/baz"` +--- +---@param node nvim_tree.api.Node +function nvim_tree.api.fs.create(node) end + +--- +---Cut to the nvim-tree clipboard. +--- +---@param node nvim_tree.api.Node +function nvim_tree.api.fs.cut(node) end + +--- +---Paste from the nvim-tree clipboard. +--- +---If {node} is a file it will pasted in the parent directory. +--- +---@param node nvim_tree.api.Node +function nvim_tree.api.fs.paste(node) end + +--- +---Print the contents of the nvim-tree clipboard. +--- +function nvim_tree.api.fs.print_clipboard() end + +--- +---Delete from the file system. +--- +---@param node nvim_tree.api.Node +function nvim_tree.api.fs.remove(node) end + +--- +---Prompt to rename by name. +--- +---@param node nvim_tree.api.Node +function nvim_tree.api.fs.rename(node) end + +--- +---Prompt to rename by name with extension omitted. +--- +---@param node nvim_tree.api.Node +function nvim_tree.api.fs.rename_basename(node) end + +--- +---Prompt to rename by absolute path. +--- +---@param node nvim_tree.api.Node +function nvim_tree.api.fs.rename_full(node) end + +--- +---Prompt to rename. +--- +---@param node nvim_tree.api.Node +function nvim_tree.api.fs.rename_node(node) end + +--- +---Prompt to rename by absolute path with name omitted. +--- +---@param node nvim_tree.api.Node +function nvim_tree.api.fs.rename_sub(node) end + +--- +---Trash as per |nvim_tree.Config.Trash| +--- +---@param node nvim_tree.api.Node +function nvim_tree.api.fs.trash(node) end + +require("nvim-tree.api.impl").fs(nvim_tree.api.fs) + +return nvim_tree.api.fs diff --git a/lua/nvim-tree/api/health.lua b/lua/nvim-tree/api/health.lua new file mode 100644 index 00000000000..454dfb9217f --- /dev/null +++ b/lua/nvim-tree/api/health.lua @@ -0,0 +1,13 @@ +---@meta +local nvim_tree = { api = { health = {} } } + +--- +---Open a new buffer displaying all nvim-tree highlight groups, their link chain and concrete definition. +--- +---Similar to `:so $VIMRUNTIME/syntax/hitest.vim` as per |:highlight| +--- +function nvim_tree.api.health.hi_test() end + +require("nvim-tree.api.impl").health(nvim_tree.api.health) + +return nvim_tree.api.health diff --git a/lua/nvim-tree/api/impl.lua b/lua/nvim-tree/api/impl.lua new file mode 100644 index 00000000000..034a98aeb9d --- /dev/null +++ b/lua/nvim-tree/api/impl.lua @@ -0,0 +1,288 @@ +local core = require("nvim-tree.core") +local view = require("nvim-tree.view") +local utils = require("nvim-tree.utils") +local actions = require("nvim-tree.actions") +local appearance_hi_test = require("nvim-tree.appearance.hi-test") +local help = require("nvim-tree.help") +local keymap = require("nvim-tree.keymap") +local notify = require("nvim-tree.notify") + +local DirectoryNode = require("nvim-tree.node.directory") +local FileNode = require("nvim-tree.node.file") +local FileLinkNode = require("nvim-tree.node.file-link") +local RootNode = require("nvim-tree.node.root") + +local M = {} + +---Print error when setup not called. +---@param fn fun(...): any +---@return fun(...): any +local function wrap(fn) + return function(...) + if vim.g.NvimTreeSetup == 1 then + return fn(...) + else + notify.error("nvim-tree setup not called") + end + end +end + +---Invoke a method on the singleton explorer. +---Print error when setup not called. +---@param explorer_method string explorer method name +---@return fun(...): any +local function wrap_explorer(explorer_method) + return wrap(function(...) + local explorer = core.get_explorer() + if explorer then + return explorer[explorer_method](explorer, ...) + end + end) +end + +---Inject the node as the first argument if present otherwise do nothing. +---@param fn fun(node: Node, ...): any +---@return fun(node: Node?, ...): any +local function wrap_node(fn) + return function(node, ...) + node = node or wrap_explorer("get_node_at_cursor")() + if node then + return fn(node, ...) + end + end +end + +---Inject the node or nil as the first argument if absent. +---@param fn fun(node: Node?, ...): any +---@return fun(node: Node?, ...): any +local function wrap_node_or_nil(fn) + return function(node, ...) + node = node or wrap_explorer("get_node_at_cursor")() + return fn(node, ...) + end +end + +---Invoke a member's method on the singleton explorer. +---Print error when setup not called. +---@param explorer_member string explorer member name +---@param member_method string method name to invoke on member +---@param ... any passed to method +---@return fun(...): any +local function wrap_explorer_member_args(explorer_member, member_method, ...) + local method_args = ... + return wrap(function(...) + local explorer = core.get_explorer() + if explorer then + return explorer[explorer_member][member_method](explorer[explorer_member], method_args, ...) + end + end) +end + +---Invoke a member's method on the singleton explorer. +---Print error when setup not called. +---@param explorer_member string explorer member name +---@param member_method string method name to invoke on member +---@return fun(...): any +local function wrap_explorer_member(explorer_member, member_method) + return wrap(function(...) + local explorer = core.get_explorer() + if explorer then + return explorer[explorer_member][member_method](explorer[explorer_member], ...) + end + end) +end + +---@param mode string +---@param node Node +---@param edit_opts NodeEditOpts? +local function edit(mode, node, edit_opts) + local file_link = node:as(FileLinkNode) + local path = file_link and file_link.link_to or node.absolute_path + local cur_tabpage = vim.api.nvim_get_current_tabpage() + + actions.node.open_file.fn(mode, path) + + edit_opts = edit_opts or {} + + local mode_unsupported_quit_on_open = mode == "drop" or mode == "tab_drop" or mode == "edit_in_place" + if not mode_unsupported_quit_on_open and edit_opts.quit_on_open then + view.close(cur_tabpage) + end + + local mode_unsupported_focus = mode == "drop" or mode == "tab_drop" or mode == "edit_in_place" + local focus = edit_opts.focus == nil or edit_opts.focus == true + if not mode_unsupported_focus and not focus then + -- if mode == "tabnew" a new tab will be opened and we need to focus back to the previous tab + if mode == "tabnew" then + vim.cmd(":tabprev") + end + view.focus() + end +end + +---@param mode string +---@param toggle_group boolean? +---@return fun(node: Node, edit_opts: NodeEditOpts?) +local function open_or_expand_or_dir_up(mode, toggle_group) + ---@param node Node + ---@param edit_opts NodeEditOpts? + return function(node, edit_opts) + local root = node:as(RootNode) + local dir = node:as(DirectoryNode) + + if root or node.name == ".." then + actions.root.change_dir.fn("..") + elseif dir then + dir:expand_or_collapse(toggle_group) + elseif not toggle_group then + edit(mode, node, edit_opts) + end + end +end + +function M.tree(tree) + tree.open = wrap(actions.tree.open.fn) + tree.focus = tree.open + tree.toggle = wrap(actions.tree.toggle.fn) + tree.close = wrap(view.close) + tree.close_in_this_tab = wrap(view.close_this_tab_only) + tree.close_in_all_tabs = wrap(view.close_all_tabs) + tree.reload = wrap_explorer("reload_explorer") + tree.resize = wrap(actions.tree.resize.fn) + tree.change_root = wrap(function(...) require("nvim-tree").change_dir(...) end) + tree.change_root_to_parent = wrap_node(wrap_explorer("dir_up")) + tree.get_node_under_cursor = wrap_explorer("get_node_at_cursor") + tree.get_nodes = wrap_explorer("get_nodes") + tree.find_file = wrap(actions.tree.find_file.fn) + tree.search_node = wrap(actions.finders.search_node.fn) + tree.collapse_all = wrap(actions.tree.modifiers.collapse.all) + tree.expand_all = wrap_node(actions.tree.modifiers.expand.all) + tree.toggle_enable_filters = wrap_explorer_member("filters", "toggle") + tree.toggle_gitignore_filter = wrap_explorer_member_args("filters", "toggle", "git_ignored") + tree.toggle_git_clean_filter = wrap_explorer_member_args("filters", "toggle", "git_clean") + tree.toggle_no_buffer_filter = wrap_explorer_member_args("filters", "toggle", "no_buffer") + tree.toggle_custom_filter = wrap_explorer_member_args("filters", "toggle", "custom") + tree.toggle_hidden_filter = wrap_explorer_member_args("filters", "toggle", "dotfiles") + tree.toggle_no_bookmark_filter = wrap_explorer_member_args("filters", "toggle", "no_bookmark") + tree.toggle_help = wrap(help.toggle) + tree.is_tree_buf = wrap(utils.is_nvim_tree_buf) + tree.is_visible = wrap(view.is_visible) + tree.winid = wrap(view.winid) + tree.reload_git = wrap_explorer("reload_git") + tree.change_root_to_node = wrap_node(function(node) + if node.name == ".." or node:is(RootNode) then + actions.root.change_dir.fn("..") + return + end + + if node:is(FileNode) and node.parent ~= nil then + actions.root.change_dir.fn(node.parent:last_group_node().absolute_path) + return + end + + if node:is(DirectoryNode) then + actions.root.change_dir.fn(node:last_group_node().absolute_path) + return + end + end) +end + +function M.fs(fs) + fs.create = wrap_node_or_nil(actions.fs.create_file.fn) + fs.remove = wrap_node(actions.fs.remove_file.fn) + fs.trash = wrap_node(actions.fs.trash.fn) + fs.rename_node = wrap_node(actions.fs.rename_file.fn(":t")) + fs.rename = wrap_node(actions.fs.rename_file.fn(":t")) + fs.rename_sub = wrap_node(actions.fs.rename_file.fn(":p:h")) + fs.rename_basename = wrap_node(actions.fs.rename_file.fn(":t:r")) + fs.rename_full = wrap_node(actions.fs.rename_file.fn(":p")) + fs.cut = wrap_node(wrap_explorer_member("clipboard", "cut")) + fs.paste = wrap_node(wrap_explorer_member("clipboard", "paste")) + fs.clear_clipboard = wrap_explorer_member("clipboard", "clear_clipboard") + fs.print_clipboard = wrap_explorer_member("clipboard", "print_clipboard") + fs.copy.node = wrap_node(wrap_explorer_member("clipboard", "copy")) + fs.copy.absolute_path = wrap_node(wrap_explorer_member("clipboard", "copy_absolute_path")) + fs.copy.filename = wrap_node(wrap_explorer_member("clipboard", "copy_filename")) + fs.copy.basename = wrap_node(wrap_explorer_member("clipboard", "copy_basename")) + fs.copy.relative_path = wrap_node(wrap_explorer_member("clipboard", "copy_path")) +end + +function M.node(node) + node.open.edit = wrap_node(open_or_expand_or_dir_up("edit")) + node.open.drop = wrap_node(open_or_expand_or_dir_up("drop")) + node.open.tab_drop = wrap_node(open_or_expand_or_dir_up("tab_drop")) + node.open.replace_tree_buffer = wrap_node(open_or_expand_or_dir_up("edit_in_place")) + node.open.no_window_picker = wrap_node(open_or_expand_or_dir_up("edit_no_picker")) + node.open.vertical = wrap_node(open_or_expand_or_dir_up("vsplit")) + node.open.vertical_no_picker = wrap_node(open_or_expand_or_dir_up("vsplit_no_picker")) + node.open.horizontal = wrap_node(open_or_expand_or_dir_up("split")) + node.open.horizontal_no_picker = wrap_node(open_or_expand_or_dir_up("split_no_picker")) + node.open.tab = wrap_node(open_or_expand_or_dir_up("tabnew")) + node.open.toggle_group_empty = wrap_node(open_or_expand_or_dir_up("toggle_group_empty", true)) + node.open.preview = wrap_node(open_or_expand_or_dir_up("preview")) + node.open.preview_no_picker = wrap_node(open_or_expand_or_dir_up("preview_no_picker")) + node.show_info_popup = wrap_node(actions.node.file_popup.toggle_file_info) + node.run.cmd = wrap_node(actions.node.run_command.run_file_command) + node.run.system = wrap_node(actions.node.system_open.fn) + node.navigate.sibling.next = wrap_node(actions.moves.sibling.fn("next")) + node.navigate.sibling.prev = wrap_node(actions.moves.sibling.fn("prev")) + node.navigate.sibling.first = wrap_node(actions.moves.sibling.fn("first")) + node.navigate.sibling.last = wrap_node(actions.moves.sibling.fn("last")) + node.navigate.parent = wrap_node(actions.moves.parent.fn(false)) + node.navigate.parent_close = wrap_node(actions.moves.parent.fn(true)) + node.navigate.git.next = wrap_node(actions.moves.item.fn({ where = "next", what = "git" })) + node.navigate.git.next_skip_gitignored = wrap_node(actions.moves.item.fn({ where = "next", what = "git", skip_gitignored = true })) + node.navigate.git.next_recursive = wrap_node(actions.moves.item.fn({ where = "next", what = "git", recurse = true })) + node.navigate.git.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "git" })) + node.navigate.git.prev_skip_gitignored = wrap_node(actions.moves.item.fn({ where = "prev", what = "git", skip_gitignored = true })) + node.navigate.git.prev_recursive = wrap_node(actions.moves.item.fn({ where = "prev", what = "git", recurse = true })) + node.navigate.diagnostics.next = wrap_node(actions.moves.item.fn({ where = "next", what = "diag" })) + node.navigate.diagnostics.next_recursive = wrap_node(actions.moves.item.fn({ where = "next", what = "diag", recurse = true })) + node.navigate.diagnostics.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "diag" })) + node.navigate.diagnostics.prev_recursive = wrap_node(actions.moves.item.fn({ where = "prev", what = "diag", recurse = true })) + node.navigate.opened.next = wrap_node(actions.moves.item.fn({ where = "next", what = "opened" })) + node.navigate.opened.prev = wrap_node(actions.moves.item.fn({ where = "prev", what = "opened" })) + node.expand = wrap_node(actions.tree.modifiers.expand.node) + node.collapse = wrap_node(actions.tree.modifiers.collapse.node) + node.buffer.delete = wrap_node(function(n, opts) actions.node.buffer.delete(n, opts) end) + node.buffer.wipe = wrap_node(function(n, opts) actions.node.buffer.wipe(n, opts) end) +end + +function M.events(events) + events.subscribe = require("nvim-tree.events").subscribe + events.Event = require("nvim-tree.events").Event +end + +function M.filter(filter) + filter.live_filter.start = wrap_explorer_member("live_filter", "start_filtering") + filter.live_filter.clear = wrap_explorer_member("live_filter", "clear_filter") +end + +function M.marks(marks) + marks.get = wrap_node(wrap_explorer_member("marks", "get")) + marks.list = wrap_explorer_member("marks", "list") + marks.toggle = wrap_node(wrap_explorer_member("marks", "toggle")) + marks.clear = wrap_explorer_member("marks", "clear") + marks.bulk.delete = wrap_explorer_member("marks", "bulk_delete") + marks.bulk.trash = wrap_explorer_member("marks", "bulk_trash") + marks.bulk.move = wrap_explorer_member("marks", "bulk_move") + marks.navigate.next = wrap_explorer_member("marks", "navigate_next") + marks.navigate.prev = wrap_explorer_member("marks", "navigate_prev") + marks.navigate.select = wrap_explorer_member("marks", "navigate_select") +end + +function M.map(map) + map.get_keymap = wrap(keymap.get_keymap) + map.get_keymap_default = wrap(keymap.get_keymap_default) + map.default_on_attach = keymap.default_on_attach +end + +function M.health(health) + health.hi_test = wrap(appearance_hi_test) +end + +function M.commands(commands) + commands.get = wrap(function() return require("nvim-tree.commands").get() end) +end + +return M diff --git a/lua/nvim-tree/api/map.lua b/lua/nvim-tree/api/map.lua new file mode 100644 index 00000000000..96cfcc3b7c5 --- /dev/null +++ b/lua/nvim-tree/api/map.lua @@ -0,0 +1,24 @@ +---@meta +local nvim_tree = { api = { map = {} } } + +--- +---Retrieve all buffer local mappings for nvim-tree. These are the mappings that are applied by [nvim_tree.Config] {on_attach}, which may include default mappings. +--- +---@return vim.api.keyset.get_keymap[] +function nvim_tree.api.map.get_keymap() end + +--- +--- Retrieves the buffer local mappings for nvim-tree that are applied by [nvim_tree.api.map.default_on_attach()] +--- +---@return vim.api.keyset.get_keymap[] +function nvim_tree.api.map.get_keymap_default() end + +--- +---Apply all [nvim-tree-mappings-default]. Call from your [nvim_tree.Config] {on_attach}. +--- +---@param bufnr integer use the `bufnr` passed to {on_attach} +function nvim_tree.api.map.default_on_attach(bufnr) end + +require("nvim-tree.api.impl").map(nvim_tree.api.map) + +return nvim_tree.api.map diff --git a/lua/nvim-tree/api/marks.lua b/lua/nvim-tree/api/marks.lua new file mode 100644 index 00000000000..63f2f2b8ed9 --- /dev/null +++ b/lua/nvim-tree/api/marks.lua @@ -0,0 +1,60 @@ +---@meta +local nvim_tree = { api = { marks = { bulk = {}, navigate = {}, } } } + +--- +---Return the node if it is marked. +--- +---@return nvim_tree.api.Node? +function nvim_tree.api.marks.get() end + +--- +---Retrieve all marked nodes. +--- +---@return nvim_tree.api.Node[] +function nvim_tree.api.marks.list() end + +--- +---Toggle mark. +--- +---@param node nvim_tree.api.Node file or directory +function nvim_tree.api.marks.toggle(node) end + +--- +---Clear all marks. +--- +function nvim_tree.api.marks.clear() end + +--- +---Delete all marked, prompting if [nvim_tree.Config.UI.Confirm] {remove} +--- +function nvim_tree.api.marks.bulk.delete() end + +--- +---Delete all marked, prompting if [nvim_tree.Config.UI.Confirm] {trash} +--- +function nvim_tree.api.marks.bulk.trash() end + +--- +---Prompts for a directory to move all marked nodes into. +--- +function nvim_tree.api.marks.bulk.move() end + +--- +---Navigate to the next marked node, wraps. +--- +function nvim_tree.api.marks.navigate.next() end + +--- +---Navigate to the previous marked node, wraps. +--- +function nvim_tree.api.marks.navigate.prev() end + +--- +---Prompts for selection of a marked node, sorted by absolute paths. +---A folder will be focused, a file will be opened. +--- +function nvim_tree.api.marks.navigate.select() end + +require("nvim-tree.api.impl").marks(nvim_tree.api.marks) + +return nvim_tree.api.marks diff --git a/lua/nvim-tree/api/node.lua b/lua/nvim-tree/api/node.lua new file mode 100644 index 00000000000..420b3fea03c --- /dev/null +++ b/lua/nvim-tree/api/node.lua @@ -0,0 +1,89 @@ +---@meta +local nvim_tree = { api = { node = { navigate = { sibling = {}, git = {}, diagnostics = {}, opened = {}, }, run = {}, open = {}, buffer = {}, } } } + +---@class ApiNodeDeleteWipeBufferOpts +---@field force boolean|nil default false + +---@class NodeEditOpts +---@field quit_on_open boolean|nil default false +---@field focus boolean|nil default true + +function nvim_tree.api.node.buffer.delete() end + +function nvim_tree.api.node.buffer.wipe() end + +function nvim_tree.api.node.collapse() end + +function nvim_tree.api.node.expand() end + +function nvim_tree.api.node.navigate.diagnostics.next() end + +function nvim_tree.api.node.navigate.diagnostics.next_recursive() end + +function nvim_tree.api.node.navigate.diagnostics.prev() end + +function nvim_tree.api.node.navigate.diagnostics.prev_recursive() end + +function nvim_tree.api.node.navigate.git.next() end + +function nvim_tree.api.node.navigate.git.next_recursive() end + +function nvim_tree.api.node.navigate.git.next_skip_gitignored() end + +function nvim_tree.api.node.navigate.git.prev() end + +function nvim_tree.api.node.navigate.git.prev_recursive() end + +function nvim_tree.api.node.navigate.git.prev_skip_gitignored() end + +function nvim_tree.api.node.navigate.opened.next() end + +function nvim_tree.api.node.navigate.opened.prev() end + +function nvim_tree.api.node.navigate.parent() end + +function nvim_tree.api.node.navigate.parent_close() end + +function nvim_tree.api.node.navigate.sibling.first() end + +function nvim_tree.api.node.navigate.sibling.last() end + +function nvim_tree.api.node.navigate.sibling.next() end + +function nvim_tree.api.node.navigate.sibling.prev() end + +function nvim_tree.api.node.open.drop() end + +function nvim_tree.api.node.open.edit() end + +function nvim_tree.api.node.open.horizontal() end + +function nvim_tree.api.node.open.horizontal_no_picker() end + +function nvim_tree.api.node.open.no_window_picker() end + +function nvim_tree.api.node.open.preview() end + +function nvim_tree.api.node.open.preview_no_picker() end + +function nvim_tree.api.node.open.replace_tree_buffer() end + +function nvim_tree.api.node.open.tab() end + +function nvim_tree.api.node.open.tab_drop() end + +function nvim_tree.api.node.open.toggle_group_empty() end + +function nvim_tree.api.node.open.vertical() end + +function nvim_tree.api.node.open.vertical_no_picker() end + +function nvim_tree.api.node.run.cmd() end + +function nvim_tree.api.node.run.system() end + +function nvim_tree.api.node.show_info_popup() end + +require("nvim-tree.api.impl").node(nvim_tree.api.node) + +return nvim_tree.api.node diff --git a/lua/nvim-tree/api/tree.lua b/lua/nvim-tree/api/tree.lua new file mode 100644 index 00000000000..ada772571d3 --- /dev/null +++ b/lua/nvim-tree/api/tree.lua @@ -0,0 +1,288 @@ +---@meta +local nvim_tree = { api = { tree = {} } } + +-- TODO #3088 move expand/collapse into api.node + +--- +---Open the tree, focusing it if already open. +--- +---@param opts? nvim_tree.api.tree.open.Opts optional +function nvim_tree.api.tree.open(opts) end + +---@class nvim_tree.api.tree.open.Opts +---@inlinedoc +--- +---Root directory for the tree +---@field path? string +--- +---Open the tree in the current window +---(default: false) +---@field current_window? boolean +--- +---Open the tree in the specified [window-ID], overrides {current_window} +---@field winid? integer +--- +---Find the current buffer. +---(default: false) +---@field find_file? boolean +--- +---Update root following {find_file}, see [nvim_tree.Config.UpdateFocusedFile] {update_root} +---(default: false) +---@field update_root? boolean + +--- +---Open or close the tree. +--- +---@param opts? nvim_tree.api.tree.toggle.Opts optional +function nvim_tree.api.tree.toggle(opts) end + +---@class nvim_tree.api.tree.toggle.Opts +---@inlinedoc +--- +---Root directory for the tree +---@field path? string +--- +---Open the tree in the current window +---(default: false) +---@field current_window? boolean +--- +---Open the tree in the specified [window-ID], overrides {current_window} +---@field winid? integer +--- +---Find the current buffer. +---(default: false) +---@field find_file? boolean +--- +---Update root following {find_file}, see [nvim_tree.Config.UpdateFocusedFile] {update_root} +---(default: false) +---@field update_root? boolean +--- +---Focus the tree when opening. +---(default: true) +---@field focus? boolean + +--- +---Close the tree, affecting all tabs as per [nvim_tree.Config.Tab.Sync] {close} +--- +function nvim_tree.api.tree.close() end + +--- +---Close the tree in this tab only. +--- +function nvim_tree.api.tree.close_in_this_tab() end + +--- +---Close the tree in all tabs. +--- +function nvim_tree.api.tree.close_in_all_tabs() end + +--- +---Focus the tree, opening it if necessary. Retained for compatibility, use [nvim_tree.api.tree.open()] with no arguments instead. +--- +function nvim_tree.api.tree.focus() end + +--- +---Refresh the tree. Does nothing if closed. +--- +function nvim_tree.api.tree.reload() end + +--- +---Resize the tree, persisting the new size. Resets to [nvim_tree.Config.View] {width} when no {opts} provided. +--- +---Only one option is supported, priority order: {width}, {absolute}, {relative}. +--- +---{absolute} and {relative} do nothing when [nvim_tree.Config.View] {width} is a function. +--- +---@param opts? nvim_tree.api.tree.resize.Opts optional +function nvim_tree.api.tree.resize(opts) end + +---@class nvim_tree.api.tree.resize.Opts +---@inlinedoc +--- +---New [nvim_tree.Config.View] {width} value. +---@field width nvim_tree.Config.View.WidthSpec|nvim_tree.Config.View.Width +--- +---Set the width. +---@field absolute integer +--- +---Increase or decrease the width. +---@field relative integer + +--- +---Change the tree's root to a path. +--- +---@param path? string absolute or relative path. +function nvim_tree.api.tree.change_root(path) end + +--- +---Change the tree's root to a folder node or the parent of a file node. +--- +---@param node nvim_tree.api.Node directory or file +function nvim_tree.api.tree.change_root_to_node(node) end + +--- +---Change the tree's root to the parent of a node. +--- +---@param node nvim_tree.api.Node directory or file +function nvim_tree.api.tree.change_root_to_parent(node) end + +--- +---Retrieve the currently focused node. +--- +---@return nvim_tree.api.Node? nil if tree is not visible. +function nvim_tree.api.tree.get_node_under_cursor() end + +--- +---Retrieve a hierarchical list of all the nodes. +--- +---@return nvim_tree.api.Node[] +function nvim_tree.api.tree.get_nodes() end + +--- +---Find and focus a file or folder in the tree. Finds current buffer unless otherwise specified. +--- +---@param opts? nvim_tree.api.tree.find_file.Opts optional +function nvim_tree.api.tree.find_file(opts) end + +---@class nvim_tree.api.tree.find_file.Opts +---@inlinedoc +--- +---Absolute/relative path OR `bufnr` to find. +---@field buf? string|integer +--- +---Open the tree if necessary. +---(default: false) +---@field open? boolean +--- +---Requires {open}: open in the current window. +---(default: false) +---@field current_window? boolean +--- +---Open the tree in the specified [window-ID], overrides {current_window} +---@field winid? integer +--- +---Update root after find, see [nvim_tree.Config.UpdateFocusedFile] {update_root} +---(default: false) +---@field update_root? boolean +--- +---Focus the tree window. +---(default: false) +---@field focus? boolean + +--- +---Open the search dialogue. +--- +function nvim_tree.api.tree.search_node() end + +--- +---Collapse the tree. +--- +---@param opts? nvim_tree.api.tree.collapse.Opts optional +function nvim_tree.api.tree.collapse_all(opts) end + +---@class nvim_tree.api.tree.collapse.Opts +---@inlinedoc +--- +---Do not collapse nodes with open buffers. +---(default: false) +---@field keep_buffers? boolean + +--- +---Recursively expand all nodes under the tree root or specified folder. +--- +---@param node? nvim_tree.api.Node directory +---@param opts? nvim_tree.api.tree.expand.Opts optional +function nvim_tree.api.tree.expand_all(node, opts) end + +---@class nvim_tree.api.tree.expand.Opts +---@inlinedoc +--- +---Return `true` if `node` should be expanded. `expansion_count` is the total number of folders expanded. +---@field expand_until? fun(expansion_count: integer, node: Node): boolean + +--- +---Toggle [nvim_tree.Config.Filters] {enable} all filters. +--- +function nvim_tree.api.tree.toggle_enable_filters() end + +--- +---Toggle [nvim_tree.Config.Filters] {git_ignored} filter. +--- +function nvim_tree.api.tree.toggle_gitignore_filter() end + +--- +---Toggle [nvim_tree.Config.Filters] {dotfiles} filter. +--- +function nvim_tree.api.tree.toggle_hidden_filter() end + +--- +---Toggle [nvim_tree.Config.Filters] {git_clean} filter. +--- +function nvim_tree.api.tree.toggle_git_clean_filter() end + +--- +---Toggle [nvim_tree.Config.Filters] {no_buffer} filter. +--- +function nvim_tree.api.tree.toggle_no_buffer_filter() end + +--- +---Toggle [nvim_tree.Config.Filters] {no_bookmark} filter. +--- +function nvim_tree.api.tree.toggle_no_bookmark_filter() end + +--- +---Toggle [nvim_tree.Config.Filters] {custom} filter. +--- +function nvim_tree.api.tree.toggle_custom_filter() end + +--- +---Toggle help view. +--- +function nvim_tree.api.tree.toggle_help() end + +--- +---Checks if a buffer is an nvim-tree. +--- +---@param bufnr? integer 0 or nil for current buffer. +--- +---@return boolean +function nvim_tree.api.tree.is_tree_buf(bufnr) end + +--- +---Checks if nvim-tree is visible on the current, specified or any tab. +--- +---@param opts? nvim_tree.api.tree.is_visible.Opts optional +---@return boolean +function nvim_tree.api.tree.is_visible(opts) end + +---@class nvim_tree.api.tree.is_visible.Opts +---@inlinedoc +--- +--- [tab-ID] 0 or nil for current. +---@field tabpage? integer +--- +---Visible on any tab. +---(default: false) +---@field any_tabpage? boolean + +--- +---Retrieve the window of the open tree. +--- +---@param opts? nvim_tree.api.tree.winid.Opts optional +---@return integer? [window-ID], nil if tree is not visible. +function nvim_tree.api.tree.winid(opts) end + +---@class nvim_tree.api.tree.winid.Opts +---@inlinedoc +--- +---[tab-ID] 0 or nil for current. +---@field tabpage? integer + +--- +---Update the git status of the entire tree. +--- +function nvim_tree.api.tree.reload_git() end + +require("nvim-tree.api.impl").tree(nvim_tree.api.tree) + +return nvim_tree.api.tree diff --git a/lua/nvim-tree/commands.lua b/lua/nvim-tree/commands.lua index 8158465a4c7..093254707bd 100644 --- a/lua/nvim-tree/commands.lua +++ b/lua/nvim-tree/commands.lua @@ -1,5 +1,6 @@ local M = {} +---@type nvim_tree.api.commands.Command[] local CMDS = { { name = "NvimTreeOpen", @@ -118,7 +119,7 @@ local CMDS = { bar = true, }, command = function() - require("nvim-tree.api").tree.collapse_all(false) + require("nvim-tree.api").tree.collapse_all({ keep_buffers = false }) end, }, { @@ -128,7 +129,7 @@ local CMDS = { bar = true, }, command = function() - require("nvim-tree.api").tree.collapse_all(true) + require("nvim-tree.api").tree.collapse_all({ keep_buffers = true }) end, }, { @@ -137,11 +138,12 @@ local CMDS = { desc = "nvim-tree: highlight test", }, command = function() - require("nvim-tree.api").diagnostics.hi_test() + require("nvim-tree.api").health.hi_test() end, }, } +---@return nvim_tree.api.commands.Command[] function M.get() return vim.deepcopy(CMDS) end diff --git a/lua/nvim-tree/keymap.lua b/lua/nvim-tree/keymap.lua index c3373741f22..1758b7f9bdc 100644 --- a/lua/nvim-tree/keymap.lua +++ b/lua/nvim-tree/keymap.lua @@ -74,8 +74,8 @@ function M.default_on_attach(bufnr) vim.keymap.set("n", "e", api.fs.rename_basename, opts("Rename: Basename")) vim.keymap.set("n", "]e", api.node.navigate.diagnostics.next, opts("Next Diagnostic")) vim.keymap.set("n", "[e", api.node.navigate.diagnostics.prev, opts("Prev Diagnostic")) - vim.keymap.set("n", "F", api.live_filter.clear, opts("Live Filter: Clear")) - vim.keymap.set("n", "f", api.live_filter.start, opts("Live Filter: Start")) + vim.keymap.set("n", "F", api.filter.live_filter.clear, opts("Live Filter: Clear")) + vim.keymap.set("n", "f", api.filter.live_filter.start, opts("Live Filter: Start")) vim.keymap.set("n", "g?", api.tree.toggle_help, opts("Help")) vim.keymap.set("n", "gy", api.fs.copy.absolute_path, opts("Copy Absolute Path")) vim.keymap.set("n", "ge", api.fs.copy.basename, opts("Copy Basename")) diff --git a/lua/nvim-tree/view.lua b/lua/nvim-tree/view.lua index 275e68635d0..e1ad5d5fd70 100644 --- a/lua/nvim-tree/view.lua +++ b/lua/nvim-tree/view.lua @@ -487,7 +487,7 @@ function M.focus(winnr, open_if_closed) end --- Retrieve the winid of the open tree. ----@param opts ApiTreeWinIdOpts|nil +---@param opts nvim_tree.api.tree.winid.Opts|nil ---@return number|nil winid unlike get_winnr(), this returns nil if the nvim-tree window is not visible function M.winid(opts) local tabpage = opts and opts.tabpage diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua index e8dda6f50e1..acdf3df6fb0 100644 --- a/scripts/gen_vimdoc_config.lua +++ b/scripts/gen_vimdoc_config.lua @@ -8,28 +8,40 @@ ---Generated within help files in this order ---@type Module[] local modules = { - { helptag = "nvim-tree-config", title = "Class: Config", path = "./lua/nvim_tree/_meta/config.lua", }, - { helptag = "nvim-tree-config-sort", title = "Class: Config.Sort", path = "./lua/nvim_tree/_meta/config/sort.lua", }, - { helptag = "nvim-tree-config-view", title = "Class: Config.View", path = "./lua/nvim_tree/_meta/config/view.lua", }, - { helptag = "nvim-tree-config-renderer", title = "Class: Config.Renderer", path = "./lua/nvim_tree/_meta/config/renderer.lua", }, - { helptag = "nvim-tree-config-hijack-directories", title = "Class: Config.HijackDirectories", path = "./lua/nvim_tree/_meta/config/hijack_directories.lua", }, - { helptag = "nvim-tree-config-update-focused-file", title = "Class: Config.UpdateFocusedFile", path = "./lua/nvim_tree/_meta/config/update_focused_file.lua", }, - { helptag = "nvim-tree-config-system-open", title = "Class: Config.SystemOpen", path = "./lua/nvim_tree/_meta/config/system_open.lua", }, - { helptag = "nvim-tree-config-git", title = "Class: Config.Git", path = "./lua/nvim_tree/_meta/config/git.lua", }, - { helptag = "nvim-tree-config-diagnostics", title = "Class: Config.Diagnostics", path = "./lua/nvim_tree/_meta/config/diagnostics.lua", }, - { helptag = "nvim-tree-config-modified", title = "Class: Config.Modified", path = "./lua/nvim_tree/_meta/config/modified.lua", }, - { helptag = "nvim-tree-config-filters", title = "Class: Config.Filters", path = "./lua/nvim_tree/_meta/config/filters.lua", }, - { helptag = "nvim-tree-config-live-filter", title = "Class: Config.LiveFilter", path = "./lua/nvim_tree/_meta/config/live_filter.lua", }, - { helptag = "nvim-tree-config-filesystem-watchers", title = "Class: Config.FilesystemWatchers", path = "./lua/nvim_tree/_meta/config/filesystem_watchers.lua", }, - { helptag = "nvim-tree-config-actions", title = "Class: Config.Actions", path = "./lua/nvim_tree/_meta/config/actions.lua", }, - { helptag = "nvim-tree-config-trash", title = "Class: Config.Trash", path = "./lua/nvim_tree/_meta/config/trash.lua", }, - { helptag = "nvim-tree-config-tab", title = "Class: Config.Tab", path = "./lua/nvim_tree/_meta/config/tab.lua", }, - { helptag = "nvim-tree-config-notify", title = "Class: Config.Notify", path = "./lua/nvim_tree/_meta/config/notify.lua", }, - { helptag = "nvim-tree-config-bookmarks", title = "Class: Config.Bookmarks", path = "./lua/nvim_tree/_meta/config/bookmarks.lua", }, - { helptag = "nvim-tree-config-help", title = "Class: Config.Help", path = "./lua/nvim_tree/_meta/config/help.lua", }, - { helptag = "nvim-tree-config-ui", title = "Class: Config.UI", path = "./lua/nvim_tree/_meta/config/ui.lua", name = "UI", }, - { helptag = "nvim-tree-config-experimental", title = "Class: Config.Experimental", path = "./lua/nvim_tree/_meta/config/experimental.lua", }, - { helptag = "nvim-tree-config-log", title = "Class: Config.Log", path = "./lua/nvim_tree/_meta/config/log.lua", }, + { helptag = "nvim-tree-config", title = "Class: Config", path = "./lua/nvim_tree/_meta/config.lua", }, + { helptag = "nvim-tree-config-sort", title = "Class: Config.Sort", path = "./lua/nvim_tree/_meta/config/sort.lua", }, + { helptag = "nvim-tree-config-view", title = "Class: Config.View", path = "./lua/nvim_tree/_meta/config/view.lua", }, + { helptag = "nvim-tree-config-renderer", title = "Class: Config.Renderer", path = "./lua/nvim_tree/_meta/config/renderer.lua", }, + { helptag = "nvim-tree-config-hijack-directories", title = "Class: Config.HijackDirectories", path = "./lua/nvim_tree/_meta/config/hijack_directories.lua", }, + { helptag = "nvim-tree-config-update-focused-file", title = "Class: Config.UpdateFocusedFile", path = "./lua/nvim_tree/_meta/config/update_focused_file.lua", }, + { helptag = "nvim-tree-config-system-open", title = "Class: Config.SystemOpen", path = "./lua/nvim_tree/_meta/config/system_open.lua", }, + { helptag = "nvim-tree-config-git", title = "Class: Config.Git", path = "./lua/nvim_tree/_meta/config/git.lua", }, + { helptag = "nvim-tree-config-diagnostics", title = "Class: Config.Diagnostics", path = "./lua/nvim_tree/_meta/config/diagnostics.lua", }, + { helptag = "nvim-tree-config-modified", title = "Class: Config.Modified", path = "./lua/nvim_tree/_meta/config/modified.lua", }, + { helptag = "nvim-tree-config-filters", title = "Class: Config.Filters", path = "./lua/nvim_tree/_meta/config/filters.lua", }, + { helptag = "nvim-tree-config-live-filter", title = "Class: Config.LiveFilter", path = "./lua/nvim_tree/_meta/config/live_filter.lua", }, + { helptag = "nvim-tree-config-filesystem-watchers", title = "Class: Config.FilesystemWatchers", path = "./lua/nvim_tree/_meta/config/filesystem_watchers.lua", }, + { helptag = "nvim-tree-config-actions", title = "Class: Config.Actions", path = "./lua/nvim_tree/_meta/config/actions.lua", }, + { helptag = "nvim-tree-config-trash", title = "Class: Config.Trash", path = "./lua/nvim_tree/_meta/config/trash.lua", }, + { helptag = "nvim-tree-config-tab", title = "Class: Config.Tab", path = "./lua/nvim_tree/_meta/config/tab.lua", }, + { helptag = "nvim-tree-config-notify", title = "Class: Config.Notify", path = "./lua/nvim_tree/_meta/config/notify.lua", }, + { helptag = "nvim-tree-config-bookmarks", title = "Class: Config.Bookmarks", path = "./lua/nvim_tree/_meta/config/bookmarks.lua", }, + { helptag = "nvim-tree-config-help", title = "Class: Config.Help", path = "./lua/nvim_tree/_meta/config/help.lua", }, + { helptag = "nvim-tree-config-ui", title = "Class: Config.UI", path = "./lua/nvim_tree/_meta/config/ui.lua", name = "UI", }, + { helptag = "nvim-tree-config-experimental", title = "Class: Config.Experimental", path = "./lua/nvim_tree/_meta/config/experimental.lua", }, + { helptag = "nvim-tree-config-log", title = "Class: Config.Log", path = "./lua/nvim_tree/_meta/config/log.lua", }, + + { helptag = "nvim-tree-api", title = "Lua module: nvim_tree.api", path = "./lua/nvim_tree/api.lua", }, + + { helptag = "nvim-tree-api-commands", title = "Lua module: nvim_tree.api.commands", path = "./lua/nvim_tree/api/commands.lua", }, + { helptag = "nvim-tree-api-events", title = "Lua module: nvim_tree.api.events", path = "./lua/nvim_tree/api/events.lua", }, + { helptag = "nvim-tree-api-filter", title = "Lua module: nvim_tree.api.filter", path = "./lua/nvim_tree/api/filter.lua", }, + { helptag = "nvim-tree-api-fs", title = "Lua module: nvim_tree.api.fs", path = "./lua/nvim_tree/api/fs.lua", }, + { helptag = "nvim-tree-api-health", title = "Lua module: nvim_tree.api.health", path = "./lua/nvim_tree/api/health.lua", }, + { helptag = "nvim-tree-api-map", title = "Lua module: nvim_tree.api.map", path = "./lua/nvim_tree/api/map.lua", }, + { helptag = "nvim-tree-api-marks", title = "Lua module: nvim_tree.api.marks", path = "./lua/nvim_tree/api/marks.lua", }, + { helptag = "nvim-tree-api-node", title = "Lua module: nvim_tree.api.node", path = "./lua/nvim_tree/api/node.lua", }, + { helptag = "nvim-tree-api-tree", title = "Lua module: nvim_tree.api.tree", path = "./lua/nvim_tree/api/tree.lua", }, } -- hydrate file names @@ -37,13 +49,13 @@ for _, m in ipairs(modules) do m.file = vim.fn.fnamemodify(m.path, ":t") end ---module name is derived by the generator as the file name with the first letter capitalised +--section name is derived by the generator as the file name with the first letter capitalised --except for some like UI ---@type table -local modules_by_name = {} +local modules_by_section = {} for _, m in ipairs(modules) do local name = m.name or m.file:gsub(".lua", ""):gsub("^%l", string.upper) - modules_by_name[name] = m + modules_by_section[name] = m end ---@diagnostic disable-next-line: undefined-doc-name @@ -59,26 +71,43 @@ local config = { files = vim.tbl_map(function(m) return m.path end, modules), section_fmt = function(name) - return modules_by_name[name] and modules_by_name[name].title or error(string.format("unknown module %s passed to section_fmt", name)) + print(string.format("section_fmt name=%s", name)) + return modules_by_section[name] and modules_by_section[name].title or + error(string.format("unknown module %s passed to section_fmt", name)) end, helptag_fmt = function(name) - return modules_by_name[name] and modules_by_name[name].helptag or error(string.format("unknown module %s passed to helptag_fmt", name)) + print(string.format("helptag_fmt name=%s", name)) + return modules_by_section[name] and modules_by_section[name].helptag or + error(string.format("unknown module %s passed to helptag_fmt", name)) end, - -- class/function's help tag - fn_helptag_fmt = function(fun) - -- Modified copy of fn_helptag_fmt_common - -- Uses fully qualified class name in the tag for methods. - -- The module is used everywhere else, however not available for classes. - local fn_sfx = fun.table and "" or "()" - if fun.classvar then - return string.format("%s:%s%s", fun.class or fun.classvar, fun.name, fn_sfx) - end - if fun.module then - return string.format("%s.%s%s", fun.module, fun.name, fn_sfx) + -- optional, no default xform + fn_xform = function(fun) + -- print(string.format("fn_xform fun=%s", vim.inspect(fun))) + + if (fun.module) then + -- generator doesn't strip meta + -- also cascades into fn_helptag_fmt + local module = fun.module:gsub("._meta", "", 1) + + if module ~= fun.module then + error("unexpected _meta in module") + print(string.format("fn_xform module: %s -> %s", fun.module, module)) + end + + -- remove the API prefix from the left aligned function name + -- this will cascade into fn_helptag_fmt, which will apply the module prefix anyway + local name, replaced = fun.name:gsub("^" .. module .. "%.", "", 1) + if (replaced ~= 1) then + error(string.format("function name does not start with module: %s", vim.inspect(fun))) + end + + print(string.format("fn_xform name: %s -> %s", fun.name, name)) + + fun.module = module + fun.name = name end - return fun.name .. fn_sfx end, } } diff --git a/scripts/help-update.sh b/scripts/help-update.sh index 7fe52a263f2..5326b7fda10 100755 --- a/scripts/help-update.sh +++ b/scripts/help-update.sh @@ -37,7 +37,7 @@ sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/DEFAULT_ON_ATTACH.lua # help human echo > /tmp/DEFAULT_ON_ATTACH.help -sed -E "s/^ *vim.keymap.set\(\"n\", \"(.*)\",.*api(.*),.*opts\(\"(.*)\".*$/'\`\1\`' '\3' '|nvim-tree-api\2()|'/g +sed -E "s/^ *vim.keymap.set\(\"n\", \"(.*)\",.*api(.*),.*opts\(\"(.*)\".*$/'\`\1\`' '\3' '|nvim_tree.api\2()|'/g " /tmp/DEFAULT_ON_ATTACH.lua | while read -r line do eval "printf '%-17.17s %-26.26s %s\n' ${line}" >> /tmp/DEFAULT_ON_ATTACH.help @@ -47,3 +47,6 @@ begin="Show the mappings:" end="======" sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/DEFAULT_ON_ATTACH.help }; /${end}/p; d; }" doc/nvim-tree-lua.txt + +# TODO #3088 remove once all api references have been updated +sed -i -e "s/nvim\-tree\-api\.tree\./nvim_tree.api.tree./g" doc/nvim-tree-lua.txt diff --git a/scripts/luals-check.sh b/scripts/luals-check.sh index 5c611b18b98..d145beb046a 100755 --- a/scripts/luals-check.sh +++ b/scripts/luals-check.sh @@ -21,6 +21,8 @@ mkdir "${DIR_OUT}" case "${1}" in "codestyle-check") + echo "TODO #3088 skipping codestyle-check until api.lua refactor is complete" + exit 0 jq \ '.diagnostics.neededFileStatus[] = "None" | .diagnostics.neededFileStatus."codestyle-check" = "Any"' \ "${PWD}/.luarc.json" > "${FILE_LUARC}"