neo-tree.nvim

Neo-tree supports several sources to display different types of hierarchical data:

• filesystem: The default source. Used for browsing files, managing CWD, file operations (add/copy/delete/etc.), and monitoring git/LSP diagnostics.
• buffers: Displays a list of currently open buffers (similar to :ls). Use :Neotree buffers.
• git_status: Displays git status output in a tree layout. Supports adding, unstaging, reverting, and committing. Use :Neotree git_status.
• document_symbols: (Experimental) Lists symbols in the current document via LSP. Requires adding "document_symbols" to config.sources first. Use :Neotree document_symbols.
• External Sources: Additional sources can be added via extensions found in the Neo-tree wiki.

Neo-tree is highly customizable by replacing built-in functions with your own implementations.

• Renderers: Each node type (e.g., file, directory) uses a specified renderer, which is a list of component configurations rendered in order.
• Components: Each component is a function (built-in or custom) that returns the text and highlight group for that component.
• Customization Pattern: You can pass strings that identify built-in functions or provide your own Lua functions to handle rendering logic.

For detailed configuration, use :h neo-tree-configuration or visit the online documentation.

To install Neo-tree.nvim with packer.nvim, use the use function and specify the v3.x branch. Ensure plenary.nvim and nui.nvim are listed in requires.

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
  }
})

Neo-tree provides an events system to hook into lifecycle moments.

To display new data points related to your files:

1. Use the before_render event to gather the necessary data.
2. Create a custom component to display that data.
3. Reference your new component in the renderer for the relevant node type (e.g., file or directory).

Common use cases include responding to the "file_opened" event to trigger actions like clearing a search.

Once installed, you can open Neo-tree as a sidebar using the following command:

:Neotree

While inside a Neo-tree window, press ? to open the keyboard help menu.

The :Neotree command controls what Neo-tree displays and where it appears. Arguments can be passed as bare values or key=value pairs. All arguments are optional and can be specified in any order. Tab completion is supported for all arguments and paths.

Basic Usage:

• :Neotree (Default: filesystem source on the left)
• :Neotree filesystem reveal right (Opens file browser on the right, revealing the active file)
• :Neotree source=filesystem reveal=true position=right (Verbose version of the above)

For Neovim 0.12 and onwards, you can use the vim.pack API. This example includes the required dependencies and the recommended devicons plugin.

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",
})

To display icons for diagnostic errors/warnings in Neo-tree, you must define them in your Neovim configuration.

For Neovim v0.10+:

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

For older Neovim versions:

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" })

To install Neo-tree.nvim with lazy.nvim, add the following configuration to your plugin specs. It is recommended to include nvim-web-devicons for file icons. Note that lazy = false is used because Neo-tree will lazily load itself internally.

Required dependencies:

• nvim-lua/plenary.nvim
• MunifTanjim/nui.nvim

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

To inspect all default configuration options with their accompanying commentary directly within Neovim, run the following command after installation:

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

Use require('neo-tree').setup() to pass a configuration table of type neotree.Config. Note that calling setup() is only required for configuration; Neo-tree commands will work even without it.

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