neo-tree.nvim

Neo-tree.nvim

Neo-tree is a Neovim plugin to browse the file system and other tree like structures in whatever style suits you, including sidebars, floating windows, netrw split style, or all of them at once!

This screenshot shows Neo-tree opened in the traditional sidebar layout:

Breaking Changes BAD :bomb: :imp:

The biggest and most important feature of Neo-tree is that we will never knowingly push a breaking change and interrupt your day. Bugs happen, but breaking changes can always be avoided. When breaking changes are needed, there will be a new branch that you can opt into, when it is a good time for you.

See What is a Breaking Change? for details.

See Changelog 3.0 for breaking changes and deprecations in 3.0.

User Experience GOOD :slightly_smiling_face: :thumbsup:

Aside from being polite about breaking changes, Neo-tree is also focused on the little details of user experience. Everything should work exactly as you would expect a sidebar to work without all of the glitchy behavior that is normally accepted in (neo)vim sidebars. I can’t stand glitchy behavior, and neither should you!

• Neo-tree won’t let other buffers take over its window.
• Neo-tree won’t leave its window scrolled to the last line when there is plenty of room to display the whole tree.
• Neo-tree does not need to be manually refreshed (set use_libuv_file_watcher = true)
• Neo-tree can intelligently follow the current file (set follow_current_file.enabled = true)
• Neo-tree can sync its clipboard across multiple trees, either globally (within the same Neovim instance) or universally (across all Neovim instances). Try clipboard.sync = "global" | "universal".
• Neo-tree is thoughtful about maintaining or setting focus on the right node
• Neo-tree windows in different tabs are completely separate
• respect_gitignore actually works!

[!NOTE] Neo-tree is meant to be smooth, efficient, stable, and intuitive. If you find anything janky, slow, broken, or unintuitive, please open an issue so we can fix it.

Installation

Neo-tree currently supports Neovim 0.8 and onwards.

This plugin relies upon these two excellent library plugins:

• MunifTanjim/nui.nvim for all UI components, including the tree!
• nvim-lua/plenary.nvim for backend utilities, such as scanning the filesystem.

There are also some optional plugins that work with Neo-tree:

• nvim-tree/nvim-web-devicons for file icons.
• Crysthamus/nvim-file-operations or antosha417/nvim-lsp-file-operations for LSP-enhanced renames/etc.
• folke/snacks.nvim for image previews, see Preview Mode section.
• snacks.rename can also work with Neo-tree
• 3rd/image.nvim for image previews.
  • If both snacks.nvim and image.nvim are installed. Neo-tree currently will try to preview with snacks.nvim first, then try image.nvim.
• s1n7ax/nvim-window-picker for _with_window_picker keymaps.

vim.pack example (requires Neovim 0.12)

vim.pack.add({
  {
    src = 'https://github.com/nvim-neo-tree/neo-tree.nvim',
    version = vim.version.range('3')
  },
  -- dependencies
  "https://github.com/nvim-lua/plenary.nvim",
  "https://github.com/MunifTanjim/nui.nvim",
  -- optional, but recommended
  "https://github.com/nvim-tree/nvim-web-devicons",
})

lazy.nvim example:

return {
  {
    "nvim-neo-tree/neo-tree.nvim",
    branch = "v3.x",
    dependencies = {
      "nvim-lua/plenary.nvim",
      "MunifTanjim/nui.nvim",
      "nvim-tree/nvim-web-devicons", -- optional, but recommended
    },
    lazy = false, -- neo-tree will lazily load itself
  }
}

return {
  {
    "nvim-neo-tree/neo-tree.nvim",
    branch = "v3.x",
    dependencies = {
      "nvim-lua/plenary.nvim",
      "MunifTanjim/nui.nvim",
      "nvim-tree/nvim-web-devicons",
    },
  },
  {
    "Crysthamus/nvim-file-operations",
    -- branch = "compat" -- if you are on Neovim <= 0.10
    dependencies = {
      "nvim-neo-tree/neo-tree.nvim", -- makes sure that this loads after Neo-tree.
    },
    config = function()
      require("nvim-file-operations").setup()
    end,
  },
  {
    "s1n7ax/nvim-window-picker",
    version = "2.*",
    config = function()
      require("window-picker").setup({
        filter_rules = {
          include_current_win = false,
          autoselect_one = true,
          -- filter using buffer options
          bo = {
            -- if the file type is one of following, the window will be ignored
            filetype = { "neo-tree", "neo-tree-popup", "notify" },
            -- if the buffer type is one of following, the window will be ignored
            buftype = { "terminal", "quickfix" },
          },
        },
      })
    end,
  },
}

