Neo-tree File Browser
Neo-tree is a modern, Lua-native file explorer sidebar. It shows the directory tree, git file status, and LSP diagnostics inline — making it a rich file management panel.
Learning Focus
Neo-tree is best used alongside Telescope, not instead of it. Use Telescope to jump quickly; use Neo-tree to browse unfamiliar areas or visually confirm project structure.
Installation
lua/plugins/neo-tree.lua
return {
{
"nvim-neo-tree/neo-tree.nvim",
branch = "v3.x",
cmd = "Neotree",
keys = {
{ "<leader>e", "<cmd>Neotree toggle<cr>", desc = "Toggle file explorer" },
{ "<leader>E", "<cmd>Neotree focus<cr>", desc = "Focus file explorer" },
{ "<leader>be", "<cmd>Neotree buffers<cr>", desc = "Buffer explorer" },
{ "<leader>ge", "<cmd>Neotree git_status<cr>", desc = "Git explorer" },
},
dependencies = {
"nvim-lua/plenary.nvim",
"nvim-tree/nvim-web-devicons",
"MunifTanjim/nui.nvim",
},
opts = {
close_if_last_window = true,
window = {
width = 35,
mappings = {
["<space>"] = "none", -- don't let space trigger here
["l"] = "open",
["h"] = "close_node",
["Y"] = "copy_to_clipboard",
["P"] = { "toggle_preview", config = { use_float = true } },
},
},
filesystem = {
follow_current_file = { enabled = true },
hijack_netrw_behavior = "open_default",
filtered_items = {
visible = false,
hide_dotfiles = false, -- show dotfiles by default
hide_gitignored = true,
hide_by_name = {
"__pycache__", ".cache", "node_modules",
},
},
},
git_status = {
window = {
position = "float",
mappings = {
["A"] = "git_add_all",
["gu"] = "git_unstage_file",
["ga"] = "git_add_file",
["gr"] = "git_revert_file",
["gc"] = "git_commit",
["gp"] = "git_push",
["gg"] = "git_commit_and_push",
},
},
},
event_handlers = {
{
event = "file_opened",
handler = function()
require("neo-tree.command").execute({ action = "close" })
end,
},
},
},
},
}
Inside Neo-tree
| Key | Action |
|---|---|
| l | Open file / expand folder |
| h | Close folder / go up |
| a | Add new file (or folder if ends in /) |
| d | Delete |
| r | Rename |
| y | Copy file name |
| Y | Copy absolute path |
| c | Copy file |
| m | Move file |
| ? | Show all key bindings |
| q | Close Neo-tree |
| R | Refresh |
| H | Toggle hidden files |
| P | Preview file |
Sources / Views
Neo-tree has multiple "sources" — switch between them:
:Neotree filesystem → file tree (default)
:Neotree buffers → open buffers list
:Neotree git_status → git changed files
:Neotree toggle → toggle current source
Git Status Icons in Neo-tree
| Icon | Meaning |
|---|---|
| M | Modified |
| A | Added (staged) |
| ? | Untracked |
| D | Deleted |
| R | Renamed |
| U | Unmerged |
In LazyVim
LazyVim Context
LazyVim includes Neo-tree by default as its primary file explorer. It is highly integrated, using the exact keymaps recommended for a modern workflow.
| Aspect | Vanilla Neovim | LazyVim |
|---|---|---|
| Explorer Toggle | <leader>e | <leader>e or <leader>E |
| Git Status View | :Neotree git_status | <leader>ge |
| Configuration | Manual options block | Pre-configured with icons and optimal window size |