feat(mapping): deprecate user mappings and add on_attach

See the help doc. I think this is better than providing our custom
binding methods, idea taken from gitsigns.nvim.
Once this is complete, we could remove the whole mapping code and
simplify the actions -> dispatch configurations.

Author: kyazdani42

doc/nvim-tree-lua.txt

@@ -539,6 +539,32 @@ This will be experimental for a few weeks and will become the default.
     Idle milliseconds between filesystem change and action.
       Type: `number`, Default: `50` (ms)
 
+*nvim-tree.on_attach*
+Function ran when creating the nvim-tree buffer.
+This can be used to attach keybindings to the tree buffer.
+>
+    on_attach = function(bufnr)
+        local inject_node = require("nvim-tree.utils").inject_node
+
+        vim.keymap.set("n", "<leader>n", inject_node(function(node)
+            if node then
+                print(node.absolute_path)
+            end
+        end), { buffer = bufnr, noremap = true })
+
+        vim.bo[bufnr].path = "/tmp"
+    end
+<
+    Type: `function(bufnr)`, Default: `empty_function`
+
+*nvim-tree.remove_keymaps*
+This can be used to remove the default mappings in the tree.
+- Remove specific keys by passing a `string` table of keys
+    eg. {"<C-o>", "<CR>", "o"}
+- Remove all default mappings by passing `true`
+- Ignore by passing `false`
+    Type: `bool` or `{string}`, Default: `false`
+
 *nvim-tree.view*
 Window / buffer setup.
 
@@ -596,14 +622,11 @@ Window / buffer setup.
     Configuration options for |nvim-tree-mappings|
 
         *nvim-tree.view.mappings.custom_only*
-        Will use only the provided user mappings and not the default otherwise,
-        extends the default mappings with the provided user mappings.
-          Type: `boolean`, Default: `false`
+            DEPRECATED: see |nvim-tree.remove_keymaps|
+
 
         *nvim-tree.view.mappings.list*
-        A list of keymaps that will extend or override the default keymaps.
-          Type: `table`
-          Default: see |nvim-tree-default-mappings|
+            DEPRECATED: see |nvim-tree.on_attach|
 
 *nvim-tree.renderer*
 UI rendering setup
@@ -943,128 +966,58 @@ A good functionnality to enable is |nvim-tree.hijack_directories|.
 ==============================================================================
  5. MAPPINGS                                              *nvim-tree-mappings*
 
-The `list` option in `view.mappings.list` is a table of
+Setting your own mapping in the configuration is deprecated, see |nvim-tree.on_attach| now.
 
-- `key` can be either a string or a table of string (lhs)
-- `action` is the name of the action, set to `""` to remove default action
-- `action_cb` is the function that will be called, it receives the node as a parameter. Optional for default actions
-- `mode` is normal by default
->
-  local tree_cb = require'nvim-tree.config'.nvim_tree_callback
-
-  local function print_node_path(node) {
-    print(node.absolute_path)
-  }
-
-  local list = {
-    { key = {"<CR>", "o" }, action = "edit", mode = "n"},
-    { key = "p", action = "print_path", action_cb = print_node_path },
-    { key = "s", cb = tree_cb("vsplit") }, --tree_cb and the cb property are deprecated
-    { key = "<2-RightMouse>", action = "" }, -- will remove default cd action
-  }
-<
-Mouse support defined in |KeyBindings|
+You can remove mappings with |nvim-tree.remove_keymaps|.
 
 DEFAULT MAPPINGS                                     *nvim-tree-default-mappings*
 
