Skip to content

Commit 74996b8

Browse files
alex-courtisalex-courtis
authored
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
1 parent 1f5bbc1 commit 74996b8

File tree

3 files changed

+104
-12
lines changed

3 files changed

+104
-12
lines changed

‎README.md

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -44,13 +44,11 @@ Please install via your preferred package manager. See [Installation](https://gi
4444

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

47-
## Setup
47+
## Quick Start
4848

49-
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.
49+
Setup the plugin in your `init.lua`
5050

5151
```lua
52-
-- examples for your init.lua
53-
5452
-- disable netrw at the very start of your init.lua (strongly advised)
5553
vim.g.loaded_netrw = 1
5654
vim.g.loaded_netrwPlugin = 1
@@ -64,6 +62,9 @@ require("nvim-tree").setup()
6462
-- OR setup with some options
6563
require("nvim-tree").setup({
6664
sort_by = "case_sensitive",
65+
view = {
66+
width = 30,
67+
},
6768
renderer = {
6869
group_empty = true,
6970
},
@@ -73,6 +74,10 @@ require("nvim-tree").setup({
7374
})
7475
```
7576

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

7883
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)

‎doc/nvim-tree-lua.txt

Lines changed: 81 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,13 @@ Requirements
7373

7474
==============================================================================
7575
2. QUICK START *nvim-tree-quickstart*
76-
>
76+
77+
Install the plugins via your package manager:
78+
`"nvim-tree/nvim-tree.lua"`
79+
`"nvim-tree/nvim-web-devicons"`
80+
81+
Setup the plugin in your `init.lua` >
82+
7783
-- disable netrw at the very start of your init.lua (strongly advised)
7884
vim.g.loaded_netrw = 1
7985
vim.g.loaded_netrwPlugin = 1
@@ -98,6 +104,63 @@ Requirements
98104
},
99105
})
100106
<
107+
Open the tree: `:NvimTreeOpen`
108+
109+
Show the mappings: `g?`
110+
111+
`<C-]>` CD |nvim-tree-api.tree.change_root_to_node()|
112+
`<C-e>` Open: In Place |nvim-tree-api.node.open.replace_tree_buffer()|
113+
`<C-k>` Info |nvim-tree-api.node.show_info_popup()|
114+
`<C-r>` Rename: Omit Filename |nvim-tree-api.fs.rename_sub()|
115+
`<C-t>` Open: New Tab |nvim-tree-api.node.open.tab()|
116+
`<C-v>` Open: Vertical Split |nvim-tree-api.node.open.vertical()|
117+
`<C-x>` Open: Horizontal Split |nvim-tree-api.node.open.horizontal()|
118+
`<BS>` Close Directory |nvim-tree-api.node.navigate.parent_close()|
119+
`<CR>` Open |nvim-tree-api.node.open.edit()|
120+
`<Tab>` Open Preview |nvim-tree-api.node.open.preview()|
121+
`>` Next Sibling |nvim-tree-api.node.navigate.sibling.next()|
122+
`<` Previous Sibling |nvim-tree-api.node.navigate.sibling.prev()|
123+
`.` Run Command |nvim-tree-api.node.run.cmd()|
124+
`-` Up |nvim-tree-api.tree.change_root_to_parent()|
125+
`a` Create |nvim-tree-api.fs.create()|
126+
`bmv` Move Bookmarked |nvim-tree-api.marks.bulk.move()|
127+
`B` Toggle No Buffer |nvim-tree-api.tree.toggle_no_buffer_filter()|
128+
`c` Copy |nvim-tree-api.fs.copy.node()|
129+
`C` Toggle Git Clean |nvim-tree-api.tree.toggle_git_clean_filter()|
130+
`[c` Prev Git |nvim-tree-api.node.navigate.git.prev()|
131+
`]c` Next Git |nvim-tree-api.node.navigate.git.next()|
132+
`d` Delete |nvim-tree-api.fs.remove()|
133+
`D` Trash |nvim-tree-api.fs.trash()|
134+
`E` Expand All |nvim-tree-api.tree.expand_all()|
135+
`e` Rename: Basename |nvim-tree-api.fs.rename_basename()|
136+
`]e` Next Diagnostic |nvim-tree-api.node.navigate.diagnostics.next()|
137+
`[e` Prev Diagnostic |nvim-tree-api.node.navigate.diagnostics.prev()|
138+
`F` Clean Filter |nvim-tree-api.live_filter.clear()|
139+
`f` Filter |nvim-tree-api.live_filter.start()|
140+
`g?` Help |nvim-tree-api.tree.toggle_help()|
141+
`gy` Copy Absolute Path |nvim-tree-api.fs.copy.absolute_path()|
142+
`H` Toggle Dotfiles |nvim-tree-api.tree.toggle_hidden_filter()|
143+
`I` Toggle Git Ignore |nvim-tree-api.tree.toggle_gitignore_filter()|
144+
`J` Last Sibling |nvim-tree-api.node.navigate.sibling.last()|
145+
`K` First Sibling |nvim-tree-api.node.navigate.sibling.first()|
146+
`m` Toggle Bookmark |nvim-tree-api.marks.toggle()|
147+
`o` Open |nvim-tree-api.node.open.edit()|
148+
`O` Open: No Window Picker |nvim-tree-api.node.open.no_window_picker()|
149+
`p` Paste |nvim-tree-api.fs.paste()|
150+
`P` Parent Directory |nvim-tree-api.node.navigate.parent()|
151+
`q` Close |nvim-tree-api.tree.close()|
152+
`r` Rename |nvim-tree-api.fs.rename()|
153+
`R` Refresh |nvim-tree-api.tree.reload()|
154+
`s` Run System |nvim-tree-api.node.run.system()|
155+
`S` Search |nvim-tree-api.tree.search_node()|
156+
`U` Toggle Hidden |nvim-tree-api.tree.toggle_custom_filter()|
157+
`W` Collapse |nvim-tree-api.tree.collapse_all()|
158+
`x` Cut |nvim-tree-api.fs.cut()|
159+
`y` Copy Name |nvim-tree-api.fs.copy.filename()|
160+
`Y` Copy Relative Path |nvim-tree-api.fs.copy.relative_path()|
161+
`<2-LeftMouse>` Open |nvim-tree-api.node.open.edit()|
162+
`<2-RightMouse>` CD |nvim-tree-api.tree.change_root_to_node()|
163+
101164
==============================================================================
102165
3. COMMANDS *nvim-tree-commands*
103166

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

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

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

