Skip to content

Commit 0ab0eb9

Browse files
kyazdani42kyazdani42
committed
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.
1 parent e522297 commit 0ab0eb9

File tree

6 files changed

+385
-130
lines changed

6 files changed

+385
-130
lines changed

‎doc/nvim-tree-lua.txt

Lines changed: 80 additions & 129 deletions
Original file line numberDiff line numberDiff line change
@@ -543,6 +543,34 @@ This will be experimental for a few weeks and will become the default.
543543
Idle milliseconds between filesystem change and action.
544544
Type: `number`, Default: `50` (ms)
545545

546+
*nvim-tree.on_attach*
547+
Function ran when creating the nvim-tree buffer.
548+
This can be used to attach keybindings to the tree buffer.
549+
When on_attach is nil, it will use the older mapping strategy, otherwise it
550+
will use the newer one.
551+
>
552+
on_attach = function(bufnr)
553+
local inject_node = require("nvim-tree.utils").inject_node
554+
555+
vim.keymap.set("n", "<leader>n", inject_node(function(node)
556+
if node then
557+
print(node.absolute_path)
558+
end
559+
end), { buffer = bufnr, noremap = true })
560+
561+
vim.bo[bufnr].path = "/tmp"
562+
end
563+
<
564+
Type: `function(bufnr)`, Default: `nil`
565+
566+
*nvim-tree.remove_keymaps*
567+
This can be used to remove the default mappings in the tree.
568+
- Remove specific keys by passing a `string` table of keys
569+
eg. {"<C-o>", "<CR>", "o", "<Tab>"}
570+
- Remove all default mappings by passing `true`
571+
- Ignore by passing `false`
572+
Type: `bool` or `{string}`, Default: `false`
573+
546574
*nvim-tree.view*
547575
Window / buffer setup.
548576

@@ -600,14 +628,11 @@ Window / buffer setup.
600628
Configuration options for |nvim-tree-mappings|
601629

602630
*nvim-tree.view.mappings.custom_only*
603-
Will use only the provided user mappings and not the default otherwise,
604-
extends the default mappings with the provided user mappings.
605-
Type: `boolean`, Default: `false`
631+
DEPRECATED: see |nvim-tree.remove_keymaps|
632+
606633

607634
*nvim-tree.view.mappings.list*
608-
A list of keymaps that will extend or override the default keymaps.
609-
Type: `table`
610-
Default: see |nvim-tree-default-mappings|
635+
DEPRECATED: see |nvim-tree.on_attach|
611636

612637
*nvim-tree.renderer*
613638
UI rendering setup
@@ -1046,130 +1071,56 @@ exists.
10461071
==============================================================================
10471072
6. MAPPINGS *nvim-tree-mappings*
10481073