use({
  "nvim-neo-tree/neo-tree.nvim",
  branch = "v3.x",
  requires = {
    "nvim-lua/plenary.nvim",
    "MunifTanjim/nui.nvim",
    "nvim-tree/nvim-web-devicons", -- optional, but recommended
  }
})

local add = MiniDeps.add

add({
  source = 'nvim-neo-tree/neo-tree.nvim',
  checkout = 'v3.x',
  depends = {
    "nvim-lua/plenary.nvim",
    "MunifTanjim/nui.nvim",
    "nvim-tree/nvim-web-devicons", -- optional, but recommended
  }
})

Manual installation via :h packages

See doc/install.sh and doc/install.ps1 for POSIX/Windows respectively.

Post-install: Try it out!

Try :Neotree to open Neo-tree as a sidebar, and press ? while in Neo-tree to open the keyboard help.

[!TIP] You can :checkhealth neo-tree to ensure you have all the required dependencies. It can also check that your config table looks correct. This is still in its early stages, so please file issues if you’d like to see more checks added or a check isn’t working properly.

Configuration

require('neo-tree').setup({
  -- options go here
})

return {
  "nvim-neo-tree/neo-tree.nvim",
  branch = "v3.x",
  dependencies = {
    "nvim-lua/plenary.nvim",
    "MunifTanjim/nui.nvim",
    "nvim-tree/nvim-web-devicons", -- optional, but recommended
  },
  lazy = false, -- neo-tree will lazily load itself
  ---@module 'neo-tree'
  ---@type neotree.Config
  opts = {
    -- options go here
  }
}

