kyazdani42 / nvim-tree.lua

A file explorer tree for neovim written in lua

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.

Questions and general support: Discussions

Requirements

neovim >=0.8.0

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

Please install via your preferred package manager. See Installation for specific package manager instructions.

nvim-tree/nvim-tree.lua

Major or minor versions may be specified via tags: v<MAJOR> e.g. v1 or v<MAJOR>.<MINOR> e.g. v1.23

nvim-tree/nvim-web-devicons optional, for file icons

Disabling netrw is strongly advised, see :help nvim-tree-netrw

Quick Start

Setup

Setup the plugin in your init.lua

-- disable netrw at the very start of your init.lua
vim.g.loaded_netrw = 1
vim.g.loaded_netrwPlugin = 1

-- optionally enable 24-bit colour
vim.opt.termguicolors = true

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

-- OR setup with some options
require("nvim-tree").setup({
  sort = {
    sorter = "case_sensitive",
  },
  view = {
    width = 30,
  },
  renderer = {
    group_empty = true,
  },
  filters = {
    dotfiles = true,
  },
})

Help

Open the tree: :NvimTreeOpen

Show the mappings: g?

Custom Mappings

:help nvim-tree-mappings-default are applied by default however you may customise via |nvim-tree.on_attach| e.g.

local function my_on_attach(bufnr)
  local api = require "nvim-tree.api"

  local function opts(desc)
    return { desc = "nvim-tree: " .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true }
  end

  -- default mappings
  api.config.mappings.default_on_attach(bufnr)

  -- custom mappings
  vim.keymap.set('n', '<C-t>', api.tree.change_root_to_parent,        opts('Up'))
  vim.keymap.set('n', '?',     api.tree.toggle_help,                  opts('Help'))
end

-- pass to setup along with your other options
require("nvim-tree").setup {
  ---
  on_attach = my_on_attach,
  ---
}

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.

vim.cmd([[
    :hi      NvimTreeExecFile    guifg=#ffa0a0
    :hi      NvimTreeSpecialFile guifg=#ff80ff gui=underline
    :hi      NvimTreeSymlink     guifg=Yellow  gui=italic
    :hi link NvimTreeImageFile   Title
]])

See :help nvim-tree-highlight for details.

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.

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

Please raise a feature request if the API is insufficient 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.

Screenshots

See Showcases wiki page for examples of user's configurations with sources.

Please add your own!

Team

• @alex-courtis Arch Linux
• @gegoune macOS
• @Akmadan23 Linux
• @dependabot[bot] Ubuntu Linux

nvim-tree.lua's Issues

Buffer local options not working

Congrats on merging the refactor 🙌
Just tried it out and it feels even snappier 🥇.

A strange issue I'm having that started before the refactor but has gotten worse, is that some buffer local options aren't working for some reason. The nonumber and nolist setting seems to now no longer be working.

I've tried with a minimal vimrc with just

call plug#begin(stdpath('data') . '/plugged')
Plug 'kyazdani42/nvim-tree.lua'
call plug#end()

set number relativenumber
set list

As you can see in the screenshot for some reason the set local call in Tree.lua isn't working I'm not really sure I understand. I also tried creating a after/ftplugin/LuaTree.vim to override things but that still didn't work.

If I remove the settings from my init.vim everything works but I need/like those settings not sure why the buffer isn't overriding it 😕

Optimize updates

Folder should only be checked if it has changed (stat.atime, stat.ctime)

• update folders modification time
  When running an update, do a BFS to check for folders with changed content and go up recursively.

Is there a way to align files to dirs when not using nvim-web-devicons?

Thanks very much for this plugin, I'm already using it as replace for nerdtree. I haven't found a way to make it look like second the pic below.

I've already tried setting

let g:lua_tree_icons = {
      \ 'default': ' ',
      \}

And something else, that isn't related to this, but g:lua_tree_follow defaults to 1, but in the docs it says it defaults to 0.

Plugin sets `splitbellow` globally

splitbellow is a global option.

'splitbelow' 'sb'	boolean	(default off)
			global

https://github.com/kyazdani42/nvim-tree.lua/blob/3bcfc70ea6759f40cc12e31e20f8b6c36f9ed2ac/lua/lib/lib.lua#L26

Actually, I can see other global options being set as well, like sidescroll

[Bug] Cannot open tree after opening file from single window tree

