neo-tree.nvim as the split explorer (netrw + vim-vinegar-like behavior)

[yehorb]

Hi. I want to share my configuration for a neo-tree.nvim, which I use mostly as the split explorer. As there are no explicit examples for such a use case, I think this will be useful for future users that are looking for the split explorer setup.

I was a netrw + vim-vinegar user for a long time, as I usually only need to skim over the directory, and netrw is good enough for that. vim-vinegar made netrw easily accessible with the single "-" keymap.

But, netrw is far from perfect - its default keymaps are not intuitive at all, and I encountered visual bugs a lot, especially with the tree style listing (g:netrw_liststyle = 3).

Recently I have been switching from AstroNvim v2.x to AstroNvim v3.x and I finally decided to dive deeper into the neo-tree.nvim configuration and set it up to my liking. The core options are already there - the Neotree position=current reveal will open the working directory with focus on the current file, and there is an option to use neo-tree to open directories with hijack_netrw_behavior.

2 major things were lacking, though. There is no "-" keymap, and using the neo-tree in place messes up the alternate file.

Adding the "-" keymap was fairly easy - I set the global keymap for "-" to open the neo-tree in place if not already in the neo-tree buffer, and set the neo-tree specific window keymap to the simple function what will navigate to the current node's parent.

Correctly tracking the alternate file was a bit more interesting problem to solve. I decided to use the BufWinEnter event to store the alternate buffer number as a window variable on entering the neo-tree buffer. Then I set the global <C-^> keymap to a function that checks the variable and opens the relevant buffer if the variable is set. If the variable is not set, it uses the existing alternate buffer number.

1 minor thing was an annoying "Window settings restored" notification every time I opened a neo-tree buffer. I checked the source code and decided that I will just remove the augroup that produces the notification. The relevant function restores window-local options for the neo-tree buffer, and I am sure that I can do without this functionality; I have never set window-local options for neo-tree anyway.

Here is the final neo-tree.lua file from my plugins directory. It is lazy.nvim plugin spec, and it is not even a full spec, as I use AstorNvim, but the relevant functions and configuration is visible and should be easily portable to other plugin managers.

local function reveal_tree()
  if vim.bo.filetype ~= "neo-tree" then
    vim.cmd.Neotree { "position=current", "reveal" }
  end
end

local function reveal_parent(state)
  require("neo-tree.ui.renderer").focus_node(state, state.tree:get_node():get_parent_id())
end

local function edit_neo_tree_alternate_file()
  local alternate_nr = vim.w.neo_tree_alternate_nr or vim.fn.bufnr "#" ---@diagnostic disable-line: param-type-mismatch
  vim.w.neo_tree_alternate_nr = nil
  vim.cmd.buffer(alternate_nr)
end

return {
  "nvim-neo-tree/neo-tree.nvim",
  keys = {
    { "<leader>e", false },
    { "<leader>o", false },
    { "-", reveal_tree },
    { "<C-^>", edit_neo_tree_alternate_file },
  },
  opts = {
    filesystem = {
      hijack_netrw_behavior = "open_current",
      window = {
        mappings = {
          ["-"] = reveal_parent,
        },
      },
    },
  },
  config = function(_, opts)
    require("neo-tree").setup(opts)
    -- removes the "Window settings restored" message
    vim.api.nvim_del_augroup_by_name "NeoTree_BufLeave"
    local bufenter = function(data)
      local pattern = "neo%-tree [^ ]+ %[1%d%d%d%]"
      if string.match(data.file, pattern) then
        vim.w.neo_tree_alternate_nr = vim.fn.bufnr "#" ---@diagnostic disable-line: param-type-mismatch
      end
    end
    vim.api.nvim_create_autocmd({ "BufWinEnter" }, {
      group = vim.api.nvim_create_augroup("NeoTree_BufEnter", { clear = true }),
      pattern = "neo-tree *",
      callback = bufenter,
    })
  end,
}

I have been using this setup for the past week or so, and it feels familiar, but also better. neo-tree.nvim is a much better tree explorer than netrw - it is much more stable and has sensible keymaps, which are easier to customize. With additional functions from AstroNvim it covers all my directory browsing needs and some of my file-management needs.

Thanks, @cseickel for the nvim-tree.nvim plugin and to @mehalter for the AstroNvim config, you make my development time more enjoyable.

I hope you found this write-up useful, have a nice day, and happy nvimming!