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

docs: lighten up readme and rework docs (#1327)

Browse Source 
* 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>
This commit is contained in:
gegoune 2022-06-18 06:14:42 +02:00 committed by GitHub
parent bdb6d4a254
commit aba394896b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 230 additions and 476 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
.github/example.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 84 KiB

406
README.md
View File

@ -2,379 +2,117 @@
[![CI](https://github.com/kyazdani42/nvim-tree.lua/actions/workflows/ci.yml/badge.svg)](https://github.com/kyazdani42/nvim-tree.lua/actions/workflows/ci.yml) [![CI](https://github.com/kyazdani42/nvim-tree.lua/actions/workflows/ci.yml/badge.svg)](https://github.com/kyazdani42/nvim-tree.lua/actions/workflows/ci.yml)
## Notice <img align="left" width="124" height="332" src=".github/example.png?raw=true">
This plugin requires [neovim >=0.7.0](https://github.com/neovim/neovim/wiki/Installing-Neovim). Automatic updates
If you have issues since the recent setup migration, check out [this guide](https://github.com/kyazdani42/nvim-tree.lua/issues/674) File type icons
Git integration
Diagnostics integration: LSP and COC
(Live) filtering
Cut, copy, paste, rename, delete, create
Highly customisable
<br clear="left"/>
## Install ## 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): Install with [vim-plug](https://github.com/junegunn/vim-plug):
```vim ```vim
" requires Plug 'kyazdani42/nvim-web-devicons' " optional, for file icons
Plug 'kyazdani42/nvim-web-devicons' " for file icons
Plug 'kyazdani42/nvim-tree.lua' Plug 'kyazdani42/nvim-tree.lua'
``` ```
Install with [packer](https://github.com/wbthomason/packer.nvim): or with [packer](https://github.com/wbthomason/packer.nvim):
```lua ```lua
use { use {
'kyazdani42/nvim-tree.lua', 'kyazdani42/nvim-tree.lua',
requires = { requires = {
'kyazdani42/nvim-web-devicons', -- optional, for file icon 'kyazdani42/nvim-web-devicons', -- optional, for file icons
}, },
tag = 'nightly' -- optional, updated every week. (see issue #1193) tag = 'nightly' -- optional, updated every week. (see issue #1193)
} }
``` ```
## Setup ## Setup
Setup should be run in a lua file or in a lua heredoc (`:help lua-heredoc`) if using in a vim file. 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.
Legacy `g:` options have been migrated to the setup function. See [this issue](https://github.com/kyazdani42/nvim-tree.lua/issues/674) for information on migrating your configuration. Setup may only be run once; subsequent calls will result in a warning.
Setup may only be run once; subsequent calls will result in a warning. Do not invoke from, say, a packer config function and then call it again later.
```vim
" vimrc
nnoremap <C-n> :NvimTreeToggle<CR>
nnoremap <leader>r :NvimTreeRefresh<CR>
nnoremap <leader>n :NvimTreeFindFile<CR>
" More available functions:
" NvimTreeOpen
" NvimTreeClose
" NvimTreeFocus
" NvimTreeFindFileToggle
" NvimTreeResize
" NvimTreeCollapse
" NvimTreeCollapseKeepBuffers
set termguicolors " this variable must be enabled for colors to be applied properly
" a list of groups can be found at `:help nvim_tree_highlight`
highlight NvimTreeFolderIcon guibg=blue
```
```lua ```lua
-- init.lua -- examples for your init.lua
-- empty setup using defaults: add your own options -- empty setup using defaults
require'nvim-tree'.setup { require("nvim-tree").setup()
}
-- OR -- OR setup with some options
require("nvim-tree").setup({
-- setup with all defaults sort_by = "case_sensitive",
-- each of these are documented in `:help nvim-tree.OPTION_NAME`
-- nested options are documented by accessing them with `.` (eg: `:help nvim-tree.view.mappings.list`).
require'nvim-tree'.setup { -- BEGIN_DEFAULT_OPTS
auto_reload_on_write = true,
create_in_closed_folder = false,
disable_netrw = false,
hijack_cursor = false,
hijack_netrw = true,
hijack_unnamed_buffer_when_opening = false,
ignore_buffer_on_setup = false,
open_on_setup = false,
open_on_setup_file = false,
open_on_tab = false,
sort_by = "name",
update_cwd = false,
reload_on_bufenter = false,
respect_buf_cwd = false,
view = { view = {
adaptive_size = false, adaptive_size = true,
centralize_selection = false,
width = 30,
height = 30,
hide_root_folder = false,
side = "left",
preserve_window_proportions = false,
number = false,
relativenumber = false,
signcolumn = "yes",
mappings = { mappings = {
custom_only = false,
list = { list = {
-- user mappings go here { key = "u", action = "dir_up" },
}, },
}, },
}, },
renderer = { renderer = {
add_trailing = false, group_empty = true,
group_empty = false,
highlight_git = false,
full_name = false,
highlight_opened_files = "none",
root_folder_modifier = ":~",
indent_markers = {
enable = false,
icons = {
corner = "└ ",
edge = "│ ",
item = "│ ",
none = " ",
},
},
icons = {
webdev_colors = true,
git_placement = "before",
padding = " ",
symlink_arrow = " ➛ ",
show = {
file = true,
folder = true,
folder_arrow = true,
git = true,
},
glyphs = {
default = "",
symlink = "",
folder = {
arrow_closed = "",
arrow_open = "",
default = "",
open = "",
empty = "",
empty_open = "",
symlink = "",
symlink_open = "",
},
git = {
unstaged = "✗",
staged = "✓",
unmerged = "",
renamed = "➜",
untracked = "★",
deleted = "",
ignored = "◌",
},
},
},
special_files = { "Cargo.toml", "Makefile", "README.md", "readme.md" },
},
hijack_directories = {
enable = true,
auto_open = true,
},
update_focused_file = {
enable = false,
update_cwd = false,
ignore_list = {},
},
ignore_ft_on_setup = {},
system_open = {
cmd = "",
args = {},
},
diagnostics = {
enable = false,
show_on_dirs = false,
icons = {
hint = "",
info = "",
warning = "",
error = "",
},
}, },
filters = { filters = {
dotfiles = false, dotfiles = true,
custom = {},
exclude = {},
}, },
filesystem_watchers = { })
enable = false,
interval = 100,
},
git = {
enable = true,
ignore = true,
timeout = 400,
},
actions = {
use_system_clipboard = true,
change_dir = {
enable = true,
global = false,
restrict_above_cwd = false,
},
expand_all = {
max_folder_discovery = 300,
},
open_file = {
quit_on_open = false,
resize_window = true,
window_picker = {
enable = true,
chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
exclude = {
filetype = { "notify", "packer", "qf", "diff", "fugitive", "fugitiveblame" },
buftype = { "nofile", "terminal", "help" },
},
},
},
remove_file = {
close_window = true,
},
},
trash = {
cmd = "gio trash",
require_confirm = true,
},
live_filter = {
prefix = "[FILTER]: ",
always_show_folders = true,
},
log = {
enable = false,
truncate = false,
types = {
all = false,
config = false,
copy_paste = false,
diagnostics = false,
git = false,
profile = false,
watcher = false,
},
},
} -- END_DEFAULT_OPTS
``` ```
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 ## Mappings
The `list` option in `view.mappings.list` is a table of 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)
```lua
-- key can be either a string or a table of string (lhs)
-- action is the name of the action, set to `""` to remove default action
-- action_cb is the function that will be called, it receives the node as a parameter. Optional for default actions
-- mode is normal by default
local tree_cb = require'nvim-tree.config'.nvim_tree_callback `g?` toggles help, showing all the mappings and their actions.
local function print_node_path(node) { ## Tips & tricks
print(node.absolute_path)
}
local list = { * 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.
{ key = {"<CR>", "o" }, action = "edit", mode = "n"}, * You can update window options for the tree by setting `require"nvim-tree.view".View.winopts.MY_OPTION = MY_OPTION_VALUE`
{ key = "p", action = "print_path", action_cb = print_node_path }, * `toggle` has a second parameter which allows to toggle without focusing the explorer (`require"nvim-tree".toggle(false, true)`).
{ key = "s", cb = tree_cb("vsplit") }, --tree_cb and the cb property are deprecated * You can allow nvim-tree to behave like vinegar, see [:help nvim-tree-vinegar](doc/nvim-tree-lua.txt)
{ key = "<2-RightMouse>", action = "" }, -- will remove default cd action * 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.
```
### Defaults ## Troubleshooting
<!-- BEGIN_DEFAULT_MAPPINGS_TABLE --> ### Diagnostic Logging
| Default Keys | Action | Description |
| - | - | - |
| \<CR> <br /> o <br /> \<2-LeftMouse> | edit | open a file or folder; root will cd to the above directory |
| \<C-e> | edit_in_place | edit the file in place, effectively replacing the tree explorer |
| O | edit_no_picker | same as (edit) with no window picker |
| \<C-]> <br /> \<2-RightMouse> | cd | cd in the directory under the cursor |
| \<C-v> | vsplit | open the file in a vertical split |
| \<C-x> | split | open the file in a horizontal split |
| \<C-t> | tabnew | open the file in a new tab |
| \< | prev_sibling | navigate to the previous sibling of current file/directory |
| > | next_sibling | navigate to the next sibling of current file/directory |
| P | parent_node | move cursor to the parent directory |
| \<BS> | close_node | close current opened directory or parent |
| \<Tab> | preview | open the file as a preview (keeps the cursor in the tree) |
| K | first_sibling | navigate to the first sibling of current file/directory |
| J | last_sibling | navigate to the last sibling of current file/directory |
| I | toggle_git_ignored | toggle visibility of files/folders hidden via `git.ignore` option |
| H | toggle_dotfiles | toggle visibility of dotfiles via `filters.dotfiles` option |
| U | toggle_custom | toggle visibility of files/folders hidden via `filters.custom` option |
| R | refresh | refresh the tree |
| a | create | add a file; leaving a trailing `/` will add a directory |
| d | remove | delete a file (will prompt for confirmation) |
| D | trash | trash a file via `trash` option |
| r | rename | rename a file |
| \<C-r> | full_rename | rename a file and omit the filename on input |
| x | cut | add/remove file/directory to cut clipboard |
| c | copy | add/remove file/directory to copy clipboard |
| p | paste | paste from clipboard; cut clipboard has precedence over copy; will prompt for confirmation |
| y | copy_name | copy name to system clipboard |
| Y | copy_path | copy relative path to system clipboard |
| gy | copy_absolute_path | copy absolute path to system clipboard |
| [c | prev_git_item | go to next git item |
| ]c | next_git_item | go to prev git item |
| - | dir_up | navigate up to the parent directory of the current file/directory |
| s | system_open | open a file with default system application or a folder with default file manager, using `system_open` option |
| f | live_filter | live filter nodes dynamically based on regex matching. |
| F | clear_live_filter | clear live filter |
| q | close | close tree window |
| W | collapse_all | collapse the whole tree |
| E | expand_all | expand the whole tree, stopping after expanding `actions.expand_all.max_folder_discovery` folders; this might hang neovim for a while if running on a big folder |
| S | search_node | prompt the user to enter a path and then expands the tree to match the path |
| . | run_file_command | enter vim command mode with the file the cursor is on |
| \<C-k> | toggle_file_info | toggle a popup with file infos about the file under the cursor |
| g? | toggle_help | toggle help |
<!-- END_DEFAULT_MAPPINGS_TABLE -->
```lua You may enable diagnostic logging to `$XDG_CACHE_HOME/nvim/nvim-tree.log`. See [:help nvim-tree.log](doc/nvim-tree-lua.txt)
view.mappings.list = { -- BEGIN_DEFAULT_MAPPINGS
{ key = { "<CR>", "o", "<2-LeftMouse>" }, action = "edit" }
{ key = "<C-e>", action = "edit_in_place" }
{ key = "O", action = "edit_no_picker" }
{ key = { "<C-]>", "<2-RightMouse>" }, action = "cd" }
{ key = "<C-v>", action = "vsplit" }
{ key = "<C-x>", action = "split" }
{ key = "<C-t>", action = "tabnew" }
{ key = "<", action = "prev_sibling" }
{ key = ">", action = "next_sibling" }
{ key = "P", action = "parent_node" }
{ key = "<BS>", action = "close_node" }
{ key = "<Tab>", action = "preview" }
{ key = "K", action = "first_sibling" }
{ key = "J", action = "last_sibling" }
{ key = "I", action = "toggle_git_ignored" }
{ key = "H", action = "toggle_dotfiles" }
{ key = "U", action = "toggle_custom" }
{ key = "R", action = "refresh" }
{ key = "a", action = "create" }
{ key = "d", action = "remove" }
{ key = "D", action = "trash" }
{ key = "r", action = "rename" }
{ key = "<C-r>", action = "full_rename" }
{ key = "x", action = "cut" }
{ key = "c", action = "copy" }
{ key = "p", action = "paste" }
{ key = "y", action = "copy_name" }
{ key = "Y", action = "copy_path" }
{ key = "gy", action = "copy_absolute_path" }
{ key = "[c", action = "prev_git_item" }
{ key = "]c", action = "next_git_item" }
{ key = "-", action = "dir_up" }
{ key = "s", action = "system_open" }
{ key = "f", action = "live_filter" }
{ key = "F", action = "clear_live_filter" }
{ key = "q", action = "close" }
{ key = "W", action = "collapse_all" }
{ key = "E", action = "expand_all" }
{ key = "S", action = "search_node" }
{ key = ".", action = "run_file_command" }
{ key = "<C-k>", action = "toggle_file_info" }
{ key = "g?", action = "toggle_help" }
} -- END_DEFAULT_MAPPINGS
```
## Tips & reminders
1. 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.
2. You can update window options for the tree by setting `require"nvim-tree.view".View.winopts.MY_OPTION = MY_OPTION_VALUE`
3. `toggle` has a second parameter which allows to toggle without focusing the explorer (`require"nvim-tree".toggle(false, true)`).
4. You can allow nvim-tree to behave like vinegar (see `:help nvim-tree-vinegar`).
5. 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.
6. 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.
## Diagnostic Logging
You may enable diagnostic logging to `$XDG_CACHE_HOME/nvim/nvim-tree.log`. See `:help nvim-tree.log`.
## Performance Issues ## Performance Issues
@ -403,7 +141,11 @@ Please attach `$XDG_CACHE_HOME/nvim/nvim-tree.log` if you raise an issue.
* Try temporarily disabling git integration by setting `git.enable = false` in your setup. * Try temporarily disabling git integration by setting `git.enable = false` in your setup.
## Help Wanted ## Contributing
PRs are always welcome. See [CONTRIBUTING.md](CONTRIBUTING.md)
### Help Wanted
Developers with the following environments: Developers with the following environments:
@ -415,9 +157,7 @@ Developers with the following environments:
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. 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.
## Contributing Let us know you're interested by commenting on issues and raising PRs.
PRs are always welcome. See [CONTRIBUTING.md](CONTRIBUTING.md)
## Screenshots ## Screenshots

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

@ -1,92 +1,157 @@
*nvim-tree.lua* A file explorer written in lua *nvim-tree* *nvim-tree.lua* A File Explorer For Neovim Written In Lua
Minimum version of neovim: 0.6.0
Author: Yazdani Kiyan <yazdani.kiyan@protonmail.com> Author: Yazdani Kiyan <yazdani.kiyan@protonmail.com>
============================================================================== ==============================================================================
INTRODUCTION *nvim-tree-introduction* CONTENTS *nvim-tree*
This file explorer requires `neovim >= 0.6.0` 1. Introduction nvim-tree-introduction
2. Quickstart nvim-tree-quickstart
3. Commands nvim-tree-commands
4. Setup/Configuration nvim-tree-setup
4.1 Vinegar Style nvim-tree-vinegar
5. Mappings nvim-tree-mappings
6. Highlight Groups nvim-tree-highlight
7. Events nvim-tree-events
7.1 Available Events nvim-tree.events
============================================================================== ==============================================================================
QUICK START *nvim-tree-quickstart* 1. INTRODUCTION *nvim-tree-introduction*
open the tree with :NvimTreeToggle Features
- Automatic updates
- File type icons
- Git integration
- Diagnostics integration: LSP and COC
- (Live) filtering
- Cut, copy, paste, rename, delete, create
- Highly customisable
File Icons
See https://github.com/kyazdani42/nvim-web-devicons
Requires a patched font.
 should look like an open folder.
Syntax highlighting uses g:terminal_color_ from colorschemes, fallbacks to
ugly colors otherwise.
Git Integration
Icon indicates when a file is:
- ✗ unstaged or folder is dirty
- ✓ staged
- ★ new file
- ✓ ✗ partially staged
- ✓ ★ new file staged
- ✓ ★ ✗ new file staged and has unstaged modifications
- ═ merging
- ➜ renamed
Requirements
This file explorer requires `neovim >= 0.7.0`
==============================================================================
2. QUICK START *nvim-tree-quickstart*
Setup should be run in a lua file or in a |lua-heredoc| if using in a vim file.
Setup may only be run once; subsequent calls will result in a warning.
> >
nnoremap <C-n> :NvimTreeToggle<CR> -- examples for your init.lua
lua require 'nvim-tree'.toggle()
<
-- 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,
},
})
<
============================================================================== ==============================================================================
COMMANDS *nvim-tree-commands* 3. COMMANDS *nvim-tree-commands*
|:NvimTreeOpen| |:NvimTreeOpen|
opens the tree. Takes an optional path argument. opens the tree. Takes an optional path argument.
|:NvimTreeClose| |:NvimTreeClose|
closes the tree closes the tree
|:NvimTreeToggle| |:NvimTreeToggle|
open or close the tree. Takes an optional path argument. open or close the tree. Takes an optional path argument.
|:NvimTreeFocus| |:NvimTreeFocus|
open the tree if it is closed, and then focus on the tree open the tree if it is closed, and then focus on the tree
|:NvimTreeRefresh| |:NvimTreeRefresh|
refresh the tree refresh the tree
|:NvimTreeFindFile| |:NvimTreeFindFile|
The command will change the cursor in the tree for the current bufname. The command will change the cursor in the tree for the current bufname.
It will also open the leafs of the tree leading to the file in the buffer It will also open the leafs of the tree leading to the file in the buffer
(if you opened a file with something else than the NvimTree, like `fzf` or (if you opened a file with something else than the NvimTree, like `fzf` or
`:split`) `:split`)
|:NvimTreeFindFileToggle| |:NvimTreeFindFileToggle|
close the tree or change the cursor in the tree for the current bufname, close the tree or change the cursor in the tree for the current bufname,
similar to combination of |:NvimTreeToggle| and |:NvimTreeFindFile|. Takes an similar to combination of |:NvimTreeToggle| and |:NvimTreeFindFile|. Takes an
optional path argument. optional path argument.
|:NvimTreeClipboard| |:NvimTreeClipboard|
Print clipboard content for both cut and copy Print clipboard content for both cut and copy
|:NvimTreeResize| |:NvimTreeResize|
Resize the NvimTree window to the given size. Example: `:NvimTreeResize 50` Resize the NvimTree window to the given size. Example: `:NvimTreeResize 50`
resizes the window to the width of 50. If the size starts with "+" or "-" it resizes the window to the width of 50. If the size starts with "+" or "-" it
adds or removes the given value to the current window width. adds or removes the given value to the current window width.
Example `:NvimTreeResize -20` removes the value 20 from the current width. And Example `:NvimTreeResize -20` removes the value 20 from the current width. And
`:NvimTreeResize +20` adds the value 20 to the current width. `:NvimTreeResize +20` adds the value 20 to the current width.
|:NvimTreeCollapse| |:NvimTreeCollapse|
Collapses the nvim-tree recursively. Collapses the nvim-tree recursively.
|:NvimTreeCollapseKeepBuffers| |:NvimTreeCollapseKeepBuffers|
Collapses the nvim-tree recursively, but keep the directories open, which are Collapses the nvim-tree recursively, but keep the directories open, which are
used in an open buffer. used in an open buffer.
============================================================================== ==============================================================================
SETUP *nvim-tree.setup* 4. SETUP *nvim-tree-setup*
To configure the tree (and make it runnable), you should call the setup You must run setup() function to initialise nvim-tree.
function.
Setup may only be run once; subsequent calls will result in a warning. Do not setup() function takes one optional argument: configuration table. If omitted
invoke from, say, a packer config function and then call it again later. nvim-tree will be initialised with default configuration.
Values may be functions. Warning: this may result in unexpected behaviour. Setup may only be run once; subsequent calls will result in a warning.
> >
require("nvim-tree").setup { -- BEGIN_DEFAULT_OPTS require("nvim-tree").setup { -- BEGIN_DEFAULT_OPTS
auto_reload_on_write = true, auto_reload_on_write = true,
@ -465,14 +530,16 @@ Window / buffer setup.
Type: `boolean`, Default: `false` Type: `boolean`, Default: `false`
*nvim-tree.view.width* *nvim-tree.view.width*
Width of the window, can be either a `%` string or a number representing columns. Width of the window, can be a `%` string, a number representing columns or
a function.
Only works with `side` is `left` or `right`. Only works with `side` is `left` or `right`.
Type: `string | number`, Default: `30` Type: `string | number | function`, Default: `30`
*nvim-tree.view.height* *nvim-tree.view.height*
Height of the window, can be either a `%` string or a number representing rows. Height of the window, can be `%` string or a number representing rows or a
function.
Only works with `side` is `top` or `bottom` Only works with `side` is `top` or `bottom`
Type: `string | number`, Default: `30` Type: `string | number | function`, Default: `30`
*nvim-tree.view.side* *nvim-tree.view.side*
Side of the tree, can be `"left"`, `"right"`, `"bottom"`, `"top"`. Side of the tree, can be `"left"`, `"right"`, `"bottom"`, `"top"`.
@ -782,9 +849,47 @@ Configuration for diagnostic logging.
Type: `boolean`, Default: `false` Type: `boolean`, Default: `false`
============================================================================== ==============================================================================
INFORMATIONS *nvim-tree-info* 4.1 VINEGAR STYLE *nvim-tree-vinegar*
MAPPINGS *nvim-tree-mappings* |nvim_tree_vinegar| *nvim_tree_vinegar*
nvim-tree can behave like vinegar. To allow this, you will need to configure
it in a specific way:
- Use `require"nvim-tree".open_replacing_current_buffer()` instead of the
default open command.
You can easily implement a toggle using this too:
>
local function toggle_replace()
local view = require"nvim-tree.view"
if view.is_visible() then
view.close()
else
require"nvim-tree".open_replacing_current_buffer()
end
end
<
- Use the `edit_in_place` action to edit files. It's bound to `<C-e>` by
default, vinegar uses `<CR>`. You can override this with:
>
require"nvim-tree".setup {
view = {
mappings = {
list = {
{ key = "<CR>", action = "edit_in_place" }
}
}
}
}
<
Going up a dir is bound to `-` by default in nvim-tree which is identical to
vinegar, no change is needed here.
You'll also need to set |nvim-tree.hijack_netrw| to `true` during setup.
A good functionnality to enable is |nvim-tree.hijack_directories|.
==============================================================================
5. MAPPINGS *nvim-tree-mappings*
The `list` option in `view.mappings.list` is a table of The `list` option in `view.mappings.list` is a table of
@ -806,6 +911,8 @@ The `list` option in `view.mappings.list` is a table of
{ key = "<2-RightMouse>", action = "" }, -- will remove default cd action { key = "<2-RightMouse>", action = "" }, -- will remove default cd action
} }
< <
Mouse support defined in |KeyBindings|
DEFAULT MAPPINGS *nvim-tree-default-mappings* DEFAULT MAPPINGS *nvim-tree-default-mappings*
`<CR>` edit open a file or folder; root will cd to the above directory `<CR>` edit open a file or folder; root will cd to the above directory
@ -900,30 +1007,8 @@ DEFAULT MAPPINGS *nvim-tree-default-mappings
{ key = "g?", action = "toggle_help" } { key = "g?", action = "toggle_help" }
} -- END_DEFAULT_MAPPINGS } -- END_DEFAULT_MAPPINGS
< <
FEATURES *nvim-tree-features*
File icons with vim-devicons.
Uses other type of icons so a good font support is recommended.
If the tree renders weird glyphs, install the correct fonts.
Syntax highlighting uses g:terminal_color_ from colorschemes, fallbacks to
ugly colors otherwise.
Git integration tells when a file is:
- ✗ unstaged or folder is dirty
- ✓ staged
- ★ new file
- ✓ ✗ partially staged
- ✓ ★ new file staged
- ✓ ★ ✗ new file staged and has unstaged modifications
- ═ merging
- ➜ renamed
Mouse support defined in |KeyBindings|
============================================================================== ==============================================================================
HIGHLIGHT GROUPS *nvim-tree-highlight* 6. HIGHLIGHT GROUPS *nvim-tree-highlight*
All the following highlight groups can be configured by hand. Aside from All the following highlight groups can be configured by hand. Aside from
`NvimTreeWindowPicker`, it is not advised to colorize the background of these `NvimTreeWindowPicker`, it is not advised to colorize the background of these
@ -988,47 +1073,7 @@ NvimTreeLiveFilterPrefix
NvimTreeLiveFilterValue NvimTreeLiveFilterValue
============================================================================== ==============================================================================
VINEGAR STYLE *nvim-tree-vinegar* 7. EVENTS *nvim-tree-events*
|nvim_tree_vinegar| *nvim_tree_vinegar*
nvim-tree can behave like vinegar. To allow this, you will need to configure
it in a specific way:
- Use `require"nvim-tree".open_replacing_current_buffer()` instead of the
default open command.
You can easily implement a toggle using this too:
>
local function toggle_replace()
local view = require"nvim-tree.view"
if view.is_visible() then
view.close()
else
require"nvim-tree".open_replacing_current_buffer()
end
end
<
- Use the `edit_in_place` action to edit files. It's bound to `<C-e>` by
default, vinegar uses `<CR>`. You can override this with:
>
require"nvim-tree".setup {
view = {
mappings = {
list = {
{ key = "<CR>", action = "edit_in_place" }
}
}
}
}
<
Going up a dir is bound to `-` by default in nvim-tree which is identical to
vinegar, no change is needed here.
You'll also need to set |nvim-tree.hijack_netrw| to `true` during setup.
A good functionnality to enable is |nvim-tree.hijack_directories|.
==============================================================================
EVENTS *nvim-tree-events*
|nvim_tree_events| |nvim_tree_events|
@ -1056,7 +1101,7 @@ For example, registering a handler for when a node is renamed is done like this:
end) end)
============================================================================== ==============================================================================
Lua module: nvim-tree.events *nvim-tree.events* 7.1 Lua module: nvim-tree.events *nvim-tree.events*
*nvim-tree.events.on_nvim_tree_ready()* *nvim-tree.events.on_nvim_tree_ready()*
on_nvim_tree_ready({handler}) on_nvim_tree_ready({handler})

