Skip to content

Commit 277632f

Browse files
alex-courtisalex-courtis
authored
docs: enhance quickstart, document git timeouts (#2400)
* doc: clarify git and remove bookmarks * doc: break up quickstart
1 parent a2b6e5a commit 277632f

File tree

2 files changed

+61
-91
lines changed

2 files changed

+61
-91
lines changed

‎README.md

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

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

43+
Disabling [netrw](https://neovim.io/doc/user/pi_netrw.html) is strongly advised, see [:help nvim-tree-netrw](doc/nvim-tree-lua.txt)
44+
4345
## Quick Start
4446

45-
Disabling [netrw](https://neovim.io/doc/user/pi_netrw.html) is strongly advised, see [:help nvim-tree-netrw](doc/nvim-tree-lua.txt)
47+
### Setup
4648

4749
Setup the plugin in your `init.lua`
4850

@@ -72,7 +74,15 @@ require("nvim-tree").setup({
7274
})
7375
```
7476

75-
Optionally customise your mappings, see [:help nvim-tree-mappings](doc/nvim-tree-lua.txt)
77+
### Help
78+
79+
Open the tree: `:NvimTreeOpen`
80+
81+
Show the mappings: `g?`
82+
83+
### Custom Mappings
84+
85+
[:help nvim-tree-mappings-default](doc/nvim-tree-lua.txt) are applied by default however you may customise via |nvim-tree.on_attach| e.g.
7686

7787
```lua
7888
local function my_on_attach(bufnr)
@@ -98,14 +108,6 @@ require("nvim-tree").setup {
98108
}
99109
```
100110

101-
Open the tree: `:NvimTreeOpen`
102-
103-
Show the mappings: `g?`
104-
105-
For complete list of available configuration options see [:help nvim-tree-setup](doc/nvim-tree-lua.txt)
106-
107-
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)
108-
109111
## Commands
110112

111113
See [:help nvim-tree-commands](doc/nvim-tree-lua.txt)
@@ -120,12 +122,6 @@ Basic commands:
120122

121123
`:NvimTreeCollapse` Collapses the nvim-tree recursively.
122124

123-
## Mappings
124-
125-
`g?` toggles help, showing all the mappings and their actions.
126-
127-
To customise your mappings see [:help nvim-tree.on_attach](doc/nvim-tree-lua.txt) and [:help nvim-tree-mappings](doc/nvim-tree-lua.txt)
128-
129125
## Roadmap
130126

131127
nvim-tree is stable and new major features will not be added. The focus is on existing user experience.
@@ -155,20 +151,6 @@ PRs are always welcome. See [wiki](https://github.com/nvim-tree/nvim-tree.lua/wi
155151

156152
See [bug](https://github.com/nvim-tree/nvim-tree.lua/issues?q=is%3Aissue+is%3Aopen+label%3Abug) and [PR Please](https://github.com/nvim-tree/nvim-tree.lua/issues?q=is%3Aopen+is%3Aissue+label%3A%22PR+please%22) issues if you are looking for some work to get you started.
157153

158-
### Help Wanted
159-
160-
Developers with the following environments:
161-
162-
* Apple macOS
163-
* Windows
164-
* WSL
165-
* msys
166-
* powershell
167-
168-
Help triaging, diagnosing and fixing issues specific to those environments is needed, as the nvim-tree developers do not have access to or expertise in these environments.
169-
170-
Let us know you're interested by commenting on issues and raising PRs.
171-
172154
## Screenshots
173155

174156
See [Showcases](https://github.com/nvim-tree/nvim-tree.lua/wiki/Showcases) wiki page for examples of user's configurations with sources.

‎doc/nvim-tree-lua.txt

Lines changed: 49 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@ CONTENTS *nvim-tree*
77

88
1. Introduction |nvim-tree-introduction|
99
2. Quickstart |nvim-tree-quickstart|
10+
2.1 Quickstart: Setup |nvim-tree-quickstart-setup|
11+
2.2 Quickstart: Help |nvim-tree-quickstart-help|
12+
2.3 Quickstart: Custom Mappings |nvim-tree-quickstart-custom-mappings|
1013
3. Commands |nvim-tree-commands|
1114
4. Setup |nvim-tree-setup|
1215
5. Opts |nvim-tree-opts|
@@ -40,12 +43,11 @@ CONTENTS *nvim-tree*
4043
6.8 API Config |nvim-tree-api.config|
4144
6.9 API Commands |nvim-tree-api.commands|
4245
7. Mappings |nvim-tree-mappings|
43-
7.1 Default Mappings |nvim-tree-mappings-default|
46+
7.1 Mappings: Default |nvim-tree-mappings-default|
4447
8. Highlight |nvim-tree-highlight|
4548
9. Events |nvim-tree-events|
46-
10. Bookmarks |nvim-tree-bookmarks|
47-
11. OS Specific Restrictions |nvim-tree-os-specific|
48-
12. Netrw |nvim-tree-netrw|
49+
10. OS Specific Restrictions |nvim-tree-os-specific|
50+
11. Netrw |nvim-tree-netrw|
4951

5052
==============================================================================
5153
1. INTRODUCTION *nvim-tree-introduction*
@@ -92,14 +94,17 @@ Requirements
9294
This file explorer requires `neovim >= 0.8.0`
9395

9496
==============================================================================
95-
2. QUICK START *nvim-tree-quickstart*
97+
2. QUICKSTART *nvim-tree-quickstart*
9698

9799
Install the plugins via your package manager:
98100
`"nvim-tree/nvim-tree.lua"`
99101
`"nvim-tree/nvim-web-devicons"`
100102

101103
Disabling |netrw| is strongly advised, see |nvim-tree-netrw|
102104

105+
==============================================================================
106+
2.1 QUICKSTART: SETUP *nvim-tree-quickstart-setup*
107+
103108
Setup the plugin in your `init.lua` >
104109
105110
-- disable netrw at the very start of your init.lua
@@ -128,30 +133,9 @@ Setup the plugin in your `init.lua` >
128133
},
129134
})
130135
<
131-
Optionally customise your |nvim-tree-mappings| via |nvim-tree.on_attach| >
132-
133-
local function my_on_attach(bufnr)
134-
local api = require "nvim-tree.api"
135-
136-
local function opts(desc)
137-
return { desc = "nvim-tree: " .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true }
138-
end
139-
140-
-- default mappings
141-
api.config.mappings.default_on_attach(bufnr)
142-
143-
-- custom mappings
144-
vim.keymap.set('n', '<C-t>', api.tree.change_root_to_parent, opts('Up'))
145-
vim.keymap.set('n', '?', api.tree.toggle_help, opts('Help'))
146-
end
136+
==============================================================================
137+
2.2 QUICKSTART: HELP *nvim-tree-quickstart-help*
147138

148-
-- pass to setup along with your other options
149-
require("nvim-tree").setup {
150-
---
151-
on_attach = my_on_attach,
152-
---
153-
}
154-
<
155139
Open the tree: `:NvimTreeOpen`
156140

157141
Show the mappings: `g?`
@@ -210,6 +194,34 @@ Show the mappings: `g?`
210194
`<2-LeftMouse>` Open |nvim-tree-api.node.open.edit()|
211195
`<2-RightMouse>` CD |nvim-tree-api.tree.change_root_to_node()|
212196

197+
==============================================================================
198+
2.3 QUICKSTART: CUSTOM MAPPINGS *nvim-tree-quickstart-custom-mappings*
199+
200+
|nvim-tree-mappings-default| are applied by default however you may customise
201+
via |nvim-tree.on_attach| e.g. >
202+
203+
local function my_on_attach(bufnr)
204+
local api = require "nvim-tree.api"
205+
206+
local function opts(desc)
207+
return { desc = "nvim-tree: " .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true }
208+
end
209+
210+
-- default mappings
211+
api.config.mappings.default_on_attach(bufnr)
212+
213+
-- custom mappings
214+
vim.keymap.set('n', '<C-t>', api.tree.change_root_to_parent, opts('Up'))
215+
vim.keymap.set('n', '?', api.tree.toggle_help, opts('Help'))
216+
end
217+
218+
-- pass to setup along with your other options
219+
require("nvim-tree").setup {
220+
---
221+
on_attach = my_on_attach,
222+
---
223+
}
224+
<
213225
==============================================================================
214226
3. COMMANDS *nvim-tree-commands*
215227

@@ -1050,15 +1062,13 @@ Leave empty for OS specific default:
10501062
==============================================================================
10511063
5.7 OPTS: GIT *nvim-tree-opts-git*
10521064

1053-
You will still need to set |renderer.icons.show.git| `= true` or
1054-
|renderer.highlight_git| `= true` to be able to see git status in the
1055-
tree. This will be changed in the future versions.
1065+
Git operations are run in the background thus status may not immediately
1066+
appear.
1067+
1068+
Processes will be killed if they exceed |nvim-tree.git.timeout|
10561069

1057-
The configurable timeout will kill the current process and so disable the
1058-
git integration for the project that takes too long.
1059-
The git integration is blocking, so if your timeout is too long (like not in
1060-
milliseconds but a few seconds), it will not render anything until the git
1061-
process returned the data.
1070+
Git integration will be disabled following 5 timeouts and you will be
1071+
notified.
10621072

10631073
*nvim-tree.git.enable*
10641074
Enable / disable the feature.
@@ -2007,7 +2017,7 @@ You may execute your own functions as well as |nvim-tree-api| functions e.g. >
20072017
vim.keymap.set('n', '<C-P>', print_node_path, opts('Print Path'))
20082018
<
20092019
==============================================================================
2010-
7.1 DEFAULT MAPPINGS *nvim-tree-mappings-default*
2020+
7.1 MAPPINGS: DEFAULT *nvim-tree-mappings-default*
20112021

20122022
In the absence of an |nvim-tree.on_attach| function, the following defaults
20132023
will be applied.
@@ -2304,29 +2314,7 @@ Example subscription: >
23042314
})
23052315
<
23062316
==============================================================================
2307-
10. BOOKMARKS *nvim-tree-bookmarks*
2308-
2309-
You can toggle marks on files/folders with
2310-
`require("nvim-tree.api").marks.toggle(node)` which is bound to `m` by
2311-
default.
2312-
2313-
To get the list of marked paths, you can call
2314-
`require("nvim-tree.api").marks.list()`. This will return `{node}`.
2315-
2316-
*nvim-tree.bookmarks.navigation*
2317-
2318-
Navigation for marks is not bound by default in nvim-tree because we don't
2319-
want to focus the tree view each time we wish to switch to another mark.
2320-
2321-
This requires binding bookmark navigation yourself.
2322-
2323-
-- in your lua configuration
2324-
vim.keymap.set("n", "<leader>mn", require("nvim-tree.api").marks.navigate.next)
2325-
vim.keymap.set("n", "<leader>mp", require("nvim-tree.api").marks.navigate.prev)
2326-
vim.keymap.set("n", "<leader>ms", require("nvim-tree.api").marks.navigate.select)
2327-
2328-
==============================================================================
2329-
11. OS SPECIFIC RESTRICTIONS *nvim-tree-os-specific*
2317+
10. OS SPECIFIC RESTRICTIONS *nvim-tree-os-specific*
23302318

23312319
macOS
23322320
- Rename to different case is not possible when using a case insensitive file
@@ -2339,7 +2327,7 @@ Windows WSL and PowerShell
23392327
- Some filesystem watcher error related to permissions will not be reported
23402328

23412329
==============================================================================
2342-
12. NETRW *nvim-tree-netrw*
2330+
11. NETRW *nvim-tree-netrw*
23432331

23442332
|netrw| is a standard neovim plugin that is enabled by default. It provides,
23452333
amongst other functionality, a file/directory browser.

0 commit comments

Comments
 (0)