mirror of
https://github.com/nvim-tree/nvim-tree.lua.git
synced 2026-07-28 15:59:44 +05:30
c760c92667
* feat: add copy absolute path with protocol into public api * feat: add helper get_basename into node * feat: add gby keymap, and allow visual mode for copy.basename|absolute_path * feat(clipboard): add opts for adding protocol in reg operations * feat(api): allow visual operation in absolute_path* * feat: add paste with protocol to keymap+api * feat: add paste with protocol to clipboard * feat: add configurable clipboard protocol * fix: filter descendant nodes on copy_absolute_path_with_protocol * refactor: change clip protocol keymaps to bgy and bgp * wip * fix(clipboad): correctly show the number of copied nodes on bgy * chore: remove bgy, bgp and add gp + gx * chore: update api/fs.lua and api impl.lua to match new keymaps * fix: correctly pass the function to new keymaps * chore: remove use_protocol and use use_register + cut options * chore: update docs * chore: move node:get_basename to cliboard_ * chore(clipboard): remove vim.cmd workaround in favor of vim.fn.setreg * chore: use newline as separator instead of comma * refactor(clipboard): simplify copying node attribute and allow all to work in visual mode * refactor(keymap): remove gx, use gp to move * feat(clipboard): always copy/cut to register and make `p` pick local data or register data * refactor(docs): update api docs and rename paste_while_cutting to move * fix: correctly format keymaps * chore: regenerate docs * fix: remove unused apis * chore: copy clipboard.data to register on copy/cut * chore: revert copy_node_attribute * refactor: remove visual mode from copy.basename|filename|path * chore: update docs * chore: add fs.move api and update docs * chore: destroy dummy nodes and prevent empty paths nodes parsing * fix: _meta/api/fs.lua and docs * fix(clipboard): destroy dummy nodes from register on paste * fix(clipboard): correctly check for local paste operation
3486 lines
142 KiB
Plaintext
3486 lines
142 KiB
Plaintext
*nvim-tree-lua.txt* A File Explorer For Nvim *nvim_tree* *nvim-tree*
|
|
|
|
Author: Yazdani Kiyan
|
|
Type |gO| to see the table of contents.
|
|
Help tag prefixes:
|
|
• `nvim-tree-` Help Sections e.g.
|
|
• |nvim-tree-mappings|
|
|
• |nvim-tree-config|
|
|
• `nvim_tree.` API and classes e.g.
|
|
• |nvim_tree.api.node.navigate.parent()|
|
|
• |nvim_tree.config.filesystem_watchers|
|
|
|
|
==============================================================================
|
|
Introduction *nvim-tree-introduction*
|
|
|
|
Features
|
|
|
|
- Automatic updates
|
|
- File type icons
|
|
- Git integration
|
|
- Diagnostics integration: LSP and COC
|
|
- (Live) filtering
|
|
- Rename, delete, create
|
|
- Cut, copy, paste locally and between instances
|
|
- 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.
|
|
|
|
Disable the display of icons with |nvim_tree.config.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
|
|
|
|
Nvim >= 0.10.
|
|
At least `n - 0.1` stable Nvim compatibility is guaranteed.
|
|
You may use a `compat-nvim-0.X` tag for earlier Nvim versions, however
|
|
they will receive no updates or support.
|
|
|
|
==============================================================================
|
|
Quickstart *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|
|
|
|
|
==============================================================================
|
|
Quickstart: Setup *nvim-tree-quickstart-setup*
|
|
|
|
Setup the plugin in your `init.lua`.
|
|
|
|
See |nvim-tree-setup| and |nvim-tree-config-default| >lua
|
|
|
|
-- disable netrw at the very start of your init.lua
|
|
vim.g.loaded_netrw = 1
|
|
vim.g.loaded_netrwPlugin = 1
|
|
|
|
-- optionally enable 24-bit colour
|
|
vim.opt.termguicolors = true
|
|
|
|
-- empty setup using defaults
|
|
require("nvim-tree").setup()
|
|
|
|
-- OR setup with a config
|
|
|
|
---@type nvim_tree.config
|
|
local config = {
|
|
sort = {
|
|
sorter = "case_sensitive",
|
|
},
|
|
view = {
|
|
width = 30,
|
|
},
|
|
renderer = {
|
|
group_empty = true,
|
|
},
|
|
filters = {
|
|
dotfiles = true,
|
|
},
|
|
}
|
|
require("nvim-tree").setup(config)
|
|
<
|
|
==============================================================================
|
|
Quickstart: Help *nvim-tree-quickstart-help*
|
|
|
|
Open the tree: `:NvimTreeOpen`
|
|
|
|
Show the mappings: `g?`
|
|
|
|
`<C-]>` n CD |nvim_tree.api.tree.change_root_to_node()|
|
|
`<C-e>` n Open: In Place |nvim_tree.api.node.open.replace_tree_buffer()|
|
|
`<C-k>` n Info |nvim_tree.api.node.show_info_popup()|
|
|
`<C-r>` n Rename: Omit Filename |nvim_tree.api.fs.rename_sub()|
|
|
`<C-t>` n Open: New Tab |nvim_tree.api.node.open.tab()|
|
|
`<C-v>` n Open: Vertical Split |nvim_tree.api.node.open.vertical()|
|
|
`<C-x>` n Open: Horizontal Split |nvim_tree.api.node.open.horizontal()|
|
|
`<BS>` n Close Directory |nvim_tree.api.node.navigate.parent_close()|
|
|
`<CR>` n Open |nvim_tree.api.node.open.edit()|
|
|
`<Del>` nx Delete |nvim_tree.api.fs.remove()|
|
|
`<Tab>` n Open Preview |nvim_tree.api.node.open.preview()|
|
|
`>` n Next Sibling |nvim_tree.api.node.navigate.sibling.next()|
|
|
`<` n Previous Sibling |nvim_tree.api.node.navigate.sibling.prev()|
|
|
`.` n Run Command |nvim_tree.api.node.run.cmd()|
|
|
`-` n Up |nvim_tree.api.tree.change_root_to_parent()|
|
|
`a` n Create File Or Directory |nvim_tree.api.fs.create()|
|
|
`bd` n Delete Bookmarked |nvim_tree.api.marks.bulk.delete()|
|
|
`bt` n Trash Bookmarked |nvim_tree.api.marks.bulk.trash()|
|
|
`bmv` n Move Bookmarked |nvim_tree.api.marks.bulk.move()|
|
|
`B` n Toggle Filter: No Buffer |nvim_tree.api.filter.no_buffer.toggle()|
|
|
`c` nx Copy |nvim_tree.api.fs.copy.node()|
|
|
`C` n Toggle Filter: Git Clean |nvim_tree.api.filter.git.clean.toggle()|
|
|
`[c` n Prev Git |nvim_tree.api.node.navigate.git.prev()|
|
|
`]c` n Next Git |nvim_tree.api.node.navigate.git.next()|
|
|
`d` nx Delete |nvim_tree.api.fs.remove()|
|
|
`D` nx Trash |nvim_tree.api.fs.trash()|
|
|
`E` n Expand All |nvim_tree.api.tree.expand_all()|
|
|
`e` n Rename: Basename |nvim_tree.api.fs.rename_basename()|
|
|
`]e` n Next Diagnostic |nvim_tree.api.node.navigate.diagnostics.next()|
|
|
`[e` n Prev Diagnostic |nvim_tree.api.node.navigate.diagnostics.prev()|
|
|
`F` n Live Filter: Clear |nvim_tree.api.filter.live.clear()|
|
|
`f` n Live Filter: Start |nvim_tree.api.filter.live.start()|
|
|
`g?` n Help |nvim_tree.api.tree.toggle_help()|
|
|
`gy` nx Copy Absolute Path |nvim_tree.api.fs.copy.absolute_path()|
|
|
`ge` n Copy Basename |nvim_tree.api.fs.copy.basename()|
|
|
`H` n Toggle Filter: Dotfiles |nvim_tree.api.filter.dotfiles.toggle()|
|
|
`I` n Toggle Filter: Git Ignored |nvim_tree.api.filter.git.ignored.toggle()|
|
|
`J` n Last Sibling |nvim_tree.api.node.navigate.sibling.last()|
|
|
`K` n First Sibling |nvim_tree.api.node.navigate.sibling.first()|
|
|
`L` n Toggle Group Empty |nvim_tree.api.node.open.toggle_group_empty()|
|
|
`M` n Toggle Filter: No Bookmark |nvim_tree.api.filter.no_bookmark.toggle()|
|
|
`m` nx Toggle Bookmark |nvim_tree.api.marks.toggle()|
|
|
`o` n Open |nvim_tree.api.node.open.edit()|
|
|
`O` n Open: No Window Picker |nvim_tree.api.node.open.no_window_picker()|
|
|
`p` n Paste |nvim_tree.api.fs.paste()|
|
|
`gp` n Move |nvim_tree.api.fs.move()|
|
|
`P` n Parent Directory |nvim_tree.api.node.navigate.parent()|
|
|
`q` n Close |nvim_tree.api.tree.close()|
|
|
`r` n Rename |nvim_tree.api.fs.rename()|
|
|
`R` n Refresh |nvim_tree.api.tree.reload()|
|
|
`s` n Run System |nvim_tree.api.node.run.system()|
|
|
`S` n Search |nvim_tree.api.tree.search_node()|
|
|
`u` n Rename: Full Path |nvim_tree.api.fs.rename_full()|
|
|
`U` n Toggle Filter: Custom |nvim_tree.api.filter.custom.toggle()|
|
|
`W` n Collapse All |nvim_tree.api.tree.collapse_all()|
|
|
`x` nx Cut |nvim_tree.api.fs.cut()|
|
|
`y` n Copy Name |nvim_tree.api.fs.copy.filename()|
|
|
`Y` n Copy Relative Path |nvim_tree.api.fs.copy.relative_path()|
|
|
`<2-LeftMouse>` n Open |nvim_tree.api.node.open.edit()|
|
|
`<2-RightMouse>` n CD |nvim_tree.api.tree.change_root_to_node()|
|
|
|
|
==============================================================================
|
|
Quickstart: Custom Mappings *nvim-tree-quickstart-custom-mappings*
|
|
|
|
|nvim-tree-mappings-default| are applied by default however you may customise
|
|
via |nvim_tree.config| {on_attach} e.g. >lua
|
|
|
|
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.map.on_attach.default(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 config
|
|
require("nvim-tree").setup({
|
|
---
|
|
on_attach = my_on_attach,
|
|
---
|
|
})
|
|
<
|
|
==============================================================================
|
|
Quickstart: Highlight Groups *nvim-tree-quickstart-highlight*
|
|
|
|
Run |:NvimTreeHiTest| to show all the highlights that nvim-tree uses.
|
|
|
|
They can be customised before or after setup is called and will be immediately
|
|
applied at runtime. e.g. >lua
|
|
|
|
vim.cmd([[
|
|
:hi NvimTreeExecFile guifg=#ffa0a0
|
|
:hi NvimTreeSpecialFile guifg=#ff80ff gui=underline
|
|
:hi NvimTreeSymlink guifg=Yellow gui=italic
|
|
:hi link NvimTreeImageFile Title
|
|
]])
|
|
<
|
|
See |nvim-tree-highlight-groups| for details.
|
|
|
|
==============================================================================
|
|
Commands *nvim-tree-commands*
|
|
|
|
Some commands may be executed with a |<bang>| `!` or take a `path` string argument.
|
|
|
|
All commands execute public API.
|
|
|
|
*:NvimTreeOpen* |nvim_tree.api.tree.open()| >lua
|
|
|
|
require("nvim-tree.api").tree.open({
|
|
path = "<args>"
|
|
})
|
|
<
|
|
*:NvimTreeClose* |nvim_tree.api.tree.close()| >lua
|
|
|
|
require("nvim-tree.api").tree.close()
|
|
<
|
|
*:NvimTreeToggle* |nvim_tree.api.tree.toggle()| >lua
|
|
|
|
require("nvim-tree.api").tree.toggle({
|
|
path = "<args>",
|
|
find_file = false,
|
|
update_root = false,
|
|
focus = true,
|
|
})
|
|
<
|
|
*:NvimTreeFocus* |nvim_tree.api.tree.open()| >lua
|
|
|
|
require("nvim-tree.api").tree.open()
|
|
<
|
|
*:NvimTreeRefresh* |nvim_tree.api.tree.reload()| >lua
|
|
|
|
require("nvim-tree.api").tree.reload()
|
|
<
|
|
*:NvimTreeFindFile* |nvim_tree.api.tree.find_file()| >lua
|
|
|
|
require("nvim-tree.api").tree.find_file({
|
|
open = true,
|
|
update_root = "<bang>",
|
|
focus = true,
|
|
})
|
|
<
|
|
*:NvimTreeFindFileToggle* |nvim_tree.api.tree.toggle()| >lua
|
|
|
|
require("nvim-tree.api").tree.toggle({
|
|
path = "<args>",
|
|
find_file = true,
|
|
update_root = "<bang>",
|
|
focus = true,
|
|
})
|
|
<
|
|
*:NvimTreeClipboard* |nvim_tree.api.fs.print_clipboard()| >lua
|
|
|
|
require("nvim-tree.api").fs.print_clipboard()
|
|
<
|
|
*:NvimTreeCollapse* |nvim_tree.api.tree.collapse_all()| >lua
|
|
|
|
require("nvim-tree.api").tree.collapse_all({
|
|
keep_buffers = false
|
|
})
|
|
<
|
|
*:NvimTreeCollapseKeepBuffers* |nvim_tree.api.tree.collapse_all()| >lua
|
|
|
|
require("nvim-tree.api").tree.collapse_all({
|
|
keep_buffers = true
|
|
})
|
|
<
|
|
*:NvimTreeHiTest* |nvim_tree.api.appearance.hi_test()| >lua
|
|
|
|
require("nvim-tree.api").appearance.hi_test()
|
|
<
|
|
*:NvimTreeResize* |nvim_tree.api.tree.resize()| >lua
|
|
|
|
local sign = c.args:sub(1, 1)
|
|
if sign == "+" or sign == "-" then
|
|
require("nvim-tree.api").tree.resize({ relative = tonumber(c.args) })
|
|
else
|
|
require("nvim-tree.api").tree.resize({ absolute = tonumber(c.args) })
|
|
end
|
|
<
|
|
|
|
==============================================================================
|
|
Setup *nvim-tree-setup*
|
|
|
|
You must run the `setup()` function once to initialise nvim-tree. It may be
|
|
called again to apply a change in configuration without restarting Nvim.
|
|
|
|
The `setup()` function takes one optional argument: |nvim_tree.config|. If
|
|
omitted nvim-tree will be initialised with default configuration:
|
|
|nvim-tree-config-default|.
|
|
|
|
Config can be validated with |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)
|
|
<
|
|
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.
|
|
|
|
==============================================================================
|
|
Mappings *nvim-tree-mappings*
|
|
|
|
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.
|
|
|
|
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. >lua
|
|
|
|
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.map.on_attach.default(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,
|
|
---
|
|
})
|
|
<
|
|
Single left mouse mappings can be achieved via `<LeftRelease>`.
|
|
|
|
Single right / middle mouse mappings will require changes to |'mousemodel'| or |'mouse'|.
|
|
|
|
|vim.keymap.set()| {rhs} is a `(function|string)` thus it may be necessary to
|
|
define your own function to map complex functionality e.g. >lua
|
|
|
|
local function print_node_path()
|
|
local api = require("nvim-tree.api")
|
|
local node = api.tree.get_node_under_cursor()
|
|
print(node.absolute_path)
|
|
end
|
|
|
|
-- on_attach
|
|
vim.keymap.set("n", "<C-P>", print_node_path, opts("Print Path"))
|
|
<
|
|
==============================================================================
|
|
Mappings: Default *nvim-tree-mappings-default*
|
|
|
|
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 {on_attach} function. >lua
|
|
|
|
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_ON_ATTACH_DEFAULT
|
|
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", "x" }, "<Del>", api.fs.remove, opts("Delete"))
|
|
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 File Or Directory"))
|
|
vim.keymap.set("n", "bd", api.marks.bulk.delete, opts("Delete Bookmarked"))
|
|
vim.keymap.set("n", "bt", api.marks.bulk.trash, opts("Trash Bookmarked"))
|
|
vim.keymap.set("n", "bmv", api.marks.bulk.move, opts("Move Bookmarked"))
|
|
vim.keymap.set("n", "B", api.filter.no_buffer.toggle, opts("Toggle Filter: No Buffer"))
|
|
vim.keymap.set({ "n", "x" }, "c", api.fs.copy.node, opts("Copy"))
|
|
vim.keymap.set("n", "C", api.filter.git.clean.toggle, 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", "x" }, "d", api.fs.remove, opts("Delete"))
|
|
vim.keymap.set({ "n", "x" }, "D", api.fs.trash, opts("Trash"))
|
|
vim.keymap.set("n", "E", api.tree.expand_all, opts("Expand All"))
|
|
vim.keymap.set("n", "e", api.fs.rename_basename, opts("Rename: Basename"))
|
|
vim.keymap.set("n", "]e", api.node.navigate.diagnostics.next, opts("Next Diagnostic"))
|
|
vim.keymap.set("n", "[e", api.node.navigate.diagnostics.prev, opts("Prev Diagnostic"))
|
|
vim.keymap.set("n", "F", api.filter.live.clear, opts("Live Filter: Clear"))
|
|
vim.keymap.set("n", "f", api.filter.live.start, opts("Live Filter: Start"))
|
|
vim.keymap.set("n", "g?", api.tree.toggle_help, opts("Help"))
|
|
vim.keymap.set({ "n", "x" }, "gy", api.fs.copy.absolute_path, opts("Copy Absolute Path"))
|
|
vim.keymap.set("n", "ge", api.fs.copy.basename, opts("Copy Basename"))
|
|
vim.keymap.set("n", "H", api.filter.dotfiles.toggle, opts("Toggle Filter: Dotfiles"))
|
|
vim.keymap.set("n", "I", api.filter.git.ignored.toggle, opts("Toggle Filter: Git Ignored"))
|
|
vim.keymap.set("n", "J", api.node.navigate.sibling.last, opts("Last Sibling"))
|
|
vim.keymap.set("n", "K", api.node.navigate.sibling.first, opts("First Sibling"))
|
|
vim.keymap.set("n", "L", api.node.open.toggle_group_empty, opts("Toggle Group Empty"))
|
|
vim.keymap.set("n", "M", api.filter.no_bookmark.toggle, opts("Toggle Filter: No Bookmark"))
|
|
vim.keymap.set({ "n", "x" }, "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", "gp", api.fs.move, opts("Move"))
|
|
vim.keymap.set("n", "P", api.node.navigate.parent, opts("Parent Directory"))
|
|
vim.keymap.set("n", "q", api.tree.close, opts("Close"))
|
|
vim.keymap.set("n", "r", api.fs.rename, opts("Rename"))
|
|
vim.keymap.set("n", "R", api.tree.reload, opts("Refresh"))
|
|
vim.keymap.set("n", "s", api.node.run.system, opts("Run System"))
|
|
vim.keymap.set("n", "S", api.tree.search_node, opts("Search"))
|
|
vim.keymap.set("n", "u", api.fs.rename_full, opts("Rename: Full Path"))
|
|
vim.keymap.set("n", "U", api.filter.custom.toggle, opts("Toggle Filter: Custom"))
|
|
vim.keymap.set("n", "W", api.tree.collapse_all, opts("Collapse All"))
|
|
vim.keymap.set({ "n", "x" }, "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_ON_ATTACH_DEFAULT
|
|
<
|
|
Alternatively, you may apply these default mappings from your
|
|
|nvim_tree.config| {on_attach} via |nvim_tree.api.map.on_attach.default()| e.g. >lua
|
|
|
|
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.map.on_attach.default(bufnr)
|
|
|
|
-- your removals and mappings go here
|
|
end
|
|
<
|
|
|
|
==============================================================================
|
|
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.
|
|
|
|
Decorators are responsible for providing the icons and highlighting. They
|
|
apply additively in order of precedence.
|
|
|
|
`DECORATOR`
|
|
See |nvim_tree.config.renderer.decorator| for available decorators and their
|
|
default precedence.
|
|
|
|
`ICON?`
|
|
Enable via |nvim_tree.config.renderer.icons.show
|
|
|
|
`REQUIRES`
|
|
Features that must be enabled to show icons and highlighting.
|
|
|
|
`PLACEMENT`
|
|
Where to place icons: |nvim_tree.config.renderer.icons.placement|
|
|
|
|
`HIGHLIGHT`
|
|
What should be highlighted: |nvim_tree.config.renderer.highlight|
|
|
|
|
`DEVICONS?`
|
|
Glyphs and their colors will be overridden by optional plugin:
|
|
`nvim-tree/nvim-web-devicons`
|
|
See |nvim_tree.config.renderer.icons.web_devicons|
|
|
|
|
`GLYPHS`
|
|
Icon glyphs definitions.
|
|
|
|
`GROUPS`
|
|
Applicable highlight groups: |nvim-tree-highlight-groups|
|
|
|
|
Some defaults noted. In ascending order of default decorator additive
|
|
precedence:
|
|
|
|
`WHAT DECORATOR 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"` {git} Y |nvim_tree.config.git| {git_placement} `"before"` {highlight_git} `"none"` |nvim_tree.config.renderer.icons.glyphs.git| N `NvimTreeGit*`
|
|
|bufloaded()| `"Open"` - - - {highlight_opened_files}`"none"` - N ` NvimTreeOpened*`
|
|
Dotfiles `"Hidden"` {hidden} N - {hidden_placement} `"after"` {highlight_hidden} `"none"` |nvim_tree.config.renderer.icons.glyphs| {hidden} N `NvimTreeHidden*`
|
|
|'modified'| `"Modified"` {modified} Y |nvim_tree.config.modified| {modified_placement} `"after"` {highlight_modified} `"none"` |nvim_tree.config.renderer.icons.glyphs| {modified} N `NvimTreeModified*`
|
|
Bookmarked `"Bookmark"` {bookmarks} Y - {bookmarks_placement} `"signcolumn"` {highlight_bookmarks} `"none"` |nvim_tree.config.renderer.icons.glyphs| {bookmark} N `NvimTreeBookmark*`
|
|
Diag Status ` "Diagnostics"` {diagnostics}Y |nvim_tree.config.diagnostics| {diagnostics_placement}`"signcolumn"` {highlight_diagnostics} `"none" ` |nvim_tree.config.diagnostics.icons| N `NvimTreeDiagnostic*`
|
|
Copied `"Copied"` - - - {highlight_clipboard} `"name"` - N `NvimTreeCopiedHL`
|
|
Cut `"Cut"` - - - {highlight_clipboard} `"name"` - N `NvimTreeCutHL`
|
|
|
|
|
|
==============================================================================
|
|
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
|
|
groups.
|
|
|
|
Example |:highlight| >vim
|
|
:hi NvimTreeSymlink guifg=blue gui=bold,underline
|
|
<
|
|
It is recommended to enable |'termguicolors'| for the more pleasant 24-bit
|
|
colours.
|
|
|
|
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, following |nvim_tree.config.renderer.decorator|
|
|
precedence.
|
|
Only present attributes will clobber each other.
|
|
In this example a modified, opened file will have magenta text, with cyan
|
|
undercurl: >vim
|
|
:hi NvimTreeOpenedHL guifg=magenta guisp=red gui=underline
|
|
:hi NvimTreeModifiedFileHL guisp=cyan gui=undercurl
|
|
<
|
|
To prevent usage of a highlight:
|
|
|
|
- Before setup: link the group to `Normal` e.g. >vim
|
|
:hi NvimTreeExecFile Normal
|
|
<
|
|
- After setup: link it to `NONE`, to override the default link e.g. >lua
|
|
:hi! link NvimTreeExecFile NONE
|
|
<
|
|
==============================================================================
|
|
Highlight Groups: Default *nvim-tree-highlight-groups-default*
|
|
|
|
|:highlight-link| `default` or |:highlight-default| define the groups on setup:
|
|
|
|
Standard: >
|
|
NvimTreeNormal Normal
|
|
NvimTreeNormalFloat NormalFloat
|
|
NvimTreeNormalNC NormalFloat
|
|
|
|
NvimTreeLineNr LineNr
|
|
NvimTreeWinSeparator WinSeparator
|
|
NvimTreeEndOfBuffer EndOfBuffer
|
|
NvimTreePopup Normal
|
|
NvimTreeSignColumn NvimTreeNormal
|
|
|
|
NvimTreeCursorColumn CursorColumn
|
|
NvimTreeCursorLine CursorLine
|
|
NvimTreeCursorLineNr CursorLineNr
|
|
|
|
NvimTreeStatusLine StatusLine
|
|
NvimTreeStatusLineNC StatusLineNC
|
|
<
|
|
File Text: >
|
|
NvimTreeExecFile SpellCap
|
|
NvimTreeImageFile SpellCap
|
|
NvimTreeSpecialFile SpellCap
|
|
NvimTreeSymlink SpellCap
|
|
<
|
|
Folder Text: >
|
|
NvimTreeRootFolder Title
|
|
NvimTreeFolderName Directory
|
|
NvimTreeEmptyFolderName Directory
|
|
NvimTreeOpenedFolderName Directory
|
|
NvimTreeSymlinkFolderName Directory
|
|
<
|
|
File Icons: >
|
|
NvimTreeFileIcon NvimTreeNormal
|
|
NvimTreeSymlinkIcon NvimTreeNormal
|
|
<
|
|
Folder Icons: >
|
|
NvimTreeFolderIcon guifg=#8094b4 ctermfg=Blue
|
|
NvimTreeOpenedFolderIcon NvimTreeFolderIcon
|
|
NvimTreeClosedFolderIcon NvimTreeFolderIcon
|
|
NvimTreeFolderArrowClosed NvimTreeIndentMarker
|
|
NvimTreeFolderArrowOpen NvimTreeIndentMarker
|
|
<
|
|
Indent: >
|
|
NvimTreeIndentMarker NvimTreeFileIcon
|
|
<
|
|
Picker: >
|
|
NvimTreeWindowPicker guifg=#ededed guibg=#4493c8 gui=bold ctermfg=White ctermbg=Cyan
|
|
<
|
|
Live Filter: >
|
|
NvimTreeLiveFilterPrefix PreProc
|
|
NvimTreeLiveFilterValue ModeMsg
|
|
<
|
|
Clipboard: >
|
|
NvimTreeCopiedHL SpellRare
|
|
NvimTreeCutHL SpellBad
|
|
<
|
|
Bookmarks: >
|
|
NvimTreeBookmarkIcon NvimTreeFolderIcon
|
|
NvimTreeBookmarkHL SpellLocal
|
|
<
|
|
Modified: >
|
|
NvimTreeModifiedIcon Type
|
|
NvimTreeModifiedFileHL NvimTreeModifiedIcon
|
|
NvimTreeModifiedFolderHL NvimTreeModifiedIcon
|
|
|
|
Hidden: >
|
|
NvimTreeModifiedIcon Conceal
|
|
NvimTreeModifiedFileHL NvimTreeHiddenIcon
|
|
NvimTreeModifiedFolderHL NvimTreeHiddenFileHL
|
|
<
|
|
Hidden Display: >
|
|
NvimTreeHiddenDisplay Conceal
|
|
<
|
|
Opened: >
|
|
NvimTreeOpenedHL Special
|
|
<
|
|
Git Icon: >
|
|
NvimTreeGitDeletedIcon Statement
|
|
NvimTreeGitDirtyIcon Statement
|
|
NvimTreeGitIgnoredIcon Comment
|
|
NvimTreeGitMergeIcon Constant
|
|
NvimTreeGitNewIcon PreProc
|
|
NvimTreeGitRenamedIcon PreProc
|
|
NvimTreeGitStagedIcon Constant
|
|
<
|
|
Git File File Highlight: >
|
|
NvimTreeGitFileDeletedHL NvimTreeGitDeletedIcon
|
|
NvimTreeGitFileDirtyHL NvimTreeGitDirtyIcon
|
|
NvimTreeGitFileIgnoredHL NvimTreeGitIgnoredIcon
|
|
NvimTreeGitFileMergeHL NvimTreeGitMergeIcon
|
|
NvimTreeGitFileNewHL NvimTreeGitNewIcon
|
|
NvimTreeGitFileRenamedHL NvimTreeGitRenamedIcon
|
|
NvimTreeGitFileStagedHL NvimTreeGitStagedIcon
|
|
<
|
|
Git Folder Folder Highlight: >
|
|
NvimTreeGitFolderDeletedHL NvimTreeGitFileDeletedHL
|
|
NvimTreeGitFolderDirtyHL NvimTreeGitFileDirtyHL
|
|
NvimTreeGitFolderIgnoredHL NvimTreeGitFileIgnoredHL
|
|
NvimTreeGitFolderMergeHL NvimTreeGitFileMergeHL
|
|
NvimTreeGitFolderNewHL NvimTreeGitFileNewHL
|
|
NvimTreeGitFolderRenamedHL NvimTreeGitFileRenamedHL
|
|
NvimTreeGitFolderStagedHL NvimTreeGitFileStagedHL
|
|
<
|
|
Diagnostics Icon: >
|
|
NvimTreeDiagnosticErrorIcon DiagnosticError
|
|
NvimTreeDiagnosticWarnIcon DiagnosticWarn
|
|
NvimTreeDiagnosticInfoIcon DiagnosticInfo
|
|
NvimTreeDiagnosticHintIcon DiagnosticHint
|
|
<
|
|
Diagnostics File Highlight: >
|
|
NvimTreeDiagnosticErrorFileHL DiagnosticUnderlineError
|
|
NvimTreeDiagnosticWarnFileHL DiagnosticUnderlineWarn
|
|
NvimTreeDiagnosticInfoFileHL DiagnosticUnderlineInfo
|
|
NvimTreeDiagnosticHintFileHL DiagnosticUnderlineHint
|
|
<
|
|
Diagnostics Folder Highlight: >
|
|
NvimTreeDiagnosticErrorFolderHL NvimTreeDiagnosticErrorFileHL
|
|
NvimTreeDiagnosticWarnFolderHL NvimTreeDiagnosticWarnFileHL
|
|
NvimTreeDiagnosticInfoFolderHL NvimTreeDiagnosticInfoFileHL
|
|
NvimTreeDiagnosticHintFolderHL NvimTreeDiagnosticHintFileHL
|
|
<
|
|
==============================================================================
|
|
Events *nvim-tree-events*
|
|
|
|
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_events_kind|.
|
|
|
|
e.g. handler for node renamed: >lua
|
|
|
|
local api = require("nvim-tree.api")
|
|
local Event = api.events.Event
|
|
|
|
api.events.subscribe(Event.NodeRenamed, function(data)
|
|
print("Node renamed from " .. data.old_name .. " to " .. data.new_name)
|
|
end)
|
|
<
|
|
*nvim_tree_events_kind*
|
|
|
|
- Event.Ready
|
|
When NvimTree has been initialized.
|
|
• Note: Handler takes no parameter.
|
|
|
|
- Event.TreePreOpen
|
|
Invoked before the window and buffer for NvimTree are created
|
|
or opened. Before `Event.TreeOpen`
|
|
• Note: Handler takes no parameter.
|
|
|
|
- Event.TreeOpen
|
|
Invoked after the NvimTree is opened.
|
|
• Note: Handler takes no parameter.
|
|
|
|
- Event.TreeClose
|
|
Invoked after the NvimTree is closed, but before the window is
|
|
closed. Dispatched on |WinClosed| event for NvimTree window.
|
|
• Note: Handler takes no parameter.
|
|
|
|
- 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.config| {on_attach}
|
|
handler parameters: ~
|
|
{buf} `{number} `API buffer handle (buffer number)
|
|
|
|
- Event.TreeRendered
|
|
Invoked every time the tree is redrawn. Normally this event
|
|
happens after `Event.TreeOpen` except that handlers of this
|
|
one will have access to the tree buffer populated with the
|
|
final content.
|
|
handler parameters: ~
|
|
{bufnr} `{number} `API buffer handle (buffer number)
|
|
{winnr} `{number} `API window handle (window number)
|
|
|
|
*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: >lua
|
|
|
|
vim.api.nvim_create_autocmd("User", {
|
|
pattern = "NvimTreeRequired",
|
|
callback = function(data)
|
|
---
|
|
end,
|
|
})
|
|
<
|
|
==============================================================================
|
|
Prompts *nvim-tree-prompts*
|
|
|
|
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
|
|
configurations for different types of prompts.
|
|
|
|
- `nvimtree_overwrite_rename`
|
|
overwrite or rename during |nvim_tree.api.fs.paste()|
|
|
|
|
- `nvimtree_remove`
|
|
delete during |nvim_tree.api.fs.remove()|
|
|
|
|
- `nvimtree_trash`
|
|
send to trash during |nvim_tree.api.fs.trash()|
|
|
|
|
- `nvimtree_bulk_delete`
|
|
delete all bookmarked during |nvim_tree.api.marks.bulk.delete()|
|
|
|
|
- `nvimtree_bulk_trash`
|
|
send all bookmarked to trash during |nvim_tree.api.marks.bulk.trash()|
|
|
|
|
==============================================================================
|
|
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
|
|
- Some filesystem watcher error related to permissions will not be reported
|
|
- Filesystem watchers can experience severe performance issues. It is strongly
|
|
recommended to tightly control watcher usage via
|
|
|nvim_tree.config.filesystem_watchers| {whitelist_dirs}
|
|
|
|
Powershell
|
|
- Observed Nvim hanging after a runaway (infinite) number of events on a
|
|
single directory. See |nvim_tree.config.filesystem_watchers| {max_events}
|
|
|
|
==============================================================================
|
|
netrw *nvim-tree-netrw*
|
|
|
|
|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
|
|
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|: >lua
|
|
|
|
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.config| {disable_netrw}` = false`
|
|
|nvim_tree.config| {hijack_netrw}` = true`
|
|
|
|
==============================================================================
|
|
Legacy *nvim-tree-legacy*
|
|
|
|
Backwards compatible, silent refactors have been done.
|
|
|
|
==============================================================================
|
|
Legacy: Config *nvim-tree-legacy-config*
|
|
|
|
Legacy config is translated to the current, making type and value changes as
|
|
needed.
|
|
|
|
`update_cwd` |nvim_tree.config| {sync_root_with_cwd}
|
|
`update_focused_file.update_cwd` |nvim_tree.config.update_focused_file| {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.web_devicons.file| {color}
|
|
`renderer.icons.padding` |nvim_tree.config.renderer.icons.padding| {icon}
|
|
|
|
==============================================================================
|
|
Legacy: API *nvim-tree-legacy-api*
|
|
|
|
Deprecated API with unchanged function signature:
|
|
|
|
`api.config.mappings.get_keymap` |nvim_tree.api.map.keymap.current()|
|
|
`api.config.mappings.get_keymap_default` |nvim_tree.api.map.keymap.default()|
|
|
`api.config.mappings.default_on_attach` |nvim_tree.api.map.on_attach.default()|
|
|
|
|
`api.diagnostics.hi_test` |nvim_tree.api.appearance.hi_test()|
|
|
|
|
`api.live_filter.start` |nvim_tree.api.filter.live.start()|
|
|
`api.live_filter.clear` |nvim_tree.api.filter.live.clear()|
|
|
|
|
`api.tree.toggle_enable_filters` |nvim_tree.api.filter.toggle()|
|
|
`api.tree.toggle_gitignore_filter` |nvim_tree.api.filter.git.ignored.toggle()|
|
|
`api.tree.toggle_git_clean_filter` |nvim_tree.api.filter.git.clean.toggle()|
|
|
`api.tree.toggle_no_buffer_filter` |nvim_tree.api.filter.no_buffer.toggle()|
|
|
`api.tree.toggle_custom_filter` |nvim_tree.api.filter.custom.toggle()|
|
|
`api.tree.toggle_hidden_filter` |nvim_tree.api.filter.dotfiles.toggle()|
|
|
`api.tree.toggle_no_bookmark_filter` |nvim_tree.api.filter.no_bookmark.toggle()|
|
|
|
|
==============================================================================
|
|
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: >
|
|
|
|
NvimTreeModifiedIcon NvimTreeModifiedFile
|
|
NvimTreeOpenedHL NvimTreeOpenedFile
|
|
NvimTreeBookmarkIcon NvimTreeBookmark
|
|
|
|
NvimTreeGitDeletedIcon NvimTreeGitDeleted
|
|
NvimTreeGitDirtyIcon NvimTreeGitDirty
|
|
NvimTreeGitIgnoredIcon NvimTreeGitIgnored
|
|
NvimTreeGitMergeIcon NvimTreeGitMerge
|
|
NvimTreeGitNewIcon NvimTreeGitNew
|
|
NvimTreeGitRenamedIcon NvimTreeGitRenamed
|
|
NvimTreeGitStagedIcon NvimTreeGitStaged
|
|
|
|
NvimTreeGitFileDeletedHL NvimTreeFileDeleted
|
|
NvimTreeGitFileDirtyHL NvimTreeFileDirty
|
|
NvimTreeGitFileIgnoredHL NvimTreeFileIgnored
|
|
NvimTreeGitFileMergeHL NvimTreeFileMerge
|
|
NvimTreeGitFileNewHL NvimTreeFileNew
|
|
NvimTreeGitFileRenamedHL NvimTreeFileRenamed
|
|
NvimTreeGitFileStagedHL NvimTreeFileStaged
|
|
|
|
NvimTreeGitFolderDeletedHL NvimTreeFolderDeleted
|
|
NvimTreeGitFolderDirtyHL NvimTreeFolderDirty
|
|
NvimTreeGitFolderIgnoredHL NvimTreeFolderIgnored
|
|
NvimTreeGitFolderMergeHL NvimTreeFolderMerge
|
|
NvimTreeGitFolderNewHL NvimTreeFolderNew
|
|
NvimTreeGitFolderRenamedHL NvimTreeFolderRenamed
|
|
NvimTreeGitFolderStagedHL NvimTreeFolderStaged
|
|
|
|
NvimTreeLspDiagnosticsError NvimTreeDiagnosticErrorIcon
|
|
NvimTreeLspDiagnosticsWarning NvimTreeDiagnosticWarnIcon
|
|
NvimTreeLspDiagnosticsInformation NvimTreeDiagnosticInfoIcon
|
|
NvimTreeLspDiagnosticsHint NvimTreeDiagnosticHintIcon
|
|
|
|
NvimTreeLspDiagnosticsErrorText NvimTreeDiagnosticErrorFileHL
|
|
NvimTreeLspDiagnosticsWarningText NvimTreeDiagnosticWarnFileHL
|
|
NvimTreeLspDiagnosticsInformationText NvimTreeDiagnosticInfoFileHL
|
|
NvimTreeLspDiagnosticsHintText NvimTreeDiagnosticHintFileHL
|
|
|
|
NvimTreeLspDiagnosticsErrorFolderText NvimTreeDiagnosticErrorFolderHL
|
|
NvimTreeLspDiagnosticsWarningFolderText NvimTreeDiagnosticWarnFolderHL
|
|
NvimTreeLspDiagnosticsInformationFolderText NvimTreeDiagnosticInfoFolderHL
|
|
NvimTreeLspDiagnosticsHintFolderText NvimTreeDiagnosticHintFolderHL
|
|
<
|
|
|
|
|
|
==============================================================================
|
|
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.
|
|
|
|
{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.update_focused_file.update_root|.
|
|
|
|
{prefer_startup_root} prefer startup root directory when updating root
|
|
directory of the tree. Requires
|
|
|nvim_tree.config.update_focused_file.update_root|.
|
|
|
|
{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: ~
|
|
• {actions}? (`nvim_tree.config.actions`)
|
|
|nvim_tree.config.actions|
|
|
• {auto_reload_on_write}? (`boolean`) (default: `true`)
|
|
• {bookmarks}? (`nvim_tree.config.bookmarks`)
|
|
|nvim_tree.config.bookmarks|
|
|
• {diagnostics}? (`nvim_tree.config.diagnostics`)
|
|
|nvim_tree.config.diagnostics|
|
|
• {disable_netrw}? (`boolean`) (default: `false`)
|
|
• {experimental}? (`nvim_tree.config.experimental`)
|
|
|nvim_tree.config.experimental|
|
|
• {filesystem_watchers}? (`nvim_tree.config.filesystem_watchers`)
|
|
|nvim_tree.config.filesystem_watchers|
|
|
• {filters}? (`nvim_tree.config.filters`)
|
|
|nvim_tree.config.filters|
|
|
• {git}? (`nvim_tree.config.git`)
|
|
|nvim_tree.config.git|
|
|
• {help}? (`nvim_tree.config.help`)
|
|
|nvim_tree.config.help|
|
|
• {hijack_cursor}? (`boolean`) (default: `false`)
|
|
• {hijack_directories}? (`nvim_tree.config.hijack_directories`)
|
|
|nvim_tree.config.hijack_directories|
|
|
• {hijack_netrw}? (`boolean`) (default: `true`)
|
|
• {hijack_unnamed_buffer_when_opening}? (`boolean`) (default: `false`)
|
|
• {live_filter}? (`nvim_tree.config.live_filter`)
|
|
|nvim_tree.config.live_filter|
|
|
• {log}? (`nvim_tree.config.log`)
|
|
|nvim_tree.config.log|
|
|
• {modified}? (`nvim_tree.config.modified`)
|
|
|nvim_tree.config.modified|
|
|
• {notify}? (`nvim_tree.config.notify`)
|
|
|nvim_tree.config.notify|
|
|
• {on_attach}? (`"default"|(fun(bufnr: integer))`)
|
|
(default: `default`)
|
|
• {prefer_startup_root}? (`boolean`) (default: `false`)
|
|
• {reload_on_bufenter}? (`boolean`) (default: `false`)
|
|
• {renderer}? (`nvim_tree.config.renderer`)
|
|
|nvim_tree.config.renderer|
|
|
• {respect_buf_cwd}? (`boolean`) (default: `false`)
|
|
• {root_dirs}? (`string[]`) (default: `{}`)
|
|
• {select_prompts}? (`boolean`) (default: `false`)
|
|
• {sort}? (`nvim_tree.config.sort`)
|
|
|nvim_tree.config.sort|
|
|
• {sync_root_with_cwd}? (`boolean`) (default: `false`)
|
|
• {tab}? (`nvim_tree.config.tab`)
|
|
|nvim_tree.config.tab|
|
|
• {trash}? (`nvim_tree.config.trash`)
|
|
|nvim_tree.config.trash|
|
|
• {ui}? (`nvim_tree.config.ui`)
|
|
|nvim_tree.config.ui|
|
|
• {update_focused_file}? (`nvim_tree.config.update_focused_file`)
|
|
|nvim_tree.config.update_focused_file|
|
|
• {view}? (`nvim_tree.config.view`)
|
|
|nvim_tree.config.view|
|
|
|
|
==============================================================================
|
|
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: ~
|
|
• {files_first}? (`boolean`, default: `false`) Sort files before
|
|
folders. Has no effect when {sorter} is a function.
|
|
Overrides {folders_first}.
|
|
• {folders_first}? (`boolean`, default: `true`) Sort folders before
|
|
files. Has no effect when {sorter} is a function.
|
|
• {sorter}? (`nvim_tree.config.sort.Sorter|(fun(nodes: nvim_tree.api.Node[]): nvim_tree.config.sort.Sorter?)`)
|
|
(default: `"name"`)
|
|
|
|
==============================================================================
|
|
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.width.spec| for static control or
|
|
a |nvim_tree.config.view.width| for fully dynamic control based on longest
|
|
line.
|
|
|
|
*nvim_tree.config.view.width.spec*
|
|
• `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.
|
|
• {float}? (`nvim_tree.config.view.float`)
|
|
|nvim_tree.config.view.float|
|
|
• {number}? (`boolean`, default: `false`)
|
|
|'number'|
|
|
• {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.
|
|
• {relativenumber}? (`boolean`, default: `false`)
|
|
|'relativenumber'|
|
|
• {side}? (`"left"|"right"`) (default: `"left"`)
|
|
• {signcolumn}? (`"yes"|"auto"|"no"`, default:
|
|
`"yes"`) |'signcolumn'|
|
|
• {width}? (`nvim_tree.config.view.width.spec|nvim_tree.config.view.width`)
|
|
(default: `30`)
|
|
|
|
*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`)
|
|
• {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, }`)
|
|
• {quit_on_focus_loss}? (`boolean`, default: `true`) Close the floating
|
|
window when it loses focus.
|
|
|
|
*nvim_tree.config.view.width*
|
|
Configure dynamic width based on longest line.
|
|
|
|
Fields: ~
|
|
• {lines_excluded}? (`("root")[]`, default: `{ "root" }`) Exclude these
|
|
lines when computing width.
|
|
• {max}? (`nvim_tree.config.view.width.spec`, default: `-1`)
|
|
-1 for unbounded.
|
|
• {min}? (`nvim_tree.config.view.width.spec`) (default:
|
|
`30`)
|
|
• {padding}? (`nvim_tree.config.view.width.spec`, default: `1`)
|
|
Extra padding to the right.
|
|
|
|
==============================================================================
|
|
Config: renderer *nvim-tree-config-renderer*
|
|
|
|
*nvim_tree.config.renderer*
|
|
Controls the appearance of the tree.
|
|
|
|
{highlight_} *nvim_tree.config.renderer.highlight*
|
|
|
|
See |nvim-tree-icons-highlighting|
|
|
• `"none"`: no highlighting
|
|
• `"icon"`: icon only
|
|
• `"name"`: name only
|
|
• `"all"`: icon and name
|
|
|
|
{decorators} *nvim_tree.config.renderer.decorator*
|
|
|
|
See |nvim-tree-icons-highlighting|
|
|
|
|
A builtin decorator name `string` or |nvim_tree.api.Decorator| class.
|
|
|
|
Builtin decorators in their default order:
|
|
• `"Git"`
|
|
• `"Open"`
|
|
• `"Hidden"`
|
|
• `"Modified"`
|
|
• `"Bookmark"`
|
|
• `"Diagnostics"`
|
|
• `"Copied"`
|
|
• `"Cut"`
|
|
|
|
Specify {decorators} is a list e.g. `{ "Git", MyDecorator, "Cut" }`
|
|
|
|
{root_folder_label} *nvim_tree.config.renderer.root_folder_label*
|
|
|
|
Controls the root folder name and visibility:
|
|
• `string`: |filename-modifiers| format string, default `":~:s?$?/..?"`
|
|
• `false`: 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
|
|
<
|
|
|
|
{hidden_display} *nvim_tree.config.renderer.hidden_display*
|
|
|
|
Summary of hidden nodes, below the last node in the directory, highlighted
|
|
with `NvimTreeHiddenDisplay`.
|
|
• `"none"`: disabled, default
|
|
• `"simple"`: total number of hidden files e.g.
|
|
• (3 hidden)
|
|
• `"all"`: total and by reason: the filter that hid the node e.g.
|
|
• (14 total git: 5, dotfile: 9)
|
|
• `(fun(hidden_stats: nvim_tree.config.renderer.hidden_stats): string)`
|
|
|
|
See |nvim_tree.config.renderer.hidden_stats| for details and example.
|
|
|
|
Fields: ~
|
|
• {add_trailing}? (`boolean`, default: `false`) Appends a
|
|
trailing slash to folder and symlink folder
|
|
target names.
|
|
• {decorators}? (`nvim_tree.config.renderer.decorator[]`, default: `{ "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", }`)
|
|
List in order of additive precedence.
|
|
• {full_name}? (`boolean`, default: `false`) Display nodes
|
|
whose name length is wider than the width
|
|
of nvim-tree window in floating window.
|
|
• {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.
|
|
• {hidden_display}? (`nvim_tree.config.renderer.hidden_display`, default: `none`)
|
|
|nvim_tree.config.renderer.hidden_display|
|
|
• {highlight_bookmarks}? (`nvim_tree.config.renderer.highlight`)
|
|
(default: `"none"`)
|
|
• {highlight_clipboard}? (`nvim_tree.config.renderer.highlight`)
|
|
(default: `"name"`)
|
|
• {highlight_diagnostics}? (`nvim_tree.config.renderer.highlight`)
|
|
(default: `"none"`)
|
|
• {highlight_git}? (`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_opened_files}? (`nvim_tree.config.renderer.highlight`)
|
|
(default: `"none"`)
|
|
• {icons}? (`nvim_tree.config.renderer.icons`)
|
|
|nvim_tree.config.renderer.icons|
|
|
• {indent_markers}? (`nvim_tree.config.renderer.indent_markers`)
|
|
|nvim_tree.config.renderer.indent_markers|
|
|
• {indent_width}? (`integer`, default: `2`) Number of spaces
|
|
for each tree nesting level. Minimum 1.
|
|
• {root_folder_label}? (`nvim_tree.config.renderer.root_folder_label`, default: `":~:s?$?/..?"`)
|
|
|nvim_tree.config.renderer.root_folder_label|
|
|
• {special_files}? (`string[]`, default: `{ "Cargo.toml", "Makefile", "README.md", "readme.md", }`)
|
|
Highlight special files and directories
|
|
with `NvimTreeSpecial*`.
|
|
• {symlink_destination}? (`boolean`, default: `true`) Appends an
|
|
arrow followed by the target of the
|
|
symlink.
|
|
|
|
*nvim_tree.config.renderer.hidden_stats*
|
|
Number of hidden nodes in a directory by reason: the filter that hid the
|
|
node.
|
|
|
|
Passed to your |nvim_tree.config.renderer.hidden_display| function e.g. >lua
|
|
|
|
---@param hidden_stats nvim_tree.config.renderer.hidden_stats
|
|
---@return string? summary
|
|
local my_hidden_display = 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
|
|
<
|
|
|
|
Fields: ~
|
|
• {bookmark} (`integer`)
|
|
• {buf} (`integer`)
|
|
• {custom} (`integer`)
|
|
• {dotfile} (`integer`)
|
|
• {git} (`integer`)
|
|
• {live_filter} (`integer`)
|
|
|
|
*nvim_tree.config.renderer.icons*
|
|
Icons and separators
|
|
|
|
{_placement} *nvim_tree.config.renderer.icons.placement*
|
|
• `"before"`: before file/folder, after the file/folders icons
|
|
• `"after"`: after file/folder
|
|
• `"signcolumn"`: far left, requires |nvim_tree.config.view| {signcolumn}.
|
|
• `"right_align"`: far right
|
|
|
|
Fields: ~
|
|
• {bookmarks_placement}? (`nvim_tree.config.renderer.icons.placement`)
|
|
(default: `signcolumn`)
|
|
• {diagnostics_placement}? (`nvim_tree.config.renderer.icons.placement`)
|
|
(default: `signcolumn`)
|
|
• {git_placement}? (`nvim_tree.config.renderer.icons.placement`)
|
|
(default: `before`)
|
|
• {glyphs}? (`nvim_tree.config.renderer.icons.glyphs`)
|
|
|nvim_tree.config.renderer.icons.glyphs|
|
|
• {hidden_placement}? (`nvim_tree.config.renderer.icons.placement`)
|
|
(default: `after`)
|
|
• {modified_placement}? (`nvim_tree.config.renderer.icons.placement`)
|
|
(default: `after`)
|
|
• {padding}? (`table`)
|
|
*nvim_tree.config.renderer.icons.padding*
|
|
• {folder_arrow}? (`string`, default: `" "`)
|
|
Between folder arrow icon and file/folder
|
|
icon.
|
|
• {icon}? (`string`, default: `" "`) Between
|
|
icon and filename.
|
|
• {show}? (`nvim_tree.config.renderer.icons.show`)
|
|
|nvim_tree.config.renderer.icons.show|
|
|
• {symlink_arrow}? (`string`, default: `" ➛ "`) Separator
|
|
between symlink source and target.
|
|
• {web_devicons}? (`nvim_tree.config.renderer.icons.web_devicons`)
|
|
|nvim_tree.config.renderer.icons.web_devicons|
|
|
|
|
*nvim_tree.config.renderer.icons.glyphs*
|
|
See |nvim-tree-icons-highlighting|.
|
|
|
|
Glyphs that appear in the sign column must have length <= 2
|
|
|
|
Fields: ~
|
|
• {bookmark}? (`string`) (default: `""`)
|
|
• {default}? (`string`, default: `""`) Files
|
|
• {folder}? (`table`) *nvim_tree.config.renderer.icons.glyphs.folder*
|
|
• {arrow_closed}? (`string`) (default: left arrow)
|
|
• {arrow_open}? (`string`) (default: down arrow)
|
|
• {default}? (`string`) (default: `""`)
|
|
• {empty}? (`string`) (default: `""`)
|
|
• {empty_open}? (`string`) (default: `""`)
|
|
• {open}? (`string`) (default: `""`)
|
|
• {symlink}? (`string`) (default: `""`)
|
|
• {symlink_open}? (`string`) (default: `""`)
|
|
• {git}? (`table`) *nvim_tree.config.renderer.icons.glyphs.git*
|
|
• {deleted}? (`string`) (default: `""`)
|
|
• {ignored}? (`string`) (default: `"◌"`)
|
|
• {renamed}? (`string`) (default: `"➜"`)
|
|
• {staged}? (`string`) (default: `"✓"`)
|
|
• {unmerged}? (`string`) (default: `""`)
|
|
• {unstaged}? (`string`) (default: `"✗"`)
|
|
• {untracked}? (`string`) (default: `"★"`)
|
|
• {hidden}? (`string`) (default: `""`)
|
|
• {modified}? (`string`) (default: `"●"`)
|
|
• {symlink}? (`string`) (default: `""`)
|
|
|
|
*nvim_tree.config.renderer.icons.show*
|
|
See |nvim-tree-icons-highlighting|.
|
|
|
|
Fields: ~
|
|
• {bookmarks}? (`boolean`) (default: `true`)
|
|
• {diagnostics}? (`boolean`) (default: `true`)
|
|
• {file}? (`boolean`) (default: `true`)
|
|
• {folder}? (`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.indent_markers|.
|
|
• {git}? (`boolean`) (default: `true`)
|
|
• {hidden}? (`boolean`) (default: `false`)
|
|
• {modified}? (`boolean`) (default: `true`)
|
|
|
|
*nvim_tree.config.renderer.icons.web_devicons*
|
|
Configure optional plugin `nvim-tree/nvim-web-devicons`, see
|
|
|nvim-tree-icons-highlighting|.
|
|
|
|
Fields: ~
|
|
• {file}? (`table`)
|
|
*nvim_tree.config.renderer.icons.web_devicons.file*
|
|
• {color}? (`boolean`) (default: `true`)
|
|
• {enable}? (`boolean`) (default: `true`)
|
|
• {folder}? (`table`)
|
|
*nvim_tree.config.renderer.icons.web_devicons.folder*
|
|
• {color}? (`boolean`) (default: `true`)
|
|
• {enable}? (`boolean`) (default: `false`)
|
|
|
|
*nvim_tree.config.renderer.indent_markers*
|
|
|
|
Fields: ~
|
|
• {enable}? (`boolean`, default: `false`) Display indent markers
|
|
when folders are open.
|
|
• {icons}? (`table`)
|
|
*nvim_tree.config.renderer.indent_markers.icons*
|
|
Before the file/directory, length 1.
|
|
• {bottom}? (`string`) (default: `"─"`)
|
|
• {corner}? (`string`) (default: `"└"`)
|
|
• {edge}? (`string`) (default: `"│"`)
|
|
• {item}? (`string`) (default: `"│"`)
|
|
• {none}? (`string`) (default: `" "`)
|
|
• {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}
|
|
|
|
==============================================================================
|
|
Config: hijack_directories *nvim-tree-config-hijack-directories*
|
|
|
|
*nvim_tree.config.hijack_directories*
|
|
Hijack directory buffers by replacing the directory buffer with the tree.
|
|
|
|
Disable this option if you use vim-dirvish or dirbuf.nvim.
|
|
|
|
If |nvim_tree.config| {hijack_netrw} and {disable_netrw} are `false` this
|
|
feature will be disabled.
|
|
|
|
Fields: ~
|
|
• {auto_open}? (`boolean`, default: `true`) Open if the tree was
|
|
previously closed.
|
|
• {enable}? (`boolean`) (default: `true`)
|
|
|
|
==============================================================================
|
|
Config: update_focused_file *nvim-tree-config-update-focused-file*
|
|
|
|
*nvim_tree.config.update_focused_file*
|
|
Update the focused file on |BufEnter|, uncollapsing folders recursively.
|
|
|
|
Fields: ~
|
|
• {enable}? (`boolean`) (default: `false`)
|
|
• {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.
|
|
• {update_root}? (`nvim_tree.config.update_focused_file.update_root`)
|
|
|nvim_tree.config.update_focused_file.update_root|
|
|
|
|
*nvim_tree.config.update_focused_file.update_root*
|
|
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.update_focused_file|
|
|
|
|
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.
|
|
|
|
==============================================================================
|
|
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: ~
|
|
• {cygwin_support}? (`boolean`, default: `false`) Use `cygpath` if
|
|
available to resolve paths for git.
|
|
• {disable_for_dirs}? (`string[]|(fun(path: string): boolean)`,
|
|
default: `{}`) Disable for top level paths.
|
|
• {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}.
|
|
• {timeout}? (`integer`, default: `400`) `git` processes
|
|
timeout milliseconds.
|
|
|
|
==============================================================================
|
|
Config: diagnostics *nvim-tree-config-diagnostics*
|
|
|
|
*nvim_tree.config.diagnostics*
|
|
Integrate with |lsp| or COC diagnostics.
|
|
|
|
See |nvim-tree-icons-highlighting|.
|
|
|
|
Fields: ~
|
|
• {debounce_delay}? (`integer`, default: `500`) Idle milliseconds
|
|
between diagnostic event and tree update.
|
|
• {diagnostic_opts}? (`boolean`, default: `false`) Global
|
|
|vim.diagnostic.Opts| overrides {severity} and
|
|
{icons}
|
|
• {enable}? (`boolean`) (default: `false`)
|
|
• {icons}? (`table`) *nvim_tree.config.diagnostics.icons*
|
|
• {error}? (`string`) (default: `""` )
|
|
• {hint}? (`string`) (default: `""` )
|
|
• {info}? (`string`) (default: `""` )
|
|
• {warning}? (`string`) (default: `""` )
|
|
• {severity}? (`table`)
|
|
*nvim_tree.config.diagnostics.severity*
|
|
• {max}? (`vim.diagnostic.Severity`, default:
|
|
ERROR) |vim.diagnostic.severity|
|
|
• {min}? (`vim.diagnostic.Severity`, default:
|
|
HINT) |vim.diagnostic.severity|
|
|
• {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}.
|
|
|
|
==============================================================================
|
|
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}.
|
|
|
|
==============================================================================
|
|
Config: filters *nvim-tree-config-filters*
|
|
|
|
*nvim_tree.config.filters*
|
|
Filters may be applied to the tree to exclude 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.filter.git.ignored.toggle()|
|
|
Ignore files based on `.gitignore`. Requires |nvim_tree.config.git|
|
|
|
|
`H `{dotfiles}` `|nvim_tree.api.filter.dotfiles.toggle()|
|
|
Filter dotfiles: files/directories starting with a `.`
|
|
|
|
`C `{git_clean}` `|nvim_tree.api.filter.git.clean.toggle()|
|
|
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.filter.no_buffer.toggle()|
|
|
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.filter.no_bookmark.toggle()|
|
|
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.filter.custom.toggle()|
|
|
Disable specific file/directory names via:
|
|
• a list of backslash escaped |regular-expression| 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.filter.toggle()|
|
|
|
|
Files/directories may be {exclude}d from filtering: they will always be
|
|
shown, overriding {git_ignored}, {dotfiles} and {custom}.
|
|
|
|
Fields: ~
|
|
• {custom}? (`string[]|(fun(absolute_path: string): boolean)`)
|
|
(default: `{}`)
|
|
• {dotfiles}? (`boolean`) (default: `false`)
|
|
• {enable}? (`boolean`, default: `true`) Enable all filters.
|
|
• {exclude}? (`string[]`) (default: `{}`)
|
|
• {git_clean}? (`boolean`) (default: `false`)
|
|
• {git_ignored}? (`boolean`) (default: `true`)
|
|
• {no_bookmark}? (`boolean`) (default: `false`)
|
|
• {no_buffer}? (`boolean`) (default: `false`)
|
|
|
|
==============================================================================
|
|
Config: live_filter *nvim-tree-config-live-filter*
|
|
|
|
*nvim_tree.config.live_filter*
|
|
Live filter allows you to filter the tree nodes dynamically using
|
|
|regular-expression| matching.
|
|
|
|
This feature is bound to the `f` key by default. The filter can be cleared
|
|
with the `F` key by default.
|
|
|
|
Fields: ~
|
|
• {always_show_folders}? (`boolean`, default: `true`) Whether to filter
|
|
folders or not.
|
|
• {prefix}? (`string`, default: `"[FILTER]: "`) Prefix of
|
|
the filter displayed in the buffer.
|
|
|
|
==============================================================================
|
|
Config: filesystem_watchers *nvim-tree-config-filesystem-watchers*
|
|
|
|
*nvim_tree.config.filesystem_watchers*
|
|
Use file system watchers (libuv `uv_fs_event_t`) to monitor the filesystem
|
|
for changes and update the tree.
|
|
|
|
With this feature, the tree will be partially updated on specific
|
|
directory changes, resulting in better performance.
|
|
|
|
Blacklist watching absolute directory paths via {ignore_dirs} and
|
|
optionally whitelist via {whitelist_dirs}:
|
|
• A table of |regular-expression| that will be passed to `vim.fn.match`
|
|
• Backslashes must be escaped e.g. `"my-proj/\\.build$"`
|
|
• Literal backslashes must be double escaped to avoid |/magic| e.g.
|
|
`"C:\\\\src\\\\my-proj"`
|
|
• OR a `fun(path: string): boolean` that is passed an absolute path:
|
|
• {ignore_dirs}: return `true` to disable
|
|
• {whitelist_dirs}: return `true` to enable
|
|
|
|
{whitelist_dirs} is STRONGLY recommended for windows:
|
|
|nvim-tree-os-specific|.
|
|
|
|
After {max_events} consecutive filesystem events on a single directory
|
|
with an interval < {debounce_delay}:
|
|
• The filesystem watcher will be disabled for that directory.
|
|
• A warning notification will be shown.
|
|
• Consider adding this directory to {ignore_dirs}
|
|
|
|
By default, {max_events} is only enabled for windows.
|
|
|
|
Fields: ~
|
|
• {debounce_delay}? (`integer`, default: `50`) Idle milliseconds
|
|
between filesystem change and tree update.
|
|
• {enable}? (`boolean`) (default: `true`)
|
|
• {ignore_dirs}? (`string[]|(fun(path: string): boolean)`, default: `{ "/.ccls-cache", "/build", "/node_modules", "/target", "/.zig-cache"}`)
|
|
Disable for specific directories.
|
|
• {max_events}? (`integer`, default: `0` or `1000` on windows)
|
|
Disable for a single directory after {max_events}
|
|
consecutive events with an interval <
|
|
{debounce_delay}. Set to 0 to allow unlimited
|
|
consecutive events.
|
|
• {whitelist_dirs}? (`string[]|(fun(path: string): boolean)`, default:
|
|
`{}`) Optionally enable only for specific
|
|
directories.
|
|
|
|
==============================================================================
|
|
Config: actions *nvim-tree-config-actions*
|
|
|
|
*nvim_tree.config.actions*
|
|
|
|
Fields: ~
|
|
• {change_dir}? (`nvim_tree.config.actions.change_dir`)
|
|
|nvim_tree.config.actions.change_dir|
|
|
• {expand_all}? (`nvim_tree.config.actions.expand_all`)
|
|
|nvim_tree.config.actions.expand_all|
|
|
• {file_popup}? (`nvim_tree.config.actions.file_popup`)
|
|
|nvim_tree.config.actions.file_popup|
|
|
• {open_file}? (`nvim_tree.config.actions.open_file`)
|
|
|nvim_tree.config.actions.open_file|
|
|
• {remove_file}? (`nvim_tree.config.actions.remove_file`)
|
|
|nvim_tree.config.actions.remove_file|
|
|
• {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 `"`
|
|
|
|
*nvim_tree.config.actions.change_dir*
|
|
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.expand_all*
|
|
Configure |nvim_tree.api.tree.expand_all()| and
|
|
|nvim_tree.api.node.expand()|
|
|
|
|
Fields: ~
|
|
• {exclude}? (`string[]`, default: `{}`) A list of
|
|
directories that should not be expanded
|
|
automatically e.g
|
|
`{ ".git", "target", "build" }`
|
|
• {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.
|
|
|
|
*nvim_tree.config.actions.file_popup*
|
|
{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.open_file*
|
|
Opening files.
|
|
|
|
Fields: ~
|
|
• {eject}? (`boolean`, default: `true`) Prevent new opened file
|
|
from opening in the same window as the tree.
|
|
• {quit_on_open}? (`boolean`, default: `false`) Closes the explorer
|
|
when opening a file
|
|
• {resize_window}? (`boolean`, default: `true`) Resizes the tree when
|
|
opening a file
|
|
• {window_picker}? (`nvim_tree.config.actions.open_file.window_picker`)
|
|
|nvim_tree.config.actions.open_file.window_picker|
|
|
|
|
*nvim_tree.config.actions.open_file.window_picker*
|
|
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: ~
|
|
• {chars}? (`string`, default:
|
|
`"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"`) Identifier
|
|
characters to use.
|
|
• {enable}? (`boolean`) (default: `true`)
|
|
• {exclude}? (`nvim_tree.config.actions.open_file.window_picker.exclude`)
|
|
|nvim_tree.config.actions.open_file.window_picker.exclude|
|
|
• {picker}? (`"default"|(fun(): integer)`, default: `"default"`)
|
|
Change the default window picker or define your own.
|
|
|
|
*nvim_tree.config.actions.open_file.window_picker.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: ~
|
|
• {buftype}? (`string[]`) (default:
|
|
`{ "nofile", "terminal", "help", }`)
|
|
• {filetype}? (`string[]`) (default:
|
|
`{ "notify", "lazy", "qf", "diff", "fugitive", "fugitiveblame", }`)
|
|
|
|
*nvim_tree.config.actions.remove_file*
|
|
Removing files.
|
|
|
|
Fields: ~
|
|
• {close_window}? (`boolean`, default: `true`) Close any window that
|
|
displays a file when removing that file from the
|
|
tree.
|
|
|
|
==============================================================================
|
|
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"`)
|
|
|
|
==============================================================================
|
|
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: ~
|
|
• {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`
|
|
• {open}? (`boolean`, default: `false`) Opens the tree automatically
|
|
when switching tabpage or opening a new tabpage if the tree
|
|
was previously open.
|
|
|
|
==============================================================================
|
|
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: ~
|
|
• {absolute_path}? (`boolean`, default: `true`) Use absolute paths in
|
|
FS action notifications, otherwise item names.
|
|
• {threshold}? (`vim.log.levels`, default: `vim.log.levels.INFO`)
|
|
Specify minimum notification |vim.log.levels|
|
|
|
|
==============================================================================
|
|
Config: bookmarks *nvim-tree-config-bookmarks*
|
|
|
|
*nvim_tree.config.bookmarks*
|
|
Optionally {persist} bookmarks to a json file:
|
|
• `true` use default: `stdpath("data") .. "/nvim-tree-bookmarks.json"`
|
|
• `false` do not persist
|
|
• `string` absolute path of your choice
|
|
|
|
Fields: ~
|
|
• {persist}? (`boolean|string`) (default: `false`)
|
|
|
|
==============================================================================
|
|
Config: help *nvim-tree-config-help*
|
|
|
|
*nvim_tree.config.help*
|
|
{sort_by} *nvim_tree.config.help.sort_by*
|
|
|
|
Sort help entries alphabetically by:
|
|
• `"key"`: map lhs
|
|
• `"desc"`: description
|
|
|
|
Fields: ~
|
|
• {sort_by}? (`nvim_tree.config.help.sort_by`) (default: `"key"`)
|
|
|
|
==============================================================================
|
|
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: ~
|
|
• {default_yes}? (`boolean`, default: `false`) If `true` the prompt
|
|
will be `Y/n`, otherwise `y/N`
|
|
• {remove}? (`boolean`, default: `true`) Prompt before removing.
|
|
• {trash}? (`boolean`, default: `true`) Prompt before trashing.
|
|
|
|
==============================================================================
|
|
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.
|
|
|
|
==============================================================================
|
|
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.
|
|
• {config}? (`boolean`, default: `false`) Config 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.
|
|
• {profile}? (`boolean`, default: `false`) Timing of some
|
|
operations.
|
|
• {watcher}? (`boolean`, default: `false`)
|
|
|nvim_tree.config.filesystem_watchers| processing,
|
|
verbose.
|
|
|
|
==============================================================================
|
|
Config: Default *nvim-tree-config-default*
|
|
|
|
Following is the default configuration, see |nvim_tree.config| for details. >lua
|
|
|
|
---@type nvim_tree.config
|
|
local config = {
|
|
on_attach = "default",
|
|
hijack_cursor = false,
|
|
auto_reload_on_write = true,
|
|
disable_netrw = false,
|
|
hijack_netrw = true,
|
|
hijack_unnamed_buffer_when_opening = false,
|
|
root_dirs = {},
|
|
prefer_startup_root = false,
|
|
sync_root_with_cwd = false,
|
|
reload_on_bufenter = false,
|
|
respect_buf_cwd = false,
|
|
select_prompts = false,
|
|
sort = {
|
|
sorter = "name",
|
|
folders_first = true,
|
|
files_first = false,
|
|
},
|
|
view = {
|
|
centralize_selection = false,
|
|
cursorline = true,
|
|
cursorlineopt = "both",
|
|
debounce_delay = 15,
|
|
side = "left",
|
|
preserve_window_proportions = false,
|
|
number = false,
|
|
relativenumber = false,
|
|
signcolumn = "yes",
|
|
width = 30,
|
|
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,
|
|
full_name = false,
|
|
root_folder_label = ":~:s?$?/..?",
|
|
indent_width = 2,
|
|
special_files = { "Cargo.toml", "Makefile", "README.md", "readme.md" },
|
|
hidden_display = "none",
|
|
symlink_destination = true,
|
|
decorators = { "Git", "Open", "Hidden", "Modified", "Bookmark", "Diagnostics", "Copied", "Cut", },
|
|
highlight_git = "none",
|
|
highlight_diagnostics = "none",
|
|
highlight_opened_files = "none",
|
|
highlight_modified = "none",
|
|
highlight_hidden = "none",
|
|
highlight_bookmarks = "none",
|
|
highlight_clipboard = "name",
|
|
indent_markers = {
|
|
enable = false,
|
|
inline_arrows = true,
|
|
icons = {
|
|
corner = "└",
|
|
edge = "│",
|
|
item = "│",
|
|
bottom = "─",
|
|
none = " ",
|
|
},
|
|
},
|
|
icons = {
|
|
web_devicons = {
|
|
file = {
|
|
enable = true,
|
|
color = true,
|
|
},
|
|
folder = {
|
|
enable = false,
|
|
color = true,
|
|
},
|
|
},
|
|
git_placement = "before",
|
|
modified_placement = "after",
|
|
hidden_placement = "after",
|
|
diagnostics_placement = "signcolumn",
|
|
bookmarks_placement = "signcolumn",
|
|
padding = {
|
|
icon = " ",
|
|
folder_arrow = " ",
|
|
},
|
|
symlink_arrow = " ➛ ",
|
|
show = {
|
|
file = true,
|
|
folder = true,
|
|
folder_arrow = true,
|
|
git = true,
|
|
modified = true,
|
|
hidden = false,
|
|
diagnostics = true,
|
|
bookmarks = true,
|
|
},
|
|
glyphs = {
|
|
default = "",
|
|
symlink = "",
|
|
bookmark = "",
|
|
modified = "●",
|
|
hidden = "",
|
|
folder = {
|
|
arrow_closed = "",
|
|
arrow_open = "",
|
|
default = "",
|
|
open = "",
|
|
empty = "",
|
|
empty_open = "",
|
|
symlink = "",
|
|
symlink_open = "",
|
|
},
|
|
git = {
|
|
unstaged = "✗",
|
|
staged = "✓",
|
|
unmerged = "",
|
|
renamed = "➜",
|
|
untracked = "★",
|
|
deleted = "",
|
|
ignored = "◌",
|
|
},
|
|
},
|
|
},
|
|
},
|
|
hijack_directories = {
|
|
enable = true,
|
|
auto_open = true,
|
|
},
|
|
update_focused_file = {
|
|
enable = false,
|
|
update_root = {
|
|
enable = false,
|
|
ignore_list = {},
|
|
},
|
|
exclude = false,
|
|
},
|
|
git = {
|
|
enable = true,
|
|
show_on_dirs = true,
|
|
show_on_open_dirs = true,
|
|
disable_for_dirs = {},
|
|
timeout = 400,
|
|
cygwin_support = false,
|
|
},
|
|
diagnostics = {
|
|
enable = false,
|
|
show_on_dirs = false,
|
|
show_on_open_dirs = true,
|
|
debounce_delay = 500,
|
|
severity = {
|
|
min = vim.diagnostic.severity.HINT,
|
|
max = vim.diagnostic.severity.ERROR,
|
|
},
|
|
icons = {
|
|
hint = "",
|
|
info = "",
|
|
warning = "",
|
|
error = "",
|
|
},
|
|
diagnostic_opts = false,
|
|
},
|
|
modified = {
|
|
enable = false,
|
|
show_on_dirs = true,
|
|
show_on_open_dirs = true,
|
|
},
|
|
filters = {
|
|
enable = true,
|
|
git_ignored = true,
|
|
dotfiles = false,
|
|
git_clean = false,
|
|
no_buffer = false,
|
|
no_bookmark = false,
|
|
custom = {},
|
|
exclude = {},
|
|
},
|
|
live_filter = {
|
|
prefix = "[FILTER]: ",
|
|
always_show_folders = true,
|
|
},
|
|
filesystem_watchers = {
|
|
enable = true,
|
|
debounce_delay = 50,
|
|
max_events = 0,
|
|
ignore_dirs = {
|
|
"/.ccls-cache",
|
|
"/build",
|
|
"/node_modules",
|
|
"/target",
|
|
"/.zig-cache",
|
|
},
|
|
whitelist_dirs = {},
|
|
},
|
|
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,
|
|
relative_path = 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",
|
|
},
|
|
tab = {
|
|
sync = {
|
|
open = false,
|
|
close = false,
|
|
ignore = {},
|
|
},
|
|
},
|
|
notify = {
|
|
threshold = vim.log.levels.INFO,
|
|
absolute_path = true,
|
|
},
|
|
help = {
|
|
sort_by = "key",
|
|
},
|
|
ui = {
|
|
confirm = {
|
|
remove = true,
|
|
trash = true,
|
|
default_yes = false,
|
|
},
|
|
},
|
|
bookmarks = {
|
|
persist = false,
|
|
},
|
|
experimental = {
|
|
},
|
|
log = {
|
|
enable = false,
|
|
truncate = false,
|
|
types = {
|
|
all = false,
|
|
config = false,
|
|
copy_paste = false,
|
|
dev = false,
|
|
diagnostics = false,
|
|
git = false,
|
|
profile = false,
|
|
watcher = false,
|
|
},
|
|
},
|
|
}
|
|
<
|
|
|
|
==============================================================================
|
|
API *nvim-tree-api*
|
|
|
|
nvim-tree exposes a public API. This is non breaking, with additions made as
|
|
necessary.
|
|
|
|
Please do not require or use modules other than `nvim-tree.api`, as internal
|
|
modules will change without notice.
|
|
|
|
The API is separated into multiple modules:
|
|
• |nvim-tree-api-appearance|
|
|
• |nvim-tree-api-commands|
|
|
• |nvim-tree-api-events|
|
|
• |nvim-tree-api-filter|
|
|
• |nvim-tree-api-fs|
|
|
• |nvim-tree-api-git|
|
|
• |nvim-tree-api-map|
|
|
• |nvim-tree-api-marks|
|
|
• |nvim-tree-api-node|
|
|
• |nvim-tree-api-tree|
|
|
|
|
Modules are accessed via `api.<module>.<function>`
|
|
|
|
Example invocation of the `reload` function in the `tree` module: >lua
|
|
|
|
local api = require("nvim-tree.api")
|
|
api.tree.reload()
|
|
<
|
|
|
|
Generally, functions accepting a |nvim_tree.api.Node| as their first argument
|
|
will use the node under the cursor when that argument is not present or nil.
|
|
Some functions are mode-dependent: when invoked in visual mode they will
|
|
operate on all nodes in the visual selection instead of a single node. See
|
|
|nvim-tree-mappings-default| for which mappings support visual mode.
|
|
|
|
e.g. the following are functionally identical: >lua
|
|
|
|
api.node.open.edit(nil, { focus = true })
|
|
|
|
api.node.open.edit(api.tree.get_node_under_cursor(), { focus = true })
|
|
<
|
|
|
|
|
|
*nvim_tree.api.Node*
|
|
The Node class is a data class. Instances may be provided by API functions
|
|
for use as a:
|
|
• handle to pass back to API functions e.g. |nvim_tree.api.node.run.cmd()|
|
|
• reference in callbacks e.g. |nvim_tree.config.sort.Sorter| {sorter}
|
|
|
|
Please do not mutate the contents of any Node object.
|
|
|
|
Fields: ~
|
|
• {absolute_path} (`string`) of the file or directory
|
|
• {diag_severity}? (`lsp.DiagnosticSeverity`) diagnostic status
|
|
• {executable} (`boolean`) file is executable
|
|
• {fs_stat}? (`uv.fs_stat.result`) at time of last tree display,
|
|
see |uv.fs_stat()|
|
|
• {git_status} (`nvim_tree.git.Status?`) for files and directories
|
|
• {hidden} (`boolean`) node is not visible in the tree
|
|
• {name} (`string`) file or directory name
|
|
• {parent}? (`nvim_tree.api.DirectoryNode`) parent directory,
|
|
nil for root
|
|
• {type} (`"file"|"directory"|"link"`) |uv.fs_stat()| {type}
|
|
|
|
*nvim_tree.git.Status*
|
|
Git statuses for a single node.
|
|
|
|
`nvim_tree.git.XY`: 2 character string, see `man 1 git-status` "Short
|
|
Format"
|
|
|
|
{dir} status is derived from its contents:
|
|
• `direct`: inherited from child files
|
|
• `indirect`: inherited from child directories
|
|
|
|
Fields: ~
|
|
• {dir}? (`table<"direct"|"indirect", nvim_tree.git.XY[]>`) direct
|
|
inclusive-or indirect status
|
|
• {file}? (`nvim_tree.git.XY`) status of a file node
|
|
|
|
==============================================================================
|
|
API: appearance *nvim-tree-api-appearance*
|
|
|
|
hi_test() *nvim_tree.api.appearance.hi_test()*
|
|
Open a new buffer displaying all nvim-tree highlight groups, their link
|
|
chain and concrete definition.
|
|
|
|
Similar to `:so $VIMRUNTIME/syntax/hitest.vim` as per |:highlight|
|
|
|
|
|
|
==============================================================================
|
|
API: commands *nvim-tree-api-commands*
|
|
|
|
get() *nvim_tree.api.commands.get()*
|
|
Retrieve all |nvim-tree-commands|
|
|
|
|
They have been created via |nvim_create_user_command()|, see also
|
|
|lua-guide-commands-create|
|
|
|
|
Return: ~
|
|
(`table[]`)
|
|
• {command}
|
|
(`fun(args: vim.api.keyset.create_user_command.command_args)`)
|
|
function that the command will execute
|
|
• {name} (`string`) name of the `:NvimTree*` command
|
|
• {opts} (`vim.api.keyset.user_command`) |command-attributes|
|
|
|
|
|
|
==============================================================================
|
|
API: config *nvim-tree-api-config*
|
|
|
|
default() *nvim_tree.api.config.default()*
|
|
Default nvim-tree config.
|
|
|
|
Return: ~
|
|
(`nvim_tree.config`) immutable deep clone
|
|
|
|
global() *nvim_tree.api.config.global()*
|
|
Global current nvim-tree config.
|
|
|
|
Return: ~
|
|
(`nvim_tree.config`) immutable deep clone
|
|
|
|
user() *nvim_tree.api.config.user()*
|
|
Reference to config passed to |nvim-tree-setup|
|
|
|
|
Return: ~
|
|
(`nvim_tree.config?`) nil when no config passed to setup
|
|
|
|
|
|
==============================================================================
|
|
API: events *nvim-tree-api-events*
|
|
|
|
subscribe({event_type}, {callback}) *nvim_tree.api.events.subscribe()*
|
|
Register a handler for an event, see |nvim-tree-events|.
|
|
|
|
Parameters: ~
|
|
• {event_type} (`nvim_tree.api.events.Event`) |nvim_tree_events_kind|
|
|
• {callback} (`fun(payload: table?)`)
|
|
|
|
|
|
==============================================================================
|
|
API: filter *nvim-tree-api-filter*
|
|
|
|
custom.toggle() *nvim_tree.api.filter.custom.toggle()*
|
|
Toggle |nvim_tree.config.filters| {custom} filter.
|
|
|
|
dotfiles.toggle() *nvim_tree.api.filter.dotfiles.toggle()*
|
|
Toggle |nvim_tree.config.filters| {dotfiles} filter.
|
|
|
|
git.clean.toggle() *nvim_tree.api.filter.git.clean.toggle()*
|
|
Toggle |nvim_tree.config.filters| {git_clean} filter.
|
|
|
|
git.ignored.toggle() *nvim_tree.api.filter.git.ignored.toggle()*
|
|
Toggle |nvim_tree.config.filters| {git_ignored} filter.
|
|
|
|
live.clear() *nvim_tree.api.filter.live.clear()*
|
|
Exit live filter mode.
|
|
|
|
live.start() *nvim_tree.api.filter.live.start()*
|
|
Enter live filter mode. Opens an input window with |filetype|
|
|
`NvimTreeFilter`
|
|
|
|
no_bookmark.toggle() *nvim_tree.api.filter.no_bookmark.toggle()*
|
|
Toggle |nvim_tree.config.filters| {no_bookmark} filter.
|
|
|
|
no_buffer.toggle() *nvim_tree.api.filter.no_buffer.toggle()*
|
|
Toggle |nvim_tree.config.filters| {no_buffer} filter.
|
|
|
|
toggle() *nvim_tree.api.filter.toggle()*
|
|
Toggle |nvim_tree.config.filters| {enable} which applies to ALL filters.
|
|
|
|
|
|
==============================================================================
|
|
API: fs *nvim-tree-api-fs*
|
|
|
|
clear_clipboard() *nvim_tree.api.fs.clear_clipboard()*
|
|
Clear the nvim-tree clipboard.
|
|
|
|
copy.absolute_path({node}) *nvim_tree.api.fs.copy.absolute_path()*
|
|
Copy the absolute path to the system clipboard.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`)
|
|
|
|
copy.basename({node}) *nvim_tree.api.fs.copy.basename()*
|
|
Copy the name with extension omitted to the system clipboard.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`)
|
|
|
|
copy.filename({node}) *nvim_tree.api.fs.copy.filename()*
|
|
Copy the name to the system clipboard.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`)
|
|
|
|
copy.node({node}) *nvim_tree.api.fs.copy.node()*
|
|
Copy to the nvim-tree clipboard. In visual mode, copies all nodes in the
|
|
visual selection.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`)
|
|
|
|
copy.relative_path({node}) *nvim_tree.api.fs.copy.relative_path()*
|
|
Copy the path relative to the tree root to the system clipboard.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`)
|
|
|
|
create({node}) *nvim_tree.api.fs.create()*
|
|
Prompt to create a file or directory.
|
|
|
|
When {node} is a file it will be created in the parent directory.
|
|
|
|
Use a trailing `"/"` to create a directory e.g. `"foo/"`
|
|
|
|
Multiple directories/files may be created e.g. `"foo/bar/baz"`
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`)
|
|
|
|
cut({node}) *nvim_tree.api.fs.cut()*
|
|
Cut to the nvim-tree clipboard. In visual mode, cuts all nodes in the
|
|
visual selection.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`)
|
|
|
|
move({node}) *nvim_tree.api.fs.move()*
|
|
Paste while cutting files from:
|
|
• current nvim-tree clipboard (if present)
|
|
• another nvim-tree instance via system clipboard
|
|
|
|
If {node} is a file it will pasted in the parent directory.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`)
|
|
|
|
paste({node}) *nvim_tree.api.fs.paste()*
|
|
Paste files from:
|
|
• current nvim-tree clipboard (if present)
|
|
• another nvim-tree instance via system clipboard
|
|
|
|
If {node} is a file it will pasted in the parent directory.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`)
|
|
|
|
print_clipboard() *nvim_tree.api.fs.print_clipboard()*
|
|
Print the contents of the nvim-tree clipboard.
|
|
|
|
remove({node}) *nvim_tree.api.fs.remove()*
|
|
Delete from the file system. In visual mode, deletes all nodes in the
|
|
visual selection with a single prompt.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`)
|
|
|
|
rename({node}) *nvim_tree.api.fs.rename()*
|
|
Prompt to rename by name.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`)
|
|
|
|
rename_basename({node}) *nvim_tree.api.fs.rename_basename()*
|
|
Prompt to rename by name with extension omitted.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`)
|
|
|
|
rename_full({node}) *nvim_tree.api.fs.rename_full()*
|
|
Prompt to rename by absolute path.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`)
|
|
|
|
rename_node({node}) *nvim_tree.api.fs.rename_node()*
|
|
Prompt to rename.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`)
|
|
|
|
rename_sub({node}) *nvim_tree.api.fs.rename_sub()*
|
|
Prompt to rename by absolute path with name omitted.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`)
|
|
|
|
trash({node}) *nvim_tree.api.fs.trash()*
|
|
Trash as per |nvim_tree.config.trash|. In visual mode, trashes all nodes
|
|
in the visual selection with a single prompt.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`)
|
|
|
|
|
|
==============================================================================
|
|
API: git *nvim-tree-api-git*
|
|
|
|
reload() *nvim_tree.api.git.reload()*
|
|
Update the git status of the entire tree.
|
|
|
|
|
|
==============================================================================
|
|
API: map *nvim-tree-api-map*
|
|
|
|
keymap.current() *nvim_tree.api.map.keymap.current()*
|
|
Retrieve all buffer local mappings for nvim-tree. These are the mappings
|
|
that are applied by |nvim_tree.config| {on_attach}, which may include
|
|
default mappings.
|
|
|
|
Return: ~
|
|
(`vim.api.keyset.get_keymap[]`)
|
|
|
|
keymap.default() *nvim_tree.api.map.keymap.default()*
|
|
Retrieves the buffer local mappings for nvim-tree that are applied by
|
|
|nvim_tree.api.map.on_attach.default()|
|
|
|
|
Return: ~
|
|
(`vim.api.keyset.get_keymap[]`)
|
|
|
|
on_attach.default({bufnr}) *nvim_tree.api.map.on_attach.default()*
|
|
Apply all |nvim-tree-mappings-default|. Call from your |nvim_tree.config|
|
|
{on_attach}.
|
|
|
|
Parameters: ~
|
|
• {bufnr} (`integer`) use the `bufnr` passed to {on_attach}
|
|
|
|
|
|
==============================================================================
|
|
API: marks *nvim-tree-api-marks*
|
|
|
|
bulk.delete() *nvim_tree.api.marks.bulk.delete()*
|
|
Delete all marked, prompting if |nvim_tree.config.ui.confirm| {remove}
|
|
|
|
bulk.move() *nvim_tree.api.marks.bulk.move()*
|
|
Prompts for a directory to move all marked nodes into.
|
|
|
|
bulk.trash() *nvim_tree.api.marks.bulk.trash()*
|
|
Delete all marked, prompting if |nvim_tree.config.ui.confirm| {trash}
|
|
|
|
clear() *nvim_tree.api.marks.clear()*
|
|
Clear all marks.
|
|
|
|
get({node}) *nvim_tree.api.marks.get()*
|
|
Return the node if it is marked.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) file or directory
|
|
|
|
Return: ~
|
|
(`nvim_tree.api.Node?`)
|
|
|
|
list() *nvim_tree.api.marks.list()*
|
|
Retrieve all marked nodes.
|
|
|
|
Return: ~
|
|
(`nvim_tree.api.Node[]`)
|
|
|
|
navigate.next() *nvim_tree.api.marks.navigate.next()*
|
|
Navigate to the next marked node, wraps.
|
|
|
|
navigate.prev() *nvim_tree.api.marks.navigate.prev()*
|
|
Navigate to the previous marked node, wraps.
|
|
|
|
navigate.select() *nvim_tree.api.marks.navigate.select()*
|
|
Prompts for selection of a marked node, sorted by absolute paths. A folder
|
|
will be focused, a file will be opened.
|
|
|
|
toggle({node}) *nvim_tree.api.marks.toggle()*
|
|
Toggle mark. In visual mode, toggles all nodes in the visual selection.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) file or directory
|
|
|
|
|
|
==============================================================================
|
|
API: node *nvim-tree-api-node*
|
|
|
|
buffer.delete({node}, {opts}) *nvim_tree.api.node.buffer.delete()*
|
|
Deletes node's related buffer, if one exists. Executes |:bdelete| or
|
|
|:bdelete|!
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) file
|
|
• {opts} (`table?`)
|
|
• {force}? (`boolean`, default: false) Proceed even if the
|
|
buffer is modified.
|
|
|
|
buffer.wipe({node}, {opts}) *nvim_tree.api.node.buffer.wipe()*
|
|
Wipes node's related buffer, if one exists. Executes |:bwipe| or |:bwipe|!
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) file
|
|
• {opts} (`table?`) optional
|
|
• {force}? (`boolean`, default: false) Proceed even if the
|
|
buffer is modified.
|
|
|
|
collapse({node}, {opts}) *nvim_tree.api.node.collapse()*
|
|
Collapse the tree under a directory or a file's parent directory.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
• {opts} (`table?`) optional
|
|
• {keep_buffers}? (`boolean`, default: false) Do not collapse
|
|
nodes with open buffers.
|
|
|
|
expand({node}, {opts}) *nvim_tree.api.node.expand()*
|
|
Recursively expand all nodes under a directory or a file's parent
|
|
directory.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
• {opts} (`table?`) optional
|
|
• {expand_until}?
|
|
(`fun(expansion_count: integer, node: Node): boolean`)
|
|
Return `true` if `node` should be expanded.
|
|
`expansion_count` is the total number of folders expanded.
|
|
|
|
*nvim_tree.api.node.navigate.diagnostics.next()*
|
|
navigate.diagnostics.next({node})
|
|
Navigate to the next item showing diagnostic status.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
|
|
*nvim_tree.api.node.navigate.diagnostics.next_recursive()*
|
|
navigate.diagnostics.next_recursive({node})
|
|
Navigate to the next item showing diagnostic status, recursively. Needs
|
|
|nvim_tree.config.diagnostics| {show_on_dirs}
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
|
|
*nvim_tree.api.node.navigate.diagnostics.prev()*
|
|
navigate.diagnostics.prev({node})
|
|
Navigate to the previous item showing diagnostic status.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
|
|
*nvim_tree.api.node.navigate.diagnostics.prev_recursive()*
|
|
navigate.diagnostics.prev_recursive({node})
|
|
Navigate to the previous item showing diagnostic status, recursively.
|
|
Needs |nvim_tree.config.diagnostics| {show_on_dirs}
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
|
|
navigate.git.next({node}) *nvim_tree.api.node.navigate.git.next()*
|
|
Navigate to the next item showing git status.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
|
|
*nvim_tree.api.node.navigate.git.next_recursive()*
|
|
navigate.git.next_recursive({node})
|
|
Navigate to the next item showing git status, recursively. Needs
|
|
|nvim_tree.config.git| {show_on_dirs}
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
|
|
*nvim_tree.api.node.navigate.git.next_skip_gitignored()*
|
|
navigate.git.next_skip_gitignored({node})
|
|
Navigate to the next item showing git status, skipping `.gitignore`
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
|
|
navigate.git.prev({node}) *nvim_tree.api.node.navigate.git.prev()*
|
|
Navigate to the previous item showing git status.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
|
|
*nvim_tree.api.node.navigate.git.prev_recursive()*
|
|
navigate.git.prev_recursive({node})
|
|
Navigate to the previous item showing git status, recursively. Needs
|
|
|nvim_tree.config.git| {show_on_dirs}
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
|
|
*nvim_tree.api.node.navigate.git.prev_skip_gitignored()*
|
|
navigate.git.prev_skip_gitignored({node})
|
|
Navigate to the previous item showing git status, skipping `.gitignore`
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
|
|
*nvim_tree.api.node.navigate.opened.next()*
|
|
navigate.opened.next({node})
|
|
Navigate to the next |bufloaded()| file.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
|
|
*nvim_tree.api.node.navigate.opened.prev()*
|
|
navigate.opened.prev({node})
|
|
Navigate to the previous |bufloaded()| file.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
|
|
navigate.parent({node}) *nvim_tree.api.node.navigate.parent()*
|
|
Navigate to the parent directory of the node.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
|
|
*nvim_tree.api.node.navigate.parent_close()*
|
|
navigate.parent_close({node})
|
|
Navigate to the parent directory of the node, closing it.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
|
|
*nvim_tree.api.node.navigate.sibling.first()*
|
|
navigate.sibling.first({node})
|
|
Navigate to the first node in the current node's folder.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
|
|
*nvim_tree.api.node.navigate.sibling.last()*
|
|
navigate.sibling.last({node})
|
|
Navigate to the last node in the current node's folder.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
|
|
*nvim_tree.api.node.navigate.sibling.next()*
|
|
navigate.sibling.next({node})
|
|
Navigate to the next node in the current node's folder, wraps.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
|
|
*nvim_tree.api.node.navigate.sibling.prev()*
|
|
navigate.sibling.prev({node})
|
|
Navigate to the previous node in the current node's folder, wraps.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
|
|
open.drop({node}) *nvim_tree.api.node.open.drop()*
|
|
Switch to window with selected file if it exists, otherwise open, see
|
|
|:drop|
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
|
|
open.edit({node}, {opts}) *nvim_tree.api.node.open.edit()*
|
|
• file: open as per |nvim_tree.config.actions.open_file|
|
|
• directory: expand or collapse
|
|
• root: change directory up
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
• {opts} (`table?`) optional
|
|
• {focus}? (`boolean`, default: false) Keep focus in the tree
|
|
when opening the file.
|
|
• {quit_on_open}? (`boolean`, default: false) Quits the tree
|
|
when opening the file.
|
|
|
|
open.horizontal({node}, {opts}) *nvim_tree.api.node.open.horizontal()*
|
|
Open file in a new horizontal split.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) file
|
|
• {opts} (`table?`) optional
|
|
• {focus}? (`boolean`, default: false) Keep focus in the tree
|
|
when opening the file.
|
|
• {quit_on_open}? (`boolean`, default: false) Quits the tree
|
|
when opening the file.
|
|
|
|
*nvim_tree.api.node.open.horizontal_no_picker()*
|
|
open.horizontal_no_picker({node}, {opts})
|
|
Open file in a new horizontal split without using the window picker.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) file
|
|
• {opts} (`table?`) optional
|
|
• {focus}? (`boolean`, default: false) Keep focus in the tree
|
|
when opening the file.
|
|
• {quit_on_open}? (`boolean`, default: false) Quits the tree
|
|
when opening the file.
|
|
|
|
*nvim_tree.api.node.open.no_window_picker()*
|
|
open.no_window_picker({node}, {opts})
|
|
Open file without using the window picker.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) file
|
|
• {opts} (`table?`) optional
|
|
• {focus}? (`boolean`, default: false) Keep focus in the tree
|
|
when opening the file.
|
|
• {quit_on_open}? (`boolean`, default: false) Quits the tree
|
|
when opening the file.
|
|
|
|
open.preview({node}, {opts}) *nvim_tree.api.node.open.preview()*
|
|
Open file with |'bufhidden'| set to `delete`.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
• {opts} (`table?`) optional
|
|
• {focus}? (`boolean`, default: false) Keep focus in the tree
|
|
when opening the file.
|
|
• {quit_on_open}? (`boolean`, default: false) Quits the tree
|
|
when opening the file.
|
|
|
|
*nvim_tree.api.node.open.preview_no_picker()*
|
|
open.preview_no_picker({node}, {opts})
|
|
Open file with |'bufhidden'| set to `delete` without using the window
|
|
picker.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
• {opts} (`table?`) optional
|
|
• {focus}? (`boolean`, default: false) Keep focus in the tree
|
|
when opening the file.
|
|
• {quit_on_open}? (`boolean`, default: false) Quits the tree
|
|
when opening the file.
|
|
|
|
*nvim_tree.api.node.open.replace_tree_buffer()*
|
|
open.replace_tree_buffer({node})
|
|
Open file in place: in the nvim-tree window.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) file
|
|
|
|
open.tab({node}, {opts}) *nvim_tree.api.node.open.tab()*
|
|
Open file in a new tab.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
• {opts} (`table?`) optional
|
|
• {focus}? (`boolean`, default: false) Keep focus in the tree
|
|
when opening the file.
|
|
• {quit_on_open}? (`boolean`, default: false) Quits the tree
|
|
when opening the file.
|
|
|
|
open.tab_drop({node}) *nvim_tree.api.node.open.tab_drop()*
|
|
Switch to tab containing window with selected file if it exists, otherwise
|
|
open in new tab, see |:drop|
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
|
|
*nvim_tree.api.node.open.toggle_group_empty()*
|
|
open.toggle_group_empty({node})
|
|
Toggle |nvim_tree.config.renderer| {group_empty} for a directory. Needs
|
|
{group_empty} set.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory
|
|
|
|
open.vertical({node}, {opts}) *nvim_tree.api.node.open.vertical()*
|
|
Open file in a new vertical split.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) file
|
|
• {opts} (`table?`) optional
|
|
• {focus}? (`boolean`, default: false) Keep focus in the tree
|
|
when opening the file.
|
|
• {quit_on_open}? (`boolean`, default: false) Quits the tree
|
|
when opening the file.
|
|
|
|
*nvim_tree.api.node.open.vertical_no_picker()*
|
|
open.vertical_no_picker({node}, {opts})
|
|
Open file in a new vertical split without using the window picker.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) file
|
|
• {opts} (`table?`) optional
|
|
• {focus}? (`boolean`, default: false) Keep focus in the tree
|
|
when opening the file.
|
|
• {quit_on_open}? (`boolean`, default: false) Quits the tree
|
|
when opening the file.
|
|
|
|
run.cmd({node}) *nvim_tree.api.node.run.cmd()*
|
|
Enter |cmdline| with the full path of the node and the cursor at the start
|
|
of the line.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
|
|
run.system({node}) *nvim_tree.api.node.run.system()*
|
|
Open with the system default handler: |vim.ui.open()|.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
|
|
show_info_popup({node}) *nvim_tree.api.node.show_info_popup()*
|
|
Open a popup window showing: fullpath, size, accessed, modified, created.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
|
|
|
|
==============================================================================
|
|
API: tree *nvim-tree-api-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.
|
|
|
|
change_root_to_node({node}) *nvim_tree.api.tree.change_root_to_node()*
|
|
Change the tree's root to a folder node or the parent of a file node.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
|
|
*nvim_tree.api.tree.change_root_to_parent()*
|
|
change_root_to_parent({node})
|
|
Change the tree's root to the parent of a node.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory or file
|
|
|
|
close() *nvim_tree.api.tree.close()*
|
|
Close the tree, affecting all tabs as per |nvim_tree.config.tab.sync|
|
|
{close}
|
|
|
|
close_in_all_tabs() *nvim_tree.api.tree.close_in_all_tabs()*
|
|
Close the tree in all tabs.
|
|
|
|
close_in_this_tab() *nvim_tree.api.tree.close_in_this_tab()*
|
|
Close the tree in this tab only.
|
|
|
|
collapse_all({opts}) *nvim_tree.api.tree.collapse_all()*
|
|
Collapse the tree.
|
|
|
|
Parameters: ~
|
|
• {opts} (`table?`) optional
|
|
• {keep_buffers}? (`boolean`, default: false) Do not collapse
|
|
nodes with open buffers.
|
|
|
|
expand_all({node}, {opts}) *nvim_tree.api.tree.expand_all()*
|
|
Recursively expand all nodes under the tree root or specified folder.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node?`) directory
|
|
• {opts} (`table?`) optional
|
|
• {expand_until}?
|
|
(`fun(expansion_count: integer, node: Node): boolean`)
|
|
Return `true` if `node` should be expanded.
|
|
`expansion_count` is the total number of folders expanded.
|
|
|
|
find_file({opts}) *nvim_tree.api.tree.find_file()*
|
|
Find and focus a file or folder in the tree. Finds current buffer unless
|
|
otherwise specified.
|
|
|
|
Parameters: ~
|
|
• {opts} (`table?`) optional
|
|
• {buf}? (`string|integer`) Absolute/relative path OR `bufnr`
|
|
to find.
|
|
• {current_window}? (`boolean`, default: false) Requires
|
|
{open}: open in the current window.
|
|
• {focus}? (`boolean`, default: false) Focus the tree window.
|
|
• {open}? (`boolean`, default: false) Open the tree if
|
|
necessary.
|
|
• {update_root}? (`boolean`, default: false) Update root after
|
|
find, see |nvim_tree.config.update_focused_file|
|
|
{update_root}
|
|
• {winid}? (`integer`) Open the tree in the specified
|
|
|window-ID|, overrides {current_window}
|
|
|
|
focus() *nvim_tree.api.tree.focus()*
|
|
Focus the tree, opening it if necessary. Retained for compatibility, use
|
|
|nvim_tree.api.tree.open()| with no arguments instead.
|
|
|
|
get_node_under_cursor() *nvim_tree.api.tree.get_node_under_cursor()*
|
|
Retrieve the currently focused node.
|
|
|
|
Return: ~
|
|
(`nvim_tree.api.Node?`) nil if tree is not visible.
|
|
|
|
get_nodes() *nvim_tree.api.tree.get_nodes()*
|
|
Retrieve a hierarchical list of all the nodes.
|
|
|
|
Return: ~
|
|
(`nvim_tree.api.Node[]`)
|
|
|
|
is_tree_buf({bufnr}) *nvim_tree.api.tree.is_tree_buf()*
|
|
Checks if a buffer is an nvim-tree.
|
|
|
|
Parameters: ~
|
|
• {bufnr} (`integer?`) 0 or nil for current buffer.
|
|
|
|
Return: ~
|
|
(`boolean`)
|
|
|
|
is_visible({opts}) *nvim_tree.api.tree.is_visible()*
|
|
Checks if nvim-tree is visible on the current, specified or any tab.
|
|
|
|
Parameters: ~
|
|
• {opts} (`table?`) optional
|
|
• {any_tabpage}? (`boolean`, default: false) Visible on any
|
|
tab.
|
|
• {tabpage}? (`integer`) |tab-ID| 0 or nil for current.
|
|
|
|
Return: ~
|
|
(`boolean`)
|
|
|
|
open({opts}) *nvim_tree.api.tree.open()*
|
|
Open the tree, focusing it if already open.
|
|
|
|
Parameters: ~
|
|
• {opts} (`table?`) optional
|
|
• {current_window}? (`boolean`, default: false) Open the tree
|
|
in the current window
|
|
• {find_file}? (`boolean`, default: false) Find the current
|
|
buffer.
|
|
• {path}? (`string`) Root directory for the tree
|
|
• {update_root}? (`boolean`, default: false) Update root
|
|
following {find_file}, see
|
|
|nvim_tree.config.update_focused_file| {update_root}
|
|
• {winid}? (`integer`) Open the tree in the specified
|
|
|window-ID|, overrides {current_window}
|
|
|
|
reload() *nvim_tree.api.tree.reload()*
|
|
Refresh the tree. Does nothing if closed.
|
|
|
|
resize({opts}) *nvim_tree.api.tree.resize()*
|
|
Resize the tree, persisting the new size. Resets to
|
|
|nvim_tree.config.view| {width} when no {opts} provided.
|
|
|
|
Only one option is supported, priority order: {width}, {absolute},
|
|
{relative}.
|
|
|
|
{absolute} and {relative} do nothing when |nvim_tree.config.view| {width}
|
|
is a function.
|
|
|
|
Parameters: ~
|
|
• {opts} (`table?`) optional
|
|
• {absolute}? (`integer`) Set the width.
|
|
• {relative}? (`integer`) Increase or decrease the width.
|
|
• {width}?
|
|
(`nvim_tree.config.view.width.spec|nvim_tree.config.view.width`)
|
|
New |nvim_tree.config.view| {width} value.
|
|
|
|
search_node() *nvim_tree.api.tree.search_node()*
|
|
Open the search dialogue.
|
|
|
|
toggle({opts}) *nvim_tree.api.tree.toggle()*
|
|
Open or close the tree.
|
|
|
|
Parameters: ~
|
|
• {opts} (`table?`) optional
|
|
• {current_window}? (`boolean`, default: false) Open the tree
|
|
in the current window
|
|
• {find_file}? (`boolean`, default: false) Find the current
|
|
buffer.
|
|
• {focus}? (`boolean`, default: true) Focus the tree when
|
|
opening.
|
|
• {path}? (`string`) Root directory for the tree
|
|
• {update_root}? (`boolean`, default: false) Update root
|
|
following {find_file}, see
|
|
|nvim_tree.config.update_focused_file| {update_root}
|
|
• {winid}? (`integer`) Open the tree in the specified
|
|
|window-ID|, overrides {current_window}
|
|
|
|
toggle_help() *nvim_tree.api.tree.toggle_help()*
|
|
Toggle help view.
|
|
|
|
winid({opts}) *nvim_tree.api.tree.winid()*
|
|
Retrieve the window of the open tree.
|
|
|
|
Parameters: ~
|
|
• {opts} (`table?`) optional
|
|
• {tabpage}? (`integer`) |tab-ID| 0 or nil for current.
|
|
|
|
Return: ~
|
|
(`integer?`) |window-ID|, nil if tree is not visible.
|
|
|
|
|
|
==============================================================================
|
|
Class: Class *nvim-tree-class*
|
|
|
|
nvim-tree uses the https://github.com/rxi/classic class framework adding safe
|
|
casts, instanceof mixin and conventional destructors.
|
|
|
|
The key differences between classic and ordinary Lua classes:
|
|
• The constructor |nvim_tree.Class:new()| is not responsible for allocation:
|
|
`self` is available when the constructor is called.
|
|
• Instances are constructed via the `__call` meta method: `SomeClass(args)`
|
|
|
|
Classes are conventionally named using camel case e.g. `MyClass`
|
|
|
|
Classes are created by extending another class: >lua
|
|
|
|
local Class = require("nvim-tree.classic")
|
|
|
|
---@class (exact) Fruit: nvim_tree.Class
|
|
---@field ...
|
|
local Fruit = Class:extend()
|
|
|
|
---@class (exact) Apple: Fruit
|
|
---@field ...
|
|
local Apple = Fruit:extend()
|
|
<
|
|
|
|
Implementing a constructor |nvim_tree.Class:new()| is optional, however it
|
|
must call the `super` constructor: >lua
|
|
|
|
---@protected
|
|
---@param args AppleArgs
|
|
function Apple:new(args)
|
|
|
|
---@type FruitArgs
|
|
local fruit_args = ...
|
|
|
|
Apple.super.new(self, fruit_args)
|
|
---
|
|
<
|
|
|
|
Create an instance of a class using the `__call` meta method that will invoke
|
|
the constructor: >lua
|
|
|
|
---@type AppleArgs
|
|
local args = ...
|
|
|
|
local an_apple = Apple(args)
|
|
-- above will call `Apple:new(args)`
|
|
<
|
|
|
|
In order to strongly type instantiation, the following pattern is used to type
|
|
the meta method `__call` with arguments and return: >lua
|
|
|
|
---@class (exact) Fruit: nvim_tree.Class
|
|
---@field ...
|
|
local Fruit = Class:extend()
|
|
|
|
---@class (exact) FruitArgs
|
|
---@field ...
|
|
|
|
---@class Fruit
|
|
---@overload fun(args: FruitArgs): Fruit
|
|
|
|
---@protected
|
|
---@param args FruitArgs
|
|
function Fruit:new(args)
|
|
<
|
|
|
|
|
|
*nvim_tree.Class*
|
|
|
|
Fields: ~
|
|
• {as} (`fun(self: nvim_tree.Class, class: T): T?`) See
|
|
|nvim_tree.Class:as()|.
|
|
• {destroy} (`fun(self: nvim_tree.Class)`) See
|
|
|nvim_tree.Class:destroy()|.
|
|
• {extend} (`fun(self: nvim_tree.Class): [nvim_tree.Class]`) See
|
|
|nvim_tree.Class:extend()|.
|
|
• {implement} (`fun(self: nvim_tree.Class, mixin: nvim_tree.Class)`)
|
|
See |nvim_tree.Class:implement()|.
|
|
• {is} (`fun(self: nvim_tree.Class, class: T): boolean`) See
|
|
|nvim_tree.Class:is()|.
|
|
• {new} (`fun(self: nvim_tree.Class, ...: any)`) See
|
|
|nvim_tree.Class:new()|.
|
|
• {nop} (`fun(self: nvim_tree.Class, ...: any)`) See
|
|
|nvim_tree.Class:nop()|.
|
|
• {super} (`nvim_tree.Class`) Parent class, `Class` for base
|
|
classes.
|
|
|
|
|
|
Class:as({class}) *nvim_tree.Class:as()*
|
|
Type safe cast.
|
|
|
|
If instance |nvim_tree.Class:is()|, cast to {class} and return it,
|
|
otherwise nil.
|
|
|
|
Parameters: ~
|
|
• {class} (`any`) `<T>`
|
|
|
|
Return: ~
|
|
(`any?`) `<T>`
|
|
|
|
Class:destroy() *nvim_tree.Class:destroy()*
|
|
Conventional destructor, optional, must be called by the owner.
|
|
|
|
Parent destructor must be invoked using the form `Parent.destroy(self)`
|
|
|
|
Class:extend() *nvim_tree.Class:extend()*
|
|
Create a new class by extending another class.
|
|
|
|
Base classes extend `Class`
|
|
|
|
Return: ~
|
|
(`[nvim_tree.Class]`) child class
|
|
|
|
Class:implement({mixin}) *nvim_tree.Class:implement()*
|
|
Add the methods and fields of a mixin using the form
|
|
`SomeClass:implement(MixinClass)`
|
|
|
|
If the mixin has fields, it must implement a constructor.
|
|
|
|
Parameters: ~
|
|
• {mixin} (`nvim_tree.Class`)
|
|
|
|
Class:is({class}) *nvim_tree.Class:is()*
|
|
Instance of.
|
|
|
|
Test whether an object is {class}, inherits {class} or implements mixin
|
|
{class}.
|
|
|
|
Parameters: ~
|
|
• {class} (`any`) `<T>`
|
|
|
|
Return: ~
|
|
(`boolean`)
|
|
|
|
Class:new({...}) *nvim_tree.Class:new()*
|
|
Constructor: `self` has been allocated and is available.
|
|
|
|
Super constructor must be called using the form
|
|
`Child.super.new(self, parent_args)`
|
|
|
|
Parameters: ~
|
|
• {...} (`any`) constructor arguments
|
|
|
|
Class:nop({...}) *nvim_tree.Class:nop()*
|
|
Utility method to bypass unused param warnings in abstract methods.
|
|
|
|
Parameters: ~
|
|
• {...} (`any`)
|
|
|
|
|
|
==============================================================================
|
|
Class: Decorator *nvim-tree-class-decorator*
|
|
|
|
Highlighting and icons for nodes are provided by Decorators, see
|
|
|nvim-tree-icons-highlighting| for an overview.
|
|
|
|
Decorators are rendered in |nvim_tree.config.renderer| {decorators} order of
|
|
additive precedence, with later decorators applying additively over earlier.
|
|
|
|
You may provide your own in addition to the builtin decorators, see
|
|
|nvim-tree-class-decorator-example|.
|
|
|
|
Decorators may:
|
|
• Add icons
|
|
• Set a highlight group name for the name or icons
|
|
• Override node icon
|
|
|
|
To register your decorator:
|
|
• Create a class that extends |nvim_tree.api.Decorator|
|
|
• Register it by adding the class to |nvim_tree.config.renderer| {decorators}
|
|
|
|
Your decorator will be constructed and executed each time the tree is
|
|
rendered.
|
|
|
|
Your class must:
|
|
• |nvim_tree.Class:extend()| the interface |nvim_tree.api.Decorator|
|
|
• Provide a no-arguments constructor |nvim_tree.Class:new()| that sets the
|
|
mandatory fields:
|
|
• {enabled}
|
|
• {highlight_range}
|
|
• {icon_placement}
|
|
• Call |nvim_tree.api.Decorator:define_sign()| in your constructor when
|
|
{icon_placement} is `"signcolumn"`
|
|
|
|
Your class may:
|
|
• Implement methods to provide decorations:
|
|
• |nvim_tree.api.Decorator:highlight_group()|
|
|
• |nvim_tree.api.Decorator:icon_node()|
|
|
• |nvim_tree.api.Decorator:icons()|
|
|
|
|
|
|
*nvim_tree.api.Decorator*
|
|
Extends: |nvim_tree.Class|
|
|
|
|
Decorator interface
|
|
|
|
Fields: ~
|
|
• {define_sign} (`fun(self: nvim_tree.api.Decorator, icon: nvim_tree.api.highlighted_string?)`)
|
|
See |nvim_tree.api.Decorator:define_sign()|.
|
|
• {enabled} (`boolean`) Enable this decorator.
|
|
• {highlight_group} (`fun(self: nvim_tree.api.Decorator, node: nvim_tree.api.Node): string?`)
|
|
See |nvim_tree.api.Decorator:highlight_group()|.
|
|
• {highlight_range} (`nvim_tree.config.renderer.highlight`) What to
|
|
highlight: |nvim_tree.config.renderer.highlight|
|
|
• {icon_node} (`fun(self: nvim_tree.api.Decorator, node: nvim_tree.api.Node): nvim_tree.api.highlighted_string?`)
|
|
See |nvim_tree.api.Decorator:icon_node()|.
|
|
• {icon_placement} (`"none"|nvim_tree.config.renderer.icons.placement`)
|
|
Where to place the icons:
|
|
|nvim_tree.config.renderer.icons.placement|
|
|
• {icons} (`fun(self: nvim_tree.api.Decorator, node: nvim_tree.api.Node): nvim_tree.api.highlighted_string[]?`)
|
|
See |nvim_tree.api.Decorator:icons()|.
|
|
|
|
*nvim_tree.api.highlighted_string*
|
|
Text or glyphs with optional highlight group names to apply to it.
|
|
|
|
Fields: ~
|
|
• {hl} (`string[]`) Highlight group names to apply in order. Empty
|
|
table for no highlighting.
|
|
• {str} (`string`) One or many glyphs/characters.
|
|
|
|
|
|
Decorator:define_sign({icon}) *nvim_tree.api.Decorator:define_sign()*
|
|
Defines a sign for an icon. This is mandatory and necessary only when
|
|
{icon_placement} is `"signcolumn"`
|
|
|
|
This must be called during your constructor for all icons that you will
|
|
return from |nvim_tree.api.Decorator:icons()|
|
|
|
|
Parameters: ~
|
|
• {icon} (`nvim_tree.api.highlighted_string?`) does nothing if nil
|
|
|
|
*nvim_tree.api.Decorator:highlight_group()*
|
|
Decorator:highlight_group({node})
|
|
One highlight group that applies additively to the {node} name for
|
|
{highlight_range}.
|
|
|
|
Abstract, optional to implement.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node`)
|
|
|
|
Return: ~
|
|
(`string?`) highlight group name `nil` when no highlighting to apply
|
|
to the node
|
|
|
|
Decorator:icon_node({node}) *nvim_tree.api.Decorator:icon_node()*
|
|
Icon to override for the node.
|
|
|
|
Abstract, optional to implement.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node`)
|
|
|
|
Return: ~
|
|
(`nvim_tree.api.highlighted_string?`) icon `nil` for no override
|
|
|
|
Decorator:icons({node}) *nvim_tree.api.Decorator:icons()*
|
|
Icons to add to the node as per {icon_placement}
|
|
|
|
Abstract, optional to implement.
|
|
|
|
Parameters: ~
|
|
• {node} (`nvim_tree.api.Node`)
|
|
|
|
Return: ~
|
|
(`nvim_tree.api.highlighted_string[]?`) icons `nil` or empty table for
|
|
no icons. Only the first glyph of {str} is used when {icon_placement}
|
|
is `"signcolumn"`
|
|
|
|
|
|
==============================================================================
|
|
Class: Decorator example *nvim-tree-class-decorator-example*
|
|
|
|
A decorator class for nodes named "example", overriding all builtin decorators
|
|
except for Cut.
|
|
• Highlights node name with `IncSearch`
|
|
• Creates two icons `"1"` and `"2"` placed after the node name, highlighted
|
|
with `DiffAdd` and `DiffText`
|
|
• Replaces the node icon with `"N"`, highlighted with `Error `
|
|
|
|
Create a class file `~/.config/nvim/lua/my-decorator.lua`
|
|
|
|
Require and register it during |nvim-tree-setup|: >lua
|
|
|
|
local MyDecorator = require("my-decorator")
|
|
|
|
require("nvim-tree").setup({
|
|
renderer = {
|
|
decorators = {
|
|
"Git",
|
|
"Open",
|
|
"Hidden",
|
|
"Modified",
|
|
"Bookmark",
|
|
"Diagnostics",
|
|
"Copied",
|
|
MyDecorator,
|
|
"Cut",
|
|
},
|
|
},
|
|
})
|
|
<
|
|
|
|
Contents of `my-decorator.lua`: >lua
|
|
|
|
---@class (exact) MyDecorator: nvim_tree.api.Decorator
|
|
---@field private my_icon1 nvim_tree.api.highlighted_string
|
|
---@field private my_icon2 nvim_tree.api.highlighted_string
|
|
---@field private my_icon_node nvim_tree.api.highlighted_string
|
|
---@field private my_highlight_group string
|
|
local MyDecorator = require("nvim-tree.api").Decorator:extend()
|
|
|
|
---Mandatory constructor :new() will be called once per tree render, with no arguments.
|
|
function MyDecorator:new()
|
|
self.enabled = true
|
|
self.highlight_range = "name"
|
|
self.icon_placement = "after"
|
|
|
|
-- create your icons and highlights once, applied to every node
|
|
self.my_icon1 = { str = "1", hl = { "DiffAdd" } }
|
|
self.my_icon2 = { str = "2", hl = { "DiffText" } }
|
|
self.my_icon_node = { str = "N", hl = { "Error" } }
|
|
self.my_highlight_group = "IncSearch"
|
|
|
|
-- Define the icon signs only once
|
|
-- Only needed if you are using icon_placement = "signcolumn"
|
|
-- self:define_sign(self.my_icon1)
|
|
-- self:define_sign(self.my_icon2)
|
|
end
|
|
|
|
---Override node icon
|
|
---@param node nvim_tree.api.Node
|
|
---@return nvim_tree.api.highlighted_string? icon_node
|
|
function MyDecorator:icon_node(node)
|
|
if node.name == "example" then
|
|
return self.my_icon_node
|
|
else
|
|
return nil
|
|
end
|
|
end
|
|
|
|
---Return two icons for DecoratorIconPlacement "after"
|
|
---@param node nvim_tree.api.Node
|
|
---@return nvim_tree.api.highlighted_string[]? icons
|
|
function MyDecorator:icons(node)
|
|
if node.name == "example" then
|
|
return { self.my_icon1, self.my_icon2, }
|
|
else
|
|
return nil
|
|
end
|
|
end
|
|
|
|
---Exactly one highlight group for DecoratorHighlightRange "name"
|
|
---@param node nvim_tree.api.Node
|
|
---@return string? highlight_group
|
|
function MyDecorator:highlight_group(node)
|
|
if node.name == "example" then
|
|
return self.my_highlight_group
|
|
else
|
|
return nil
|
|
end
|
|
end
|
|
|
|
return MyDecorator
|
|
<
|
|
|
|
vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:
|