refactor(#2988): migrate change_dir functionality to Explorer class #3233

Uanela · 2025-12-27T12:08:31Z

This refactor moves directory change operations from the actions.root module into the Explorer class, improving code organization and encapsulation.

Changes:

Moved change_dir, force_dirchange, and dir_up methods to Explorer class
Deleted actions/root/change-dir.lua and actions/root/dir-up.lua files
Removed actions.root module from actions/init.lua
Added helper methods: is_window_event, clean_input_cwd, prevent_cwd_change,
add_profiling_to, should_change_dir, and cd
Introduced explorer_fn helper in nvim-tree.lua for safe explorer method calls
Updated all references to use explorer methods instead of actions.root
Renamed M.current_tab to self.current_tab for proper class encapsulation
Renamed internal _foldername parameter to folder_name for consistency

Resolves #2988

…all places using change_dir to use it from explorer

Uanela · 2025-12-27T12:15:47Z

@alex-courtis this one was really interesting to refactor, I was able to really strengthen my knowledge in lua classes even though the problems weren't that hard.

I will get into the next ones.

… using it

lua/nvim-tree/explorer/init.lua

lua/nvim-tree/lib.lua

lua/nvim-tree/explorer/init.lua

lua/nvim-tree/api.lua

lua/nvim-tree.lua

lua/nvim-tree/explorer/init.lua

alex-courtis · 2025-12-28T03:07:56Z

even though the problems weren't that hard.

You underestimate yourself. This was not an easy change.

FYI you now have permissions to push branches directly to this repo, so you don't need to use your fork next time.

…above_cwd config path

Uanela · 2025-12-28T10:53:04Z

Prev changes made and tested.
Moved Api.tree.change_root_to_node into Explorer

Just a question

what is the profiling for?

alex-courtis · 2026-01-02T03:45:52Z

Base Test Case Failure

Setup

cd /tmp
git clone git@github.com:rvaiya/keyd.git

change_root_to_node - fail

Open nvim in /tmp/keyd

:NvimTreeOpen

<C-]> data

Expected: data is new root
Actual: root has not changed

After R the correct root is shown

Analysis

core.init(foldername) destroys the explorer and creates a new one, hence the call toself.renderer:draw() fails as self has been destroyed.

We can debug this by adding lines that note the explorer's unique id:

-- in constructor
  self.uid_explorer = vim.loop.hrtime()
  log.line("dev", "Explorer:new uid_explorer=%d", self.uid_explorer)

-- destructor
function Explorer:destroy()
  log.line("dev", "Explorer:destroy uid_explorer=%d", self.uid_explorer)

-- change
function Explorer:force_dirchange(foldername, should_open_view)
  log.line("dev", "Explorer:force_dirchange uid_explorer=%d foldername=%s", self.uid_explorer, foldername)
  ---
    else
      log.line("dev", "Explorer:change_dir uid_explorer=%d calling renderer:draw()")
    self.renderer:draw()
   ---

You can see that the old explorer instance is destroyed and a new on created, but draw is called on the old one:

tail: '/home/alex/.local/state/nvim/nvim-tree.log' has appeared;  following new file
[2026-01-02 14:23:41] [dev] Explorer:new uid_explorer=5572366830148
[2026-01-02 14:23:45] [dev] Explorer:change_dir uid_explorer=5572366830148 input_cwd=/tmp/keyd/data
[2026-01-02 14:23:45] [dev] Explorer:force_dirchange uid_explorer=5572366830148 foldername=/tmp/keyd/data
[2026-01-02 14:23:45] [dev] Explorer:destroy uid_explorer=5572366830148
[2026-01-02 14:23:45] [dev] Explorer:new uid_explorer=5576582353809
[2026-01-02 14:23:45] [dev] Explorer:change_dir uid_explorer=5572366830148 calling renderer:draw()

Recommendation

Revert to old behaviour of getting the new explorer before drawing:

    if should_open_view then
      require("nvim-tree.lib").open()
    else
      -- TODO #2255
      -- The call to core.init destroyed this Explorer instance hence we need to fetch the new instance.
      local explorer = core.get_explorer()
      if explorer then
        explorer.renderer:draw()
      end
    end

This is not ideal at all, as an Explorer method from a destroyed instance is running.
This is a pragmatic, temporary solution. We don't have much option as core owns the singleton Explorer.
Once #2255 is complete and core is gone, it will be resolved.
There should be no issues with resource leaks as Explorer:destroy is called.
There should be no memory leaks as the old explorer will be garbage collected when this method ends.

alex-courtis · 2026-01-02T03:47:10Z

what is the profiling for?

It's used to report performance of costly operations. We ask users to enable it when reporting Performance Issues