I'm not sure if title is descriptive enough, but i'll give steps to reproduce.
Basically, when nvim-tree is last window, and you open file from it, later it errors out:

Steps:

• Open up neovim
• do :LuaTreeOpen
• close the other empty window that's on the right, this leaves only nvim-tree
• Find some file, open it
• Try :LuaTreeToggle or :LuaTreeOpen. Toggle throws error, open silently fails.

I guess there are 2 available fixes:

1. Always open a window in case when nvim-tree is only window available
2. Properly handle nvim-tree state after opening a file so it can be opened again

Overriding icons requires complete map or causes errors

If a user doesn't specify items in the lua_tree_icons map vim fails to startup/crashes

Steps to reproduce:

1. Add

let g:lua_tree_icons = {
   \ 'folder': {
    \   'default': "",
    \   'open': ""
    \   }

2. Restart vim

The fix here is just to make sure to specify the whole thing, so not a huge issue this is just FYI since it's kind of a gnarly bug

fix issue with new folder git informations

if you delete or rename a file, folder can have a git status of D or D and ??.
Renaming could be detected but it might be a little bit complicated. Even for files, it would be a little bit hard.
Another solution would be to show that this folder has a new and deleted state.

'winhl' is being overwritten

In my config files, I set the winhl option for LuaTree when it starts, but it's being overwritten. LuaTree should use set winhl+= to preserver existing options.

Btw, as soon as you merge the refactor PR I plan to help.

Below is a screenshot of the reason why I wanna modify it. Had to monkey-patch some files to make it.

attempt to concatenate local 'git_root' (a nil value)

Error detected while processing VimEnter Autocommands for "*":
E5108: Error executing lua ...e/lks/.config/nvim/plugged/nvim-tree.lua/lua/lib/git.lua:68: attempt to concatenate local 'git_root' (a nil value)

Keybinding customization

Would it be possible to customize keybindings? (e.g.: change keybind to create a file or change keybind to expand directory from to something else)

[bug] error when closing (toggle) the tree

When I close (toggle) tree for the first time this error appears:

E5108: Error executing lua .../.local/share/nvim/plugged/nvim-tree.lua/lua/lib/lib.lua:252: Vim(lua):E5108: Error executing lua .../.local/share/nvim/plugged/nvim-tree.lua/lua/tree.lua:100: attempt to call field 'defer_fn' (a nil value)

When I try to open it again (toggle), this appears:

E5108: Error executing lua .../.local/share/nvim/plugged/nvim-tree.lua/lua/lib/lib.lua:231: Vim:E95: Buffer with this name already exists

Suggestion -- add a preview key

Hi there,

I love your plugin, and I noticed that you don't have a key that opens files without leaving the tree's window.

It's a simple thing to add, and I have attached a snippet below of how I have it in my config.

I think this is a common enough usecase to include in the plugin though.

    lv.tree_preview = function ()
      local pos = api.nvim_win_get_cursor(0)
      local tree = require "tree"
      tree.on_keypress("edit")
      bindings.exec[[LuaTreeClose]]
      bindings.exec[[LuaTreeOpen]]
      api.nvim_win_set_cursor(0, pos)
    end

    bindings.map.normal("<Tab>", ":lua lv.tree_preview()<CR>")

*I wrote some config wrappers in my code, but you get the idea

Highlights broken on sourcing vimrc

Just tried this out this plugin on my work mono repo of 100,000 files and approx 1500 subfolders and it was so fast 😍 .

I'm still getting a few issues before I can make it my daily driver for work. I'll try and get a minimal vimrc reproduction once I get a chance.

Symlinks don't have an icon

I don't use icons, but since it doesn't fallback to the default "icon" it doesn't get the padding like the other files.

Screenshots

Few minor improvements

Hey,

i really like the state of the plugin right now, it's really great. I'm completely switched to it.
I want to suggest few more improvements. Will work on them myself, just want a confirmation from your side:

1. Allow multiple keys for single action
   I'm used to using o for open action, but sometimes I also try to use <CR>. Currently I can map only one of these.

2. Show current cwd at top
   When I work on similar projects, sometimes i forget in which folder I am. Having the info at top (beside the ..) would help. I'm aware that this will require changing all if checks where we have if node.name == '..' then return end, but it should not be a complicated change.

Show git icons in files to the right as folders

Folders show the git icon to the right, I'd like to do the same for files. I don't think there is a way to do that right now, so it would be a new setting

[Question] I wonder why does not support windows technically

Add multiple projects

from this comment

Calling :LuaTreeToggle creates empty buffers when "hidden" is set

OS: Ubuntu 18.04
terminal: Gnome Terminal
nvim: NVIM v0.5.0-392-gff1730373

Steps to reproduce using nvim -u NORC

In any buffer, set the following option:

:set hidden

Then, call :LuaTreeToggle a few times. When inspecting the buffer list, this is the result:

:buffers                                                                                   
  1 %a   "[No Name]"                    line 1
  4  h   "[No Name]"                    line 1
  6  h   "[No Name]"                    line 1
  8  h   "[No Name]"                    line 1
 10  h   "[No Name]"                    line 1
Press ENTER or type command to continue

---

After investigating the issue a bit, it seems to come from this line:
https://github.com/kyazdani42/nvim-tree.lua/blob/7e3ff3db86effd9901448ff8d553af71526e979a/lua/lib/winutils.lua#L69

According to the documentation, :new opens a new window with an empty file in it, hence why the buffer isn't discarded. Using :vsplit instead seems to fix the bug, but I'm not familiar enough with (Neo)vim's quirks to know whether this causes other undesirable side effects.

Thanks for the cool plugin by the way, it has nice defaults and works really well out of the box :)