@@ -1763,10 +1826,22 @@ The `on_attach` function is passed the `bufnr` of nvim-tree. Use
17631826
return { desc = 'nvim-tree: ' .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true }
17641827
end
17651828
1766-
-- put some default mappings here
1829+
-- copy default mappings here from defaults in next section
1830+
vim.keymap.set('n', '<C-]>', api.tree.change_root_to_node, opts('CD'))
1831+
vim.keymap.set('n', '<C-e>', api.node.open.replace_tree_buffer, opts('Open: In Place'))
1832+
---
1833+
-- OR use all default mappings
1834+
api.config.mappings.default_on_attach(bufnr)
1835+
1836+
-- remove a default
1837+
vim.keymap.del('n', '<C-]>', { buffer = bufnr })
17671838
1768-
-- user mappings
1769-
vim.keymap.set('n', '?', api.tree.toggle_help, opts('Help'))
1839+
-- override a default
1840+
vim.keymap.set('n', '<C-e>', api.tree.reload, opts('Refresh'))
1841+
1842+
-- add your mappings
1843+
vim.keymap.set('n', '?', api.tree.toggle_help, opts('Help'))
1844+
---
17701845
end
17711846
17721847
require("nvim-tree").setup({

‎scripts/update-help.sh

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,11 +31,23 @@ end="END_DEFAULT_ON_ATTACH"
3131
# scrape DEFAULT_ON_ATTACH, indented at 2
3232
sed -n -e "/${begin}/,/${end}/{ /${begin}/d; /${end}/d; p; }" lua/nvim-tree/keymap.lua > /tmp/DEFAULT_ON_ATTACH.lua
3333

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

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

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

0 commit comments

Comments
 (0)