Repository files navigation

Neo-tree is a Neovim plugin to browse the file system and other tree likestructures 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:

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

SeeWhat is a Breaking Change? for details.

SeeChangelog 3.0for breaking changes and deprecations in 3.0.

Aside from being polite about breaking changes, Neo-tree is also focused on thelittle details of user experience. Everything should work exactly as you wouldexpect a sidebar to work without all of the glitchy behavior that is normallyaccepted in (neo)vim sidebars. I can't stand glitchy behavior, and neithershould 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 plentyof room to display the whole tree.
• Neo-tree does not need to be manually refreshed(setuse_libuv_file_watcher = true)
• Neo-tree can intelligently follow the current file(setfollow_current_file.enabled = true)
• Neo-tree can sync its clipboard across multiple trees, either globally(within the same Neovim instance) or universally (across all Neoviminstances). Tryclipboard.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!

This plugin relies upon these two excellent library plugins:

• MunifTanjim/nui.nvim for all UIcomponents, including the tree!
• nvim-lua/plenary.nvim for backendutilities, such as scanning the filesystem.

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

• nvim-tree/nvim-web-deviconsfor file icons.
• antosha417/nvim-lsp-file-operationsfor LSP-enhanced renames/etc.
• folke/snacks.nvim for image previews,see Preview Mode section.
• snacks.renamecan also work with Neo-tree
• 3rd/image.nvim for image previews.
  • If both snacks.nvim and image.nvim are installed. Neo-tree currently will tryto preview with snacks.nvim first, then try image.nvim.
• s1n7ax/nvim-window-picker for_with_window_picker keymaps.

