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 44206bdc483..1d792adbd99 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -1,71 +1,11 @@ -*nvim-tree.lua* A File Explorer For Neovim Written In Lua +*nvim-tree-lua.txt* A File Explorer For Nvim *nvim-tree* Author: Yazdani Kiyan -============================================================================== -CONTENTS *nvim-tree* - - 1. Introduction |nvim-tree-introduction| - 2. Quickstart |nvim-tree-quickstart| - 2.1 Quickstart: Setup |nvim-tree-quickstart-setup| - 2.2 Quickstart: Help |nvim-tree-quickstart-help| - 2.3 Quickstart: Custom Mappings |nvim-tree-quickstart-custom-mappings| - 2.4 Quickstart: Highlight |nvim-tree-quickstart-highlight| - 3. Commands |nvim-tree-commands| - 4. Setup |nvim-tree-setup| - 5. Opts |nvim-tree-opts| - 5.1 Opts: Sort |nvim-tree-opts-sort| - 5.2 Opts: View |nvim-tree-opts-view| - 5.3 Opts: Renderer |nvim-tree-opts-renderer| - 5.4 Opts: Hijack Directories |nvim-tree-opts-hijack-directories| - 5.5 Opts: Update Focused File |nvim-tree-opts-update-focused-file| - 5.6 Opts: System Open |nvim-tree-opts-system-open| - 5.7 Opts: Git |nvim-tree-opts-git| - 5.8 Opts: Diagnostics |nvim-tree-opts-diagnostics| - 5.9 Opts: Modified |nvim-tree-opts-modified| - 5.10 Opts: Filters |nvim-tree-opts-filters| - 5.11 Opts: Live Filter |nvim-tree-opts-live-filter| - 5.12 Opts: Filesystem Watchers |nvim-tree-opts-filesystem-watchers| - 5.13 Opts: Actions |nvim-tree-opts-actions| - 5.14 Opts: Trash |nvim-tree-opts-trash| - 5.15 Opts: Tab |nvim-tree-opts-tab| - 5.16 Opts: Notify |nvim-tree-opts-notify| - 5.17 Opts: Help |nvim-tree-opts-help| - 5.18 Opts: UI |nvim-tree-opts-ui| - 5.19 Opts: Bookmarks |nvim-tree-opts-bookmarks| - 5.20 Opts: Experimental |nvim-tree-opts-experimental| - 5.21 Opts: Log |nvim-tree-opts-log| - 6. API |nvim-tree-api| - 6.1 API Tree |nvim-tree-api.tree| - 6.2 API File System |nvim-tree-api.fs| - 6.3 API Node |nvim-tree-api.node| - 6.4 API Git |nvim-tree-api.git| - 6.5 API Events |nvim-tree-api.events| - 6.6 API Live Filter |nvim-tree-api.live_filter| - 6.7 API Marks |nvim-tree-api.marks| - 6.8 API Config |nvim-tree-api.config| - 6.9 API Commands |nvim-tree-api.commands| - 6.10 API Diagnostics |nvim-tree-api.diagnostics| - 7. Mappings |nvim-tree-mappings| - 7.1 Mappings: Default |nvim-tree-mappings-default| - 8. Highlight |nvim-tree-highlight| - 8.1 Highlight: Default |nvim-tree-highlight-default| - 8.2 Highlight: Overhaul |nvim-tree-highlight-overhaul| - 9. Events |nvim-tree-events| - 10. Prompts |nvim-tree-prompts| - 11. Decorators |nvim-tree-decorators| - 11.1 Decorator Example |nvim-tree-decorator-example| - 12. OS Specific Restrictions |nvim-tree-os-specific| - 13. Netrw |nvim-tree-netrw| - 14. Legacy |nvim-tree-legacy| - 14.1 Legacy: Opts |nvim-tree-legacy-opts| - 14.2 Legacy: Highlight |nvim-tree-legacy-highlight| - 15. Index |nvim-tree-index| - 15.1 Index: Opts |nvim-tree-index-opts| - 15.2 Index: API |nvim-tree-index-api| + Type |gO| to see the table of contents. ============================================================================== - 1. INTRODUCTION *nvim-tree-introduction* +Introduction *nvim-tree-introduction* Features @@ -85,7 +25,7 @@ File Icons  should look like an open folder. - To disable the display of icons see |renderer.icons.show| + Disable the display of icons with |nvim_tree.Config.Renderer.Icons.Show| Colours @@ -106,10 +46,10 @@ Git Integration Requirements - This file explorer requires `neovim >= 0.9.0` + Nvim >= 0.9 ============================================================================== - 2. QUICKSTART *nvim-tree-quickstart* +Quickstart *nvim-tree-quickstart* Install the plugins via your package manager: `"nvim-tree/nvim-tree.lua"` @@ -118,9 +58,10 @@ Install the plugins via your package manager: Disabling |netrw| is strongly advised, see |nvim-tree-netrw| ============================================================================== - 2.1 QUICKSTART: SETUP *nvim-tree-quickstart-setup* +Quickstart: Setup *nvim-tree-quickstart-setup* -Setup the plugin in your `init.lua` e.g. >lua +Setup the plugin in your `init.lua`, passing |nvim_tree.Config| +e.g. >lua -- disable netrw at the very start of your init.lua vim.g.loaded_netrw = 1 @@ -149,7 +90,7 @@ Setup the plugin in your `init.lua` e.g. >lua }) < ============================================================================== - 2.2 QUICKSTART: HELP *nvim-tree-quickstart-help* +Quickstart: Help *nvim-tree-quickstart-help* Open the tree: `:NvimTreeOpen` @@ -215,10 +156,10 @@ Show the mappings: `g?` `<2-RightMouse>` CD |nvim-tree-api.tree.change_root_to_node()| ============================================================================== - 2.3 QUICKSTART: CUSTOM MAPPINGS *nvim-tree-quickstart-custom-mappings* +Quickstart: Custom Mappings *nvim-tree-quickstart-custom-mappings* |nvim-tree-mappings-default| are applied by default however you may customise -via |nvim-tree.on_attach| e.g. >lua +via |nvim_tree.Config| {on_attach} e.g. >lua local function my_on_attach(bufnr) local api = require "nvim-tree.api" @@ -243,7 +184,7 @@ via |nvim-tree.on_attach| e.g. >lua } < ============================================================================== - 2.4 QUICKSTART: HIGHLIGHT *nvim-tree-quickstart-highlight* +Quickstart: Highlight *nvim-tree-quickstart-highlight* Run |:NvimTreeHiTest| to show all the highlights that nvim-tree uses. @@ -260,7 +201,7 @@ applied at runtime. e.g. >lua See |nvim-tree-highlight| for details. ============================================================================== - 3. COMMANDS *nvim-tree-commands* +Commands *nvim-tree-commands* *:NvimTreeOpen* @@ -362,10 +303,10 @@ See |nvim-tree-highlight| for details. Calls: `api.diagnostics.hi_test()` ============================================================================== - 4. SETUP *nvim-tree-setup* +Setup *nvim-tree-setup* You must run setup() function once to initialise nvim-tree. It may be called -again to apply a change in configuration without restarting nvim. +again to apply a change in configuration without restarting Nvim. setup() function takes one optional argument: configuration table. If omitted nvim-tree will be initialised with default configuration. @@ -376,7 +317,7 @@ the configuration. Nothing happens until the tree is first opened. Subsequent setup() calls are expensive as they tear down the world before applying configuration. -Following is the default configuration. See |nvim-tree-opts| for details. >lua +Following is the default configuration. See |nvim_tree.Config| for details. >lua require("nvim-tree").setup { -- BEGIN_DEFAULT_OPTS on_attach = "default", @@ -663,1070 +604,7 @@ Following is the default configuration. See |nvim-tree-opts| for details. >lua < ============================================================================== - 5. OPTS *nvim-tree-opts* - -*nvim-tree.on_attach* -Runs when creating the nvim-tree buffer. Use this to set your nvim-tree -specific mappings. See |nvim-tree-mappings|. -When on_attach is not a function, |nvim-tree-mappings-default| will be called. - Type: `function(bufnr) | string`, Default: `"default"` - -*nvim-tree.hijack_cursor* -Keeps the cursor on the first letter of the filename when moving in the tree. - Type: `boolean`, Default: `false` - -*nvim-tree.auto_reload_on_write* -Reloads the explorer every time a buffer is written to. - Type: `boolean`, Default: `true` - -*nvim-tree.disable_netrw* -Completely disable netrw - Type: `boolean`, Default: `false` - -It is strongly advised to eagerly disable netrw, due to race conditions at vim -startup. -Set the following at the very beginning of your `init.lua` / `init.vim`: >lua - vim.g.loaded_netrw = 1 - vim.g.loaded_netrwPlugin = 1 -< -*nvim-tree.hijack_netrw* -Hijack netrw windows (overridden if |disable_netrw| is `true`) - Type: `boolean`, Default: `true` - -*nvim-tree.hijack_unnamed_buffer_when_opening* -Opens in place of the unnamed buffer if it's empty. - Type: `boolean`, Default: `false` - -*nvim-tree.root_dirs* -Preferred root directories. -Only relevant when `update_focused_file.update_root` is `true` - Type: `{string}`, Default: `{}` - -*nvim-tree.prefer_startup_root* -Prefer startup root directory when updating root directory of the tree. -Only relevant when `update_focused_file.update_root` is `true` - Type: `boolean`, Default: `false` - -*nvim-tree.sync_root_with_cwd* -Changes the tree root directory on `DirChanged` and refreshes the tree. - Type: `boolean`, Default: `false` - -*nvim-tree.reload_on_bufenter* -Automatically reloads the tree on `BufEnter` nvim-tree. - Type: `boolean`, Default: `false` - -*nvim-tree.respect_buf_cwd* -Will change cwd of nvim-tree to that of new buffer's when opening nvim-tree. - Type: `boolean`, Default: `false` - -*nvim-tree.select_prompts* -Use |vim.ui.select| style prompts. Necessary when using a UI prompt decorator -such as dressing.nvim or telescope-ui-select.nvim -Type: `boolean`, Default: `false` - -============================================================================== - 5.1 OPTS: SORT *nvim-tree-opts-sort* - -File and folder sorting options. - -*nvim-tree.sort.sorter* -Changes how files within the same directory are sorted. -Can be one of `"name"`, `"case_sensitive"`, `"modification_time"`, `"extension"`, -`"suffix"`, `"filetype"` or a function. -`"extension"` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz` -`"suffix"` uses the last e.g. `.gz` - Type: `string` | `function(nodes)`, Default: `"name"` - - Function may perform a sort or return a string with one of the above - methods. It is passed a table of nodes to be sorted, each node containing: - - `absolute_path`: `string` - - `executable`: `boolean` - - `extension`: `string` - - `filetype`: `string` - - `link_to`: `string` - - `name`: `string` - - `type`: `"directory"` | `"file"` | `"link"` - - Example: sort by name length: >lua - local sorter = function(nodes) - table.sort(nodes, function(a, b) - return #a.name < #b.name - end) - end -< -*nvim-tree.sort.folders_first* -Sort folders before files. Has no effect when |nvim-tree.sort.sorter| is a -function. - Type: `boolean`, Default: `true` - -*nvim-tree.sort.files_first* -Sort files before folders. Has no effect when |nvim-tree.sort.sorter| is a -function. If set to `true` it overrides |nvim-tree.sort.folders_first|. - Type: `boolean`, Default: `false` - -============================================================================== - 5.2 OPTS: VIEW *nvim-tree-opts-view* - -*nvim-tree.view.centralize_selection* -When entering nvim-tree, reposition the view so that the current node is -initially centralized, see |zz|. - Type: `boolean`, Default: `false` - -*nvim-tree.view.cursorline* -Enable |cursorline| in the tree window. - Type: `boolean`, Default: `true` - -*nvim-tree.view.cursorlineopt* -Set |cursorlineopt| in the tree window. - Type: `string`, Default: `"both"` - -*nvim-tree.view.debounce_delay* -Idle milliseconds before some reload / refresh operations. -Increase if you experience performance issues around screen refresh. - Type: `number`, Default: `15` (ms) - -*nvim-tree.view.side* -Side of the tree, can be `"left"`, `"right"`. - Type: `string`, Default: `"left"` - -*nvim-tree.view.preserve_window_proportions* -Preserves window proportions when opening a file. -If `false`, the height and width of windows other than nvim-tree will be equalized. - Type: `boolean`, Default: `false` - -*nvim-tree.view.number* -Print the line number in front of each line. - Type: `boolean`, Default: `false` - -*nvim-tree.view.relativenumber* -Show the line number relative to the line with the cursor in front of each line. -If the option `view.number` is also `true`, the number on the cursor line -will be the line number instead of `0`. - Type: `boolean`, Default: `false` - -*nvim-tree.view.signcolumn* -Show |signcolumn|. Value can be `"yes"`, `"auto"`, `"no"`. - Type: `string`, Default: `"yes"` - -*nvim-tree.view.width* -Width of the window: can be a `%` string, a number representing columns, a -function or a table. -A table indicates that the view should be dynamically sized based on the -longest line. - Type: `string | number | table | fun(): number|string` - Default: `30` - - *nvim-tree.view.width.min* - Minimum dynamic width. - Type: `string | number | fun(): number|string` - Default: `30` - - *nvim-tree.view.width.max* - Maximum dynamic width, -1 for unbounded. - Type: `string | number | fun(): number|string` - Default: `-1` - - *nvim-tree.view.width.lines_excluded* - Exclude these lines when computing width. - Supported values: `"root". - Type: `table` - Default: - `{` - `"root"` - `}` - - *nvim-tree.view.width.padding* - Extra padding to the right. - Type: `number | fun(): number|string` - Default: `1` - -*nvim-tree.view.float* -Use nvim-tree in a floating window. - - *nvim-tree.view.float.enable* - Tree window will be floating. - Type: `boolean`, Default: `false` - - *nvim-tree.view.float.quit_on_focus_loss* - Close the floating tree window when it loses focus. - Type: `boolean`, Default: `true` - - *nvim-tree.view.float.open_win_config* - Floating window config. See |nvim_open_win| for more details. - Type: `table | function` returning a table - Default: - `{` - `relative = "editor",` - `border = "rounded",` - `width = 30,` - `height = 30,` - `row = 1,` - `col = 1,` - `}` - -============================================================================== - 5.3 OPTS: RENDERER *nvim-tree-opts-renderer* - -*nvim-tree.renderer.add_trailing* -Appends a trailing slash to folder and symlink folder destination names. - Type: `boolean`, Default: `false` - -*nvim-tree.renderer.group_empty* -Compact folders that only contain a single folder into one node. -Boolean or function that takes one argument (the relative path -of grouped folders) and returns a string to be displayed. - Type: `boolean | function(relative_path):string`, Default: `false` - -*nvim-tree.renderer.full_name* -Display node whose name length is wider than the width of nvim-tree window in -floating window. - Type: `boolean`, Default: `false` - -*nvim-tree.renderer.root_folder_label* -In what format to show root folder. See `:help filename-modifiers` for -available `string` options. -Set to `false` to hide the root folder. - Type: `string` or `boolean` or `function(root_cwd)`, Default: `":~:s?$?/..?"` - - Function is passed the absolute path of the root folder and should - return a string. e.g. >lua - my_root_folder_label = function(path) - return ".../" .. vim.fn.fnamemodify(path, ":t") - end -< -*nvim-tree.renderer.indent_width* -Number of spaces for an each tree nesting level. Minimum 1. - Type: `number`, Default: `2` - -*nvim-tree.renderer.special_files* -A list of filenames that gets highlighted with `NvimTreeSpecialFile`. - Type: `table`, Default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }` - -*nvim-tree.renderer.hidden_display* -Show a summary of hidden files below the tree using `NvimTreeHiddenDisplay - Type: `function | string`, Default: `"none"` - - Possible string values are: - - `"none"`: Doesn't inform anything about hidden files. - - `"simple"`: Shows how many hidden files are in a folder. - - `"all"`: Shows how many files are hidden and the number of hidden - files per reason why they're hidden. - - Example `"all"`: - If a folder has 14 hidden items for various reasons, the display might - show: > - (14 total git: 5, dotfile: 9) -< - If a function is provided, it receives a table `hidden_stats` where keys are - reasons and values are the count of hidden files for that reason. - - The `hidden_stats` argument is structured as follows, where is the - number of hidden files related to the field: >lua - hidden_stats = { - bookmark = , - buf = , - custom = , - dotfile = , - git = , - live_filter = , - } -< - Example of function that can be passed: >lua - function(hidden_stats) - local total_count = 0 - for reason, count in pairs(hidden_stats) do - total_count = total_count + count - end - - if total_count > 0 then - return "(" .. tostring(total_count) .. " hidden)" - end - return nil - end -< - -*nvim-tree.renderer.symlink_destination* -Whether to show the destination of the symlink. - Type: `boolean`, Default: `true` - -*nvim-tree.renderer.decorators* -Highlighting and icons for the nodes, in increasing order of precedence. -Uses strings to specify builtin decorators otherwise specify your -`nvim_tree.api.decorator.UserDecorator` class. - Type: `nvim_tree.api.decorator.Name[]`, Default: >lua - { - "Git", - "Open", - "Hidden", - "Modified", - "Bookmark", - "Diagnostics", - "Copied", - "Cut", - } -< -*nvim-tree.renderer.highlight_git* -Enable highlight for git attributes using `NvimTreeGit*HL` highlight groups. -Requires |nvim-tree.git.enable| -Value can be `"none"`, `"icon"`, `"name"` or `"all"`. - Type: `string`, Default: `"none"` - -*nvim-tree.renderer.highlight_diagnostics* -Enable highlight for diagnostics using `NvimTreeDiagnostic*HL` highlight groups. -Requires |nvim-tree.diagnostics.enable| -Value can be `"none"`, `"icon"`, `"name"` or `"all"`. - Type: `string`, Default: `"none"` - -*nvim-tree.renderer.highlight_opened_files* -Highlight icons and/or names for |bufloaded()| files using the -`NvimTreeOpenedHL` highlight group. -See |nvim-tree-api.navigate.opened.next()| and |nvim-tree-api.navigate.opened.prev()| -Value can be `"none"`, `"icon"`, `"name"` or `"all"`. - Type: `string`, Default: `"none"` - -*nvim-tree.renderer.highlight_modified* -Highlight icons and/or names for modified files using the -`NvimTreeModifiedFile` highlight group. -Requires |nvim-tree.modified.enable| -Value can be `"none"`, `"icon"`, `"name"` or `"all"` - Type: `string`, Default `"none"` - -*nvim-tree.renderer.highlight_hidden* -Highlight icons and/or names for hidden files (dotfiles) using the -`NvimTreeHiddenFileHL` highlight group. -Value can be `"none"`, `"icon"`, `"name"` or `"all"` - Type: `string`, Default `"none"` - -*nvim-tree.renderer.highlight_bookmarks* -Highlight bookmarked using the `NvimTreeBookmarkHL` group. -Value can be `"none"`, `"icon"`, `"name"` or `"all"` - Type: `string`, Default `"none"` - -*nvim-tree.renderer.highlight_clipboard* -Enable highlight for clipboard items using the `NvimTreeCutHL` and -`NvimTreeCopiedHL` groups. -Value can be `"none"`, `"icon"`, `"name"` or `"all"`. - Type: `string`, Default: `"name"` - -*nvim-tree.renderer.indent_markers* -Configuration options for tree indent markers. - - *nvim-tree.renderer.indent_markers.enable* - Display indent markers when folders are open - Type: `boolean`, Default: `false` - - *nvim-tree.renderer.indent_markers.inline_arrows* - Display folder arrows in the same column as indent marker - when using |renderer.icons.show.folder_arrow| - Type: `boolean`, Default: `true` - - *nvim-tree.renderer.indent_markers.icons* - Icons shown before the file/directory. Length 1. - Type: `table`, Default: >lua - { - corner = "└", - edge = "│", - item = "│", - bottom = "─", - none = " ", - } -< -*nvim-tree.renderer.icons* -Configuration options for icons. - -`renderer.icons.*_placement` options may be: -- `"before"` : before file/folder, after the file/folders icons -- `"after"` : after file/folder -- `"signcolumn"` : far left, requires |nvim-tree.view.signcolumn| enabled -- `"right_align"` : far right - - *nvim-tree.renderer.icons.web_devicons* - Configure optional plugin `"nvim-tree/nvim-web-devicons"` - - *nvim-tree.renderer.icons.web_devicons.file* - File icons. - - *nvim-tree.renderer.icons.web_devicons.file.enable* - Show icons on files. - Overrides |nvim-tree.renderer.icons.glyphs.default| - Type: `boolean`, Default: `true` - - *nvim-tree.renderer.icons.web_devicons.file.color* - Use icon colors for files. Overrides highlight groups. - Type: `boolean`, Default: `true` - - *nvim-tree.renderer.icons.web_devicons.folder* - Folder icons. - - *nvim-tree.renderer.icons.web_devicons.folder.enable* - Show icons on folders. - Overrides |nvim-tree.renderer.icons.glyphs.folder| - Type: `boolean`, Default: `false` - - *nvim-tree.renderer.icons.web_devicons.folder.color* - Use icon colors for folders. Overrides highlight groups. - Type: `boolean`, Default: `true` - - *nvim-tree.renderer.icons.git_placement* - Git icons placement. - Type: `string`, Default: `"before"` - - *nvim-tree.renderer.icons.diagnostics_placement* - Diganostic icon placement. - Type: `string`, Default: `"signcolumn"` - - *nvim-tree.renderer.icons.modified_placement* - Modified icon placement. - Type: `string`, Default: `"after"` - - *nvim-tree.renderer.icons.hidden_placement* - Hidden icon placement. - Type: `string`, Default: `"after"` - - *nvim-tree.renderer.icons.bookmarks_placement* - Bookmark icon placement. - Type: `string`, Default: `"signcolumn"` - - *nvim-tree.renderer.icons.padding.icon* - Inserted between icon and filename. - Type: `string`, Default: `" "` - - *nvim-tree.renderer.icons.padding.folder_arrow* - Inserted between folder arrow icon and file/folder icon. - Type: `string`, Default: `" "` - - *nvim-tree.renderer.icons.symlink_arrow* - Used as a separator between symlinks' source and target. - Type: `string`, Default: `" ➛ "` - - *nvim-tree.renderer.icons.show* - Configuration options for showing icon types. - Left to right order: file/folder, git, modified, hidden, diagnostics, bookmarked. - - *nvim-tree.renderer.icons.show.file* - Show an icon before the file name. - Type: `boolean`, Default: `true` - - *nvim-tree.renderer.icons.show.folder* - Show an icon before the folder name. - Type: `boolean`, Default: `true` - - *nvim-tree.renderer.icons.show.folder_arrow* - Show a small arrow before the folder node. Arrow will be a part of the - node when using |renderer.indent_markers|. - Type: `boolean`, Default: `true` - - *nvim-tree.renderer.icons.show.git* - Show a git status icon, see |renderer.icons.git_placement| - Requires |git.enable| `= true` - Type: `boolean`, Default: `true` - - *nvim-tree.renderer.icons.show.modified* - Show a modified icon, see |renderer.icons.modified_placement| - Requires |modified.enable| `= true` - Type: `boolean`, Default: `true` - - *nvim-tree.renderer.icons.show.hidden* - Show a hidden icon, see |renderer.icons.hidden_placement| - Type: `boolean`, Default: `false` - - *nvim-tree.renderer.icons.show.diagnostics* - Show a diagnostics status icon, see |renderer.icons.diagnostics_placement| - Requires |diagnostics.enable| `= true` - Type: `boolean`, Default: `true` - - *nvim-tree.renderer.icons.show.bookmarks* - Show a bookmark icon, see |renderer.icons.bookmarks_placement| - Type: `boolean`, Default: `true` - - *nvim-tree.renderer.icons.glyphs* - Configuration options for icon glyphs. - NOTE: Do not set any glyphs to more than two characters if it's going - to appear in the signcolumn. - - *nvim-tree.renderer.icons.glyphs.default* - Glyph for files. - Overridden by |nvim-tree.renderer.icons.web_devicons| if available. - Type: `string`, Default: `""` - - *nvim-tree.renderer.icons.glyphs.symlink* - Glyph for symlinks to files. - Type: `string`, Default: `""` - - *nvim-tree.renderer.icons.glyphs.modified* - Icon to display for modified files. - Type: `string`, Default: `"●"` - - *nvim-tree.renderer.icons.glyphs.hidden* - Icon to display for hidden files. - Type: `string`, Default: `"󰜌""` - - *nvim-tree.renderer.icons.glyphs.folder* - Glyphs for directories. - Overridden by |nvim-tree.renderer.icons.web_devicons| if available. - Type: `table`, Default: - `{` - `arrow_closed = "",` - `arrow_open = "",` - `default = "",` - `open = "",` - `empty = "",` - `empty_open = "",` - `symlink = "",` - `symlink_open = "",` - `}` - - *nvim-tree.renderer.icons.glyphs.git* - Glyphs for git status. - Type: `table`, Default: - `{` - `unstaged = "✗",` - `staged = "✓",` - `unmerged = "",` - `renamed = "➜",` - `untracked = "★",` - `deleted = "",` - `ignored = "◌",` - `}` - -============================================================================== - 5.4 OPTS: HIJACK DIRECTORIES *nvim-tree-opts-hijack-directories* - -*nvim-tree.hijack_directories.enable* -Enable the feature. -Disable this option if you use vim-dirvish or dirbuf.nvim. -If `hijack_netrw` and `disable_netrw` are `false`, this feature will be disabled. - Type: `boolean`, Default: `true` - -*nvim-tree.hijack_directories.auto_open* -Opens the tree if the tree was previously closed. - Type: `boolean`, Default: `true` - -============================================================================== - 5.5 OPTS: UPDATE FOCUSED FILE *nvim-tree-opts-update-focused-file* - -Update the focused file on `BufEnter`, un-collapses the folders recursively -until it finds the file. - -*nvim-tree.update_focused_file.enable* -Enable this feature. - Type: `boolean`, Default: `false` - -*nvim-tree.update_focused_file.update_root* -Update the root directory of the tree if the file is not under current -root directory. It prefers vim's cwd and `root_dirs`. -Otherwise it falls back to the folder containing the file. -Only relevant when `update_focused_file.enable` is `true` - - *nvim-tree.update_focused_file.update_root.enable* - Type: `boolean`, Default: `false` - - *nvim-tree.update_focused_file.update_root.ignore_list* - List of buffer names and filetypes that will not update the root dir - of the tree if the file isn't found under the current root directory. - Only relevant when `update_focused_file.update_root.enable` and - `update_focused_file.enable` are `true`. - Type: {string}, Default: `{}` - -*nvim-tree.update_focused_file.exclude* -A function that returns true if the file should not be focused when opening. -Takes the `BufEnter` event as an argument. see |autocmd-events| - Type: {function}, Default: `false` - -============================================================================== - 5.6 OPTS: SYSTEM OPEN *nvim-tree-opts-system-open* - -Open a file or directory in your preferred application. - -|vim.ui.open| was introduced in neovim 0.10 and is the default. - -Once nvim-tree minimum neovim version is updated to 0.10, these options will -no longer be necessary and will be removed. - -*nvim-tree.system_open.cmd* -The open command itself. - Type: `string`, Default: `""` - -neovim >= 0.10 defaults to |vim.ui.open| - -neovim < 0.10 defaults to: - UNIX: `"xdg-open"` - macOS: `"open"` - Windows: `"cmd"` - -*nvim-tree.system_open.args* -Optional argument list. - Type: {string}, Default: `{}` - -Leave empty for OS specific default: - Windows: `{ "/c", "start", '""' }` - -============================================================================== - 5.7 OPTS: GIT *nvim-tree-opts-git* - -Git operations are run in the background thus status may not immediately -appear. - -Processes will be killed if they exceed |nvim-tree.git.timeout| - -Git integration will be disabled following 5 timeouts and you will be -notified. - -*nvim-tree.git.enable* -Enable / disable the feature. - Type: `boolean`, Default: `true` - -*nvim-tree.git.show_on_dirs* -Show status icons of children when directory itself has no status icon. - Type: `boolean`, Default: `true` - -*nvim-tree.git.show_on_open_dirs* -Show status icons of children on directories that are open. -Only relevant when `git.show_on_dirs` is `true`. - Type: `boolean`, Default: `true` - -*nvim-tree.git.disable_for_dirs* -Disable git integration when git top-level matches these paths. -Strings may be relative, evaluated via |fnamemodify| `":p"` -Function is passed an absolute path and returns true for disable. - Type: `string[] | fun(path: string): boolean`, Default: `{}` - -*nvim-tree.git.timeout* -Kills the git process after some time if it takes too long. -Git integration will be disabled after 10 git jobs exceed this timeout. - Type: `number`, Default: `400` (ms) - -*nvim-tree.git.cygwin_support* -Use `cygpath` if available to resolve paths for git. - Type: `boolean`, Default: `false` - -============================================================================== - 5.8 OPTS: DIAGNOSTICS *nvim-tree-opts-diagnostics* - -LSP and COC diagnostics. - -*nvim-tree.diagnostics.enable* -Enable/disable the feature. - Type: `boolean`, Default: `false` - -*nvim-tree.diagnostics.debounce_delay* -Idle milliseconds between diagnostic event and update. - Type: `number`, Default: `500` (ms) - -*nvim-tree.diagnostics.show_on_dirs* -Show diagnostic icons on parent directories. - Type: `boolean`, Default: `false` - -*nvim-tree.diagnostics.show_on_open_dirs* -Show diagnostics icons on directories that are open. -Only relevant when `diagnostics.show_on_dirs` is `true`. - Type: `boolean`, Default: `true` - -*nvim-tree.diagnostics.severity* -Severity for which the diagnostics will be displayed. See |diagnostic-severity| - - *nvim-tree.diagnostics.severity.min* - Minimum severity. - Type: |vim.diagnostic.severity|, Default: `vim.diagnostic.severity.HINT` - - *nvim-tree.diagnostics.severity.max* - Maximum severity. - Type: |vim.diagnostic.severity|, Default: `vim.diagnostic.severity.ERROR` - -*nvim-tree.diagnostics.icons* -Icons for diagnostic severity. - Type: `table`, Default: >lua - { - hint = "", - info = "", - warning = "", - error = "" - } -< -*nvim-tree.diagnostics.diagnostic_opts* -|vim.diagnostic.Opts| overrides |nvim-tree.diagnostics.severity| and -|nvim-tree.diagnostics.icons| - Type: `boolean`, Default: `false` -============================================================================== - 5.9 OPTS: MODIFIED *nvim-tree-opts-modified* - -Indicate which file have unsaved modification. - -You will still need to set |renderer.icons.show.modified| `= true` or -|renderer.highlight_modified| `= true` to be able to see modified status in the -tree. - -*nvim-tree.modified.enable* -Enable / disable the feature. - Type: `boolean`, Default: `false` - -*nvim-tree.modified.show_on_dirs* -Show modified indication on directory whose children are modified. - Type: `boolean`, Default: `true` - -*nvim-tree.modified.show_on_open_dirs* -Show modified indication on open directories. -Only relevant when |modified.show_on_dirs| is `true`. - Type: `boolean`, Default: `true` - -============================================================================== - 5.10 OPTS: FILTERS *nvim-tree-opts-filters* - -File / folder filters that may be toggled. - -*nvim-tree.filters.enable* -Enable / disable all filters including live filter. -Toggle via |nvim-tree-api.tree.toggle_enable_filters()| - Type: `boolean`, Default: `true` - -*nvim-tree.filters.git_ignored* -Ignore files based on `.gitignore`. Requires |git.enable| `= true` -Toggle via |nvim-tree-api.tree.toggle_gitignore_filter()|, default `I` - Type: `boolean`, Default: `true` - -*nvim-tree.filters.dotfiles* -Do not show dotfiles: files starting with a `.` -Toggle via |nvim-tree-api.tree.toggle_hidden_filter()|, default `H` - Type: `boolean`, Default: `false` - -*nvim-tree.filters.git_clean* -Do not show files with no git status. This will show ignored files when -|nvim-tree.filters.git_ignored| is set, as they are effectively dirty. -Toggle via |nvim-tree-api.tree.toggle_git_clean_filter()|, default `C` - Type: `boolean`, Default: `false` - -*nvim-tree.filters.no_buffer* -Do not show files that have no |buflisted()| buffer. -Toggle via |nvim-tree-api.tree.toggle_no_buffer_filter()|, default `B` -For performance reasons this may not immediately update on buffer -delete/wipe. A reload or filesystem event will result in an update. - Type: `boolean`, Default: `false` - -*nvim-tree.filters.no_bookmark* -Do not show files that are not bookmarked. -Toggle via |nvim-tree-api.tree.toggle_no_bookmark_filter()|, default `M` - Type: `boolean`, Default: `false` - -*nvim-tree.filters.custom* -Custom list of vim regex for file/directory names that will not be shown. -Backslashes must be escaped e.g. "^\\.git". See |string-match|. -Toggle via |nvim-tree-api.tree.toggle_custom_filter()|, default `U` - Type: {string} | `function(absolute_path)`, Default: `{}` - -*nvim-tree.filters.exclude* -List of directories or files to exclude from filtering: always show them. -Overrides `filters.git_ignored`, `filters.dotfiles` and `filters.custom`. - Type: {string}, Default: `{}` - -============================================================================== - 5.11 OPTS: LIVE FILTER *nvim-tree-opts-live-filter* - -Configurations for the live_filtering feature. -The live filter allows you to filter the tree nodes dynamically, based on -regex matching (see |vim.regex|). -This feature is bound to the `f` key by default. -The filter can be cleared with the `F` key by default. - -*nvim-tree.live_filter.prefix* -Prefix of the filter displayed in the buffer. - Type: `string`, Default: `"[FILTER]: "` - -*nvim-tree.live_filter.always_show_folders* -Whether to filter folders or not. - Type: `boolean`, Default: `true` - -============================================================================== - 5.12 OPTS: FILESYSTEM WATCHERS *nvim-tree-opts-filesystem-watchers* - -Will use file system watcher (libuv fs_event) to watch the filesystem for -changes. -Using this will disable BufEnter / BufWritePost events in nvim-tree which -were used to update the whole tree. With this feature, the tree will be -updated only for the appropriate folder change, resulting in better -performance. - -*nvim-tree.filesystem_watchers.enable* -Enable / disable the feature. - Type: `boolean`, Default: `true` - -*nvim-tree.filesystem_watchers.debounce_delay* -Idle milliseconds between filesystem change and action. - Type: `number`, Default: `50` (ms) - -*nvim-tree.filesystem_watchers.ignore_dirs* -List of vim regex for absolute directory paths that will not be watched or -function returning whether a path should be ignored. -Strings must be backslash escaped e.g. `"my-proj/\\.build$"`. See |string-match|. -Function is passed an absolute path. -Useful when path is not in `.gitignore` or git integration is disabled. - Type: `string[] | fun(path: string): boolean`, Default: >lua - { - "/.ccls-cache", - "/build", - "/node_modules", - "/target", - } -< -============================================================================== - 5.13 OPTS: ACTIONS *nvim-tree-opts-actions* - -*nvim-tree.actions.use_system_clipboard* -A boolean value that toggle the use of system clipboard when copy/paste -function are invoked. When enabled, copied text will be stored in registers -'+' (system), otherwise, it will be stored in '1' and '"'. - Type: `boolean`, Default: `true` - -*nvim-tree.actions.change_dir* -vim |current-directory| behaviour. - - *nvim-tree.actions.change_dir.enable* - Change the working directory when changing directories in the tree. - Type: `boolean`, Default: `true` - - *nvim-tree.actions.change_dir.global* - Use `:cd` instead of `:lcd` when changing directories. - Type: `boolean`, Default: `false` - - *nvim-tree.actions.change_dir.restrict_above_cwd* - Restrict changing to a directory above the global cwd. - Type: `boolean`, Default: `false` - -*nvim-tree.actions.expand_all* -Configuration for |nvim-tree-api.tree.expand_all()| and -|nvim-tree-api.node.expand()| - - *nvim-tree.actions.expand_all.max_folder_discovery* - Limit the number of folders being explored when expanding every folders. - Avoids hanging neovim when running this action on very large folders. - Type: `number`, Default: `300` - - *nvim-tree.actions.expand_all.exclude* - A list of directories that should not be expanded automatically. - E.g `{ ".git", "target", "build" }` etc. - Type: `table`, Default: `{}` - -*nvim-tree.actions.file_popup* -Configuration for file_popup behaviour. - - *nvim-tree.actions.file_popup.open_win_config* - Floating window config for file_popup. See |nvim_open_win| for more details. - You shouldn't define `"width"` and `"height"` values here. They will be - overridden to fit the file_popup content. - Type: `table`, Default: - `{` - `col = 1,` - `row = 1,` - `relative = "cursor",` - `border = "shadow",` - `style = "minimal",` - `}` - -*nvim-tree.actions.open_file* -Configuration options for opening a file from nvim-tree. - - *nvim-tree.actions.open_file.quit_on_open* - Closes the explorer when opening a file. - Type: `boolean`, Default: `false` - - *nvim-tree.actions.open_file.eject* - Prevent new opened file from opening in the same window as the tree. - Type: `boolean`, Default: `true` - - *nvim-tree.actions.open_file.resize_window* - Resizes the tree when opening a file. - Type: `boolean`, Default: `true` - - *nvim-tree.actions.open_file.window_picker* - Window picker configuration. - - *nvim-tree.actions.open_file.window_picker.enable* - Enable the feature. If the feature is not enabled, files will open in - window from which you last opened the tree, obeying - |nvim-tree.actions.open_file.window_picker.exclude| - Type: `boolean`, Default: `true` - - *nvim-tree.actions.open_file.window_picker.picker* - Change the default window picker: a string `"default"` or a function. - The function should return the window id that will open the node, - or `nil` if an invalid window is picked or user cancelled the action. - The picker may create a new window. - Type: `string` | `function`, Default: `"default"` - e.g. s1n7ax/nvim-window-picker plugin: >lua - window_picker = { - enable = true, - picker = require("window-picker").pick_window, -< - *nvim-tree.actions.open_file.window_picker.chars* - A string of chars used as identifiers by the window picker. - Type: `string`, Default: `"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"` - - *nvim-tree.actions.open_file.window_picker.exclude* - Table of buffer option names mapped to a list of option values. - Windows containing matching buffers will not be: - - available when using a window picker - - selected when not using a window picker - Type: `table`, Default: >lua - { - filetype = { - "notify", - "packer", - "qf", - "diff", - "fugitive", - "fugitiveblame", - }, - buftype = { - "nofile", - "terminal", - "help", - }, - } -< -*nvim-tree.actions.remove_file.close_window* -Close any window displaying a file when removing the file from the tree. - Type: `boolean`, Default: `true` - -============================================================================== - 5.14 OPTS: TRASH *nvim-tree-opts-trash* - -*nvim-tree.trash.cmd* -The command used to trash items (must be installed on your system). -Default `"gio trash"` from glib2 is a commonly shipped linux package. -macOS default `"trash"` requires the homebrew package `trash` -Windows default `"trash"` requires `trash-cli` or similar - Type: `string`, Default: `"gio trash"` or `"trash"` - -============================================================================== - 5.15 OPTS: TAB *nvim-tree-opts-tab* - -*nvim-tree.tab.sync* -Configuration for syncing nvim-tree across tabs. - - *nvim-tree.tab.sync.open* - Opens the tree automatically when switching tabpage or opening a new - tabpage if the tree was previously open. - Type: `boolean`, Default: `false` - - *nvim-tree.tab.sync.close* - Closes the tree across all tabpages when the tree is closed. - Type: `boolean`, Default: `false` - - *nvim-tree.tab.sync.ignore* - List of filetypes or buffer names on new tab that will prevent - |nvim-tree.tab.sync.open| and |nvim-tree.tab.sync.close| - Type: {string}, Default: `{}` - -============================================================================== - 5.16 OPTS: NOTIFY *nvim-tree-opts-notify* - -*nvim-tree.notify.threshold* -Specify minimum notification level, uses the values from |vim.log.levels| - Type: `enum`, Default: `vim.log.levels.INFO` - -`ERROR`: hard errors e.g. failure to read from the file system. -`WARNING`: non-fatal errors e.g. unable to system open a file. -`INFO:` information only e.g. file copy path confirmation. -`DEBUG:` information for troubleshooting, e.g. failures in some window closing operations. - -*nvim-tree.notify.absolute_path* -Whether to use absolute paths or item names in fs action notifications. - Type: `boolean`, Default: `true` - -============================================================================== - 5.17 OPTS: HELP *nvim-tree-opts-help* - -*nvim-tree.help.sort_by* -Defines how mappings are sorted in the help window. -Can be `"key"` (sort alphabetically by keymap) -or `"desc"` (sort alphabetically by description). - Type: `string`, Default: `"key"` - -============================================================================== - 5.18 OPTS: UI *nvim-tree-opts-ui* - -*nvim-tree.ui.confirm* -Confirmation prompts. - - *nvim-tree.ui.confirm.remove* - Prompt before removing. - Type: `boolean`, Default: `true` - - *nvim-tree.ui.confirm.trash* - Prompt before trashing. - Type: `boolean`, Default: `true` - - *nvim-tree.ui.confirm.default_yes* - If `true` the prompt will be `"Y/n"`, otherwise `"y/N"`. - Type: `boolean`, Default: `false` - -============================================================================== - 5.19 OPTS: BOOKMARKS *nvim-tree-opts-bookmarks* - -*nvim-tree.bookmarks.persist* -Persist bookmarks to a json file containing a list of absolute paths. -Type: `boolean` | `string`, Default: `false` - -`true`: use default: `stdpath("data") .. "/nvim-tree-bookmarks.json"` -`string`: absolute path of your choice. - -============================================================================== - 5.20 OPTS: EXPERIMENTAL *nvim-tree-opts-experimental* - -*nvim-tree.experimental* -Experimental features that may become default or optional functionality. -In the event of a problem please disable the experiment and raise an issue. - -============================================================================== - 5.21 OPTS: LOG *nvim-tree-opts-log* - -Configuration for diagnostic logging. - -*nvim-tree.log.enable* -Enable logging to a file `nvim-tree.log` in |stdpath| `"log"`, usually -`${XDG_STATE_HOME}/nvim` - Type: `boolean`, Default: `false` - -*nvim-tree.log.truncate* -Remove existing log file at startup. - Type: `boolean`, Default: `false` - -*nvim-tree.log.types* -Specify which information to log. - - *nvim-tree.log.types.all* - Everything. - Type: `boolean`, Default: `false` - - *nvim-tree.log.types.profile* - Timing of some operations. - Type: `boolean`, Default: `false` - - *nvim-tree.log.types.config* - Options and mappings, at startup. - Type: `boolean`, Default: `false` - - *nvim-tree.log.types.copy_paste* - File copy and paste actions. - Type: `boolean`, Default: `false` - - *nvim-tree.log.types.dev* - Used for local development only. Not useful for users. - Type: `boolean`, Default: `false` - - *nvim-tree.log.types.diagnostics* - LSP and COC processing, verbose. - Type: `boolean`, Default: `false` - - *nvim-tree.log.types.git* - Git processing, verbose. - Type: `boolean`, Default: `false` - - *nvim-tree.log.types.watcher* - |nvim-tree.filesystem_watchers| processing, verbose. - Type: `boolean`, Default: `false` - -============================================================================== - 6. API *nvim-tree-api* +API *nvim-tree-api* Nvim-tree's public API can be used to access features. e.g. >lua local api = require("nvim-tree.api") @@ -1742,7 +620,7 @@ Functions accepting {node} as their first argument will use the node under the cursor when that argument is not present or nil. ============================================================================== - 6.1 API TREE *nvim-tree-api.tree* +API: Tree *nvim-tree-api.tree* tree.open({opts}) *nvim-tree-api.tree.open()* Open the tree, focusing it if already open. @@ -1757,7 +635,7 @@ tree.open({opts}) *nvim-tree-api.tree.open()* overrides {current_window} • {find_file} (boolean) find the current buffer • {update_root} (boolean) requires {find_file}, see - |nvim-tree.update_focused_file.update_root| + |nvim_tree.Config.UpdateFocusedFile| {update_root} tree.toggle({opts}) *nvim-tree-api.tree.toggle()* Open or close the tree. @@ -1772,11 +650,11 @@ tree.toggle({opts}) *nvim-tree-api.tree.toggle()* overrides {current_window} • {find_file} (boolean) find the current buffer • {update_root} (boolean) requires {find_file}, see - |nvim-tree.update_focused_file.update_root| + |nvim_tree.Config.UpdateFocusedFile| {update_root} • {focus} (boolean) focus the tree when opening, default true tree.close() *nvim-tree-api.tree.close()* - Close the tree, affecting all tabs as per |nvim-tree.tab.sync.close| + Close the tree, affecting all tabs as per |nvim_tree.Config.Tab.Sync| {close} tree.close_in_this_tab() *nvim-tree-api.tree.close_in_this_tab()* Close the tree in this tab only. @@ -1786,21 +664,21 @@ tree.close_in_all_tabs() *nvim-tree-api.tree.close_in_all_tabs()* tree.focus() *nvim-tree-api.tree.focus()* Focus the tree, opening it if necessary. - Retained for compatibility, use |tree.open()| with no arguments instead. + Retained for compatibility, use |nvim-tree-api.tree.open()| with no arguments instead. tree.reload() *nvim-tree-api.tree.reload()* Refresh the tree. Does nothing if closed. tree.resize({opts}) *nvim-tree-api.tree.resize()* Resize the tree, persisting the new size. - Resets to |nvim-tree.view.width| when no {opts} provided. + Resets to |nvim_tree.Config.View| {width} when no {opts} provided. See |:NvimTreeResize| Parameters: ~ • {opts} (table) optional parameters Options: ~ - • {width} (table) new |nvim-tree.view.width| value + • {width} (table) new |nvim_tree.Config.View| {width} value • {absolute} (number) set the width • {relative} (number) increase or decrease the width @@ -1853,7 +731,7 @@ tree.find_file({opts}) *nvim-tree-api.tree.find_file()* • {current_window} (boolean) requires {open}, open in the current window • {winid} (number) open the tree in the specified |winid|, overrides {current_window} - • {update_root} (boolean) see |nvim-tree.update_focused_file.update_root| + • {update_root} (boolean) see |nvim_tree.Config.UpdateFocusedFile| {update_root} • {focus} (boolean) focus the tree tree.search_node() *nvim-tree-api.tree.search_node()* @@ -1882,31 +760,31 @@ tree.expand_all({node}, {opts}) *nvim-tree-api.tree.expand_all()* *nvim-tree-api.tree.toggle_enable_filters()* tree.toggle_enable_filters() - Toggle |nvim-tree.filters.enable| all filters. + Toggle |nvim_tree.Config.Filters| {enable} all filters. *nvim-tree-api.tree.toggle_gitignore_filter()* tree.toggle_gitignore_filter() - Toggle |nvim-tree.filters.git_ignored| filter. + Toggle |nvim_tree.Config.Filters| {git_ignored} filter. *nvim-tree-api.tree.toggle_git_clean_filter()* tree.toggle_git_clean_filter() - Toggle |nvim-tree.filters.git_clean| filter. + Toggle |nvim_tree.Config.Filters| {git_clean} filter. *nvim-tree-api.tree.toggle_no_buffer_filter()* tree.toggle_no_buffer_filter() - Toggle |nvim-tree.filters.no_buffer| filter. + Toggle |nvim_tree.Config.Filters| {no_buffer} filter. *nvim-tree-api.tree.toggle_no_bookmark_filter()* tree.toggle_no_bookmark_filter() - Toggle |nvim-tree.filters.no_bookmark| filter. + Toggle |nvim_tree.Config.Filters| {no_bookmark} filter. *nvim-tree-api.tree.toggle_custom_filter()* tree.toggle_custom_filter() - Toggle |nvim-tree.filters.custom| filter. + Toggle |nvim_tree.Config.Filters| {custom} filter. *nvim-tree-api.tree.toggle_hidden_filter()* tree.toggle_hidden_filter() - Toggle |nvim-tree.filters.dotfiles| filter. + Toggle |nvim_tree.Config.Filters| {dotfiles} filter. tree.toggle_help() *nvim-tree-api.tree.toggle_help()* Toggle help view. @@ -1946,7 +824,7 @@ tree.winid({opts}) *nvim-tree-api.tree.winid()* (number) winid or nil if tree is not visible ============================================================================== - 6.2 API FILE SYSTEM *nvim-tree-api.fs* +API: File System *nvim-tree-api.fs* fs.create({node}) *nvim-tree-api.fs.create()* Prompt to create a file or directory. Use a trailing `/` for a directory. @@ -1962,7 +840,7 @@ fs.remove({node}) *nvim-tree-api.fs.remove()* • {node} (Node|nil) file or folder fs.trash({node}) *nvim-tree-api.fs.trash()* - Trash a file or folder as per |nvim-tree.trash| + Trash a file or folder as per |nvim_tree.Config.Trash| Parameters: ~ • {node} (Node|nil) file or folder @@ -2048,13 +926,10 @@ fs.print_clipboard() *nvim-tree-api.fs.print_clipboard()* Print the contents of the nvim-tree clipboard. ============================================================================== - 6.3 API NODE *nvim-tree-api.node* - -Parameters: ~ - • {node} (Node|nil) file or folder +API: Node *nvim-tree-api.node* -node.open.edit({node}, {opts}) *nvim-tree-api.node.open.edit()* - File: open as per |nvim-tree.actions.open_file| +node.open.edit({node}, {opts}) *nvim-tree-api.node.open.edit()* + File: open as per |nvim_tree.Config.Actions.OpenFile| Folder: expand or collapse Root: change directory up @@ -2068,13 +943,12 @@ node.open.edit({node}, {opts}) *nvim-tree-api.node.open.e *nvim-tree-api.node.open.replace_tree_buffer()* node.open.replace_tree_buffer({node}) - |nvim-tree-api.node.edit()|, file will be opened in place: in the + |nvim-tree-api.node.open.edit()|, file will be opened in place: in the nvim-tree window. *nvim-tree-api.node.open.no_window_picker()* node.open.no_window_picker({node}, {opts}) - |nvim-tree-api.node.edit()|, window picker will never be used as per - |nvim-tree.actions.open_file.window_picker.enable| `false` + |nvim-tree-api.node.open.edit()|, window picker will be bypassed. Parameters: ~ • {node} (Node|nil) file or folder @@ -2085,7 +959,7 @@ node.open.no_window_picker({node}, {opts}) • {focus} (boolean) keep focus in the tree when opening the file node.open.vertical({node}, {opts}) *nvim-tree-api.node.open.vertical()* - |nvim-tree-api.node.edit()|, file will be opened in a new vertical split. + |nvim-tree-api.node.open.edit()|, file will be opened in a new vertical split. Parameters: ~ • {node} (Node|nil) file or folder @@ -2097,8 +971,7 @@ node.open.vertical({node}, {opts}) *nvim-tree-api.node.open.verti *nvim-tree-api.node.open.vertical_no_picker()* node.open.vertical_no_picker({node}, {opts}) - |nvim-tree-api.node.vertical()|, window picker will never be used as per - |nvim-tree.actions.open_file.window_picker.enable| `false` + |nvim-tree-api.node.open.vertical()|, window picker will be bypassed. Parameters: ~ • {node} (Node|nil) file or folder @@ -2109,7 +982,7 @@ node.open.vertical_no_picker({node}, {opts}) • {focus} (boolean) keep focus in the tree when opening the file node.open.horizontal({node}, {opts}) *nvim-tree-api.node.open.horizontal()* - |nvim-tree-api.node.edit()|, file will be opened in a new horizontal split. + |nvim-tree-api.node.open.edit()|, file will be opened in a new horizontal split. Parameters: ~ • {node} (Node|nil) file or folder @@ -2121,8 +994,7 @@ node.open.horizontal({node}, {opts}) *nvim-tree-api.node.open.horizon *nvim-tree-api.node.open.horizontal_no_picker()* node.open.horizontal_no_picker({node}, {opts}) - |nvim-tree-api.node.horizontal()|, window picker will never be used as per - |nvim-tree.actions.open_file.window_picker.enable| `false` + |nvim-tree-api.node.open.horizontal()|, window picker will be bypassed. Parameters: ~ • {node} (Node|nil) file or folder @@ -2134,9 +1006,9 @@ node.open.horizontal_no_picker({node}, {opts}) *nvim-tree-api.node.open.toggle_group_empty()* node.open.toggle_group_empty({node}, {opts}) - Toggle |nvim-tree.renderer.group_empty| for a specific folder. + Toggle |nvim_tree.Config.Renderer| {group_empty} for a specific folder. Does nothing on files. - Needs |nvim-tree.renderer.group_empty| set. + Needs |nvim_tree.Config.Renderer| {group_empty} set. Parameters: ~ • {node} (Node|nil) file or folder @@ -2156,7 +1028,7 @@ node.open.drop({node}) *nvim-tree-api.node.open.drop()* Root: change directory up node.open.tab({node}, {opts}) *nvim-tree-api.node.open.tab()* - |nvim-tree-api.node.edit()|, file will be opened in a new tab. + |nvim-tree-api.node.open.edit()|, file will be opened in a new tab. Parameters: ~ • {node} (Node|nil) file or folder @@ -2176,7 +1048,7 @@ node.open.tab_drop({node}) Root: change directory up node.open.preview({node}, {opts}) *nvim-tree-api.node.open.preview()* - |nvim-tree-api.node.edit()|, file buffer will have |bufhidden| set to `delete`. + |nvim-tree-api.node.open.edit()|, file buffer will have |'bufhidden'| set to `delete`. Parameters: ~ • {node} (Node|nil) file or folder @@ -2188,9 +1060,8 @@ node.open.preview({node}, {opts}) *nvim-tree-api.node.open.prev *nvim-tree-api.node.open.preview_no_picker()* node.open.preview_no_picker({node}, {opts}) - |nvim-tree-api.node.edit()|, file buffer will have |bufhidden| set to `delete`. - window picker will never be used as per - |nvim-tree.actions.open_file.window_picker.enable| `false` + |nvim-tree-api.node.open.edit()|, file buffer will have |'bufhidden'| set to `delete`. + window picker will be bypassed. Parameters: ~ • {node} (Node|nil) file or folder @@ -2207,11 +1078,11 @@ node.navigate.git.next({node}) *nvim-tree-api.node.navigate.git.next()* node.navigate.git.next_recursive({node}) Alternative to |nvim-tree-api.node.navigate.git.next()| that navigates to the next file showing git status, recursively. - Needs |nvim-tree.git.show_on_dirs| set. + Needs |nvim_tree.Config.Git| {show_on_dirs} set. *nvim-tree-api.node.navigate.git.next_skip_gitignored()* node.navigate.git.next_skip_gitignored({node}) - Same as |node.navigate.git.next()|, but skips gitignored files. + Same as |nvim-tree-api.node.navigate.git.next()|, but skips gitignored files. node.navigate.git.prev({node}) *nvim-tree-api.node.navigate.git.prev()* Navigate to the previous item showing git status. @@ -2220,11 +1091,11 @@ node.navigate.git.prev({node}) *nvim-tree-api.node.navigate.git.prev()* node.navigate.git.prev_recursive({node}) Alternative to |nvim-tree-api.node.navigate.git.prev()| that navigates to the previous file showing git status, recursively. - Needs |nvim-tree.git.show_on_dirs| set. + Needs |nvim_tree.Config.Git| {show_on_dirs} set. *nvim-tree-api.node.navigate.git.prev_skip_gitignored()* node.navigate.git.prev_skip_gitignored({node}) - Same as |node.navigate.git.prev()|, but skips gitignored files. + same as |nvim-tree-api.node.navigate.git.prev()|, but skips gitignored files. *nvim-tree-api.node.navigate.diagnostics.next()* node.navigate.diagnostics.next({node}) @@ -2234,7 +1105,7 @@ node.navigate.diagnostics.next({node}) node.navigate.diagnostics.next_recursive({node}) Alternative to |nvim-tree-api.node.navigate.diagnostics.next()| that navigates to the next file showing diagnostic status, recursively. - Needs |nvim-tree.diagnostics.show_on_dirs| set. + Needs |nvim_tree.Config.Diagnostics| {show_on_dirs} set. *nvim-tree-api.node.navigate.diagnostics.prev()* node.navigate.diagnostics.prev({node}) @@ -2244,17 +1115,17 @@ node.navigate.diagnostics.prev({node}) node.navigate.diagnostics.prev_recursive({node}) Alternative to |nvim-tree-api.node.navigate.diagnostics.prev()| that navigates to the previous file showing diagnostic status, recursively. - Needs |nvim-tree.diagnostics.show_on_dirs| set. + Needs |nvim_tree.Config.Diagnostics| {show_on_dirs} set. *nvim-tree-api.node.navigate.opened.next()* node.navigate.opened.next({node}) Navigate to the next |bufloaded()| item. - See |nvim-tree.renderer.highlight_opened_files| + See |nvim_tree.Config.Renderer| {highlight_opened_files} *nvim-tree-api.node.navigate.opened.prev()* node.navigate.opened.prev({node}) Navigate to the previous |bufloaded()| item. - See |nvim-tree.renderer.highlight_opened_files| + See |nvim_tree.Config.Renderer| {highlight_opened_files} *nvim-tree-api.node.navigate.sibling.next()* node.navigate.sibling.next({node}) @@ -2278,7 +1149,7 @@ node.navigate.parent({node}) *nvim-tree-api.node.navigate.parent_close()* node.navigate.parent_close({node}) - |api.node.navigate.parent()|, closing that folder. + |nvim-tree-api.node.navigate.parent()|, closing that folder. node.show_info_popup({node}) *nvim-tree-api.node.show_info_popup()* Open a popup window showing: fullpath, size, accessed, modified, created. @@ -2288,7 +1159,7 @@ node.run.cmd({node}) *nvim-tree-api.node.run.cmd()* of the line. node.run.system({node}) *nvim-tree-api.node.run.system()* - Execute |nvim-tree.system_open| + Execute |nvim_tree.Config.SystemOpen| node.buffer.delete({node}, {opts}) *nvim-tree-api.node.buffer.delete()* Deletes node's related buffer, if one exists. @@ -2336,13 +1207,13 @@ node.collapse({node}, {opts}) *nvim-tree-api.node.collapse()* • {keep_buffers} (boolean) do not collapse nodes with open buffers. ============================================================================== - 6.4 API GIT *nvim-tree-api.git* +API: Git *nvim-tree-api.git* git.reload() *nvim-tree-api.git.reload()* Update the git status of the entire tree. ============================================================================== - 6.5 API EVENTS *nvim-tree-api.events* +API: Events *nvim-tree-api.events* *nvim-tree-api.events.subscribe()* events.subscribe({event_type}, {callback}) @@ -2357,17 +1228,17 @@ events.Event *nvim-tree-api.events.Event* ============================================================================== - 6.6 API LIVE FILTER *nvim-tree-api.live_filter* +API: Live Filter *nvim-tree-api.live_filter* live_filter.start() *nvim-tree-api.live_filter.start()* - Enter |nvim-tree.live_filter| mode. + Enter |nvim-tree-api.live_filter| mode. Opens an input window with |filetype| `"NvimTreeFilter"` live_filter.clear() *nvim-tree-api.live_filter.clear()* - Exit |nvim-tree.live_filter| mode. + Exit |nvim-tree-api.live_filter| mode. ============================================================================== - 6.7 API MARKS *nvim-tree-api.marks* +API: Marks *nvim-tree-api.marks* marks.get({node}) *nvim-tree-api.marks.get()* Return the node if it is marked. @@ -2401,8 +1272,8 @@ marks.bulk.move() *nvim-tree-api.marks.bulk.move()* marks.navigate.next() *nvim-tree-api.marks.navigate.next()* Navigate to the next marked node, wraps. - Opens files as per |nvim-tree.actions.open_file| - Works best with |nvim-tree.update_focused_file| enabled. + Opens files as per |nvim_tree.Config.Actions.OpenFile| + Works best with |nvim_tree.Config.UpdateFocusedFile| enabled. marks.navigate.prev() *nvim-tree-api.marks.navigate.prev()* As per |nvim-tree-api.marks.navigate.next()| @@ -2412,19 +1283,19 @@ marks.navigate.select() *nvim-tree-api.marks.navigate.select()* A folder will be focused, a file will be opened. ============================================================================== - 6.8 API CONFIG *nvim-tree-api.config* +API: Config *nvim-tree-api.config* *nvim-tree-api.config.mappings.default_on_attach()* config.mappings.default_on_attach({bufnr}) - Set all |nvim-tree-mappings-default|. Call from your |nvim-tree.on_attach| + Set all |nvim-tree-mappings-default|. Call from your |nvim_tree.Config| {on_attach} Parameters: ~ - • {bufnr} (number) nvim-tree buffer number passed to |nvim-tree.on_attach| + • {bufnr} (number) nvim-tree buffer number passed to |nvim_tree.Config| {on_attach} *nvim-tree-api.config.mappings.get_keymap()* config.mappings.get_keymap() Retrieves all buffer local mappings for nvim-tree. - These are the mappings that are applied by |nvim-tree.on_attach|, which + These are the mappings that are applied by |nvim_tree.Config| {on_attach}, which may include default mappings. Return: ~ @@ -2439,7 +1310,7 @@ config.mappings.get_keymap_default() (table) as per |nvim_buf_get_keymap()| ============================================================================== - 6.9 API COMMANDS *nvim-tree-api.commands* +API: Commands *nvim-tree-api.commands* commands.get() *nvim-tree-api.commands.get()* Retrieve all commands, see |nvim-tree-commands| @@ -2451,7 +1322,7 @@ commands.get() *nvim-tree-api.commands.get()* • {opts} (table) ============================================================================== - 6.10 DIAGNOSTICS *nvim-tree-api.diagnostics* +API: Diagnostics *nvim-tree-api.diagnostics* diagnostics.hi_test() *nvim-tree-api.diagnostics.hi_test()* Open a new buffer displaying all nvim-tree highlight groups, their link @@ -2460,9 +1331,9 @@ diagnostics.hi_test() *nvim-tree-api.diagnostics.hi_test()* Similar to `:so $VIMRUNTIME/syntax/hitest.vim` as per |:highlight| ============================================================================== - 7. MAPPINGS *nvim-tree-mappings* +Mappings *nvim-tree-mappings* -Mappings are set via the |nvim-tree.on_attach| function, which is run upon +Mappings are set via the |nvim_tree.Config| {on_attach} function, which is run upon creating the nvim-tree buffer. Mappings are usually |nvim-tree-api| functions however may be your own. @@ -2505,11 +1376,9 @@ The `on_attach` function is passed the `bufnr` of nvim-tree. Use --- }) < -Mouse support is defined in |KeyBindings| - Single left mouse mappings can be achieved via ``. -Single right / middle mouse mappings will require changes to |mousemodel| or |mouse|. +Single right / middle mouse mappings will require changes to |'mousemodel'| or |'mouse'|. |vim.keymap.set()| {rhs} is a `(function|string)` thus it may be necessary to define your own function to map complex functionality e.g. >lua @@ -2524,12 +1393,12 @@ define your own function to map complex functionality e.g. >lua vim.keymap.set("n", "", print_node_path, opts("Print Path")) < ============================================================================== - 7.1 MAPPINGS: DEFAULT *nvim-tree-mappings-default* +Mappings: Default *nvim-tree-mappings-default* -In the absence of an |nvim-tree.on_attach| function, the following defaults +In the absence of an |nvim_tree.Config| {on_attach} function, the following defaults will be applied. -You are encouraged to copy these to your own |nvim-tree.on_attach| function. >lua +You are encouraged to copy these to your own |nvim_tree.Config| {on_attach} function. >lua local api = require("nvim-tree.api") @@ -2598,7 +1467,7 @@ You are encouraged to copy these to your own |nvim-tree.on_attach| function. >lu vim.keymap.set("n", "<2-RightMouse>", api.tree.change_root_to_node, opts("CD")) -- END_DEFAULT_ON_ATTACH < -Alternatively, you may apply these default mappings from your |nvim-tree.on_attach| via +Alternatively, you may apply these default mappings from your |nvim_tree.Config| {on_attach} via |nvim-tree-api.config.mappings.default_on_attach()| e.g. >lua local function my_on_attach(bufnr) @@ -2614,7 +1483,7 @@ Alternatively, you may apply these default mappings from your |nvim-tree.on_atta end < ============================================================================== - 8. HIGHLIGHT *nvim-tree-highlight* +Highlight *nvim-tree-highlight* All the following highlight groups can be configured by hand. Aside from `NvimTreeWindowPicker`, it is not advised to colorize the background of these @@ -2623,7 +1492,7 @@ groups. Example |:highlight| >vim :hi NvimTreeSymlink guifg=blue gui=bold,underline < -It is recommended to enable |termguicolors| for the more pleasant 24-bit +It is recommended to enable |'termguicolors'| for the more pleasant 24-bit colours. To view the nvim-tree highlight groups run |:NvimTreeHiTest| @@ -2631,7 +1500,7 @@ To view the nvim-tree highlight groups run |:NvimTreeHiTest| To view all active highlight groups run `:so $VIMRUNTIME/syntax/hitest.vim` as per |:highlight| -The `*HL` groups are additive as per |nvim-tree-opts-renderer| precedence. +The `*HL` groups are additive as per |nvim_tree.Config.Renderer| precedence. Only present attributes will clobber each other. In this example a modified, opened file will have magenta text, with cyan undercurl: >vim @@ -2647,7 +1516,7 @@ To prevent usage of a highlight: :hi! link NvimTreeExecFile NONE < ============================================================================== - 8.1 HIGHLIGHT: DEFAULT *nvim-tree-highlight-default* +Highlight: Default *nvim-tree-highlight-default* |:highlight-link| `default` or |:highlight-default| define the groups on setup: @@ -2773,46 +1642,7 @@ Diagnostics Folder Highlight: > NvimTreeDiagnosticHintFolderHL NvimTreeDiagnosticHintFileHL < ============================================================================== - 8.2 HIGHLIGHT: OVERHAUL *nvim-tree-highlight-overhaul* - -See |nvim-tree-legacy-highlight| for old highlight group compatibility. - -2024-01-20: significant highlighting changes, some breaking: - -- Full cterm support. -- Standard vim highlight groups such |DiagnosticUnderlineError| are now the - defaults. -- Highlight groups named consistently. -- All `highlight_xxx` e.g. |nvim-tree.renderer.highlight_git| are granular, - allowing `"none"`, `"icon"`, `"name"` or `"all"` -- `highlight_xxx` has highlight groups for both File and Folder -- `highlight_xxx` is additive instead of overwriting. See - |nvim-tree-opts-renderer| for precedence. - -2024-01-29: disambiguate default highlights sharing groups: - -- NvimTreeRootFolder PreProc -> Title -- NvimTreeModified* Constant -> Type -- NvimTreeOpenedHL Constant -> Special -- NvimTreeBookmarkIcon Constant -> NvimTreeFolderIcon -- NvimTreeExecFile Constant -> SpellCap -- NvimTreeImageFile PreProc -> SpellCap -- NvimTreeSpecialFile PreProc -> SpellCap -- NvimTreeSymlink Statement -> SpellCap - -Approximate pre-overhaul values for the `SpellCap` groups may be set via: >lua - - vim.cmd([[ - :hi NvimTreeExecFile gui=bold guifg=#ffa0a0 - :hi NvimTreeSymlink gui=bold guifg=#ffff60 - :hi NvimTreeSpecialFile gui=bold,underline guifg=#ff80ff - :hi NvimTreeImageFile gui=bold guifg=#ff80ff - ]]) -< -============================================================================== - 9. EVENTS *nvim-tree-events* - -|nvim_tree_events| +Events *nvim-tree-events* nvim-tree will dispatch events whenever an action is made. These events can be subscribed to through handler functions. This allows for even further @@ -2822,7 +1652,7 @@ A handler for an event is just a function which receives one argument, the payload of the event. The payload is different for each event type. Refer to |nvim_tree_registering_handlers| for more information. -|nvim_tree_registering_handlers| +*nvim_tree_registering_handlers* Handlers are registered by calling |nvim-tree-api.events.subscribe()| function with an |nvim-tree-api.events.Event| @@ -2836,7 +1666,7 @@ e.g. handler for node renamed: >lua print("Node renamed from " .. data.old_name .. " to " .. data.new_name) end) < -|nvim_tree_events_kind| +*nvim_tree_events_kind* - Event.Ready When NvimTree has been initialized. @@ -2844,7 +1674,7 @@ e.g. handler for node renamed: >lua - Event.TreePreOpen Invoked before the window and buffer for NvimTree are created - or opened. Before |Event.TreeOpen| event. + or opened. Before `Event.TreeOpen` • Note: Handler takes no parameter. - Event.TreeOpen @@ -2900,20 +1730,20 @@ e.g. handler for node renamed: >lua - Event.TreeAttachedPost Invoked after the tree's buffer has been created and mappings - have been applied: |nvim-tree-mappings| or |nvim-tree.on_attach| + have been applied: |nvim-tree-mappings| or |nvim_tree.Config| {on_attach} handler parameters: ~ {buf} `{number} `API buffer handle (buffer number) - Event.TreeRendered Invoked every time the tree is redrawn. Normally this event - happens after |Event.TreeOpen| except that handlers of this + happens after `Event.TreeOpen` except that handlers of this one will have access to the tree buffer populated with the final content. handler parameters: ~ {bufnr} `{number} `API buffer handle (buffer number) {winnr} `{number} `API window handle (window number) -|nvim_tree_events_startup| +*nvim_tree_events_startup* There are two special startup events in the form of User autocommands: @@ -2933,10 +1763,10 @@ Example subscription: >lua }) < ============================================================================== - 10. PROMPTS *nvim-tree-prompts* +Prompts *nvim-tree-prompts* -Some NvimTree actions use the builtin |vim.ui.select| prompt API for -confirmations when the |nvim_tree.select_prompts| option is set. +Some NvimTree actions use the builtin |vim.ui.select()| prompt API for +confirmations when the |nvim_tree.Config| {select_prompts} option is set. The API accepts the optional `kind` key as part of the {opts} parameter, which can can be used to identify the type of prompt, to allow user side @@ -2958,7 +1788,7 @@ configurations for different types of prompts. send all bookmarked to trash during |nvim-tree-api.marks.bulk.trash()| ============================================================================== - 11. DECORATORS *nvim-tree-decorators* +Decorators *nvim-tree-decorators* Highlighting and icons for nodes are provided by Decorators. You may provide your own in addition to the builtin decorators. @@ -2969,14 +1799,12 @@ Decorators may: - Override node icon Create a `nvim_tree.api.decorator.UserDecorator` class and register it with -precedence via |nvim-tree.renderer.decorators| +precedence via |nvim_tree.Config.Renderer| {decorators} See |nvim-tree-decorator-example| -See `nvim-tree/_meta/api_decorator.lua` for full class documentation. - ============================================================================== - 11.1. DECORATOR EXAMPLE *nvim-tree-decorator-example* +Decorators: Example *nvim-tree-decorator-example* A decorator class for nodes named "example", overridind all builtin decorators except for Cut. @@ -3071,18 +1899,18 @@ Contents of `my-decorator.lua`: return MyDecorator < ============================================================================== - 12. OS SPECIFIC RESTRICTIONS *nvim-tree-os-specific* +OS Specific Restrictions *nvim-tree-os-specific* Windows WSL and PowerShell - Trash is synchronized - Executable file detection is disabled as this is non-performant and can - freeze nvim + freeze Nvim - Some filesystem watcher error related to permissions will not be reported ============================================================================== - 13. NETRW *nvim-tree-netrw* +netrw *nvim-tree-netrw* -|netrw| is a standard neovim plugin that is enabled by default. It provides, +|netrw| is a standard Nvim plugin that is enabled by default. It provides, amongst other functionality, a file/directory browser. It interferes with nvim-tree and the intended user experience is nvim-tree @@ -3097,37 +1925,37 @@ must be disabled manually at the start of your `init.lua` as per |netrw-noload|: There are many |netrw| features beyond the file browser. If you want to keep using |netrw| without its browser features please ensure: -|nvim-tree.disable_netrw| `= false` -|nvim-tree.hijack_netrw| ` = true` +|nvim_tree.Config| {disable_netrw}` = false` +|nvim_tree.Config| {hijack_netrw}` = true` ============================================================================== - 14. LEGACY *nvim-tree-legacy* +Legacy *nvim-tree-legacy* Breaking refactors have been made however the legacy versions will be silently migrated and used. There are no plans to remove this migration. ============================================================================== - 14.1 LEGACY: OPTS *nvim-tree-legacy-opts* +Legacy: Config *nvim-tree-legacy-opts* -Legacy options are translated to the current, making type and value changes as +Legacy config is translated to the current, making type and value changes as needed. -`update_cwd` |nvim-tree.sync_root_with_cwd| -`update_focused_file.update_cwd` |nvim-tree.update_focused_file.update_root| -`open_on_tab` |nvim-tree.tab.sync.open| -`ignore_buf_on_tab_change` |nvim-tree.tab.sync.ignore| -`renderer.root_folder_modifier` |nvim-tree.renderer.root_folder_label| -`update_focused_file.debounce_delay` |nvim-tree.view.debounce_delay| -`trash.require_confirm` |nvim-tree.ui.confirm.trash| -`view.adaptive_size` |nvim-tree.view.width| -`sort_by` |nvim-tree.sort.sorter| -`git.ignore` |nvim-tree.filters.git_ignored| -`renderer.icons.webdev_colors` |nvim-tree.renderer.icons.web_devicons.file.color| -`renderer.icons.padding` |nvim-tree.renderer.icons.padding.icon| +`update_cwd` |nvim_tree.Config| {sync_root_with_cwd} +`update_focused_file.update_cwd` |nvim_tree.Config.UpdateFocusedFile| {update_root} +`open_on_tab` |nvim_tree.Config.Tab.Sync| {open} +`ignore_buf_on_tab_change` |nvim_tree.Config.Tab.Sync| {ignore} +`renderer.root_folder_modifier` |nvim_tree.Config.Renderer| {root_folder_label} +`update_focused_file.debounce_delay` |nvim_tree.Config.View| {debounce_delay} +`trash.require_confirm` |nvim_tree.Config.UI.Confirm| {trash} +`view.adaptive_size` |nvim_tree.Config.View| {width} +`sort_by` |nvim_tree.Config.Sort| {sorter} +`git.ignore` |nvim_tree.Config.Filters| {git_ignored} +`renderer.icons.webdev_colors` |nvim_tree.Config.Renderer.Icons.WebDevicons.File| {color} +`renderer.icons.padding` |nvim_tree.Config.Renderer.Icons.Padding| {icon} ============================================================================== - 14.2 LEGACY: HIGHLIGHT *nvim-tree-legacy-highlight* +Legacy: Highlight *nvim-tree-legacy-highlight* Legacy highlight group are still obeyed when they are defined and the current highlight group is not, hard linking as follows: > @@ -3175,288 +2003,1063 @@ highlight group is not, hard linking as follows: > NvimTreeLspDiagnosticsInformationFolderText NvimTreeDiagnosticInfoFolderHL NvimTreeLspDiagnosticsHintFolderText NvimTreeDiagnosticHintFolderHL < + ============================================================================== - 15 INDEX *nvim-tree-index* +Hidden Display *nvim-tree-hidden-display* + +Show a summary of hidden files below the tree highlighted with `NvimTreeHiddenDisplay + +Configure via |nvim_tree.Config.Renderer| {hidden_display} + + *nvim_tree.Config.Renderer.HiddenDisplay* + • `none`: disabled + • `simple`: show how many hidden files are in a folder + • `all`: show how many hidden and the number of hidden files by reason + • `fun(hidden_stats: table): string`: returns a summary of hidden stats + +Example `"all"`: +If a folder has 14 hidden items for various reasons, the display might show: > + (14 total git: 5, dotfile: 9) +< +If a function is provided, it receives a table `hidden_stats` where keys are +reasons and values are the count of hidden files for that reason. + +The `hidden_stats` argument is structured as follows, where is the number +of hidden files related to the field: > + hidden_stats = { + bookmark = , + buf = , + custom = , + dotfile = , + git = , + live_filter = , + } +< +Example of function that can be passed: >lua + function(hidden_stats) + local total_count = 0 + for reason, count in pairs(hidden_stats) do + total_count = total_count + count + end + + if total_count > 0 then + return "(" .. tostring(total_count) .. " hidden)" + end + return nil + end +< ============================================================================== - 15.1 INDEX: OPTS *nvim-tree-index-opts* - -|nvim-tree.actions.change_dir| -|nvim-tree.actions.change_dir.enable| -|nvim-tree.actions.change_dir.global| -|nvim-tree.actions.change_dir.restrict_above_cwd| -|nvim-tree.actions.expand_all| -|nvim-tree.actions.expand_all.exclude| -|nvim-tree.actions.expand_all.max_folder_discovery| -|nvim-tree.actions.file_popup| -|nvim-tree.actions.file_popup.open_win_config| -|nvim-tree.actions.open_file| -|nvim-tree.actions.open_file.eject| -|nvim-tree.actions.open_file.quit_on_open| -|nvim-tree.actions.open_file.resize_window| -|nvim-tree.actions.open_file.window_picker| -|nvim-tree.actions.open_file.window_picker.chars| -|nvim-tree.actions.open_file.window_picker.enable| -|nvim-tree.actions.open_file.window_picker.exclude| -|nvim-tree.actions.open_file.window_picker.picker| -|nvim-tree.actions.remove_file.close_window| -|nvim-tree.actions.use_system_clipboard| -|nvim-tree.auto_reload_on_write| -|nvim-tree.bookmarks.persist| -|nvim-tree.diagnostics.debounce_delay| -|nvim-tree.diagnostics.diagnostic_opts| -|nvim-tree.diagnostics.enable| -|nvim-tree.diagnostics.icons| -|nvim-tree.diagnostics.severity| -|nvim-tree.diagnostics.severity.max| -|nvim-tree.diagnostics.severity.min| -|nvim-tree.diagnostics.show_on_dirs| -|nvim-tree.diagnostics.show_on_open_dirs| -|nvim-tree.disable_netrw| -|nvim-tree.experimental| -|nvim-tree.filesystem_watchers.debounce_delay| -|nvim-tree.filesystem_watchers.enable| -|nvim-tree.filesystem_watchers.ignore_dirs| -|nvim-tree.filters.custom| -|nvim-tree.filters.dotfiles| -|nvim-tree.filters.enable| -|nvim-tree.filters.exclude| -|nvim-tree.filters.git_clean| -|nvim-tree.filters.git_ignored| -|nvim-tree.filters.no_bookmark| -|nvim-tree.filters.no_buffer| -|nvim-tree.git.cygwin_support| -|nvim-tree.git.disable_for_dirs| -|nvim-tree.git.enable| -|nvim-tree.git.show_on_dirs| -|nvim-tree.git.show_on_open_dirs| -|nvim-tree.git.timeout| -|nvim-tree.help.sort_by| -|nvim-tree.hijack_cursor| -|nvim-tree.hijack_directories.auto_open| -|nvim-tree.hijack_directories.enable| -|nvim-tree.hijack_netrw| -|nvim-tree.hijack_unnamed_buffer_when_opening| -|nvim-tree.live_filter.always_show_folders| -|nvim-tree.live_filter.prefix| -|nvim-tree.log.enable| -|nvim-tree.log.truncate| -|nvim-tree.log.types| -|nvim-tree.log.types.all| -|nvim-tree.log.types.config| -|nvim-tree.log.types.copy_paste| -|nvim-tree.log.types.dev| -|nvim-tree.log.types.diagnostics| -|nvim-tree.log.types.git| -|nvim-tree.log.types.profile| -|nvim-tree.log.types.watcher| -|nvim-tree.modified.enable| -|nvim-tree.modified.show_on_dirs| -|nvim-tree.modified.show_on_open_dirs| -|nvim-tree.notify.threshold| -|nvim-tree.on_attach| -|nvim-tree.prefer_startup_root| -|nvim-tree.reload_on_bufenter| -|nvim-tree.renderer.add_trailing| -|nvim-tree.renderer.decorators| -|nvim-tree.renderer.full_name| -|nvim-tree.renderer.group_empty| -|nvim-tree.renderer.hidden_display| -|nvim-tree.renderer.highlight_bookmarks| -|nvim-tree.renderer.highlight_clipboard| -|nvim-tree.renderer.highlight_diagnostics| -|nvim-tree.renderer.highlight_git| -|nvim-tree.renderer.highlight_hidden| -|nvim-tree.renderer.highlight_modified| -|nvim-tree.renderer.highlight_opened_files| -|nvim-tree.renderer.icons| -|nvim-tree.renderer.icons.bookmarks_placement| -|nvim-tree.renderer.icons.diagnostics_placement| -|nvim-tree.renderer.icons.git_placement| -|nvim-tree.renderer.icons.glyphs| -|nvim-tree.renderer.icons.glyphs.default| -|nvim-tree.renderer.icons.glyphs.folder| -|nvim-tree.renderer.icons.glyphs.git| -|nvim-tree.renderer.icons.glyphs.hidden| -|nvim-tree.renderer.icons.glyphs.modified| -|nvim-tree.renderer.icons.glyphs.symlink| -|nvim-tree.renderer.icons.hidden_placement| -|nvim-tree.renderer.icons.modified_placement| -|nvim-tree.renderer.icons.padding.folder_arrow| -|nvim-tree.renderer.icons.padding.icon| -|nvim-tree.renderer.icons.show| -|nvim-tree.renderer.icons.show.bookmarks| -|nvim-tree.renderer.icons.show.diagnostics| -|nvim-tree.renderer.icons.show.file| -|nvim-tree.renderer.icons.show.folder| -|nvim-tree.renderer.icons.show.folder_arrow| -|nvim-tree.renderer.icons.show.git| -|nvim-tree.renderer.icons.show.hidden| -|nvim-tree.renderer.icons.show.modified| -|nvim-tree.renderer.icons.symlink_arrow| -|nvim-tree.renderer.icons.web_devicons| -|nvim-tree.renderer.icons.web_devicons.file| -|nvim-tree.renderer.icons.web_devicons.file.color| -|nvim-tree.renderer.icons.web_devicons.file.enable| -|nvim-tree.renderer.icons.web_devicons.folder| -|nvim-tree.renderer.icons.web_devicons.folder.color| -|nvim-tree.renderer.icons.web_devicons.folder.enable| -|nvim-tree.renderer.indent_markers| -|nvim-tree.renderer.indent_markers.enable| -|nvim-tree.renderer.indent_markers.icons| -|nvim-tree.renderer.indent_markers.inline_arrows| -|nvim-tree.renderer.indent_width| -|nvim-tree.renderer.root_folder_label| -|nvim-tree.renderer.special_files| -|nvim-tree.renderer.symlink_destination| -|nvim-tree.respect_buf_cwd| -|nvim-tree.root_dirs| -|nvim-tree.select_prompts| -|nvim-tree.sort.files_first| -|nvim-tree.sort.folders_first| -|nvim-tree.sort.sorter| -|nvim-tree.sync_root_with_cwd| -|nvim-tree.system_open.args| -|nvim-tree.system_open.cmd| -|nvim-tree.tab.sync| -|nvim-tree.tab.sync.close| -|nvim-tree.tab.sync.ignore| -|nvim-tree.tab.sync.open| -|nvim-tree.trash.cmd| -|nvim-tree.ui.confirm| -|nvim-tree.ui.confirm.default_yes| -|nvim-tree.ui.confirm.remove| -|nvim-tree.ui.confirm.trash| -|nvim-tree.update_focused_file.enable| -|nvim-tree.update_focused_file.exclude| -|nvim-tree.update_focused_file.update_root| -|nvim-tree.update_focused_file.update_root.enable| -|nvim-tree.update_focused_file.update_root.ignore_list| -|nvim-tree.view.centralize_selection| -|nvim-tree.view.cursorline| -|nvim-tree.view.cursorlineopt| -|nvim-tree.view.debounce_delay| -|nvim-tree.view.float| -|nvim-tree.view.float.enable| -|nvim-tree.view.float.open_win_config| -|nvim-tree.view.float.quit_on_focus_loss| -|nvim-tree.view.number| -|nvim-tree.view.preserve_window_proportions| -|nvim-tree.view.relativenumber| -|nvim-tree.view.side| -|nvim-tree.view.signcolumn| -|nvim-tree.view.width| -|nvim-tree.view.width.lines_excluded| -|nvim-tree.view.width.max| -|nvim-tree.view.width.min| -|nvim-tree.view.width.padding| +Class: Config *nvim-tree-config* + +Arguments to pass to |nvim-tree-setup|. + +They can be validated by |lsp| when passed directly e.g. >lua + require("nvim-tree").setup({ + hijack_cursor = true, + }) +< + +or as a typed variable e.g. >lua + ---@type nvim_tree.Config + local config = { + hijack_cursor = true, + } + require("nvim-tree").setup(config) +< + +When a value is not present/nil, the default will be used. + + +*nvim_tree.Config* + + Fields: ~ + • {on_attach}? (`string|(fun(bufnr: integer))`) Runs when + creating the nvim-tree buffer. Use this to + set your |nvim-tree-mappings|. When + `on_attach` is not a function, + |nvim-tree-mappings-default| will be called. + • {hijack_cursor}? (`boolean`, default: `false`) Keeps the + cursor on the first letter of the filename + when moving in the tree. + • {auto_reload_on_write}? (`boolean`, default: `true`) Reloads the + explorer every time a buffer is written to. + • {disable_netrw}? (`boolean`, default: `false`) Completely + disable |netrw|, see |nvim-tree-netrw| for + details. It is strongly advised to eagerly + disable netrw, due to race conditions at vim + startup. + • {hijack_netrw}? (`boolean`, default: `true`) Hijack netrw + windows, ignored when `disable_netrw` is + `true` + • {hubwo}? (`boolean`, default: `false`) Opens in place + of the unnamed buffer if it's empty. TODO + reinstate this one when formatting is done + #2934 --@field + hijack_unnamed_buffer_when_opening? boolean + • {root_dirs}? (`string[]`) Preferred root directories. + Requires + |nvim_tree.Config.UpdateFocusedFile.UpdateRoot|. + • {prefer_startup_root}? (`boolean`, default: `false`) Prefer startup + root directory when updating root directory + of the tree. Requires + |nvim_tree.Config.UpdateFocusedFile.UpdateRoot|. + • {sync_root_with_cwd}? (`boolean`, default: `false`) Changes the + tree root directory on |DirChanged| and + refreshes the tree. + • {reload_on_bufenter}? (`boolean`, default: `false`) Automatically + reloads the tree on |BufEnter| nvim-tree. + • {respect_buf_cwd}? (`boolean`, default: `false`) Change cwd of + nvim-tree to that of new buffer's when + opening nvim-tree. + • {select_prompts}? (`boolean`, default: `false`) Use + |vim.ui.select()| style prompts. Necessary + when using a UI prompt decorator such as + dressing.nvim or telescope-ui-select.nvim + • {sort}? (`nvim_tree.Config.Sort`) + |nvim_tree.Config.Sort| + • {view}? (`nvim_tree.Config.View`) + |nvim_tree.Config.View| + • {renderer}? (`nvim_tree.Config.Renderer`) + |nvim_tree.Config.Renderer| + • {hijack_directories}? (`nvim_tree.Config.HijackDirectories`) + |nvim_tree.Config.HijackDirectories| + • {update_focused_file}? (`nvim_tree.Config.UpdateFocusedFile`) + |nvim_tree.Config.UpdateFocusedFile| + • {system_open}? (`nvim_tree.Config.SystemOpen`) + |nvim_tree.Config.SystemOpen| + • {git}? (`nvim_tree.Config.Git`) + |nvim_tree.Config.Git| + • {diagnostics}? (`nvim_tree.Config.Diagnostics`) + |nvim_tree.Config.Diagnostics| + • {modified}? (`nvim_tree.Config.Modified`) + |nvim_tree.Config.Modified| + • {filters}? (`nvim_tree.Config.Filters`) + |nvim_tree.Config.Filters| + • {live_filter}? (`nvim_tree.Config.LiveFilter`) + |nvim_tree.Config.LiveFilter| + • {filesystem_watchers}? (`nvim_tree.Config.FilesystemWatchers`) + |nvim_tree.Config.FilesystemWatchers| + • {actions}? (`nvim_tree.Config.Actions`) + |nvim_tree.Config.Actions| + • {trash}? (`nvim_tree.Config.Trash`) + |nvim_tree.Config.Trash| + • {tab}? (`nvim_tree.Config.Tab`) + |nvim_tree.Config.Tab| + • {bookmarks}? (`nvim_tree.Config.Bookmarks`) + |nvim_tree.Config.Bookmarks| + • {notify}? (`nvim_tree.Config.Notify`) + |nvim_tree.Config.Notify| + • {help}? (`nvim_tree.Config.Help`) + |nvim_tree.Config.Help| + • {ui}? (`nvim_tree.Config.UI`) |nvim_tree.Config.UI| + • {log}? (`nvim_tree.Config.Log`) + |nvim_tree.Config.Log| + + ============================================================================== - 15.2 INDEX: API *nvim-tree-index-api* - -|nvim-tree-api.commands.get()| -|nvim-tree-api.config.mappings.default_on_attach()| -|nvim-tree-api.config.mappings.get_keymap()| -|nvim-tree-api.config.mappings.get_keymap_default()| -|nvim-tree-api.diagnostics.hi_test()| -|nvim-tree-api.events.subscribe()| -|nvim-tree-api.fs.clear_clipboard()| -|nvim-tree-api.fs.copy.absolute_path()| -|nvim-tree-api.fs.copy.basename()| -|nvim-tree-api.fs.copy.filename()| -|nvim-tree-api.fs.copy.node()| -|nvim-tree-api.fs.copy.relative_path()| -|nvim-tree-api.fs.create()| -|nvim-tree-api.fs.cut()| -|nvim-tree-api.fs.paste()| -|nvim-tree-api.fs.print_clipboard()| -|nvim-tree-api.fs.remove()| -|nvim-tree-api.fs.rename()| -|nvim-tree-api.fs.rename_basename()| -|nvim-tree-api.fs.rename_full()| -|nvim-tree-api.fs.rename_node()| -|nvim-tree-api.fs.rename_sub()| -|nvim-tree-api.fs.trash()| -|nvim-tree-api.git.reload()| -|nvim-tree-api.live_filter.clear()| -|nvim-tree-api.live_filter.start()| -|nvim-tree-api.marks.bulk.delete()| -|nvim-tree-api.marks.bulk.move()| -|nvim-tree-api.marks.bulk.trash()| -|nvim-tree-api.marks.clear()| -|nvim-tree-api.marks.get()| -|nvim-tree-api.marks.list()| -|nvim-tree-api.marks.navigate.next()| -|nvim-tree-api.marks.navigate.prev()| -|nvim-tree-api.marks.navigate.select()| -|nvim-tree-api.marks.toggle()| -|nvim-tree-api.node.buffer.delete()| -|nvim-tree-api.node.buffer.wipe()| -|nvim-tree-api.node.collapse()| -|nvim-tree-api.node.expand()| -|nvim-tree-api.node.navigate.diagnostics.next()| -|nvim-tree-api.node.navigate.diagnostics.next_recursive()| -|nvim-tree-api.node.navigate.diagnostics.prev()| -|nvim-tree-api.node.navigate.diagnostics.prev_recursive()| -|nvim-tree-api.node.navigate.git.next()| -|nvim-tree-api.node.navigate.git.next_recursive()| -|nvim-tree-api.node.navigate.git.next_skip_gitignored()| -|nvim-tree-api.node.navigate.git.prev()| -|nvim-tree-api.node.navigate.git.prev_recursive()| -|nvim-tree-api.node.navigate.git.prev_skip_gitignored()| -|nvim-tree-api.node.navigate.opened.next()| -|nvim-tree-api.node.navigate.opened.prev()| -|nvim-tree-api.node.navigate.parent()| -|nvim-tree-api.node.navigate.parent_close()| -|nvim-tree-api.node.navigate.sibling.first()| -|nvim-tree-api.node.navigate.sibling.last()| -|nvim-tree-api.node.navigate.sibling.next()| -|nvim-tree-api.node.navigate.sibling.prev()| -|nvim-tree-api.node.open.drop()| -|nvim-tree-api.node.open.edit()| -|nvim-tree-api.node.open.horizontal()| -|nvim-tree-api.node.open.horizontal_no_picker()| -|nvim-tree-api.node.open.no_window_picker()| -|nvim-tree-api.node.open.preview()| -|nvim-tree-api.node.open.preview_no_picker()| -|nvim-tree-api.node.open.replace_tree_buffer()| -|nvim-tree-api.node.open.tab()| -|nvim-tree-api.node.open.tab_drop()| -|nvim-tree-api.node.open.toggle_group_empty()| -|nvim-tree-api.node.open.vertical()| -|nvim-tree-api.node.open.vertical_no_picker()| -|nvim-tree-api.node.run.cmd()| -|nvim-tree-api.node.run.system()| -|nvim-tree-api.node.show_info_popup()| -|nvim-tree-api.tree.change_root()| -|nvim-tree-api.tree.change_root_to_node()| -|nvim-tree-api.tree.change_root_to_parent()| -|nvim-tree-api.tree.close()| -|nvim-tree-api.tree.close_in_all_tabs()| -|nvim-tree-api.tree.close_in_this_tab()| -|nvim-tree-api.tree.collapse_all()| -|nvim-tree-api.tree.expand_all()| -|nvim-tree-api.tree.find_file()| -|nvim-tree-api.tree.focus()| -|nvim-tree-api.tree.get_nodes()| -|nvim-tree-api.tree.get_node_under_cursor()| -|nvim-tree-api.tree.is_tree_buf()| -|nvim-tree-api.tree.is_visible()| -|nvim-tree-api.tree.open()| -|nvim-tree-api.tree.reload()| -|nvim-tree-api.tree.resize()| -|nvim-tree-api.tree.search_node()| -|nvim-tree-api.tree.toggle()| -|nvim-tree-api.tree.toggle_custom_filter()| -|nvim-tree-api.tree.toggle_enable_filters()| -|nvim-tree-api.tree.toggle_git_clean_filter()| -|nvim-tree-api.tree.toggle_gitignore_filter()| -|nvim-tree-api.tree.toggle_help()| -|nvim-tree-api.tree.toggle_hidden_filter()| -|nvim-tree-api.tree.toggle_no_bookmark_filter()| -|nvim-tree-api.tree.toggle_no_buffer_filter()| -|nvim-tree-api.tree.winid()| +Class: Config.Sort *nvim-tree-config-sort* + +Sort files within a directory. + +{sorter} presets *nvim_tree.Config.Sort.Sorter* +• `name` +• `case_sensitive` name +• `modification_time` +• `extension` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz` +• `suffix` uses the last e.g. `foo.tar.gz` -> `.gz` +• `filetype` |filetype| + +{sorter} may be a function that is passed a list of `nvim_tree.api.Node` to be +sorted in place e.g. >lua + + ---Sort by name length + ---@param nodes nvim_tree.api.Node[] + ---@return nvim_tree.Config.Sort.Sorter? + local sorter = function(nodes) + table.sort(nodes, function(a, b) + return #a.name < #b.name + end) + end +< + +{sorter} may be a function that returns a |nvim_tree.Config.Sort.Sorter| + + +*nvim_tree.Config.Sort* + + Fields: ~ + • {sorter}? (`nvim_tree.Config.Sort.Sorter|(fun(nodes: nvim_tree.api.Node[]): nvim_tree.Config.Sort.Sorter?)`) + (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* + +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 + + +*nvim_tree.Config.View* + + Fields: ~ + • {centralize_selection}? (`boolean`, default: `false`) When + entering nvim-tree, reposition the + view so that the current node is + initially centralized, see |zz|. + • {cursorline}? (`boolean`, default: `true`) + |'cursorline'| + • {cursorlineopt}? (`string`, default: `both`) + |'cursorlineopt'| + • {debounce_delay}? (`integer`, default: `15`) Idle + milliseconds before some reload / + refresh operations. Increase if you + experience performance issues around + screen refresh. + • {side}? (`"left"|"right"`) (default: `left`) + • {preserve_window_proportions}? (`boolean`, default: `false`) + Preserves window proportions when + opening a file. If `false`, the height + and width of windows other than + nvim-tree will be equalized. + • {number}? (`boolean`, default: `false`) + |'number'| + • {relativenumber}? (`boolean`, default: `false`) + |'relativenumber'| + • {signcolumn}? (`"yes"|"auto"|"no"`, default: `yes`) + |'signcolumn'| + • {width}? (`nvim_tree.Config.View.WidthSpec|nvim_tree.Config.View.Width`) + (default: `30`) + • {float}? (`nvim_tree.Config.View.Float`) + |nvim_tree.Config.View.Float| + +*nvim_tree.Config.View.Float* + Configure floating window behaviour + + {open_win_config} is passed directly to |nvim_open_win()|, default: >lua + { + relative = "editor", + border = "rounded", + width = 30, + height = 30, + row = 1, + col = 1, + } +< + + Fields: ~ + • {enable}? (`boolean`) (default: `false`) + • {quit_on_focus_loss}? (`boolean`, default: `true`) Close the floating + window when it loses focus. + • {open_win_config}? (`vim.api.keyset.win_config|(fun(): vim.api.keyset.win_config)`) + (default: above) + +*nvim_tree.Config.View.Width* + Configure dynamic width based on longest line. + + Fields: ~ + • {min}? (`nvim_tree.Config.View.WidthSpec`) (default: `30`) + • {max}? (`nvim_tree.Config.View.WidthSpec`, default: `-1`) + -1 for unbounded. + • {lines_excluded}? (`("root")[]`, default: `{ "root" }`) Exclude these + lines when computing width. + • {padding}? (`nvim_tree.Config.View.WidthSpec`, default: `1`) + Extra padding to the right. + + + +============================================================================== +Class: Config.Renderer *nvim-tree-config-renderer* + +Controls the appearance of the tree. + +{highlight_} options *nvim_tree.Config.Renderer.HighlightPlacement* +• `none`: no highlighting +• `icon`: icon only +• `name`: name only +• `all`: icon and name + +{root_folder_label} has 3 forms: +• `string`: |filename-modifiers| format string +• `boolean`: `true` to disable +• `fun(root_cwd: string): string`: return a literal string from root's + absolute path e.g. >lua + my_root_folder_label = function(path) + return ".../" .. vim.fn.fnamemodify(path, ":t") + end +< + + +*nvim_tree.Config.Renderer* + + Fields: ~ + • {add_trailing}? (`boolean`, default: `false`) Appends a + trailing slash to folder and symlink folder + target names. + • {group_empty}? (`boolean|(fun(relative_path: string): string)`, default: `false`) + Compact folders that only contain a single + folder into one node. Function variant + takes the relative path of grouped folders + and returns a string to be displayed. + • {full_name}? (`boolean`, default: `false`) Display nodes + whose name length is wider than the width + of nvim-tree window in floating window. + • {root_folder_label}? (`string|boolean|(fun(root_cwd: string): string)`) + (default: `":~:s?$?/..?"`) + • {indent_width}? (`integer`, default: `2`) Number of spaces + for each tree nesting level. Minimum 1. + • {hidden_display}? (`nvim_tree.Config.Renderer.HiddenDisplay`, default: `none`) + |nvim-tree-hidden-display| + • {symlink_destination}? (`boolean`, default: `true`) Appends an + arrow followed by the target of the + symlink. + • {decorators}? (`(string|nvim_tree.api.decorator.UserDecorator)[]`, default: `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) + Highlighting and icons for the nodes, in + increasing order of precedence. Strings + specify builtin decorators. See + |nvim-tree-decorators|. + • {highlight_git}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) + Git status: `NvimTreeGit*HL`. Requires + |nvim_tree.Config.Git|. + • {highlight_opened_files}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) + |bufloaded()| files: `NvimTreeOpenedHL`. + • {highlight_hidden}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) + Hidden (dotfiles): `NvimTreeHiddenFileHL`. + • {highlight_modified}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) + Modified files: `NvimTreeModifiedFile`. + Requires |nvim_tree.Config.Modified|. + • {highlight_bookmarks}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) + Bookmarked: `NvimTreeBookmarkHL`. + • {highlight_diagnostics}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `none`) + Diagnostic status: `NvimTreeDiagnostic*HL`. + Requires |nvim_tree.Config.Diagnostics|. + • {highlight_clipboard}? (`nvim_tree.Config.Renderer.HighlightPlacement`, default: `name`) + Copied: `NvimTreeCopiedHL`, cut: + `NvimTreeCutHL`. + • {special_files}? (`string[]`, default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }`) + Sepcial files: `NvimTreeSpecialFile`. + • {indent_markers}? (`nvim_tree.Config.Renderer.IndentMarkers`) + |nvim_tree.Config.Renderer.IndentMarkers| + • {icons}? (`nvim_tree.Config.Renderer.Icons`) + |nvim_tree.Config.Renderer.Icons| + +*nvim_tree.Config.Renderer.Icons* + Icons and separators. + + {_placement} options *nvim_tree.Config.Renderer.Icons.Placement* + • `before`: before file/folder, after the file/folders icons + • `after`: after file/folder + • `signcolumn`: far left, requires |nvim_tree.Config.View| {signcolumn}. + • `right_align`: far right + + Fields: ~ + • {web_devicons}? (`nvim_tree.Config.Renderer.Icons.WebDevicons`) + |nvim_tree.Config.Renderer.Icons.WebDevicons| + Use optional plugin + `nvim-tree/nvim-web-devicons` + • {git_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`) + (default: `before`) + • {diagnostics_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`, default: `signcolumn`) + Requires |nvim_tree.Config.Diagnostics|. + • {modified_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`, default: `after`) + Requires |nvim_tree.Config.Modified|. + • {hidden_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`) + (default: `after`) + • {bookmarks_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`) + (default: `signcolumn`) + • {padding}? (`table`) + *nvim_tree.Config.Renderer.Icons.Padding* + • {icon}? (`string`, default: ` `) Between + icon and filename. + • {folder_arrow}? (`string`, default: ` `) + Between folder arrow icon and file/folder + icon. + • {symlink_arrow}? (`string`, default: ` ➛ `) Separator + between symlink source and target. + • {show}? (`nvim_tree.Config.Renderer.Icons.Show`) + |nvim_tree.Config.Renderer.Icons.Show| + • {glyphs}? (`nvim_tree.Config.Renderer.Icons.Glyphs`) + |nvim_tree.Config.Renderer.Icons.Glyphs| + +*nvim_tree.Config.Renderer.Icons.Glyphs* + Glyphs that appear in the sign column must have length <= 2 + + Glyphs defined elsewhere: + • |nvim_tree.Config.Diagnostics.Icons| + • |nvim_tree.Config.Renderer.IndentMarkers.Icons| + + Fields: ~ + • {default}? (`string`, default: `` ) Files, overridden by + |nvim_tree.Config.Renderer.Icons.WebDevicons|. + • {symlink}? (`string`) (default: `` ) + • {bookmark}? (`string`) (default: `󰆤` ) + • {modified}? (`string`) (default: `●` ) + • {hidden}? (`string`) (default: `󰜌` ) + • {folder}? (`table`) Overridden by + |nvim_tree.Config.Renderer.Icons.WebDevicons|. *nvim_tree.Config.Renderer.Icons.Glyphs.Folder* + • {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. *nvim_tree.Config.Renderer.Icons.Glyphs.Git* + • {unstaged}? (`string`) (default: `✗` ) + • {staged}? (`string`) (default: `✓` ) + • {unmerged}? (`string`) (default: `` ) + • {renamed}? (`string`) (default: `➜` ) + • {untracked}? (`string`) (default: `★` ) + • {deleted}? (`string`) (default: `` ) + • {ignored}? (`string`) (default: `◌` ) + +*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.IndentMarkers|. + • {git}? (`boolean`, default: `true`) Location: + |nvim_tree.Config.Renderer.Icons| {git_placement}. + Icons: |nvim_tree.Config.Renderer.Icons.Glyphs.Git|. + Requires |nvim_tree.Config.Git|. + • {modified}? (`boolean`, default: `true`) Location: + |nvim_tree.Config.Renderer.Icons| + {modified_placement}. Requires + |nvim_tree.Config.Modified|. + • {hidden}? (`boolean`, default: `false`) Location: + |nvim_tree.Config.Renderer.Icons| {hidden_placement}. + • {diagnostics}? (`boolean`, default: `true`) Location: + |nvim_tree.Config.Renderer.Icons| + {diagnostics_placement}. Icons: + |nvim_tree.Config.Diagnostics.Icons|. Requires + |nvim_tree.Config.Diagnostics|. + • {bookmarks}? (`boolean`, default: `true`) Location: + |nvim_tree.Config.Renderer.Icons| + {bookmarks_placement}. + +*nvim_tree.Config.Renderer.Icons.WebDevicons* + Configure optional plugin `nvim-tree/nvim-web-devicons`. + + Overrides glyphs and highlight groups where noted. + + Fields: ~ + • {file}? (`table`) + *nvim_tree.Config.Renderer.Icons.WebDevicons.File* + • {enable}? (`boolean`, default: `true`) Show icons for + files, overrides + |nvim_tree.Config.Renderer.Icons.Glyphs.Git|. + • {color}? (`boolean`, default: `true`) Apply colours to + files, overrides `NvimTreeFileIcon`. + • {folder}? (`table`) + *nvim_tree.Config.Renderer.Icons.WebDevicons.Folder* + • {enable}? (`boolean`, default: `false`) Show icons for + directories, overrides + |nvim_tree.Config.Renderer.Icons.Glyphs.Folder|. + • {color}? (`boolean`, default: `true`) Apply colors to + directories, overrides `NvimTree*FolderName`. + +*nvim_tree.Config.Renderer.IndentMarkers* + + Fields: ~ + • {enable}? (`boolean`, default: `false`) Display indent markers + when folders are open. + • {inline_arrows}? (`boolean`, default: `true`) Display folder arrows + in the same column as indent marker when using + |nvim_tree.Config.Renderer.Icons.Padding| + {folder_arrow} + • {icons}? (`table`) + *nvim_tree.Config.Renderer.IndentMarkers.Icons* + Before the file/directory, length 1. + • {corner}? (`string`) (default: `└` ) + • {edge}? (`string`) (default: `│` ) + • {item}? (`string`) (default: `│` ) + • {bottom}? (`string`) (default: `─` ) + • {none}? (`string`) (default: ` ` ) + + + +============================================================================== +Class: Config.HijackDirectories *nvim-tree-config-hijack-directories* + +Hijack directory buffers by replacing the directory buffer with the tree. + +Disable this option if you use vim-dirvish or dirbuf.nvim. + +If |nvim_tree.Config| {hijack_netrw} and {disable_netrw} are `false` this +feature will be disabled. + + +*nvim_tree.Config.HijackDirectories* + + 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* + +Update the focused file on |BufEnter|, uncollapsing folders recursively. + + +*nvim_tree.Config.UpdateFocusedFile* + + 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. + + Requires |nvim_tree.Config.UpdateFocusedFile| + + 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* + +Open files or directories via the OS. + +Nvim: +• `>=` 0.10 uses |vim.ui.open()| unless {cmd} is specified +• `<` 0.10 calls external {cmd}: + • UNIX: `xdg-open` + • macOS: `open` + • Windows: `cmd` + +Once nvim-tree minimum Nvim version is updated to 0.10, these options will no +longer be necessary and will be removed. + + +*nvim_tree.Config.SystemOpen* + + 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* + +Git operations are run in the background thus status may not immediately +appear. + +Processes will be killed if they exceed {timeout} ms. Git integration will be +disabled following 5 timeouts and you will be notified. + +Git integration may be disabled for git top-level directories via +{disable_for_dirs}: +• A list of relative paths evaluated with |fnamemodify()| `:p` OR +• A function that is passed an absolute path and returns `true` to disable + + +*nvim_tree.Config.Git* + + Fields: ~ + • {enable}? (`boolean`) (default: `true`) + • {show_on_dirs}? (`boolean`, default: `true`) Show status icons + of children when directory itself has no status + icon + • {show_on_open_dirs}? (`boolean`, default: `true`) Show status icons + of children on directories that are open. + Requires {show_on_dirs}. + • {disable_for_dirs}? (`string[]|(fun(path: string): boolean)`, + default: `{}`) Disable for top level paths. + • {timeout}? (`integer`, default: `400`) `git` processes + timeout milliseconds. + • {cygwin_support}? (`boolean`, default: `false`) Use `cygpath` if + available to resolve paths for git. + + + +============================================================================== +Class: Config.Diagnostics *nvim-tree-config-diagnostics* + +Integrate with |lsp| or COC diagnostics. + + +*nvim_tree.Config.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. Requires + {show_on_dirs}. + • {diagnostic_opts}? (`boolean`, default: `false`) Global + |vim.diagnostic.Opts| overrides {severity} and + {icons} + • {severity}? (`table`) + *nvim_tree.Config.Diagnostics.Severity* + • {min}? (`vim.diagnostic.Severity`, default: + HINT) |vim.diagnostic.severity| + • {max}? (`vim.diagnostic.Severity`, default: + ERROR) |vim.diagnostic.severity| + • {icons}? (`table`) *nvim_tree.Config.Diagnostics.Icons* + • {hint}? (`string`) (default: `` ) + • {info}? (`string`) (default: `` ) + • {warning}? (`string`) (default: `` ) + • {error}? (`string`) (default: `` ) + + + +============================================================================== +Class: Config.Modified *nvim-tree-config-modified* + +Indicate which files have unsaved modification. To see modified status in the +tree you will need: +• |nvim_tree.Config.Renderer.Icons.Show| {modified} OR +• |nvim_tree.Config.Renderer| {highlight_modified} + + +*nvim_tree.Config.Modified* + + Fields: ~ + • {enable}? (`boolean`) (default: `false`) + • {show_on_dirs}? (`boolean`, default: `true`) Show modified + indication on directory whose children are + modified. + • {show_on_open_dirs}? (`boolean`, default: `false`) Show modified + indication on open directories. Requires + {show_on_dirs}. + + ============================================================================== +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| + +`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* + +Live filter allows you to filter the tree nodes dynamically, based on regex +matching, see |vim.regex| + +This feature is bound to the `f` key by default. The filter can be cleared +with the `F` key by default. + + +*nvim_tree.Config.LiveFilter* + + 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* + +Use file system watchers (libuv `uv_fs_event_t`) to monitor the filesystem for +changes and update the tree. + +With this feature, the tree will be partially updated on specific directory +changes, resulting in better performance. + +Watchers may be disabled for absolute directory paths via {ignore_dirs}. +• A list of |vim.regex| to match a path, backslash escaped e.g. + `"my-proj/\\.build$"` OR +• A function that is passed an absolute path and returns `true` to disable + This may be useful when a path is not in `.gitignore` or git integration is + disabled. + + +*nvim_tree.Config.FilesystemWatchers* + + 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 folder. Avoids hanging Nvim when + running this action on very large folders. + • {exclude}? (`string[]`, default: `{}`) A list of + directories that should not be expanded + automatically e.g + `{ ".git", "target", "build" }` + +*nvim_tree.Config.Actions.FilePopup* + {file_popup} floating window. + + {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 {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* + +Files may be trashed via an external command that must be installed on your +system. +• linux: `gio trash`, from linux package `glib2` +• macOS: `trash`, from homebrew package `trash` +• windows: `trash`, requires `trash-cli` or similar + + +*nvim_tree.Config.Trash* + + 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* + + 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 |vim.log.levels| +• `ERROR`: hard errors e.g. failure to read from the file system. +• `WARN`: non-fatal errors e.g. unable to system open a file. +• `INFO`: information only e.g. file copy path confirmation. +• `DEBUG`: information for troubleshooting, e.g. failures in some window + closing operations. + + +*nvim_tree.Config.Notify* + + Fields: ~ + • {threshold}? (`vim.log.levels`, default: `vim.log.levels.INFO`) + Specify minimum notification |vim.log.levels| + • {absolute_path}? (`boolean`, default: `true`) Use absolute paths in + FS action notifications, otherwise item names. + + + +============================================================================== +Class: Config.Bookmarks *nvim-tree-config-bookmarks* + +Optionally {persist} bookmarks to a json file: +• `true` use default: `stdpath("data") .. "/nvim-tree-bookmarks.json"` +• `false` do not persist +• `string` absolute path of your choice + + +*nvim_tree.Config.Bookmarks* + + Fields: ~ + • {persist}? (`boolean|string`) (default: `false`) + + + +============================================================================== +Class: Config.Help *nvim-tree-config-help* + +Configure help window, default mapping `g?` + + *nvim_tree.Config.Help.SortBy* +• `key`: alphabetically by keymap +• `desc`: alphabetically by description + + +*nvim_tree.Config.Help* + + 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. + + 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* + +Log to a file `nvim-tree.log` in |stdpath()| `log`, usually +`${XDG_STATE_HOME}/nvim` + + +*nvim_tree.Config.Log* + + 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=4:sw=4:et:ft=help:norl: + 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 9fe579ccdfe..9d27cee3541 100644 --- a/lua/nvim-tree.lua +++ b/lua/nvim-tree.lua @@ -252,6 +252,7 @@ local function setup_autocommands(opts) }) end +---@type nvim_tree.Config local DEFAULT_OPTS = { -- BEGIN_DEFAULT_OPTS on_attach = "default", hijack_cursor = false, @@ -627,7 +628,7 @@ local ACCEPTED_ENUMS = { }, } ----@param conf table|nil +---@param conf? nvim_tree.Config local function validate_options(conf) local msg @@ -732,7 +733,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..39643a11d58 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..01741b079c7 --- /dev/null +++ b/lua/nvim-tree/_meta/config.lua @@ -0,0 +1,137 @@ +---@meta +error("Cannot require a meta file") + + +---@brief +--- +---Arguments to pass to [nvim-tree-setup]. +--- +---They can be validated by |lsp| when passed directly e.g. +---```lua +--- require("nvim-tree").setup({ +--- hijack_cursor = true, +--- }) +---``` +--- +---or as a typed variable e.g. +---```lua +--- ---@type nvim_tree.Config +--- local config = { +--- hijack_cursor = true, +--- } +--- require("nvim-tree").setup(config) +---``` +--- +---When a value is not present/nil, the default will be used. + + + +---@class nvim_tree.Config +--- +---Runs when creating the nvim-tree buffer. Use this to set your [nvim-tree-mappings]. When `on_attach` is not a function, [nvim-tree-mappings-default] will be called. +---@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. Requires [nvim_tree.Config.UpdateFocusedFile.UpdateRoot]. +---@field root_dirs? string[] +--- +---Prefer startup root directory when updating root directory of the tree. Requires [nvim_tree.Config.UpdateFocusedFile.UpdateRoot]. +---(default: `false`) +---@field prefer_startup_root? boolean +--- +---Changes the tree root directory on [DirChanged] and refreshes the tree. +---(default: `false`) +---@field sync_root_with_cwd? boolean +--- +---Automatically reloads the tree on [BufEnter] nvim-tree. +---(default: `false`) +---@field reload_on_bufenter? boolean +--- +---Change cwd of nvim-tree to that of new buffer's when opening nvim-tree. +---(default: `false`) +---@field respect_buf_cwd? boolean +--- +---Use [vim.ui.select()] style prompts. Necessary when using a UI prompt decorator such as dressing.nvim or telescope-ui-select.nvim +---(default: `false`) +---@field select_prompts? boolean +--- +---[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.Bookmarks] +---@field bookmarks? nvim_tree.Config.Bookmarks +--- +---[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 diff --git a/lua/nvim-tree/_meta/config/actions.lua b/lua/nvim-tree/_meta/config/actions.lua new file mode 100644 index 00000000000..75aed0891ac --- /dev/null +++ b/lua/nvim-tree/_meta/config/actions.lua @@ -0,0 +1,140 @@ +---@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 folder. Avoids hanging Nvim 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. +--- +---{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 {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/bookmarks.lua b/lua/nvim-tree/_meta/config/bookmarks.lua new file mode 100644 index 00000000000..c174097b2d7 --- /dev/null +++ b/lua/nvim-tree/_meta/config/bookmarks.lua @@ -0,0 +1,16 @@ +---@meta +error("Cannot require a meta file") + + +---@brief +---Optionally {persist} bookmarks to a json file: +---- `true` use default: `stdpath("data") .. "/nvim-tree-bookmarks.json"` +---- `false` do not persist +---- `string` absolute path of your choice + + + +---@class nvim_tree.Config.Bookmarks +--- +---(default: `false`) +---@field persist? boolean|string diff --git a/lua/nvim-tree/_meta/config/diagnostics.lua b/lua/nvim-tree/_meta/config/diagnostics.lua new file mode 100644 index 00000000000..1368be54570 --- /dev/null +++ b/lua/nvim-tree/_meta/config/diagnostics.lua @@ -0,0 +1,66 @@ +---@meta +error("Cannot require a meta file") + + + +---@brief +---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. Requires {show_on_dirs}. +---(default: `true`) +---@field show_on_open_dirs? boolean +--- +---Global [vim.diagnostic.Opts] overrides {severity} and {icons} +---(default: `false`) +---@field diagnostic_opts? boolean +--- +---@field severity? nvim_tree.Config.Diagnostics.Severity +--- +---@field icons? nvim_tree.Config.Diagnostics.Icons + + + +---[nvim_tree.Config.Diagnostics.Severity]() +---@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 + + + +---[nvim_tree.Config.Diagnostics.Icons]() +---@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..fc66ab220e7 --- /dev/null +++ b/lua/nvim-tree/_meta/config/filesystem_watchers.lua @@ -0,0 +1,29 @@ +---@meta +error("Cannot require a meta file") + + + +---@brief +---Use file system watchers (libuv `uv_fs_event_t`) to monitor the filesystem for changes and update the tree. +--- +---With this feature, the tree will be partially updated on specific directory changes, resulting in better performance. +--- +---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..decfa9094bd --- /dev/null +++ b/lua/nvim-tree/_meta/config/filters.lua @@ -0,0 +1,74 @@ +---@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|
+---
+---`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..9e1705ff6ea --- /dev/null +++ b/lua/nvim-tree/_meta/config/git.lua @@ -0,0 +1,40 @@ +---@meta +error("Cannot require a meta file") + + + +---@brief +---Git operations are run in the background thus status may not immediately appear. +--- +---Processes will be killed if they exceed {timeout} ms. Git integration will be disabled following 5 timeouts and you will be notified. +--- +---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. Requires {show_on_dirs}. +---(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..c8b6f79deb7 --- /dev/null +++ b/lua/nvim-tree/_meta/config/help.lua @@ -0,0 +1,23 @@ +---@meta +error("Cannot require a meta file") + + + +---@alias nvim_tree.Config.Help.SortBy "key"|"desc" + + + +---@brief +---Configure help window, default mapping `g?` +--- +---[nvim_tree.Config.Help.SortBy]() +---- `key`: alphabetically by keymap +---- `desc`: alphabetically by description + + + +---@class nvim_tree.Config.Help +--- +---[nvim_tree.Config.Help.SortBy] +---(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..872ae6bc17e --- /dev/null +++ b/lua/nvim-tree/_meta/config/hijack_directories.lua @@ -0,0 +1,22 @@ +---@meta +error("Cannot require a meta file") + + + +---@brief +---Hijack directory buffers by replacing the directory buffer with the tree. +--- +---Disable this option if you use vim-dirvish or dirbuf.nvim. +--- +---If [nvim_tree.Config] {hijack_netrw} and {disable_netrw} are `false` this feature will be disabled. + + + +---@class nvim_tree.Config.HijackDirectories +--- +---(default: `true`) +---@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..60b52f172e4 --- /dev/null +++ b/lua/nvim-tree/_meta/config/live_filter.lua @@ -0,0 +1,21 @@ +---@meta +error("Cannot require a meta file") + + + +---@brief +--- Live filter allows you to filter the tree nodes dynamically, based on regex matching, see [vim.regex] +--- +--- This feature is bound to the `f` key by default. The filter can be cleared with the `F` key by default. + + + +---@class nvim_tree.Config.LiveFilter +--- +---Prefix of the filter displayed in the buffer. +---(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..e3808a16fa0 --- /dev/null +++ b/lua/nvim-tree/_meta/config/log.lua @@ -0,0 +1,56 @@ +---@meta +error("Cannot require a meta file") + + + +---@brief +---Log to a file `nvim-tree.log` in [stdpath()] `log`, usually `${XDG_STATE_HOME}/nvim` + + + +---@class nvim_tree.Config.Log +--- +---(default: `false`) +---@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..bd5a8f4dc6a --- /dev/null +++ b/lua/nvim-tree/_meta/config/modified.lua @@ -0,0 +1,25 @@ +---@meta +error("Cannot require a meta file") + + + +---@brief +---Indicate which files have unsaved modification. +---To see modified status in the tree you will need: +--- - [nvim_tree.Config.Renderer.Icons.Show] {modified} OR +--- - [nvim_tree.Config.Renderer] {highlight_modified} + + + +---@class nvim_tree.Config.Modified +--- +---(default: `false`) +---@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. Requires {show_on_dirs}. +---(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..fd1165d9e93 --- /dev/null +++ b/lua/nvim-tree/_meta/config/notify.lua @@ -0,0 +1,23 @@ +---@meta +error("Cannot require a meta file") + + + +---@brief +---nvim-tree |vim.log.levels| +---- `ERROR`: hard errors e.g. failure to read from the file system. +---- `WARN`: non-fatal errors e.g. unable to system open a file. +---- `INFO`: information only e.g. file copy path confirmation. +---- `DEBUG`: information for troubleshooting, e.g. failures in some window closing operations. + + + +---@class nvim_tree.Config.Notify +--- +---Specify minimum notification |vim.log.levels| +---(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..f3174865dd6 --- /dev/null +++ b/lua/nvim-tree/_meta/config/renderer.lua @@ -0,0 +1,361 @@ +---@meta +error("Cannot require a meta file") + + + +---@alias nvim_tree.Config.Renderer.HighlightPlacement "none"|"icon"|"name"|"all" + +---@alias nvim_tree.Config.Renderer.HiddenDisplay "none"|"simple"|"all"|(fun(hidden_stats: table): string) + +---@alias nvim_tree.Config.Renderer.Icons.Placement "before"|"after"|"signcolumn"|"right_align" + + + +---@brief +---Controls the appearance of the tree. +--- +---{highlight_} options [nvim_tree.Config.Renderer.HighlightPlacement]() +---- `none`: no highlighting +---- `icon`: icon only +---- `name`: name only +---- `all`: icon and name +--- +---{root_folder_label} has 3 forms: +---- `string`: [filename-modifiers] format string +---- `boolean`: `true` to disable +---- `fun(root_cwd: string): string`: return a literal string from root's absolute path e.g. +---```lua +---my_root_folder_label = function(path) +--- return ".../" .. vim.fn.fnamemodify(path, ":t") +---end +---``` + + + +---@class nvim_tree.Config.Renderer +--- +---Appends a trailing slash to folder and symlink folder target names. +---(default: `false`) +---@field add_trailing? boolean +--- +---Compact folders that only contain a single folder into one node. Function variant takes the relative path of grouped folders and returns a string to be displayed. +---(default: `false`) +---@field group_empty? boolean|(fun(relative_path: string): string) +--- +---Display nodes whose name length is wider than the width of nvim-tree window in floating window. +---(default: `false`) +---@field full_name? boolean +--- +---(default: `":~:s?$?/..?"`) +---@field root_folder_label? string|boolean|(fun(root_cwd: string): string) +--- +---Number of spaces for each tree nesting level. Minimum 1. +---(default: `2`) +---@field indent_width? integer +--- +---[nvim-tree-hidden-display] +---(default: `none`) +---@field hidden_display? nvim_tree.Config.Renderer.HiddenDisplay +--- +---Appends an arrow followed by the target of the symlink. +---(default: `true`) +---@field symlink_destination? boolean +--- +---Highlighting and icons for the nodes, in increasing order of precedence. Strings specify builtin decorators. See [nvim-tree-decorators]. +---(default: `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) +---@field decorators? (string|nvim_tree.api.decorator.UserDecorator)[] +--- +---Git status: `NvimTreeGit*HL`. +---Requires [nvim_tree.Config.Git]. +---(default: `none`) +---@field highlight_git? nvim_tree.Config.Renderer.HighlightPlacement +--- +---[bufloaded()] files: `NvimTreeOpenedHL`. +---(default: `none`) +---@field highlight_opened_files? nvim_tree.Config.Renderer.HighlightPlacement +--- +---Hidden (dotfiles): `NvimTreeHiddenFileHL`. +---(default: `none`) +---@field highlight_hidden? nvim_tree.Config.Renderer.HighlightPlacement +--- +---Modified files: `NvimTreeModifiedFile`. +---Requires [nvim_tree.Config.Modified]. +---(default: `none`) +---@field highlight_modified? nvim_tree.Config.Renderer.HighlightPlacement +--- +---Bookmarked: `NvimTreeBookmarkHL`. +---(default: `none`) +---@field highlight_bookmarks? nvim_tree.Config.Renderer.HighlightPlacement +--- +---Diagnostic status: `NvimTreeDiagnostic*HL`. +---Requires [nvim_tree.Config.Diagnostics]. +---(default: `none`) +---@field highlight_diagnostics? nvim_tree.Config.Renderer.HighlightPlacement +--- +---Copied: `NvimTreeCopiedHL`, cut: `NvimTreeCutHL`. +---(default: `name`) +---@field highlight_clipboard? nvim_tree.Config.Renderer.HighlightPlacement +--- +---Sepcial files: `NvimTreeSpecialFile`. +---(default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }`) +---@field special_files? string[] +--- +---[nvim_tree.Config.Renderer.IndentMarkers] +---@field indent_markers? nvim_tree.Config.Renderer.IndentMarkers +--- +---[nvim_tree.Config.Renderer.Icons] +---@field icons? nvim_tree.Config.Renderer.Icons + + +---@class nvim_tree.Config.Renderer.IndentMarkers +--- +---Display indent markers when folders are open. +---(default: `false`) +---@field enable? boolean +--- +---Display folder arrows in the same column as indent marker when using [nvim_tree.Config.Renderer.Icons.Padding] {folder_arrow} +---(default: `true`) +---@field inline_arrows? boolean +--- +---@field icons? nvim_tree.Config.Renderer.IndentMarkers.Icons + + + +---[nvim_tree.Config.Renderer.IndentMarkers.Icons]() +---Before the file/directory, length 1. +---@class nvim_tree.Config.Renderer.IndentMarkers.Icons +---@inlinedoc +--- +---(default: `└` ) +---@field corner? string +---(default: `│` ) +---@field edge? string +---(default: `│` ) +---@field item? string +---(default: `─` ) +---@field bottom? string +---(default: ` ` ) +---@field none? string + + + +---Icons and separators. +--- +---{_placement} options [nvim_tree.Config.Renderer.Icons.Placement]() +---- `before`: before file/folder, after the file/folders icons +---- `after`: after file/folder +---- `signcolumn`: far left, requires [nvim_tree.Config.View] {signcolumn}. +---- `right_align`: far right +--- +---@class nvim_tree.Config.Renderer.Icons +--- +---[nvim_tree.Config.Renderer.Icons.WebDevicons] +---Use optional plugin `nvim-tree/nvim-web-devicons` +---@field web_devicons? nvim_tree.Config.Renderer.Icons.WebDevicons +--- +---(default: `before`) +---@field git_placement? nvim_tree.Config.Renderer.Icons.Placement +--- +---Requires [nvim_tree.Config.Diagnostics]. +---(default: `signcolumn`) +---@field diagnostics_placement? nvim_tree.Config.Renderer.Icons.Placement +--- +---Requires [nvim_tree.Config.Modified]. +---(default: `after`) +---@field modified_placement? nvim_tree.Config.Renderer.Icons.Placement +--- +---(default: `after`) +---@field hidden_placement? nvim_tree.Config.Renderer.Icons.Placement +--- +---(default: `signcolumn`) +---@field bookmarks_placement? nvim_tree.Config.Renderer.Icons.Placement +--- +---@field padding? nvim_tree.Config.Renderer.Icons.Padding +--- +---Separator between symlink source and target. +---(default: ` ➛ `) +---@field symlink_arrow? string +--- +---[nvim_tree.Config.Renderer.Icons.Show] +---@field show? nvim_tree.Config.Renderer.Icons.Show +--- +---[nvim_tree.Config.Renderer.Icons.Glyphs] +---@field glyphs? nvim_tree.Config.Renderer.Icons.Glyphs + + + +---Configure optional plugin `nvim-tree/nvim-web-devicons`. +--- +---Overrides glyphs and highlight groups where noted. +--- +---@class nvim_tree.Config.Renderer.Icons.WebDevicons +--- +---@field file? nvim_tree.Config.Renderer.Icons.WebDevicons.File +--- +---@field folder? nvim_tree.Config.Renderer.Icons.WebDevicons.Folder + + + +---[nvim_tree.Config.Renderer.Icons.WebDevicons.File]() +---@class nvim_tree.Config.Renderer.Icons.WebDevicons.File +---@inlinedoc +--- +---Show icons for files, overrides [nvim_tree.Config.Renderer.Icons.Glyphs.Git]. +---(default: `true`) +---@field enable? boolean +--- +---Apply colours to files, overrides `NvimTreeFileIcon`. +---(default: `true`) +---@field color? boolean + + +---[nvim_tree.Config.Renderer.Icons.WebDevicons.Folder]() +---@class nvim_tree.Config.Renderer.Icons.WebDevicons.Folder +---@inlinedoc +--- +---Show icons for directories, overrides [nvim_tree.Config.Renderer.Icons.Glyphs.Folder]. +---(default: `false`) +---@field enable? boolean +--- +---Apply colors to directories, overrides `NvimTree*FolderName`. +---(default: `true`) +---@field color? boolean + + + +---[nvim_tree.Config.Renderer.Icons.Padding]() +---@class nvim_tree.Config.Renderer.Icons.Padding +---@inlinedoc +--- +---Between icon and filename. +---(default: ` `) +---@field icon? string +--- +---Between folder arrow icon and file/folder icon. +---(default: ` `) +---@field folder_arrow? string + + + +---Control which icons are displayed. +--- +---Left to right ordered: +---- {file} +---- {folder} +---- {git} +---- {modified} +---- {hidden} +---- {diagnostics} +---- {bookmarks} +--- +---@class nvim_tree.Config.Renderer.Icons.Show +--- +---Before file name. +---(default: `true`) +---@field file? boolean +--- +---Before folder name. +---(default: `true`) +---@field folder? boolean +--- +---Show a small arrow before the folder node. Arrow will be a part of the node when using [nvim_tree.Config.Renderer.IndentMarkers]. +---(default: `true`) +---@field folder_arrow? boolean +--- +---Location: [nvim_tree.Config.Renderer.Icons] {git_placement}. +---Icons: [nvim_tree.Config.Renderer.Icons.Glyphs.Git]. +---Requires [nvim_tree.Config.Git]. +---(default: `true`) +---@field git? boolean +--- +---Location: [nvim_tree.Config.Renderer.Icons] {modified_placement}. +---Requires [nvim_tree.Config.Modified]. +---(default: `true`) +---@field modified? boolean +--- +---Location: [nvim_tree.Config.Renderer.Icons] {hidden_placement}. +---(default: `false`) +---@field hidden? boolean +--- +---Location: [nvim_tree.Config.Renderer.Icons] {diagnostics_placement}. +---Icons: [nvim_tree.Config.Diagnostics.Icons]. +---Requires [nvim_tree.Config.Diagnostics]. +---(default: `true`) +---@field diagnostics? boolean +--- +---Location: [nvim_tree.Config.Renderer.Icons] {bookmarks_placement}. +---(default: `true`) +---@field bookmarks? boolean + + + +---Glyphs that appear in the sign column must have length <= 2 +--- +---Glyphs defined elsewhere: +---- [nvim_tree.Config.Diagnostics.Icons] +---- [nvim_tree.Config.Renderer.IndentMarkers.Icons] +---@class nvim_tree.Config.Renderer.Icons.Glyphs +--- +---Files, overridden by [nvim_tree.Config.Renderer.Icons.WebDevicons]. +---(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.WebDevicons]. +---@field folder? nvim_tree.Config.Renderer.Icons.Glyphs.Folder +--- +---Git status on files and directories. +---@field git? nvim_tree.Config.Renderer.Icons.Glyphs.Git + + + +---[nvim_tree.Config.Renderer.Icons.Glyphs.Folder]() +---@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 + + + +---[nvim_tree.Config.Renderer.Icons.Glyphs.Git]() +---@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/sort.lua b/lua/nvim-tree/_meta/config/sort.lua new file mode 100644 index 00000000000..e1e7bb3e4cc --- /dev/null +++ b/lua/nvim-tree/_meta/config/sort.lua @@ -0,0 +1,49 @@ +---@meta +error("Cannot require a meta file") + + + +---@alias nvim_tree.Config.Sort.Sorter "name"|"case_sensitive"|"modification_time"|"extension"|"suffix"|"filetype" + + + +---@brief +---Sort files within a directory. +--- +---{sorter} presets [nvim_tree.Config.Sort.Sorter]() +---- `name` +---- `case_sensitive` name +---- `modification_time` +---- `extension` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz` +---- `suffix` uses the last e.g. `foo.tar.gz` -> `.gz` +---- `filetype` [filetype] +--- +---{sorter} may be a function that is passed a list of `nvim_tree.api.Node` to be sorted in place e.g. +---```lua +--- +------Sort by name length +------@param nodes nvim_tree.api.Node[] +------@return nvim_tree.Config.Sort.Sorter? +---local sorter = function(nodes) +--- table.sort(nodes, function(a, b) +--- return #a.name < #b.name +--- end) +---end +---``` +---{sorter} may be a function that returns a [nvim_tree.Config.Sort.Sorter] + + + +---@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..dffd5eaea77 --- /dev/null +++ b/lua/nvim-tree/_meta/config/system_open.lua @@ -0,0 +1,28 @@ +---@meta +error("Cannot require a meta file") + + + +---@brief +---Open files or directories via the OS. +--- +---Nvim: +---- `>=` 0.10 uses [vim.ui.open()] unless {cmd} is specified +---- `<` 0.10 calls external {cmd}: +--- - UNIX: `xdg-open` +--- - macOS: `open` +--- - Windows: `cmd` +--- +---Once nvim-tree minimum Nvim version is updated to 0.10, these options will no longer be necessary and will be removed. + + + +---@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..7fc5f9f2146 --- /dev/null +++ b/lua/nvim-tree/_meta/config/tab.lua @@ -0,0 +1,26 @@ +---@meta +error("Cannot require a meta file") + + + +---@class nvim_tree.Config.Tab +--- +---[nvim_tree.Config.Tab.Sync] +---@field sync? nvim_tree.Config.Tab.Sync + + + +---@class nvim_tree.Config.Tab.Sync +--- +---Opens the tree automatically when switching tabpage or opening a new tabpage if the tree was previously open. +---(default: `false`) +---@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..4724caa956d --- /dev/null +++ b/lua/nvim-tree/_meta/config/trash.lua @@ -0,0 +1,18 @@ +---@meta +error("Cannot require a meta file") + + + +---@brief +---Files may be trashed via an external command that must be installed on your system. +--- - linux: `gio trash`, from linux package `glib2` +--- - macOS: `trash`, from homebrew package `trash` +--- - windows: `trash`, requires `trash-cli` or similar + + + +---@class nvim_tree.Config.Trash +--- +---External command. +---(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..b1b50905359 --- /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 + + + +---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..0f0b5b571df --- /dev/null +++ b/lua/nvim-tree/_meta/config/update_focused_file.lua @@ -0,0 +1,38 @@ +---@meta +error("Cannot require a meta file") + + + +---@brief +---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. +--- +---Requires [nvim_tree.Config.UpdateFocusedFile] +--- +---@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..dfcddaa0449 --- /dev/null +++ b/lua/nvim-tree/_meta/config/view.lua @@ -0,0 +1,113 @@ +---@meta +error("Cannot require a meta file") + + + +---@alias nvim_tree.Config.View.WidthSpec string|integer|(fun(): integer|string) + + + +---@brief +---Configures the dimensions and appearance of the nvim-tree window. +--- +---The window is "docked" at the left by default, however may be configured to float: [nvim_tree.Config.View.Float] +--- +---{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 +--- +---{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 275e68635d0..077fe6580c6 100644 --- a/lua/nvim-tree/view.lua +++ b/lua/nvim-tree/view.lua @@ -438,7 +438,7 @@ function M.abandon_all_windows() end end ----@param opts table|nil +---@param opts? nvim_tree.api.TreeIsVisibleOpts ---@return boolean function M.is_visible(opts) if opts and opts.tabpage then @@ -487,7 +487,7 @@ function M.focus(winnr, open_if_closed) end --- Retrieve the winid of the open tree. ----@param opts ApiTreeWinIdOpts|nil +---@param opts nvim_tree.api.TreeWinIdOpts|nil ---@return number|nil winid unlike get_winnr(), this returns nil if the nvim-tree window is not visible function M.winid(opts) local tabpage = opts and opts.tabpage diff --git a/scripts/gen_vimdoc.sh b/scripts/gen_vimdoc.sh new file mode 100755 index 00000000000..03ebf5d89f8 --- /dev/null +++ b/scripts/gen_vimdoc.sh @@ -0,0 +1,39 @@ +#!/usr/bin/env sh + +# Wrapper around nvim help generator gen_vimdoc.lua, run as part of nvim's make doc target. +# +# Doesn't require nvim to have been built. +# +# Shims our moudules into gen_vimdoc_config.lua, replacing nvim's. +# +# There are some hardcoded expectations which we work around as commented. + +set -e + +if [ ! -d "${NVIM_SRC}" ]; then + echo "\$NVIM_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 "${NVIM_SRC}/src/gen/gen_vimdoc.lua" gen_vimdoc.lua +sed -i -E 's/spairs\(config\)/spairs\(require("gen_vimdoc_config")\)/g' gen_vimdoc.lua + +# use luacacts etc. from neovim src as well as our specific config +export LUA_PATH="${NVIM_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..72271a4be63 --- /dev/null +++ b/scripts/gen_vimdoc_config.lua @@ -0,0 +1,88 @@ +---@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-bookmarks", title = "Class: Config.Bookmarks", path = "lua/nvim-tree/_meta/config/bookmarks.lua", }, + { helptag = "nvim-tree-config-help", title = "Class: Config.Help", path = "lua/nvim-tree/_meta/config/help.lua", }, + { helptag = "nvim-tree-config-ui", title = "Class: Config.UI", path = "lua/nvim-tree/_meta/config/ui.lua", name = "UI", }, + { helptag = "nvim-tree-config-log", title = "Class: Config.Log", path = "lua/nvim-tree/_meta/config/log.lua", }, + + -- { 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 diff --git a/scripts/help-update.sh b/scripts/help-update.sh index b888e61cd33..7fe52a263f2 100755 --- a/scripts/help-update.sh +++ b/scripts/help-update.sh @@ -21,39 +21,6 @@ sed -e "s/^ / /" /tmp/DEFAULT_OPTS.2.lua > /tmp/DEFAULT_OPTS.6.lua sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/DEFAULT_OPTS.6.lua }; /${end}/p; d; }" doc/nvim-tree-lua.txt - -# -# opts index -# -begin="nvim-tree-index-opts\*" -end="=====================" - -printf '\n' > /tmp/index-opts.txt -sed -E " -/^ *\*(nvim-tree\..*)\*$/! d ; -s/^.*\*(.*)\*/|\1|/g -" doc/nvim-tree-lua.txt | sort -d >> /tmp/index-opts.txt -printf '\n' >> /tmp/index-opts.txt - -sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/index-opts.txt - }; /${end}/p; d; }" doc/nvim-tree-lua.txt - -# -# api index -# -begin="nvim-tree-index-api\*" -end="=====================" - -printf '\n' > /tmp/index-api.txt -sed -E " -/\*(nvim-tree-api.*\(\))\*/! d ; -s/^.*\*(.*)\*/|\1|/g -" doc/nvim-tree-lua.txt | sort -d >> /tmp/index-api.txt -printf '\n' >> /tmp/index-api.txt - -sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/index-api.txt - }; /${end}/p; d; }" doc/nvim-tree-lua.txt - # # DEFAULT_ON_ATTACH # diff --git a/scripts/lintdoc.sh b/scripts/lintdoc.sh new file mode 100755 index 00000000000..978f2d79b54 --- /dev/null +++ b/scripts/lintdoc.sh @@ -0,0 +1,32 @@ +#!/usr/bin/env sh + +# Wrapper around nvim help linter lintdoc.lua, run as part of nvim's make lintdoc target. +# +# Requires nvim to have been built. +# +# Desired: +# - tags valid +# - links valid +# Also: +# - brand spelling, notably Nvim and Lua +# +# There are some hardcoded expectations which we work around as commented. + +set -e + +if [ ! -d "${NVIM_SRC}" ]; then + echo "\$NVIM_SRC not set" + exit 1 +fi + +# runtime/doc in the nvim source is practically hardcoded, copy our help in +cp -v "doc/nvim-tree-lua.txt" "${NVIM_SRC}/runtime/doc" + +# run from within nvim source +cd "${NVIM_SRC}" + +# make nvim +make + +# execute the lint +VIMRUNTIME=runtime scripts/lintdoc.lua