Skip to content

chore: refacto setup part 1 #603

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 7 commits into from
Sep 25, 2021
Merged

chore: refacto setup part 1 #603

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
dfcc305
chore: refacto setup part 1
kyazdani42 Aug 31, 2021
54592ab
add deprecation warning
kyazdani42 Sep 3, 2021
47936df
update readme
kyazdani42 Sep 3, 2021
2b80047
schedule on enter to avoid running before vim first buffer has loaded
kyazdani42 Sep 3, 2021
2a0cb2b
update docs
kyazdani42 Sep 4, 2021
09f1d48
correct typo
kyazdani42 Sep 4, 2021
83a238a
rename tab open -> open on tab
kyazdani42 Sep 4, 2021
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
59 changes: 47 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,40 +21,75 @@ Install with [packer](https://github.com/wbthomason/packer.nvim):
```lua
use {
'kyazdani42/nvim-tree.lua',
requires = 'kyazdani42/nvim-web-devicons'
requires = 'kyazdani42/nvim-web-devicons',
config = function() require'nvim-tree'.setup {} end
}
```

## Setup

Options are currently being migrated into the setup function, you need to run `require'nvim-tree'.setup()` in your personal configurations.
Setup should be run in a lua file or in a lua heredoc (`:help lua-heredoc`) if using in a vim file.
Note that options under the `g:` command should be set **BEFORE** running the setup function.

```lua
-- following options are the default
require'nvim-tree'.setup {
-- disables netrw completely
disable_netrw = true,
-- hijack netrw window on startup
hijack_netrw = true,
-- open the tree when running this setup function
open_on_setup = false,
-- will not open on setup if the filetype is in this list
ignore_ft_on_setup = {},
-- closes neovim automatically when the tree is the last **WINDOW** in the view
auto_close = false,
-- opens the tree when changing/opening a new tab if the tree wasn't previously opened
open_on_tab = false,
-- hijack the cursor in the tree to put it at the start of the filename
hijack_cursor = false,
-- updates the root directory of the tree on `DirChanged` (when your run `:cd` usually)
update_cwd = false,
-- update the focused file on `BufEnter`, un-collapses the folders recursively until it finds the file
update_focused_file = {
-- enables the feature
enable = false,
-- update the root directory of the tree to the one of the folder containing the file if the file is not under the current root directory
-- only relevant when `update_focused_file.enable` is true
update_cwd = false,
-- list of buffer names / filetypes that will not update the cwd if the file isn't found under the current root directory
-- only relevant when `update_focused_file.update_cwd` is true and `update_focused_file.enable` is true
ignore_list = {}
},
-- configuration options for the system open command (`s` in the tree by default)
system_open = {
-- the command to run this, leaving nil should work in most cases
cmd = nil,
-- the command arguments as a list
args = {}
},
}
```

```vim
let g:nvim_tree_side = 'right' "left by default
let g:nvim_tree_width = 40 "30 by default, can be width_in_columns or 'width_in_percent%'
let g:nvim_tree_ignore = [ '.git', 'node_modules', '.cache' ] "empty by default
let g:nvim_tree_gitignore = 1 "0 by default
let g:nvim_tree_auto_open = 1 "0 by default, opens the tree when typing `vim $DIR` or `vim`
let g:nvim_tree_auto_close = 1 "0 by default, closes the tree when it's the last window
let g:nvim_tree_auto_ignore_ft = [ 'startify', 'dashboard' ] "empty by default, don't auto open tree on specific filetypes.
let g:nvim_tree_quit_on_open = 1 "0 by default, closes the tree when you open a file
let g:nvim_tree_follow = 1 "0 by default, this option allows the cursor to be updated when entering a buffer
let g:nvim_tree_follow_update_path = 1 "0 by default, will update the path of the current dir if the file is not inside the tree.
let g:nvim_tree_indent_markers = 1 "0 by default, this option shows indent markers when folders are open
let g:nvim_tree_hide_dotfiles = 1 "0 by default, this option hides files and folders starting with a dot `.`
let g:nvim_tree_git_hl = 1 "0 by default, will enable file highlight for git attributes (can be used without the icons).
let g:nvim_tree_highlight_opened_files = 1 "0 by default, will enable folder and file icon highlight for opened files/directories.
let g:nvim_tree_root_folder_modifier = ':~' "This is the default. See :help filename-modifiers for more options
let g:nvim_tree_tab_open = 1 "0 by default, will open the tree when entering a new tab and the tree was previously open
let g:nvim_tree_auto_resize = 0 "1 by default, will resize the tree to its saved width when opening a file
let g:nvim_tree_disable_netrw = 0 "1 by default, disables netrw
let g:nvim_tree_hijack_netrw = 0 "1 by default, prevents netrw from automatically opening when opening directories (but lets you keep its other utilities)
let g:nvim_tree_add_trailing = 1 "0 by default, append a trailing slash to folder names
let g:nvim_tree_group_empty = 1 " 0 by default, compact folders that only contain a single folder into one node in the file tree
let g:nvim_tree_lsp_diagnostics = 1 "0 by default, will show lsp diagnostics in the signcolumn. See :help nvim_tree_lsp_diagnostics
let g:nvim_tree_disable_window_picker = 1 "0 by default, will disable the window picker.
let g:nvim_tree_hijack_cursor = 0 "1 by default, when moving cursor in the tree, will position the cursor at the start of the file on the current line
let g:nvim_tree_icon_padding = ' ' "one space by default, used for rendering the space between the icon and the filename. Use with caution, it could break rendering if you set an empty string depending on your font.
let g:nvim_tree_symlink_arrow = ' >> ' " defaults to ' ➛ '. used as a separator between symlinks' source and target.
let g:nvim_tree_update_cwd = 1 "0 by default, will update the tree cwd when changing nvim's directory (DirChanged event). Behaves strangely with autochdir set.
let g:nvim_tree_respect_buf_cwd = 1 "0 by default, will change cwd of nvim-tree to that of new buffer's when opening nvim-tree.
let g:nvim_tree_refresh_wait = 500 "1000 by default, control how often the tree can be refreshed, 1000 means the tree can be refresh once per 1000ms.
let g:nvim_tree_window_picker_exclude = {
Expand Down Expand Up @@ -148,7 +183,7 @@ highlight NvimTreeFolderIcon guibg=blue
- type `]c` to go to next git item
- type `[c` to go to prev git item
- type `-` to navigate up to the parent directory of the current file/directory
- type `s` to open a file with default system application or a folder with default file manager (if you want to change the command used to do it see `:h g:nvim_tree_system_open_command` and `:h g:nvim_tree_system_open_command_args`)
- type `s` to open a file with default system application or a folder with default file manager (if you want to change the command used to do it see `:h nvim-tree.setup` under `system_open`)
- if the file is a directory, `<CR>` will open the directory otherwise it will open the file in the buffer near the tree
- if the file is a symlink, `<CR>` will follow the symlink (if the target is a file)
- `<C-v>` will open the file in a vertical split
Expand Down
177 changes: 101 additions & 76 deletions doc/nvim-tree-lua.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,107 @@ Print clipboard content for both cut and copy
Resize the NvimTree window to the given size. Example: `:NvimTreeresize 50`
resizes the window to the width of 50.

==============================================================================
SETUP *nvim-tree-setup*

To configure the tree (and make it runnable), you should call the setup
function.

>
require'nvim-tree'.setup {
disable_netrw = true,
hijack_netrw = true,
open_on_setup = false,
ignore_ft_on_setup = {},
auto_close = false,
open_on_tab = false,
hijack_cursor = false,
update_cwd = false,
update_focused_file = {
enable = false,
update_cwd = false,
ignore_list = {}
},
system_open = {
cmd = nil,
args = {}
},
}
<

As options are currently being migrated, configuration of global options in
*nvim-tree-options* should be done BEFORE the setup call.

Here is a list of the options available in the setup call:
- |disable_netrw|: completely disable netrw
type: `boolean`
default: `true`

- |hijack_netrw|: hijack netrw windows (overriden if |disable_netrw| is `true`)
type: `boolean`
default: `true`

- |open_on_setup|: will automatically open the tree when running setup if current
buffer is a directory, is empty or is unnamed.
type: `boolean`
default: `false`

- |ignore_ft_on_setup|: list of filetypes that will make |open_on_setup| not
open. You can use this option if you don't want the tree to open in some
scenarios (eg using vim startify).
type: `{string}`
default: `{}`

- |auto_close|: force closing neovim when the tree is the last window in the view.
type: `boolean`
default: `false`

- |open_on_tab|: opens the tree automatically when switching tabpage or opening a new
tabpage if the tree was previously open.
type: `boolean`
default: `false`

- |hijack_cursor|: keeps the cursor on the first letter of the filename when
moving in the tree.
type: `boolean`
default: `false`

- |update_cwd|: changes the tree root directory on `DirChanged` and refreshes
the tree.
type: `boolean`
default: `false`

- |update_focused_file|: update the focused file on `BufEnter`, un-collapses
the folders recursively until it finds the file

- |update_focused_file.enable|: enable this feature.
type: `boolean`
default: `false`

- |update_focused_file.update_cwd|: update the root directory of the tree to the one
of the folder containing the file if the file is not under the current root
directory. Only relevant when |update_focused_file.enable| is `true`
type: `boolean`
default: `false`

- |update_focused_file.ignore_list|: list of buffer names and filetypes that will not
update the root dir of the tree if the file isn't found under the current root
directory. Only relevant when |update_focused_file.update_cwd| is `true` and
|update_focused_file.enable| is `true`.
type: `{string}`
default: `{}`

- |system_open|: configuration options for the system open command

- |system_open.cmd|: the command to run, leaving nil should work but
useful if you want to override the default command with another one.
type: `string`
default: `nil`

- |system_open.args|: the command arguments as a list
type: `{string}`
default: `{}`

==============================================================================
OPTIONS *nvim-tree-options*

Expand Down Expand Up @@ -166,58 +267,12 @@ You can enable file highlight for git attributes by setting this property.
This can be used with or without the icons.


|g:nvim_tree_follow| *g:nvim_tree_follow*

Can be `0` or `1`. When `1`, will update the cursor to update to the correct
location in the tree on |BufEnter|.
Default is 0

|g:nvim_tree_follow_update_path| *g:nvim_tree_follow_update_path*

Can be `0` or `1`. When `1`, will update the path of the current dir if the
file is not inside the tree. Works only with |g:nvim_tree_follow| = 1.
Default is 0

|g:nvim_tree_auto_open| *g:nvim_tree_auto_open*

Can be `0` or `1`. When `1`, will open the tree when the package is loaded.
It's not relying on VimEnter anymore.
Default is 0

|g:nvim_tree_auto_close| *g:nvim_tree_auto_close*

Can be `0` or `1`. When `1`, will bind |BufEnter| to automatically
close the tree if it's the last window.
Default is 0

|g:nvim_tree_auto_ignore_ft| *g:nvim_tree_auto_ignore_ft*

Don't auto open the tree on specific filetypes.
Useful when you don't want to open tree on plugins like 'Startify'
Default is {}
>
example: let g.nvim_tree_auto_ignore_ft = {'startify', 'dashboard'}

|g:nvim_tree_quit_on_open| *g:nvim_tree_quit_on_open*

Can be `0` or `1`. When `1`, will close the tree when a file is opened.
Applies to: `edit`, `vsplit`, `split`, `tabnew`.
Default is 0

|g:nvim_tree_system_open_command| *g:nvim_tree_system_open_command*

A string containing the command used to open a file/folder with default system
application. If left unset it will be automatically filled with the right
command, depending on the operating system. If your operating system isn't
recognized or if you want to use another command you can edit it.
Default: depends on the operating system

|g:nvim_tree_system_open_command_args| *g:nvim_tree_system_open_command_args*

An array of strings containing the arguments to be passed to the command
specified in |g:nvim_tree_system_open_command|.
Default: unset if not using Windows

|g:nvim_tree_disable_keybindings| *g:nvim_tree_disable_keybindings*

Can be `0` or `1`. When `1`, will disable all keybindings by the plugin.
Expand Down Expand Up @@ -246,30 +301,12 @@ In what format to show root folder. See `:help filename-modifiers` for
available options.
Default is `:~`

|g:nvim_tree_tab_open| *g:nvim_tree_tab_open*

Can be 0 or 1. When 1, will open the tree when entering a new tab if the
tree was previously open.
Default is 0

|g:nvim_tree_auto_resize| *g:nvim_tree_auto_resize*

Can be 0 or 1. When 1, it will resize the tree to it's saved width
when opening a new file.
Default is 1

|g:nvim_tree_hijack_netrw| *g:nvim_tree_hijack_netrw*

Can be 0 or 1. When 1, disable netrw buffers when nvim-tree start but keeps
existing netrw functionnalities accross buffers (like `gx`).
1 by default.

|g:nvim_tree_disable_netrw| *g:nvim_tree_disable_netrw*

Can be 0 or 1. When 1, completely disable netrw and all related
functionnalities.
1 by default.

|g:nvim_tree_add_trailing| *g:nvim_tree_add_trailing*

Can be 0 or 1. When 1, appends a trailing slash to folder names.
Expand Down Expand Up @@ -324,12 +361,6 @@ selectable. The default table is
}
<

|g:nvim_tree_hijack_cursor| *g:nvim_tree_hijack_cursor*

Can be 0 or 1. 1 by default.
When 1, moving cursor in the tree will position the cursor at the start
of the file on the current line.

|g:nvim_tree_icon_padding| *g:nvim_tree_icon_padding*

One space by default, used for rendering the space between the icon and the filename. Use with caution, it could break rendering if you set an empty string depending on your font.
Expand All @@ -338,12 +369,6 @@ One space by default, used for rendering the space between the icon and the file

Defaults to ' ➛ '. Used as a separator between symlinks' source and target.

|g:nvim_tree_update_cwd|

Can be 0 or 1. 0 by default.
Will update the tree cwd when changing nvim's directory (DirChanged event).
WARNING: Behaves strangely with autochdir set.

|g:nvim_tree_respect_buf_cwd| *g:nvim_tree_respect_buf_cwd*

Can be 0 or 1. 0 by default.
Expand Down
Loading