localadd=MiniDeps.addadd({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  }})

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",    },  },  {"antosha417/nvim-lsp-file-operations",dependencies= {"nvim-lua/plenary.nvim","nvim-neo-tree/neo-tree.nvim",-- makes sure that this loads after Neo-tree.    },config=function()require("lsp-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 optionsbo= {-- if the file type is one of following, the window will be ignoredfiletype= {"neo-tree","neo-tree-popup","notify"},-- if the buffer type is one of following, the window will be ignoredbuftype= {"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  }})

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

Seedoc/install.sh anddoc/install.ps1 forPOSIX/Windows respectively.

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

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'---@typeneotree.Configopts= {-- 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 tabpopup_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 buftypesopen_files_using_relative_paths=false,sort_case_insensitive=false,-- used when sorting files and directories in the treesort_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 descendantlydefault_component_configs= {container= {enable_character_fade=true,    },indent= {indent_size=2,padding=1,-- extra padding on left hand side-- indent guideswith_markers=true,indent_marker="│",last_indent_marker="└",highlight="NeoTreeIndentMarker",-- expander config, needed for nesting fileswith_expanders=nil,-- if nil and file nesting is enabled, will enable expandersexpander_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 availableifnode.type=="file"ornode.type=="terminal"thenlocalsuccess,web_devicons=pcall(require,"nvim-web-devicons")localname=node.type=="terminal"and"terminal"ornode.nameifsuccessthenlocaldevicon,hl=web_devicons.get_icon(name)icon.text=deviconoricon.texticon.highlight=hloricon.highlightendendend,-- 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 typeadded="",-- or "✚"modified="",-- or ""deleted="✖",-- this can only be used in the git_status sourcerenamed="󰁕",-- this can only be used in the git_status source-- Status typeuntracked="",ignored="",unstaged="󰄱",staged="",conflict="",      },    },-- If you don't want to use these columns, you can set `enabled = false` for each of them individuallyfile_size= {enabled=true,width=12,-- width of the columnrequired_width=64,-- min width of window required to show this column    },type= {enabled=true,width=10,-- width of the columnrequired_width=122,-- min width of window required to show this column    },last_modified= {enabled=true,width=20,-- width of the columnrequired_width=88,-- min width of window required to show this column    },created= {enabled=true,width=20,-- width of the columnrequired_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= {      ["<space>"]= {"toggle_node",nowait=false,-- disable `nowait` if you have existing combos starting with this char that you want to use      },      ["<2-LeftMouse>"]="open",      ["<cr>"]="open",      ["<esc>"]="cancel",-- close preview or floating neo-tree window      ["P"]= {"toggle_preview",config= {use_float=true,use_snacks_image=true,use_image_nvim=true,        },      },-- Read `# Preview Mode` for more information      ["l"]="focus_preview",      ["S"]="open_split",      ["s"]="open_vsplit",-- ["S"] = "split_with_window_picker",-- ["s"] = "vsplit_with_window_picker",      ["t"]="open_tabnew",-- ["<cr>"] = "open_drop",-- ["t"] = "open_tab_drop",      ["w"]="open_with_window_picker",--["P"] = "toggle_preview", -- enter preview mode, which shows the current node without focusing      ["C"]="close_node",-- ['C'] = 'close_all_subnodes',      ["z"]="close_all_nodes",--["Z"] = "expand_all_nodes",--["Z"] = "expand_all_subnodes",      ["a"]= {"add",-- this command supports BASH style brace expansion ("x{a,b,c}" -> xa,xb,xc). see `:h neo-tree-file-actions` for details-- some commands may take optional config options, see `:h neo-tree-mappings` for detailsconfig= {show_path="none",-- "none", "relative", "absolute"        },      },      ["A"]="add_directory",-- also accepts the optional config.show_path option like "add". this also supports BASH style brace expansion.      ["d"]="delete",      ["r"]="rename",      ["b"]="rename_basename",      ["y"]="copy_to_clipboard",      ["x"]="cut_to_clipboard",      ["p"]="paste_from_clipboard",      ["<C-r>"]="clear_clipboard",      ["c"]="copy",-- takes text input for destination, also accepts the optional config.show_path option like "add":-- ["c"] = {--  "copy",--  config = {--    show_path = "none" -- "none", "relative", "absolute"--  }--}      ["m"]="move",-- takes text input for destination, also accepts the optional config.show_path option like "add".      ["q"]="close_window",      ["R"]="refresh",      ["?"]="show_help",      ["<"]="prev_source",      [">"]="next_source",      ["i"]="show_file_details",-- ["i"] = {--   "show_file_details",--   -- format strings of the timestamps shown for date created and last modified (see `:h os.date()`)--   -- both options accept a string or a function that takes in the date in seconds and returns a string to display--   -- config = {--   --   created_format = "%Y-%m-%d %I:%M %p",--   --   modified_format = "relative", -- equivalent to the line below--   --   modified_format = function(seconds) return require('neo-tree.utils').relative_date(seconds) end--   -- }-- },    },  },nesting_rules= {},filesystem= {filtered_items= {visible=false,-- when true, they will just be displayed differently than normal itemshide_dotfiles=true,hide_gitignored=true,hide_ignored=true,-- hide files that are ignored by other gitignore-like files-- other gitignore-like files, in descending order of precedence.ignore_files= {".neotreeignore",".ignore",-- ".rgignore"      },hide_hidden=true,-- only works on Windows for hidden files/directorieshide_by_name= {--"node_modules"      },hide_by_pattern= {-- uses glob style patterns--"*.meta",--"*/src/*/tsconfig.json",      },always_show= {-- remains visible even if other settings would normally hide it--".gitignored",      },always_show_by_pattern= {-- uses glob style patterns--".env*",      },never_show= {-- remains hidden even if visible is toggled to true, this overrides always_show--".DS_Store",--"thumbs.db"      },never_show_by_pattern= {-- uses glob style patterns--".null-ls_*",      },    },follow_current_file= {enabled=false,-- This will find and focus the file in the active buffer every time--               -- the current file is changed while the tree is open.leave_dirs_open=false,-- `false` closes auto expanded dirs, such as with `:Neotree reveal`    },group_empty_dirs=false,-- when true, empty folders will be grouped togetherhijack_netrw_behavior="open_default",-- netrw disabled, opening a directory opens neo-tree-- in whatever position is specified in window.position-- "open_current",  -- netrw disabled, opening a directory opens within the-- window like netrw would, regardless of window.position-- "disabled",    -- netrw left alone, neo-tree does not handle opening dirsuse_libuv_file_watcher=false,-- This will use the OS level file watchers to detect changes-- instead of relying on nvim autocmd events.window= {mappings= {        ["<bs>"]="navigate_up",        ["."]="set_root",        ["H"]="toggle_hidden",        ["/"]="fuzzy_finder",        ["D"]="fuzzy_finder_directory",        ["#"]="fuzzy_sorter",-- fuzzy sorting using the fzy algorithm-- ["D"] = "fuzzy_sorter_directory",        ["f"]="filter_on_submit",        ["<c-x>"]="clear_filter",        ["[g"]="prev_git_modified",        ["]g"]="next_git_modified",        ["o"]= {"show_help",nowait=false,config= {title="Order by",prefix_key="o"},        },        ["oc"]= {"order_by_created",nowait=false },        ["od"]= {"order_by_diagnostics",nowait=false },        ["og"]= {"order_by_git_status",nowait=false },        ["om"]= {"order_by_modified",nowait=false },        ["on"]= {"order_by_name",nowait=false },        ["os"]= {"order_by_size",nowait=false },        ["ot"]= {"order_by_type",nowait=false },-- ['<key>'] = function(state) ... end,      },fuzzy_finder_mappings= {-- define keymaps for filter popup window in fuzzy_finder_mode        ["<down>"]="move_cursor_down",        ["<C-n>"]="move_cursor_down",        ["<up>"]="move_cursor_up",        ["<C-p>"]="move_cursor_up",        ["<esc>"]="close",        ["<S-CR>"]="close_keep_filter",        ["<C-CR>"]="close_clear_filter",        ["<C-w>"]= {"<C-S-w>",raw=true },        {-- normal mode mappingsn= {            ["j"]="move_cursor_down",            ["k"]="move_cursor_up",            ["<S-CR>"]="close_keep_filter",            ["<C-CR>"]="close_clear_filter",            ["<esc>"]="close",          }        }-- ["<esc>"] = "noop", -- if you want to use normal mode-- ["key"] = function(state, scroll_padding) ... end,      },    },commands= {},-- Add a custom command or override a global one using the same function name  },buffers= {follow_current_file= {enabled=true,-- This will find and focus the file in the active buffer every time--              -- the current file is changed while the tree is open.leave_dirs_open=false,-- `false` closes auto expanded dirs, such as with `:Neotree reveal`    },group_empty_dirs=true,-- when true, empty folders will be grouped togethershow_unloaded=true,window= {mappings= {        ["d"]="buffer_delete",        ["bd"]="buffer_delete",        ["<bs>"]="navigate_up",        ["."]="set_root",        ["o"]= {"show_help",nowait=false,config= {title="Order by",prefix_key="o"},        },        ["oc"]= {"order_by_created",nowait=false },        ["od"]= {"order_by_diagnostics",nowait=false },        ["om"]= {"order_by_modified",nowait=false },        ["on"]= {"order_by_name",nowait=false },        ["os"]= {"order_by_size",nowait=false },        ["ot"]= {"order_by_type",nowait=false },      },    },  },git_status= {window= {position="float",mappings= {        ["A"]="git_add_all",        ["gu"]="git_unstage_file",        ["gU"]="git_undo_last_commit",        ["ga"]="git_add_file",        ["gr"]="git_revert_file",        ["gc"]="git_commit",        ["gp"]="git_push",        ["gg"]="git_commit_and_push",        ["o"]= {"show_help",nowait=false,config= {title="Order by",prefix_key="o"},        },        ["oc"]= {"order_by_created",nowait=false },        ["od"]= {"order_by_diagnostics",nowait=false },        ["om"]= {"order_by_modified",nowait=false },        ["on"]= {"order_by_name",nowait=false },        ["os"]= {"order_by_size",nowait=false },        ["ot"]= {"order_by_type",nowait=false },      },    },  },})

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

