tomas.mirchev/nvim-tree.lua
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
116b88564f
nvim-tree.lua/doc/nvim-tree-lua.txt
Alexander Courtis 116b88564f
chore: use stdpath "log" rather than "cache" (#2372)
2023-08-14 11:03:38 +10:00

2327 lines
86 KiB
Plaintext
Raw Blame History

*nvim-tree.lua* A File Explorer For Neovim Written In Lua
Author: Yazdani Kiyan
==============================================================================
CONTENTS *nvim-tree*
1. Introduction |nvim-tree-introduction|
2. Quickstart |nvim-tree-quickstart|
3. Commands |nvim-tree-commands|
4. Setup/Configuration |nvim-tree-setup|
5. API |nvim-tree-api|
5.1 API Tree |nvim-tree-api.tree|
5.2 API File System |nvim-tree-api.fs|
5.3 API Node |nvim-tree-api.node|
5.4 API Git |nvim-tree-api.git|
5.5 API Events |nvim-tree-api.events|
5.6 API Live Filter |nvim-tree-api.live_filter|
5.7 API Marks |nvim-tree-api.marks|
5.8 API Config |nvim-tree-api.config|
5.9 API Commands |nvim-tree-api.commands|
6. Mappings |nvim-tree-mappings|
6.1 Default Mappings |nvim-tree-mappings-default|
6.2 Legacy Mappings |nvim-tree-mappings-legacy|
7. Highlight Groups |nvim-tree-highlight|
8. Events |nvim-tree-events|
9. Bookmarks |nvim-tree-bookmarks|
10. OS Specific Restrictions |nvim-tree-os-specific|
11. Netrw |nvim-tree-netrw|
==============================================================================
1. INTRODUCTION *nvim-tree-introduction*
Features
- Automatic updates
- File type icons
- Git integration
- Diagnostics integration: LSP and COC
- (Live) filtering
- Cut, copy, paste, rename, delete, create
- Highly customisable
File Icons
https://github.com/nvim-tree/nvim-web-devicons is optional and used to display file icons.
It requires a patched font: https://www.nerdfonts.com
Your terminal emulator must be configured to use that font, usually "Hack Nerd Font"
 should look like an open folder.
To disable the display of icons see |renderer.icons.show|
Colours
Syntax highlighting uses g:terminal_color_ from colorschemes, falls back to
ugly colors otherwise.
Git Integration
One or two icons for git status. When two are shown, the left is staged.
✗ unstaged
✓ staged
 unmerged
➜ renamed
★ untracked
 deleted
◌ ignored
Requirements
This file explorer requires `neovim >= 0.8.0`
==============================================================================
2. QUICK START *nvim-tree-quickstart*
Install the plugins via your package manager:
`"nvim-tree/nvim-tree.lua"`
`"nvim-tree/nvim-web-devicons"`
Disabling |netrw| is strongly advised, see |nvim-tree-netrw|
Setup the plugin in your `init.lua` >
-- disable netrw at the very start of your init.lua
vim.g.loaded_netrw = 1
vim.g.loaded_netrwPlugin = 1
-- set termguicolors to enable highlight groups
vim.opt.termguicolors = true
-- empty setup using defaults
require("nvim-tree").setup()
-- OR setup with some options
require("nvim-tree").setup({
sort = {
sorter = "case_sensitive",
},
view = {
width = 30,
},
renderer = {
group_empty = true,
},
filters = {
dotfiles = true,
},
})
<
Optionally customise your |nvim-tree-mappings| via |nvim-tree.on_attach| >
local function my_on_attach(bufnr)
local api = require "nvim-tree.api"
local function opts(desc)
return { desc = "nvim-tree: " .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true }
end
-- default mappings
api.config.mappings.default_on_attach(bufnr)
-- custom mappings
vim.keymap.set('n', '<C-t>', api.tree.change_root_to_parent, opts('Up'))
vim.keymap.set('n', '?', api.tree.toggle_help, opts('Help'))
end
-- pass to setup along with your other options
require("nvim-tree").setup {
---
on_attach = my_on_attach,
---
}
<
Open the tree: `:NvimTreeOpen`
Show the mappings: `g?`
`<C-]>` CD |nvim-tree-api.tree.change_root_to_node()|
`<C-e>` Open: In Place |nvim-tree-api.node.open.replace_tree_buffer()|
`<C-k>` Info |nvim-tree-api.node.show_info_popup()|
`<C-r>` Rename: Omit Filename |nvim-tree-api.fs.rename_sub()|
`<C-t>` Open: New Tab |nvim-tree-api.node.open.tab()|
`<C-v>` Open: Vertical Split |nvim-tree-api.node.open.vertical()|
`<C-x>` Open: Horizontal Split |nvim-tree-api.node.open.horizontal()|
`<BS>` Close Directory |nvim-tree-api.node.navigate.parent_close()|
`<CR>` Open |nvim-tree-api.node.open.edit()|
`<Tab>` Open Preview |nvim-tree-api.node.open.preview()|
`>` Next Sibling |nvim-tree-api.node.navigate.sibling.next()|
`<` Previous Sibling |nvim-tree-api.node.navigate.sibling.prev()|
`.` Run Command |nvim-tree-api.node.run.cmd()|
`-` Up |nvim-tree-api.tree.change_root_to_parent()|
`a` Create |nvim-tree-api.fs.create()|
`bd` Delete Bookmarked |nvim-tree-api.marks.bulk.delete()|
`bmv` Move Bookmarked |nvim-tree-api.marks.bulk.move()|
`B` Toggle Filter: No Buffer |nvim-tree-api.tree.toggle_no_buffer_filter()|
`c` Copy |nvim-tree-api.fs.copy.node()|
`C` Toggle Filter: Git Clean |nvim-tree-api.tree.toggle_git_clean_filter()|
`[c` Prev Git |nvim-tree-api.node.navigate.git.prev()|
`]c` Next Git |nvim-tree-api.node.navigate.git.next()|
`d` Delete |nvim-tree-api.fs.remove()|
`D` Trash |nvim-tree-api.fs.trash()|
`E` Expand All |nvim-tree-api.tree.expand_all()|
`e` Rename: Basename |nvim-tree-api.fs.rename_basename()|
`]e` Next Diagnostic |nvim-tree-api.node.navigate.diagnostics.next()|
`[e` Prev Diagnostic |nvim-tree-api.node.navigate.diagnostics.prev()|
`F` Clean Filter |nvim-tree-api.live_filter.clear()|
`f` Filter |nvim-tree-api.live_filter.start()|
`g?` Help |nvim-tree-api.tree.toggle_help()|
`gy` Copy Absolute Path |nvim-tree-api.fs.copy.absolute_path()|
`H` Toggle Filter: Dotfiles |nvim-tree-api.tree.toggle_hidden_filter()|
`I` Toggle Filter: Git Ignore |nvim-tree-api.tree.toggle_gitignore_filter()|
`J` Last Sibling |nvim-tree-api.node.navigate.sibling.last()|
`K` First Sibling |nvim-tree-api.node.navigate.sibling.first()|
`m` Toggle Bookmark |nvim-tree-api.marks.toggle()|
`o` Open |nvim-tree-api.node.open.edit()|
`O` Open: No Window Picker |nvim-tree-api.node.open.no_window_picker()|
`p` Paste |nvim-tree-api.fs.paste()|
`P` Parent Directory |nvim-tree-api.node.navigate.parent()|
`q` Close |nvim-tree-api.tree.close()|
`r` Rename |nvim-tree-api.fs.rename()|
`R` Refresh |nvim-tree-api.tree.reload()|
`s` Run System |nvim-tree-api.node.run.system()|
`S` Search |nvim-tree-api.tree.search_node()|
`U` Toggle Filter: Hidden |nvim-tree-api.tree.toggle_custom_filter()|
`W` Collapse |nvim-tree-api.tree.collapse_all()|
`x` Cut |nvim-tree-api.fs.cut()|
`y` Copy Name |nvim-tree-api.fs.copy.filename()|
`Y` Copy Relative Path |nvim-tree-api.fs.copy.relative_path()|
`<2-LeftMouse>` Open |nvim-tree-api.node.open.edit()|
`<2-RightMouse>` CD |nvim-tree-api.tree.change_root_to_node()|
==============================================================================
3. COMMANDS *nvim-tree-commands*
*:NvimTreeOpen*
Opens the tree. See |nvim-tree-api.tree.open()|
Calls: `api.tree.open({ path = "<arg>" })`
*:NvimTreeClose*
Closes the tree. See |nvim-tree-api.tree.close()|
Calls: `api.tree.close()`
*:NvimTreeToggle*
Open or close the tree. See |nvim-tree-api.tree.toggle()|
Calls: `api.tree.toggle({ path = "<arg>" })`
*:NvimTreeFocus*
Open the tree if it is closed, and then focus on the tree.
See |nvim-tree-api.tree.toggle()|
Calls: `api.tree.focus()`
*:NvimTreeRefresh*
Refresh the tree. See |nvim-tree-api.tree.reload()|
Calls: `api.tree.reload()`
*:NvimTreeFindFile*
The command will change the cursor in the tree for the current bufname.
It will also open the leafs of the tree leading to the file in the buffer
(if you opened a file with something else than the NvimTree, like `fzf` or
`:split`)
Invoke with a bang `:NvimTreeFindFile!` to update the root.
See |nvim-tree-api.tree.find_file()|
Calls: `api.tree.find_file { open = true, update_root = <bang> }`
*:NvimTreeFindFileToggle*
close the tree or change the cursor in the tree for the current bufname,
similar to combination of |:NvimTreeToggle| and |:NvimTreeFindFile|. Takes an
optional path argument.
Invoke with a bang `:NvimTreeFindFileToggle!` to update the root.
See |nvim-tree-api.tree.toggle()|
Calls: `api.tree.toggle { find_file = true, focus = true, path = "<arg>", update_root = <bang> }`
*:NvimTreeClipboard*
Print clipboard content for both cut and copy
See |nvim-tree-api.fs.print_clipboard()|
Calls: `api.fs.print_clipboard()`
*:NvimTreeResize*
Resize the NvimTree window to the given size. Example: `:NvimTreeResize 50`
resizes the window to the width of 50. If the size starts with "+" or "-" it
adds or removes the given value to the current window width.
Example `:NvimTreeResize -20` removes the value 20 from the current width. And
`:NvimTreeResize +20` adds the value 20 to the current width.
*:NvimTreeCollapse*
Collapses the nvim-tree recursively.
See |nvim-tree-api.tree.collapse_all()|
Calls: `api.tree.collapse_all(false)`
*:NvimTreeCollapseKeepBuffers*
Collapses the nvim-tree recursively, but keep the directories open, which are
used in an open buffer.
See |nvim-tree-api.tree.collapse_all()|
Calls: `api.tree.collapse_all(true)`
*:NvimTreeGenerateOnAttach*
Creates and opens a new file `nvim-tree-on-attach.lua` in |stdpath| `"cache"`,
usually `$XDG_CACHE_HOME/nvim`. Contains |nvim-tree.on_attach| function based
on your |nvim-tree.view.mappings|, |nvim-tree.remove_keymaps| as well as the
defaults.
See https://github.com/nvim-tree/nvim-tree.lua/wiki/Migrating-To-on_attach
==============================================================================
4. 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.
setup() function takes one optional argument: configuration table. If omitted
nvim-tree will be initialised with default configuration.
>
The first setup() call is cheap: it does nothing more than validate / apply
the configuration. Nothing happens until the tree is first opened.
Subsequent setup() calls are expensive as they tear down the world before
applying configuration.
>
require("nvim-tree").setup { -- BEGIN_DEFAULT_OPTS
auto_reload_on_write = true,
disable_netrw = false,
hijack_cursor = false,
hijack_netrw = true,
hijack_unnamed_buffer_when_opening = false,
sort = {
sorter = "name",
folders_first = true,
},
root_dirs = {},
prefer_startup_root = false,
sync_root_with_cwd = false,
reload_on_bufenter = false,
respect_buf_cwd = false,
on_attach = "default",
remove_keymaps = false,
select_prompts = false,
view = {
centralize_selection = false,
cursorline = true,
debounce_delay = 15,
width = 30,
hide_root_folder = false,
side = "left",
preserve_window_proportions = false,
number = false,
relativenumber = false,
signcolumn = "yes",
mappings = {
custom_only = false,
list = {
-- user mappings go here
},
},
float = {
enable = false,
quit_on_focus_loss = true,
open_win_config = {
relative = "editor",
border = "rounded",
width = 30,
height = 30,
row = 1,
col = 1,
},
},
},
renderer = {
add_trailing = false,
group_empty = false,
highlight_git = false,
full_name = false,
highlight_opened_files = "none",
highlight_modified = "none",
root_folder_label = ":~:s?$?/..?",
indent_width = 2,
indent_markers = {
enable = false,
inline_arrows = true,
icons = {
corner = "└",
edge = "│",
item = "│",
bottom = "─",
none = " ",
},
},
icons = {
webdev_colors = true,
git_placement = "before",
modified_placement = "after",
padding = " ",
symlink_arrow = " ➛ ",
show = {
file = true,
folder = true,
folder_arrow = true,
git = true,
modified = true,
},
glyphs = {
default = "",
symlink = "",
bookmark = "󰆤",
modified = "●",
folder = {
arrow_closed = "",
arrow_open = "",
default = "",
open = "",
empty = "",
empty_open = "",
symlink = "",
symlink_open = "",
},
git = {
unstaged = "✗",
staged = "✓",
unmerged = "",
renamed = "➜",
untracked = "★",
deleted = "",
ignored = "◌",
},
},
},
special_files = { "Cargo.toml", "Makefile", "README.md", "readme.md" },
symlink_destination = true,
},
hijack_directories = {
enable = true,
auto_open = true,
},
update_focused_file = {
enable = false,
update_root = false,
ignore_list = {},
},
system_open = {
cmd = "",
args = {},
},
diagnostics = {
enable = false,
show_on_dirs = false,
show_on_open_dirs = true,
debounce_delay = 50,
severity = {
min = vim.diagnostic.severity.HINT,
max = vim.diagnostic.severity.ERROR,
},
icons = {
hint = "",
info = "",
warning = "",
error = "",
},
},
filters = {
git_ignored = true,
dotfiles = false,
git_clean = false,
no_buffer = false,
custom = {},
exclude = {},
},
filesystem_watchers = {
enable = true,
debounce_delay = 50,
ignore_dirs = {},
},
git = {
enable = true,
show_on_dirs = true,
show_on_open_dirs = true,
disable_for_dirs = {},
timeout = 400,
},
modified = {
enable = false,
show_on_dirs = true,
show_on_open_dirs = true,
},
actions = {
use_system_clipboard = true,
change_dir = {
enable = true,
global = false,
restrict_above_cwd = false,
},
expand_all = {
max_folder_discovery = 300,
exclude = {},
},
file_popup = {
open_win_config = {
col = 1,
row = 1,
relative = "cursor",
border = "shadow",
style = "minimal",
},
},
open_file = {
quit_on_open = false,
eject = true,
resize_window = true,
window_picker = {
enable = true,
picker = "default",
chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
exclude = {
filetype = { "notify", "packer", "qf", "diff", "fugitive", "fugitiveblame" },
buftype = { "nofile", "terminal", "help" },
},
},
},
remove_file = {
close_window = true,
},
},
trash = {
cmd = "gio trash",
},
live_filter = {
prefix = "[FILTER]: ",
always_show_folders = true,
},
tab = {
sync = {
open = false,
close = false,
ignore = {},
},
},
notify = {
threshold = vim.log.levels.INFO,
absolute_path = true,
},
ui = {
confirm = {
remove = true,
trash = true,
},
},
experimental = {},
log = {
enable = false,
truncate = false,
types = {
all = false,
config = false,
copy_paste = false,
dev = false,
diagnostics = false,
git = false,
profile = false,
watcher = false,
},
},
} -- END_DEFAULT_OPTS
<
Here is a list of the options available in the setup call:
*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`: >
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.auto_reload_on_write*
Reloads the explorer every time a buffer is written to.
Type: `boolean`, Default: `true`
*nvim-tree.sort*
File and folder sorting options.
*nvim-tree.sort.sorter* (previously `sort_by`)
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: >
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.hijack_unnamed_buffer_when_opening*
Opens in place of the unnamed buffer if it's empty.
Type: `boolean`, Default: `false`
*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.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* (previously `update_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.hijack_directories* (previously `update_to_buf_dir`)
hijacks new directory buffers when they are opened (`:e dir`).
*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`
*nvim-tree.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* (previously `update_focused_file.update_cwd`)
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`
Type: `boolean`, Default: `false`
*nvim-tree.update_focused_file.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` and
`update_focused_file.enable` are `true`.
Type: {string}, Default: `{}`
*nvim-tree.system_open*
Open a file or directory in your preferred application.
*nvim-tree.system_open.cmd*
The open command itself.
Type: `string`, Default: `""`
Leave empty for OS specific default:
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", '""' }`
*nvim-tree.diagnostics*
Show LSP and COC diagnostics in the signcolumn
Note that the modified sign will take precedence over the diagnostics signs.
`NOTE`: it will use the default diagnostic color groups to highlight the signs.
If you wish to customize, you can override these groups:
- `NvimTreeLspDiagnosticsError`
- `NvimTreeLspDiagnosticsWarning`
- `NvimTreeLspDiagnosticsInformation`
- `NvimTreeLspDiagnosticsHint`
*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: `50` (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.icons*
Icons for diagnostic severity.
Type: `table`, Default: `{ hint = "", info = "", warning = "", error = "" }`
*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.git*
Git integration with icons and colors.
*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.
May be relative, evaluated via |fnamemodify| `":p"`
Type: `table`, 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)
You will still need to set |renderer.icons.show.git| `= true` or
|renderer.highlight_git| `= true` to be able to see things in the
tree. This will be changed in the future versions.
The configurable timeout will kill the current process and so disable the
git integration for the project that takes too long.
The git integration is blocking, so if your timeout is too long (like not in
milliseconds but a few seconds), it will not render anything until the git
process returned the data.
*nvim-tree.modified*
Indicate which file have unsaved modification.
*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`
You will still need to set |renderer.icons.show.modified| `= true` or
|renderer.highlight_modified| `= true` to be able to see things in the
tree.
*nvim-tree.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.
Backslashes must be escaped e.g. `"my-project/\\.build$"`. See |string-match|.
Useful when path is not in `.gitignore` or git integration is disabled.
Type: {string}, Default: `{}`
*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.remove_keymaps*
Deprecated: please see |nvim-tree-mappings-legacy|
This can be used to remove the default mappings in the tree.
- Remove specific keys by passing a `string` table of keys
eg. {"<C-o>", "<CR>", "o", "<Tab>"}
- Remove all default mappings by passing `true`
- Ignore by passing `false`
Type: `bool` or `{string}`, 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`
*nvim-tree.view*
Window / buffer setup.
*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.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.hide_root_folder*
Deprecated: please set |nvim-tree.renderer.root_folder_label| to `false`.
Hide the path of the current working directory on top of the tree.
Type: `boolean`, Default: `false`
*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 (previously `view.adaptive_size`).
Type: `string | number | function | table`, Default: `30`
*nvim-tree.view.width.min*
Minimum dynamic width.
Type: `string | number | function`, Default: `30`
*nvim-tree.view.width.max*
Maximum dynamic width, -1 for unbounded.
Type: `string | number | function`, Default: `-1`
*nvim-tree.view.width.padding*
Extra padding to the right.
Type: `string | number | function`, Default: `1`
*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 diagnostic sign column. Value can be `"yes"`, `"auto"`, `"no"`.
Type: `string`, Default: `"yes"`
*nvim-tree.view.mappings*
Deprecated: please see |nvim-tree-mappings-legacy|
*nvim-tree.view.mappings.custom_only*
Will use only the provided user mappings and not the default otherwise,
extends the default mappings with the provided user mappings.
Overrides |nvim-tree.remove_keymaps|
Type: `boolean`, Default: `false`
*nvim-tree.view.mappings.list*
A list of keymaps that will extend or override the default keymaps.
Type: `table`
Default: see |nvim-tree-mappings-legacy|
*nvim-tree.view.float*
Configuration options for 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` or `function` that returns a table, Default:
`{`
`relative = "editor",`
`border = "rounded",`
`width = 30,`
`height = 30,`
`row = 1,`
`col = 1,`
`}`
*nvim-tree.renderer*
UI rendering setup
*nvim-tree.renderer.add_trailing*
Appends a trailing slash to folder names.
Type: `boolean`, Default: `false`
*nvim-tree.renderer.group_empty*
Compact folders that only contain a single folder into one node in the file tree.
Type: `boolean`, 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.highlight_git*
Enable file highlight for git attributes using `NvimTreeGit*` highlight groups.
Requires |nvim-tree.git.enable|
This can be used with or without the icons.
Type: `boolean`, Default: `false`
*nvim-tree.renderer.highlight_opened_files*
Highlight icons and/or names for |bufloaded()| files using the
`NvimTreeOpenedFile` 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"`
This can be used with or without the icons.
Type: `string`, Default `"none"`
*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. >
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.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: `{ corner = "└", edge = "│", item = "│", bottom = "─", none = " ", }`
*nvim-tree.renderer.icons*
Configuration options for icons.
*nvim-tree.renderer.icons.webdev_colors*
Use the webdev icon colors, otherwise `NvimTreeFileIcon`.
Type: `boolean`, Default: `true`
*nvim-tree.renderer.icons.git_placement*
Place where the git icons will be rendered.
Can be `"after"` or `"before"` filename (after the file/folders icons)
or `"signcolumn"` (requires |nvim-tree.view.signcolumn| enabled).
Note that the diagnostic signs and the modified sign will take precedence over the git signs.
Type: `string`, Default: `before`
*nvim-tree.renderer.icons.modified_placement*
Place where the modified icon will be rendered.
Can be `"after"` or `"before"` filename (after the file/folders icons)
or `"signcolumn"` (requires |nvim-tree.view.signcolumn| enabled).
Type: `string`, Default: `after`
*nvim-tree.renderer.icons.padding*
Inserted between icon and filename.
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.
*nvim-tree.renderer.icons.show.file*
Show an icon before the file name. `nvim-web-devicons` will be used if available.
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.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. Will be overridden by `nvim-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.folder*
Glyphs for directories.
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 = "◌",`
`}`
*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.symlink_destination*
Whether to show the destination of the symlink.
Type: `boolean`, Default: `true`
*nvim-tree.filters*
Filtering options.
*nvim-tree.filters.git_ignored* (previously `git.ignore`)
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.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}, 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: `{}`
*nvim-tree.trash*
Configuration options for trashing.
*nvim-tree.trash.cmd*
The command used to trash items (must be installed on your system).
The default `"gio trash"` is shipped with glib2 which is a common 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"`
*nvim-tree.actions*
Configuration for various actions.
*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.
Consider that this might cause issues with the |nvim-tree.sync_root_with_cwd| option.
Type: `boolean`, Default: `false`
*nvim-tree.actions.change_dir.restrict_above_cwd*
Restrict changing to a directory above the global current working directory.
Type: `boolean`, Default: `false`
*nvim-tree.actions.expand_all*
Configuration for expand_all behaviour.
*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* (previously `view.auto_resize`)
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.
Type: `boolean`, Default: `true`
*nvim-tree.actions.open_file.window_picker.picker*
Change the default window picker, can be 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: >
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 that indicates
to the picker that the buffer's window should not be selectable.
Type: `table`
Default:
`{`
`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`
*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.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`
*nvim-tree.tab*
Configuration for tab behaviour.
*nvim-tree.tab.sync*
Configuration for syncing nvim-tree across tabs.
*nvim-tree.tab.sync.open* (previously `nvim-tree.open_on_tab`)
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* (previously `nvim-tree.ignore_buf_on_tab_change`)
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: `{}`
*nvim-tree.notify*
Configuration for notification.
*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:` not used.
*nvim-tree.notify.absolute_path*
Whether to use absolute paths or item names in fs action notifications.
Type: `boolean`, Default: `true`
*nvim-tree.ui*
General UI configuration.
*nvim-tree.ui.confirm*
Confirmation prompts.
*nvim-tree.ui.confirm.remove*
Prompt before removing.
Type: `boolean`, Default: `true`
*nvim-tree.ui.confirm.trash* (previously `trash.require_confirm`)
Prompt before trashing.
Type: `boolean`, Default: `true`
*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.
*nvim-tree.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`
==============================================================================
5. API *nvim-tree-api*
Nvim-tree's public API can be used to access features.
>
e.g. >
local api = require("nvim-tree.api")
api.tree.toggle()
<
This module exposes stable functionalities, it is advised to use this in order
to avoid breaking configurations due to internal breaking changes.
The api is separated in multiple modules, which can be accessed with
`api.<module>.<function>`
Functions that needs a tree node parameter are exposed with an abstraction
that injects the node from the cursor position in the tree when calling
the function. It will use the node you pass as an argument in priority if it
exists.
==============================================================================
5.1 API TREE *nvim-tree-api.tree*
tree.open({opts}) *nvim-tree-api.tree.open()*
Open the tree, focusing it if already open.
Parameters: ~
• {opts} (table) optional parameters
Options: ~
• {path} (string) root directory for the tree
• {current_window} (boolean) open the tree in the current window
• {winid} (number) open the tree in the specified |winid|,
overrides {current_window}
• {find_file} (boolean) find the current buffer
• {update_root} (boolean) requires {find_file}, see
|nvim-tree.update_focused_file.update_root|
tree.toggle({opts}) *nvim-tree-api.tree.toggle()*
Open or close the tree.
Parameters: ~
• {opts} (table) optional parameters
Options: ~
• {path} (string) root directory for the tree
• {current_window} (boolean) open the tree in the current window
• {winid} (number) open the tree in the specified |winid|,
overrides {current_window}
• {find_file} (boolean) find the current buffer
• {update_root} (boolean) requires {find_file}, see
|nvim-tree.update_focused_file.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|
tree.close_in_this_tab() *nvim-tree-api.tree.close_in_this_tab()*
Close the tree in this tab only.
tree.close_in_all_tabs() *nvim-tree-api.tree.close_in_all_tabs()*
Close the tree in all tabs.
tree.focus() *nvim-tree-api.tree.focus()*
Focus the tree, opening it if necessary.
tree.reload() *nvim-tree-api.tree.reload()*
Refresh the tree. Does nothing if closed.
tree.change_root({path}) *nvim-tree-api.tree.change_root()*
Change the tree's root to a path.
Parameters: ~
• {path} (string) absolute or relative path
*nvim-tree-api.tree.change_root_to_node()*
tree.change_root_to_node({node})
Change the tree's root to a folder node or the parent of a file node.
Parameters: ~
• {node} (Node) folder or file
*nvim-tree-api.tree.change_root_to_parent()*
tree.change_root_to_parent({node})
Change the tree's root to the parent of a node.
Parameters: ~
• {node} (Node) folder or file
tree.get_node_under_cursor() *nvim-tree-api.tree.get_node_under_cursor()*
Retrieve the currently focused node.
Return: ~
node or nil if tree is not visible
tree.get_nodes() *nvim-tree-api.tree.get_nodes()*
Retrieve a hierarchical list of all the nodes. This is a cloned list for
reference purposes only and should not be passed into other API functions.
Return: ~
table of nodes
tree.find_file({opts}) *nvim-tree-api.tree.find_file()*
Find and focus a file or folder in the tree. Finds current buffer unless
otherwise specified.
Parameters: ~
• {opts} (table) optional parameters
Options: ~
• {buf} (string|number) absolute/relative path OR bufnr to find
• {open} (boolean) open the tree if necessary
• {current_window} (boolean) requires {open}, open in the current window
• {winid} (number) open the tree in the specified |winid|,
overrides {current_window}
• {update_root} (boolean) see |nvim-tree.update_focused_file.update_root|
• {focus} (boolean) focus the tree
tree.search_node() *nvim-tree-api.tree.search_node()*
Open the search dialogue as per the search_node action.
tree.collapse_all({keep_buffers}) *nvim-tree-api.tree.collapse_all()*
Collapse the tree.
Parameters: ~
• {keep_buffers} (boolean) do not collapse nodes with open buffers.
tree.expand_all() *nvim-tree-api.tree.expand_all()*
Recursively expand all nodes in the tree.
Folder: only the nodes underneath that folder.
*nvim-tree-api.tree.toggle_gitignore_filter()*
tree.toggle_gitignore_filter()
Toggle |nvim-tree.filters.git_ignored| filter.
*nvim-tree-api.tree.toggle_git_clean_filter()*
tree.toggle_git_clean_filter()
Toggle |nvim-tree.filters.git_clean| filter.
*nvim-tree-api.tree.toggle_no_buffer_filter()*
tree.toggle_no_buffer_filter()
Toggle |nvim-tree.filters.no_buffer| filter.
*nvim-tree-api.tree.toggle_custom_filter()*
tree.toggle_custom_filter()
Toggle |nvim-tree.filters.custom| filter.
*nvim-tree-api.tree.toggle_hidden_filter()*
tree.toggle_hidden_filter()
Toggle |nvim-tree.filters.dotfiles| filter.
tree.toggle_help() *nvim-tree-api.tree.toggle_help()*
Toggle help view.
tree.is_tree_buf({bufnr}) *nvim-tree-api.tree.is_tree_buf()*
Checks if a buffer is an nvim-tree.
Parameters: ~
• {bufnr} (number|nil) buffer handle, 0 or nil for current buffer
Return: ~
(boolean) buffer is an nvim-tree buffer
tree.is_visible({opts}) *nvim-tree-api.tree.is_visible()*
Checks if nvim-tree is visible on the current, specified or any tab.
Parameters: ~
• {opts} (table) optional parameters
Options: ~
• {tabpage} (number) as per |nvim_get_current_tabpage()|
• {any_tabpage} (boolean) visible on any tab, default false
Return: ~
(boolean) nvim-tree is visible
==============================================================================
5.2 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.
Parameters: ~
• {node} (Node) parent, uses the parent of a file.
fs.remove({node}) *nvim-tree-api.fs.remove()*
Delete a file or folder from the file system.
Parameters: ~
• {node} (Node) file or folder
fs.trash({node}) *nvim-tree-api.fs.trash()*
Trash a file or folder as per |nvim-tree.trash|
Parameters: ~
• {node} (Node) file or folder
fs.rename_node({node}) *nvim-tree-api.fs.rename_node()*
Prompt to rename a file or folder.
Parameters: ~
• {node} (Node) file or folder
fs.rename({node}) *nvim-tree-api.fs.rename()*
Prompt to rename a file or folder by name.
Parameters: ~
• {node} (Node) file or folder
fs.rename_basename({node}) *nvim-tree-api.fs.rename_basename()*
Prompt to rename a file or folder by name with extension omitted.
Parameters: ~
• {node} (Node) file or folder
fs.rename_sub({node}) *nvim-tree-api.fs.rename_sub()*
Prompt to rename a file or folder by absolute path with name omitted.
Parameters: ~
• {node} (Node) file or folder
fs.cut({node}) *nvim-tree-api.fs.cut()*
Cut a file or folder to the nvim-tree clipboard.
Parameters: ~
• {node} (Node) file or folder
fs.paste({node}) *nvim-tree-api.fs.paste()*
Paste a file or folder from the nvim-tree clipboard.
Parameters: ~
• {node} (Node) destination folder, uses the parent of a file.
fs.copy.node({node}) *nvim-tree-api.fs.copy.node()*
Copy a file or folder from the nvim-tree clipboard.
Parameters: ~
• {node} (Node) file or folder
fs.copy.absolute_path({node}) *nvim-tree-api.fs.copy.absolute_path()*
Copy the absolute path of a file or folder to the system clipboard.
Parameters: ~
• {node} (Node) file or folder
fs.copy.filename({node}) *nvim-tree-api.fs.copy.filename()*
Copy the name of a file or folder to the system clipboard.
Parameters: ~
• {node} (Node) file or folder
fs.copy.relative_path({node}) *nvim-tree-api.fs.copy.relative_path()*
Copy the path of a file or folder relative to the tree root to the system
clipboard.
Parameters: ~
• {node} (Node) file or folder
fs.clear_clipboard() *nvim-tree-api.fs.clear_clipboard()*
Clear the nvim-tree clipboard.
fs.print_clipboard() *nvim-tree-api.fs.print_clipboard()*
Print the contents of the nvim-tree clipboard.
==============================================================================
5.3 API NODE *nvim-tree-api.node*
node.open.edit() *nvim-tree-api.node.open.edit()*
File: open as per |nvim-tree.actions.open_file|
Folder: expand or collapse
Root: change directory up
*nvim-tree-api.node.open.replace_tree_buffer()*
node.open.replace_tree_buffer()
|nvim-tree-api.node.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()
|nvim-tree-api.node.edit()|, window picker will never be used as per
|nvim-tree.actions.open_file.window_picker.enable| `false`
node.open.vertical() *nvim-tree-api.node.open.vertical()*
|nvim-tree-api.node.edit()|, file will be opened in a new vertical split.
node.open.horizontal() *nvim-tree-api.node.open.horizontal()*
|nvim-tree-api.node.edit()|, file will be opened in a new horizontal split.
node.open.drop() *nvim-tree-api.node.open.drop()*
Switch to window with selected file if it exists.
Open file otherwise.
See: `:h :drop`.
File: open file using `:drop`
Folder: expand or collapse
Root: change directory up
node.open.tab() *nvim-tree-api.node.open.tab()*
|nvim-tree-api.node.edit()|, file will be opened in a new tab.
*nvim-tree-api.node.open.tab_drop()*
node.open.tab_drop()
Switch to tab containing window with selected file if it exists.
Open file in new tab otherwise.
File: open file using `tab :drop`
Folder: expand or collapse
Root: change directory up
node.open.preview() *nvim-tree-api.node.open.preview()*
|nvim-tree-api.node.edit()|, file buffer will have |bufhidden| set to `delete`.
node.node.navigate.git.next() *nvim-tree-api.node.navigate.git.next()*
Navigate to the next item showing git status.
node.navigate.git.prev() *nvim-tree-api.node.navigate.git.prev()*
Navigate to the previous item showing git status.
*nvim-tree-api.node.navigate.diagnostics.next()*
node.navigate.diagnostics.next()
Navigate to the next item showing diagnostic status.
*nvim-tree-api.node.navigate.diagnostics.prev()*
node.navigate.diagnostics.prev()
Navigate to the next item showing diagnostic status.
*nvim-tree-api.node.navigate.opened.next()*
node.navigate.opened.next()
Navigate to the next |bufloaded()| item.
See |nvim-tree.renderer.highlight_opened_files|
*nvim-tree-api.node.navigate.opened.prev()*
node.navigate.opened.prev()
Navigate to the previous |bufloaded()| item.
See |nvim-tree.renderer.highlight_opened_files|
*nvim-tree-api.node.navigate.sibling.next()*
node.navigate.sibling.next()
Navigate to the next node in the current node's folder, wraps.
*nvim-tree-api.node.navigate.sibling.prev()*
node.navigate.sibling.prev()
Navigate to the previous node in the current node's folder, wraps.
*nvim-tree-api.node.navigate.sibling.first()*
node.navigate.sibling.first()
Navigate to the first node in the current node's folder.
*nvim-tree-api.node.navigate.sibling.last()*
node.navigate.sibling.last()
Navigate to the last node in the current node's folder.
*nvim-tree-api.node.navigate.parent()*
node.navigate.parent()
Navigate to the parent folder of the current node.
*nvim-tree-api.node.navigate.parent_close()*
node.navigate.parent_close()
|api.node.navigate.parent()|, closing that folder.
node.show_info_popup() *nvim-tree-api.node.show_info_popup()*
Open a popup window showing: fullpath, size, accessed, modified, created.
node.run.cmd() *nvim-tree-api.node.run.cmd()*
Enter |cmdline| with the full path of the node and the cursor at the start
of the line.
node.run.system() *nvim-tree-api.node.run.system()*
Execute |nvim-tree.system_open|
==============================================================================
5.4 API GIT *nvim-tree-api.git*
git.reload() *nvim-tree-api.git.reload()*
Update the git status of the entire tree.
==============================================================================
5.5 API EVENTS *nvim-tree-api.events*
*nvim-tree-api.events.subscribe()*
events.subscribe({event_type}, {callback})
Register a handler for an event, see |nvim-tree-events|
Parameters: ~
• {event_type} (string) |nvim-tree-api.events.Event|
• {callback} (function) see |nvim_tree_events_kind| for parameters
events.Event *nvim-tree-api.events.Event*
String enum: |nvim_tree_events_kind|
==============================================================================
5.6 API LIVE FILTER *nvim-tree-api.live_filter*
live_filter.start() *nvim-tree-api.live_filter.start()*
Enter |nvim-tree.live_filter| mode.
live_filter.clear() *nvim-tree-api.live_filter.clear()*
Exit |nvim-tree.live_filter| mode.
==============================================================================
5.7 API MARKS *nvim-tree-api.marks*
marks.get({node}) *nvim-tree-api.marks.get()*
Return the node if it is marked.
Parameters: ~
• {node} (Node) folder or file
marks.list() *nvim-tree-api.marks.list()*
Retrieve all marked nodes.
Return: ~
(table) marked nodes
marks.toggle({node}) *nvim-tree-api.marks.toggle()*
Toggle node mark.
Parameters: ~
• {node} (Node) folder or file
marks.clear() *nvim-tree-api.marks.clear()*
Clear all marks.
marks.bulk.delete() *nvim-tree-api.marks.bulk.delete()*
Delete all marked. Optionally prompts.
marks.bulk.move() *nvim-tree-api.marks.bulk.move()*
Prompts for a directory to move all marked nodes into.
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.
marks.navigate.prev() *nvim-tree-api.marks.navigate.prev()*
As per |nvim-tree-api.marks.navigate.next()|
marks.navigate.select() *nvim-tree-api.marks.navigate.select()*
Prompts for selection of a marked node as per
|nvim-tree-api.marks.navigate.next()|
==============================================================================
5.8 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|
Parameters: ~
• {bufnr} (number) nvim-tree buffer number passed to |nvim-tree.on_attach|
config.mappings.active() *nvim-tree-api.config.mappings.active()*
Deprecated: only functions when using legacy |nvim-tree.view.mappings|
Retrieve a clone of the currently active mappings: defaults + user.
Changing the active mappings will require a call to |nvim-tree-setup|
Return: ~
(table) as per |nvim-tree.view.mappings.list|
config.mappings.default() *nvim-tree-api.config.mappings.default()*
Deprecated: only functions when using legacy |nvim-tree.view.mappings|
Retrieve a clone of the default mappings.
Return: ~
(table) as per |nvim-tree.view.mappings.list|
*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
may include default mappings.
Return: ~
(table) as per |nvim_buf_get_keymap()|
*nvim-tree-api.config.mappings.get_keymap_default()*
config.mappings.get_keymap_default()
Retrieves the buffer local mappings for nvim-tree that are applied by
|nvim-tree-api.config.mappings.default_on_attach()|
Return: ~
(table) as per |nvim_buf_get_keymap()|
==============================================================================
5.8 API COMMANDS *nvim-tree-api.commands*
commands.get() *nvim-tree-api.commands.get()*
Retrieve all commands, see |nvim-tree-commands|
Return: ~
(table) array containing |nvim_create_user_command()| parameters:
• {name} (string)
• {command} (function)
• {opts} (table)
==============================================================================
6. MAPPINGS *nvim-tree-mappings*
Mappings are set via the |nvim-tree.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.
Active mappings may be viewed via HELP, default `g?`. The mapping's description
is used when displaying HELP.
The `on_attach` function is passed the `bufnr` of nvim-tree. Use
|vim.keymap.set()| or |nvim_set_keymap()| to define mappings as usual. e.g. >
local function my_on_attach(bufnr)
local api = require('nvim-tree.api')
local function opts(desc)
return { desc = 'nvim-tree: ' .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true }
end
-- copy default mappings here from defaults in next section
vim.keymap.set('n', '<C-]>', api.tree.change_root_to_node, opts('CD'))
vim.keymap.set('n', '<C-e>', api.node.open.replace_tree_buffer, opts('Open: In Place'))
---
-- OR use all default mappings
api.config.mappings.default_on_attach(bufnr)
-- remove a default
vim.keymap.del('n', '<C-]>', { buffer = bufnr })
-- override a default
vim.keymap.set('n', '<C-e>', api.tree.reload, opts('Refresh'))
-- add your mappings
vim.keymap.set('n', '?', api.tree.toggle_help, opts('Help'))
---
end
require("nvim-tree").setup({
---
on_attach = my_on_attach,
---
})
<
Mouse support is defined in |KeyBindings|
Single left mouse mappings can be achieved via `<LeftRelease>`.
Single right / middle mouse mappings will require changes to |mousemodel| or |mouse|.
You may execute your own functions as well as |nvim-tree-api| functions e.g. >
local function print_node_path()
local api = require('nvim-tree.api')
local node = api.tree.get_node_under_cursor()
print(node.absolute_path)
end
-- on_attach
vim.keymap.set('n', '<C-P>', print_node_path, opts('Print Path'))
<
==============================================================================
6.1 DEFAULT MAPPINGS *nvim-tree-mappings-default*
In the absence of an |nvim-tree.on_attach| function, the following defaults
will be applied.
You are encouraged to copy these to your own |nvim-tree.on_attach| function.
>
local api = require('nvim-tree.api')
local function opts(desc)
return { desc = 'nvim-tree: ' .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true }
end
-- BEGIN_DEFAULT_ON_ATTACH
vim.keymap.set('n', '<C-]>', api.tree.change_root_to_node, opts('CD'))
vim.keymap.set('n', '<C-e>', api.node.open.replace_tree_buffer, opts('Open: In Place'))
vim.keymap.set('n', '<C-k>', api.node.show_info_popup, opts('Info'))
vim.keymap.set('n', '<C-r>', api.fs.rename_sub, opts('Rename: Omit Filename'))
vim.keymap.set('n', '<C-t>', api.node.open.tab, opts('Open: New Tab'))
vim.keymap.set('n', '<C-v>', api.node.open.vertical, opts('Open: Vertical Split'))
vim.keymap.set('n', '<C-x>', api.node.open.horizontal, opts('Open: Horizontal Split'))
vim.keymap.set('n', '<BS>', api.node.navigate.parent_close, opts('Close Directory'))
vim.keymap.set('n', '<CR>', api.node.open.edit, opts('Open'))
vim.keymap.set('n', '<Tab>', api.node.open.preview, opts('Open Preview'))
vim.keymap.set('n', '>', api.node.navigate.sibling.next, opts('Next Sibling'))
vim.keymap.set('n', '<', api.node.navigate.sibling.prev, opts('Previous Sibling'))
vim.keymap.set('n', '.', api.node.run.cmd, opts('Run Command'))
vim.keymap.set('n', '-', api.tree.change_root_to_parent, opts('Up'))
vim.keymap.set('n', 'a', api.fs.create, opts('Create'))
vim.keymap.set('n', 'bd', api.marks.bulk.delete, opts('Delete Bookmarked'))
vim.keymap.set('n', 'bmv', api.marks.bulk.move, opts('Move Bookmarked'))
vim.keymap.set('n', 'B', api.tree.toggle_no_buffer_filter, opts('Toggle Filter: No Buffer'))
vim.keymap.set('n', 'c', api.fs.copy.node, opts('Copy'))
vim.keymap.set('n', 'C', api.tree.toggle_git_clean_filter, opts('Toggle Filter: Git Clean'))
vim.keymap.set('n', '[c', api.node.navigate.git.prev, opts('Prev Git'))
vim.keymap.set('n', ']c', api.node.navigate.git.next, opts('Next Git'))
vim.keymap.set('n', 'd', api.fs.remove, opts('Delete'))
vim.keymap.set('n', 'D', api.fs.trash, opts('Trash'))
vim.keymap.set('n', 'E', api.tree.expand_all, opts('Expand All'))
vim.keymap.set('n', 'e', api.fs.rename_basename, opts('Rename: Basename'))
vim.keymap.set('n', ']e', api.node.navigate.diagnostics.next, opts('Next Diagnostic'))
vim.keymap.set('n', '[e', api.node.navigate.diagnostics.prev, opts('Prev Diagnostic'))
vim.keymap.set('n', 'F', api.live_filter.clear, opts('Clean Filter'))
vim.keymap.set('n', 'f', api.live_filter.start, opts('Filter'))
vim.keymap.set('n', 'g?', api.tree.toggle_help, opts('Help'))
vim.keymap.set('n', 'gy', api.fs.copy.absolute_path, opts('Copy Absolute Path'))
vim.keymap.set('n', 'H', api.tree.toggle_hidden_filter, opts('Toggle Filter: Dotfiles'))
vim.keymap.set('n', 'I', api.tree.toggle_gitignore_filter, opts('Toggle Filter: Git Ignore'))
vim.keymap.set('n', 'J', api.node.navigate.sibling.last, opts('Last Sibling'))
vim.keymap.set('n', 'K', api.node.navigate.sibling.first, opts('First Sibling'))
vim.keymap.set('n', 'm', api.marks.toggle, opts('Toggle Bookmark'))
vim.keymap.set('n', 'o', api.node.open.edit, opts('Open'))
vim.keymap.set('n', 'O', api.node.open.no_window_picker, opts('Open: No Window Picker'))
vim.keymap.set('n', 'p', api.fs.paste, opts('Paste'))
vim.keymap.set('n', 'P', api.node.navigate.parent, opts('Parent Directory'))
vim.keymap.set('n', 'q', api.tree.close, opts('Close'))
vim.keymap.set('n', 'r', api.fs.rename, opts('Rename'))
vim.keymap.set('n', 'R', api.tree.reload, opts('Refresh'))
vim.keymap.set('n', 's', api.node.run.system, opts('Run System'))
vim.keymap.set('n', 'S', api.tree.search_node, opts('Search'))
vim.keymap.set('n', 'U', api.tree.toggle_custom_filter, opts('Toggle Filter: Hidden'))
vim.keymap.set('n', 'W', api.tree.collapse_all, opts('Collapse'))
vim.keymap.set('n', 'x', api.fs.cut, opts('Cut'))
vim.keymap.set('n', 'y', api.fs.copy.filename, opts('Copy Name'))
vim.keymap.set('n', 'Y', api.fs.copy.relative_path, opts('Copy Relative Path'))
vim.keymap.set('n', '<2-LeftMouse>', api.node.open.edit, opts('Open'))
vim.keymap.set('n', '<2-RightMouse>', api.tree.change_root_to_node, opts('CD'))
-- END_DEFAULT_ON_ATTACH
<
Alternatively, you may apply these default mappings from your |nvim-tree.on_attach| via
|nvim-tree-api.config.mappings.default_on_attach()| e.g.
>
local function my_on_attach(bufnr)
local api = require('nvim-tree.api')
local function opts(desc)
return { desc = 'nvim-tree: ' .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true }
end
api.config.mappings.default_on_attach(bufnr)
-- your removals and mappings go here
end
<
==============================================================================
6.2 LEGACY MAPPINGS *nvim-tree-mappings-legacy*
nvim-tree mappings were provided via the deprecated |nvim-tree.view.mappings|
and |nvim-tree.remove_keymaps|
These are ignored when |nvim-tree.on_attach| is present.
You are encouraged to migrate you existing legacy mappings to
|nvim-tree.on_attach| using |:NvimTreeGenerateOnAttach|
Please visit https://github.com/nvim-tree/nvim-tree.lua/wiki/Migrating-To-on_attach
`view.mappings.list` is a table of:
{key} (string|table of string) mandatory |{lhs}|.
{action} (string) mandatory name of the action.
`""` to remove an action with {key}. The case of {key} must
exactly match the action you are removing e.g. `'<Tab>'` to
remove the default preview action.
An arbitrary description when using `action_cb`.
{action_cb} (function) optional custom function that will be called.
Receives the node as a parameter.
Non-empty description for `action` is required.
{mode} (string) optional mode as per |nvim_set_keymap|.
Default `'n'`.
Examples:
>
local function print_node_path(node)
print(node.absolute_path)
end
----
view = {
mappings = {
list = {
-- remove a default mapping for cd
{ key = "<2-RightMouse>", action = "" },
-- add multiple normal mode mappings for edit
{ key = { "<CR>", "o" }, action = "edit", mode = "n" },
-- custom action
{ key = "p", action = "print_the_node_path", action_cb = print_node_path },
----
<
==============================================================================
7. HIGHLIGHT GROUPS *nvim-tree-highlight*
All the following highlight groups can be configured by hand. Aside from
`NvimTreeWindowPicker`, it is not advised to colorize the background of these
groups.
Example (in your `init.vim`):
>
highlight NvimTreeSymlink guifg=blue gui=bold,underline
<
You should have 'termguicolors' enabled, otherwise, colors will not be
applied.
To view the active highlight groups run `:so $VIMRUNTIME/syntax/hitest.vim`
as per |:highlight|
Default linked group follows name.
NvimTreeSymlink
NvimTreeSymlinkIcon
NvimTreeSymlinkFolderName (Directory)
NvimTreeFolderName (Directory)
NvimTreeRootFolder
NvimTreeFolderIcon
NvimTreeOpenedFolderIcon (NvimTreeFolderIcon)
NvimTreeClosedFolderIcon (NvimTreeFolderIcon)
NvimTreeFileIcon
NvimTreeEmptyFolderName (Directory)
NvimTreeOpenedFolderName (Directory)
NvimTreeExecFile
NvimTreeOpenedFile
NvimTreeModifiedFile
NvimTreeSpecialFile
NvimTreeImageFile
NvimTreeIndentMarker
NvimTreeLspDiagnosticsError (DiagnosticError)
NvimTreeLspDiagnosticsWarning (DiagnosticWarn)
NvimTreeLspDiagnosticsInformation (DiagnosticInfo)
NvimTreeLspDiagnosticsHint (DiagnosticHint)
NvimTreeGitDirty
NvimTreeGitStaged
NvimTreeGitMerge
NvimTreeGitRenamed
NvimTreeGitNew
NvimTreeGitDeleted
NvimTreeGitIgnored (Comment)
NvimTreeWindowPicker
There are also links to normal bindings to style the tree itself.
NvimTreeNormal
NvimTreeNormalFloat
NvimTreeEndOfBuffer (NonText)
NvimTreeCursorLine (CursorLine)
NvimTreeCursorLineNr (CursorLineNr)
NvimTreeLineNr (LineNr)
NvimTreeWinSeparator (WinSeparator)
NvimTreeCursorColumn (CursorColumn)
There are also links for file highlight with git properties, linked to their
Git equivalent:
NvimTreeFileDirty (NvimTreeGitDirty)
NvimTreeFileStaged (NvimTreeGitStaged)
NvimTreeFileMerge (NvimTreeGitMerge)
NvimTreeFileRenamed (NvimTreeGitRenamed)
NvimTreeFileNew (NvimTreeGitNew)
NvimTreeFileDeleted (NvimTreeGitDeleted)
NvimTreeFileIgnored (NvimTreeGitIgnored)
There are 2 highlight groups for the live filter feature
NvimTreeLiveFilterPrefix
NvimTreeLiveFilterValue
Color of the bookmark icon
NvimTreeBookmark
==============================================================================
8. EVENTS *nvim-tree-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
customization of nvim-tree.
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|
Handlers are registered by calling |nvim-tree-api.events.subscribe()|
function with an |nvim-tree-api.events.Event|
e.g. handler for node renamed: >
local api = require("nvim-tree.api")
local Event = api.events.Event
api.events.subscribe(Event.NodeRenamed, function(data)
print("Node renamed from " .. data.old_name .. " to " .. data.new_name)
end)
<
|nvim_tree_events_kind|
- Event.Ready
When NvimTree has been initialized
• Note: Handler takes no parameter.
- Event.TreeOpen
• Note: Handler takes no parameter.
- Event.TreeClose
• Note: Handler takes no parameter.
- Event.Resize - When NvimTree is resized.
handler parameters: ~
size: `number` size of the view in columns.
- Event.WillRenameNode
• Note: A node can either be a file or a directory.
handler parameters: ~
{old_name} `{string}` Absolute path to the old node location.
{new_name} `{string}` Absolute path to the new node location.
- Event.NodeRenamed
• Note: A node can either be a file or a directory.
handler parameters: ~
{old_name} `{string}` Absolute path to the old node location.
{new_name} `{string}` Absolute path to the new node location.
- Event.FileCreated
handler parameters: ~
{fname} `{string}` Absolute path to the created file
- Event.WillCreateFile
handler parameters: ~
{fname} `{string}` Absolute path to the file to be
created
- Event.FileRemoved
handler parameters: ~
{fname} `{string}` Absolute path to the removed file.
- Event.WillRemoveFile
handler parameters: ~
{fname} `{string}` Absolute path to the file to be
removed
- Event.FolderCreated
handler parameters: ~
{folder_name} `{string}` Absolute path to the created folder.
- Event.FolderRemoved
handler parameters: ~
{folder_name} `{string}` Absolute path to the removed folder.
- Event.TreeAttachedPost
Invoked after the tree's buffer has been created and mappings
have been applied: |nvim-tree-mappings| or |nvim-tree.on_attach|
handler parameters: ~
{buf} `{number} `API buffer handle (buffer number)
- Event.TreeRendered
Invoked every time the tree is redrawn. Normally this event
happens after |Event.TreeOpen| except that handlers of this
one will have access to the tree buffer populated with the
final content.
handler parameters: ~
{bufnr} `{number} `API buffer handle (buffer number)
{winnr} `{number} `API window handle (window number)
|nvim_tree_events_startup|
There are two special startup events in the form of User autocommands:
`NvimTreeRequired` first `require("nvim-tree")`
`NvimTreeSetup` `setup({})` completed
Immediately before firing: a global variable of the same name will be set to a
value of 1.
Example subscription: >
vim.api.nvim_create_autocmd("User", {
pattern = "NvimTreeRequired",
callback = function(data)
---
end,
})
<
==============================================================================
9. BOOKMARKS *nvim-tree-bookmarks*
You can toggle marks on files/folders with
`require("nvim-tree.api").marks.toggle(node)` which is bound to `m` by
default.
To get the list of marked paths, you can call
`require("nvim-tree.api").marks.list()`. This will return `{node}`.
*nvim-tree.bookmarks.navigation*
Navigation for marks is not bound by default in nvim-tree because we don't
want to focus the tree view each time we wish to switch to another mark.
This requires binding bookmark navigation yourself.
-- in your lua configuration
vim.keymap.set("n", "<leader>mn", require("nvim-tree.api").marks.navigate.next)
vim.keymap.set("n", "<leader>mp", require("nvim-tree.api").marks.navigate.prev)
vim.keymap.set("n", "<leader>ms", require("nvim-tree.api").marks.navigate.select)
==============================================================================
10. OS SPECIFIC RESTRICTIONS *nvim-tree-os-specific*
macOS
- Rename to different case is not possible when using a case insensitive file
system.
Windows WSL and PowerShell
- Trash is synchronized
- Executable file detection is disabled as this is non-performant and can
freeze nvim
- Some filesystem watcher error related to permissions will not be reported
==============================================================================
11. NETRW *nvim-tree-netrw*
|netrw| is a standard neovim 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
replacing the |netrw| browser.
It is strongly recommended to disable |netrw|. As it is a bundled plugin it
must be disabled manually at the start of your `init.lua` as per |netrw-noload|: >
vim.g.loaded_netrw = 1
vim.g.loaded_netrwPlugin = 1
<
There are many |netrw| features beyond the file browser. If you want to
keep using |netrw| without its browser features please ensure:
|nvim-tree.disable_netrw| `= false`
|nvim-tree.hijack_netrw| ` = true`
vim:tw=78:ts=4:sw=4:et:ft=help:norl:
Reference in New Issue View Git Blame Copy Permalink