-`<CR>`            edit                open a file or folder; root will cd to the above directory
-`o`
-`<2-LeftMouse>`
-`<C-e>`           edit_in_place       edit the file in place, effectively replacing the tree explorer
-`O`               edit_no_picker      same as (edit) with no window picker
-`<C-]>`           cd                  cd in the directory under the cursor
-`<2-RightMouse>`
-`<C-v>`           vsplit              open the file in a vertical split
-`<C-x>`           split               open the file in a horizontal split
-`<C-t>`           tabnew              open the file in a new tab
-`<`               prev_sibling        navigate to the previous sibling of current file/directory
-`>`               next_sibling        navigate to the next sibling of current file/directory
-`P`               parent_node         move cursor to the parent directory
-`<BS>`            close_node          close current opened directory or parent
-`<Tab>`           preview             open the file as a preview (keeps the cursor in the tree)
-`K`               first_sibling       navigate to the first sibling of current file/directory
-`J`               last_sibling        navigate to the last sibling of current file/directory
-`I`               toggle_git_ignored  toggle visibility of files/folders hidden via |git.ignore| option
-`H`               toggle_dotfiles     toggle visibility of dotfiles via |filters.dotfiles| option
-`U`               toggle_custom       toggle visibility of files/folders hidden via |filters.custom| option
-`R`               refresh             refresh the tree
-`a`               create              add a file; leaving a trailing `/` will add a directory
-`d`               remove              delete a file (will prompt for confirmation)
-`D`               trash               trash a file via |trash| option
-`r`               rename              rename a file
-`<C-r>`           full_rename         rename a file and omit the filename on input
-`x`               cut                 add/remove file/directory to cut clipboard
-`c`               copy                add/remove file/directory to copy clipboard
-`p`               paste               paste from clipboard; cut clipboard has precedence over copy; will prompt for confirmation
-`y`               copy_name           copy name to system clipboard
-`Y`               copy_path           copy relative path to system clipboard
-`gy`              copy_absolute_path  copy absolute path to system clipboard
-`[e`              prev_diag_item      go to next diagnostic item
-`[c`              prev_git_item       go to next git item
-`]e`              next_diag_item      go to prev diagnostic item
-`]c`              next_git_item       go to prev git item
-`-`               dir_up              navigate up to the parent directory of the current file/directory
-`s`               system_open         open a file with default system application or a folder with default file manager, using |system_open| option
-`f`               live_filter         live filter nodes dynamically based on regex matching.
-`F`               clear_live_filter   clear live filter
-`q`               close               close tree window
-`W`               collapse_all        collapse the whole tree
-`E`               expand_all          expand the whole tree, stopping after expanding |actions.expand_all.max_folder_discovery| folders; this might hang neovim for a while if running on a big folder
-`S`               search_node         prompt the user to enter a path and then expands the tree to match the path
-`.`               run_file_command    enter vim command mode with the file the cursor is on
-`<C-k>`           toggle_file_info    toggle a popup with file infos about the file under the cursor
-`g?`              toggle_help         toggle help
-`m`               toggle_mark         Toggle node in bookmarks
+`<CR>`, `o`, `<2-LeftMouse>`    open a file or folder; root will cd to the above directory
+`<C-e>`                         edit the file in place, effectively replacing the tree explorer
+`O`                             same as (edit) with no window picker
+`<C-]>`, `<2-RightMouse>`       cd in the directory under the cursor
+`<C-v>`                         open the file in a vertical split
+`<C-x>`                         open the file in a horizontal split
+`<C-t>`                         open the file in a new tab
+`<`                             navigate to the previous sibling of current file/directory
+`>`                             navigate to the next sibling of current file/directory
+`P`                             move cursor to the parent directory
+`<BS>`                          close current opened directory or parent
+`<Tab>`                         open the file as a preview (keeps the cursor in the tree)
+`K`                             navigate to the first sibling of current file/directory
+`J`                             navigate to the last sibling of current file/directory
+`I`                             toggle visibility of files/folders hidden via |git.ignore| option
+`H`                             toggle visibility of dotfiles via |filters.dotfiles| option
+`U`                             toggle visibility of files/folders hidden via |filters.custom| option
+`R`                             refresh the tree
+`a`                             add a file; leaving a trailing `/` will add a directory
+`d`                             delete a file (will prompt for confirmation)
+`D`                             trash a file via |trash| option
+`r`                             rename a file
+`<C-r>`                         rename a file and omit the filename on input
+`x`                             add/remove file/directory to cut clipboard
+`c`                             add/remove file/directory to copy clipboard
+`p`                             paste from clipboard; cut clipboard has precedence over copy; will prompt for confirmation
+`y`                             copy name to system clipboard
+`Y`                             copy relative path to system clipboard
+`gy`                            copy absolute path to system clipboard
+`[e`                            go to next diagnostic item
+`[c`                            go to next git item
+`]e`                            go to prev diagnostic item
+`]c`                            go to prev git item
+`-`                             navigate up to the parent directory of the current file/directory
+`s`                             open a file with default system application or a folder with default file manager, using |system_open| option
+`f`                             live filter nodes dynamically based on regex matching.
+`F`                             clear live filter
+`q`                             close tree window
+`W`                             collapse the whole tree
+`E`                             expand the whole tree, stopping after expanding |actions.expand_all.max_folder_discovery| folders; this might hang neovim for a while if running on a big folder
+`S`                             prompt the user to enter a path and then expands the tree to match the path
+`.`                             enter vim command mode with the file the cursor is on
+`<C-k>`                         toggle a popup with file infos about the file under the cursor
+`g?`                            toggle help
+`m`                             Toggle node in bookmarks
 