20
scripts/generate_default_mappings.lua
View File

@ -82,23 +82,3 @@ for _, m in pairs(outs_lua) do
io.write(string.format(fmt, m.key, m.action)) io.write(string.format(fmt, m.key, m.action))
end end
io.close(file) io.close(file)
-- md
file = io.open("/tmp/DEFAULT_MAPPINGS.md", "w")
io.output(file)
io.write "| Default Keys | Action | Description |\n"
io.write "| - | - | - |\n"
for _, m in pairs(M.mappings) do
local keys = ""
if type(m.key) == "table" then
local first = true
for _, sub_key in pairs(m.key) do
keys = keys .. (first and "" or " <br /> ") .. sub_key:gsub("<", "\\<")
first = false
end
else
keys = m.key:gsub("<", "\\<")
end
io.write(string.format("| %s | %s | %s |\n", keys, m.action, m.desc:gsub("|", "`")))
end
io.close(file)

17
scripts/update-default-opts.sh
View File

@ -1,7 +1,7 @@
#!/bin/sh #!/bin/sh
# run after changing nvim-tree.lua DEFAULT_OPTS or nvim-tree/actions/init.lua M.mappings # run after changing nvim-tree.lua DEFAULT_OPTS or nvim-tree/actions/init.lua M.mappings
# scrapes and updates README.md, nvim-tree-lua.txt # scrapes and updates nvim-tree-lua.txt
# run from repositry root: scripts/update-default-opts.sh # run from repositry root: scripts/update-default-opts.sh
@ -14,13 +14,9 @@ sed -n -e "/${begin}/,/${end}/{ /${begin}/d; /${end}/d; p; }" lua/nvim-tree.lua
# indent some more # indent some more
sed -e "s/^ / /" /tmp/DEFAULT_OPTS.2.lua > /tmp/DEFAULT_OPTS.6.lua sed -e "s/^ / /" /tmp/DEFAULT_OPTS.2.lua > /tmp/DEFAULT_OPTS.6.lua
# README.md indented at 2
sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/DEFAULT_OPTS.2.lua
}; /${end}/p; d }" README.md
# help, indented at 6 # help, indented at 6
sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/DEFAULT_OPTS.6.lua sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/DEFAULT_OPTS.6.lua
}; /${end}/p; d }" doc/nvim-tree-lua.txt }; /${end}/p; d; }" doc/nvim-tree-lua.txt
begin="BEGIN_DEFAULT_MAPPINGS" begin="BEGIN_DEFAULT_MAPPINGS"
@ -28,17 +24,10 @@ end="END_DEFAULT_MAPPINGS"
# generate various DEFAULT_MAPPINGS # generate various DEFAULT_MAPPINGS
sed -n -e "/${begin}/,/${end}/{ /${begin}/d; /${end}/d; p; }" lua/nvim-tree/actions/init.lua > /tmp/DEFAULT_MAPPINGS.M.lua sed -n -e "/${begin}/,/${end}/{ /${begin}/d; /${end}/d; p; }" lua/nvim-tree/actions/init.lua > /tmp/DEFAULT_MAPPINGS.M.lua
lua <(cat /tmp/DEFAULT_MAPPINGS.M.lua scripts/generate_default_mappings.lua) cat /tmp/DEFAULT_MAPPINGS.M.lua scripts/generate_default_mappings.lua | lua
# README.md
sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/DEFAULT_MAPPINGS.lua
}; /${end}/p; d }" README.md
sed -i -e "/BEGIN_DEFAULT_MAPPINGS_TABLE/,/END_DEFAULT_MAPPINGS_TABLE/{ /BEGIN_DEFAULT_MAPPINGS_TABLE/{p; r /tmp/DEFAULT_MAPPINGS.md
}; /END_DEFAULT_MAPPINGS_TABLE/p; d }" README.md
# help # help
sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/DEFAULT_MAPPINGS.lua sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/DEFAULT_MAPPINGS.lua
}; /${end}/p; d }" doc/nvim-tree-lua.txt }; /${end}/p; d }" doc/nvim-tree-lua.txt
sed -i -e "/^DEFAULT MAPPINGS/,/^>$/{ /^DEFAULT MAPPINGS/{p; r /tmp/DEFAULT_MAPPINGS.help sed -i -e "/^DEFAULT MAPPINGS/,/^>$/{ /^DEFAULT MAPPINGS/{p; r /tmp/DEFAULT_MAPPINGS.help
}; /^>$/p; d }" doc/nvim-tree-lua.txt }; /^>$/p; d }" doc/nvim-tree-lua.txt