docs: clarify on_attach example, quick start (#2165)

* doc: more on_attach examples * doc: human readable mappings help * doc: human readable mappings help * doc: more on_attach examples * doc: enhance quick start * doc: enhance quick start * doc: enhance quick start * doc: enhance quick start * doc: enhance quick start * doc: enhance quick start
2023-04-29 17:00:40 +10:00 · 2023-04-29 17:00:40 +10:00 · 74996b8626
commit 74996b8626
parent 1f5bbc1efd
3 changed files with 104 additions and 12 deletions
--- a/README.md
+++ b/README.md
@ -44,13 +44,11 @@ Please install via your preferred package manager. See [Installation](https://gi

 `nvim-tree/nvim-web-devicons` optional, for file icons

-## Setup
+## Quick Start

-Setup should be run in a lua file or in a lua heredoc [:help lua-heredoc](https://neovim.io/doc/user/lua.html) if using in a vim file.
+Setup the plugin in your `init.lua`

 ```lua
-- examples for your init.lua
-
 -- disable netrw at the very start of your init.lua (strongly advised)
 vim.g.loaded_netrw = 1
 vim.g.loaded_netrwPlugin = 1
@ -64,6 +62,9 @@ require("nvim-tree").setup()
 -- OR setup with some options
 require("nvim-tree").setup({
  sort_by = "case_sensitive",
+  view = {
+    width = 30,
+  },
  renderer = {
    group_empty = true,
  },
@ -73,6 +74,10 @@ require("nvim-tree").setup({
 })
 ```

+Open the tree:  `:NvimTreeOpen`
+
+Show the mappings:  `g?`
+
 For complete list of available configuration options see [:help nvim-tree-setup](doc/nvim-tree-lua.txt)

 Each option is documented in `:help nvim-tree.OPTION_NAME`. Nested options can be accessed by appending `.`, for example [:help nvim-tree.filters.dotfiles](doc/nvim-tree-lua.txt)
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@ -73,7 +73,13 @@ Requirements

 ==============================================================================
 2. QUICK START                                         *nvim-tree-quickstart*
->
+
+Install the plugins via your package manager:
+  `"nvim-tree/nvim-tree.lua"`
+  `"nvim-tree/nvim-web-devicons"`
+
+Setup the plugin in your `init.lua` >
+
  -- disable netrw at the very start of your init.lua (strongly advised)
  vim.g.loaded_netrw = 1
  vim.g.loaded_netrwPlugin = 1
@ -98,6 +104,63 @@ Requirements
    },
  })
 <
+Open the tree:  `:NvimTreeOpen`
+
+Show the mappings:  `g?`
+
+`<C-]>`           CD                      |nvim-tree-api.tree.change_root_to_node()|
+`<C-e>`           Open: In Place          |nvim-tree-api.node.open.replace_tree_buffer()|
+`<C-k>`           Info                    |nvim-tree-api.node.show_info_popup()|
+`<C-r>`           Rename: Omit Filename   |nvim-tree-api.fs.rename_sub()|
+`<C-t>`           Open: New Tab           |nvim-tree-api.node.open.tab()|
+`<C-v>`           Open: Vertical Split    |nvim-tree-api.node.open.vertical()|
+`<C-x>`           Open: Horizontal Split  |nvim-tree-api.node.open.horizontal()|
+`<BS>`            Close Directory         |nvim-tree-api.node.navigate.parent_close()|
+`<CR>`            Open                    |nvim-tree-api.node.open.edit()|
+`<Tab>`           Open Preview            |nvim-tree-api.node.open.preview()|
+`>`               Next Sibling            |nvim-tree-api.node.navigate.sibling.next()|
+`<`               Previous Sibling        |nvim-tree-api.node.navigate.sibling.prev()|
+`.`               Run Command             |nvim-tree-api.node.run.cmd()|
+`-`               Up                      |nvim-tree-api.tree.change_root_to_parent()|
+`a`               Create                  |nvim-tree-api.fs.create()|
+`bmv`             Move Bookmarked         |nvim-tree-api.marks.bulk.move()|
+`B`               Toggle No Buffer        |nvim-tree-api.tree.toggle_no_buffer_filter()|
+`c`               Copy                    |nvim-tree-api.fs.copy.node()|
+`C`               Toggle Git Clean        |nvim-tree-api.tree.toggle_git_clean_filter()|
+`[c`              Prev Git                |nvim-tree-api.node.navigate.git.prev()|
+`]c`              Next Git                |nvim-tree-api.node.navigate.git.next()|
+`d`               Delete                  |nvim-tree-api.fs.remove()|
+`D`               Trash                   |nvim-tree-api.fs.trash()|
+`E`               Expand All              |nvim-tree-api.tree.expand_all()|
+`e`               Rename: Basename        |nvim-tree-api.fs.rename_basename()|
+`]e`              Next Diagnostic         |nvim-tree-api.node.navigate.diagnostics.next()|
+`[e`              Prev Diagnostic         |nvim-tree-api.node.navigate.diagnostics.prev()|
+`F`               Clean Filter            |nvim-tree-api.live_filter.clear()|
+`f`               Filter                  |nvim-tree-api.live_filter.start()|
+`g?`              Help                    |nvim-tree-api.tree.toggle_help()|
+`gy`              Copy Absolute Path      |nvim-tree-api.fs.copy.absolute_path()|
+`H`               Toggle Dotfiles         |nvim-tree-api.tree.toggle_hidden_filter()|
+`I`               Toggle Git Ignore       |nvim-tree-api.tree.toggle_gitignore_filter()|
+`J`               Last Sibling            |nvim-tree-api.node.navigate.sibling.last()|
+`K`               First Sibling           |nvim-tree-api.node.navigate.sibling.first()|
+`m`               Toggle Bookmark         |nvim-tree-api.marks.toggle()|
+`o`               Open                    |nvim-tree-api.node.open.edit()|
+`O`               Open: No Window Picker  |nvim-tree-api.node.open.no_window_picker()|
+`p`               Paste                   |nvim-tree-api.fs.paste()|
+`P`               Parent Directory        |nvim-tree-api.node.navigate.parent()|
+`q`               Close                   |nvim-tree-api.tree.close()|
+`r`               Rename                  |nvim-tree-api.fs.rename()|
+`R`               Refresh                 |nvim-tree-api.tree.reload()|
+`s`               Run System              |nvim-tree-api.node.run.system()|
+`S`               Search                  |nvim-tree-api.tree.search_node()|
+`U`               Toggle Hidden           |nvim-tree-api.tree.toggle_custom_filter()|
+`W`               Collapse                |nvim-tree-api.tree.collapse_all()|
+`x`               Cut                     |nvim-tree-api.fs.cut()|
+`y`               Copy Name               |nvim-tree-api.fs.copy.filename()|
+`Y`               Copy Relative Path      |nvim-tree-api.fs.copy.relative_path()|
+`<2-LeftMouse>`   Open                    |nvim-tree-api.node.open.edit()|
+`<2-RightMouse>`  CD                      |nvim-tree-api.tree.change_root_to_node()|
+
 ==============================================================================
 3. COMMANDS                                              *nvim-tree-commands*

