feat: add TreePreOpen event

[devansh08]

This adds 2 new events TreePreOpen and TreePreClose, which get triggered before TreeOpen and TreeClose events. They work similar to TreeOpen and TreeClose, in terms of the handler function.

This should help running logic before the NvimTree window is created or removed.

Let me know your thoughts.
Thanks!

[gegoune]

Could you please give us some examples why is it needed?

[devansh08]

So in my personal setup, I wanted a way to auto adjust split sizes in a tabpage, but the opening/closing of the NvimTree window would usually reset the layout. Also, none of the builtin Win events in NeoVim get triggered before a window is created or removed; so I wasn't able to use those either.

When I saw the TreeOpen event, I thought to add this TreePreOpen event, which is what I needed.

Frankly I don't currently have a use of TreePreClose, but just added it for symmetry :)

[alex-courtis]

1. Closes do not fire when window is closed via, say, :q. They only fire when :NvimTreeClose or API close is called. This is existing behaviour.

2. Open events are sometimes called twice: once in lib.open and again in view.open. This is consistent with existing behaviour.

Test Case:

-- subscribe to events
api.events.subscribe(api.events.Event.TreePreOpen, function(data)
  log.line("dev", "Event.TreePreOpen %s", vim.inspect(data))
end)

api.events.subscribe(api.events.Event.TreeOpen, function(data)
  log.line("dev", "Event.TreeOpen %s", vim.inspect(data))
end)

api.events.subscribe(api.events.Event.TreePreClose, function(data)
  log.line("dev", "Event.TreePreClose %s", vim.inspect(data))
end)

api.events.subscribe(api.events.Event.TreeClose, function(data)
  log.line("dev", "Event.TreeClose %s", vim.inspect(data))
end)

-- map 
vim.keymap.set("n", "<leader>c", function() api.tree.open({ current_window = true }) end,  { noremap = true })
vim.keymap.set("n", "<leader>n", function() api.tree.open({ current_window = false }) end, { noremap = true })

Open in current then :NvimTreeClose, expected:

[2025-04-13 09:28:22] [dev] Event.TreePreOpen nil
[2025-04-13 09:28:22] [dev] Event.TreeOpen nil
[2025-04-13 09:28:31] [dev] Event.TreePreClose nil
[2025-04-13 09:28:31] [dev] Event.TreeClose nil

Open in new then :NvimTreeClose, double opens, demonstrates 2

[2025-04-13 09:29:08] [dev] Event.TreePreOpen nil
[2025-04-13 09:29:08] [dev] Event.TreePreOpen nil
[2025-04-13 09:29:08] [dev] Event.TreeOpen nil
[2025-04-13 09:29:08] [dev] Event.TreeOpen nil
[2025-04-13 09:29:13] [dev] Event.TreePreClose nil
[2025-04-13 09:29:13] [dev] Event.TreeClose nil

Open two windows, open in current, then :q. No close event, demonstrates 1

[2025-04-13 09:30:53] [dev] Event.TreePreOpen nil
[2025-04-13 09:30:53] [dev] Event.TreeOpen nil
NOTHING HERE!

[alex-courtis]

At a minimum we need to fix 2. This is a bug and will be more of a problem for PreOpen events than the Open event, as users are more likely to be executing non-idempotent actions during PreOpen.

How? I reckon we could move it down into view:
There are two entry points open_in_win and open. The latter fires the event, the former does not.
We could move the event dispatch from lib to view. I think that's enough as they are the only places that actually creates the tree buffer.

[alex-courtis]

I'd also like to fix 1. Events not firing is not acceptable and we're compounding the problem with a new event. It should be achievable via a vim event listener.

What are your thoughts on all of this @gegoune ?

[alex-courtis]

I've invited you to write access to this project @devansh08 ; you can push directly instead of having to fork every time.

[devansh08]

Sure @alex-courtis, will take a look at and try to implement separately what you have suggested for these cases. Open to thoughts from others as well.

[devansh08]

There are two entry points open_in_win and open. The latter fires the event, the former does not. We could move the event dispatch from lib to view. I think that's enough as they are the only places that actually creates the tree buffer.

So in lib, the open event is fired from lib.open(), which calls either view.open_in_win() or view.open(). I think it would be better to remove the event dispatch from view and leave it in lib, so that it fires once for both open_in_win and open. Unless there is some reason to not fire the event when opening in current window ?

Events not firing is not acceptable and we're compounding the problem with a new event. It should be achievable via a vim event listener.

For this, I see that NvimTreeClose triggers WinClosed event, via vim.api.nvim_win_close. So I'm thinking we can make autocmds for WinClosed which can dispatch TreeClose event; and QuitPre for TreePreClose event.
QuitPre fires before WinClosed and it seems like the buffer still exists while its fired. So it looks to me like the logical place to keep the PreClose dispatch.

vim.api.nvim_create_autocmd("WinClosed", { pattern = "*", callback = function(e) print("WinClosed: " .. vim.inspect(e)) end })
vim.api.nvim_create_autocmd("QuitPre", { pattern = "*", callback = function(e) print("QuitPre: " .. vim.inspect(e)) end })

