From 277632fbd9810d20ced10e2ba155bd4f6a68d56e Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sun, 3 Sep 2023 16:36:37 +1000 Subject: [PATCH] docs: enhance quickstart, document git timeouts (#2400) * doc: clarify git and remove bookmarks * doc: break up quickstart --- README.md | 42 +++++----------- doc/nvim-tree-lua.txt | 110 +++++++++++++++++++----------------------- 2 files changed, 61 insertions(+), 91 deletions(-) diff --git a/README.md b/README.md index 98a9c5be..359368cf 100644 --- a/README.md +++ b/README.md @@ -40,9 +40,11 @@ Please install via your preferred package manager. See [Installation](https://gi `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 -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` @@ -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 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 See [:help nvim-tree-commands](doc/nvim-tree-lua.txt) @@ -120,12 +122,6 @@ Basic commands: `: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 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. -### 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 See [Showcases](https://github.com/nvim-tree/nvim-tree.lua/wiki/Showcases) wiki page for examples of user's configurations with sources. diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 57245187..4f2c95d2 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -7,6 +7,9 @@ CONTENTS *nvim-tree* 1. Introduction |nvim-tree-introduction| 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| 4. Setup |nvim-tree-setup| 5. Opts |nvim-tree-opts| @@ -40,12 +43,11 @@ CONTENTS *nvim-tree* 6.8 API Config |nvim-tree-api.config| 6.9 API Commands |nvim-tree-api.commands| 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| 9. Events |nvim-tree-events| - 10. Bookmarks |nvim-tree-bookmarks| - 11. OS Specific Restrictions |nvim-tree-os-specific| - 12. Netrw |nvim-tree-netrw| + 10. OS Specific Restrictions |nvim-tree-os-specific| + 11. Netrw |nvim-tree-netrw| ============================================================================== 1. INTRODUCTION *nvim-tree-introduction* @@ -92,7 +94,7 @@ Requirements This file explorer requires `neovim >= 0.8.0` ============================================================================== - 2. QUICK START *nvim-tree-quickstart* + 2. QUICKSTART *nvim-tree-quickstart* Install the plugins via your package manager: `"nvim-tree/nvim-tree.lua"` @@ -100,6 +102,9 @@ Install the plugins via your package manager: Disabling |netrw| is strongly advised, see |nvim-tree-netrw| +============================================================================== + 2.1 QUICKSTART: SETUP *nvim-tree-quickstart-setup* + Setup the plugin in 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', '', 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` Show the mappings: `g?` @@ -210,6 +194,34 @@ Show the mappings: `g?` `<2-LeftMouse>` Open |nvim-tree-api.node.open.edit()| `<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', '', 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* @@ -1050,15 +1062,13 @@ Leave empty for OS specific default: ============================================================================== 5.7 OPTS: GIT *nvim-tree-opts-git* -You will still need to set |renderer.icons.show.git| `= true` or -|renderer.highlight_git| `= true` to be able to see git status in the -tree. This will be changed in the future versions. +Git operations are run in the background thus status may not immediately +appear. -The configurable timeout will kill the current process and so disable the -git integration for the project that takes too long. -The git integration is blocking, so if your timeout is too long (like not in -milliseconds but a few seconds), it will not render anything until the git -process returned the data. +Processes will be killed if they exceed |nvim-tree.git.timeout| + +Git integration will be disabled following 5 timeouts and you will be +notified. *nvim-tree.git.enable* 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', '', 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 will be applied. @@ -2304,29 +2314,7 @@ Example subscription: > }) < ============================================================================== - 10. BOOKMARKS *nvim-tree-bookmarks* - -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", "mn", require("nvim-tree.api").marks.navigate.next) -vim.keymap.set("n", "mp", require("nvim-tree.api").marks.navigate.prev) -vim.keymap.set("n", "ms", require("nvim-tree.api").marks.navigate.select) - -============================================================================== - 11. OS SPECIFIC RESTRICTIONS *nvim-tree-os-specific* + 10. OS SPECIFIC RESTRICTIONS *nvim-tree-os-specific* macOS - 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 ============================================================================== - 12. NETRW *nvim-tree-netrw* + 11. NETRW *nvim-tree-netrw* |netrw| is a standard neovim plugin that is enabled by default. It provides, amongst other functionality, a file/directory browser.