Broken indent markers for image files

@kyazdani42 looks like the latest commit broke handling of indent markers for image files.

This doesn't seem to have affected other filetypes though so not sure if images are special cased somehow

Configurable directory icons (no devicons)

Hi,
I don't use devicons and currently if I want to change directory close/open icons I need to modify renderer.lua. Can you make it configurable so that it can be set in init.vim?

Files inside directory not intended

If you see, the files inside lib is rendered along with lib.
I think this might only happens without icons, not sure though.

Nvim Tree prevents gx mapping working

It seems like g:loaded_netrw is being set by nvim-tree at some point, which I probably wouldn't have noticed if not for the fact that I use gx often to follow links in nvim. I know Netrw interferes with other alternative tree plugins as this has been something I've seen across several plugins. But is it possible to avoid disabling it altogether or at least maintaining the gx behaviour. Maybe a replacement mapping to gx that calls loads netrw only for that purpose.

Not entirely sure how that would work tbh

Use hl-Directory

The hl-Directory group already exists, it would be nice to link to it by default.

highlight default link LuaTreeFolderName Directory

`lua_tree_git_hl` doesn't update when not using git icons

let g:lua_tree_git_hl = 1

let g:lua_tree_show_icons = {
      \ 'git': 0,
}

If you change a file, the color doesn't get updated, according to the docs it should work without icons

Add :LuaTreeOpen/Close

Optimize rendering

currently, the whole tree is redrawn all the time.
It should only redraw from the cursor to the end of the buffer

Not disable netrw

Is there a reason why netrw is being disabled? gx doesn't work without it in other buffers.

https://github.com/kyazdani42/nvim-tree.lua/blob/3bcfc70ea6759f40cc12e31e20f8b6c36f9ed2ac/plugin/tree.vim#L6-L7

File operations use git if within repository and fs-object is tracked

Hey thanks for this cool plugin! 🙏

I think it would be a cool feature to integrate git also into the operations to the file system. So if I call an operation to remove or rename on an object, it would be great if the git equivalent commands could be used. So to name git-rm and git-mv. Of course this should only be done when inside a git repository and if the object is actually tracked by git (already). I would not handle operations creating new objects.

Curious what you think about this idea. 🙃

Refactoring

Doing:

• use vim nightly features
• when updating file system, check for open buffers, if some name matches, change the buffer names to avoid conflicts when saving a file
• fix various bugs
• use fs_scandir instead of ls which makes ignoring also available on macos and makes the tree much much much faster

not doing:

• bufferize project in the background to open directories faster -> too slow
• whole tree async with luv fs operations -> codebase becomes messy

LuaTreeFindFile doesn't always work

Thanks for fixing #9 so quickly 🙌 .

I ran into another issue FYI 😅, when buffers from different repositories are open, nvim-tree doesn't move to the current project root (or alternatively the directory that contains the file). The GIF below hopefully shows what I mean. The first buffer in the GIF is my dotfiles repo, but I opened vim in a dart project repo. LuaTree sticks to the initial directory, and when I move into the dotfiles project it doesn't change the tree to show the new dir.