vim.keymap.set("n", "<leader>e", "<Cmd>Neotree<CR>")
require("neo-tree").setup({
  close_if_last_window = false, -- Close Neo-tree if it is the last window left in the tab
  popup_border_style = "NC", -- or "" to use 'winborder' on Neovim v0.11+
  clipboard = {
    sync = "none", -- or "global"/"universal" to share a clipboard for each/all Neovim instance(s), respectively
  },
  enable_git_status = true,
  enable_diagnostics = true,
  open_files_do_not_replace_types = { "terminal", "trouble", "qf" }, -- when opening files, do not use windows containing these filetypes or buftypes
  open_files_using_relative_paths = false,
  sort_case_insensitive = false, -- used when sorting files and directories in the tree
  sort_function = nil, -- use a custom function for sorting files and directories in the tree
  -- sort_function = function (a,b)
  --       if a.type == b.type then
  --           return a.path > b.path
  --       else
  --           return a.type > b.type
  --       end
  --   end , -- this sorts files and directories descendantly
  default_component_configs = {
    container = {
      enable_character_fade = true,
    },
    indent = {
      indent_size = 2,
      padding = 1, -- extra padding on left hand side
      -- indent guides
      with_markers = true,
      indent_marker = "│",
      last_indent_marker = "└",
      highlight = "NeoTreeIndentMarker",
      -- expander config, needed for nesting files
      with_expanders = nil, -- if nil and file nesting is enabled, will enable expanders
      expander_collapsed = "",
      expander_expanded = "",
      expander_highlight = "NeoTreeExpander",
    },
    icon = {
      folder_closed = "",
      folder_open = "",
      folder_empty = "󰜌",
      provider = function(icon, node, state) -- default icon provider utilizes nvim-web-devicons if available
        if node.type == "file" or node.type == "terminal" then
          local success, web_devicons = pcall(require, "nvim-web-devicons")
          local name = node.type == "terminal" and "terminal" or node.name
          if success then
            local devicon, hl = web_devicons.get_icon(name)
            icon.text = devicon or icon.text
            icon.highlight = hl or icon.highlight
          end
        end
      end,
      -- The next two settings are only a fallback, if you use nvim-web-devicons and configure default icons there
      -- then these will never be used.
      default = "*",
      highlight = "NeoTreeFileIcon",
      use_filtered_colors = true, -- Whether to use a different highlight when the file is filtered (hidden, dotfile, etc.).
    },
    modified = {
      symbol = "[+]",
      highlight = "NeoTreeModified",
    },
    name = {
      trailing_slash = false,
      use_filtered_colors = true, -- Whether to use a different highlight when the file is filtered (hidden, dotfile, etc.).
      use_git_status_colors = true,
      highlight = "NeoTreeFileName",
    },
    git_status = {
      symbols = {
        -- Change type
        added = "", -- or "✚"
        modified = "", -- or ""
        deleted = "✖", -- this can only be used in the git_status source
        renamed = "󰁕", -- this can only be used in the git_status source
        -- Status type
        untracked = "",
        ignored = "",
        unstaged = "󰄱",
        staged = "",
        conflict = "",
      },
    },
    -- If you don't want to use these columns, you can set `enabled = false` for each of them individually
    file_size = {
      enabled = true,
      width = 12, -- width of the column
      required_width = 64, -- min width of window required to show this column
    },
    type = {
      enabled = true,
      width = 10, -- width of the column
      required_width = 122, -- min width of window required to show this column
    },
    last_modified = {
      enabled = true,
      width = 20, -- width of the column
      required_width = 88, -- min width of window required to show this column
    },
    created = {
      enabled = true,
      width = 20, -- width of the column
      required_width = 110, -- min width of window required to show this column
    },
    symlink_target = {
      enabled = false,
    },
  },
  -- A list of functions, each representing a global custom command
  -- that will be available in all sources (if not overridden in `opts[source_name].commands`)
  -- see `:h neo-tree-custom-commands-global`
  commands = {},
  window = {
    position = "left",
    width = 40,
    mapping_options = {
      noremap = true,
      nowait = true,
    },
    mappings = {
      ["<C-s>"] = {
        "quick_jump",
        config = {
          -- This will automaticly open / toggle the target node after jumping.
          -- You can set it to `nil` to perform only the jump action,
          -- or write your own callback (---@type fun(state, node)).
          on_jump = "open_or_toggle",
          jump_labels = "jfkdlsahgnuvrbytmiceoxwpqz",
        }
      },
      ["<Tab>"] = "select"

提示：代码过长已自动截断

See :h neo-tree for full documentation. You can also preview that online at doc/neo-tree.txt, although it’s best viewed within Neovim.

To see all of the default config options with commentary, you can view it online at lua/neo-tree/defaults.lua. You can also paste it into a buffer after installing Neo-tree by running:

:lua require("neo-tree").paste_default_config()

vim.diagnostic.config({
  signs = {
    text = {
      [vim.diagnostic.severity.ERROR] = '',
      [vim.diagnostic.severity.WARN] = '',
      [vim.diagnostic.severity.INFO] = '',
      [vim.diagnostic.severity.HINT] = '󰌵',
    },
  }
})

vim.fn.sign_define("DiagnosticSignError", { text = " ", texthl = "DiagnosticSignError" })
vim.fn.sign_define("DiagnosticSignWarn", { text = " ", texthl = "DiagnosticSignWarn" })
vim.fn.sign_define("DiagnosticSignInfo", { text = " ", texthl = "DiagnosticSignInfo" })
vim.fn.sign_define("DiagnosticSignHint", { text = "󰌵", texthl = "DiagnosticSignHint" })

The :Neotree Command

The single :Neotree command accepts a range of arguments that give you full control over the details of what and where it will show. For example, the following command will open a file browser on the right hand side, “revealing” the currently active file:

:Neotree filesystem reveal right

Arguments can be specified as either a key=value pair or just as the value. The key=value form is more verbose but may help with clarity. For example, the command above can also be specified as:

:Neotree source=filesystem reveal=true position=right

All arguments are optional and can be specified in any order. If you issue the command without any arguments, it will use default values for everything. For example:

:Neotree

will open the filesystem source on the left hand side and focus it, if you are using the default config.

Tab Completion

Neotree supports tab completion for all arguments. Once a given argument has a value, it will stop suggesting those completions. It will also offer completions for paths. The simplest way to disambiguate a path from another type of argument is to start them with / or ./.

Arguments

Here is the full list of arguments you can use:

action

What to do. Can be one of:

source

What to show. Can be one of:

position

Where to show it, can be one of:

toggle

This is a boolean flag. Adding this means that the window will be closed if it is already open.

dir

The directory to set as the root/cwd of the specified window. If you include a directory as one of the arguments, it will be assumed to be this option, you don’t need the full dir=/path. You may use any value that can be passed to the ‘expand’ function, such as %:p:h:h to specify two directories up from the current file. For example:

:Neotree ./relative/path
:Neotree /home/user/relative/path
:Neotree dir=/home/user/relative/path
:Neotree position=current dir=relative/path

git_base

The base that is used to calculate the git status for each dir/file. By default it uses HEAD, so it shows all changes that are not yet committed. You can for example work on a feature branch, and set it to main. It will show all changes that happened on the feature branch and main since you branched off.

Any git ref, commit, tag, or sha will work.

:Neotree main
:Neotree v1.0
:Neotree git_base=8fe34be
:Neotree git_base=HEAD

reveal

This is a boolean flag. Adding this will make Neotree automatically find and focus the current file when it opens.

reveal_file

A path to a file to reveal. This supersedes the “reveal” flag so there is no need to specify both. Use this if you want to reveal something other than the current file. If you include a path to a file as one of the arguments, it will be assumed to be this option. Like “dir”, you can pass any value that can be passed to the ‘expand’ function. For example:

:Neotree reveal_file=/home/user/my/file.text
:Neotree position=current dir=%:p:h:h reveal_file=%:p
:Neotree current %:p:h:h %:p

One neat trick you can do with this is to open a Neotree window which is focused on the file under the cursor using the <cfile> keyword:

nnoremap gd :Neotree float reveal_file=<cfile> reveal_force_cwd<cr>

reveal_force_cwd

This is a boolean flag. Normally, if you use one of the reveal options and the given file is not within the current working directory, you will be asked if you want to change the current working directory. If you include this flag, it will automatically change the directory without prompting. This option implies “reveal”, so you do not need to specify both.

selector

This is a boolean flag. When you specifically set this to false (selector=false) neo-tree will disable the source selector for that neo-tree instance. Otherwise, the source selector will depend on what you specified in the configuration (config.source_selector.{winbar,statusline}).

See :h neo-tree-commands for details and a full listing of available arguments.

File Nesting

See :h neo-tree-file-nesting for more details about file nesting.

Netrw Hijack

:edit .
:[v]split .

If "filesystem.window.position" is set to "current", or if you have specified filesystem.hijack_netrw_behavior = "open_current", then any command that would open a directory will open neo-tree in the specified window.

Sources

Neo-tree is built on the idea of supporting various sources. Sources are basically interface implementations whose job it is to provide a list of hierarchical items to be rendered, along with commands that are appropriate to those items.

filesystem

The default source is filesystem, which displays your files and folders. This is the default source in commands when none is specified.

This source can be used to:

• Browse the filesystem
• Control the current working directory of nvim
• Add/Copy/Delete/Move/Rename files and directories
• Search the filesystem
• Monitor git status and lsp diagnostics for the current working directory

buffers

Another available source is buffers, which displays your open buffers. This is the same list you would see from :ls. To show with the buffers list, use:

:Neotree buffers

git_status

This view take the results of the git status command and display them in a tree. It includes commands for adding, unstaging, reverting, and committing.

The screenshot below shows the result of :Neotree float git_status while the filesystem is open in a sidebar:

You can specify a different git base here as well. But be aware that it is not possible to unstage / revert a file that is already committed.

:Neotree float git_status git_base=main

document_symbols

The document_symbols source lists the symbols in the current document obtained by the LSP request “textDocument/documentSymbols”. It currently supports the following features:

• UI:
  • Display all symbols in the current file with symbol kinds
  • Symbols nesting
  • Configurable kinds’ name and icon
  • Auto-refresh symbol list
    • Follow cursor
• Commands
  • Jump to symbols, open symbol in split,… (open_split and friends)
  • Rename symbols (rename)
  • Preview symbol (preview and friends)
  • Hover docs
  • Call hierarchy
• LSP
  • LSP Support
  • LSP server selection (ignore, allow_only, use first, use all, etc.)
• CoC Support

See #879 for the tracking issue of these features.

This source is currently experimental, so in order to use it, you need to first add "document_symbols" to config.sources and open it with the command

:Neotree document_symbols

External Sources

There are more sources available as extensions that are managed outside of this repository. See the wiki for more information.

Source Selector

You can enable a clickable source selector in either the winbar (requires neovim 0.8+) or the statusline. To do so, set one of these options to true:

    require("neo-tree").setup({
        source_selector = {
            winbar = false,
            statusline = false
        }
    })

There are many configuration options to change the style of these tabs. See lua/neo-tree/defaults.lua for details.

Preview Mode

:h neo-tree-preview-mode

Preview mode will temporarily show whatever file the cursor is on without switching focus from the Neo-tree window. By default, files will be previewed in a new floating window. This can also be configured to automatically choose an existing split by configuring the command like this:

require("neo-tree").setup({
  window = {
    mappings = {
      ["P"] = {
        "toggle_preview",
        config = {
          use_float = false,
          -- use_image_nvim = true,
          -- use_snacks_image = true,
          -- title = 'Neo-tree Preview',
        },
      },
    }
  }
})

Anything that causes Neo-tree to lose focus will end preview mode. When use_float = false, the window that was taken over by preview mode will revert back to whatever was shown in that window before preview mode began.

You can choose a custom title for the floating window by setting the title option in its config.

If you want to work with the floating preview mode window in autocmds or other custom code, the window will have the neo-tree-preview filetype.

When preview mode is not using floats, the window will have the window local variable neo_tree_preview set to 1 to indicate that it is being used as a preview window. You can refer to this in statusline and winbar configs to mark a window as being used as a preview.

Image Support in Preview Mode

If you have folke/snacks.nvim or 3rd/image.nvim installed, preview mode supports image rendering by default using kitty graphics protocol or ueberzug (Video).

However, if you do not want this feature, you can disable it by setting use_snacks_image = false or use_image_nvim = false in the mappings config mentioned above.

Configuration and Customization

This is designed to be flexible. The way that is achieved is by making everything a function, or a string that identifies a built-in function. All of the built-in functions can be replaced with your own implementation, or you can add new ones.

Each node in the tree is created from the renderer specified for the given node type, and each renderer is a list of component configs to be rendered in order. Each component is a function, either built-in or specified in your config. Those functions simply return the text and highlight group for the component.

Additionally, there is an events system that you can hook into. If you want to show some new data point related to your files, gather it in the before_render event, create a component to display it, and reference that component in the renderer for the file and/or directory type.

Details on how to configure everything is in the help file at :h neo-tree-configuration or online at neo-tree.txt

Recipes for customizations can be found on the wiki. Recipes include things like adding a component to show the Harpoon index for files, or responding to the "file_opened" event to auto clear the search when you open a file.

Why?

There are many tree plugins for (Neo)vim, so why make another one? Well, I wanted something that was:

1. Easy to maintain and enhance.
2. Stable.
3. Easy to customize.

Easy to maintain and enhance

This plugin is designed to grow and be flexible. This is accomplished by making the code as decoupled and functional as possible. Hopefully new contributors will find it easy to work with.

One big difference between this plugin and the ones that came before it, which is also what finally pushed me over the edge into making a new plugin, is that we now have libraries to build upon that did not exist when other tree plugins were created. Most notably, nui.nvim and plenary.nvm. Building upon shared libraries will go a long way in making neo-tree easy to maintain.

Stable

This project will have releases and release tags that follow a simplified Semantic Versioning scheme. The quickstart instructions will always refer to the latest stable major version. Following the main branch is for contributors and those that always want bleeding edge. There will be branches for v1.x, v2.x, etc which will receive updates after a short testing period in main. You should be safe to follow those branches and be sure your tree won’t break in an update. There will also be tags for each release pushed to those branches named v1.1, v1.2, etc. If stability is critical to you, or a bug accidentally makes it into v3.x, you can use those tags instead. It’s possible we may backport bug fixes to those tags, but no guarantees on that.

There will never be a breaking change within a major version (1.x, 2.x, etc.) If a breaking change is needed, there will be depracation warnings in the prior major version, and the breaking change will happen in the next major version.

Easy to Customize

Neo-tree follows in the spirit of plugins like lualine.nvim and nvim-cokeline. Everything will be configurable and take either strings, tables, or functions. You can take sane defaults or build your tree items from scratch. There should be the ability to add any features you can think of through existing hooks in the setup function.

What is a Breaking Change?

As of v1.30, a breaking change is defined as anything that changes existing:

• vim commands (:Neotree)
• configuration options that are passed into the setup() function
• NeoTree* highlight groups
• lua functions exported in the following modules that are not prefixed with _:

• neo-tree
• neo-tree.events
• neo-tree.sources.manager
• neo-tree.sources.* (init.lua files)
• neo-tree.sources.*.commands
• neo-tree.ui.renderer
• neo-tree.utils

If there are other functions you would like to use that are not yet considered part of the public API, please open an issue so we can discuss it.

Contributions

Contributions are encouraged. Please see CONTRIBUTING for more details.

Acknowledgements

Maintainers

First and foremost, this project is a community endeavor and would not survive without the constant stream of features and bug fixes that comes from that community. There have been many valued contributors, but a few have stepped up to become maintainers that generously donate their time to guide the project, help out others, and manage the issues. The current list of maintainers are:

• @pynappo

Past maintainers:

(in alphabetical order)

• @cseickel
• @miversen33
• @nhat-vo
• @pysan3

Other Projects

The design is heavily inspired by these excellent plugins:

• lualine.nvim
• nvim-cokeline

Everything I know about writing a tree control in lua, I learned from:

• nvim-tree.lua