feat(#2994): add visual selection operations

[v3ceban]

Add visual selection operations

Closes #2994
See also: #2993

Summary

Adds visual selection support to nvim-tree. Users can V or v + motion to select a range of nodes and operate on them with a single keypress, matching standard Vim visual mode behavior.

Supported operations:

• Toggle bookmark (m)
• Copy (c)
• Cut (x)
• Delete (d and Del) -- single confirmation prompt for the entire selection
• Trash (D) -- single confirmation prompt for the entire selection

Design

Existing API functions (api.fs.copy.node, api.fs.cut, api.fs.remove, api.fs.trash, api.marks.toggle) are now mode-dependent -- no new API functions are added. When called in visual mode they operate on the selected range; in normal mode they behave exactly as before.

Default keymaps use { "n", "x" } mode tables so the same key works in both modes. The g? help window shows a mode column (e.g. n, nx) for each mapping.

• Visual range detection uses vim.fn.line("v") / vim.fn.line(".") while still in visual mode, avoiding <Esc> + '</'> marks.
• Explorer:get_nodes_in_range() reuses the existing get_nodes_by_line() infrastructure.
• Descendant filtering for destructive and clipboard ops: when a directory and its children are both selected, only the directory is operated on, preventing errors from attempting to remove already-deleted children.
• Single prompt for delete/trash rather than per-node confirmation.
• Visual mode is exited synchronously (nvim_feedkeys with "nx" flags) before any operation executes.
• Respects ui.confirm.default_yes config for bulk prompts.

Files Changed

• explorer/init.lua -- Explorer:get_nodes_in_range(start_line, end_line)
• marks/init.lua -- filter_descendant_nodes(), bulk_delete_nodes(), bulk_trash_nodes(), shared bulk_remove() helper
• api/impl/post.lua -- wrap_node_or_visual(), wrap_node_or_visual_bulk(), mode detection and visual range helpers
• _meta/api/fs.lua, _meta/api/marks.lua -- updated docs with "In visual mode..." notes
• api.lua -- mode-dependent behavior note
• keymap.lua -- { "n", "x" } mode tables for visual-capable keymaps
• help.lua -- mode column display, mode merging for duplicate lhs+desc entries
• scripts/help-defaults.sh -- parse both "n" and { "n", "x" } mode forms
• doc/nvim-tree-lua.txt -- regenerated help with mode column

[Copilot]

Pull request overview

This pull request adds first-class visual selection support to nvim-tree, allowing users to use V + motion to select a range of nodes and operate on them with a single keypress. The implementation includes support for toggle bookmark, copy, cut, delete, and trash operations on visually selected nodes.

Changes:

• Added visual mode keybindings (m, c, x, d, D) for operating on visual selections
• Implemented Explorer:get_nodes_in_range() to retrieve all nodes within a visual selection
• Created bulk operation functions bulk_delete_nodes() and bulk_trash_nodes() with single confirmation prompts
• Added descendant filtering to prevent errors when both a directory and its children are selected
• Updated help system to display visual mode keymaps with [v] prefix

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
lua/nvim-tree/marks/init.lua	Adds filter_descendant_nodes, bulk_delete_nodes, and bulk_trash_nodes functions for visual selection operations
lua/nvim-tree/explorer/init.lua	Implements get_nodes_in_range method to retrieve nodes within a line range
lua/nvim-tree/api/impl/post.lua	Adds wrap_visual_range and wrap_visual_bulk wrapper functions and wires up visual API endpoints
lua/nvim-tree/keymap.lua	Defines default visual mode keymaps (x mode) for visual operations
lua/nvim-tree/help.lua	Prefixes visual mode keymaps with [v] in help window
lua/nvim-tree/_meta/api/marks.lua	Adds type annotation for toggle_visual function
lua/nvim-tree/_meta/api/fs.lua	Adds type annotations for visual, cut_visual, remove_visual, and trash_visual functions

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[alex-courtis]

I see many Copilot comments on this PR.

Was AI used to generate this code?

[v3ceban]

I see many Copilot comments on this PR.

Yeah, it's just the review thingy. Didn't even know it'd work in someone else's repo.

Was AI used to generate this code?

A bit. Initially, to find the right API functions in the nvim-tree codebase for the bindings that I left in #2994, and then for the automated review, obviously.

[alex-courtis]

You can fix help generation by adding other mode handling to the script:

diff --git a/scripts/help-defaults.sh b/scripts/help-defaults.sh
index 11ffefe..609072f 100755
--- a/scripts/help-defaults.sh
+++ b/scripts/help-defaults.sh
@@ -45,7 +45,7 @@ sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/ON_ATTACH_DEFAULT.lua

 # help human
 echo > /tmp/ON_ATTACH_DEFAULT.help
-sed -E "s/^ *vim.keymap.set\(\"n\", \"(.*)\",.*api(.*),.*opts\(\"(.*)\".*$/'\`\1\`' '\3' '|nvim_tree.api\2()|'/g
+sed -E "s/^ *vim.keymap.set\(\".\", \"(.*)\",.*api(.*),.*opts\(\"(.*)\".*$/'\`\1\`' '\3' '|nvim_tree.api\2()|'/g
 " /tmp/ON_ATTACH_DEFAULT.lua | while read -r line
 do
    eval "printf '%-17.17s %-26.26s %s\n' ${line}" >> /tmp/ON_ATTACH_DEFAULT.help

You can then commit the updated help as per https://github.com/nvim-tree/nvim-tree.lua/blob/master/CONTRIBUTING.md#help-documentation

[alex-courtis]

Yeah, it's just the review thingy. Didn't even know it'd work in someone else's repo.

Please don't use automated reviews in the future.

I'll get to a review this week.

[Uanela]

This such a great feat, I was already looking forward to start working on this, I was just tired of jump from tree to oil and so on for some simple tasks.

[alex-courtis]

I haven't had a chance to review the code, however cursory initial testing looks good. This is fantastic as it opens the door for future visual (and other) mode operations.

Looking at the new API like nvim_tree.api.fs.copy.visual(): do we actually need it?

Rather than adding new API, we could make the existing API context dependent: when vim.api.nvim_get_mode().mode == "v" or V or maybe x we do the visual copy otherwise we do "normal" node copy.

[alex-courtis]

Disregard the CI that has not run; new test matricies have not yet filtered through.

[v3ceban]

I haven't had a chance to review the code, however cursory initial testing looks good. This is fantastic as it opens the door for future visual (and other) mode operations.

Thanks! And no worries - I’ve been quite busy myself - might not have a chance to jump on this again till tomorrow

Rather than adding new API, we could make the existing API context dependent: when vim.api.nvim_get_mode().mode == "v" or V or maybe x we do the visual copy otherwise we do "normal" node copy.

Yeah, this sounds good to me. No reason to duplicate the apis if existing ones are ok to extend. I was a bit cautious to not break any direct api usage accidentally with the new mode, but the risk is probably low here.

What should we do with mapping and help menu though? I assume having a separate entry for visual mode won’t make sense then.

I can extend the description of existing maps to mention visual mode operations.

Or, perhaps, we could even skip mentioning it in the description at all? At least to me this felt like a “natural” thing to try when I first attempted to delete multiple files. Mentioning it for every supported mapping may just add redundancy.

---

sry for typos - sent from my phone

[alex-courtis]

Yeah, this sounds good to me. No reason to duplicate the apis if existing ones are ok to extend. I was a bit cautious to not break any direct api usage accidentally with the new mode, but the risk is probably low here.

Your caution is most gratefully appreciated.

For the mapping itself, we can set multiple modes (table) e.g.

  vim.keymap.set({"n","v"}, "c",              api.fs.copy.node,                   opts("Copy"))

What should we do with mapping and help menu though? I assume having a separate entry for visual mode won’t make sense then.

We could be lazy with the help screen and just add a mode column in the middle, something like nx or nv or nV

nvim-tree-quickstart-help could mirror this, as the first two columns are the same.

I can extend the description of existing maps to mention visual mode operations.

Or, perhaps, we could even skip mentioning it in the description at all? At least to me this felt like a “natural” thing to try when I first attempted to delete multiple files. Mentioning it for every supported mapping may just add redundancy.

That should be OK.

vim help already has nvim-tree-mappings-default and the users will see it in the help screen and nvim-tree-quickstart-help

We can add a catch all note to nvim-tree-api in the "Generally, functions accepting..." section to describe mode dependent behaviour of API that has modal mappings.

[v3ceban]

We could be lazy with the help screen and just add a mode column in the middle, something like nx or nv or nV

nvim-tree-quickstart-help could mirror this, as the first two columns are the same.

vim help already has nvim-tree-mappings-default and the users will see it in the help screen and nvim-tree-quickstart-help

We can add a catch all note to nvim-tree-api in the "Generally, functions accepting..." section to describe mode dependent behaviour of API that has modal mappings.

Ok, this sounds good to me! I’ll get to it whenever I have a chance (most likely in the next ~24 hours)

[alex-courtis]

Cheers. No hurry at all.

[v3ceban]

@alex-courtis Thanks for the patience with this! It's ready for review.

[alex-courtis]

This is looking good functionally:

• keymappings work nicely
• new visual operations work well
• help and doc are very clear, as are comments on the interfaces

However, the code requires significant rework. There have been far too many changes, refactors that are not necessary and the bulk FS operations are not in the correct class.

This change should be a single, atomic commit that is easy to read and identify the changes.
This change should do exactly one thing: add the 4 visual operations. Refactoring or reworking of unrelated code is encouraged, however not when it is unrelated to or not necessary for a change. Raise a separate, follow up PR.

Please:

• revert changes to Marks. I don't think any changes are required: https://github.com/nvim-tree/nvim-tree.lua/pull/3268/changes#r2839038833
• move all the new visual api.fs operations to actions.fs files

[alex-courtis]

Many thanks for the detail.

[alex-courtis]

Adding the explicit notes is most gratefully appreciated.

[alex-courtis]

The original single functions called the actions.fs "domain", wheras the new bulk versions are calling the marks domain, which results in difficult to read and maintain code.

The bulk operations should reside in the actions.fs domain, not marks.

See https://github.com/nvim-tree/nvim-tree.lua/pull/3268/changes#r2839038833

[alex-courtis]

There are significant refactors and changes in this class that do not appear necessary which results in unclear git history and a non-atomic commit.

• The prompt has been changed to respect default_yes. Whilst I appreciate the initiative, it is unrelated to this functionality and should be reverted. We can make that change in a future pull request.
• bulk_delete_nodes and trash have been added. They do not appear related to marks, which already has the bulk operations which do not require any change. They appear to be used only by API.fs
• Many portions have been refactored or rewritten, such as extracting the bulk_remove and bulk_trash methods. These will be removed, however for future reference, the general OO principal of dynamic dispatch should be used instead of proxying a method with a, quite frankly, riduculous number of arguments. This is not readable or maintainable code.

In fact, it does not appear that any changes are required to this class: the existing Marks:toggle is successfully called repeatedly via wrap_node_or_visual, which is the only additional marks functionality.

[alex-courtis]

Many thanks for splitting this sed program and making it readable.

[v3ceban]

@alex-courtis Thank you for a detailed and in-depth review. This is a great learning opportunity for me and I sincerely appreciate your feedback! I believe I addressed all your concerns - please do let me know if anything is still not up to standards, is unrelated, or missing.