Note: using LuaTreeFindFile in a buffer in a different project than lua tree does nothing

Still reading through the code so not exactly sure what is going on yet. Looks like maybe ROOT_PATH isn't being updated when you enter a new dir 🤷‍♂️

Git status changes

Hi,

is there any specific reason why folders have git status icon after, and files have it before? :)

I would like to make that consistent, and also to introduce an option to highlight the whole item when it is "dirty". What do you think about that?

[bug] tab pages broken when opening the tree in a new tab

The tree window is breaking neovim tab pages when opening the tree in a new tab.

• open neovim
• :LuaTreeOpen
• :tabnew
• :LuaTreeClose
• :LuaTreeOpen

Fix fs operations

i've noticed a few bugs when altering the fs:

• When renaming a file, it doesn't update the UI properly (the old file stays, maybe because of filename matching).
• When changing the name of a buffer to match a renamed file, then it asks Overwrite existing file: $renamedfile. Strange.
• deleting folders not working properly. This needs to be rewritten using synchronous operations.

[bug] there is a error when open nvim at $HOME dir

Error detected while processing VimEnter Autocommands for "*":

E5108: Error executing lua .../.config/nvim/plugged/nvim-tree.lua/lua/lib/renderer.lua:39: attempt to get length of local 'extension' (a nil value)

[bug] render bug

It get error when I open tree
E5108: Error executing lua .../.config/nvim/plugged/nvim-tree.lua/lua/lib/renderer.lua:271: Expected lua string

Open LuaTree on multiple/all tabs

I would love to have the ability to open LuaTree on multiple tabs.

I use NERDTree with the vim-nerdtree-tabs plugin, which basically makes the tree behave like a panel as found in apps like VSCode or Atom.

