Refresh generated nvim config
This commit is contained in:
856
config/neovim/store/lazy-plugins/neo-tree.nvim/README.md
Normal file
856
config/neovim/store/lazy-plugins/neo-tree.nvim/README.md
Normal file
@ -0,0 +1,856 @@
|
||||
# Neo-tree.nvim
|
||||
|
||||
Neo-tree is a Neovim plugin to browse the file system and other tree like
|
||||
structures in whatever style suits you, including sidebars, floating windows,
|
||||
netrw split style, or all of them at once!
|
||||
|
||||
### Neo-tree filesystem as Sidebar:
|
||||
|
||||
This screenshot shows Neo-tree opened in the traditional sidebar layout:
|
||||
|
||||
|
||||
|
||||
### Neo-tree filesystem Netrw Style
|
||||
|
||||
The below screenshot shows Neo-tree opened "netrw style" (`:Neotree position=current`). When opened in this way,
|
||||
there is more room so the extra detail columns can be shown. This screenshot also shows how the contents can be
|
||||
sorted on any column. In this example, we are sorted on "Size" descending:
|
||||
|
||||
|
||||
|
||||
### Breaking Changes BAD :bomb: :imp:
|
||||
|
||||
The biggest and most important feature of Neo-tree is that we will never
|
||||
knowingly push a breaking change and interrupt your day. Bugs happen, but
|
||||
breaking changes can always be avoided. When breaking changes are needed, there
|
||||
will be a new branch that you can opt into, when it is a good time for you.
|
||||
|
||||
See [What is a Breaking Change?](#what-is-a-breaking-change) for details.
|
||||
|
||||
See [Changelog 3.0](https://github.com/nvim-neo-tree/neo-tree.nvim/wiki/Changelog#30)
|
||||
for breaking changes and deprecations in 3.0.
|
||||
|
||||
|
||||
### User Experience GOOD :slightly_smiling_face: :thumbsup:
|
||||
|
||||
Aside from being polite about breaking changes, Neo-tree is also focused on the
|
||||
little details of user experience. Everything should work exactly as you would
|
||||
expect a sidebar to work without all of the glitchy behavior that is normally
|
||||
accepted in (neo)vim sidebars. I can't stand glitchy behavior, and neither
|
||||
should you!
|
||||
|
||||
- Neo-tree won't let other buffers take over its window.
|
||||
- Neo-tree won't leave its window scrolled to the last line when there is
|
||||
plenty of room to display the whole tree.
|
||||
- Neo-tree does not need to be manually refreshed (set `use_libuv_file_watcher=true`)
|
||||
- Neo-tree can intelligently follow the current file (set `follow_current_file.enabled=true`)
|
||||
- Neo-tree is thoughtful about maintaining or setting focus on the right node
|
||||
- Neo-tree windows in different tabs are completely separate
|
||||
- `respect_gitignore` actually works!
|
||||
|
||||
Neo-tree is smooth, efficient, stable, and pays attention to the little details.
|
||||
If you find anything janky, wanky, broken, or unintuitive, please open an issue
|
||||
so we can fix it.
|
||||
|
||||
|
||||
## Minimal Quickstart
|
||||
|
||||
#### Minimal Example for Lazy:
|
||||
```lua
|
||||
{
|
||||
"nvim-neo-tree/neo-tree.nvim",
|
||||
branch = "v3.x",
|
||||
dependencies = {
|
||||
"nvim-lua/plenary.nvim",
|
||||
"nvim-tree/nvim-web-devicons", -- not strictly required, but recommended
|
||||
"MunifTanjim/nui.nvim",
|
||||
-- "3rd/image.nvim", -- Optional image support in preview window: See `# Preview Mode` for more information
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Minimal Example for Packer:
|
||||
```lua
|
||||
use {
|
||||
"nvim-neo-tree/neo-tree.nvim",
|
||||
branch = "v3.x",
|
||||
requires = {
|
||||
"nvim-lua/plenary.nvim",
|
||||
"nvim-tree/nvim-web-devicons", -- not strictly required, but recommended
|
||||
"MunifTanjim/nui.nvim",
|
||||
-- "3rd/image.nvim", -- Optional image support in preview window: See `# Preview Mode` for more information
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
After installing, run:
|
||||
```
|
||||
:Neotree
|
||||
```
|
||||
|
||||
Press `?` in the Neo-tree window to view the list of mappings.
|
||||
|
||||
|
||||
## Quickstart
|
||||
|
||||
#### Longer Example for Packer:
|
||||
|
||||
```lua
|
||||
use {
|
||||
"nvim-neo-tree/neo-tree.nvim",
|
||||
branch = "v3.x",
|
||||
requires = {
|
||||
"nvim-lua/plenary.nvim",
|
||||
"nvim-tree/nvim-web-devicons", -- not strictly required, but recommended
|
||||
"MunifTanjim/nui.nvim",
|
||||
-- "3rd/image.nvim", -- Optional image support in preview window: See `# Preview Mode` for more information
|
||||
{
|
||||
's1n7ax/nvim-window-picker',
|
||||
version = '2.*',
|
||||
config = function()
|
||||
require 'window-picker'.setup({
|
||||
filter_rules = {
|
||||
include_current_win = false,
|
||||
autoselect_one = true,
|
||||
-- filter using buffer options
|
||||
bo = {
|
||||
-- if the file type is one of following, the window will be ignored
|
||||
filetype = { 'neo-tree', "neo-tree-popup", "notify" },
|
||||
-- if the buffer type is one of following, the window will be ignored
|
||||
buftype = { 'terminal', "quickfix" },
|
||||
},
|
||||
},
|
||||
})
|
||||
end,
|
||||
},
|
||||
},
|
||||
config = function ()
|
||||
-- If you want icons for diagnostic errors, you'll need to define them somewhere:
|
||||
vim.fn.sign_define("DiagnosticSignError",
|
||||
{text = " ", texthl = "DiagnosticSignError"})
|
||||
vim.fn.sign_define("DiagnosticSignWarn",
|
||||
{text = " ", texthl = "DiagnosticSignWarn"})
|
||||
vim.fn.sign_define("DiagnosticSignInfo",
|
||||
{text = " ", texthl = "DiagnosticSignInfo"})
|
||||
vim.fn.sign_define("DiagnosticSignHint",
|
||||
{text = "", texthl = "DiagnosticSignHint"})
|
||||
|
||||
require("neo-tree").setup({
|
||||
close_if_last_window = false, -- Close Neo-tree if it is the last window left in the tab
|
||||
popup_border_style = "rounded",
|
||||
enable_git_status = true,
|
||||
enable_diagnostics = true,
|
||||
open_files_do_not_replace_types = { "terminal", "trouble", "qf" }, -- when opening files, do not use windows containing these filetypes or buftypes
|
||||
sort_case_insensitive = false, -- used when sorting files and directories in the tree
|
||||
sort_function = nil , -- use a custom function for sorting files and directories in the tree
|
||||
-- sort_function = function (a,b)
|
||||
-- if a.type == b.type then
|
||||
-- return a.path > b.path
|
||||
-- else
|
||||
-- return a.type > b.type
|
||||
-- end
|
||||
-- end , -- this sorts files and directories descendantly
|
||||
default_component_configs = {
|
||||
container = {
|
||||
enable_character_fade = true
|
||||
},
|
||||
indent = {
|
||||
indent_size = 2,
|
||||
padding = 1, -- extra padding on left hand side
|
||||
-- indent guides
|
||||
with_markers = true,
|
||||
indent_marker = "│",
|
||||
last_indent_marker = "└",
|
||||
highlight = "NeoTreeIndentMarker",
|
||||
-- expander config, needed for nesting files
|
||||
with_expanders = nil, -- if nil and file nesting is enabled, will enable expanders
|
||||
expander_collapsed = "",
|
||||
expander_expanded = "",
|
||||
expander_highlight = "NeoTreeExpander",
|
||||
},
|
||||
icon = {
|
||||
folder_closed = "",
|
||||
folder_open = "",
|
||||
folder_empty = "",
|
||||
-- The next two settings are only a fallback, if you use nvim-web-devicons and configure default icons there
|
||||
-- then these will never be used.
|
||||
default = "*",
|
||||
highlight = "NeoTreeFileIcon"
|
||||
},
|
||||
modified = {
|
||||
symbol = "[+]",
|
||||
highlight = "NeoTreeModified",
|
||||
},
|
||||
name = {
|
||||
trailing_slash = false,
|
||||
use_git_status_colors = true,
|
||||
highlight = "NeoTreeFileName",
|
||||
},
|
||||
git_status = {
|
||||
symbols = {
|
||||
-- Change type
|
||||
added = "", -- or "✚", but this is redundant info if you use git_status_colors on the name
|
||||
modified = "", -- or "", but this is redundant info if you use git_status_colors on the name
|
||||
deleted = "✖",-- this can only be used in the git_status source
|
||||
renamed = "",-- this can only be used in the git_status source
|
||||
-- Status type
|
||||
untracked = "",
|
||||
ignored = "",
|
||||
unstaged = "",
|
||||
staged = "",
|
||||
conflict = "",
|
||||
}
|
||||
},
|
||||
-- If you don't want to use these columns, you can set `enabled = false` for each of them individually
|
||||
file_size = {
|
||||
enabled = true,
|
||||
required_width = 64, -- min width of window required to show this column
|
||||
},
|
||||
type = {
|
||||
enabled = true,
|
||||
required_width = 122, -- min width of window required to show this column
|
||||
},
|
||||
last_modified = {
|
||||
enabled = true,
|
||||
required_width = 88, -- min width of window required to show this column
|
||||
},
|
||||
created = {
|
||||
enabled = true,
|
||||
required_width = 110, -- min width of window required to show this column
|
||||
},
|
||||
symlink_target = {
|
||||
enabled = false,
|
||||
},
|
||||
},
|
||||
-- A list of functions, each representing a global custom command
|
||||
-- that will be available in all sources (if not overridden in `opts[source_name].commands`)
|
||||
-- see `:h neo-tree-custom-commands-global`
|
||||
commands = {},
|
||||
window = {
|
||||
position = "left",
|
||||
width = 40,
|
||||
mapping_options = {
|
||||
noremap = true,
|
||||
nowait = true,
|
||||
},
|
||||
mappings = {
|
||||
["<space>"] = {
|
||||
"toggle_node",
|
||||
nowait = false, -- disable `nowait` if you have existing combos starting with this char that you want to use
|
||||
},
|
||||
["<2-LeftMouse>"] = "open",
|
||||
["<cr>"] = "open",
|
||||
["<esc>"] = "cancel", -- close preview or floating neo-tree window
|
||||
["P"] = { "toggle_preview", config = { use_float = true, use_image_nvim = true } },
|
||||
-- Read `# Preview Mode` for more information
|
||||
["l"] = "focus_preview",
|
||||
["S"] = "open_split",
|
||||
["s"] = "open_vsplit",
|
||||
-- ["S"] = "split_with_window_picker",
|
||||
-- ["s"] = "vsplit_with_window_picker",
|
||||
["t"] = "open_tabnew",
|
||||
-- ["<cr>"] = "open_drop",
|
||||
-- ["t"] = "open_tab_drop",
|
||||
["w"] = "open_with_window_picker",
|
||||
--["P"] = "toggle_preview", -- enter preview mode, which shows the current node without focusing
|
||||
["C"] = "close_node",
|
||||
-- ['C'] = 'close_all_subnodes',
|
||||
["z"] = "close_all_nodes",
|
||||
--["Z"] = "expand_all_nodes",
|
||||
["a"] = {
|
||||
"add",
|
||||
-- this command supports BASH style brace expansion ("x{a,b,c}" -> xa,xb,xc). see `:h neo-tree-file-actions` for details
|
||||
-- some commands may take optional config options, see `:h neo-tree-mappings` for details
|
||||
config = {
|
||||
show_path = "none" -- "none", "relative", "absolute"
|
||||
}
|
||||
},
|
||||
["A"] = "add_directory", -- also accepts the optional config.show_path option like "add". this also supports BASH style brace expansion.
|
||||
["d"] = "delete",
|
||||
["r"] = "rename",
|
||||
["y"] = "copy_to_clipboard",
|
||||
["x"] = "cut_to_clipboard",
|
||||
["p"] = "paste_from_clipboard",
|
||||
["c"] = "copy", -- takes text input for destination, also accepts the optional config.show_path option like "add":
|
||||
-- ["c"] = {
|
||||
-- "copy",
|
||||
-- config = {
|
||||
-- show_path = "none" -- "none", "relative", "absolute"
|
||||
-- }
|
||||
--}
|
||||
["m"] = "move", -- takes text input for destination, also accepts the optional config.show_path option like "add".
|
||||
["q"] = "close_window",
|
||||
["R"] = "refresh",
|
||||
["?"] = "show_help",
|
||||
["<"] = "prev_source",
|
||||
[">"] = "next_source",
|
||||
["i"] = "show_file_details",
|
||||
}
|
||||
},
|
||||
nesting_rules = {},
|
||||
filesystem = {
|
||||
filtered_items = {
|
||||
visible = false, -- when true, they will just be displayed differently than normal items
|
||||
hide_dotfiles = true,
|
||||
hide_gitignored = true,
|
||||
hide_hidden = true, -- only works on Windows for hidden files/directories
|
||||
hide_by_name = {
|
||||
--"node_modules"
|
||||
},
|
||||
hide_by_pattern = { -- uses glob style patterns
|
||||
--"*.meta",
|
||||
--"*/src/*/tsconfig.json",
|
||||
},
|
||||
always_show = { -- remains visible even if other settings would normally hide it
|
||||
--".gitignored",
|
||||
},
|
||||
never_show = { -- remains hidden even if visible is toggled to true, this overrides always_show
|
||||
--".DS_Store",
|
||||
--"thumbs.db"
|
||||
},
|
||||
never_show_by_pattern = { -- uses glob style patterns
|
||||
--".null-ls_*",
|
||||
},
|
||||
},
|
||||
follow_current_file = {
|
||||
enabled = false, -- This will find and focus the file in the active buffer every time
|
||||
-- -- the current file is changed while the tree is open.
|
||||
leave_dirs_open = false, -- `false` closes auto expanded dirs, such as with `:Neotree reveal`
|
||||
},
|
||||
group_empty_dirs = false, -- when true, empty folders will be grouped together
|
||||
hijack_netrw_behavior = "open_default", -- netrw disabled, opening a directory opens neo-tree
|
||||
-- in whatever position is specified in window.position
|
||||
-- "open_current", -- netrw disabled, opening a directory opens within the
|
||||
-- window like netrw would, regardless of window.position
|
||||
-- "disabled", -- netrw left alone, neo-tree does not handle opening dirs
|
||||
use_libuv_file_watcher = false, -- This will use the OS level file watchers to detect changes
|
||||
-- instead of relying on nvim autocmd events.
|
||||
window = {
|
||||
mappings = {
|
||||
["<bs>"] = "navigate_up",
|
||||
["."] = "set_root",
|
||||
["H"] = "toggle_hidden",
|
||||
["/"] = "fuzzy_finder",
|
||||
["D"] = "fuzzy_finder_directory",
|
||||
["#"] = "fuzzy_sorter", -- fuzzy sorting using the fzy algorithm
|
||||
-- ["D"] = "fuzzy_sorter_directory",
|
||||
["f"] = "filter_on_submit",
|
||||
["<c-x>"] = "clear_filter",
|
||||
["[g"] = "prev_git_modified",
|
||||
["]g"] = "next_git_modified",
|
||||
["o"] = { "show_help", nowait=false, config = { title = "Order by", prefix_key = "o" }},
|
||||
["oc"] = { "order_by_created", nowait = false },
|
||||
["od"] = { "order_by_diagnostics", nowait = false },
|
||||
["og"] = { "order_by_git_status", nowait = false },
|
||||
["om"] = { "order_by_modified", nowait = false },
|
||||
["on"] = { "order_by_name", nowait = false },
|
||||
["os"] = { "order_by_size", nowait = false },
|
||||
["ot"] = { "order_by_type", nowait = false },
|
||||
-- ['<key>'] = function(state) ... end,
|
||||
},
|
||||
fuzzy_finder_mappings = { -- define keymaps for filter popup window in fuzzy_finder_mode
|
||||
["<down>"] = "move_cursor_down",
|
||||
["<C-n>"] = "move_cursor_down",
|
||||
["<up>"] = "move_cursor_up",
|
||||
["<C-p>"] = "move_cursor_up",
|
||||
-- ['<key>'] = function(state, scroll_padding) ... end,
|
||||
},
|
||||
},
|
||||
|
||||
commands = {} -- Add a custom command or override a global one using the same function name
|
||||
},
|
||||
buffers = {
|
||||
follow_current_file = {
|
||||
enabled = true, -- This will find and focus the file in the active buffer every time
|
||||
-- -- the current file is changed while the tree is open.
|
||||
leave_dirs_open = false, -- `false` closes auto expanded dirs, such as with `:Neotree reveal`
|
||||
},
|
||||
group_empty_dirs = true, -- when true, empty folders will be grouped together
|
||||
show_unloaded = true,
|
||||
window = {
|
||||
mappings = {
|
||||
["bd"] = "buffer_delete",
|
||||
["<bs>"] = "navigate_up",
|
||||
["."] = "set_root",
|
||||
["o"] = { "show_help", nowait=false, config = { title = "Order by", prefix_key = "o" }},
|
||||
["oc"] = { "order_by_created", nowait = false },
|
||||
["od"] = { "order_by_diagnostics", nowait = false },
|
||||
["om"] = { "order_by_modified", nowait = false },
|
||||
["on"] = { "order_by_name", nowait = false },
|
||||
["os"] = { "order_by_size", nowait = false },
|
||||
["ot"] = { "order_by_type", nowait = false },
|
||||
}
|
||||
},
|
||||
},
|
||||
git_status = {
|
||||
window = {
|
||||
position = "float",
|
||||
mappings = {
|
||||
["A"] = "git_add_all",
|
||||
["gu"] = "git_unstage_file",
|
||||
["ga"] = "git_add_file",
|
||||
["gr"] = "git_revert_file",
|
||||
["gc"] = "git_commit",
|
||||
["gp"] = "git_push",
|
||||
["gg"] = "git_commit_and_push",
|
||||
["o"] = { "show_help", nowait=false, config = { title = "Order by", prefix_key = "o" }},
|
||||
["oc"] = { "order_by_created", nowait = false },
|
||||
["od"] = { "order_by_diagnostics", nowait = false },
|
||||
["om"] = { "order_by_modified", nowait = false },
|
||||
["on"] = { "order_by_name", nowait = false },
|
||||
["os"] = { "order_by_size", nowait = false },
|
||||
["ot"] = { "order_by_type", nowait = false },
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
vim.cmd([[nnoremap \ :Neotree reveal<cr>]])
|
||||
end
|
||||
}
|
||||
```
|
||||
|
||||
_The above configuration is not everything that can be changed, it's just the
|
||||
parts you might want to change first._
|
||||
|
||||
|
||||
See `:h neo-tree` for full documentation. You can also preview that online at
|
||||
[doc/neo-tree.txt](doc/neo-tree.txt), although it's best viewed within vim.
|
||||
|
||||
|
||||
To see all of the default config options with commentary, you can view it online
|
||||
at [lua/neo-tree/defaults.lua](lua/neo-tree/defaults.lua). You can also paste it
|
||||
into a buffer after installing Neo-tree by running:
|
||||
|
||||
```
|
||||
:lua require("neo-tree").paste_default_config()
|
||||
```
|
||||
|
||||
## The `:Neotree` Command
|
||||
|
||||
The single `:Neotree` command accepts a range of arguments that give you full
|
||||
control over the details of what and where it will show. For example, the following
|
||||
command will open a file browser on the right hand side, "revealing" the currently
|
||||
active file:
|
||||
|
||||
```
|
||||
:Neotree filesystem reveal right
|
||||
```
|
||||
|
||||
Arguments can be specified as either a key=value pair or just as the value. The
|
||||
key=value form is more verbose but may help with clarity. For example, the command
|
||||
above can also be specified as:
|
||||
|
||||
```
|
||||
:Neotree source=filesystem reveal=true position=right
|
||||
```
|
||||
|
||||
All arguments are optional and can be specified in any order. If you issue the command
|
||||
without any arguments, it will use default values for everything. For example:
|
||||
|
||||
```
|
||||
:Neotree
|
||||
```
|
||||
|
||||
will open the filesystem source on the left hand side and focus it, if you are using
|
||||
the default config.
|
||||
|
||||
### Tab Completion
|
||||
|
||||
Neotree supports tab completion for all arguments. Once a given argument has a value,
|
||||
it will stop suggesting those completions. It will also offer completions for paths.
|
||||
The simplest way to disambiguate a path from another type of argument is to start
|
||||
them with `/` or `./`.
|
||||
|
||||
### Arguments
|
||||
|
||||
Here is the full list of arguments you can use:
|
||||
|
||||
#### `action`
|
||||
What to do. Can be one of:
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| focus | Show and/or switch focus to the specified Neotree window. DEFAULT |
|
||||
| show | Show the window, but keep focus on your current window. |
|
||||
| close | Close the window(s) specified. Can be combined with "position" and/or "source" to specify which window(s) to close. |
|
||||
|
||||
#### `source`
|
||||
What to show. Can be one of:
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| filesystem | Show a file browser. DEFAULT |
|
||||
| buffers | Show a list of currently open buffers. |
|
||||
| git_status | Show the output of `git status` in a tree layout. |
|
||||
| last | Equivalent to the last source used |
|
||||
|
||||
#### `position`
|
||||
Where to show it, can be one of:
|
||||
|
||||
| Option | Description |
|
||||
|---------|-------------|
|
||||
| left | Open as left hand sidebar. DEFAULT |
|
||||
| right | Open as right hand sidebar. |
|
||||
| top | Open as top window. |
|
||||
| bottom | Open as bottom window. |
|
||||
| float | Open as floating window. |
|
||||
| current | Open within the current window, like netrw or vinegar would. |
|
||||
|
||||
#### `toggle`
|
||||
This is a boolean flag. Adding this means that the window will be closed if it
|
||||
is already open.
|
||||
|
||||
#### `dir`
|
||||
The directory to set as the root/cwd of the specified window. If you include a
|
||||
directory as one of the arguments, it will be assumed to be this option, you
|
||||
don't need the full dir=/path. You may use any value that can be passed to the
|
||||
'expand' function, such as `%:p:h:h` to specify two directories up from the
|
||||
current file. For example:
|
||||
|
||||
```
|
||||
:Neotree ./relative/path
|
||||
:Neotree /home/user/relative/path
|
||||
:Neotree dir=/home/user/relative/path
|
||||
:Neotree position=current dir=relative/path
|
||||
```
|
||||
|
||||
#### `git_base`
|
||||
The base that is used to calculate the git status for each dir/file.
|
||||
By default it uses `HEAD`, so it shows all changes that are not yet committed.
|
||||
You can for example work on a feature branch, and set it to `main`. It will
|
||||
show all changes that happened on the feature branch and main since you
|
||||
branched off.
|
||||
|
||||
Any git ref, commit, tag, or sha will work.
|
||||
|
||||
```
|
||||
:Neotree main
|
||||
:Neotree v1.0
|
||||
:Neotree git_base=8fe34be
|
||||
:Neotree git_base=HEAD
|
||||
```
|
||||
|
||||
#### `reveal`
|
||||
This is a boolean flag. Adding this will make Neotree automatically find and
|
||||
focus the current file when it opens.
|
||||
|
||||
#### `reveal_file`
|
||||
A path to a file to reveal. This supersedes the "reveal" flag so there is no
|
||||
need to specify both. Use this if you want to reveal something other than the
|
||||
current file. If you include a path to a file as one of the arguments, it will
|
||||
be assumed to be this option. Like "dir", you can pass any value that can be
|
||||
passed to the 'expand' function. For example:
|
||||
|
||||
```
|
||||
:Neotree reveal_file=/home/user/my/file.text
|
||||
:Neotree position=current dir=%:p:h:h reveal_file=%:p
|
||||
:Neotree current %:p:h:h %:p
|
||||
```
|
||||
|
||||
One neat trick you can do with this is to open a Neotree window which is
|
||||
focused on the file under the cursor using the `<cfile>` keyword:
|
||||
|
||||
```
|
||||
nnoremap gd :Neotree float reveal_file=<cfile> reveal_force_cwd<cr>
|
||||
```
|
||||
|
||||
#### `reveal_force_cwd`
|
||||
This is a boolean flag. Normally, if you use one of the reveal options and the
|
||||
given file is not within the current working directory, you will be asked if you
|
||||
want to change the current working directory. If you include this flag, it will
|
||||
automatically change the directory without prompting. This option implies
|
||||
"reveal", so you do not need to specify both.
|
||||
|
||||
#### `selector`
|
||||
This is a boolean flag. When you specifically set this to false (`selector=false`)
|
||||
neo-tree will disable the [source selector](#source-selector) for that neo-tree
|
||||
instance. Otherwise, the source selector will depend on what you specified in
|
||||
the configuration (`config.source_selector.{winbar,statusline}`).
|
||||
|
||||
See `:h neo-tree-commands` for details and a full listing of available arguments.
|
||||
|
||||
### File Nesting
|
||||
|
||||
See `:h neo-tree-file-nesting` for more details about file nesting.
|
||||
|
||||
|
||||
### Netrw Hijack
|
||||
|
||||
```
|
||||
:edit .
|
||||
:[v]split .
|
||||
```
|
||||
|
||||
If `"filesystem.window.position"` is set to `"current"`, or if you have specified
|
||||
`filesystem.hijack_netrw_behavior = "open_current"`, then any command
|
||||
that would open a directory will open neo-tree in the specified window.
|
||||
|
||||
|
||||
## Sources
|
||||
|
||||
Neo-tree is built on the idea of supporting various sources. Sources are
|
||||
basically interface implementations whose job it is to provide a list of
|
||||
hierarchical items to be rendered, along with commands that are appropriate to
|
||||
those items.
|
||||
|
||||
### filesystem
|
||||
The default source is `filesystem`, which displays your files and folders. This
|
||||
is the default source in commands when none is specified.
|
||||
|
||||
This source can be used to:
|
||||
- Browse the filesystem
|
||||
- Control the current working directory of nvim
|
||||
- Add/Copy/Delete/Move/Rename files and directories
|
||||
- Search the filesystem
|
||||
- Monitor git status and lsp diagnostics for the current working directory
|
||||
|
||||
### buffers
|
||||
|
||||
|
||||
Another available source is `buffers`, which displays your open buffers. This is
|
||||
the same list you would see from `:ls`. To show with the `buffers` list, use:
|
||||
|
||||
```
|
||||
:Neotree buffers
|
||||
```
|
||||
|
||||
### git_status
|
||||
This view take the results of the `git status` command and display them in a
|
||||
tree. It includes commands for adding, unstaging, reverting, and committing.
|
||||
|
||||
The screenshot below shows the result of `:Neotree float git_status` while the
|
||||
filesystem is open in a sidebar:
|
||||
|
||||
|
||||
|
||||
You can specify a different git base here as well. But be aware that it is not
|
||||
possible to unstage / revert a file that is already committed.
|
||||
|
||||
```
|
||||
:Neotree float git_status git_base=main
|
||||
```
|
||||
|
||||
### document_symbols
|
||||
|
||||
|
||||
The document_symbols source lists the symbols in the current document obtained
|
||||
by the LSP request "textDocument/documentSymbols". It currently supports the
|
||||
following features:
|
||||
- [x] UI:
|
||||
- [x] Display all symbols in the current file with symbol kinds
|
||||
- [x] Symbols nesting
|
||||
- [x] Configurable kinds' name and icon
|
||||
- [x] Auto-refresh symbol list
|
||||
- [x] Follow cursor
|
||||
- [ ] Commands
|
||||
- [x] Jump to symbols, open symbol in split,... (`open_split` and friends)
|
||||
- [x] Rename symbols (`rename`)
|
||||
- [x] Preview symbol (`preview` and friends)
|
||||
- [ ] Hover docs
|
||||
- [ ] Call hierarchy
|
||||
- [x] LSP
|
||||
- [x] LSP Support
|
||||
- [x] LSP server selection (ignore, allow_only, use first, use all, etc.)
|
||||
- [ ] CoC Support
|
||||
|
||||
See #879 for the tracking issue of these features.
|
||||
|
||||
This source is currently experimental, so in order to use it, you need to first
|
||||
add `"document_symbols"` to `config.sources` and open it with the command
|
||||
```
|
||||
:Neotree document_symbols
|
||||
```
|
||||
|
||||
### External Sources
|
||||
|
||||
There are more sources available as extensions that are managed outside of this repository. See the
|
||||
[wiki](https://github.com/nvim-neo-tree/neo-tree.nvim/wiki/External-Sources) for more information.
|
||||
|
||||
### Source Selector
|
||||
|
||||
|
||||
|
||||
You can enable a clickable source selector in either the winbar (requires neovim 0.8+) or the statusline.
|
||||
To do so, set one of these options to `true`:
|
||||
|
||||
```lua
|
||||
require("neo-tree").setup({
|
||||
source_selector = {
|
||||
winbar = false,
|
||||
statusline = false
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
There are many configuration options to change the style of these tabs.
|
||||
See [lua/neo-tree/defaults.lua](lua/neo-tree/defaults.lua) for details.
|
||||
|
||||
### Preview Mode
|
||||
|
||||
`:h neo-tree-preview-mode`
|
||||
|
||||
Preview mode will temporarily show whatever file the cursor is on without
|
||||
switching focus from the Neo-tree window. By default, files will be previewed
|
||||
in a new floating window. This can also be configured to automatically choose
|
||||
an existing split by configuring the command like this:
|
||||
|
||||
```lua
|
||||
require("neo-tree").setup({
|
||||
window = {
|
||||
mappings = {
|
||||
["P"] = { "toggle_preview", config = { use_float = false, use_image_nvim = true } },
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
Anything that causes Neo-tree to lose focus will end preview mode. When
|
||||
`use_float = false`, the window that was taken over by preview mode will revert
|
||||
back to whatever was shown in that window before preview mode began.
|
||||
|
||||
If you want to work with the floating preview mode window in autocmds or other
|
||||
custom code, the window will have the `neo-tree-preview` filetype.
|
||||
|
||||
When preview mode is not using floats, the window will have the window local
|
||||
variable `neo_tree_preview` set to `1` to indicate that it is being used as a
|
||||
preview window. You can refer to this in statusline and winbar configs to mark a
|
||||
window as being used as a preview.
|
||||
|
||||
#### Image Support in Preview Mode
|
||||
|
||||
If you have [3rd/image.nvim](https://github.com/3rd/image.nvim) installed, preview
|
||||
mode supports image rendering by default using kitty graphics protocol or ueberzug
|
||||
([Video](https://user-images.githubusercontent.com/41065736/277180763-b7152637-f310-43a5-b8c3-4bcba135629d.mp4)).
|
||||
However, if you do not want this feature, you can disable it by changing the option
|
||||
`use_image_nvim = false` in the mappings config mentioned above.
|
||||
|
||||
## Configuration and Customization
|
||||
|
||||
This is designed to be flexible. The way that is achieved is by making
|
||||
everything a function, or a string that identifies a built-in function. All of the
|
||||
built-in functions can be replaced with your own implementation, or you can
|
||||
add new ones.
|
||||
|
||||
Each node in the tree is created from the renderer specified for the given node
|
||||
type, and each renderer is a list of component configs to be rendered in order.
|
||||
Each component is a function, either built-in or specified in your config. Those
|
||||
functions simply return the text and highlight group for the component.
|
||||
|
||||
Additionally, there is an events system that you can hook into. If you want to
|
||||
show some new data point related to your files, gather it in the
|
||||
`before_render` event, create a component to display it, and reference that
|
||||
component in the renderer for the `file` and/or `directory` type.
|
||||
|
||||
Details on how to configure everything is in the help file at `:h
|
||||
neo-tree-configuration` or online at
|
||||
[neo-tree.txt](https://github.com/nvim-neo-tree/neo-tree.nvim/blob/main/doc/neo-tree.txt)
|
||||
|
||||
Recipes for customizations can be found on the [wiki](https://github.com/nvim-neo-tree/neo-tree.nvim/wiki/Recipes). Recipes include
|
||||
things like adding a component to show the
|
||||
[Harpoon](https://github.com/ThePrimeagen/harpoon) index for files, or
|
||||
responding to the `"file_opened"` event to auto clear the search when you open a
|
||||
file.
|
||||
|
||||
|
||||
## Why?
|
||||
|
||||
There are many tree plugins for (neo)vim, so why make another one? Well, I
|
||||
wanted something that was:
|
||||
|
||||
1. Easy to maintain and enhance.
|
||||
2. Stable.
|
||||
3. Easy to customize.
|
||||
|
||||
### Easy to maintain and enhance
|
||||
|
||||
This plugin is designed to grow and be flexible. This is accomplished by making
|
||||
the code as decoupled and functional as possible. Hopefully new contributors
|
||||
will find it easy to work with.
|
||||
|
||||
One big difference between this plugin and the ones that came before it, which
|
||||
is also what finally pushed me over the edge into making a new plugin, is that
|
||||
we now have libraries to build upon that did not exist when other tree plugins
|
||||
were created. Most notably, [nui.nvim](https://github.com/MunifTanjim/nui.nvim)
|
||||
and [plenary.nvm](https://github.com/nvim-lua/plenary.nvim). Building upon
|
||||
shared libraries will go a long way in making neo-tree easy to maintain.
|
||||
|
||||
### Stable
|
||||
|
||||
This project will have releases and release tags that follow a simplified
|
||||
Semantic Versioning scheme. The quickstart instructions will always refer to
|
||||
the latest stable major version. Following the **main** branch is for
|
||||
contributors and those that always want bleeding edge. There will be branches
|
||||
for **v1.x**, **v2.x**, etc which will receive updates after a short testing
|
||||
period in **main**. You should be safe to follow those branches and be sure
|
||||
your tree won't break in an update. There will also be tags for each release
|
||||
pushed to those branches named **v1.1**, **v1.2**, etc. If stability is
|
||||
critical to you, or a bug accidentally make it into **v1.x**, you can use those
|
||||
tags instead. It's possible we may backport bug fixes to those tags, but no
|
||||
garauntees on that.
|
||||
|
||||
There will never be a breaking change within a major version (1.x, 2.x, etc.) If
|
||||
a breaking change is needed, there will be depracation warnings in the prior
|
||||
major version, and the breaking change will happen in the next major version.
|
||||
|
||||
### Easy to Customize
|
||||
|
||||
Neo-tree follows in the spirit of plugins like
|
||||
[lualine.nvim](https://github.com/nvim-lualine/lualine.nvim) and
|
||||
[nvim-cokeline](https://github.com/noib3/nvim-cokeline). Everything will be
|
||||
configurable and take either strings, tables, or functions. You can take sane
|
||||
defaults or build your tree items from scratch. There should be the ability to
|
||||
add any features you can think of through existing hooks in the setup function.
|
||||
|
||||
## What is a Breaking Change?
|
||||
|
||||
As of v1.30, a breaking change is defined as anything that _changes_ existing:
|
||||
|
||||
- vim commands (`:Neotree`)
|
||||
- configuration options that are passed into the `setup()` function
|
||||
- `NeoTree*` highlight groups
|
||||
- lua functions exported in the following modules that are not prefixed with `_`:
|
||||
* `neo-tree`
|
||||
* `neo-tree.events`
|
||||
* `neo-tree.sources.manager`
|
||||
* `neo-tree.sources.*` (init.lua files)
|
||||
* `neo-tree.sources.*.commands`
|
||||
* `neo-tree.ui.renderer`
|
||||
* `neo-tree.utils`
|
||||
|
||||
If there are other functions you would like to use that are not yet considered
|
||||
part of the public API, please open an issue so we can discuss it.
|
||||
|
||||
## Contributions
|
||||
|
||||
Contributions are encouraged. Please see [CONTRIBUTING](CONTRIBUTING.md) for more details.
|
||||
|
||||
## Acknowledgements
|
||||
|
||||
### Maintainers
|
||||
|
||||
First and foremost, this project is a community endeavor and would not survive without the constant stream of features
|
||||
and bug fixes that comes from that community. There have been many valued contributors, but a few have stepped up to
|
||||
become maintainers that generously donate their time to guide the project, help out others, and manage the issues. The
|
||||
current list of maintainers are:
|
||||
|
||||
(in alphabetical order)
|
||||
|
||||
- @cseickel
|
||||
- @miversen33
|
||||
- @nhat-vo
|
||||
- @pysan3
|
||||
|
||||
### Other Projects
|
||||
|
||||
This project relies upon these two excellent libraries:
|
||||
- [nui.nvim](https://github.com/MunifTanjim/nui.nvim) for all UI components, including the tree!
|
||||
- [plenary.nvim](https://github.com/nvim-lua/plenary.nvim) for backend utilities, such as scanning the filesystem.
|
||||
|
||||
The design is heavily inspired by these excellent plugins:
|
||||
- [lualine.nvim](https://github.com/nvim-lualine/lualine.nvim)
|
||||
- [nvim-cokeline](https://github.com/noib3/nvim-cokeline)
|
||||
|
||||
Everything I know about writing a tree control in lua, I learned from:
|
||||
- [nvim-tree.lua](https://github.com/nvim-tree/nvim-tree.lua)
|
||||
Reference in New Issue
Block a user