->
-  view.mappings.list = { -- BEGIN_DEFAULT_MAPPINGS
-    { key = { "<CR>", "o", "<2-LeftMouse>" }, action = "edit" }
-    { key = "<C-e>",                          action = "edit_in_place" }
-    { key = "O",                              action = "edit_no_picker" }
-    { key = { "<C-]>", "<2-RightMouse>" },    action = "cd" }
-    { key = "<C-v>",                          action = "vsplit" }
-    { key = "<C-x>",                          action = "split" }
-    { key = "<C-t>",                          action = "tabnew" }
-    { key = "<",                              action = "prev_sibling" }
-    { key = ">",                              action = "next_sibling" }
-    { key = "P",                              action = "parent_node" }
-    { key = "<BS>",                           action = "close_node" }
-    { key = "<Tab>",                          action = "preview" }
-    { key = "K",                              action = "first_sibling" }
-    { key = "J",                              action = "last_sibling" }
-    { key = "I",                              action = "toggle_git_ignored" }
-    { key = "H",                              action = "toggle_dotfiles" }
-    { key = "U",                              action = "toggle_custom" }
-    { key = "R",                              action = "refresh" }
-    { key = "a",                              action = "create" }
-    { key = "d",                              action = "remove" }
-    { key = "D",                              action = "trash" }
-    { key = "r",                              action = "rename" }
-    { key = "<C-r>",                          action = "full_rename" }
-    { key = "x",                              action = "cut" }
-    { key = "c",                              action = "copy" }
-    { key = "p",                              action = "paste" }
-    { key = "y",                              action = "copy_name" }
-    { key = "Y",                              action = "copy_path" }
-    { key = "gy",                             action = "copy_absolute_path" }
-    { key = "[e",                             action = "prev_diag_item" }
-    { key = "[c",                             action = "prev_git_item" }
-    { key = "]e",                             action = "next_diag_item" }
-    { key = "]c",                             action = "next_git_item" }
-    { key = "-",                              action = "dir_up" }
-    { key = "s",                              action = "system_open" }
-    { key = "f",                              action = "live_filter" }
-    { key = "F",                              action = "clear_live_filter" }
-    { key = "q",                              action = "close" }
-    { key = "W",                              action = "collapse_all" }
-    { key = "E",                              action = "expand_all" }
-    { key = "S",                              action = "search_node" }
-    { key = ".",                              action = "run_file_command" }
-    { key = "<C-k>",                          action = "toggle_file_info" }
-    { key = "g?",                             action = "toggle_help" }
-    { key = "m",                              action = "toggle_mark" }
-  } -- END_DEFAULT_MAPPINGS
-<
 ==============================================================================
  6. HIGHLIGHT GROUPS                                     *nvim-tree-highlight*
 

lua/nvim-tree.lua