-- Running `:q` in the NvimTree buffer (with current_window true or false)
--[[ Output:
QuitPre: {
  buf = 9,
  event = "QuitPre",
  file = "/home/devansh/NvimTree_1",
  id = 146,
  match = "/home/devansh/NvimTree_1"
}
WinClosed: {
  buf = 9,
  event = "WinClosed",
  file = "1011",
  id = 145,
  match = "1011"
}
]]

Thoughts ?

@alex-courtis @gegoune

[alex-courtis]

So in lib, the open event is fired from lib.open(), which calls either view.open_in_win() or view.open(). I think it would be better to remove the event dispatch from view and leave it in lib, so that it fires once for both open_in_win and open. Unless there is some reason to not fire the event when opening in current window ?

Unfortunately lib.open is only one place that will open the tree; there are many other calls into view that will open the tree. create_buffer is the one place that all the open paths will reach, hence it should stay down there.

[alex-courtis]

For this, I see that NvimTreeClose triggers WinClosed event, via vim.api.nvim_win_close. So I'm thinking we can make autocmds for WinClosed which can dispatch TreeClose event; and QuitPre for TreePreClose event.
QuitPre fires before WinClosed and it seems like the buffer still exists while its fired. So it looks to me like the logical place to keep the PreClose dispatch.

Sounds great... it will be a pleasure to have complete and reliable events!

[devansh08]

So in lib, the open event is fired from lib.open(), which calls either view.open_in_win() or view.open(). I think it would be better to remove the event dispatch from view and leave it in lib, so that it fires once for both open_in_win and open. Unless there is some reason to not fire the event when opening in current window ?

Unfortunately lib.open is only one place that will open the tree; there are many other calls into view that will open the tree. create_buffer is the one place that all the open paths will reach, hence it should stay down there.

Ah, I see... Alright, will remove the event dispatch from lib.open and add it to view.open_in_win.

[alex-courtis]

Removed invalid events._dispatch_on_tree_pre_open() in lib.lua

Close, other windows present:

• :q TreePreClose not called
• :NvimTreeClose

Open:

• vim.keymap.set("n", "<leader>c", function() api.tree.open({ current_window = true }) end, { noremap = true }) TreePreOpen not called
• vim.keymap.set("n", "<leader>n", function() api.tree.open({ current_window = false }) end, { noremap = true })
• :NvimTreeOpen
• :NvimTreeToggle

The open case seems to be resolved if a matching events._dispatch_on_tree_pre_open() is added to view.open_in_win

The close case is problematic; needs some thought.

See #3105 (comment)

[alex-courtis]

Apologies for not asking; in the interest of speed I merged #3107 and rebased this branch.

[alex-courtis]

Looking at :help WinClosed it seems that it's actually a "pre close" event.

add debug

  -- Handles event dispatch when tree is closed by `:q`
  create_nvim_tree_autocmd("WinClosed", {
    pattern = "*",
    ---@param ev vim.api.keyset.create_autocmd.callback_args
    callback = function(ev)
      if vim.api.nvim_get_option_value("filetype", { buf = ev.buf }) == "NvimTree" then
        log.line("dev", "au WinClosed\nev=%s\nwins=%s", vim.inspect(ev), vim.inspect(vim.api.nvim_list_wins()))
        require("nvim-tree.events")._dispatch_on_tree_close()
      end
    end,
  })

shows

[2025-04-20 10:19:53] [dev] au WinClosed
ev={
  buf = 2,
  event = "WinClosed",
  file = "1002",
  group = 11,
  id = 21,
  match = "1002"
}
wins={ 1002, 1000 }

That resolves the pre close event problem - this event is pre close rather than close.

Open question: how to we fire the closed event?

Edit: suggestion: don't have a PreClose event:
WinClosed has no matching "Post" and there's no easy way to hook this via other buffer events with unpredictable order.
Matching vim event behaviour is acceptable: if it doesn't have an event, we don't need to either.

• Remove TreePreClose
• Accept that TreeClose is a "Pre" event, to match WinClosed, so leave create_nvim_tree_autocmd("WinClosed" as it is.
• Document that TreeClose is actually "Pre" event. It wasn't correct or reliable before, hence we're not breaking anything, just fixing a bug.

[alex-courtis]

Apologies for the long train of thought for what is now a small change. Action needed:

• Add _dispatch_on_tree_pre_open to view.open_in_win
• Remove TreePreClose event
• Document that TreeClose occurs before the window is closed, at the time of WinClosed

[devansh08]

suggestion: don't have a PreClose event:
WinClosed has no matching "Post" and there's no easy way to hook this via other buffer events with unpredictable order.
Matching vim event behaviour is acceptable: if it doesn't have an event, we don't need to either.

Yeah that makes sense. The best that could be done is a pre and post on buffer close rather than window close, using QuitPre and WinClosed. But probably does not make sense to do so, since open events are window based.

Will remove TreePreClose.

[alex-courtis]

All test cases from both PRs successful.

Many thanks for this most difficult contribution.

IMO events are the most difficult bit of vim to get right.

[devansh08]

Thanks for the help along the way! 😃