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
5 changed files with 230 additions and 476 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,92 +1,157 @@
*nvim-tree.lua* A file explorer written in lua
Minimum version of neovim: 0.6.0
*nvim-tree* *nvim-tree.lua* A File Explorer For Neovim Written In Lua
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>
lua require 'nvim-tree'.toggle()
<
-- 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,
},
})
<
==============================================================================
COMMANDS *nvim-tree-commands*
3. COMMANDS *nvim-tree-commands*
|:NvimTreeOpen|
opens the tree. Takes an optional path argument.
opens the tree. Takes an optional path argument.
|:NvimTreeClose|
closes the tree
closes the tree
|:NvimTreeToggle|
open or close the tree. Takes an optional path argument.
open or close the tree. Takes an optional path argument.
|: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|
refresh the tree
refresh the tree
|: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
(if you opened a file with something else than the NvimTree, like `fzf` or
`:split`)
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
`:split`)
|:NvimTreeFindFileToggle|
close the tree or change the cursor in the tree for the current bufname,
similar to combination of |:NvimTreeToggle| and |:NvimTreeFindFile|. Takes an
optional path argument.
close the tree or change the cursor in the tree for the current bufname,
similar to combination of |:NvimTreeToggle| and |:NvimTreeFindFile|. Takes an
optional path argument.
|:NvimTreeClipboard|
Print clipboard content for both cut and copy
Print clipboard content for both cut and copy
|:NvimTreeResize|
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
adds or removes the given value to the current window width.
Example `:NvimTreeResize -20` removes the value 20 from the current width. And
`:NvimTreeResize +20` adds the value 20 to the current width.
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
adds or removes the given value to the current window width.
Example `:NvimTreeResize -20` removes the value 20 from the current width. And
`:NvimTreeResize +20` adds the value 20 to the current width.
|:NvimTreeCollapse|
Collapses the nvim-tree recursively.
Collapses the nvim-tree recursively.
|:NvimTreeCollapseKeepBuffers|
Collapses the nvim-tree recursively, but keep the directories open, which are
used in an open buffer.
Collapses the nvim-tree recursively, but keep the directories open, which are
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
function.
You must run setup() function to initialise nvim-tree.
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.
setup() function takes one optional argument: configuration table. If omitted
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
auto_reload_on_write = true,
@@ -465,14 +530,16 @@ Window / buffer setup.
Type: `boolean`, Default: `false`
*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`.
Type: `string | number`, Default: `30`
Type: `string | number | function`, Default: `30`
*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`
Type: `string | number`, Default: `30`
Type: `string | number | function`, Default: `30`
*nvim-tree.view.side*
Side of the tree, can be `"left"`, `"right"`, `"bottom"`, `"top"`.
@@ -782,9 +849,47 @@ Configuration for diagnostic logging.
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
@@ -806,6 +911,8 @@ The `list` option in `view.mappings.list` is a table of
{ key = "<2-RightMouse>", action = "" }, -- will remove default cd action
}
<
Mouse support defined in |KeyBindings|
DEFAULT MAPPINGS *nvim-tree-default-mappings*
`<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" }
} -- 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
`NvimTreeWindowPicker`, it is not advised to colorize the background of these
@@ -988,47 +1073,7 @@ NvimTreeLiveFilterPrefix
NvimTreeLiveFilterValue
==============================================================================
VINEGAR STYLE *nvim-tree-vinegar*
|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*
7. 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)
==============================================================================
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()*
on_nvim_tree_ready({handler})