feat(#2994): add visual selection operations

[v3ceban]

Add visual selection operations

Closes #2994
See also: #2993

Summary

Adds first-class visual selection support to nvim-tree. Users can now 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) -- single confirmation prompt for the entire selection
• Trash (D) -- single confirmation prompt for the entire selection

New API

Function	Description
api.marks.toggle_visual	Toggle bookmark on all visually selected nodes
api.fs.copy.visual	Copy all visually selected nodes to clipboard
api.fs.cut_visual	Cut all visually selected nodes to clipboard
api.fs.remove_visual	Delete all visually selected nodes (single prompt)
api.fs.trash_visual	Trash all visually selected nodes (single prompt)

Design

• Visual range detection uses vim.fn.line("v") / vim.fn.line(".") while in x mode, avoiding <Esc> + '</'> marks.
• Explorer:get_nodes_in_range() reuses the existing get_nodes_by_line() infrastructure.
• Descendant filtering for destructive 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.
• g? help window prefixes visual mode keymaps with [v] to distinguish them from normal mode.

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()
• api/impl/post.lua -- wrap_visual_range(), wrap_visual_bulk(), API wiring
• _meta/api/fs.lua, _meta/api/marks.lua -- type annotations
• keymap.lua -- default visual mode keymaps in on_attach_default
• help.lua -- [v] prefix for visual mode keymaps

[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.