alex-courtis · 2026-01-02T04:21:33Z

Base Test Case Plan

Change To Directory Node

Open nvim in /tmp/keyd
:NvimTreeOpen

<C-]> data

Expected: tree root is data

Change To File Node

Open nvim in /tmp/keyd
:NvimTreeOpen

Navigate to data/unicode.txt

<C-]> unicode.txt

Expected: tree root changes to data

Change Up Root Node

Open nvim in /tmp/keyd
:NvimTreeOpen

<C-]> on root

Expected: tree root changes /tmp

is_window_event

We must create a test cases that results in is_window_event returning false when calling Explorer:change_dir

Option Test Case Plan

sync_root_with_cwd = true

Open nvim in /tmp/keyd

:NvimTreeOpen

:cd data

Expected: tree root should change to data

nvim-tree.lua change_root

Open nvim in home

:NvimTreeOpen
:e /tmp/keyd/README.md
:NvimTreeFindFile!

Expected: tree root change to /tmp/keyd

nvim-tree.lua open_on_directory

Set hijack_directories = true

Open nvim in home
:NvimTreeOpen
change to previous win
:e /tmp

Expected: tree with root /tmp is opened

config.actions.change_dir.enable = true

Open nvim in /tmp/keyd

:NvimTreeOpen

<C-]> data
:pwd
Expected: /tmp/keyd/data

-
:pwd
Expected: /tmp/keyd

-
:pwd
Expected: /tmp

config.actions.change_dir.enable = false

Open nvim in /tmp/keyd

:NvimTreeOpen

<C-]> data
:pwd
Expected: /tmp/keyd

-
:pwd
Expected: /tmp/keyd

config.actions.change_dir.restrict_above_cwd = true

Set config.actions.change_dir.enable = true

Open nvim in /tmp/keyd

:NvimTreeOpen

-
Expected: no change dir

:pwd
Expected: /tmp/keyd

config.actions.change_dir.global = true

Set config.actions.change_dir.enable = true

Open nvim in /tmp/keyd
:NvimTreeOpen

<C-]> data
:pwd
Expected: /tmp/keyd/data

Switch to editor window
:pwd
Expected: /tmp/keyd

alex-courtis

This has turned out to be much harder than anticipated... there were a lot of landmines. We are close, please:

Test!
Update the remaining config paths #3233 (comment) #3233 (comment)
Apply the sad hack to force_dirchange #3233 (comment)
Add param annotation #3233 (comment)

alex-courtis · 2026-01-02T03:49:12Z

lua/nvim-tree/explorer/init.lua

+---@private
+---@return boolean
+function Explorer:should_change_dir()
+  return config.enable and vim.tbl_isempty(vim.v.event)


Suggested change

return config.enable and vim.tbl_isempty(vim.v.event)

return config.actions.change_dir.enable and vim.tbl_isempty(vim.v.event)

alex-courtis · 2026-01-02T03:50:22Z

lua/nvim-tree/explorer/init.lua

+  local valid_dir = vim.fn.isdirectory(foldername) == 1 -- prevent problems on non existing dirs
+  if valid_dir then
+    if self:should_change_dir() then
+      self:cd(config.global, foldername)


Suggested change

self:cd(config.global, foldername)

self:cd(config.actions.change_dir.global, foldername)

alex-courtis · 2026-01-02T03:53:09Z

lua/nvim-tree/explorer/init.lua

+function Explorer:change_dir_to_node(node)
+  if node.name == ".." or node:is(RootNode) then
+    self:change_dir("..")
+  elseif node:is(FileNode) and node.parent ~= nil then
+    self:change_dir(node.parent:last_group_node().absolute_path)
+  else
+    node = node:as(DirectoryNode)
+    if node then
+      self:change_dir(node:last_group_node().absolute_path)
+    end
+  end
+end


Many thanks for going the extra mile here - this looks so much better as this functionality should be owned by the Explorer instance.

Please do remember to add parameter annotations.

Uanela · 2026-01-05T06:25:29Z

I will get back asap

Uanela · 2026-01-15T10:16:48Z

Hi @alex-courtis, I am just commenting to say that I am alive :).

As I state before I've been practicing on some few small things so that I can better contribute. Currently I can contribute, I can understand the things you ask me to change and so on (sometimes need to do some researches but is ok)

But there some things that I feel like "I should know this from the beginning", and I believe by improving just little bit I can better contribute to this project and start fixing bugs, not losing obvious things when doing the tasks

and so on. I will be making the changes shortly.

Btw I created a repo to help any people now or in the future that I pretty sure will enhance their knowledge base on playing around with lua + neovim, because lua is not neovim, so there is a need to learn