1049-
The `list` option in `view.mappings.list` is a table of
1074+
Setting your own mapping in the configuration is deprecated, see |nvim-tree.on_attach| now.
1075+
1076+
You can remove default mappings with |nvim-tree.remove_keymaps|.
1077+
1078+
`<CR>`, `o`, `<2-LeftMouse>` open a file or folder; root will cd to the above directory
1079+
`<C-e>` edit the file in place, effectively replacing the tree explorer
1080+
`O` same as (edit) with no window picker
1081+
`<C-]>`, `<2-RightMouse>` cd in the directory under the cursor
1082+
`<C-v>` open the file in a vertical split
1083+
`<C-x>` open the file in a horizontal split
1084+
`<C-t>` open the file in a new tab
1085+
`<` navigate to the previous sibling of current file/directory
1086+
`>` navigate to the next sibling of current file/directory
1087+
`P` move cursor to the parent directory
1088+
`<BS>` close current opened directory or parent
1089+
`<Tab>` open the file as a preview (keeps the cursor in the tree)
1090+
`K` navigate to the first sibling of current file/directory
1091+
`J` navigate to the last sibling of current file/directory
1092+
`I` toggle visibility of files/folders hidden via |git.ignore| option
1093+
`H` toggle visibility of dotfiles via |filters.dotfiles| option
1094+
`U` toggle visibility of files/folders hidden via |filters.custom| option
1095+
`R` refresh the tree
1096+
`a` add a file; leaving a trailing `/` will add a directory
1097+
`d` delete a file (will prompt for confirmation)
1098+
`D` trash a file via |trash| option
1099+
`r` rename a file
1100+
`<C-r>` rename a file and omit the filename on input
1101+
`x` add/remove file/directory to cut clipboard
1102+
`c` add/remove file/directory to copy clipboard
1103+
`p` paste from clipboard; cut clipboard has precedence over copy; will prompt for confirmation
1104+
`y` copy name to system clipboard
1105+
`Y` copy relative path to system clipboard
1106+
`gy` copy absolute path to system clipboard
1107+
`[e` go to next diagnostic item
1108+
`[c` go to next git item
1109+
`]e` go to prev diagnostic item
1110+
`]c` go to prev git item
1111+
`-` navigate up to the parent directory of the current file/directory
1112+
`s` open a file with default system application or a folder with default file manager, using |system_open| option
1113+
`f` live filter nodes dynamically based on regex matching.
1114+
`F` clear live filter
1115+
`q` close tree window
1116+
`W` collapse the whole tree
1117+
`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
1118+
`S` prompt the user to enter a path and then expands the tree to match the path
1119+
`.` enter vim command mode with the file the cursor is on
1120+
`<C-k>` toggle a popup with file infos about the file under the cursor
1121+
`g?` toggle help
1122+
`m` Toggle node in bookmarks
10501123

1051-
- `key` can be either a string or a table of string (lhs)
1052-
- `action` is the name of the action, set to `""` to remove default action
1053-
- `action_cb` is the function that will be called, it receives the node as a parameter. Optional for default actions
1054-
- `mode` is normal by default
1055-
>
1056-
local tree_cb = require'nvim-tree.config'.nvim_tree_callback
1057-
1058-
local function print_node_path(node) {
1059-
print(node.absolute_path)
1060-
}
1061-
1062-
local list = {
1063-
{ key = {"<CR>", "o" }, action = "edit", mode = "n"},
1064-
{ key = "p", action = "print_path", action_cb = print_node_path },
1065-
{ key = "s", cb = tree_cb("vsplit") }, --tree_cb and the cb property are deprecated
1066-
{ key = "<2-RightMouse>", action = "" }, -- will remove default cd action
1067-
}
1068-
<
1069-
Mouse support defined in |KeyBindings|
1070-
1071-
DEFAULT MAPPINGS *nvim-tree-default-mappings*
1072-
1073-
`<CR>` edit open a file or folder; root will cd to the above directory
1074-
`o`
1075-
`<2-LeftMouse>`
1076-
`<C-e>` edit_in_place edit the file in place, effectively replacing the tree explorer
1077-
`O` edit_no_picker same as (edit) with no window picker
1078-
`<C-]>` cd cd in the directory under the cursor
1079-
`<2-RightMouse>`
1080-
`<C-v>` vsplit open the file in a vertical split
1081-
`<C-x>` split open the file in a horizontal split
1082-
`<C-t>` tabnew open the file in a new tab
1083-
`<` prev_sibling navigate to the previous sibling of current file/directory
1084-
`>` next_sibling navigate to the next sibling of current file/directory
1085-
`P` parent_node move cursor to the parent directory
1086-
`<BS>` close_node close current opened directory or parent
1087-
`<Tab>` preview open the file as a preview (keeps the cursor in the tree)
1088-
`K` first_sibling navigate to the first sibling of current file/directory
1089-
`J` last_sibling navigate to the last sibling of current file/directory
1090-
`I` toggle_git_ignored toggle visibility of files/folders hidden via |git.ignore| option
1091-
`H` toggle_dotfiles toggle visibility of dotfiles via |filters.dotfiles| option
1092-
`U` toggle_custom toggle visibility of files/folders hidden via |filters.custom| option
1093-
`R` refresh refresh the tree
1094-
`a` create add a file; leaving a trailing `/` will add a directory
1095-
`d` remove delete a file (will prompt for confirmation)
1096-
`D` trash trash a file via |trash| option
1097-
`r` rename rename a file
1098-
`<C-r>` full_rename rename a file and omit the filename on input
1099-
`x` cut add/remove file/directory to cut clipboard
1100-
`c` copy add/remove file/directory to copy clipboard
1101-
`p` paste paste from clipboard; cut clipboard has precedence over copy; will prompt for confirmation
1102-
`y` copy_name copy name to system clipboard
1103-
`Y` copy_path copy relative path to system clipboard
1104-
`gy` copy_absolute_path copy absolute path to system clipboard
1105-
`[e` prev_diag_item go to next diagnostic item
1106-
`[c` prev_git_item go to next git item
1107-
`]e` next_diag_item go to prev diagnostic item
1108-
`]c` next_git_item go to prev git item
1109-
`-` dir_up navigate up to the parent directory of the current file/directory
1110-
`s` system_open open a file with default system application or a folder with default file manager, using |system_open| option
1111-
`f` live_filter live filter nodes dynamically based on regex matching.
1112-
`F` clear_live_filter clear live filter
1113-
`q` close close tree window
1114-
`W` collapse_all collapse the whole tree
1115-
`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
1116-
`S` search_node prompt the user to enter a path and then expands the tree to match the path
1117-
`.` run_file_command enter vim command mode with the file the cursor is on
1118-
`<C-k>` toggle_file_info toggle a popup with file infos about the file under the cursor
1119-
`g?` toggle_help toggle help
1120-
`m` toggle_mark Toggle node in bookmarks
1121-
`bmv` bulk_move Move all bookmarked nodes into specified location
1122-
1123-
>
1124-
view.mappings.list = { -- BEGIN_DEFAULT_MAPPINGS
1125-
{ key = { "<CR>", "o", "<2-LeftMouse>" }, action = "edit" },
1126-
{ key = "<C-e>", action = "edit_in_place" },
1127-
{ key = "O", action = "edit_no_picker" },
1128-
{ key = { "<C-]>", "<2-RightMouse>" }, action = "cd" },
1129-
{ key = "<C-v>", action = "vsplit" },
1130-
{ key = "<C-x>", action = "split" },
1131-
{ key = "<C-t>", action = "tabnew" },
1132-
{ key = "<", action = "prev_sibling" },
1133-
{ key = ">", action = "next_sibling" },
1134-
{ key = "P", action = "parent_node" },
1135-
{ key = "<BS>", action = "close_node" },
1136-
{ key = "<Tab>", action = "preview" },
1137-
{ key = "K", action = "first_sibling" },
1138-
{ key = "J", action = "last_sibling" },
1139-
{ key = "I", action = "toggle_git_ignored" },
1140-
{ key = "H", action = "toggle_dotfiles" },
1141-
{ key = "U", action = "toggle_custom" },
1142-
{ key = "R", action = "refresh" },
1143-
{ key = "a", action = "create" },
1144-
{ key = "d", action = "remove" },
1145-
{ key = "D", action = "trash" },
1146-
{ key = "r", action = "rename" },
1147-
{ key = "<C-r>", action = "full_rename" },
1148-
{ key = "x", action = "cut" },
1149-
{ key = "c", action = "copy" },
1150-
{ key = "p", action = "paste" },
1151-
{ key = "y", action = "copy_name" },
1152-
{ key = "Y", action = "copy_path" },
1153-
{ key = "gy", action = "copy_absolute_path" },
1154-
{ key = "[e", action = "prev_diag_item" },
1155-
{ key = "[c", action = "prev_git_item" },
1156-
{ key = "]e", action = "next_diag_item" },
1157-
{ key = "]c", action = "next_git_item" },
1158-
{ key = "-", action = "dir_up" },
1159-
{ key = "s", action = "system_open" },
1160-
{ key = "f", action = "live_filter" },
1161-
{ key = "F", action = "clear_live_filter" },
1162-
{ key = "q", action = "close" },
1163-
{ key = "W", action = "collapse_all" },
1164-
{ key = "E", action = "expand_all" },
1165-
{ key = "S", action = "search_node" },
1166-
{ key = ".", action = "run_file_command" },
1167-
{ key = "<C-k>", action = "toggle_file_info" },
1168-
{ key = "g?", action = "toggle_help" },
1169-
{ key = "m", action = "toggle_mark" },
1170-
{ key = "bmv", action = "bulk_move" },
1171-
} -- END_DEFAULT_MAPPINGS
1172-
<
11731124
==============================================================================
11741125
7. HIGHLIGHT GROUPS *nvim-tree-highlight*
11751126