@ -1745,8 +1808,8 @@ commands.get()                                  *nvim-tree-api.commands.get()*
 6. MAPPINGS                                              *nvim-tree-mappings*

 Mappings are set via the |nvim-tree.on_attach| function, which is run upon
-creating the nvim-tree buffer. Mappings may be directly to |nvim-tree-api.
-functions or your own.
+creating the nvim-tree buffer. Mappings are usually |nvim-tree-api| functions
+however may be your own.

 When on_attach is not a function, |nvim-tree-mappings-default| will be used.

@ -1763,10 +1826,22 @@ The `on_attach` function is passed the `bufnr` of nvim-tree. Use
      return { desc = 'nvim-tree: ' .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true }
    end

-    -- put some default mappings here
+    -- copy default mappings here from defaults in next section
+    vim.keymap.set('n', '<C-]>', api.tree.change_root_to_node,          opts('CD'))
+    vim.keymap.set('n', '<C-e>', api.node.open.replace_tree_buffer,     opts('Open: In Place'))
+    ---
+    -- OR use all default mappings
+    api.config.mappings.default_on_attach(bufnr)

-    -- user mappings
-    vim.keymap.set('n', '?', api.tree.toggle_help, opts('Help'))
+    -- remove a default
+    vim.keymap.del('n', '<C-]>', { buffer = bufnr })
+
+    -- override a default
+    vim.keymap.set('n', '<C-e>', api.tree.reload,                       opts('Refresh'))
+
+    -- add your mappings
+    vim.keymap.set('n', '?',     api.tree.toggle_help,                  opts('Help'))
+    ---
  end

  require("nvim-tree").setup({
--- a/scripts/update-help.sh
+++ b/scripts/update-help.sh
@ -31,11 +31,23 @@ end="END_DEFAULT_ON_ATTACH"
 # scrape DEFAULT_ON_ATTACH, indented at 2
 sed -n -e "/${begin}/,/${end}/{ /${begin}/d; /${end}/d; p; }" lua/nvim-tree/keymap.lua > /tmp/DEFAULT_ON_ATTACH.lua

-# help
+# help lua
 sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/DEFAULT_ON_ATTACH.lua
           }; /${end}/p; d; }" doc/nvim-tree-lua.txt

-# legacy keymap
+# legacy keymap lua
 sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/DEFAULT_ON_ATTACH.lua
           }; /${end}/p; d; }" lua/nvim-tree/keymap-legacy.lua

+# help human
+echo > /tmp/DEFAULT_ON_ATTACH.help
+sed -E "s/^ *vim.keymap.set\('n', '(.*)',.*api(.*),.*opts\('(.*)'.*$/'\`\1\`' '\3' '|nvim-tree-api\2()|'/g
+" /tmp/DEFAULT_ON_ATTACH.lua | while read line
+do
+	eval "printf '%-17.17s %-23.23s %s\n' ${line}" >> /tmp/DEFAULT_ON_ATTACH.help
+done
+echo >> /tmp/DEFAULT_ON_ATTACH.help
+begin="Show the mappings:"
+end="======"
+sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/DEFAULT_ON_ATTACH.help
+           }; /${end}/p; d; }" doc/nvim-tree-lua.txt