lua for neovim (basically learn the apis and some real world things that can be done). The aim of the repo is to guide the user through a series of challenges (leveling up the difficulty on each) so that they

easily make progress on their paths, I did this in the past with JavaScript/TypeScript and the results are real real GOOD for me today.

Maybe you can check and reference for any new coming contributor that enters on a situation similar to mine.

the repo is Neovim Plugin Challenges.

alex-courtis · 2026-01-16T00:44:57Z

Maybe you can check and reference for any new coming contributor that enters on a situation similar to mine.

the repo is Neovim Plugin Challenges.

That is incredible! You've looked into a great variety of apis - properties, commands, uvlib etc - AND patterns like events.

I've put it on the wiki, if that's OK with you: https://github.com/nvim-tree/nvim-tree.lua/wiki/Development

nowadays checking with AI also (which many will not admit)

There is no shame at all - you acknowledge it (thus own it) and will benefit from it.

Uanela added 6 commits December 9, 2025 16:43

chore: moving root action dir-up to explorer class

6b1f5b8

chore(explorer): moving requires to top level

41585a8

wip(explorer): moved all change-dir functions to explorer class

a12890c

wip(explorer): rename M.current_tab to self.current_tab

fd5ee1d

chore(explorer): move change_dir root action to explorer and replace …

85b621b

…all places using change_dir to use it from explorer

refactor(explorer): changing _foldername to folder_name

896e629

Uanela requested review from Akmadan23 and alex-courtis December 27, 2025 12:08

merge with master

2ea9992

Uanela removed the request for review from Akmadan23 December 27, 2025 12:15

wip(explorer): rename expand method to expand_dir_node and all places…

5084dd4

… using it

alex-courtis requested changes Dec 28, 2025

View reviewed changes

Uanela added 3 commits December 28, 2025 11:46

wip(explorer): mark private methods and remove add_profiling_to method

d5b8ead

fix: allow changing root to file`s parent directory and fix restrict_…

0d6eefd

…above_cwd config path

refactor(api): moving change_root_to_node to Explorer:change_dir_to_node

db36b04

Uanela requested a review from alex-courtis December 28, 2025 10:50

alex-courtis requested changes Jan 2, 2026

View reviewed changes

alex-courtis changed the title ~~refactor(explorer): migrate change_dir functionality to Explorer class~~ refactor(#3225): migrate change_dir functionality to Explorer class Jan 3, 2026

alex-courtis changed the title ~~refactor(#3225): migrate change_dir functionality to Explorer class~~ refactor(#2988): migrate change_dir functionality to Explorer class Jan 3, 2026

alex-courtis mentioned this pull request Jan 5, 2026

refactor(#3225): multi instance - move expand actions to nodes #3234

Open

	return config.enable and vim.tbl_isempty(vim.v.event)
	return config.actions.change_dir.enable and vim.tbl_isempty(vim.v.event)

	self:cd(config.global, foldername)
	self:cd(config.actions.change_dir.global, foldername)

Uh oh!

refactor(#2988): migrate change_dir functionality to Explorer class #3233

Are you sure you want to change the base?

refactor(#2988): migrate change_dir functionality to Explorer class #3233

Uh oh!

Conversation

Uanela commented Dec 27, 2025 • edited by alex-courtis Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uanela commented Dec 27, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

alex-courtis commented Dec 28, 2025

Uh oh!

Uanela commented Dec 28, 2025

Just a question

Uh oh!

alex-courtis commented Jan 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Base Test Case Failure

Setup

change_root_to_node - fail

Analysis

Recommendation

Uh oh!

alex-courtis commented Jan 2, 2026

Uh oh!

alex-courtis commented Jan 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Base Test Case Plan

Change To Directory Node

Change To File Node

Change Up Root Node

is_window_event

Option Test Case Plan

sync_root_with_cwd = true

nvim-tree.lua change_root

nvim-tree.lua open_on_directory

config.actions.change_dir.enable = true

config.actions.change_dir.enable = false

config.actions.change_dir.restrict_above_cwd = true

config.actions.change_dir.global = true

Uh oh!

alex-courtis left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alex-courtis Jan 2, 2026

Choose a reason for hiding this comment

Uh oh!

alex-courtis Jan 2, 2026

Choose a reason for hiding this comment

Uh oh!

alex-courtis Jan 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uanela commented Jan 5, 2026

Uh oh!

Uanela commented Jan 15, 2026

Uh oh!

alex-courtis commented Jan 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uanela commented Dec 27, 2025 •

edited by alex-courtis

Loading

alex-courtis commented Jan 2, 2026 •

edited

Loading

alex-courtis commented Jan 2, 2026 •

edited

Loading

alex-courtis left a comment •

edited

Loading