Skip to content

docs: enhance quickstart, document git timeouts #2400

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Sep 3, 2023
Merged

docs: enhance quickstart, document git timeouts #2400

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2a947c7
doc: clarify git and remove bookmarks
alex-courtis Sep 3, 2023
8c4f52f
doc: break up quickstart
alex-courtis Sep 3, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 12 additions & 30 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`

Expand Down Expand Up @@ -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)
Expand All @@ -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)
Expand All @@ -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.
Expand Down Expand Up @@ -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.
Expand Down
110 changes: 49 additions & 61 deletions doc/nvim-tree-lua.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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|
Expand Down Expand Up @@ -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*
Expand Down Expand Up @@ -92,14 +94,17 @@ 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"`
`"nvim-tree/nvim-web-devicons"`

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
Expand Down Expand Up @@ -128,30 +133,9 @@ Setup the plugin in your `init.lua` >
},
})
<
Optionally customise your |nvim-tree-mappings| via |nvim-tree.on_attach| >

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
==============================================================================
2.2 QUICKSTART: HELP *nvim-tree-quickstart-help*

-- 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?`
Expand Down Expand Up @@ -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', '<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*

Expand Down Expand Up @@ -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.

Processes will be killed if they exceed |nvim-tree.git.timeout|

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.
Git integration will be disabled following 5 timeouts and you will be
notified.

*nvim-tree.git.enable*
Enable / disable the feature.
Expand Down Expand Up @@ -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'))
<
==============================================================================
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.
Expand Down Expand Up @@ -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", "<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*
10. OS SPECIFIC RESTRICTIONS *nvim-tree-os-specific*

macOS
- Rename to different case is not possible when using a case insensitive file
Expand All @@ -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.
Expand Down