diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 07118f01c2d..aa7262123c4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -105,6 +105,7 @@ Suppressions are permitted only in the following cases: - Backwards compatibility shims - neovim API metadata incorrect, awaiting upstream fix - classic class framework +- `gen_vimdoc_config.lua` help generator as it requires neovim source # Backwards Compatibility diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 6aadaf3dc27..f85dab8e72c 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -1,9 +1,9 @@ -*nvim-tree.lua* A File Explorer For Neovim Written In Lua +*nvim-tree* A File Explorer For Neovim Written In Lua Author: Yazdani Kiyan ============================================================================== -CONTENTS *nvim-tree* +CONTENTS 1. Introduction |nvim-tree-introduction| 2. Quickstart |nvim-tree-quickstart| @@ -949,6 +949,7 @@ Whether to show the destination of the symlink. Highlighting and icons for the nodes, in increasing order of precedence. Uses strings to specify builtin decorators otherwise specify your `nvim_tree.api.decorator.UserDecorator` class. +See |nvim-tree-decorators|, |nvim-tree-api.decorator| Type: `nvim_tree.api.decorator.Name[]`, Default: >lua { "Git", @@ -2955,13 +2956,13 @@ Decorators may: - Set highlight group for the name or icons - Override node icon +See |nvim-tree-api.decorator| + Create a `nvim_tree.api.decorator.UserDecorator` class and register it with precedence via |nvim-tree.renderer.decorators| See |nvim-tree-decorator-example| -See `nvim-tree/_meta/api_decorator.lua` for full class documentation. - ============================================================================== 11.1. DECORATOR EXAMPLE *nvim-tree-decorator-example* @@ -3444,5 +3445,986 @@ highlight group is not, hard linking as follows: > |nvim-tree-api.tree.winid()| ============================================================================== +Class: Config *nvim-tree-config* + +*nvim_tree.Config* + TODO #2934 brief and some links + + Fields: ~ + • {on_attach}? (`string|(fun(bufnr: integer))`) Runs when + creating the nvim-tree buffer. Use this to + set your |nvim-tree-mappings|. When + `on_attach` is not a function, + |nvim-tree-mappings-default| will be called. + • {hijack_cursor}? (`boolean`, default: `false`) Keeps the + cursor on the first letter of the filename + when moving in the tree. + • {auto_reload_on_write}? (`boolean`, default: `true`) Reloads the + explorer every time a buffer is written to. + • {disable_netrw}? (`boolean`, default: `false`) Completely + disable |netrw|, see |nvim-tree-netrw| for + details. It is strongly advised to eagerly + disable netrw, due to race conditions at vim + startup. + • {hijack_netrw}? (`boolean`, default: `true`) Hijack netrw + windows, ignored when `disable_netrw` is + `true` + • {hubwo}? (`boolean`, default: `false`) Opens in place + of the unnamed buffer if it's empty. TODO + reinstate this one when formatting is done + #2934 --@field + hijack_unnamed_buffer_when_opening? boolean + • {root_dirs}? (`string[]`) Preferred root directories. Only + relevant when + |nvim_tree.Config.UpdateFocusedFile| + {update_root} is `true` + • {prefer_startup_root}? (`boolean`, default: `false`) Prefer startup + root directory when updating root directory + of the tree. Only relevant when + |nvim_tree.Config.UpdateFocusedFile| + {update_root} is `true` + • {sync_root_with_cwd}? (`boolean`, default: `false`) Changes the + tree root directory on |DirChanged| and + refreshes the tree. + • {reload_on_bufenter}? (`boolean`, default: `false`) Automatically + reloads the tree on |BufEnter| nvim-tree. + • {respect_buf_cwd}? (`boolean`, default: `false`) Change cwd of + nvim-tree to that of new buffer's when + opening nvim-tree. + • {select_prompts}? (`boolean`, default: `false`) Use + |vim.ui.select| style prompts. Necessary when + using a UI prompt decorator such as + dressing.nvim or telescope-ui-select.nvim + • {sort}? (`nvim_tree.Config.Sort`) + |nvim_tree.Config.Sort| + • {view}? (`nvim_tree.Config.View`) + |nvim_tree.Config.View| + • {renderer}? (`nvim_tree.Config.Renderer`) + |nvim_tree.Config.Renderer| + • {hijack_directories}? (`nvim_tree.Config.HijackDirectories`) + |nvim_tree.Config.HijackDirectories| + • {update_focused_file}? (`nvim_tree.Config.UpdateFocusedFile`) + |nvim_tree.Config.UpdateFocusedFile| + • {system_open}? (`nvim_tree.Config.SystemOpen`) + |nvim_tree.Config.SystemOpen| + • {git}? (`nvim_tree.Config.Git`) + |nvim_tree.Config.Git| + • {diagnostics}? (`nvim_tree.Config.Diagnostics`) + |nvim_tree.Config.Diagnostics| + • {modified}? (`nvim_tree.Config.Modified`) + |nvim_tree.Config.Modified| + • {filters}? (`nvim_tree.Config.Filters`) + |nvim_tree.Config.Filters| + • {live_filter}? (`nvim_tree.Config.LiveFilter`) + |nvim_tree.Config.LiveFilter| + • {filesystem_watchers}? (`nvim_tree.Config.FilesystemWatchers`) + |nvim_tree.Config.FilesystemWatchers| + • {actions}? (`nvim_tree.Config.Actions`) + |nvim_tree.Config.Actions| + • {trash}? (`nvim_tree.Config.Trash`) + |nvim_tree.Config.Trash| + • {tab}? (`nvim_tree.Config.Tab`) + |nvim_tree.Config.Tab| + • {notify}? (`nvim_tree.Config.Notify`) + |nvim_tree.Config.Notify| + • {help}? (`nvim_tree.Config.Help`) + |nvim_tree.Config.Help| + • {ui}? (`nvim_tree.Config.UI`) |nvim_tree.Config.UI| + • {log}? (`nvim_tree.Config.Log`) + |nvim_tree.Config.Log| + +*nvim_tree.Config.Renderer* + TODO overview + + {root_folder_label} has 3 forms: + • `string`: |filename-modifiers| format string + • `boolean`: `true` to disable + • `fun(root_cwd: string): string`: string from root absolute path e.g. >lua + my_root_folder_label = function(path) + return ".../" .. vim.fn.fnamemodify(path, ":t") + end +< + + TODO: link to hidden display help section + *nvim_tree.Config.Renderer.HiddenDisplay* + + {hidden_display} summary of hidden files below the tree. + • `none`: disabled + • `simple`: show how many hidden files are in a folder + • `all`: show how many hidden and the number of hidden files by reason + • `fun(hidden_stats: table): string`: returns a summary + of hidden stats + + Fields: ~ + • {add_trailing}? (`boolean`, default: `false`) Appends a + trailing slash to folder and symlink folder + destination names. + • {group_empty}? (`boolean|(fun(relative_path: string): string)`, default: `false`) + Compact folders that only contain a single + folder into one node. Function variant + takes the relative path of grouped folders + and returns a string to be displayed. + • {full_name}? (`boolean`, default: `false`) Display node + whose name length is wider than the width + of nvim-tree window in floating window. + • {root_folder_label}? (`string|boolean|(fun(root_cwd: string): string)`) + (default: `":~:s?$?/..?"`) + • {indent_width}? (`integer`, default: `2`) Number of spaces + for an each tree nesting level. Minimum 1. + • {special_files}? (`string[]`, default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }`) + A list of filenames that gets highlighted + with `NvimTreeSpecialFile`. + • {hidden_display}? (`nvim_tree.Config.Renderer.HiddenDisplay`) + (default: `none`) + • {symlink_destination}? (`boolean`, default: `true`) Appends an + arrow followed by the destination of the + symlink. + • {decorators}? (`(string|nvim_tree.api.decorator.UserDecorator)[]`, default: `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) + Highlighting and icons for the nodes, in + increasing order of precedence. Strings + specify builtin decorators. + • {highlight_git}? (`nvim_tree.HighlightOption`) Enable + highlight for git attributes using + `NvimTreeGit*HL` highlight groups. Requires + |nvim-tree.git.enable| Value can be + `"none"`, `"icon"`, `"name"` or `"all"`. + Default: `"none"` @see nvim-tree.git.enable + • {highlight_diagnostics}? (`nvim_tree.HighlightOption`) Enable + highlight for diagnostics using + `NvimTreeDiagnostic*HL` highlight groups. + Requires |nvim-tree.diagnostics.enable| + Value can be `"none"`, `"icon"`, `"name"` + or `"all"`. Default: `"none"` @see + nvim-tree.diagnostics.enable + • {highlight_opened_files}? (`nvim_tree.HighlightOption`) Highlight + icons and/or names for |bufloaded()| files + using the `NvimTreeOpenedHL` highlight + group. See + |nvim-tree-api.navigate.opened.next()| and + |nvim-tree-api.navigate.opened.prev()| + Value can be `"none"`, `"icon"`, `"name"` + or `"all"`. Default: `"none"` + • {highlight_modified}? (`nvim_tree.HighlightOption`) Highlight + icons and/or names for modified files using + the `NvimTreeModifiedFile` highlight group. + Requires |nvim-tree.modified.enable| Value + can be `"none"`, `"icon"`, `"name"` or + `"all"` Default `"none"` @see + nvim-tree.modified.enable + • {highlight_hidden}? (`nvim_tree.HighlightOption`) Highlight + icons and/or names for hidden files + (dotfiles) using the `NvimTreeHiddenFileHL` + highlight group. Value can be `"none"`, + `"icon"`, `"name"` or `"all"` Default + `"none"` + • {highlight_bookmarks}? (`nvim_tree.HighlightOption`) Highlight + bookmarked using the `NvimTreeBookmarkHL` + group. Value can be `"none"`, `"icon"`, + `"name"` or `"all"` Default `"none"` + • {highlight_clipboard}? (`nvim_tree.HighlightOption`) Enable + highlight for clipboard items using the + `NvimTreeCutHL` and `NvimTreeCopiedHL` + groups. Value can be `"none"`, `"icon"`, + `"name"` or `"all"`. Default: `"name"` + • {indent_markers}? (`nvim_tree.Config.Renderer.IndentMarkers`) + Configuration options for tree indent + markers. + • {icons}? (`nvim_tree.Config.Renderer.Icons`) + Configuration options for icons. + +*nvim_tree.Config.Renderer.Icons* + + Fields: ~ + • {web_devicons}? (`nvim_tree.Config.Renderer.Icons.WebDevicons`) + Configure optional plugin + `"nvim-tree/nvim-web-devicons"` + • {git_placement}? (`nvim_tree.PlacementOption`) Git icons + placement. Default: `"before"` + • {diagnostics_placement}? (`nvim_tree.PlacementOption`) Diganostic + icon placement. Default: `"signcolumn"` @see + nvim-tree.view.signcolumn @see + nvim-tree.renderer.icons.show.diagnostics + • {modified_placement}? (`nvim_tree.PlacementOption`) Modified icon + placement. Default: `"after"` + • {hidden_placement}? (`nvim_tree.PlacementOption`) Hidden icon + placement. Default: `"after"` + • {bookmarks_placement}? (`nvim_tree.PlacementOption`) Bookmark icon + placement. Default: `"signcolumn"` @see + nvim-tree.renderer.icons.show.bookmarks + • {padding}? (`nvim_tree.Config.Renderer.Icons.Padding`) + • {symlink_arrow}? (`string`) Used as a separator between + symlinks' source and target. Default: + `" ➛ "` + • {show}? (`nvim_tree.Config.Renderer.Icons.Show`) + Configuration options for showing icon + types. Left to right order: file/folder, + git, modified, hidden, diagnostics, + bookmarked. + • {glyphs}? (`nvim_tree.Config.Renderer.Icons.Glyphs`) + Configuration options for icon glyphs. NOTE: + Do not set any glyphs to more than two + characters if it's going to appear in the + signcolumn. + +*nvim_tree.Config.Renderer.Icons.Glyphs* + Glyphs that appear in the sign column must have length <= 2 + + Glyphs defined elsewhere: + • |nvim_tree.Config.Diagnostics.Icons| + • |nvim_tree.Config.Renderer.IndentMarkers.Icons| + + Fields: ~ + • {default}? (`string`, default: `` ) Files, overridden by + |nvim_tree.Config.Renderer.Icons| {web_devicons} + • {symlink}? (`string`) (default: `` ) + • {bookmark}? (`string`) (default: `󰆤` ) + • {modified}? (`string`) (default: `●` ) + • {hidden}? (`string`) (default: `󰜌` ) + • {folder}? (`table`) Overridden by |nvim_tree.Config.Renderer.Icons| + {web_devicons} + • {arrow_closed}? (`string`) (default: left arrow) + • {arrow_open}? (`string`) (default: down arrow) + • {default}? (`string`) (default: `` ) + • {open}? (`string`) (default: `` ) + • {empty}? (`string`) (default: `` ) + • {empty_open}? (`string`) (default: `` ) + • {symlink}? (`string`) (default: `` ) + • {symlink_open}? (`string`) (default: `` ) + • {git}? (`table`) Git status on files and directories. + • {unstaged}? (`string`) (default: `✗` ) + • {staged}? (`string`) (default: `✓` ) + • {unmerged}? (`string`) (default: `` ) + • {renamed}? (`string`) (default: `➜` ) + • {untracked}? (`string`) (default: `★` ) + • {deleted}? (`string`) (default: `` ) + • {ignored}? (`string`) (default: `◌` ) + +*nvim_tree.Config.Renderer.Icons.Padding* + + Fields: ~ + • {icon}? (`string`) Inserted between icon and filename. + Default: `" "` + • {folder_arrow}? (`string`) Inserted between folder arrow icon and + file/folder icon. Default: `" "` + +*nvim_tree.Config.Renderer.Icons.Show* + Control which icons are displayed. + + Left to right ordered: + • {file} + • {folder} + • {git} + • {modified} + • {hidden} + • {diagnostics} + • {bookmarks} + + Fields: ~ + • {file}? (`boolean`, default: `true`) Before file name. + • {folder}? (`boolean`, default: `true`) Before folder name. + • {folder_arrow}? (`boolean`, default: `true`) Show a small arrow + before the folder node. Arrow will be a part of the + node when using |nvim_tree.Config.Renderer| + {indent_markers}. + • {git}? (`boolean`, default: `true`) Icons: + |nvim_tree.Config.Renderer.Icons.Glyphs.Git|. + Location: |nvim_tree.Config.Renderer.Icons| + {git_placement}. Requires |nvim_tree.Config.Git| + {enable}. + • {modified}? (`boolean`, default: `true`) Location: + |nvim_tree.Config.Renderer.Icons| + {modified_placement}. Requires + |nvim_tree.Config.Modified| {enable}. + • {hidden}? (`boolean`, default: `false`) Location: + |nvim_tree.Config.Renderer.Icons| {hidden_placement}. + • {diagnostics}? (`boolean`, default: `true`) Icons: + |nvim_tree.Config.Diagnostics.Icons| Location: + |nvim_tree.Config.Renderer.Icons| + {diagnostics_placement}. Requires + |nvim_tree.Config.Diagnostics| {enable}. + • {bookmarks}? (`boolean`, default: `true`) Location: + |nvim_tree.Config.Renderer.Icons| + {bookmarks_placement}. + +*nvim_tree.Config.Renderer.Icons.WebDevicons* + + Fields: ~ + • {file}? (`nvim_tree.Config.Renderer.Icons.WebDevicons.File`) File + icons. + • {folder}? (`nvim_tree.Config.Renderer.Icons.WebDevicons.Folder`) + Folder icons. + +*nvim_tree.Config.Renderer.Icons.WebDevicons.File* + + Fields: ~ + • {enable}? (`boolean`) Show icons on files. Overrides + |nvim-tree.renderer.icons.glyphs.default| Default: `true` + • {color}? (`boolean`) Use icon colors for files. Overrides highlight + groups. Default: `true` + +*nvim_tree.Config.Renderer.Icons.WebDevicons.Folder* + + Fields: ~ + • {enable}? (`boolean`) Show icons on folders. Overrides + |nvim-tree.renderer.icons.glyphs.folder| Default: `false` + • {color}? (`boolean`) Use icon colors for folders. Overrides + highlight groups. Default: `true` + +*nvim_tree.Config.Renderer.IndentMarkers* + + Fields: ~ + • {enable}? (`boolean`) Display indent markers when folders are + open Default: `false` + • {inline_arrows}? (`boolean`) Display folder arrows in the same column + as indent marker when using + |renderer.icons.show.folder_arrow| Default: `true` + • {icons}? (`nvim_tree.Config.Renderer.IndentMarkers.Icons`) + Icons shown before the file/directory. Length 1. + Default: > lua { corner = "└", edge = "│", item + = "│", bottom = "─", none = " ", } + +*nvim_tree.Config.Renderer.IndentMarkers.Icons* + + Fields: ~ + • {corner}? (`string`) Default: `"└"` + • {edge}? (`string`) Default: `"│"` + • {item}? (`string`) Default: `"│"` + • {bottom}? (`string`) Default: `"─"` + • {none}? (`string`) Default: `" "` + + + +============================================================================== +Class: Config.Sort *nvim-tree-config-sort* + +*nvim_tree.Config.Sort* + Sort files within a directory. + + {sorter} *nvim_tree.Config.Sort.Sorter* + • `name` + • `case_sensitive` name + • `modification_time` + • `extension` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz` + • `suffix` uses the last e.g. `foo.tar.gz` -> `.gz` + • `filetype` |filetype| + + {sorter} may be a function that is passed a list of |nvim_tree.api.Node| + to be sorted in place e.g. >lua + + ---Sort by name length + ---@param nodes nvim_tree.api.Node[] + ---@return nvim_tree.Config.Sort.Sorter? + local sorter = function(nodes) + table.sort(nodes, function(a, b) + return #a.name < #b.name + end) + end +< + + {sorter} may be a function that returns a |nvim_tree.Config.Sort.Sorter| + + Fields: ~ + • {sorter}? (`nvim_tree.Config.Sort.Sorter|(fun(nodes: nvim_tree.api.Node[]): nvim_tree.Config.Sort.Sorter?)`) + (default: `name`) + • {folders_first}? (`boolean`, default: `true`) Sort folders before + files. Has no effect when {sorter} is a function. + • {files_first}? (`boolean`, default: `false`) Sort files before + folders. Has no effect when {sorter} is a function. + Overrides {folders_first}. + + + +============================================================================== +Class: Config.View *nvim-tree-config-view* + +*nvim_tree.Config.View* + Configures the dimensions and appearance of the nvim-tree window. + + The window is "docked" at the left by default, however may be configured + to float: |nvim_tree.Config.View.Float| + + {width} can be a |nvim_tree.Config.View.WidthSpec| for simple static + control or a |nvim_tree.Config.View.Width| for fully dynamic control based + on longest line. + + *nvim_tree.Config.View.WidthSpec* + • string: `x%` string e.g. `30%` + • integer: number of columns + • function: returns one of the above + + Fields: ~ + • {centralize_selection}? (`boolean`, default: `false`) When + entering nvim-tree, reposition the + view so that the current node is + initially centralized, see |zz|. + • {cursorline}? (`boolean`, default: `true`) + |cursorline| + • {cursorlineopt}? (`string`, default: `both`) + |cursorlineopt| + • {debounce_delay}? (`integer`, default: `15`) Idle + milliseconds before some reload / + refresh operations. Increase if you + experience performance issues around + screen refresh. + • {side}? (`"left"|"right"`) (default: `left`) + • {preserve_window_proportions}? (`boolean`, default: `false`) + Preserves window proportions when + opening a file. If `false`, the height + and width of windows other than + nvim-tree will be equalized. + • {number}? (`boolean`, default: `false`) |number| + • {relativenumber}? (`boolean`, default: `false`) + |relativenumber| + • {signcolumn}? (`"yes"|"auto"|"no"`, default: `yes`) + |signcolumn| + • {width}? (`nvim_tree.Config.View.WidthSpec|nvim_tree.Config.View.Width`) + (default: `30`) + • {float}? (`nvim_tree.Config.View.Float`) + |nvim_tree.Config.View.Float| + +*nvim_tree.Config.View.Float* + Configure floating window behaviour + + |vim.api.keyset.win_config| {open_win_config} is passed directly to + |nvim_open_win|, default: >lua + { + relative = "editor", + border = "rounded", + width = 30, + height = 30, + row = 1, + col = 1, + } +< + + Fields: ~ + • {enable}? (`boolean`) (default: `false`) + • {quit_on_focus_loss}? (`boolean`, default: `true`) Close the floating + window when it loses focus. + • {open_win_config}? (`vim.api.keyset.win_config|(fun(): vim.api.keyset.win_config)`) + (default: above) + +*nvim_tree.Config.View.Width* + Configure dynamic width based on longest line. + + Fields: ~ + • {min}? (`nvim_tree.Config.View.WidthSpec`) (default: `30`) + • {max}? (`nvim_tree.Config.View.WidthSpec`, default: `-1`) + -1 for unbounded. + • {lines_excluded}? (`("root")[]`, default: `{ "root" }`) Exclude these + lines when computing width. + • {padding}? (`nvim_tree.Config.View.WidthSpec`, default: `1`) + Extra padding to the right. + + + +============================================================================== +Class: Config.HijackDirectories *nvim-tree-config-hijack-directories* + +*nvim_tree.Config.HijackDirectories* + Hijack directory buffers by replacing the directory buffer with the tree. + + Disable this option if you use vim-dirvish or dirbuf.nvim. + + If |nvim_tree.Config| {hijack_netrw} and {disable_netrw} are `false` this + feature will be disabled. + + Fields: ~ + • {enable}? (`boolean`) (default: `true`) + • {auto_open}? (`boolean`, default: `true`) Open if the tree was + previously closed. + + + +============================================================================== +Class: Config.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.Config.UpdateFocusedFile.UpdateRoot* + Update the root directory of the tree if the file is not under the current + root directory. + + Prefers vim's cwd and |nvim_tree.Config| {root_dirs}, falling back to the + directory containing the file. + + Only relevant when |nvim_tree.Config.UpdateFocusedFile| {enable} is `true` + + Fields: ~ + • {enable}? (`boolean`) (default: `false`) + • {ignore_list}? (`string[]`, default: `{}`) List of buffer names and + filetypes that will not update the root dir of the + tree if the file isn't found under the current root + directory. + + + +============================================================================== +Class: Config.SystemOpen *nvim-tree-config-system-open* + +*nvim_tree.Config.SystemOpen* + Open files or directories via the OS. + + Neovim: + • `>=` 0.10 uses |vim.ui.open| unless {cmd} is specified + • `<` 0.10 calls external {cmd}: + • UNIX: `xdg-open` + • macOS: `open` + • Windows: `cmd` + + Fields: ~ + • {cmd}? (`string`, default: `xdg-open`, `open` or `cmd`) The open + command itself + • {args}? (`string[]`, default: `{}` or `{ "/c", "start", '""' }` on + windows) Optional argument list. Leave empty for OS specific + default. + + + +============================================================================== +Class: Config.Git *nvim-tree-config-git* + +*nvim_tree.Config.Git* + Git operations are run in the background thus status may not immediately + appear. + + Processes will be killed if they exceed {timeout}ms. Git integration will + be disabled following 5 timeouts and you will be notified. + + Git integration may be disabled for git top-level directories via + {disable_for_dirs}: + • A list of relative paths evaluated with |fnamemodify| `:p` OR + • A function that is passed an absolute path and returns `true` to disable + + Fields: ~ + • {enable}? (`boolean`) (default: `true`) + • {show_on_dirs}? (`boolean`, default: `true`) Show status icons + of children when directory itself has no status + icon + • {show_on_open_dirs}? (`boolean`, default: `true`) Show status icons + of children on directories that are open. Only + relevant when {show_on_dirs} is `true`. + • {disable_for_dirs}? (`string[]|(fun(path: string): boolean)`, + default: `{}`) Disable for top level paths. + • {timeout}? (`integer`, default: `400`) `git` processes + timeout milliseconds. + • {cygwin_support}? (`boolean`, default: `false`) Use `cygpath` if + available to resolve paths for git. + + + +============================================================================== +Class: Config.Diagnostics *nvim-tree-config-diagnostics* + +*nvim_tree.Config.Diagnostics* + Integrate with |lsp| or COC diagnostics. + + Fields: ~ + • {enable}? (`boolean`) (default: `false`) + • {debounce_delay}? (`integer`, default: `500`) Idle milliseconds + between diagnostic event and tree update. + • {show_on_dirs}? (`boolean`, default: `false`) Show diagnostic + icons on parent directories. + • {show_on_open_dirs}? (`boolean`, default: `true`) Show diagnostics + icons on directories that are open. Only + relevant when {show_on_dirs} is `true`. + • {diagnostic_opts}? (`boolean`, default: `false`) Global + |vim.diagnostic.Opts| overrides {severity} and + {icons} + • {severity}? (`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: `` ) + + + +============================================================================== +Class: Config.Modified *nvim-tree-config-modified* + +*nvim_tree.Config.Modified* + Indicate which files have unsaved modification. To see modified status in + the tree you will need to set: + • |nvim_tree.Config.Renderer.Icons.Show| {modified} to `true` OR + • |nvim_tree.Config.Renderer| {highlight_modified} to `true` + + Fields: ~ + • {enable}? (`boolean`) (default: `false`) + • {show_on_dirs}? (`boolean`, default: `true`) Show modified + indication on directory whose children are + modified. + • {show_on_open_dirs}? (`boolean`, default: `false`) Show modified + indication on open directories. Only relevant + when {show_on_dirs} is `true`. + + + +============================================================================== +Class: Config.Filters *nvim-tree-config-filters* + + +Filters may be applied to the tree to exlude the display of file and directories. + +Multiple filters may be applied at once. + +Filters can be set at startup and toggled live via API with default keymappings. + +`I` {git_ignored} |nvim-tree-api.tree.toggle_gitignore_filter()| + Ignore files based on `.gitignore`. + Requires |nvim_tree.Config.Git| {enable} + +`H` {dotfiles} |nvim-tree-api.tree.toggle_hidden_filter()| + Filter dotfiles: files starting with a `.` + +`C` {git_clean} |nvim-tree-api.tree.toggle_git_clean_filter()| + Filter files with no git status. + Git ignored files will not be filtered when {git_ignored}, as they are + effectively dirty. + +`B` {no_buffer} |nvim-tree-api.tree.toggle_no_buffer_filter()| + Filter files that have no |buflisted()| buffer. + For performance reasons this may not immediately update on buffer delete/wipe. + A reload or filesystem event will result in an update. + +`M` {no_bookmark} |nvim-tree-api.tree.toggle_no_bookmark_filter()| + Filter files that are not bookmarked. + Enabling this is not useful as there is no means yet to persist bookmarks. + +`U` {custom} |nvim-tree-api.tree.toggle_custom_filter()| + Disable file/directory names via: + a list of backslash escaped |vim.regex| strings e.g. `"^\\.git""` + OR a function passed the absolute path of the directory. + +All filters including live filter may be disabled via {enable} and toggled +with |nvim-tree-api.tree.toggle_enable_filters()| + +Files/directories may be {exclude}d from filtering: they will always be shown, +overriding {git_ignored}, {dotfiles} and {custom} + + +*nvim_tree.Config.Filters* + + Fields: ~ + • {enable}? (`boolean`, default: `true`) Enable all filters. + • {git_ignored}? (`boolean`) (default: `true`) + • {dotfiles}? (`boolean`) (default: `false`) + • {git_clean}? (`boolean`) (default: `false`) + • {no_buffer}? (`boolean`) (default: `false`) + • {no_bookmark}? (`boolean`) (default: `false`) + • {custom}? (`string[]|(fun(absolute_path: string): boolean)`) + (default: `{}`) + • {exclude}? (`string[]`) (default: `{}`) + + + +============================================================================== +Class: Config.LiveFilter *nvim-tree-config-live-filter* + +*nvim_tree.Config.LiveFilter* + Live filter allows you to filter the tree nodes dynamically, based on + regex matching, see |vim.regex| + + This feature is bound to the `f` key by default. The filter can be cleared + with the `F` key by default. + + Fields: ~ + • {prefix}? (`string`, default: `[FILTER]: `) Prefix of + the filter displayed in the buffer. + • {always_show_folders}? (`boolean`, default: `true`) Whether to filter + folders or not. + + + +============================================================================== +Class: Config.FilesystemWatchers *nvim-tree-config-filesystem-watchers* + +*nvim_tree.Config.FilesystemWatchers* + Use file system watchers (libuv fs_event) to monitor the filesystem for + changes and update the tree. + + With this feature, the tree will be partially updated on specific + directory changes, resulting in better performance. + + Watchers may be disabled for absolute directory paths via {ignore_dirs}. + • A list of |vim regex| to match a path, backslash escaped e.g. + `"my-proj/\\.build$"` OR + • A function that is passed an absolute path and returns `true` to disable + This may be useful when a path is not in `.gitignore` or git integration + is disabled. + + 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. + + + +============================================================================== +Class: Config.Actions *nvim-tree-config-actions* + +*nvim_tree.Config.Actions* + + Fields: ~ + • {use_system_clipboard}? (`boolean`, default: `true`) Use the system + clipboard for copy/paste. Copied text will be + stored in registers `+` (system), otherwise, + it will be stored in `1` and `"` + • {change_dir}? (`nvim_tree.Config.Actions.ChangeDir`) + |nvim_tree.Config.Actions.ChangeDir| + • {expand_all}? (`nvim_tree.Config.Actions.ExpandAll`) + |nvim_tree.Config.Actions.ExpandAll| + • {file_popup}? (`nvim_tree.Config.Actions.FilePopup`) + |nvim_tree.Config.Actions.FilePopup| + • {open_file}? (`nvim_tree.Config.Actions.OpenFile`) + |nvim_tree.Config.Actions.OpenFile| + • {remove_file}? (`nvim_tree.Config.Actions.RemoveFile`) + |nvim_tree.Config.Actions.RemoveFile| + +*nvim_tree.Config.Actions.ChangeDir* + vim |current-directory| behaviour + + Fields: ~ + • {enable}? (`boolean`, default: `true`) Change the working + directory when changing directories in the tree + • {global}? (`boolean`, default: `false`) Use `:cd` instead + of `:lcd` when changing directories. + • {restrict_above_cwd}? (`boolean`, default: `false`) Restrict changing + to a directory above the global cwd. + +*nvim_tree.Config.Actions.ExpandAll* + Configure |nvim-tree-api.tree.expand_all()| and + |nvim-tree-api.node.expand()| + + Fields: ~ + • {max_folder_discovery}? (`integer`, default: `300`) Limit the number + of folders being explored when expanding + every folders. Avoids hanging neovim when + running this action on very large folders. + • {exclude}? (`string[]`, default: `{}`) A list of + directories that should not be expanded + automatically e.g + `{ ".git", "target", "build" }` + +*nvim_tree.Config.Actions.FilePopup* + {file_popup} floating window. + + |vim.api.keyset.win_config| {open_win_config} is passed directly to + |nvim_open_win|, default: >lua + { + col = 1, + row = 1, + relative = "cursor", + border = "shadow", + style = "minimal", + } +< + + You shouldn't define |vim.api.keyset.win_config| {width} and {height} + values here. They will be overridden to fit the file_popup content. + + Fields: ~ + • {open_win_config}? (`vim.api.keyset.win_config`) (default: above) + +*nvim_tree.Config.Actions.OpenFile* + Opening files. + + Fields: ~ + • {quit_on_open}? (`boolean`, default: `false`) Closes the explorer + when opening a file + • {eject}? (`boolean`, default: `true`) Prevent new opened file + from opening in the same window as the tree. + • {resize_window}? (`boolean`, default: `true`) Resizes the tree when + opening a file + • {window_picker}? (`nvim_tree.Config.Actions.OpenFile.WindowPicker`) + |nvim_tree.Config.Actions.OpenFile.WindowPicker| + +*nvim_tree.Config.Actions.OpenFile.WindowPicker* + A window picker will be shown when there are multiple windows available to + open a file. It will show a single character identifier in each window's + status line. + + When it is not enabled the file will open in the window from which you + last opened the tree, obeying {exclude} + + You may define a function that should return the window id that will open + the node, or `nil` if an invalid window is picked or user cancelled the + action. The picker may create a new window. + + Fields: ~ + • {enable}? (`boolean`) (default: `true`) + • {picker}? (`string|(fun(): integer)`, default: `default`) Change the + default window picker: string `default` or a function. + • {chars}? (`string`, default: + `"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"`) Identifier + characters to use. + • {exclude}? (`nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude`) + |nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude| + +*nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude* + Tables of buffer option names mapped to a list of option values. Windows + containing matching buffers will not be: + • available when using a window picker + • selected when not using a window picker + + Fields: ~ + • {filetype}? (`string[]`) (default: + `{ "notify", "lazy", "qf", "diff", "fugitive", "fugitiveblame", }`) + • {buftype}? (`string[]`) (default: + `{ "nofile", "terminal", "help", }`) + +*nvim_tree.Config.Actions.RemoveFile* + Removing files. + + Fields: ~ + • {close_window}? (`boolean`, default: `true`) Close any window that + displays a file when removing that file from the + tree. + + + +============================================================================== +Class: Config.Trash *nvim-tree-config-trash* + +*nvim_tree.Config.Trash* + Files may be trashed via an external command that must be installed on + your system. + • linux: `gio trash`, from linux package `glib2` + • macOS: `trash`, from homebrew package `trash` + • windows: `trash`, requires `trash-cli` or similar + + Fields: ~ + • {cmd}? (`string`, default: `gio trash` or `trash`) External command. + + + +============================================================================== +Class: Config.Tab *nvim-tree-config-tab* + +*nvim_tree.Config.Tab* + + Fields: ~ + • {sync}? (`nvim_tree.Config.Tab.Sync`) |nvim_tree.Config.Tab.Sync| + +*nvim_tree.Config.Tab.Sync* + Sync nvim-tree across tabs. + + Fields: ~ + • {open}? (`boolean`, default: `false`) Opens the tree automatically + when switching tabpage or opening a new tabpage if the tree + was previously open. + • {close}? (`boolean`, default: `false`) Closes the tree across all + tabpages when the tree is closed. + • {ignore}? (`string[]`, default: `{}`) List of filetypes or buffer + names on new tab that will prevent `open` and `close` + + + +============================================================================== +Class: Config.Notify *nvim-tree-config-notify* + +*nvim_tree.Config.Notify* + nvim-tree notifications levels: + • ERROR: hard errors e.g. failure to read from the file system. + • WARN: non-fatal errors e.g. unable to system open a file. + • INFO: information only e.g. file copy path confirmation. + • DEBUG: information for troubleshooting, e.g. failures in some window + closing operations. + + Fields: ~ + • {threshold}? (`vim.log.levels`, default: `vim.log.levels.INFO`) + Specify minimum notification level + • {absolute_path}? (`boolean`, default: `true`) Use absolute paths in + FS action notifications, otherwise item names. + + + +============================================================================== +Class: Config.Help *nvim-tree-config-help* + +*nvim_tree.Config.Help* + Configure help window, default mapping `g?` + + *nvim_tree.Config.Help.SortBy* + • `key`: alphabetically by keymap + • `desc`: alphabetically by description + + Fields: ~ + • {sort_by}? (`nvim_tree.Config.Help.SortBy`, default: `key`) + |nvim_tree.Config.Help.SortBy| + + + +============================================================================== +Class: Config.UI *nvim-tree-config-ui* + +*nvim_tree.Config.UI* + + Fields: ~ + • {confirm}? (`nvim_tree.Config.UI.Confirm`) + |nvim_tree.Config.UI.Confirm| + +*nvim_tree.Config.UI.Confirm* + Confirmation prompts. - vim:tw=78:ts=4:sw=4:et:ft=help:norl: + 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` + + + +============================================================================== +Class: Config.Log *nvim-tree-config-log* + +*nvim_tree.Config.Log* + Log to a file `nvim-tree.log` in |stdpath| `log`, usually + `${XDG_STATE_HOME}/nvim` + + Fields: ~ + • {enable}? (`boolean`) (default: `false`) + • {truncate}? (`boolean`, default: `false`) Remove existing log file at + startup. + • {types}? (`nvim_tree.Config.Log.Types`) + |nvim_tree.Config.Log.Types| + +*nvim_tree.Config.Log.Types* + Specify which information to log. + + Fields: ~ + • {all}? (`boolean`, default: `false`) Everything. + • {profile}? (`boolean`, default: `false`) Timing of some + operations. + • {config}? (`boolean`, default: `false`) Options and mappings, at + startup. + • {copy_paste}? (`boolean`, default: `false`) File copy and paste + actions. + • {dev}? (`boolean`, default: `false`) Used for local + development only. Not useful for users. + • {diagnostics}? (`boolean`, default: `false`) LSP and COC processing, + verbose. + • {git}? (`boolean`, default: `false`) Git processing, verbose. + • {watcher}? (`boolean`, default: `false`) + |nvim_tree.Config.FilesystemWatchers| processing, + verbose. + + + + vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: diff --git a/lua/nvim-tree.lua b/lua/nvim-tree.lua index dc0178b4a18..d8ec57270a1 100644 --- a/lua/nvim-tree.lua +++ b/lua/nvim-tree.lua @@ -252,6 +252,7 @@ local function setup_autocommands(opts) }) end +---@type nvim_tree.Config local DEFAULT_OPTS = { -- BEGIN_DEFAULT_OPTS on_attach = "default", hijack_cursor = false, @@ -621,7 +622,7 @@ local ACCEPTED_ENUMS = { }, } ----@param conf table|nil +---@param conf? nvim_tree.Config local function validate_options(conf) local msg @@ -726,7 +727,7 @@ function M.purge_all_state() require("nvim-tree.watcher").purge_watchers() end ----@param conf table|nil +---@param conf? nvim_tree.Config function M.setup(conf) if vim.fn.has("nvim-0.9") == 0 then notify.warn("nvim-tree.lua requires Neovim 0.9 or higher") diff --git a/lua/nvim-tree/_meta/api.lua b/lua/nvim-tree/_meta/api.lua index d6847940781..fabd8e0c943 100644 --- a/lua/nvim-tree/_meta/api.lua +++ b/lua/nvim-tree/_meta/api.lua @@ -1,6 +1,59 @@ ---@meta error("Cannot require a meta file") +-- +-- API Options +-- + +---@class (exact) nvim_tree.api.TreeOpenOpts +---@field path? string root directory for the tree +---@field current_window? boolean open the tree in the current window +---@field winid? number open the tree in the specified winid, overrides current_window +---@field find_file? boolean find the current buffer +---@field update_root? boolean requires find_file, see |nvim-tree.update_focused_file.update_root| +---@field focus? boolean focus the tree when opening, default true + +---@class (exact) nvim_tree.api.TreeToggleOpts +---@field path? string root directory for the tree +---@field current_window? boolean open the tree in the current window +---@field winid? number open the tree in the specified |winid|, overrides current_window +---@field find_file? boolean find the current buffer +---@field update_root? boolean requires find_file, see |nvim-tree.update_focused_file.update_root| +---@field focus? boolean focus the tree when opening, default true + +---@class (exact) nvim_tree.api.TreeResizeOpts +---@field width? string|function|number|table new |nvim-tree.view.width| value +---@field absolute? number set the width +---@field relative? number relative width adjustment + +---@class (exact) nvim_tree.api.TreeFindFileOpts +---@field buf? string|number absolute/relative path OR bufnr to find +---@field open? boolean open the tree if necessary +---@field current_window? boolean requires open, open in the current window +---@field winid? number open the tree in the specified |winid|, overrides current_window +---@field update_root? boolean see |nvim-tree.update_focused_file.update_root| +---@field focus? boolean focus the tree + +---@class (exact) nvim_tree.api.CollapseOpts +---@field keep_buffers? boolean do not collapse nodes with open buffers + +---@class (exact) nvim_tree.api.TreeExpandOpts +---@field expand_until? (fun(expansion_count: integer, node: Node): boolean) Return true if node should be expanded. expansion_count is the total number of folders expanded. + +---@class (exact) nvim_tree.api.TreeIsVisibleOpts +---@field tabpage? number as per |nvim_get_current_tabpage()| +---@field any_tabpage? boolean visible on any tab, default false + +---@class (exact) nvim_tree.api.TreeWinIdOpts +---@field tabpage? number tabpage, 0 or nil for current, default nil + +---@class (exact) nvim_tree.api.NodeEditOpts +---@field quit_on_open? boolean quits the tree when opening the file +---@field focus? boolean keep focus in the tree when opening the file + +---@class (exact) nvim_tree.api.NodeBufferOpts +---@field force? boolean delete/wipe even if buffer is modified, default false + -- -- Nodes -- diff --git a/lua/nvim-tree/_meta/config.lua b/lua/nvim-tree/_meta/config.lua new file mode 100644 index 00000000000..c4132d0292b --- /dev/null +++ b/lua/nvim-tree/_meta/config.lua @@ -0,0 +1,365 @@ +---@meta +error("Cannot require a meta file") + +--- TODO #2934 these were not correctly generated, inline or fix +---@alias nvim_tree.PlacementOption "before"|"after"|"signcolumn"|"right_align" +---@alias nvim_tree.HighlightOption "none"|"icon"|"name"|"all" + +--- TODO #2934 brief and some links +--- +--- +---@class nvim_tree.Config +--- +---Runs when creating the nvim-tree buffer. Use this to set your [nvim-tree-mappings]. When `on_attach` is not a function, [nvim-tree-mappings-default] will be called. +---@field on_attach? string|(fun(bufnr: integer)) +--- +---Keeps the cursor on the first letter of the filename when moving in the tree. +---(default: `false`) +---@field hijack_cursor? boolean +--- +---Reloads the explorer every time a buffer is written to. +---(default: `true`) +---@field auto_reload_on_write? boolean +--- +---Completely disable [netrw], see [nvim-tree-netrw] for details. It is strongly advised to eagerly disable netrw, due to race conditions at vim startup. +---(default: `false`) +---@field disable_netrw? boolean +--- +---Hijack netrw windows, ignored when `disable_netrw` is `true` +---(default: `true`) +---@field hijack_netrw? boolean +--- +---Opens in place of the unnamed buffer if it's empty. +---(default: `false`) +---TODO reinstate this one when formatting is done #2934 +-----@field hijack_unnamed_buffer_when_opening? boolean +---@field hubwo? boolean +--- +---Preferred root directories. Only relevant when [nvim_tree.Config.UpdateFocusedFile] {update_root} is `true` +---@field root_dirs? string[] +--- +---Prefer startup root directory when updating root directory of the tree. Only relevant when [nvim_tree.Config.UpdateFocusedFile] {update_root} is `true` +---(default: `false`) +---@field prefer_startup_root? boolean +--- +---Changes the tree root directory on [DirChanged] and refreshes the tree. +---(default: `false`) +---@field sync_root_with_cwd? boolean +--- +---Automatically reloads the tree on [BufEnter] nvim-tree. +---(default: `false`) +---@field reload_on_bufenter? boolean +--- +---Change cwd of nvim-tree to that of new buffer's when opening nvim-tree. +---(default: `false`) +---@field respect_buf_cwd? boolean +--- +---Use [vim.ui.select] style prompts. Necessary when using a UI prompt decorator such as dressing.nvim or telescope-ui-select.nvim +---(default: `false`) +---@field select_prompts? boolean +--- +---[nvim_tree.Config.Sort] +---@field sort? nvim_tree.Config.Sort +--- +---[nvim_tree.Config.View] +---@field view? nvim_tree.Config.View +--- +---[nvim_tree.Config.Renderer] +---@field renderer? nvim_tree.Config.Renderer +--- +---[nvim_tree.Config.HijackDirectories] +---@field hijack_directories? nvim_tree.Config.HijackDirectories +--- +---[nvim_tree.Config.UpdateFocusedFile] +---@field update_focused_file? nvim_tree.Config.UpdateFocusedFile +--- +---[nvim_tree.Config.SystemOpen] +---@field system_open? nvim_tree.Config.SystemOpen +--- +---[nvim_tree.Config.Git] +---@field git? nvim_tree.Config.Git +--- +---[nvim_tree.Config.Diagnostics] +---@field diagnostics? nvim_tree.Config.Diagnostics +--- +---[nvim_tree.Config.Modified] +---@field modified? nvim_tree.Config.Modified +--- +---[nvim_tree.Config.Filters] +---@field filters? nvim_tree.Config.Filters +--- +---[nvim_tree.Config.LiveFilter] +---@field live_filter? nvim_tree.Config.LiveFilter +--- +---[nvim_tree.Config.FilesystemWatchers] +---@field filesystem_watchers? nvim_tree.Config.FilesystemWatchers +--- +---[nvim_tree.Config.Actions] +---@field actions? nvim_tree.Config.Actions +--- +---[nvim_tree.Config.Trash] +---@field trash? nvim_tree.Config.Trash +--- +---[nvim_tree.Config.Tab] +---@field tab? nvim_tree.Config.Tab +--- +---[nvim_tree.Config.Notify] +---@field notify? nvim_tree.Config.Notify +--- +---[nvim_tree.Config.Help] +---@field help? nvim_tree.Config.Help +--- +---[nvim_tree.Config.UI] +---@field ui? nvim_tree.Config.UI +--- +---[nvim_tree.Config.Log] +---@field log? nvim_tree.Config.Log + + +---@alias nvim_tree.Config.Renderer.HiddenDisplay "none"|"simple"|"all"|(fun(hidden_stats: table): string) + +---TODO overview +--- +---{root_folder_label} has 3 forms: +---- `string`: [filename-modifiers] format string +---- `boolean`: `true` to disable +---- `fun(root_cwd: string): string`: string from root absolute path e.g. +---```lua +---my_root_folder_label = function(path) +--- return ".../" .. vim.fn.fnamemodify(path, ":t") +---end +---``` +--- +---TODO: link to hidden display help section [nvim_tree.Config.Renderer.HiddenDisplay]() +--- +---{hidden_display} summary of hidden files below the tree. +---- `none`: disabled +---- `simple`: show how many hidden files are in a folder +---- `all`: show how many hidden and the number of hidden files by reason +---- `fun(hidden_stats: table): string`: returns a summary of hidden stats +--- +---@class nvim_tree.Config.Renderer +--- +---Appends a trailing slash to folder and symlink folder destination names. +---(default: `false`) +---@field add_trailing? boolean +--- +---Compact folders that only contain a single folder into one node. Function variant takes the relative path of grouped folders and returns a string to be displayed. +---(default: `false`) +---@field group_empty? boolean|(fun(relative_path: string): string) +--- +---Display node whose name length is wider than the width of nvim-tree window in floating window. +---(default: `false`) +---@field full_name? boolean +--- +---(default: `":~:s?$?/..?"`) +---@field root_folder_label? string|boolean|(fun(root_cwd: string): string) +--- +---Number of spaces for an each tree nesting level. Minimum 1. +---(default: `2`) +---@field indent_width? integer +--- +---A list of filenames that gets highlighted with `NvimTreeSpecialFile`. +---(default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }`) +---@field special_files? string[] +--- +---(default: `none`) +---@field hidden_display? nvim_tree.Config.Renderer.HiddenDisplay +--- +---Appends an arrow followed by the destination of the symlink. +---(default: `true`) +---@field symlink_destination? boolean +--- +---Highlighting and icons for the nodes, in increasing order of precedence. Strings specify builtin decorators. +---(default: `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) +---@field decorators? (string|nvim_tree.api.decorator.UserDecorator)[] +--- +---@field highlight_git? nvim_tree.HighlightOption Enable highlight for git attributes using `NvimTreeGit*HL` highlight groups. Requires |nvim-tree.git.enable| Value can be `"none"`, `"icon"`, `"name"` or `"all"`. Default: `"none"` @see nvim-tree.git.enable +--- +--- +---@field highlight_diagnostics? nvim_tree.HighlightOption Enable highlight for diagnostics using `NvimTreeDiagnostic*HL` highlight groups. Requires |nvim-tree.diagnostics.enable| Value can be `"none"`, `"icon"`, `"name"` or `"all"`. Default: `"none"` @see nvim-tree.diagnostics.enable +--- +--- +---@field highlight_opened_files? nvim_tree.HighlightOption Highlight icons and/or names for |bufloaded()| files using the `NvimTreeOpenedHL` highlight group. See |nvim-tree-api.navigate.opened.next()| and |nvim-tree-api.navigate.opened.prev()| Value can be `"none"`, `"icon"`, `"name"` or `"all"`. Default: `"none"` +--- +--- +---@field highlight_modified? nvim_tree.HighlightOption Highlight icons and/or names for modified files using the `NvimTreeModifiedFile` highlight group. Requires |nvim-tree.modified.enable| Value can be `"none"`, `"icon"`, `"name"` or `"all"` Default `"none"` @see nvim-tree.modified.enable +--- +--- +---@field highlight_hidden? nvim_tree.HighlightOption Highlight icons and/or names for hidden files (dotfiles) using the `NvimTreeHiddenFileHL` highlight group. Value can be `"none"`, `"icon"`, `"name"` or `"all"` Default `"none"` +--- +--- +---@field highlight_bookmarks? nvim_tree.HighlightOption Highlight bookmarked using the `NvimTreeBookmarkHL` group. Value can be `"none"`, `"icon"`, `"name"` or `"all"` Default `"none"` +--- +--- +---@field highlight_clipboard? nvim_tree.HighlightOption Enable highlight for clipboard items using the `NvimTreeCutHL` and `NvimTreeCopiedHL` groups. Value can be `"none"`, `"icon"`, `"name"` or `"all"`. Default: `"name"` +--- +--- +---@field indent_markers? nvim_tree.Config.Renderer.IndentMarkers Configuration options for tree indent markers. +--- +--- +---@field icons? nvim_tree.Config.Renderer.Icons Configuration options for icons. + + +---@class nvim_tree.Config.Renderer.IndentMarkers +---@field enable? boolean Display indent markers when folders are open Default: `false` +---@field inline_arrows? boolean Display folder arrows in the same column as indent marker when using |renderer.icons.show.folder_arrow| Default: `true` +---@field icons? nvim_tree.Config.Renderer.IndentMarkers.Icons Icons shown before the file/directory. Length 1. Default: > lua { corner = "└", edge = "│", item = "│", bottom = "─", none = " ", } + + +---@class nvim_tree.Config.Renderer.IndentMarkers.Icons +---@field corner? string Default: `"└"` +---@field edge? string Default: `"│"` +---@field item? string Default: `"│"` +---@field bottom? string Default: `"─"` +---@field none? string Default: `" "` + + +---@class nvim_tree.Config.Renderer.Icons Configuration options for icons. +---@field web_devicons? nvim_tree.Config.Renderer.Icons.WebDevicons Configure optional plugin `"nvim-tree/nvim-web-devicons"` +---@field git_placement? nvim_tree.PlacementOption Git icons placement. Default: `"before"` +---@field diagnostics_placement? nvim_tree.PlacementOption Diganostic icon placement. Default: `"signcolumn"` @see nvim-tree.view.signcolumn @see nvim-tree.renderer.icons.show.diagnostics +---@field modified_placement? nvim_tree.PlacementOption Modified icon placement. Default: `"after"` +---@field hidden_placement? nvim_tree.PlacementOption Hidden icon placement. Default: `"after"` +---@field bookmarks_placement? nvim_tree.PlacementOption Bookmark icon placement. Default: `"signcolumn"` @see nvim-tree.renderer.icons.show.bookmarks +---@field padding? nvim_tree.Config.Renderer.Icons.Padding +---@field symlink_arrow? string Used as a separator between symlinks' source and target. Default: `" ➛ "` +---@field show? nvim_tree.Config.Renderer.Icons.Show Configuration options for showing icon types. Left to right order: file/folder, git, modified, hidden, diagnostics, bookmarked. +---@field glyphs? nvim_tree.Config.Renderer.Icons.Glyphs Configuration options for icon glyphs. NOTE: Do not set any glyphs to more than two characters if it's going to appear in the signcolumn. + + +---@class nvim_tree.Config.Renderer.Icons.WebDevicons +---@field file? nvim_tree.Config.Renderer.Icons.WebDevicons.File File icons. +---@field folder? nvim_tree.Config.Renderer.Icons.WebDevicons.Folder Folder icons. + + +---@class nvim_tree.Config.Renderer.Icons.WebDevicons.File +---@field enable? boolean Show icons on files. Overrides |nvim-tree.renderer.icons.glyphs.default| Default: `true` +---@field color? boolean Use icon colors for files. Overrides highlight groups. Default: `true` + + +---@class nvim_tree.Config.Renderer.Icons.WebDevicons.Folder +---@field enable? boolean Show icons on folders. Overrides |nvim-tree.renderer.icons.glyphs.folder| Default: `false` +---@field color? boolean Use icon colors for folders. Overrides highlight groups. Default: `true` + + +---@class nvim_tree.Config.Renderer.Icons.Padding +---@field icon? string Inserted between icon and filename. Default: `" "` +---@field folder_arrow? string Inserted between folder arrow icon and file/folder icon. Default: `" "` + + +---Control which icons are displayed. +--- +---Left to right ordered: +---- {file} +---- {folder} +---- {git} +---- {modified} +---- {hidden} +---- {diagnostics} +---- {bookmarks} +--- +---@class nvim_tree.Config.Renderer.Icons.Show +--- +---Before file name. +---(default: `true`) +---@field file? boolean +--- +---Before folder name. +---(default: `true`) +---@field folder? boolean +--- +---Show a small arrow before the folder node. Arrow will be a part of the node when using [nvim_tree.Config.Renderer] {indent_markers}. +---(default: `true`) +---@field folder_arrow? boolean +--- +---Icons: [nvim_tree.Config.Renderer.Icons.Glyphs.Git]. +---Location: [nvim_tree.Config.Renderer.Icons] {git_placement}. +---Requires |nvim_tree.Config.Git| {enable}. +---(default: `true`) +---@field git? boolean +--- +---Location: [nvim_tree.Config.Renderer.Icons] {modified_placement}. +---Requires |nvim_tree.Config.Modified| {enable}. +---(default: `true`) +---@field modified? boolean +--- +---Location: [nvim_tree.Config.Renderer.Icons] {hidden_placement}. +---(default: `false`) +---@field hidden? boolean +--- +---Icons: [nvim_tree.Config.Diagnostics.Icons] +---Location: [nvim_tree.Config.Renderer.Icons] {diagnostics_placement}. +---Requires |nvim_tree.Config.Diagnostics| {enable}. +---(default: `true`) +---@field diagnostics? boolean +--- +---Location: [nvim_tree.Config.Renderer.Icons] {bookmarks_placement}. +---(default: `true`) +---@field bookmarks? boolean + + +---Glyphs that appear in the sign column must have length <= 2 +--- +---Glyphs defined elsewhere: +---- [nvim_tree.Config.Diagnostics.Icons] +---- [nvim_tree.Config.Renderer.IndentMarkers.Icons] +---@class nvim_tree.Config.Renderer.Icons.Glyphs +--- +---Files, overridden by [nvim_tree.Config.Renderer.Icons] {web_devicons} +---(default: `` ) +---@field default? string +--- +---(default: `` ) +---@field symlink? string +--- +---(default: `󰆤` ) +---@field bookmark? string +--- +---(default: `●` ) +---@field modified? string +--- +---(default: `󰜌` ) +---@field hidden? string +--- +---Overridden by [nvim_tree.Config.Renderer.Icons] {web_devicons} +---@field folder? nvim_tree.Config.Renderer.Icons.Glyphs.Folder +--- +---Git status on files and directories. +---@field git? nvim_tree.Config.Renderer.Icons.Glyphs.Git + +---@class nvim_tree.Config.Renderer.Icons.Glyphs.Folder +---@inlinedoc +---(default: left arrow) +---@field arrow_closed? string +---(default: down arrow) +---@field arrow_open? string +---(default: `` ) +---@field default? string +---(default: `` ) +---@field open? string +---(default: `` ) +---@field empty? string +---(default: `` ) +---@field empty_open? string +---(default: `` ) +---@field symlink? string +---(default: `` ) +---@field symlink_open? string + +---@class nvim_tree.Config.Renderer.Icons.Glyphs.Git +---@inlinedoc +---(default: `✗` ) +---@field unstaged? string +---(default: `✓` ) +---@field staged? string +---(default: `` ) +---@field unmerged? string +---(default: `➜` ) +---@field renamed? string +---(default: `★` ) +---@field untracked? string +---(default: `` ) +---@field deleted? string +---(default: `◌` ) +---@field ignored? string diff --git a/lua/nvim-tree/_meta/config/actions.lua b/lua/nvim-tree/_meta/config/actions.lua new file mode 100644 index 00000000000..3b23fe3f653 --- /dev/null +++ b/lua/nvim-tree/_meta/config/actions.lua @@ -0,0 +1,132 @@ +---@meta +error("Cannot require a meta file") + +---@class nvim_tree.Config.Actions +--- +---Use the system clipboard for copy/paste. Copied text will be stored in registers `+` (system), otherwise, it will be stored in `1` and `"` +---(default: `true`) +---@field use_system_clipboard? boolean +--- +---[nvim_tree.Config.Actions.ChangeDir] +---@field change_dir? nvim_tree.Config.Actions.ChangeDir +--- +---[nvim_tree.Config.Actions.ExpandAll] +---@field expand_all? nvim_tree.Config.Actions.ExpandAll +--- +---[nvim_tree.Config.Actions.FilePopup] +---@field file_popup? nvim_tree.Config.Actions.FilePopup +--- +---[nvim_tree.Config.Actions.OpenFile] +---@field open_file? nvim_tree.Config.Actions.OpenFile +--- +---[nvim_tree.Config.Actions.RemoveFile] +---@field remove_file? nvim_tree.Config.Actions.RemoveFile + + +--- vim [current-directory] behaviour +---@class nvim_tree.Config.Actions.ChangeDir +--- +---Change the working directory when changing directories in the tree +---(default: `true`) +---@field enable? boolean +--- +---Use `:cd` instead of `:lcd` when changing directories. +---(default: `false`) +---@field global? boolean +--- +--- Restrict changing to a directory above the global cwd. +---(default: `false`) +---@field restrict_above_cwd? boolean + + +---Configure [nvim-tree-api.tree.expand_all()] and [nvim-tree-api.node.expand()] +---@class nvim_tree.Config.Actions.ExpandAll +--- +---Limit the number of folders being explored when expanding every folders. Avoids hanging neovim when running this action on very large folders. +---(default: `300`) +---@field max_folder_discovery? integer +--- +---A list of directories that should not be expanded automatically e.g `{ ".git", "target", "build" }` +---(default: `{}`) +---@field exclude? string[] + + +---{file_popup} floating window. +--- +---[vim.api.keyset.win_config] {open_win_config} is passed directly to [nvim_open_win], default: +---```lua +---{ +--- col = 1, +--- row = 1, +--- relative = "cursor", +--- border = "shadow", +--- style = "minimal", +---} +---``` +---You shouldn't define [vim.api.keyset.win_config] {width} and {height} values here. They will be overridden to fit the file_popup content. +---@class nvim_tree.Config.Actions.FilePopup +--- +---(default: above) +---@field open_win_config? vim.api.keyset.win_config + + +---Opening files. +---@class nvim_tree.Config.Actions.OpenFile +--- +---Closes the explorer when opening a file +---(default: `false`) +---@field quit_on_open? boolean +--- +---Prevent new opened file from opening in the same window as the tree. +---(default: `true`) +---@field eject? boolean +--- +---Resizes the tree when opening a file +---(default: `true`) +---@field resize_window? boolean +--- +---[nvim_tree.Config.Actions.OpenFile.WindowPicker] +---@field window_picker? nvim_tree.Config.Actions.OpenFile.WindowPicker + + +---A window picker will be shown when there are multiple windows available to open a file. It will show a single character identifier in each window's status line. +--- +---When it is not enabled the file will open in the window from which you last opened the tree, obeying {exclude} +--- +---You may define a function that should return the window id that will open the node, or `nil` if an invalid window is picked or user cancelled the action. The picker may create a new window. +--- +---@class nvim_tree.Config.Actions.OpenFile.WindowPicker +--- +---(default: `true`) +---@field enable? boolean +--- +---Change the default window picker: string `default` or a function. +---(default: `default`) +---@field picker? string|(fun(): integer) +--- +---Identifier characters to use. +---(default: `"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"`) +---@field chars? string +--- +---[nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude] +---@field exclude? nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude + + +---Tables of buffer option names mapped to a list of option values. Windows containing matching buffers will not be: +--- - available when using a window picker +--- - selected when not using a window picker +---@class nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude +--- +---(default: `{ "notify", "lazy", "qf", "diff", "fugitive", "fugitiveblame", }`) +---@field filetype? string[] +--- +---(default: `{ "nofile", "terminal", "help", }`) +---@field buftype? string[] + + +---Removing files. +---@class nvim_tree.Config.Actions.RemoveFile +--- +---Close any window that displays a file when removing that file from the tree. +---(default: `true`) +---@field close_window? boolean diff --git a/lua/nvim-tree/_meta/config/diagnostics.lua b/lua/nvim-tree/_meta/config/diagnostics.lua new file mode 100644 index 00000000000..f15f5baee45 --- /dev/null +++ b/lua/nvim-tree/_meta/config/diagnostics.lua @@ -0,0 +1,57 @@ +---@meta +error("Cannot require a meta file") + +---Integrate with [lsp] or COC diagnostics. +--- +---@class nvim_tree.Config.Diagnostics +--- +---(default: `false`) +---@field enable? boolean +--- +---Idle milliseconds between diagnostic event and tree update. +---(default: `500`) +---@field debounce_delay? integer +--- +---Show diagnostic icons on parent directories. +---(default: `false`) +---@field show_on_dirs? boolean +--- +---Show diagnostics icons on directories that are open. Only relevant when {show_on_dirs} is `true`. +---(default: `true`) +---@field show_on_open_dirs? boolean +--- +---Global [vim.diagnostic.Opts] overrides {severity} and {icons} +---(default: `false`) +---@field diagnostic_opts? boolean +--- +---[nvim_tree.Config.Diagnostics.Severity] +---@field severity? nvim_tree.Config.Diagnostics.Severity +--- +---[nvim_tree.Config.Diagnostics.Icons] +---@field icons? nvim_tree.Config.Diagnostics.Icons + +---@class nvim_tree.Config.Diagnostics.Severity +---@inlinedoc +--- +---[vim.diagnostic.Severity] +---(default: HINT) +---@field min? vim.diagnostic.Severity +--- +---[vim.diagnostic.Severity] +---(default: ERROR) +---@field max? vim.diagnostic.Severity + +---@class nvim_tree.Config.Diagnostics.Icons +---@inlinedoc +--- +---(default: `` ) +---@field hint? string +--- +---(default: `` ) +---@field info? string +--- +---(default: `` ) +---@field warning? string +--- +---(default: `` ) +---@field error? string diff --git a/lua/nvim-tree/_meta/config/filesystem_watchers.lua b/lua/nvim-tree/_meta/config/filesystem_watchers.lua new file mode 100644 index 00000000000..85b4e807c6a --- /dev/null +++ b/lua/nvim-tree/_meta/config/filesystem_watchers.lua @@ -0,0 +1,23 @@ +---@meta +error("Cannot require a meta file") + +---Use file system watchers (libuv fs_event) to monitor the filesystem for changes and update the tree. +--- +---With this feature, the tree will be partially updated on specific directory changes, resulting in better performance. +--- +---Watchers may be disabled for absolute directory paths via {ignore_dirs}. +--- - A list of [vim regex] to match a path, backslash escaped e.g. `"my-proj/\\.build$"` OR +--- - A function that is passed an absolute path and returns `true` to disable +---This may be useful when a path is not in `.gitignore` or git integration is disabled. +---@class nvim_tree.Config.FilesystemWatchers +--- +---(default: `true`) +---@field enable? boolean +--- +---Idle milliseconds between filesystem change and tree update. +---(default: `50`) +---@field debounce_delay? integer +--- +---Disable for directories. +---(default: `{ "/.ccls-cache", "/build", "/node_modules", "/target", }`) +---@field ignore_dirs? string[]|(fun(path: string): boolean) diff --git a/lua/nvim-tree/_meta/config/filters.lua b/lua/nvim-tree/_meta/config/filters.lua new file mode 100644 index 00000000000..1d028495e56 --- /dev/null +++ b/lua/nvim-tree/_meta/config/filters.lua @@ -0,0 +1,70 @@ +---@meta +error("Cannot require a meta file") + +---@brief +---
help
+---Filters may be applied to the tree to exlude the display of file and directories.
+---
+---Multiple filters may be applied at once.
+---
+---Filters can be set at startup and toggled live via API with default keymappings.
+---
+---`I`    {git_ignored}    |nvim-tree-api.tree.toggle_gitignore_filter()|
+---   Ignore files based on `.gitignore`.
+---   Requires |nvim_tree.Config.Git| {enable}
+---
+---`H`    {dotfiles}       |nvim-tree-api.tree.toggle_hidden_filter()|
+---   Filter dotfiles: files starting with a `.`
+---
+---`C`    {git_clean}      |nvim-tree-api.tree.toggle_git_clean_filter()|
+---   Filter files with no git status.
+---   Git ignored files will not be filtered when {git_ignored}, as they are
+---   effectively dirty.
+---
+---`B`    {no_buffer}      |nvim-tree-api.tree.toggle_no_buffer_filter()|
+---   Filter files that have no |buflisted()| buffer.
+---   For performance reasons this may not immediately update on buffer delete/wipe.
+---   A reload or filesystem event will result in an update.
+---
+---`M`    {no_bookmark}    |nvim-tree-api.tree.toggle_no_bookmark_filter()|
+---   Filter files that are not bookmarked.
+---   Enabling this is not useful as there is no means yet to persist bookmarks.
+---
+---`U`    {custom}         |nvim-tree-api.tree.toggle_custom_filter()|
+---   Disable file/directory names via:
+---   a list of backslash escaped |vim.regex| strings e.g. `"^\\.git""`
+---   OR a function passed the absolute path of the directory.
+---
+---All filters including live filter may be disabled via {enable} and toggled
+---with |nvim-tree-api.tree.toggle_enable_filters()|
+---
+---Files/directories may be {exclude}d from filtering: they will always be shown,
+---overriding {git_ignored}, {dotfiles} and {custom}
+---
+ +---@class nvim_tree.Config.Filters +--- +---Enable all filters. +---(default: `true`) +---@field enable? boolean +--- +---(default: `true`) +---@field git_ignored? boolean +--- +---(default: `false`) +---@field dotfiles? boolean +--- +---(default: `false`) +---@field git_clean? boolean +--- +---(default: `false`) +---@field no_buffer? boolean +--- +---(default: `false`) +---@field no_bookmark? boolean +--- +---(default: `{}`) +---@field custom? string[]|(fun(absolute_path: string): boolean) +--- +---(default: `{}`) +---@field exclude? string[] diff --git a/lua/nvim-tree/_meta/config/git.lua b/lua/nvim-tree/_meta/config/git.lua new file mode 100644 index 00000000000..4251b211f91 --- /dev/null +++ b/lua/nvim-tree/_meta/config/git.lua @@ -0,0 +1,35 @@ +---@meta +error("Cannot require a meta file") + +---Git operations are run in the background thus status may not immediately appear. +--- +---Processes will be killed if they exceed {timeout}ms. Git integration will be disabled following 5 timeouts and you will be notified. +--- +---Git integration may be disabled for git top-level directories via {disable_for_dirs}: +--- - A list of relative paths evaluated with [fnamemodify] `:p` OR +--- - A function that is passed an absolute path and returns `true` to disable +--- +---@class nvim_tree.Config.Git +--- +---(default: `true`) +---@field enable? boolean +--- +---Show status icons of children when directory itself has no status icon +---(default: `true`) +---@field show_on_dirs? boolean +--- +---Show status icons of children on directories that are open. Only relevant when {show_on_dirs} is `true`. +---(default: `true`) +---@field show_on_open_dirs? boolean +--- +---Disable for top level paths. +---(default: `{}`) +---@field disable_for_dirs? string[]|(fun(path: string): boolean) +--- +---`git` processes timeout milliseconds. +---(default: `400`) +---@field timeout? integer +--- +---Use `cygpath` if available to resolve paths for git. +---(Default: `false`) +---@field cygwin_support? boolean diff --git a/lua/nvim-tree/_meta/config/help.lua b/lua/nvim-tree/_meta/config/help.lua new file mode 100644 index 00000000000..51e6a5d2453 --- /dev/null +++ b/lua/nvim-tree/_meta/config/help.lua @@ -0,0 +1,16 @@ +---@meta +error("Cannot require a meta file") + +---@alias nvim_tree.Config.Help.SortBy "key"|"desc" + +---Configure help window, default mapping `g?` +--- +---[nvim_tree.Config.Help.SortBy]() +---- `key`: alphabetically by keymap +---- `desc`: alphabetically by description +--- +---@class nvim_tree.Config.Help +--- +---[nvim_tree.Config.Help.SortBy] +---(default: `key`) +---@field sort_by? nvim_tree.Config.Help.SortBy diff --git a/lua/nvim-tree/_meta/config/hijack_directories.lua b/lua/nvim-tree/_meta/config/hijack_directories.lua new file mode 100644 index 00000000000..0219e858653 --- /dev/null +++ b/lua/nvim-tree/_meta/config/hijack_directories.lua @@ -0,0 +1,17 @@ +---@meta +error("Cannot require a meta file") + + +---Hijack directory buffers by replacing the directory buffer with the tree. +--- +---Disable this option if you use vim-dirvish or dirbuf.nvim. +--- +---If [nvim_tree.Config] {hijack_netrw} and {disable_netrw} are `false` this feature will be disabled. +---@class nvim_tree.Config.HijackDirectories +--- +---(default: `true`) +---@field enable? boolean +--- +---Open if the tree was previously closed. +---(default: `true`) +---@field auto_open? boolean diff --git a/lua/nvim-tree/_meta/config/live_filter.lua b/lua/nvim-tree/_meta/config/live_filter.lua new file mode 100644 index 00000000000..156e243855c --- /dev/null +++ b/lua/nvim-tree/_meta/config/live_filter.lua @@ -0,0 +1,15 @@ +---@meta +error("Cannot require a meta file") + +--- Live filter allows you to filter the tree nodes dynamically, based on regex matching, see [vim.regex] +--- +--- This feature is bound to the `f` key by default. The filter can be cleared with the `F` key by default. +---@class nvim_tree.Config.LiveFilter +--- +---Prefix of the filter displayed in the buffer. +---(default: `[FILTER]: `) +---@field prefix? string +--- +---Whether to filter folders or not. +---(default: `true`) +---@field always_show_folders? boolean diff --git a/lua/nvim-tree/_meta/config/log.lua b/lua/nvim-tree/_meta/config/log.lua new file mode 100644 index 00000000000..ee0358e2919 --- /dev/null +++ b/lua/nvim-tree/_meta/config/log.lua @@ -0,0 +1,50 @@ +---@meta +error("Cannot require a meta file") + +---Log to a file `nvim-tree.log` in [stdpath] `log`, usually `${XDG_STATE_HOME}/nvim` +---@class nvim_tree.Config.Log +--- +---(default: `false`) +---@field enable? boolean +--- +---Remove existing log file at startup. +---(default: `false`) +---@field truncate? boolean +--- +---[nvim_tree.Config.Log.Types] +---@field types? nvim_tree.Config.Log.Types + +---Specify which information to log. +---@class nvim_tree.Config.Log.Types +--- +---Everything. +---(default: `false`) +---@field all? boolean +--- +--- Timing of some operations. +---(default: `false`) +---@field profile? boolean +--- +---Options and mappings, at startup. +---(default: `false`) +---@field config? boolean +--- +---File copy and paste actions. +---(default: `false`) +---@field copy_paste? boolean +--- +---Used for local development only. Not useful for users. +---(default: `false`) +---@field dev? boolean +--- +---LSP and COC processing, verbose. +---(default: `false`) +---@field diagnostics? boolean +--- +---Git processing, verbose. +---(default: `false`) +---@field git? boolean +--- +---[nvim_tree.Config.FilesystemWatchers] processing, verbose. +---(default: `false`) +---@field watcher? boolean diff --git a/lua/nvim-tree/_meta/config/modified.lua b/lua/nvim-tree/_meta/config/modified.lua new file mode 100644 index 00000000000..b9aa02b223c --- /dev/null +++ b/lua/nvim-tree/_meta/config/modified.lua @@ -0,0 +1,19 @@ +---@meta +error("Cannot require a meta file") + +---Indicate which files have unsaved modification. +---To see modified status in the tree you will need to set: +--- - [nvim_tree.Config.Renderer.Icons.Show] {modified} to `true` OR +--- - [nvim_tree.Config.Renderer] {highlight_modified} to `true` +---@class nvim_tree.Config.Modified +--- +---(default: `false`) +---@field enable? boolean +--- +---Show modified indication on directory whose children are modified. +---(default: `true`) +---@field show_on_dirs? boolean +--- +---Show modified indication on open directories. Only relevant when {show_on_dirs} is `true`. +---(default: `false`) +---@field show_on_open_dirs? boolean diff --git a/lua/nvim-tree/_meta/config/notify.lua b/lua/nvim-tree/_meta/config/notify.lua new file mode 100644 index 00000000000..252d478ba93 --- /dev/null +++ b/lua/nvim-tree/_meta/config/notify.lua @@ -0,0 +1,18 @@ +---@meta +error("Cannot require a meta file") + +---nvim-tree notifications levels: +---- ERROR: hard errors e.g. failure to read from the file system. +---- WARN: non-fatal errors e.g. unable to system open a file. +---- INFO: information only e.g. file copy path confirmation. +---- DEBUG: information for troubleshooting, e.g. failures in some window closing operations. +--- +---@class nvim_tree.Config.Notify +--- +---Specify minimum notification level +---(Default: `vim.log.levels.INFO`) +---@field threshold? vim.log.levels +--- +---Use absolute paths in FS action notifications, otherwise item names. +---(default: `true`) +---@field absolute_path? boolean diff --git a/lua/nvim-tree/_meta/config/renderer.lua b/lua/nvim-tree/_meta/config/renderer.lua new file mode 100644 index 00000000000..4ab716dc93a --- /dev/null +++ b/lua/nvim-tree/_meta/config/renderer.lua @@ -0,0 +1,4 @@ +---@meta +error("Cannot require a meta file") + +--- TODO #2934 diff --git a/lua/nvim-tree/_meta/config/sort.lua b/lua/nvim-tree/_meta/config/sort.lua new file mode 100644 index 00000000000..2a0e0f7bc86 --- /dev/null +++ b/lua/nvim-tree/_meta/config/sort.lua @@ -0,0 +1,42 @@ +---@meta +error("Cannot require a meta file") + +---@alias nvim_tree.Config.Sort.Sorter "name"|"case_sensitive"|"modification_time"|"extension"|"suffix"|"filetype" + +---Sort files within a directory. +--- +---{sorter} [nvim_tree.Config.Sort.Sorter]() +---- `name` +---- `case_sensitive` name +---- `modification_time` +---- `extension` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz` +---- `suffix` uses the last e.g. `foo.tar.gz` -> `.gz` +---- `filetype` [filetype] +--- +---{sorter} may be a function that is passed a list of [nvim_tree.api.Node] to be sorted in place e.g. +---```lua +--- +------Sort by name length +------@param nodes nvim_tree.api.Node[] +------@return nvim_tree.Config.Sort.Sorter? +---local sorter = function(nodes) +--- table.sort(nodes, function(a, b) +--- return #a.name < #b.name +--- end) +---end +---``` +---{sorter} may be a function that returns a [nvim_tree.Config.Sort.Sorter] +--- +---@class nvim_tree.Config.Sort +--- +---(default: `name`) +---@field sorter? nvim_tree.Config.Sort.Sorter|(fun(nodes: nvim_tree.api.Node[]): nvim_tree.Config.Sort.Sorter?) +--- +---Sort folders before files. Has no effect when {sorter} is a function. +---(default: `true`) +---@field folders_first? boolean +--- +---Sort files before folders. Has no effect when {sorter} is a function. Overrides {folders_first}. +---(default: `false`) +---@field files_first? boolean +--- diff --git a/lua/nvim-tree/_meta/config/system_open.lua b/lua/nvim-tree/_meta/config/system_open.lua new file mode 100644 index 00000000000..6956b8d592b --- /dev/null +++ b/lua/nvim-tree/_meta/config/system_open.lua @@ -0,0 +1,21 @@ +---@meta +error("Cannot require a meta file") + +---Open files or directories via the OS. +--- +---Neovim: +---- `>=` 0.10 uses [vim.ui.open] unless {cmd} is specified +---- `<` 0.10 calls external {cmd}: +--- - UNIX: `xdg-open` +--- - macOS: `open` +--- - Windows: `cmd` +--- +---@class nvim_tree.Config.SystemOpen +--- +---The open command itself +---(default: `xdg-open`, `open` or `cmd`) +---@field cmd? string +--- +---Optional argument list. Leave empty for OS specific default. +---(default: `{}` or `{ "/c", "start", '""' }` on windows) +---@field args? string[] diff --git a/lua/nvim-tree/_meta/config/tab.lua b/lua/nvim-tree/_meta/config/tab.lua new file mode 100644 index 00000000000..0e56420f51a --- /dev/null +++ b/lua/nvim-tree/_meta/config/tab.lua @@ -0,0 +1,27 @@ +---@meta +error("Cannot require a meta file") + +---@class nvim_tree.Config.Tab +--- +---[nvim_tree.Config.Tab.Sync] +---@field sync? nvim_tree.Config.Tab.Sync + +-- +-- Tab.Sync +-- + +---Sync nvim-tree across tabs. +---@class nvim_tree.Config.Tab.Sync +--- +---Opens the tree automatically when switching tabpage or opening a new tabpage if the tree was previously open. +---(default: `false`) +---@field open? boolean +--- +---Closes the tree across all tabpages when the tree is closed. +---(default: `false`) +---@field close? boolean +--- +--- +---List of filetypes or buffer names on new tab that will prevent `open` and `close` +---(default: `{}`) +---@field ignore? string[] diff --git a/lua/nvim-tree/_meta/config/trash.lua b/lua/nvim-tree/_meta/config/trash.lua new file mode 100644 index 00000000000..37582670249 --- /dev/null +++ b/lua/nvim-tree/_meta/config/trash.lua @@ -0,0 +1,12 @@ +---@meta +error("Cannot require a meta file") + +---Files may be trashed via an external command that must be installed on your system. +--- - linux: `gio trash`, from linux package `glib2` +--- - macOS: `trash`, from homebrew package `trash` +--- - windows: `trash`, requires `trash-cli` or similar +---@class nvim_tree.Config.Trash +--- +---External command. +---(default: `gio trash` or `trash`) +---@field cmd? string diff --git a/lua/nvim-tree/_meta/config/ui.lua b/lua/nvim-tree/_meta/config/ui.lua new file mode 100644 index 00000000000..438e46fad17 --- /dev/null +++ b/lua/nvim-tree/_meta/config/ui.lua @@ -0,0 +1,26 @@ +---@meta +error("Cannot require a meta file") + +---@class nvim_tree.Config.UI +--- +---[nvim_tree.Config.UI.Confirm] +---@field confirm? nvim_tree.Config.UI.Confirm + +-- +-- UI.Confirm +-- + +---Confirmation prompts. +---@class nvim_tree.Config.UI.Confirm +--- +---Prompt before removing. +---(default: `true`) +---@field remove? boolean +--- +---Prompt before trashing. +---(default: `true`) +---@field trash? boolean +--- +---If `true` the prompt will be `Y/n`, otherwise `y/N` +---(default: `false`) +---@field default_yes? boolean diff --git a/lua/nvim-tree/_meta/config/update_focused_file.lua b/lua/nvim-tree/_meta/config/update_focused_file.lua new file mode 100644 index 00000000000..33a26b7d840 --- /dev/null +++ b/lua/nvim-tree/_meta/config/update_focused_file.lua @@ -0,0 +1,32 @@ +---@meta +error("Cannot require a meta file") + +---Update the focused file on [BufEnter], uncollapsing folders recursively. +--- +---@class nvim_tree.Config.UpdateFocusedFile +--- +---(default: `false`) +---@field enable? boolean +--- +---[nvim_tree.Config.UpdateFocusedFile.UpdateRoot] +---@field update_root? nvim_tree.Config.UpdateFocusedFile.UpdateRoot +--- +---A function called on [BufEnter] that returns true if the file should not be focused when opening. +---(default: `false`) +---@field exclude? boolean|(fun(args: vim.api.keyset.create_autocmd.callback_args): boolean) + + +---Update the root directory of the tree if the file is not under the current root directory. +--- +---Prefers vim's cwd and [nvim_tree.Config] {root_dirs}, falling back to the directory containing the file. +--- +---Only relevant when [nvim_tree.Config.UpdateFocusedFile] {enable} is `true` +--- +---@class nvim_tree.Config.UpdateFocusedFile.UpdateRoot +--- +---(default: `false`) +---@field enable? boolean +--- +---List of buffer names and filetypes that will not update the root dir of the tree if the file isn't found under the current root directory. +---(default: `{}`) +---@field ignore_list? string[] diff --git a/lua/nvim-tree/_meta/config/view.lua b/lua/nvim-tree/_meta/config/view.lua new file mode 100644 index 00000000000..0693a669e1c --- /dev/null +++ b/lua/nvim-tree/_meta/config/view.lua @@ -0,0 +1,104 @@ +---@meta +error("Cannot require a meta file") + +---@alias nvim_tree.Config.View.WidthSpec string|integer|(fun(): integer|string) + +---Configures the dimensions and appearance of the nvim-tree window. +--- +---The window is "docked" at the left by default, however may be configured to float: [nvim_tree.Config.View.Float] +--- +---{width} can be a [nvim_tree.Config.View.WidthSpec] for simple static control or a [nvim_tree.Config.View.Width] for fully dynamic control based on longest line. +--- +---[nvim_tree.Config.View.WidthSpec]() +---- string: `x%` string e.g. `30%` +---- integer: number of columns +---- function: returns one of the above +--- +---@class nvim_tree.Config.View +--- +---When entering nvim-tree, reposition the view so that the current node is initially centralized, see [zz]. +---(default: `false`) +---@field centralize_selection? boolean +--- +---[cursorline] +---(default: `true`) +---@field cursorline? boolean +--- +---[cursorlineopt] +---(default: `both`) +---@field cursorlineopt? string +--- +---Idle milliseconds before some reload / refresh operations. Increase if you experience performance issues around screen refresh. +---(default: `15`) +---@field debounce_delay? integer +--- +---(default: `left`) +---@field side? "left"|"right" +--- +---Preserves window proportions when opening a file. If `false`, the height and width of windows other than nvim-tree will be equalized. +---(default: `false`) +---@field preserve_window_proportions? boolean +--- +---[number] +---(default: `false`) +---@field number? boolean +--- +---[relativenumber] +---(default: `false`) +---@field relativenumber? boolean +--- +---[signcolumn] +---(default: `yes`) +---@field signcolumn? "yes"|"auto"|"no" +--- +---(default: `30`) +---@field width? nvim_tree.Config.View.WidthSpec|nvim_tree.Config.View.Width +--- +---[nvim_tree.Config.View.Float] +---@field float? nvim_tree.Config.View.Float + + +---Configure dynamic width based on longest line. +--- +---@class nvim_tree.Config.View.Width +--- +---(default: `30`) +---@field min? nvim_tree.Config.View.WidthSpec +--- +----1 for unbounded. +---(default: `-1`) +---@field max? nvim_tree.Config.View.WidthSpec +--- +---Exclude these lines when computing width. +---(default: `{ "root" }`) +---@field lines_excluded? ("root")[] +--- +---Extra padding to the right. +---(default: `1`) +---@field padding? nvim_tree.Config.View.WidthSpec + + +---Configure floating window behaviour +--- +---[vim.api.keyset.win_config] {open_win_config} is passed directly to [nvim_open_win], default: +---```lua +---{ +--- relative = "editor", +--- border = "rounded", +--- width = 30, +--- height = 30, +--- row = 1, +--- col = 1, +---} +---``` +---@class nvim_tree.Config.View.Float +--- +---(default: `false`) +---@field enable? boolean +--- +---Close the floating window when it loses focus. +---(default: `true`) +---@field quit_on_focus_loss? boolean +--- +---(default: above) +---@field open_win_config? vim.api.keyset.win_config|(fun(): vim.api.keyset.win_config) diff --git a/lua/nvim-tree/actions/node/buffer.lua b/lua/nvim-tree/actions/node/buffer.lua index 425fcfa4ba6..00cd3efdc63 100644 --- a/lua/nvim-tree/actions/node/buffer.lua +++ b/lua/nvim-tree/actions/node/buffer.lua @@ -4,14 +4,14 @@ local notify = require("nvim-tree.notify") local M = {} ---@param node Node ----@param opts ApiNodeDeleteWipeBufferOpts|nil +---@param opts nvim_tree.api.NodeBufferOpts|nil ---@return nil function M.delete(node, opts) M.delete_buffer("delete", node.absolute_path, opts) end ---@param node Node ----@param opts ApiNodeDeleteWipeBufferOpts|nil +---@param opts nvim_tree.api.NodeBufferOpts|nil ---@return nil function M.wipe(node, opts) M.delete_buffer("wipe", node.absolute_path, opts) @@ -21,7 +21,7 @@ end ---@param mode ApiNodeDeleteWipeBufferMode ---@param filename string ----@param opts ApiNodeDeleteWipeBufferOpts|nil +---@param opts nvim_tree.api.NodeBufferOpts|nil ---@return nil function M.delete_buffer(mode, filename, opts) if type(mode) ~= "string" then diff --git a/lua/nvim-tree/actions/tree/find-file.lua b/lua/nvim-tree/actions/tree/find-file.lua index 8a05bf6db45..b0d2834232f 100644 --- a/lua/nvim-tree/actions/tree/find-file.lua +++ b/lua/nvim-tree/actions/tree/find-file.lua @@ -6,7 +6,7 @@ local finders_find_file = require("nvim-tree.actions.finders.find-file") local M = {} --- Find file or buffer ----@param opts ApiTreeFindFileOpts|nil|boolean legacy -> opts.buf +---@param opts nvim_tree.api.TreeFindFileOpts|nil|boolean legacy -> opts.buf function M.fn(opts) -- legacy arguments if type(opts) == "string" then diff --git a/lua/nvim-tree/actions/tree/modifiers/collapse.lua b/lua/nvim-tree/actions/tree/modifiers/collapse.lua index 51a15f3d464..5c46cbdcae3 100644 --- a/lua/nvim-tree/actions/tree/modifiers/collapse.lua +++ b/lua/nvim-tree/actions/tree/modifiers/collapse.lua @@ -26,7 +26,7 @@ end ---Collapse a node, root if nil ---@param node Node? ----@param opts ApiCollapseOpts +---@param opts nvim_tree.api.CollapseOpts local function collapse(node, opts) local explorer = core.get_explorer() if not explorer then @@ -60,7 +60,7 @@ local function collapse(node, opts) end ----@param opts ApiCollapseOpts|boolean|nil legacy -> opts.keep_buffers +---@param opts nvim_tree.api.CollapseOpts|boolean|nil legacy -> opts.keep_buffers function M.all(opts) -- legacy arguments if type(opts) == "boolean" then @@ -73,7 +73,7 @@ function M.all(opts) end ---@param node Node ----@param opts ApiCollapseOpts? +---@param opts nvim_tree.api.CollapseOpts? function M.node(node, opts) collapse(node, opts or {}) end diff --git a/lua/nvim-tree/actions/tree/modifiers/expand.lua b/lua/nvim-tree/actions/tree/modifiers/expand.lua index 44e3fa67baa..c4a1274522b 100644 --- a/lua/nvim-tree/actions/tree/modifiers/expand.lua +++ b/lua/nvim-tree/actions/tree/modifiers/expand.lua @@ -125,7 +125,7 @@ local function gen_iterator(should_descend) end ---@param node Node? ----@param expand_opts ApiTreeExpandOpts? +---@param expand_opts nvim_tree.api.TreeExpandOpts? local function expand_node(node, expand_opts) if not node then return @@ -141,14 +141,14 @@ end ---Expand the directory node or the root ---@param node Node ----@param expand_opts ApiTreeExpandOpts? +---@param expand_opts nvim_tree.api.TreeExpandOpts? function M.all(node, expand_opts) expand_node(node and node:as(DirectoryNode) or core.get_explorer(), expand_opts) end ---Expand the directory node or parent node ---@param node Node ----@param expand_opts ApiTreeExpandOpts? +---@param expand_opts nvim_tree.api.TreeExpandOpts? function M.node(node, expand_opts) if not node then return diff --git a/lua/nvim-tree/actions/tree/open.lua b/lua/nvim-tree/actions/tree/open.lua index ff2da837b87..0c819ef83cb 100644 --- a/lua/nvim-tree/actions/tree/open.lua +++ b/lua/nvim-tree/actions/tree/open.lua @@ -5,7 +5,7 @@ local finders_find_file = require("nvim-tree.actions.finders.find-file") local M = {} ---Open the tree, focusing if already open. ----@param opts ApiTreeOpenOpts|nil|string legacy -> opts.path +---@param opts nvim_tree.api.TreeOpenOpts|nil|string legacy -> opts.path function M.fn(opts) -- legacy arguments if type(opts) == "string" then diff --git a/lua/nvim-tree/actions/tree/resize.lua b/lua/nvim-tree/actions/tree/resize.lua index e8d4e950729..43fba021134 100644 --- a/lua/nvim-tree/actions/tree/resize.lua +++ b/lua/nvim-tree/actions/tree/resize.lua @@ -3,7 +3,7 @@ local view = require("nvim-tree.view") local M = {} ---Resize the tree, persisting the new size. ----@param opts ApiTreeResizeOpts|nil +---@param opts nvim_tree.api.TreeResizeOpts|nil function M.fn(opts) if opts == nil then -- reset to config values diff --git a/lua/nvim-tree/actions/tree/toggle.lua b/lua/nvim-tree/actions/tree/toggle.lua index 10aa978467e..c2c4153a3c7 100644 --- a/lua/nvim-tree/actions/tree/toggle.lua +++ b/lua/nvim-tree/actions/tree/toggle.lua @@ -5,7 +5,7 @@ local finders_find_file = require("nvim-tree.actions.finders.find-file") local M = {} ---Toggle the tree. ----@param opts ApiTreeToggleOpts|nil|boolean legacy -> opts.find_file +---@param opts nvim_tree.api.TreeToggleOpts|nil|boolean legacy -> opts.find_file ---@param no_focus string|nil legacy -> opts.focus ---@param cwd boolean|nil legacy -> opts.path ---@param bang boolean|nil legacy -> opts.update_root diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua index e5a109142f1..75c3483797d 100644 --- a/lua/nvim-tree/api.lua +++ b/lua/nvim-tree/api.lua @@ -14,6 +14,18 @@ local FileLinkNode = require("nvim-tree.node.file-link") local RootNode = require("nvim-tree.node.root") local UserDecorator = require("nvim-tree.renderer.decorator.user") +-- Backwards compatibility aliases for renamed classes +---@alias ApiTreeOpenOpts nvim_tree.api.TreeOpenOpts +---@alias ApiTreeToggleOpts nvim_tree.api.TreeToggleOpts +---@alias ApiTreeResizeOpts nvim_tree.api.TreeResizeOpts +---@alias ApiTreeFindFileOpts nvim_tree.api.TreeFindFileOpts +---@alias ApiCollapseOpts nvim_tree.api.CollapseOpts +---@alias ApiTreeExpandOpts nvim_tree.api.TreeExpandOpts +---@alias ApiTreeIsVisibleOpts nvim_tree.api.TreeIsVisibleOpts +---@alias ApiTreeWinIdOpts nvim_tree.api.TreeWinIdOpts +---@alias NodeEditOpts nvim_tree.api.NodeEditOpts +---@alias ApiNodeDeleteWipeBufferOpts nvim_tree.api.NodeBufferOpts + local Api = { tree = {}, node = { @@ -123,35 +135,15 @@ local function wrap_explorer_member(explorer_member, member_method) end) end ----@class ApiTreeOpenOpts ----@field path string|nil path ----@field current_window boolean|nil default false ----@field winid number|nil ----@field find_file boolean|nil default false ----@field update_root boolean|nil default false - Api.tree.open = wrap(actions.tree.open.fn) Api.tree.focus = Api.tree.open ----@class ApiTreeToggleOpts ----@field path string|nil ----@field current_window boolean|nil default false ----@field winid number|nil ----@field find_file boolean|nil default false ----@field update_root boolean|nil default false ----@field focus boolean|nil default true - Api.tree.toggle = wrap(actions.tree.toggle.fn) Api.tree.close = wrap(view.close) Api.tree.close_in_this_tab = wrap(view.close_this_tab_only) Api.tree.close_in_all_tabs = wrap(view.close_all_tabs) Api.tree.reload = wrap_explorer("reload_explorer") ----@class ApiTreeResizeOpts ----@field width string|function|number|table|nil ----@field absolute number|nil ----@field relative number|nil - Api.tree.resize = wrap(actions.tree.resize.fn) Api.tree.change_root = wrap(function(...) @@ -179,25 +171,11 @@ Api.tree.change_root_to_parent = wrap_node(wrap_explorer("dir_up")) Api.tree.get_node_under_cursor = wrap_explorer("get_node_at_cursor") Api.tree.get_nodes = wrap_explorer("get_nodes") ----@class ApiTreeFindFileOpts ----@field buf string|number|nil ----@field open boolean|nil default false ----@field current_window boolean|nil default false ----@field winid number|nil ----@field update_root boolean|nil default false ----@field focus boolean|nil default false - Api.tree.find_file = wrap(actions.tree.find_file.fn) Api.tree.search_node = wrap(actions.finders.search_node.fn) ----@class ApiCollapseOpts ----@field keep_buffers boolean|nil default false - Api.tree.collapse_all = wrap(actions.tree.modifiers.collapse.all) ----@class ApiTreeExpandOpts ----@field expand_until (fun(expansion_count: integer, node: Node): boolean)|nil - Api.tree.expand_all = wrap_node(actions.tree.modifiers.expand.all) Api.tree.toggle_enable_filters = wrap_explorer_member("filters", "toggle") Api.tree.toggle_gitignore_filter = wrap_explorer_member_args("filters", "toggle", "git_ignored") @@ -209,15 +187,8 @@ Api.tree.toggle_no_bookmark_filter = wrap_explorer_member_args("filters", "toggl Api.tree.toggle_help = wrap(help.toggle) Api.tree.is_tree_buf = wrap(utils.is_nvim_tree_buf) ----@class ApiTreeIsVisibleOpts ----@field tabpage number|nil ----@field any_tabpage boolean|nil default false - Api.tree.is_visible = wrap(view.is_visible) ----@class ApiTreeWinIdOpts ----@field tabpage number|nil default nil - Api.tree.winid = wrap(view.winid) Api.fs.create = wrap_node_or_nil(actions.fs.create_file.fn) @@ -238,13 +209,9 @@ Api.fs.copy.filename = wrap_node(wrap_explorer_member("clipboard", "copy_filenam Api.fs.copy.basename = wrap_node(wrap_explorer_member("clipboard", "copy_basename")) Api.fs.copy.relative_path = wrap_node(wrap_explorer_member("clipboard", "copy_path")) --- ----@class NodeEditOpts ----@field quit_on_open boolean|nil default false ----@field focus boolean|nil default true - ---@param mode string ---@param node Node ----@param edit_opts NodeEditOpts? +---@param edit_opts nvim_tree.api.NodeEditOpts? local function edit(mode, node, edit_opts) local file_link = node:as(FileLinkNode) local path = file_link and file_link.link_to or node.absolute_path @@ -272,10 +239,10 @@ end ---@param mode string ---@param toggle_group boolean? ----@return fun(node: Node, edit_opts: NodeEditOpts?) +---@return fun(node: Node, edit_opts: nvim_tree.api.NodeEditOpts?) local function open_or_expand_or_dir_up(mode, toggle_group) ---@param node Node - ---@param edit_opts NodeEditOpts? + ---@param edit_opts nvim_tree.api.NodeEditOpts? return function(node, edit_opts) local root = node:as(RootNode) local dir = node:as(DirectoryNode) @@ -330,9 +297,6 @@ Api.node.navigate.opened.prev = wrap_node(actions.moves.item.fn({ where = "prev" Api.node.expand = wrap_node(actions.tree.modifiers.expand.node) Api.node.collapse = wrap_node(actions.tree.modifiers.collapse.node) ----@class ApiNodeDeleteWipeBufferOpts ----@field force boolean|nil default false - Api.node.buffer.delete = wrap_node(function(node, opts) actions.node.buffer.delete(node, opts) end) diff --git a/lua/nvim-tree/view.lua b/lua/nvim-tree/view.lua index a8c1c9a0ae2..bb1d746a72c 100644 --- a/lua/nvim-tree/view.lua +++ b/lua/nvim-tree/view.lua @@ -437,7 +437,7 @@ function M.abandon_all_windows() end end ----@param opts table|nil +---@param opts? nvim_tree.api.TreeIsVisibleOpts ---@return boolean function M.is_visible(opts) if opts and opts.tabpage then @@ -486,7 +486,7 @@ function M.focus(winnr, open_if_closed) end --- Retrieve the winid of the open tree. ----@param opts ApiTreeWinIdOpts|nil +---@param opts nvim_tree.api.TreeWinIdOpts|nil ---@return number|nil winid unlike get_winnr(), this returns nil if the nvim-tree window is not visible function M.winid(opts) local tabpage = opts and opts.tabpage diff --git a/scripts/gen_vimdoc.sh b/scripts/gen_vimdoc.sh new file mode 100755 index 00000000000..fa0d28b4265 --- /dev/null +++ b/scripts/gen_vimdoc.sh @@ -0,0 +1,31 @@ +#!/usr/bin/env sh + +set -e + +if [ ! -d "${NEOVIM_SRC}" ]; then + echo "\$NEOVIM_SRC not set" + exit 1 +fi + +# runtime/doc is hardcoded, copy the help in +mkdir -pv runtime/doc +cp -v "doc/nvim-tree-lua.txt" runtime/doc + +# modify gen_vimdoc.lua to use our config +cp -v "${NEOVIM_SRC}/src/gen/gen_vimdoc.lua" gen_vimdoc.lua +sed -i -E 's/spairs\(config\)/spairs\(require("gen_vimdoc_config")\)/g' gen_vimdoc.lua + +# use luacacts etc. from neovim src as well as our specific config +export LUA_PATH="${NEOVIM_SRC}/src/?.lua;scripts/?.lua" + +# generate +./gen_vimdoc.lua + +# move the generated help out +mv -v "runtime/doc/nvim-tree-lua.txt" doc + +# clean up +rmdir -v runtime/doc +rmdir -v runtime +rm -v gen_vimdoc.lua + diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua new file mode 100644 index 00000000000..a0ce0ee4ea6 --- /dev/null +++ b/scripts/gen_vimdoc_config.lua @@ -0,0 +1,87 @@ +---@class (exact) Module +---@field helptag string must be globally unique +---@field title string arbitrary +---@field path string relative to root +---@field file string? generated from path +---@field name string? override generated module name + +---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-help", title = "Class: Config.Help", path = "lua/nvim-tree/_meta/config/help.lua", }, + { helptag = "nvim-tree-config-ui", title = "Class: Config.UI", path = "lua/nvim-tree/_meta/config/ui.lua", name = "UI", }, + { helptag = "nvim-tree-config-log", title = "Class: Config.Log", path = "lua/nvim-tree/_meta/config/log.lua", }, + + -- { helptag = "nvim-tree-api", title = "Lua module: nvim_tree.api", path = "lua/nvim-tree/_meta/api.lua", }, + -- { helptag = "nvim-tree-api-decorator", title = "Lua module: nvim_tree.api.decorator", path = "lua/nvim-tree/_meta/api_decorator.lua", }, +} + +-- hydrate file names +for _, m in ipairs(modules) do + m.file = vim.fn.fnamemodify(m.path, ":t") +end + +--module name is derived by the generator as the file name with the first letter capitalised +--except for some like UI +---@type table +local modules_by_name = {} +for _, m in ipairs(modules) do + local name = m.name or m.file:gsub(".lua", ""):gsub("^%l", string.upper) + modules_by_name[name] = m +end + +---@diagnostic disable-next-line: undefined-doc-name +--- @type table +local config = { + all = { + filename = "nvim-tree-lua.txt", + + -- file is used to set order + section_order = vim.tbl_map(function(m) return m.file end, modules), + + -- path + 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)) + 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)) + 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) + end + return fun.name .. fn_sfx + end, + } +} + +return config