To see all of the default config options with commentary, you can view it onlineatlua/neo-tree/defaults.lua. You can also paste itinto 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 single:Neotree command accepts a range of arguments that give you fullcontrol over the details of what and where it will show. For example, the followingcommand will open a file browser on the right hand side, "revealing" the currentlyactive file:

:Neotree filesystem reveal right

Arguments can be specified as either a key=value pair or just as the value. Thekey=value form is more verbose but may help with clarity. For example, the commandabove 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 commandwithout 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 usingthe default config.

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 startthem with/ or./.

Here is the full list of arguments you can use:

What to do. Can be one of:

What to show. Can be one of:

Where to show it, can be one of:

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

The directory to set as the root/cwd of the specified window. If you include adirectory as one of the arguments, it will be assumed to be this option, youdon'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 thecurrent file. For example:

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

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

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

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

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

A path to a file to reveal. This supersedes the "reveal" flag so there is noneed to specify both. Use this if you want to reveal something other than thecurrent file. If you include a path to a file as one of the arguments, it willbe assumed to be this option. Like "dir", you can pass any value that can bepassed 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 isfocused on the file under the cursor using the<cfile> keyword:

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

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

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

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

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

:edit .:[v]split .

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

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

The default source isfilesystem, which displays your files and folders. Thisis 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

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

