aba394896b
* docs: lighten up readme and rework docs * docs: clean up mappings from readme + some other small changes * docs: move sections around * ci: remove readme parts of docs' autogen * docs: discuss nvim-web-devicons and provide an example * docs: add an example setup * docs: fix opts scraping; try and make more macos compatible * docs: add *nvim-tree* tag at start of help * docs: add an example setup * docs: update quick start to match readme * docs: add basic commands * docs: add g? hint * docs: add :help links to readme * docs: restore help wanted * docs: add example screenshot * docs: add features * docs: add example screenshot * docs: add features to help * docs: clarify option functions Co-authored-by: Alexander Courtis <alex@courtis.org>
168 lines
5.5 KiB
Markdown
168 lines
5.5 KiB
Markdown
# A File Explorer For Neovim Written In Lua
|
|
|
|
[](https://github.com/kyazdani42/nvim-tree.lua/actions/workflows/ci.yml)
|
|
|
|
<img align="left" width="124" height="332" src=".github/example.png?raw=true">
|
|
|
|
Automatic updates
|
|
|
|
File type icons
|
|
|
|
Git integration
|
|
|
|
Diagnostics integration: LSP and COC
|
|
|
|
(Live) filtering
|
|
|
|
Cut, copy, paste, rename, delete, create
|
|
|
|
Highly customisable
|
|
|
|
<br clear="left"/>
|
|
|
|
## Install
|
|
|
|
This plugin requires [neovim >=0.7.0](https://github.com/neovim/neovim/wiki/Installing-Neovim).
|
|
|
|
Install with [vim-plug](https://github.com/junegunn/vim-plug):
|
|
|
|
```vim
|
|
Plug 'kyazdani42/nvim-web-devicons' " optional, for file icons
|
|
Plug 'kyazdani42/nvim-tree.lua'
|
|
```
|
|
|
|
or with [packer](https://github.com/wbthomason/packer.nvim):
|
|
|
|
```lua
|
|
use {
|
|
'kyazdani42/nvim-tree.lua',
|
|
requires = {
|
|
'kyazdani42/nvim-web-devicons', -- optional, for file icons
|
|
},
|
|
tag = 'nightly' -- optional, updated every week. (see issue #1193)
|
|
}
|
|
```
|
|
|
|
## Setup
|
|
|
|
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.
|
|
|
|
Setup may only be run once; subsequent calls will result in a warning.
|
|
|
|
```lua
|
|
-- examples for your init.lua
|
|
|
|
-- empty setup using defaults
|
|
require("nvim-tree").setup()
|
|
|
|
-- OR setup with some options
|
|
require("nvim-tree").setup({
|
|
sort_by = "case_sensitive",
|
|
view = {
|
|
adaptive_size = true,
|
|
mappings = {
|
|
list = {
|
|
{ key = "u", action = "dir_up" },
|
|
},
|
|
},
|
|
},
|
|
renderer = {
|
|
group_empty = true,
|
|
},
|
|
filters = {
|
|
dotfiles = true,
|
|
},
|
|
})
|
|
```
|
|
|
|
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.view.mappings](doc/nvim-tree-lua.txt)
|
|
|
|
## Commands
|
|
|
|
See [:help nvim-tree-commands](doc/nvim-tree-lua.txt)
|
|
|
|
Basic commands:
|
|
|
|
`:NvimTreeToggle` Open or close the tree. Takes an optional path argument.
|
|
|
|
`:NvimTreeFocus` Open the tree if it is closed, and then focus on the tree.
|
|
|
|
`:NvimTreeFindFile` Move the cursor in the tree for the current buffer, opening folders if needed.
|
|
|
|
`:NvimTreeCollapse` Collapses the nvim-tree recursively.
|
|
|
|
## Mappings
|
|
|
|
nvim-tree comes with number of mappings; for default mappings please see [:help nvim-tree-default-mappings](doc/nvim-tree-lua.txt), for way of configuring mappings see [:help nvim-tree-mappings](doc/nvim-tree-lua.txt)
|
|
|
|
`g?` toggles help, showing all the mappings and their actions.
|
|
|
|
## Tips & tricks
|
|
|
|
* You can add a directory by adding a `/` at the end of the paths, entering multiple directories `BASE/foo/bar/baz` will add directory foo, then bar and add a file baz to it.
|
|
* You can update window options for the tree by setting `require"nvim-tree.view".View.winopts.MY_OPTION = MY_OPTION_VALUE`
|
|
* `toggle` has a second parameter which allows to toggle without focusing the explorer (`require"nvim-tree".toggle(false, true)`).
|
|
* You can allow nvim-tree to behave like vinegar, see [:help nvim-tree-vinegar](doc/nvim-tree-lua.txt)
|
|
* If you `:set nosplitright`, the files will open on the left side of the tree, placing the tree window in the right side of the file you opened.
|
|
* You can automatically close the tab/vim when nvim-tree is the last window in the tab: <https://github.com/kyazdani42/nvim-tree.lua/discussions/1115>. WARNING: other plugins or automation may interfere with this.
|
|
|
|
## Troubleshooting
|
|
|
|
### Diagnostic Logging
|
|
|
|
You may enable diagnostic logging to `$XDG_CACHE_HOME/nvim/nvim-tree.log`. See [:help nvim-tree.log](doc/nvim-tree-lua.txt)
|
|
|
|
## Performance Issues
|
|
|
|
If you are experiencing performance issues with nvim-tree.lua, you can enable profiling in the logs. It is advisable to enable git logging at the same time, as that can be a source of performance problems.
|
|
|
|
```lua
|
|
log = {
|
|
enable = true,
|
|
truncate = true,
|
|
types = {
|
|
git = true,
|
|
profile = true,
|
|
},
|
|
},
|
|
```
|
|
|
|
Please attach `$XDG_CACHE_HOME/nvim/nvim-tree.log` if you raise an issue.
|
|
|
|
*Performance Tips:*
|
|
|
|
* If you are using fish as an editor shell (which might be fixed in the future), try set `shell=/bin/bash` in your vim config. Alternatively, you can [prevent fish from loading interactive configuration in a non-interactive shell](https://github.com/kyazdani42/nvim-tree.lua/issues/549#issuecomment-1127394585).
|
|
|
|
* Try manually running the git command (see the logs) in your shell e.g. `git --no-optional-locks status --porcelain=v1 --ignored=matching -u`.
|
|
|
|
* Huge git repositories may timeout after the default `git.timeout` of 400ms. Try increasing that in your setup if you see `[git] job timed out` in the logs.
|
|
|
|
* Try temporarily disabling git integration by setting `git.enable = false` in your setup.
|
|
|
|
## Contributing
|
|
|
|
PRs are always welcome. See [CONTRIBUTING.md](CONTRIBUTING.md)
|
|
|
|
### 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
|
|
|
|
|
|
|
|
|
|
|