‎lua/nvim-tree.lua

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -434,6 +434,8 @@ local DEFAULT_OPTS = { -- BEGIN_DEFAULT_OPTS
434434
sync_root_with_cwd = false,
435435
reload_on_bufenter = false,
436436
respect_buf_cwd = false,
437+
on_attach = nil, -- function(bufnr). If nil, will use the deprecated mapping strategy
438+
remove_keymaps = false, -- boolean (disable totally or not) or list of key (lhs)
437439
view = {
438440
adaptive_size = false,
439441
centralize_selection = false,
@@ -445,6 +447,7 @@ local DEFAULT_OPTS = { -- BEGIN_DEFAULT_OPTS
445447
number = false,
446448
relativenumber = false,
447449
signcolumn = "yes",
450+
-- @deprecated
448451
mappings = {
449452
custom_only = false,
450453
list = {
@@ -682,6 +685,7 @@ function M.setup(conf)
682685
log.raw("config", "%s\n", vim.inspect(opts))
683686

684687
require("nvim-tree.actions").setup(opts)
688+
require("nvim-tree.keymap").setup(opts)
685689
require("nvim-tree.colors").setup()
686690
require("nvim-tree.diagnostics").setup(opts)
687691
require("nvim-tree.explorer").setup(opts)

‎lua/nvim-tree/actions/init.lua

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
-- @deprecated: new implemention in nvim-tree.keymap. Please do not edit this file.
2+
13
local a = vim.api
24

35
local log = require "nvim-tree.log"

0 commit comments

Comments
 (0)