@@ -421,6 +421,8 @@ local DEFAULT_OPTS = { -- BEGIN_DEFAULT_OPTS
   sync_root_with_cwd = false,
   reload_on_bufenter = false,
   respect_buf_cwd = false,
+  on_attach = function() end,
+  remove_keymaps = false, -- boolean (disable totally or not) or list of key (lhs)
   view = {
     adaptive_size = false,
     centralize_selection = false,
@@ -432,6 +434,7 @@ local DEFAULT_OPTS = { -- BEGIN_DEFAULT_OPTS
     number = false,
     relativenumber = false,
     signcolumn = "yes",
+    -- @deprecated
     mappings = {
       custom_only = false,
       list = {

lua/nvim-tree/actions/init.lua

@@ -269,6 +269,7 @@ function M.apply_mappings(bufnr)
   end
 end
 
+-- @deprecated
 local function merge_mappings(user_mappings)
   if #user_mappings == 0 then
     return M.mappings
@@ -327,6 +328,7 @@ local function merge_mappings(user_mappings)
   return vim.fn.extend(default_map, user_map)
 end
 
+-- @deprecated
 local function copy_mappings(user_mappings)
   if #user_mappings == 0 then
     return M.mappings
@@ -356,10 +358,45 @@ local function cleanup_existing_mappings()
 end
 
 local DEFAULT_MAPPING_CONFIG = {
+  -- @deprecated
   custom_only = false,
+  -- @deprecated
   list = {},
 }
 
+local function remove_keymaps(keys_to_disable)
+  if keys_to_disable == true then
+    M.mappings = {}
+    return
+  end
+
+  if type(keys_to_disable) == "table" and #keys_to_disable > 0 then
+    local new_map = {}
+    for _, m in pairs(M.mappings) do
+      local keys = type(m.key) == "table" and m.key or { m.key }
+      local reminding_keys = {}
+      for _, key in pairs(keys) do
+        local found = false
+        for _, key_to_disable in pairs(keys_to_disable) do
+          if key_to_disable == key then
+            found = true
+            break
+          end
+        end
+        if not found then
+          table.insert(reminding_keys, key)
+        end
+      end
+      if #reminding_keys > 0 then
+        local map = vim.deepcopy(m)
+        map.key = reminding_keys
+        table.insert(new_map, map)
+      end
+    end
+    M.mappings = new_map
+  end
+end
+
 function M.setup(opts)
   require("nvim-tree.actions.fs.trash").setup(opts)
   require("nvim-tree.actions.node.system-open").setup(opts)
@@ -373,15 +410,22 @@ function M.setup(opts)
 
   cleanup_existing_mappings()
   M.mappings = vim.deepcopy(DEFAULT_MAPPINGS)
+  remove_keymaps(opts.remove_keymaps)
 
+  -- @deprecated
   local user_map_config = (opts.view or {}).mappings or {}
+  -- @deprecated
   local options = vim.tbl_deep_extend("force", DEFAULT_MAPPING_CONFIG, user_map_config)
+  -- @deprecated
   if options.custom_only then
+    -- @deprecated
     M.mappings = copy_mappings(options.list)
   else
+    -- @deprecated
     M.mappings = merge_mappings(options.list)
   end
 
+  -- @deprecated
   require("nvim-tree.actions.dispatch").setup(M.custom_keypress_funcs)
 
   log.line("config", "active mappings")

lua/nvim-tree/utils.lua

@@ -335,4 +335,10 @@ function M.focus_file(path)
   require("nvim-tree.view").set_cursor { i + 1, 1 }
 end
 
+function M.inject_node(f)
+  return function()
+    f(require("nvim-tree.lib").get_node_at_cursor())
+  end
+end
+
 return M

lua/nvim-tree/view.lua

@@ -93,6 +93,7 @@ local function create_buffer(bufnr)
   end
 
   require("nvim-tree.actions").apply_mappings(M.get_bufnr())
+  M.on_attach(M.get_bufnr())
 end
 
 local function get_size()
@@ -425,6 +426,7 @@ function M.setup(opts)
   M.View.winopts.number = options.number
   M.View.winopts.relativenumber = options.relativenumber
   M.View.winopts.signcolumn = options.signcolumn
+  M.on_attach = opts.on_attach
 end
 
 return M