tomas.mirchev/nvim-tree.lua
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: enhance quickstart, document git timeouts (#2400)

Browse Source 
* doc: clarify git and remove bookmarks

* doc: break up quickstart
This commit is contained in:
Alexander Courtis
2023-09-03 16:36:37 +10:00
committed by GitHub
parent a2b6e5ad2a
commit 277632fbd9
2 changed files with 61 additions and 91 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
README.md
View File

@@ -40,9 +40,11 @@ Please install via your preferred package manager. See [Installation](https://gi
`nvim-tree/nvim-web-devicons` optional, for file icons `nvim-tree/nvim-web-devicons` optional, for file icons
Disabling [netrw](https://neovim.io/doc/user/pi_netrw.html) is strongly advised, see [:help nvim-tree-netrw](doc/nvim-tree-lua.txt)
## Quick Start ## Quick Start
Disabling [netrw](https://neovim.io/doc/user/pi_netrw.html) is strongly advised, see [:help nvim-tree-netrw](doc/nvim-tree-lua.txt) ### Setup
Setup the plugin in your `init.lua` Setup the plugin in your `init.lua`
@@ -72,7 +74,15 @@ require("nvim-tree").setup({
}) })
``` ```
Optionally customise your mappings, see [:help nvim-tree-mappings](doc/nvim-tree-lua.txt) ### Help
Open the tree: `:NvimTreeOpen`
Show the mappings: `g?`
### Custom Mappings
[: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.
```lua ```lua
local function my_on_attach(bufnr) local function my_on_attach(bufnr)
@@ -98,14 +108,6 @@ 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)
## Commands ## Commands
See [:help nvim-tree-commands](doc/nvim-tree-lua.txt) See [:help nvim-tree-commands](doc/nvim-tree-lua.txt)
@@ -120,12 +122,6 @@ Basic commands:
`:NvimTreeCollapse` Collapses the nvim-tree recursively. `:NvimTreeCollapse` Collapses the nvim-tree recursively.
## Mappings
`g?` toggles help, showing all the mappings and their actions.
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)
## Roadmap ## Roadmap
nvim-tree is stable and new major features will not be added. The focus is on existing user experience. 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
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. 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.
### Help Wanted
Developers with the following environments:
* Apple macOS
* Windows
* WSL
* msys
* powershell
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.
Let us know you're interested by commenting on issues and raising PRs.
## Screenshots ## Screenshots
See [Showcases](https://github.com/nvim-tree/nvim-tree.lua/wiki/Showcases) wiki page for examples of user's configurations with sources. See [Showcases](https://github.com/nvim-tree/nvim-tree.lua/wiki/Showcases) wiki page for examples of user's configurations with sources.

108
doc/nvim-tree-lua.txt
View File

@@ -7,6 +7,9 @@ CONTENTS *nvim-tree*
1. Introduction |nvim-tree-introduction| 1. Introduction |nvim-tree-introduction|
2. Quickstart |nvim-tree-quickstart| 2. Quickstart |nvim-tree-quickstart|
2.1 Quickstart: Setup |nvim-tree-quickstart-setup|
2.2 Quickstart: Help |nvim-tree-quickstart-help|
2.3 Quickstart: Custom Mappings |nvim-tree-quickstart-custom-mappings|
3. Commands |nvim-tree-commands| 3. Commands |nvim-tree-commands|
4. Setup |nvim-tree-setup| 4. Setup |nvim-tree-setup|
5. Opts |nvim-tree-opts| 5. Opts |nvim-tree-opts|
@@ -40,12 +43,11 @@ CONTENTS *nvim-tree*
6.8 API Config |nvim-tree-api.config| 6.8 API Config |nvim-tree-api.config|
6.9 API Commands |nvim-tree-api.commands| 6.9 API Commands |nvim-tree-api.commands|
7. Mappings |nvim-tree-mappings| 7. Mappings |nvim-tree-mappings|
7.1 Default Mappings |nvim-tree-mappings-default| 7.1 Mappings: Default |nvim-tree-mappings-default|
8. Highlight |nvim-tree-highlight| 8. Highlight |nvim-tree-highlight|
9. Events |nvim-tree-events| 9. Events |nvim-tree-events|
10. Bookmarks |nvim-tree-bookmarks| 10. OS Specific Restrictions |nvim-tree-os-specific|
11. OS Specific Restrictions |nvim-tree-os-specific| 11. Netrw |nvim-tree-netrw|
12. Netrw |nvim-tree-netrw|
============================================================================== ==============================================================================
1. INTRODUCTION *nvim-tree-introduction* 1. INTRODUCTION *nvim-tree-introduction*
@@ -100,6 +102,9 @@ Install the plugins via your package manager:
Disabling |netrw| is strongly advised, see |nvim-tree-netrw| Disabling |netrw| is strongly advised, see |nvim-tree-netrw|
==============================================================================
2.1 QUICKSTART: SETUP *nvim-tree-quickstart-setup*
Setup the plugin in your `init.lua` > Setup the plugin in your `init.lua` >
-- disable netrw at the very start of your init.lua -- disable netrw at the very start of your init.lua
@@ -128,30 +133,9 @@ Setup the plugin in your `init.lua` >
}, },
}) })
< <
Optionally customise your |nvim-tree-mappings| via |nvim-tree.on_attach| > ==============================================================================
2.2 QUICKSTART: HELP *nvim-tree-quickstart-help*
local function my_on_attach(bufnr)
local api = require "nvim-tree.api"
local function opts(desc)
return { desc = "nvim-tree: " .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true }
end
-- default mappings
api.config.mappings.default_on_attach(bufnr)
-- custom mappings
vim.keymap.set('n', '<C-t>', api.tree.change_root_to_parent, opts('Up'))
vim.keymap.set('n', '?', api.tree.toggle_help, opts('Help'))
end
-- pass to setup along with your other options
require("nvim-tree").setup {
---
on_attach = my_on_attach,
---
}
<
Open the tree: `:NvimTreeOpen` Open the tree: `:NvimTreeOpen`
Show the mappings: `g?` Show the mappings: `g?`
@@ -210,6 +194,34 @@ Show the mappings: `g?`
`<2-LeftMouse>` Open |nvim-tree-api.node.open.edit()| `<2-LeftMouse>` Open |nvim-tree-api.node.open.edit()|
`<2-RightMouse>` CD |nvim-tree-api.tree.change_root_to_node()| `<2-RightMouse>` CD |nvim-tree-api.tree.change_root_to_node()|
==============================================================================
2.3 QUICKSTART: CUSTOM MAPPINGS *nvim-tree-quickstart-custom-mappings*
|nvim-tree-mappings-default| are applied by default however you may customise
via |nvim-tree.on_attach| e.g. >
local function my_on_attach(bufnr)
local api = require "nvim-tree.api"
local function opts(desc)
return { desc = "nvim-tree: " .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true }
end
-- default mappings
api.config.mappings.default_on_attach(bufnr)
-- custom mappings
vim.keymap.set('n', '<C-t>', api.tree.change_root_to_parent, opts('Up'))
vim.keymap.set('n', '?', api.tree.toggle_help, opts('Help'))
end
-- pass to setup along with your other options
require("nvim-tree").setup {
---
on_attach = my_on_attach,
---
}
<
============================================================================== ==============================================================================
3. COMMANDS *nvim-tree-commands* 3. COMMANDS *nvim-tree-commands*
@@ -1050,15 +1062,13 @@ Leave empty for OS specific default:
============================================================================== ==============================================================================
5.7 OPTS: GIT *nvim-tree-opts-git* 5.7 OPTS: GIT *nvim-tree-opts-git*
You will still need to set |renderer.icons.show.git| `= true` or Git operations are run in the background thus status may not immediately
|renderer.highlight_git| `= true` to be able to see git status in the appear.
tree. This will be changed in the future versions.
The configurable timeout will kill the current process and so disable the Processes will be killed if they exceed |nvim-tree.git.timeout|
git integration for the project that takes too long.
The git integration is blocking, so if your timeout is too long (like not in Git integration will be disabled following 5 timeouts and you will be
milliseconds but a few seconds), it will not render anything until the git notified.
process returned the data.
*nvim-tree.git.enable* *nvim-tree.git.enable*
Enable / disable the feature. Enable / disable the feature.
@@ -2007,7 +2017,7 @@ You may execute your own functions as well as |nvim-tree-api| functions e.g. >
vim.keymap.set('n', '<C-P>', print_node_path, opts('Print Path')) vim.keymap.set('n', '<C-P>', print_node_path, opts('Print Path'))
< <
============================================================================== ==============================================================================
7.1 DEFAULT MAPPINGS *nvim-tree-mappings-default* 7.1 MAPPINGS: DEFAULT *nvim-tree-mappings-default*
In the absence of an |nvim-tree.on_attach| function, the following defaults In the absence of an |nvim-tree.on_attach| function, the following defaults
will be applied. will be applied.
@@ -2304,29 +2314,7 @@ Example subscription: >
}) })
< <
============================================================================== ==============================================================================
10. BOOKMARKS *nvim-tree-bookmarks* 10. OS SPECIFIC RESTRICTIONS *nvim-tree-os-specific*
You can toggle marks on files/folders with
`require("nvim-tree.api").marks.toggle(node)` which is bound to `m` by
default.
To get the list of marked paths, you can call
`require("nvim-tree.api").marks.list()`. This will return `{node}`.
*nvim-tree.bookmarks.navigation*
Navigation for marks is not bound by default in nvim-tree because we don't
want to focus the tree view each time we wish to switch to another mark.
This requires binding bookmark navigation yourself.
-- in your lua configuration
vim.keymap.set("n", "<leader>mn", require("nvim-tree.api").marks.navigate.next)
vim.keymap.set("n", "<leader>mp", require("nvim-tree.api").marks.navigate.prev)
vim.keymap.set("n", "<leader>ms", require("nvim-tree.api").marks.navigate.select)
==============================================================================
11. OS SPECIFIC RESTRICTIONS *nvim-tree-os-specific*
macOS macOS
- Rename to different case is not possible when using a case insensitive file - Rename to different case is not possible when using a case insensitive file
@@ -2339,7 +2327,7 @@ Windows WSL and PowerShell
- Some filesystem watcher error related to permissions will not be reported - Some filesystem watcher error related to permissions will not be reported
============================================================================== ==============================================================================
12. NETRW *nvim-tree-netrw* 11. NETRW *nvim-tree-netrw*
|netrw| is a standard neovim plugin that is enabled by default. It provides, |netrw| is a standard neovim plugin that is enabled by default. It provides,
amongst other functionality, a file/directory browser. amongst other functionality, a file/directory browser.