diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 385b33b5b07..86b0b49d32e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -53,6 +53,7 @@ jobs: env: VIMRUNTIME: /home/runner/nvim-${{ matrix.nvim_version }}/share/nvim/runtime + DIR_NVIM_SRC: /home/runner/src/neovim-${{ matrix.nvim_version }} steps: - name: checkout @@ -72,8 +73,15 @@ jobs: - run: make check - - run: make help-check - - run: make style - run: make style-doc + + - name: build Nvim from source + run: | + mkdir -p "${DIR_NVIM_SRC}" + curl -L "https://github.com/neovim/neovim/archive/refs/tags/${{ matrix.nvim_version }}.tar.gz" | tar zx --directory "${DIR_NVIM_SRC}/.." + cd "${DIR_NVIM_SRC}" + make + + - run: make help-check diff --git a/.gitignore b/.gitignore index faee0c43dd9..97422fc2180 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ /luals-out/ /luals/ +/src/ # backup vim files *~ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 07118f01c2d..50bff754ea3 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 @@ -120,19 +121,32 @@ else end ``` -# Adding New Actions +# Documentation -To add a new action, add a file in `actions/name-of-the-action.lua`. You should export a `setup` function if some configuration is needed. +## Config And Mappings -Once you did, you should run `make help-update` +When adding to or changing: +1. `DEFAULT_OPTS` +2. `Config` classes +3. `on_attach` default mappings -# Documentation +You must generate help documentation. This requires neovim stable sources. You will be promted with instructions on fetching and referencing the source. -## Opts +```sh +make help-update +``` -When adding new options, you should declare the defaults in the main `nvim-tree.lua` file. +This will: +1. Update config defaults in `*nvim-tree-setup*` +2. Regenerate from `*nvim-tree-config*` to the end of the file, see `gen_vimdoc.sh` +3. Update default mappings in `*nvim-tree-mappings-default*` and `*nvim-tree-quickstart-help*` + +Commit your changes then run: +```sh +make help-check +``` -Documentation for options should also be added to `nvim-tree-opts` in `doc/nvim-tree-lua.txt` +This will re-run `help-update` and check that there are no diffs. It will also lint the documentation, see `lintdoc.sh` ## API diff --git a/Makefile b/Makefile index 72326964a79..9b3b00cc71a 100644 --- a/Makefile +++ b/Makefile @@ -36,12 +36,15 @@ style-fix: # help-update: scripts/help-update.sh + scripts/gen_vimdoc.sh # # CI +# --ignore-blank-lines is used as nightly has removed unnecessary blank lines that stable (0.11.5) currently inserts # help-check: help-update - git diff --exit-code doc/nvim-tree-lua.txt + git diff --ignore-blank-lines --exit-code doc/nvim-tree-lua.txt + @scripts/lintdoc.sh .PHONY: all lint style check luacheck style-check style-doc luals style-fix help-update help-check diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 40a17a6c867..b055e7dabac 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -1,71 +1,10 @@ -*nvim-tree.lua* A File Explorer For Neovim Written In Lua +*nvim-tree-lua.txt* A File Explorer For Nvim *nvim_tree* *nvim-tree* Author: Yazdani Kiyan + Type |gO| to see the table of contents. ============================================================================== -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| - -============================================================================== - 1. INTRODUCTION *nvim-tree-introduction* +Introduction *nvim-tree-introduction* Features @@ -85,7 +24,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 +45,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 +57,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 +89,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` @@ -216,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" @@ -244,7 +184,7 @@ via |nvim-tree.on_attach| e.g. >lua } < ============================================================================== - 2.4 QUICKSTART: HIGHLIGHT *nvim-tree-quickstart-highlight* +Quickstart: Highlight Groups *nvim-tree-quickstart-highlight* Run |:NvimTreeHiTest| to show all the highlights that nvim-tree uses. @@ -258,10 +198,10 @@ applied at runtime. e.g. >lua :hi link NvimTreeImageFile Title ]]) < -See |nvim-tree-highlight| for details. +See |nvim-tree-highlight-groups| for details. ============================================================================== - 3. COMMANDS *nvim-tree-commands* +Commands *nvim-tree-commands* *:NvimTreeOpen* @@ -363,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. @@ -377,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", @@ -664,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") @@ -1743,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. @@ -1758,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. @@ -1773,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. @@ -1787,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 @@ -1854,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()* @@ -1883,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. @@ -1947,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. @@ -1963,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 @@ -2049,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 @@ -2069,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 @@ -2086,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 @@ -2098,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 @@ -2110,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 @@ -2122,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 @@ -2135,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 @@ -2157,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 @@ -2177,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 @@ -2189,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 @@ -2208,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. @@ -2221,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}) @@ -2235,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}) @@ -2245,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}) @@ -2279,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. @@ -2289,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. @@ -2337,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}) @@ -2358,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. @@ -2402,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()| @@ -2413,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: ~ @@ -2440,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| @@ -2452,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 @@ -2461,13 +1331,13 @@ 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. -When on_attach is not a function, |nvim-tree-mappings-default| will be used. +When {on_attach} is not a function, |nvim-tree-mappings-default| will be used. Active mappings may be viewed via HELP, default `g?`. The mapping's description is used when displaying HELP. @@ -2506,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 @@ -2525,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 -will be applied. +In the absence of an |nvim_tree.Config| {on_attach} function, the following +defaults will be applied. -You are encouraged to copy these to your own |nvim-tree.on_attach| function. >lua +You are encouraged to copy these to your {on_attach} function. >lua local api = require("nvim-tree.api") @@ -2600,7 +1468,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) @@ -2615,8 +1483,67 @@ Alternatively, you may apply these default mappings from your |nvim-tree.on_atta -- your removals and mappings go here end < + ============================================================================== - 8. HIGHLIGHT *nvim-tree-highlight* +Icons And Highlighting *nvim-tree-icons-highlighting* + +Icons may be displayed before files and directories. + +Additional icons and highlighting may be displayed to indicate various states +for files and and directories. + +Highlighting is additive, with higher precedence overriding lower. + +|nvim_tree.Config.Renderer| {decorators} controls which highlighting is +applied and its precedence. See |nvim-tree-decorators| for information on +creating custom decorators. +< +`ICON` + Enable via |nvim_tree.Config.Renderer.Icons.Show + +`REQUIRES` + Feature must be enabled to show icons and highlighting. + +`PLACEMENT` *nvim_tree.Config.Renderer.Icons.Placement* + Where to place the icon: |nvim_tree.Config.Renderer.Icons| {_placement} + • `before`: before file/folder, after the file/folders icons + • `after`: after file/folder + • `signcolumn`: far left, requires |nvim_tree.Config.View| {signcolumn}. + • `right_align`: far right + +`HIGHLIGHT` *nvim_tree.Config.Renderer.Highlight* + What should be highlighted: |nvim_tree.Config.Renderer| {highlight_} + • `none`: no highlighting + • `icon`: icon only + • `name`: name only + • `all`: icon and name + +`DEVICONS` + Glyphs and their colors will be overridden by optional plugin: + `nvim-tree/nvim-web-devicons` |nvim_tree.Config.Renderer.Icons.WebDevicons| + +`GLYPHS` + Icon glyphs definitions. + +`GROUPS` + Applicable highlight groups: |nvim-tree-highlight-groups| + +Some defaults noted. In ascending order of default highlight precedence: + +`WHAT ICON REQUIRES PLACEMENT HIGHLIGHT GLYPHS DEVICONS GROUPS` +File Icon {file} Y - - - |nvim_tree.Config.Renderer.Icons.Glyphs| {default} Y `NvimTreeNormal`, `NvimTreeFileIcon` +Folder Icon {folder} Y - - - |nvim_tree.Config.Renderer.Icons.Glyphs.Folder| Y `NvimTree*FolderName`, `NvimTree*FolderIcon` +Git Status {git} Y |nvim_tree.Config.Git| {git_placement} `"before"` {highlight_git} `"none"` |nvim_tree.Config.Renderer.Icons.Glyphs.Git| N `NvimTreeGit*` +|bufloaded()| - - - {highlight_opened_files}`"none"` - N ` NvimTreeOpened*` +Dotfiles {hidden} N - {hidden_placement} `"after"` {highlight_hidden} `"none"` |nvim_tree.Config.Renderer.Icons.Glyphs| {hidden} N `NvimTreeHidden*` +|'modified'| {modified} Y |nvim_tree.Config.Modified| {modified_placement} `"after"` {highlight_modified} `"none"` |nvim_tree.Config.Renderer.Icons.Glyphs| {modified} N `NvimTreeModified*` +Bookmarked {bookmarks} Y - {bookmarks_placement} `"signcolumn"` {highlight_bookmarks} `"none"` |nvim_tree.Config.Renderer.Icons.Glyphs| {bookmark} N `NvimTreeBookmark*` +Diag Status {diagnostics}Y |nvim_tree.Config.Diagnostics| {diagnostics_placement}`"signcolumn"` {highlight_diagnostics} `"none" ` |nvim_tree.Config.Diagnostics.Icons| N `NvimTreeDiagnostic*` +Cut/Copied - - - {highlight_clipboard} `"name"` - N `NvimTreeCutHL`, `NvimTreeCopiedHL` + + +============================================================================== +Highlight Groups *nvim-tree-highlight-groups* All the following highlight groups can be configured by hand. Aside from `NvimTreeWindowPicker`, it is not advised to colorize the background of these @@ -2625,7 +1552,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| @@ -2633,7 +1560,7 @@ To view the nvim-tree highlight groups run |:NvimTreeHiTest| To view all active highlight groups run `:so $VIMRUNTIME/syntax/hitest.vim` as per |:highlight| -The `*HL` groups are additive as per |nvim-tree-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 @@ -2649,7 +1576,7 @@ To prevent usage of a highlight: :hi! link NvimTreeExecFile NONE < ============================================================================== - 8.1 HIGHLIGHT: DEFAULT *nvim-tree-highlight-default* +Highlight Groups: Default *nvim-tree-highlight-groups-default* |:highlight-link| `default` or |:highlight-default| define the groups on setup: @@ -2775,46 +1702,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 @@ -2824,7 +1712,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| @@ -2838,7 +1726,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. @@ -2846,7 +1734,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 @@ -2902,20 +1790,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: @@ -2935,10 +1823,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 @@ -2960,7 +1848,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. @@ -2971,14 +1859,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. @@ -3073,18 +1959,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 @@ -3099,37 +1985,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: > @@ -3177,288 +2063,1009 @@ highlight group is not, hard linking as follows: > NvimTreeLspDiagnosticsInformationFolderText NvimTreeDiagnosticInfoFolderHL NvimTreeLspDiagnosticsHintFolderText NvimTreeDiagnosticHintFolderHL < + +============================================================================== +Hidden Display *nvim-tree-hidden-display* + +Show a summary of hidden files below the tree highlighted with `NvimTreeHiddenDisplay + +Configure via |nvim_tree.Config.Renderer| {hidden_display} + + *nvim_tree.Config.Renderer.HiddenDisplay* + • `none`: disabled + • `simple`: show how many hidden files are in a folder + • `all`: show how many hidden and the number of hidden files by reason + • `fun(hidden_stats: table): string`: returns a summary of hidden stats + +Example `"all"`: +If a folder has 14 hidden items for various reasons, the display might show: > + (14 total git: 5, dotfile: 9) +< +If a function is provided, it receives a table `hidden_stats` where keys are +reasons and values are the count of hidden files for that reason. + +The `hidden_stats` argument is structured as follows, where is the number +of hidden files related to the field: > + hidden_stats = { + bookmark = , + buf = , + custom = , + dotfile = , + git = , + live_filter = , + } +< +Example of function that can be passed: >lua + function(hidden_stats) + local total_count = 0 + for reason, count in pairs(hidden_stats) do + total_count = total_count + count + end + + if total_count > 0 then + return "(" .. tostring(total_count) .. " hidden)" + end + return nil + end +< + +============================================================================== +Class: Config *nvim-tree-config* + +*nvim_tree.Config* + Arguments to pass to |nvim-tree-setup|. + + When a value is not present/nil, the default will be used. + + They can be validated by |lsp| when passed directly e.g. >lua + require("nvim-tree").setup({ + hijack_cursor = true, + }) +< + + or as a typed variable e.g. >lua + ---@type nvim_tree.Config + local config = { + hijack_cursor = true, + } + require("nvim-tree").setup(config) +< + + {on_attach} Runs when creating the nvim-tree buffer. Use this to set your + |nvim-tree-mappings|. When not a function, |nvim-tree-mappings-default| + will be used. + + {hijack_cursor} keep the cursor on the first letter of the filename when + moving in the tree. + + {auto_reload_on_write} reload the explorer every time a buffer is written + to. + + {disable_netrw} completely disables |netrw|, see |nvim-tree-netrw| for + details. It is strongly advised to eagerly disable netrw, due to race + conditions at vim startup. + + {hijack_netrw} hijacks netrw windows, ignored when {disable_netrw}. + + {hijack_unnamed_buffer_when_opening} opens in place of the unnamed buffer + if it's empty. + + {root_dirs} preferred root directories, requires + |nvim_tree.Config.UpdateFocusedFile.UpdateRoot|. + + {prefer_startup_root} prefer startup root directory when updating root + directory of the tree. Requires + |nvim_tree.Config.UpdateFocusedFile.UpdateRoot|. + + {sync_root_with_cwd} changes the tree root directory on |DirChanged| and + refreshes the tree. + + {reload_on_bufenter} automatically reloads the tree on |BufEnter| + nvim-tree. + + {respect_buf_cwd} changes the |current-directory| of nvim-tree to that of + new buffer's when opening nvim-tree. + + {select_prompts} uses |vim.ui.select()| style prompts. Necessary when + using a UI prompt decorator such as dressing.nvim or + telescope-ui-select.nvim + + Fields: ~ + • {on_attach}? (`"default"|(fun(bufnr: integer))`) + (default: `default`) + • {hijack_cursor}? (`boolean`) (default: `false`) + • {auto_reload_on_write}? (`boolean`) (default: `true`) + • {disable_netrw}? (`boolean`) (default: `false`) + • {hijack_netrw}? (`boolean`) (default: `true`) + • {hijack_unnamed_buffer_when_opening}? (`boolean`) (default: `false`) + • {root_dirs}? (`string[]`) (default: `{}`) + • {prefer_startup_root}? (`boolean`) (default: `false`) + • {sync_root_with_cwd}? (`boolean`) (default: `false`) + • {reload_on_bufenter}? (`boolean`) (default: `false`) + • {respect_buf_cwd}? (`boolean`) (default: `false`) + • {select_prompts}? (`boolean`) (default: `false`) + • {sort}? (`nvim_tree.Config.Sort`) + |nvim_tree.Config.Sort| + • {view}? (`nvim_tree.Config.View`) + |nvim_tree.Config.View| + • {renderer}? (`nvim_tree.Config.Renderer`) + |nvim_tree.Config.Renderer| + • {hijack_directories}? (`nvim_tree.Config.HijackDirectories`) + |nvim_tree.Config.HijackDirectories| + • {update_focused_file}? (`nvim_tree.Config.UpdateFocusedFile`) + |nvim_tree.Config.UpdateFocusedFile| + • {system_open}? (`nvim_tree.Config.SystemOpen`) + |nvim_tree.Config.SystemOpen| + • {git}? (`nvim_tree.Config.Git`) + |nvim_tree.Config.Git| + • {diagnostics}? (`nvim_tree.Config.Diagnostics`) + |nvim_tree.Config.Diagnostics| + • {modified}? (`nvim_tree.Config.Modified`) + |nvim_tree.Config.Modified| + • {filters}? (`nvim_tree.Config.Filters`) + |nvim_tree.Config.Filters| + • {live_filter}? (`nvim_tree.Config.LiveFilter`) + |nvim_tree.Config.LiveFilter| + • {filesystem_watchers}? (`nvim_tree.Config.FilesystemWatchers`) + |nvim_tree.Config.FilesystemWatchers| + • {actions}? (`nvim_tree.Config.Actions`) + |nvim_tree.Config.Actions| + • {trash}? (`nvim_tree.Config.Trash`) + |nvim_tree.Config.Trash| + • {tab}? (`nvim_tree.Config.Tab`) + |nvim_tree.Config.Tab| + • {bookmarks}? (`nvim_tree.Config.Bookmarks`) + |nvim_tree.Config.Bookmarks| + • {notify}? (`nvim_tree.Config.Notify`) + |nvim_tree.Config.Notify| + • {help}? (`nvim_tree.Config.Help`) + |nvim_tree.Config.Help| + • {ui}? (`nvim_tree.Config.UI`) + |nvim_tree.Config.UI| + • {experimental}? (`nvim_tree.Config.Experimental`) + |nvim_tree.Config.Experimental| + • {log}? (`nvim_tree.Config.Log`) + |nvim_tree.Config.Log| + + + +============================================================================== +Class: Config.Sort *nvim-tree-config-sort* + +*nvim_tree.Config.Sort* + Sort files within a directory. + + {sorter} presets *nvim_tree.Config.Sort.Sorter* + • `"name"` + • `"case_sensitive"` name + • `"modification_time"` + • `"extension"` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz` + • `"suffix"` uses the last e.g. `foo.tar.gz` -> `.gz` + • `"filetype"` |filetype| + + {sorter} may be a function that is passed a list of `nvim_tree.api.Node` + to be sorted in place e.g. >lua + + ---Sort by name length + ---@param nodes nvim_tree.api.Node[] + ---@return nvim_tree.Config.Sort.Sorter? + local sorter = function(nodes) + table.sort(nodes, function(a, b) + return #a.name < #b.name + end) + end +< + + {sorter} may be a function that returns a |nvim_tree.Config.Sort.Sorter| + + Fields: ~ + • {sorter}? (`nvim_tree.Config.Sort.Sorter|(fun(nodes: nvim_tree.api.Node[]): nvim_tree.Config.Sort.Sorter?)`) + (default: `"name"`) + • {folders_first}? (`boolean`, default: `true`) Sort folders before + files. Has no effect when {sorter} is a function. + • {files_first}? (`boolean`, default: `false`) Sort files before + folders. Has no effect when {sorter} is a function. + Overrides {folders_first}. + + + +============================================================================== +Class: Config.View *nvim-tree-config-view* + +*nvim_tree.Config.View* + Configures the dimensions and appearance of the nvim-tree window. + + The window is "docked" at the left by default, however may be configured + to float: |nvim_tree.Config.View.Float| + + {width} can be a |nvim_tree.Config.View.WidthSpec| for simple static + control or a |nvim_tree.Config.View.Width| for fully dynamic control based + on longest line. + + *nvim_tree.Config.View.WidthSpec* + • `string`: `x%` string e.g. `30%` + • `integer`: number of columns + • `function`: returns one of the above + + Fields: ~ + • {centralize_selection}? (`boolean`, default: `false`) When + entering nvim-tree, reposition the + view so that the current node is + initially centralized, see |zz|. + • {cursorline}? (`boolean`, default: `true`) + |'cursorline'| + • {cursorlineopt}? (`string`, default: `both`) + |'cursorlineopt'| + • {debounce_delay}? (`integer`, default: `15`) Idle + milliseconds before some reload / + refresh operations. Increase if you + experience performance issues around + screen refresh. + • {side}? (`"left"|"right"`) (default: `"left"`) + • {preserve_window_proportions}? (`boolean`, default: `false`) + Preserves window proportions when + opening a file. If `false`, the height + and width of windows other than + nvim-tree will be equalized. + • {number}? (`boolean`, default: `false`) + |'number'| + • {relativenumber}? (`boolean`, default: `false`) + |'relativenumber'| + • {signcolumn}? (`"yes"|"auto"|"no"`, default: + `"yes"`) |'signcolumn'| + • {width}? (`nvim_tree.Config.View.WidthSpec|nvim_tree.Config.View.Width`) + (default: `30`) + • {float}? (`nvim_tree.Config.View.Float`) + |nvim_tree.Config.View.Float| + +*nvim_tree.Config.View.Float* + Configure floating window behaviour + + {open_win_config} is passed 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: + `{ relative = "editor", border = "rounded", width = 30, height = 30, row = 1, col = 1, }`) + +*nvim_tree.Config.View.Width* + Configure dynamic width based on longest line. + + Fields: ~ + • {min}? (`nvim_tree.Config.View.WidthSpec`) (default: `30`) + • {max}? (`nvim_tree.Config.View.WidthSpec`, default: `-1`) + -1 for unbounded. + • {lines_excluded}? (`("root")[]`, default: `{ "root" }`) Exclude these + lines when computing width. + • {padding}? (`nvim_tree.Config.View.WidthSpec`, default: `1`) + Extra padding to the right. + + + +============================================================================== +Class: Config.Renderer *nvim-tree-config-renderer* + +*nvim_tree.Config.Renderer* + Controls the appearance of the tree. + + See |nvim-tree-icons-highlighting| for {highlight_} and {decorators} + fields. + + {root_folder_label} has 3 forms: + • `string`: |filename-modifiers| format string, default `":~:s?$?/..?"` + • `boolean`: `true` to disable + • `fun(root_cwd: string): string`: return a literal string from root's + absolute path e.g. >lua + my_root_folder_label = function(path) + return ".../" .. vim.fn.fnamemodify(path, ":t") + end +< + + Fields: ~ + • {add_trailing}? (`boolean`, default: `false`) Appends a + trailing slash to folder and symlink folder + target names. + • {group_empty}? (`boolean|(fun(relative_path: string): string)`, default: `false`) + Compact folders that only contain a single + folder into one node. Function variant + takes the relative path of grouped folders + and returns a string to be displayed. + • {full_name}? (`boolean`, default: `false`) Display nodes + whose name length is wider than the width + of nvim-tree window in floating window. + • {root_folder_label}? (`string|boolean|(fun(root_cwd: string): string)`) + (default: `":~:s?$?/..?"`) + • {indent_width}? (`integer`, default: `2`) Number of spaces + for each tree nesting level. Minimum 1. + • {hidden_display}? (`nvim_tree.Config.Renderer.HiddenDisplay`, default: `none`) + |nvim-tree-hidden-display| + • {symlink_destination}? (`boolean`, default: `true`) Appends an + arrow followed by the target of the + symlink. + • {decorators}? (`(string|nvim_tree.api.decorator.UserDecorator)[]`) + (default: + `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) + • {highlight_git}? (`nvim_tree.Config.Renderer.Highlight`) + (default: `"none"`) + • {highlight_opened_files}? (`nvim_tree.Config.Renderer.Highlight`) + (default: `"none"`) + • {highlight_hidden}? (`nvim_tree.Config.Renderer.Highlight`) + (default: `"none"`) + • {highlight_modified}? (`nvim_tree.Config.Renderer.Highlight`) + (default: `"none"`) + • {highlight_bookmarks}? (`nvim_tree.Config.Renderer.Highlight`) + (default: `"none"`) + • {highlight_diagnostics}? (`nvim_tree.Config.Renderer.Highlight`) + (default: `"none"`) + • {highlight_clipboard}? (`nvim_tree.Config.Renderer.Highlight`) + (default: `"name"`) + • {special_files}? (`string[]`, default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }`) + Highlight special files and directories + with `NvimTreeSpecial*`. + • {indent_markers}? (`nvim_tree.Config.Renderer.IndentMarkers`) + |nvim_tree.Config.Renderer.IndentMarkers| + • {icons}? (`nvim_tree.Config.Renderer.Icons`) + |nvim_tree.Config.Renderer.Icons| + +*nvim_tree.Config.Renderer.Icons* + Icons and separators + + See |nvim-tree-icons-highlighting| for: {_placement} fields. + + Fields: ~ + • {git_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`) + (default: `before`) + • {hidden_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`) + (default: `after`) + • {modified_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`) + (default: `after`) + • {bookmarks_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`) + (default: `signcolumn`) + • {diagnostics_placement}? (`nvim_tree.Config.Renderer.Icons.Placement`) + (default: `signcolumn`) + • {padding}? (`table`) + *nvim_tree.Config.Renderer.Icons.Padding* + • {icon}? (`string`, default: `" "`) Between + icon and filename. + • {folder_arrow}? (`string`, default: `" "`) + Between folder arrow icon and file/folder + icon. + • {symlink_arrow}? (`string`, default: `" ➛ "`) Separator + between symlink source and target. + • {show}? (`nvim_tree.Config.Renderer.Icons.Show`) + |nvim_tree.Config.Renderer.Icons.Show| + • {glyphs}? (`nvim_tree.Config.Renderer.Icons.Glyphs`) + |nvim_tree.Config.Renderer.Icons.Glyphs| + • {web_devicons}? (`nvim_tree.Config.Renderer.Icons.WebDevicons`) + |nvim_tree.Config.Renderer.Icons.WebDevicons| + +*nvim_tree.Config.Renderer.Icons.Glyphs* + See |nvim-tree-icons-highlighting|. + + Glyphs that appear in the sign column must have length <= 2 + + Fields: ~ + • {default}? (`string`, default: `""`) Files + • {symlink}? (`string`) (default: `""`) + • {bookmark}? (`string`) (default: `"󰆤"`) + • {modified}? (`string`) (default: `"●"`) + • {hidden}? (`string`) (default: `"󰜌"`) + • {folder}? (`table`) *nvim_tree.Config.Renderer.Icons.Glyphs.Folder* + • {arrow_closed}? (`string`) (default: left arrow) + • {arrow_open}? (`string`) (default: down arrow) + • {default}? (`string`) (default: `""`) + • {open}? (`string`) (default: `""`) + • {empty}? (`string`) (default: `""`) + • {empty_open}? (`string`) (default: `""`) + • {symlink}? (`string`) (default: `""`) + • {symlink_open}? (`string`) (default: `""`) + • {git}? (`table`) *nvim_tree.Config.Renderer.Icons.Glyphs.Git* + • {unstaged}? (`string`) (default: `"✗"`) + • {staged}? (`string`) (default: `"✓"`) + • {unmerged}? (`string`) (default: `""`) + • {renamed}? (`string`) (default: `"➜"`) + • {untracked}? (`string`) (default: `"★"`) + • {deleted}? (`string`) (default: `""`) + • {ignored}? (`string`) (default: `"◌"`) + +*nvim_tree.Config.Renderer.Icons.Show* + See |nvim-tree-icons-highlighting|. + + Fields: ~ + • {file}? (`boolean`) (default: `true`) + • {folder}? (`boolean`) (default: `true`) + • {git}? (`boolean`) (default: `true`) + • {modified}? (`boolean`) (default: `true`) + • {hidden}? (`boolean`) (default: `false`) + • {diagnostics}? (`boolean`) (default: `true`) + • {bookmarks}? (`boolean`) (default: `true`) + • {folder_arrow}? (`boolean`, default: `true`) Show a small arrow + before the folder node. Arrow will be a part of the + node when using + |nvim_tree.Config.Renderer.IndentMarkers|. + +*nvim_tree.Config.Renderer.Icons.WebDevicons* + Configure optional plugin `nvim-tree/nvim-web-devicons`, see + |nvim-tree-icons-highlighting|. + + Fields: ~ + • {file}? (`table`) + *nvim_tree.Config.Renderer.Icons.WebDevicons.File* + • {enable}? (`boolean`) (default: `true`) + • {color}? (`boolean`) (default: `true`) + • {folder}? (`table`) + *nvim_tree.Config.Renderer.Icons.WebDevicons.Folder* + • {enable}? (`boolean`) (default: `false`) + • {color}? (`boolean`) (default: `true`) + +*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* + +*nvim_tree.Config.HijackDirectories* + Hijack directory buffers by replacing the directory buffer with the tree. + + Disable this option if you use vim-dirvish or dirbuf.nvim. + + If |nvim_tree.Config| {hijack_netrw} and {disable_netrw} are `false` this + feature will be disabled. + + Fields: ~ + • {enable}? (`boolean`) (default: `true`) + • {auto_open}? (`boolean`, default: `true`) Open if the tree was + previously closed. + + + +============================================================================== +Class: Config.UpdateFocusedFile *nvim-tree-config-update-focused-file* + +*nvim_tree.Config.UpdateFocusedFile* + Update the focused file on |BufEnter|, uncollapsing folders recursively. + + Fields: ~ + • {enable}? (`boolean`) (default: `false`) + • {update_root}? (`nvim_tree.Config.UpdateFocusedFile.UpdateRoot`) + |nvim_tree.Config.UpdateFocusedFile.UpdateRoot| + • {exclude}? (`boolean|(fun(args: vim.api.keyset.create_autocmd.callback_args): boolean)`, default: `false`) + A function called on |BufEnter| that returns true if + the file should not be focused when opening. + +*nvim_tree.Config.UpdateFocusedFile.UpdateRoot* + Update the root directory of the tree if the file is not under the current + root directory. + + Prefers vim's cwd and |nvim_tree.Config| {root_dirs}, falling back to the + directory containing the file. + + 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* + +*nvim_tree.Config.SystemOpen* + Open files or directories via the OS. + + Nvim: + • `>=` 0.10 uses |vim.ui.open()| unless {cmd} is specified + • `<` 0.10 calls external {cmd}: + • UNIX: `xdg-open` + • macOS: `open` + • Windows: `cmd` + + Once nvim-tree minimum Nvim version is updated to 0.10, these options will + no longer be necessary and will be removed. + + Fields: ~ + • {cmd}? (`string`) The open command itself + • {args}? (`string[]`, default: `{}` or `{ "/c", "start", '""' }` on + windows) Optional argument list. Leave empty for OS specific + default. + + + +============================================================================== +Class: Config.Git *nvim-tree-config-git* + +*nvim_tree.Config.Git* + Git operations are run in the background thus status may not immediately + appear. + + Processes will be killed if they exceed {timeout} ms. Git integration will + be disabled following 5 timeouts and you will be notified. + + Git integration may be disabled for git top-level directories via + {disable_for_dirs}: + • A list of relative paths evaluated with |fnamemodify()| `:p` OR + • A function that is passed an absolute path and returns `true` to disable + + See |nvim-tree-icons-highlighting|. + + 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* + +*nvim_tree.Config.Diagnostics* + Integrate with |lsp| or COC diagnostics. + + See |nvim-tree-icons-highlighting|. + + 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* + +*nvim_tree.Config.Modified* + Indicate which files have unsaved modification. To see modified status in + the tree you will need: + • |nvim_tree.Config.Renderer.Icons.Show| {modified} OR + • |nvim_tree.Config.Renderer| {highlight_modified} + + See |nvim-tree-icons-highlighting|. + + Fields: ~ + • {enable}? (`boolean`) (default: `false`) + • {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* + +*nvim_tree.Config.Filters* + Filters may be applied to the tree to exlude the display of + file/directories. + + Multiple filters may be applied at once. + + Filters can be set at startup or toggled live via API with default + mappings. + + `I `{git_ignored}` `|nvim-tree-api.tree.toggle_gitignore_filter()| + Ignore files based on `.gitignore`. Requires |nvim_tree.Config.Git| + + `H `{dotfiles}` `|nvim-tree-api.tree.toggle_hidden_filter()| + Filter dotfiles: files/directories starting with a `.` + + `C `{git_clean}` `|nvim-tree-api.tree.toggle_git_clean_filter()| + Filter files with no git status. `.gitignore` files will not be filtered + when {git_ignored}, as they are effectively dirty. + + `B `{no_buffer}` `|nvim-tree-api.tree.toggle_no_buffer_filter()| + Filter files that have no |buflisted()| buffer. For performance reasons + buffer delete/wipe may not be immediately shown. A reload or filesystem + event will always result in an update. + + `M `{no_bookmark}` `|nvim-tree-api.tree.toggle_no_bookmark_filter()| + Filter files that are not bookmarked. Enabling this is not useful as there + is no means yet to persist bookmarks. + + `U `{custom}` `|nvim-tree-api.tree.toggle_custom_filter()| + Disable specific file/directory names via: + • a list of backslash escaped |vim.regex| strings e.g. `"^\\.git""` + • a function passed the absolute path of the directory. + + All filters including live filter may be disabled via {enable} and toggled + with |nvim-tree-api.tree.toggle_enable_filters()| + + Files/directories may be {exclude}d from filtering: they will always be + shown, overriding {git_ignored}, {dotfiles} and {custom}. + + Fields: ~ + • {enable}? (`boolean`, default: `true`) Enable all filters. + • {git_ignored}? (`boolean`) (default: `true`) + • {dotfiles}? (`boolean`) (default: `false`) + • {git_clean}? (`boolean`) (default: `false`) + • {no_buffer}? (`boolean`) (default: `false`) + • {no_bookmark}? (`boolean`) (default: `false`) + • {custom}? (`string[]|(fun(absolute_path: string): boolean)`) + (default: `{}`) + • {exclude}? (`string[]`) (default: `{}`) + + + +============================================================================== +Class: Config.LiveFilter *nvim-tree-config-live-filter* + +*nvim_tree.Config.LiveFilter* + Live filter allows you to filter the tree nodes dynamically, based on + regex matching, see |vim.regex| + + This feature is bound to the `f` key by default. The filter can be cleared + with the `F` key by default. + + Fields: ~ + • {prefix}? (`string`, default: `"[FILTER]: "`) Prefix of + the filter displayed in the buffer. + • {always_show_folders}? (`boolean`, default: `true`) Whether to filter + folders or not. + + + +============================================================================== +Class: Config.FilesystemWatchers *nvim-tree-config-filesystem-watchers* + +*nvim_tree.Config.FilesystemWatchers* + Use file system watchers (libuv `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. + + 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 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: + `{ col = 1, row = 1, relative = "cursor", border = "shadow", style = "minimal", }`) + +*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 {picker} function that should return the window id that + will open the node, or `nil` if an invalid window is picked or user + cancelled the action. The picker may create a new window. + + Fields: ~ + • {enable}? (`boolean`) (default: `true`) + • {picker}? (`"default"|(fun(): integer)`, default: `"default"`) + Change the default window picker or define your own. + • {chars}? (`string`, default: + `"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"`) Identifier + characters to use. + • {exclude}? (`nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude`) + |nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude| + +*nvim_tree.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. + + + ============================================================================== - 15 INDEX *nvim-tree-index* +Class: Config.Trash *nvim-tree-config-trash* + +*nvim_tree.Config.Trash* + Files may be trashed via an external command that must be installed on + your system. + • linux: `gio trash`, from linux package `glib2` + • macOS: `trash`, from homebrew package `trash` + • windows: `trash`, requires `trash-cli` or similar + + Fields: ~ + • {cmd}? (`string`) (default: `"gio trash"` or `"trash"`) + + ============================================================================== - 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.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` + + ============================================================================== - 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.Notify *nvim-tree-config-notify* + +*nvim_tree.Config.Notify* + nvim-tree |vim.log.levels| + • `ERROR`: hard errors e.g. failure to read from the file system. + • `WARN`: non-fatal errors e.g. unable to system open a file. + • `INFO`: information only e.g. file copy path confirmation. + • `DEBUG`: information for troubleshooting, e.g. failures in some window + closing operations. + + Fields: ~ + • {threshold}? (`vim.log.levels`, default: `vim.log.levels.INFO`) + Specify minimum notification |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* - vim:tw=78:ts=4:sw=4:et:ft=help:norl: +*nvim_tree.Config.Bookmarks* + Optionally {persist} bookmarks to a json file: + • `true` use default: `stdpath("data") .. "/nvim-tree-bookmarks.json"` + • `false` do not persist + • `string` absolute path of your choice + + Fields: ~ + • {persist}? (`boolean|string`) (default: `false`) + + + +============================================================================== +Class: Config.Help *nvim-tree-config-help* + +*nvim_tree.Config.Help* + Configure help window, default mapping `g?` + + *nvim_tree.Config.Help.SortBy* + • `"key"`: alphabetically by keymap + • `"desc"`: alphabetically by description + + Fields: ~ + • {sort_by}? (`nvim_tree.Config.Help.SortBy`, default: `"key"`) + |nvim_tree.Config.Help.SortBy| + + + +============================================================================== +Class: Config.UI *nvim-tree-config-ui* + +*nvim_tree.Config.UI* + + Fields: ~ + • {confirm}? (`nvim_tree.Config.UI.Confirm`) + |nvim_tree.Config.UI.Confirm| + +*nvim_tree.Config.UI.Confirm* + Confirmation prompts. + + 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.Experimental *nvim-tree-config-experimental* + +*nvim_tree.Config.Experimental* + Experimental features that may become default or optional functionality. + + In the event of a problem please disable the experiment and raise an + issue. + + + +============================================================================== +Class: Config.Log *nvim-tree-config-log* + +*nvim_tree.Config.Log* + Log to a file `nvim-tree.log` in |stdpath()| `log`, usually + `${XDG_STATE_HOME}/nvim` + + Fields: ~ + • {enable}? (`boolean`) (default: `false`) + • {truncate}? (`boolean`, default: `false`) Remove existing log file at + startup. + • {types}? (`nvim_tree.Config.Log.Types`) + |nvim_tree.Config.Log.Types| + +*nvim_tree.Config.Log.Types* + Specify which information to log. + + Fields: ~ + • {all}? (`boolean`, default: `false`) Everything. + • {profile}? (`boolean`, default: `false`) Timing of some + operations. + • {config}? (`boolean`, default: `false`) Options and mappings, at + startup. + • {copy_paste}? (`boolean`, default: `false`) File copy and paste + actions. + • {dev}? (`boolean`, default: `false`) Used for local + development only. Not useful for users. + • {diagnostics}? (`boolean`, default: `false`) LSP and COC processing, + verbose. + • {git}? (`boolean`, default: `false`) Git processing, verbose. + • {watcher}? (`boolean`, default: `false`) + |nvim_tree.Config.FilesystemWatchers| processing, + verbose. + + + + vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: diff --git a/lua/nvim-tree.lua b/lua/nvim-tree.lua index 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/config.lua b/lua/nvim-tree/_meta/config.lua new file mode 100644 index 00000000000..aa3f7aa1b1f --- /dev/null +++ b/lua/nvim-tree/_meta/config.lua @@ -0,0 +1,151 @@ +---@meta +error("Cannot require a meta file") + + + +-- Root class {field}s are documented manually above "Fields:" as there is insufficent room for them in the column. + + + +---Arguments to pass to [nvim-tree-setup]. +--- +---When a value is not present/nil, the default will be used. +--- +---They can be validated by |lsp| when passed directly e.g. +---```lua +--- require("nvim-tree").setup({ +--- hijack_cursor = true, +--- }) +---``` +--- +---or as a typed variable e.g. +---```lua +--- ---@type nvim_tree.Config +--- local config = { +--- hijack_cursor = true, +--- } +--- require("nvim-tree").setup(config) +---``` +---{on_attach} Runs when creating the nvim-tree buffer. Use this to set your [nvim-tree-mappings]. When not a function, [nvim-tree-mappings-default] will be used. +--- +---{hijack_cursor} keep the cursor on the first letter of the filename when moving in the tree. +--- +---{auto_reload_on_write} reload the explorer every time a buffer is written to. +--- +---{disable_netrw} completely disables [netrw], see [nvim-tree-netrw] for details. It is strongly advised to eagerly disable netrw, due to race conditions at vim startup. +--- +---{hijack_netrw} hijacks netrw windows, ignored when {disable_netrw}. +--- +---{hijack_unnamed_buffer_when_opening} opens in place of the unnamed buffer if it's empty. +--- +---{root_dirs} preferred root directories, requires [nvim_tree.Config.UpdateFocusedFile.UpdateRoot]. +--- +---{prefer_startup_root} prefer startup root directory when updating root directory of the tree. Requires [nvim_tree.Config.UpdateFocusedFile.UpdateRoot]. +--- +---{sync_root_with_cwd} changes the tree root directory on [DirChanged] and refreshes the tree. +--- +---{reload_on_bufenter} automatically reloads the tree on [BufEnter] nvim-tree. +--- +---{respect_buf_cwd} changes the [current-directory] of nvim-tree to that of new buffer's when opening nvim-tree. +--- +---{select_prompts} uses [vim.ui.select()] style prompts. Necessary when using a UI prompt decorator such as dressing.nvim or telescope-ui-select.nvim +---@class nvim_tree.Config +--- +---(default: `default`) +---@field on_attach? "default"|(fun(bufnr: integer)) +--- +---(default: `false`) +---@field hijack_cursor? boolean +--- +---(default: `true`) +---@field auto_reload_on_write? boolean +--- +---(default: `false`) +---@field disable_netrw? boolean +--- +---(default: `true`) +---@field hijack_netrw? boolean +--- +---(default: `false`) +---@field hijack_unnamed_buffer_when_opening? boolean +--- +---(default: `{}`) +---@field root_dirs? string[] +--- +---(default: `false`) +---@field prefer_startup_root? boolean +--- +---(default: `false`) +---@field sync_root_with_cwd? boolean +--- +---(default: `false`) +---@field reload_on_bufenter? boolean +--- +---(default: `false`) +---@field respect_buf_cwd? boolean +--- +---(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.Experimental] +---@field experimental? nvim_tree.Config.Experimental +--- +---[nvim_tree.Config.Log] +---@field log? nvim_tree.Config.Log diff --git a/lua/nvim-tree/_meta/config/actions.lua b/lua/nvim-tree/_meta/config/actions.lua new file mode 100644 index 00000000000..e65fe4d79c4 --- /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 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: `{ col = 1, row = 1, relative = "cursor", border = "shadow", style = "minimal", }`) +---@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 {picker} function that should return the window id that will open the node, or `nil` if an invalid window is picked or user cancelled the action. The picker may create a new window. +--- +---@class nvim_tree.Config.Actions.OpenFile.WindowPicker +--- +---(default: `true`) +---@field enable? boolean +--- +---Change the default window picker or define your own. +---(default: `"default"`) +---@field picker? "default"|(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..83a3c3d0ac3 --- /dev/null +++ b/lua/nvim-tree/_meta/config/bookmarks.lua @@ -0,0 +1,13 @@ +---@meta +error("Cannot require a meta file") + + +---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..44b0d6d4f8c --- /dev/null +++ b/lua/nvim-tree/_meta/config/diagnostics.lua @@ -0,0 +1,65 @@ +---@meta +error("Cannot require a meta file") + + + +---Integrate with [lsp] or COC diagnostics. +--- +---See [nvim-tree-icons-highlighting]. +--- +---@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/experimental.lua b/lua/nvim-tree/_meta/config/experimental.lua new file mode 100644 index 00000000000..ce2afeeb1c8 --- /dev/null +++ b/lua/nvim-tree/_meta/config/experimental.lua @@ -0,0 +1,17 @@ +---@meta +error("Cannot require a meta file") + + + +---Experimental features that may become default or optional functionality. +--- +---In the event of a problem please disable the experiment and raise an issue. +--- +---@class nvim_tree.Config.Experimental +--- +--Example below for future reference: +-- +--Buffers opened by nvim-tree will use with relative paths instead of absolute. +--(default: false) +--@field relative_path? boolean + diff --git a/lua/nvim-tree/_meta/config/filesystem_watchers.lua b/lua/nvim-tree/_meta/config/filesystem_watchers.lua new file mode 100644 index 00000000000..959d70017ac --- /dev/null +++ b/lua/nvim-tree/_meta/config/filesystem_watchers.lua @@ -0,0 +1,26 @@ +---@meta +error("Cannot require a meta file") + + + +---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..93de5d64733 --- /dev/null +++ b/lua/nvim-tree/_meta/config/filters.lua @@ -0,0 +1,60 @@ +---@meta +error("Cannot require a meta file") + + + +---Filters may be applied to the tree to exlude the display of file/directories. +--- +---Multiple filters may be applied at once. +--- +---Filters can be set at startup or toggled live via API with default mappings. +--- +---`I `{git_ignored}` `|nvim-tree-api.tree.toggle_gitignore_filter()| +---Ignore files based on `.gitignore`. Requires |nvim_tree.Config.Git| +--- +---`H `{dotfiles}` `|nvim-tree-api.tree.toggle_hidden_filter()| +---Filter dotfiles: files/directories starting with a `.` +--- +---`C `{git_clean}` `|nvim-tree-api.tree.toggle_git_clean_filter()| +---Filter files with no git status. `.gitignore` files will not be filtered when {git_ignored}, as they are effectively dirty. +--- +---`B `{no_buffer}` `|nvim-tree-api.tree.toggle_no_buffer_filter()| +---Filter files that have no |buflisted()| buffer. For performance reasons buffer delete/wipe may not be immediately shown. A reload or filesystem event will always result in an update. +--- +---`M `{no_bookmark}` `|nvim-tree-api.tree.toggle_no_bookmark_filter()| +---Filter files that are not bookmarked. Enabling this is not useful as there is no means yet to persist bookmarks. +--- +---`U `{custom}` `|nvim-tree-api.tree.toggle_custom_filter()| +---Disable specific file/directory names via: +---- a list of backslash escaped |vim.regex| strings e.g. `"^\\.git""` +---- a function passed the absolute path of the directory. +--- +---All filters including live filter may be disabled via {enable} and toggled with |nvim-tree-api.tree.toggle_enable_filters()| +--- +---Files/directories may be {exclude}d from filtering: they will always be shown, overriding {git_ignored}, {dotfiles} and {custom}. +---@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..318fec0aed1 --- /dev/null +++ b/lua/nvim-tree/_meta/config/git.lua @@ -0,0 +1,39 @@ +---@meta +error("Cannot require a meta file") + + + +---Git operations are run in the background thus status may not immediately appear. +--- +---Processes will be killed if they exceed {timeout} ms. Git integration will be disabled following 5 timeouts and you will be notified. +--- +---Git integration may be disabled for git top-level directories via {disable_for_dirs}: +--- - A list of relative paths evaluated with [fnamemodify()] `:p` OR +--- - A function that is passed an absolute path and returns `true` to disable +--- +---See [nvim-tree-icons-highlighting]. +--- +---@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..8724b397c6f --- /dev/null +++ b/lua/nvim-tree/_meta/config/help.lua @@ -0,0 +1,20 @@ +---@meta +error("Cannot require a meta file") + + + +---@alias nvim_tree.Config.Help.SortBy "key"|"desc" + + + +---Configure help window, default mapping `g?` +--- +---[nvim_tree.Config.Help.SortBy]() +---- `"key"`: alphabetically by keymap +---- `"desc"`: alphabetically by description +--- +---@class nvim_tree.Config.Help +--- +---[nvim_tree.Config.Help.SortBy] +---(default: `"key"`) +---@field sort_by? nvim_tree.Config.Help.SortBy diff --git a/lua/nvim-tree/_meta/config/hijack_directories.lua b/lua/nvim-tree/_meta/config/hijack_directories.lua new file mode 100644 index 00000000000..af601f4ac1e --- /dev/null +++ b/lua/nvim-tree/_meta/config/hijack_directories.lua @@ -0,0 +1,19 @@ +---@meta +error("Cannot require a meta file") + + + +---Hijack directory buffers by replacing the directory buffer with the tree. +--- +---Disable this option if you use vim-dirvish or dirbuf.nvim. +--- +---If [nvim_tree.Config] {hijack_netrw} and {disable_netrw} are `false` this feature will be disabled. +--- +---@class nvim_tree.Config.HijackDirectories +--- +---(default: `true`) +---@field enable? boolean +--- +---Open if the tree was previously closed. +---(default: `true`) +---@field auto_open? boolean diff --git a/lua/nvim-tree/_meta/config/live_filter.lua b/lua/nvim-tree/_meta/config/live_filter.lua new file mode 100644 index 00000000000..b5569a68d93 --- /dev/null +++ b/lua/nvim-tree/_meta/config/live_filter.lua @@ -0,0 +1,18 @@ +---@meta +error("Cannot require a meta file") + + + +--- Live filter allows you to filter the tree nodes dynamically, based on regex matching, see [vim.regex] +--- +--- This feature is bound to the `f` key by default. The filter can be cleared with the `F` key by default. +--- +---@class nvim_tree.Config.LiveFilter +--- +---Prefix of the filter displayed in the buffer. +---(default: `"[FILTER]: "`) +---@field prefix? string +--- +---Whether to filter folders or not. +---(default: `true`) +---@field always_show_folders? boolean diff --git a/lua/nvim-tree/_meta/config/log.lua b/lua/nvim-tree/_meta/config/log.lua new file mode 100644 index 00000000000..3f43101f2f8 --- /dev/null +++ b/lua/nvim-tree/_meta/config/log.lua @@ -0,0 +1,53 @@ +---@meta +error("Cannot require a meta file") + + + +---Log to a file `nvim-tree.log` in [stdpath()] `log`, usually `${XDG_STATE_HOME}/nvim` +--- +---@class nvim_tree.Config.Log +--- +---(default: `false`) +---@field enable? boolean +--- +---Remove existing log file at startup. +---(default: `false`) +---@field truncate? boolean +--- +---[nvim_tree.Config.Log.Types] +---@field types? nvim_tree.Config.Log.Types + +---Specify which information to log. +---@class nvim_tree.Config.Log.Types +--- +---Everything. +---(default: `false`) +---@field all? boolean +--- +--- Timing of some operations. +---(default: `false`) +---@field profile? boolean +--- +---Options and mappings, at startup. +---(default: `false`) +---@field config? boolean +--- +---File copy and paste actions. +---(default: `false`) +---@field copy_paste? boolean +--- +---Used for local development only. Not useful for users. +---(default: `false`) +---@field dev? boolean +--- +---LSP and COC processing, verbose. +---(default: `false`) +---@field diagnostics? boolean +--- +---Git processing, verbose. +---(default: `false`) +---@field git? boolean +--- +---[nvim_tree.Config.FilesystemWatchers] processing, verbose. +---(default: `false`) +---@field watcher? boolean diff --git a/lua/nvim-tree/_meta/config/modified.lua b/lua/nvim-tree/_meta/config/modified.lua new file mode 100644 index 00000000000..e527d6ee62e --- /dev/null +++ b/lua/nvim-tree/_meta/config/modified.lua @@ -0,0 +1,24 @@ +---@meta +error("Cannot require a meta file") + + + +---Indicate which files have unsaved modification. +---To see modified status in the tree you will need: +--- - [nvim_tree.Config.Renderer.Icons.Show] {modified} OR +--- - [nvim_tree.Config.Renderer] {highlight_modified} +--- +---See [nvim-tree-icons-highlighting]. +--- +---@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..bf6b9493005 --- /dev/null +++ b/lua/nvim-tree/_meta/config/notify.lua @@ -0,0 +1,20 @@ +---@meta +error("Cannot require a meta file") + + + +---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..08f052b8393 --- /dev/null +++ b/lua/nvim-tree/_meta/config/renderer.lua @@ -0,0 +1,303 @@ +---@meta +error("Cannot require a meta file") + + + +---@alias nvim_tree.Config.Renderer.Highlight "none"|"icon"|"name"|"all" + +---@alias nvim_tree.Config.Renderer.HiddenDisplay "none"|"simple"|"all"|(fun(hidden_stats: table): string) + +---@alias nvim_tree.Config.Renderer.Icons.Placement "before"|"after"|"signcolumn"|"right_align" + + + +---Controls the appearance of the tree. +--- +---See [nvim-tree-icons-highlighting] for {highlight_} and {decorators} fields. +--- +---{root_folder_label} has 3 forms: +---- `string`: [filename-modifiers] format string, default `":~:s?$?/..?"` +---- `boolean`: `true` to disable +---- `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 +--- +---(default: `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`) +---@field decorators? (string|nvim_tree.api.decorator.UserDecorator)[] +--- +---(default: `"none"`) +---@field highlight_git? nvim_tree.Config.Renderer.Highlight +--- +---(default: `"none"`) +---@field highlight_opened_files? nvim_tree.Config.Renderer.Highlight +--- +---(default: `"none"`) +---@field highlight_hidden? nvim_tree.Config.Renderer.Highlight +--- +---(default: `"none"`) +---@field highlight_modified? nvim_tree.Config.Renderer.Highlight +--- +---(default: `"none"`) +---@field highlight_bookmarks? nvim_tree.Config.Renderer.Highlight +--- +---(default: `"none"`) +---@field highlight_diagnostics? nvim_tree.Config.Renderer.Highlight +--- +---(default: `"name"`) +---@field highlight_clipboard? nvim_tree.Config.Renderer.Highlight +--- +---Highlight special files and directories with `NvimTreeSpecial*`. +---(default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }`) +---@field special_files? string[] +--- +---[nvim_tree.Config.Renderer.IndentMarkers] +---@field indent_markers? nvim_tree.Config.Renderer.IndentMarkers +--- +---[nvim_tree.Config.Renderer.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 +--- +---See [nvim-tree-icons-highlighting] for: {_placement} fields. +---@class nvim_tree.Config.Renderer.Icons +--- +---(default: `before`) +---@field git_placement? nvim_tree.Config.Renderer.Icons.Placement +--- +---(default: `after`) +---@field hidden_placement? nvim_tree.Config.Renderer.Icons.Placement +--- +---(default: `after`) +---@field modified_placement? nvim_tree.Config.Renderer.Icons.Placement +--- +---(default: `signcolumn`) +---@field bookmarks_placement? nvim_tree.Config.Renderer.Icons.Placement +--- +---(default: `signcolumn`) +---@field diagnostics_placement? nvim_tree.Config.Renderer.Icons.Placement +--- +---@field padding? nvim_tree.Config.Renderer.Icons.Padding +--- +---Separator between symlink source and target. +---(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 +--- +---[nvim_tree.Config.Renderer.Icons.WebDevicons] +---@field web_devicons? nvim_tree.Config.Renderer.Icons.WebDevicons + + + +---Configure optional plugin `nvim-tree/nvim-web-devicons`, see [nvim-tree-icons-highlighting]. +--- +---@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 +--- +---(default: `true`) +---@field enable? boolean +--- +---(default: `true`) +---@field color? boolean + + +---[nvim_tree.Config.Renderer.Icons.WebDevicons.Folder]() +---@class nvim_tree.Config.Renderer.Icons.WebDevicons.Folder +---@inlinedoc +--- +---(default: `false`) +---@field enable? boolean +--- +---(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 + + + +---See [nvim-tree-icons-highlighting]. +---@class nvim_tree.Config.Renderer.Icons.Show +--- +---(default: `true`) +---@field file? boolean +--- +---(default: `true`) +---@field folder? boolean +--- +---(default: `true`) +---@field git? boolean +--- +---(default: `true`) +---@field modified? boolean +--- +---(default: `false`) +---@field hidden? boolean +--- +---(default: `true`) +---@field diagnostics? boolean +--- +---(default: `true`) +---@field bookmarks? boolean +--- +---Show a small arrow before the folder node. Arrow will be a part of the node when using [nvim_tree.Config.Renderer.IndentMarkers]. +---(default: `true`) +---@field folder_arrow? boolean + + + +---See [nvim-tree-icons-highlighting]. +--- +---Glyphs that appear in the sign column must have length <= 2 +---@class nvim_tree.Config.Renderer.Icons.Glyphs +--- +---Files +---(default: `""`) +---@field default? string +--- +---(default: `""`) +---@field symlink? string +--- +---(default: `"󰆤"`) +---@field bookmark? string +--- +---(default: `"●"`) +---@field modified? string +--- +---(default: `"󰜌"`) +---@field hidden? string +--- +---@field folder? nvim_tree.Config.Renderer.Icons.Glyphs.Folder +--- +---@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..0646ab587a2 --- /dev/null +++ b/lua/nvim-tree/_meta/config/sort.lua @@ -0,0 +1,45 @@ +---@meta +error("Cannot require a meta file") + + + +---@alias nvim_tree.Config.Sort.Sorter "name"|"case_sensitive"|"modification_time"|"extension"|"suffix"|"filetype" + + + +---Sort files within a directory. +--- +---{sorter} 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..00ea263e11a --- /dev/null +++ b/lua/nvim-tree/_meta/config/system_open.lua @@ -0,0 +1,24 @@ +---@meta +error("Cannot require a meta file") + + + +---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 +---@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..ad7a6f48cfc --- /dev/null +++ b/lua/nvim-tree/_meta/config/trash.lua @@ -0,0 +1,14 @@ +---@meta +error("Cannot require a meta file") + + + +---Files may be trashed via an external command that must be installed on your system. +--- - linux: `gio trash`, from linux package `glib2` +--- - macOS: `trash`, from homebrew package `trash` +--- - windows: `trash`, requires `trash-cli` or similar +--- +---@class nvim_tree.Config.Trash +--- +---(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..a193cddc0bc --- /dev/null +++ b/lua/nvim-tree/_meta/config/update_focused_file.lua @@ -0,0 +1,35 @@ +---@meta +error("Cannot require a meta file") + + + +---Update the focused file on [BufEnter], uncollapsing folders recursively. +--- +---@class nvim_tree.Config.UpdateFocusedFile +--- +---(default: `false`) +---@field enable? boolean +--- +---[nvim_tree.Config.UpdateFocusedFile.UpdateRoot] +---@field update_root? nvim_tree.Config.UpdateFocusedFile.UpdateRoot +--- +---A function called on [BufEnter] that returns true if the file should not be focused when opening. +---(default: `false`) +---@field exclude? boolean|(fun(args: vim.api.keyset.create_autocmd.callback_args): boolean) + + + +---Update the root directory of the tree if the file is not under the current root directory. +--- +---Prefers vim's cwd and [nvim_tree.Config] {root_dirs}, falling back to the directory containing the file. +--- +---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..1a9d24d78a0 --- /dev/null +++ b/lua/nvim-tree/_meta/config/view.lua @@ -0,0 +1,110 @@ +---@meta +error("Cannot require a meta file") + + + +---@alias nvim_tree.Config.View.WidthSpec string|integer|(fun(): integer|string) + + + +---Configures the dimensions and appearance of the nvim-tree window. +--- +---The window is "docked" at the left by default, however may be configured to float: [nvim_tree.Config.View.Float] +--- +---{width} can be a [nvim_tree.Config.View.WidthSpec] for simple static control or a [nvim_tree.Config.View.Width] for fully dynamic control based on longest line. +--- +---[nvim_tree.Config.View.WidthSpec]() +---- `string`: `x%` string e.g. `30%` +---- `integer`: number of columns +---- `function`: returns one of the above +--- +---@class nvim_tree.Config.View +--- +---When entering nvim-tree, reposition the view so that the current node is initially centralized, see [zz]. +---(default: `false`) +---@field centralize_selection? boolean +--- +---['cursorline'] +---(default: `true`) +---@field cursorline? boolean +--- +---['cursorlineopt'] +---(default: `both`) +---@field cursorlineopt? string +--- +---Idle milliseconds before some reload / refresh operations. Increase if you experience performance issues around screen refresh. +---(default: `15`) +---@field debounce_delay? integer +--- +---(default: `"left"`) +---@field side? "left"|"right" +--- +---Preserves window proportions when opening a file. If `false`, the height and width of windows other than nvim-tree will be equalized. +---(default: `false`) +---@field preserve_window_proportions? boolean +--- +---['number'] +---(default: `false`) +---@field number? boolean +--- +---['relativenumber'] +---(default: `false`) +---@field relativenumber? boolean +--- +---['signcolumn'] +---(default: `"yes"`) +---@field signcolumn? "yes"|"auto"|"no" +--- +---(default: `30`) +---@field width? nvim_tree.Config.View.WidthSpec|nvim_tree.Config.View.Width +--- +---[nvim_tree.Config.View.Float] +---@field float? nvim_tree.Config.View.Float + + + +---Configure dynamic width based on longest line. +--- +---@class nvim_tree.Config.View.Width +--- +---(default: `30`) +---@field min? nvim_tree.Config.View.WidthSpec +--- +----1 for unbounded. +---(default: `-1`) +---@field max? nvim_tree.Config.View.WidthSpec +--- +---Exclude these lines when computing width. +---(default: `{ "root" }`) +---@field lines_excluded? ("root")[] +--- +---Extra padding to the right. +---(default: `1`) +---@field padding? nvim_tree.Config.View.WidthSpec + + + +---Configure floating window behaviour +--- +---{open_win_config} is passed 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: `{ relative = "editor", border = "rounded", width = 30, height = 30, row = 1, col = 1, }`) +---@field open_win_config? vim.api.keyset.win_config|(fun(): vim.api.keyset.win_config) diff --git a/scripts/gen_vimdoc.sh b/scripts/gen_vimdoc.sh new file mode 100755 index 00000000000..8af3aa0b49a --- /dev/null +++ b/scripts/gen_vimdoc.sh @@ -0,0 +1,71 @@ +#!/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 + +# unset to ensure no collisions with system installs etc. +unset VIMRUNTIME + +# Use a directory outside of nvim_tree source. Adding lua files inside will (rightly) upset luals. +DIR_NVT="${PWD}" +DIR_WORK="/tmp/nvim-tree-gen_vimdoc" +DIR_NVIM_SRC_DEF="/tmp/src/neovim-stable" + +if [ ! -f "${DIR_NVT}/scripts/gen_vimdoc.sh" ]; then + echo "Must be run from nvim-tree root" + exit 1 +fi + +if [ -z "${DIR_NVIM_SRC}" ] && [ -d "${DIR_NVIM_SRC_DEF}" ]; then + export DIR_NVIM_SRC="${DIR_NVIM_SRC_DEF}" + echo "Assumed DIR_NVIM_SRC=${DIR_NVIM_SRC}" +fi + +if [ ! -d "${DIR_NVIM_SRC}" ]; then + cat << EOM + +\$DIR_NVIM_SRC=${DIR_NVIM_SRC} not set or missing. + +Nvim source is required to run ${0} + +Please: + mkdir -p ${DIR_NVIM_SRC_DEF} + curl -L 'https://github.com/neovim/neovim/archive/refs/tags/stable.tar.gz' | tar zx --directory $(dirname "${DIR_NVIM_SRC_DEF}") + export DIR_NVIM_SRC=/tmp/src/neovim-stable +EOM +exit 1 +fi + +# clean up previous +rm -rfv "${DIR_WORK}" + +# runtime/doc is hardcoded, copy the help in +mkdir -pv "${DIR_WORK}/runtime/doc" +cp -v "${DIR_NVT}/doc/nvim-tree-lua.txt" "${DIR_WORK}/runtime/doc" + +# modify gen_vimdoc.lua to use our config +cp -v "${DIR_NVIM_SRC}/src/gen/gen_vimdoc.lua" "${DIR_WORK}/gen_vimdoc.lua" +sed -i -E 's/spairs\(config\)/spairs\(require("gen_vimdoc_config")\)/g' "${DIR_WORK}/gen_vimdoc.lua" + +# use luacacts etc. from neovim src as well as our specific config +export LUA_PATH="${DIR_NVIM_SRC}/src/?.lua;${DIR_NVT}/scripts/?.lua" + +# gen_vimdoc.lua doesn't like dashes in lua module names +# -> use nvim_tree instead of nvim-tree +mkdir -pv "${DIR_WORK}/lua" +ln -sv "${DIR_NVT}/lua/nvim-tree" "${DIR_WORK}/lua/nvim_tree" + +# generate +cd "${DIR_WORK}" && pwd +./gen_vimdoc.lua +cd - + +# copy the generated help out +cp -v "${DIR_WORK}/runtime/doc/nvim-tree-lua.txt" "${DIR_NVT}/doc" diff --git a/scripts/gen_vimdoc_config.lua b/scripts/gen_vimdoc_config.lua new file mode 100644 index 00000000000..e8dda6f50e1 --- /dev/null +++ b/scripts/gen_vimdoc_config.lua @@ -0,0 +1,86 @@ +---@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-experimental", title = "Class: Config.Experimental", path = "./lua/nvim_tree/_meta/config/experimental.lua", }, + { helptag = "nvim-tree-config-log", title = "Class: Config.Log", path = "./lua/nvim_tree/_meta/config/log.lua", }, +} + +-- hydrate file names +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..6b5b0a88d77 --- /dev/null +++ b/scripts/lintdoc.sh @@ -0,0 +1,57 @@ +#!/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 + +# unset to ensure no collisions with system installs etc. +unset VIMRUNTIME + +# Use a directory outside of nvim_tree source. Adding lua files inside will (rightly) upset luals. +DIR_NVT="${PWD}" +DIR_WORK="/tmp/nvim-tree-lintdoc" +DIR_NVIM_SRC_DEF="/tmp/src/neovim-stable" + +if [ ! -f "${DIR_NVT}/scripts/lintdoc.sh" ]; then + echo "Must be run from nvim-tree root" + exit 1 +fi + +if [ -z "${DIR_NVIM_SRC}" ] && [ -d "${DIR_NVIM_SRC_DEF}" ]; then + export DIR_NVIM_SRC="${DIR_NVIM_SRC_DEF}" + echo "Assumed DIR_NVIM_SRC=${DIR_NVIM_SRC}" +fi + +if [ ! -d "${DIR_NVIM_SRC}" ]; then + cat << EOM + +\$DIR_NVIM_SRC=${DIR_NVIM_SRC} not set or missing. + +Nvim source is required to run ${0} + +Please: + mkdir -p ${DIR_NVIM_SRC_DEF} + curl -L 'https://github.com/neovim/neovim/archive/refs/tags/stable.tar.gz' | tar zx --directory $(dirname "${DIR_NVIM_SRC_DEF}") + export DIR_NVIM_SRC=/tmp/src/neovim-stable +EOM +exit 1 +fi + +# runtime/doc in the Nvim source is practically hardcoded, copy our help in +cp -v "${DIR_NVT}/doc/nvim-tree-lua.txt" "${DIR_NVIM_SRC}/runtime/doc" + +# run from within Nvim source +cd "${DIR_NVIM_SRC}" + +# make nvim and execute the lint +make lintdoc