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.
The new keymap.lua module is now used whenever on_attach is defined.

Author: kyazdani42

doc/nvim-tree-lua.txt

@@ -543,6 +543,34 @@ 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.
+When on_attach is nil, it will use the older mapping strategy, otherwise it
+will use the newer one.
+>
+    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: `nil`
+
+*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", "<Tab>"}
+- Remove all default mappings by passing `true`
+- Ignore by passing `false`
+    Type: `bool` or `{string}`, Default: `false`
+
 *nvim-tree.view*
 Window / buffer setup.
 
@@ -600,14 +628,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
@@ -975,6 +1000,7 @@ exists.
     - focus
     - reload
     - change_root `(path: string)`
+    - change_root_to_node
     - change_root_to_parent
     - get_node_under_cursor
     - find_file `(filename: string)`
@@ -1043,130 +1069,56 @@ exists.
 ==============================================================================
  6. 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.
+
+You can remove default mappings with |nvim-tree.remove_keymaps|.
+
+`<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
 
-- `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|
-
-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
-`bmv`             bulk_move           Move all bookmarked nodes into specified location
-
->
-  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" },
-    { key = "bmv",                            action = "bulk_move" },
-  } -- END_DEFAULT_MAPPINGS
-<
 ==============================================================================
  7. HIGHLIGHT GROUPS                                     *nvim-tree-highlight*
 

lua/nvim-tree.lua

@@ -434,6 +434,8 @@ local DEFAULT_OPTS = { -- BEGIN_DEFAULT_OPTS
   sync_root_with_cwd = false,
   reload_on_bufenter = false,
   respect_buf_cwd = false,
+  on_attach = nil, -- function(bufnr). If nil, will use the deprecated mapping strategy
+  remove_keymaps = false, -- boolean (disable totally or not) or list of key (lhs)
   view = {
     adaptive_size = false,
     centralize_selection = false,
@@ -445,6 +447,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

@@ -1,3 +1,5 @@
+-- @deprecated: new implemention in nvim-tree.keymap. Please do not edit this file.
+
 local a = vim.api
 
 local log = require "nvim-tree.log"

lua/nvim-tree/api.lua

@@ -21,6 +21,13 @@ Api.tree.close = require("nvim-tree.view").close
 Api.tree.focus = require("nvim-tree").focus
 Api.tree.reload = require("nvim-tree.actions.reloaders.reloaders").reload_explorer
 Api.tree.change_root = require("nvim-tree").change_dir
+Api.tree.change_root_to_node = inject_node(function(node)
+  if node.name == ".." then
+    require("nvim-tree.actions.root.change-dir").fn ".."
+  elseif node.nodes ~= nil then
+    require("nvim-tree.actions.root.change-dir").fn(require("nvim-tree.lib").get_last_group_node(node).absolute_path)
+  end
+end)
 Api.tree.change_root_to_parent = inject_node(require("nvim-tree.actions.root.dir-up").fn)
 Api.tree.get_node_under_cursor = require("nvim-tree.lib").get_node_at_cursor
 Api.tree.find_file = require("nvim-tree.actions.finders.find-file").fn
@@ -74,6 +81,8 @@ local function open_preview(node)
 end
 
 Api.node.open.edit = inject_node(open_or_expand_or_dir_up "edit")
+Api.node.open.replace_tree_buffer = inject_node(open_or_expand_or_dir_up "edit_in_place")
+Api.node.open.no_window_picker = inject_node(open_or_expand_or_dir_up "edit_no_picker")
 Api.node.open.vertical = inject_node(open_or_expand_or_dir_up "vsplit")
 Api.node.open.horizontal = inject_node(open_or_expand_or_dir_up "split")
 Api.node.open.tab = inject_node(open_or_expand_or_dir_up "tabnew")