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

Join us on matrix

Requirements

neovim >=0.7.0

nvim-web-devicons is optional and used to display file icons. It requires a patched 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 = 1
vim.g.loaded_netrwPlugin = 1

-- empty setup using defaults
require("nvim-tree").setup()

-- OR setup with some options
require("nvim-tree").setup({
  sort_by = "case_sensitive",
  view = {
    adaptive_size = true,
    mappings = {
      list = {
        { key = "u", action = "dir_up" },
      },
    },
  },
  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.view.mappings

Commands

See :help nvim-tree-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.

Api

nvim-tree exposes a public api; see :help nvim-tree-api. This is a stable non breaking api.

Mappings

nvim-tree comes with number of mappings; for default mappings please see :help nvim-tree-default-mappings, for way of configuring mappings see :help nvim-tree-mappings

g? toggles help, showing all the mappings and their actions.

Tips & tricks

• You can add a directory by adding a / at the end of the paths, entering multiple directories BASE/foo/bar/baz will add directory foo, then bar and add a file baz to it.
• You can update window options for the tree by setting require"nvim-tree.view".View.winopts.MY_OPTION = MY_OPTION_VALUE
• toggle has a second parameter which allows to toggle without focusing the explorer (require"nvim-tree".toggle(false, true)).
• You can allow nvim-tree to behave like vinegar, see :help nvim-tree-vinegar
• If you :set nosplitright, the files will open on the left side of the tree, placing the tree window in the right side of the file you opened.
• You can automatically close the tab/vim when nvim-tree is the last window in the tab: nvim-tree#1115. WARNING: this can catastrophically fail: nvim-tree#1368. This will not be added to nvim-tree and the team will not provide support / assistance with this, due to complexities in vim event timings and side-effects.
• Hide the .git folder: filters = { custom = { "^.git$" } }. See :help nvim-tree.filters.custom.
• To disable the display of icons see :help nvim-tree.renderer.icons.show.

Troubleshooting

Diagnostic Logging

You may enable diagnostic logging to $XDG_CACHE_HOME/nvim/nvim-tree.log. See :help nvim-tree.log

netrw Keeps Popping Up

Eagerly disable netrw. See :help nvim-tree.disable_netrw

Performance Issues

If you are experiencing performance issues with nvim-tree.lua, you can enable profiling in the logs. It is advisable to enable git logging at the same time, as that can be a source of performance problems.

log = {
  enable = true,
  truncate = true,
  types = {
    git = true,
    profile = true,
  },
},

Please attach $XDG_CACHE_HOME/nvim/nvim-tree.log if you raise an issue.

Performance Tips:

• If you are using fish as an editor shell (which might be fixed in the future), try set shell=/bin/bash in your vim config. Alternatively, you can prevent fish from loading interactive configuration in a non-interactive shell.

• Try manually running the git command (see the logs) in your shell e.g. git --no-optional-locks status --porcelain=v1 --ignored=matching -u.

• Huge git repositories may timeout after the default git.timeout of 400ms. Try increasing that in your setup if you see [git] job timed out in the logs.

• Try temporarily disabling git integration by setting git.enable = false in your setup.

Contributing

PRs are always welcome. See CONTRIBUTING.md

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

kyazdani42

alex-courtis

nvim-tree.lua

akin909

stsewd

reyhankaplan

almo7aya

nvim-tree on floating mode