README.md

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

Install

This plugin requires neovim >=0.7.0.

Install with vim-plug:

Plug 'kyazdani42/nvim-web-devicons' " optional, for file icons
Plug 'kyazdani42/nvim-tree.lua'

or with packer:

use {
  'kyazdani42/nvim-tree.lua',
  requires = {
    'kyazdani42/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.

Setup may only be run once; subsequent calls will result in a warning.

-- examples for your init.lua

-- 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.

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. Use with great caution.

Troubleshooting

Diagnostic Logging

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

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