This seems to be somewhat controversial (see NERDTree#faq) but it best fits the way I use vim, and judging by the popularity of the vim-nerdtree-tabs plugin, I am not alone.

I would be happy to work on a PR if this is something amicable to the goals of the project but which you don't want to implement yourself.

P.s. wow, this is an excellent plugin. It is considerably faster than NERDTree. Great job Kiyan!

Add nvim-tree filetype and re-apply colorscheme on sourcing init.vim

Firstly thanks for the awesome plugin, it's super snappy 💯

Sorry I bundled two issues in one.

1. Buffer Filetypes

I noticed that the plugin doesn't give the nvim-tree buffers specific filetypes so it's hard to set autocommands or use the filetype to do whatever a user might want with that buffer e.g. nerdtree or coc-explorer etc. buffers have a filetype so I could have line number on or off by setting a filetype autocommand or using a ftplugin file. Or in my statusline I can check the filetype and show a formatted name with an icon for that kind of buffer or hide the statusline in that buffer altogether 🤷.

I'd be up for raising a PR for that if that interests you at all?

2. Buffer highlights disappear on sourcing init.vim

This is a fairly common issue with a lot of different plugins, as far as I can guess the highlights set in the nvim-tree buffer are only done once not on Colorscheme changed. Think a fix here would be register a function in the plugin to apply the highlights and call it when the colorscheme changes.

slow when scrolling through folders, comparing to defx

it pretty slow when I scrolling down/up (j/k) through folders, comparing to defx

Opening new file sometimes override window options.

I found one bug with it. Looks like it overrides some things globally, for example set number. Here are steps to reproduce.

• Make sure you have set number in your init.vim
• Open up neovim
• do :LuaTreeOpen
• close the other empty window that's on the right, this leaves only nvim-tree
• Find some file, open it
• do :LuaTreeOpen, find some other file and open it in vertical split
• The new split window doesn't have numbers, but it should

Originally posted by @kristijanhusak in #57 (comment)

Filetype set after buffer window is created (maybe)

I'm seeing an issue when trying to use the &filetype hook for LuaTree to setup autocommands or a custom statusline for the buffer. I haven't looked through the code so this is a guess, but I wonder when the ft is being set. Currently if I set my statusline to change when it detects the filetype=LuaTree it doesn't work the first time. I also can't highlight the window using winhighlight because it doesn't seem to pick up the filetype.

I've tried using coc-explorer which also sets a filetype and things work fine.
If this isn't enough information please let me know I can try and do a minimal repro but I think just setting up an autocommand for LuaTree buffers should be enough to see that the autocommand won't work the first time the buffer is opened

Few feature requests

Hi,

very nice plugin, works really fast!

I have few feature requests that you might consider:

• Allow selecting files and operating on them (For example, multiple rename)
• DONE in #52: Introduce cut/copy/paste
• DONE IN #56: Add mappings for jumping to previous/next git changed file, something like vim-gitgutter does with ]c and [c
• DONE in #53: Allow toggling visibility of ignored files

I'm currently using these features in defx.nvim, and I'm also author of git and icons plugins for defx.

space between icon and filename for special files

I'm not sure if it was caused by this PR, but "special" filenames now have a default icon (which is fine), but it looks like it's missing a space after:

Originally posted by @kristijanhusak in #71 (comment)

Default icon

Would it be possible to add a default icon so that files that don't match any filetype/filename icon are aligned at the same level as the rest?

Missing variable causing autocommand errors

Whilst swapping branches and dealing with a merge conflict I tried to open lua tree and got the following errors. I've seen these before but not sure exactly what causes them, sorry. Just noting here for now will update later once I'm not at work with a clearer way to reproduce if I find it.

E5108: Error executing lua ...al/share/nvim/plugged/nvim-tree.lua/lua/lib/renderer.lua:81: bad argument #1 to 'ipairs' (table expected, got nil)                                                                                                   
E5108: Error executing lua ...al/share/nvim/plugged/nvim-tree.lua/lua/lib/renderer.lua:81: bad argument #1 to 'ipairs' (table expected, got nil)                                                                                                   
Error detected while processing BufEnter Autocommands for "*":                                                                                                                                                                                     
E5108: Error executing lua .../.local/share/nvim/plugged/nvim-tree.lua/lua/lib/lib.lua:172: Cursor position outside buffer                                                                                                                         
E5108: Error executing lua .../.local/share/nvim/plugged/nvim-tree.lua/lua/lib/lib.lua:172: Cursor position outside buffer                                                                                                                         
E5108: Error executing lua .../.local/share/nvim/plugged/nvim-tree.lua/lua/lib/lib.lua:172: Cursor position outside buffer                                                                                                                         
E5108: Error executing lua ...al/share/nvim/plugged/nvim-tree.lua/lua/lib/renderer.lua:81: bad argument #1 to 'ipairs' (table expected, got nil)                                                                                                   
E5108: Error executing lua ...al/share/nvim/plugged/nvim-tree.lua/lua/lib/renderer.lua:81: bad argument #1 to 'ipairs' (table expected, got nil) 

Feature request: indent markers

This is a completely stylistic addition which I found quite nice in other file explorers e.g. coc-explorer below.

maybe this could be added as a config option so anyone who does or doesn't like it can toggle it.

I had a quick look at the code to see if it could be added easily and looks like in the renderer.lua where the padding is added you could insert a special character one for most indents | and one at the end of that indent level (can't find the exact unicode symbol atm). Naively just inserting the symbol breaks the position based highlighting. I'm happy to dig into it when I have some free time if you haven't already had a look (if you think it's fine to implement)

LuaTreeFindFile doesn't automatically open tree

For example, in NerdTree, running NerdTreeFindFile also opens the tree if it's not already opened. Here we need tree to be opened in order to execute the find. Is that on purpose ?

Autocommand errors

I've encountered a few autocommand errors whilst using nvim tree

and

I'm not sure exactly how to reproduce either of them unfortunately I haven't had enough time to debug. The config I'm currently using is

let g:lua_tree_auto_close = 1 " 0 by default, closes the tree when it's the last window
let g:lua_tree_follow     = 1 " On bufEnter find the current file
let g:lua_tree_bindings = {
      \ "edit": "o",
      \}
let g:lua_tree_ignore = [ '.git', 'node_modules' ]

I've also noticed that when I save a buffer nvim seems to block for like 1-2seconds. When I disable nvim-tree things go back to normal.

Sorry this isn't too detailed I'll do some more digging when I get a chance and update this

Creating a directory

First of all, I want to say that I am really enjoying this plugin so far, especially coming from having tried nerdtree -> coc-explorer -> defx.

I am wondering, is there a way to create a directory, just like you can create files from nvim-tree? If not, would it be something possible to implement?