A File Explorer For Neovim Written In Lua
Automatic updates
File type icons
Git integration
Diagnostics integration: LSP and COC
(Live) filtering
Cut, copy, paste, rename, delete, create
Highly customisable
Take a look at the wiki for Showcases, Tips, Recipes and more.
Breaking Change 2023-01-30
Existing *_on_setup*
mechanisms have been removed in favour of Open At Startup
New Mapping Method 2023-02-27
:help nvim-tree.view.mappings have been deprecated in favour of :help nvim-tree.on_attach. Please visit Migrating To on_attach to transition.
Requirements
nvim-web-devicons is optional and used to display file icons. It requires a patched font. Your terminal emulator must be configured to use that font, usually "Hack Nerd Font"
Install
Install with vim-plug:
Plug 'nvim-tree/nvim-web-devicons' " optional, for file icons
Plug 'nvim-tree/nvim-tree.lua'
or with packer:
use {
'nvim-tree/nvim-tree.lua',
requires = {
'nvim-tree/nvim-web-devicons', -- optional, for file icons
},
tag = 'nightly' -- optional, updated every week. (see issue #1193)
}
Setup
Setup should be run in a lua file or in a lua heredoc :help lua-heredoc if using in a vim file.
-- examples for your init.lua
-- disable netrw at the very start of your init.lua (strongly advised)
vim.g.loaded_netrw = 1
vim.g.loaded_netrwPlugin = 1
-- set termguicolors to enable highlight groups
vim.opt.termguicolors = true
-- empty setup using defaults
require("nvim-tree").setup()
-- OR setup with some options
require("nvim-tree").setup({
sort_by = "case_sensitive",
renderer = {
group_empty = true,
},
filters = {
dotfiles = true,
},
})
For complete list of available configuration options see :help nvim-tree-setup
Each option is documented in :help nvim-tree.OPTION_NAME
. Nested options can be accessed by appending .
, for example :help nvim-tree.filters.dotfiles
Commands
Basic commands:
:NvimTreeToggle
Open or close the tree. Takes an optional path argument.
:NvimTreeFocus
Open the tree if it is closed, and then focus on the tree.
:NvimTreeFindFile
Move the cursor in the tree for the current buffer, opening folders if needed.
:NvimTreeCollapse
Collapses the nvim-tree recursively.
Mappings
g?
toggles help, showing all the mappings and their actions.
To customise your mappings see :help nvim-tree.on_attach and :help nvim-tree-mappings
Roadmap
nvim-tree is stable and new major features will not be added. The focus is on existing user experience.
Users are encouraged to add their own custom features via the public API.
Development is focused on:
- Bug fixes
- Performance
- Quality of Life improvements
- API / Events
- Enhancements to existing features
API
nvim-tree exposes a public API. This is non breaking, with additions made as necessary. See :help nvim-tree-api
See wiki Recipes and Tips for ideas and insipration.
Please raise a feature request if the API is insufficent for your needs. Contributions are always welcome.
You may also subscribe to events that nvim-tree will dispatch in a variety of situations, see :help nvim-tree-events
Contributing
PRs are always welcome. See wiki to get started.
See bug and PR Please issues if you are looking for some work to get you started.
Help Wanted
Developers with the following environments:
- Apple macOS
- Windows
- WSL
- msys
- powershell
Help triaging, diagnosing and fixing issues specific to those environments is needed, as the nvim-tree developers do not have access to or expertise in these environments.
Let us know you're interested by commenting on issues and raising PRs.
Screenshots
See Showcases wiki page for examples of user's configurations with sources.
Please add your own!