:Neotree buffers

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

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

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

:Neotree float git_status git_base=main

The document_symbols source lists the symbols in the current document obtainedby the LSP request "textDocument/documentSymbols". It currently supports thefollowing 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 firstadd"document_symbols" toconfig.sources and open it with the command

:Neotree document_symbols

There are more sources available as extensions that are managed outside of thisrepository. See thewiki formore information.

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

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

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

:h neo-tree-preview-mode

Preview mode will temporarily show whatever file the cursor is on withoutswitching focus from the Neo-tree window. By default, files will be previewedin a new floating window. This can also be configured to automatically choosean 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. Whenuse_float = false, the window that was taken over by preview mode will revertback to whatever was shown in that window before preview mode began.

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

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

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

If you havefolke/snacks.nvimor3rd/image.nvim installed, preview modesupports image rendering by default using kitty graphics protocol or ueberzug(Video).

However, if you do not want this feature, you can disable it by settinguse_snacks_image = false oruse_image_nvim = false in the mappings configmentioned above.

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

Each node in the tree is created from the renderer specified for the given nodetype, 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. Thosefunctions simply return the text and highlight group for the component.

Additionally, there is an events system that you can hook into. If you want toshow some new data point related to your files, gather it in thebefore_renderevent, create a component to display it, and reference that component in therenderer for thefile and/ordirectory type.

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

Recipes for customizations can be found on thewiki. Recipesinclude things like adding a component to show theHarpoon index for files, orresponding to the"file_opened" event to auto clear the search when you open afile.

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

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

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

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

This project will have releases and release tags that follow a simplifiedSemantic Versioning scheme. The quickstart instructions will always refer to thelatest stable major version. Following themain branch is for contributorsand those that always want bleeding edge. There will be branches forv1.x,v2.x, etc which will receive updates after a short testing period inmain. You should be safe to follow those branches and be sure your treewon't break in an update. There will also be tags for each release pushed tothose branches namedv1.1,v1.2, etc. If stability is critical to you,or a bug accidentally makes it intov3.x, you can use those tags instead.It's possible we may backport bug fixes to those tags, but no guarantees onthat.

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

Neo-tree follows in the spirit of plugins likelualine.nvim andnvim-cokeline. Everything will beconfigurable and take either strings, tables, or functions. You can take sanedefaults or build your tree items from scratch. There should be the ability toadd any features you can think of through existing hooks in the setup function.

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

• vim commands (:Neotree)
• configuration options that are passed into thesetup() 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 consideredpart of the public API, please open an issue so we can discuss it.

Contributions are encouraged. Please seeCONTRIBUTING formore details.

First and foremost, this project is a community endeavor and would not survivewithout the constant stream of features and bug fixes that comes from thatcommunity. There have been many valued contributors, but a few have stepped upto 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

(in alphabetical order)

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

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