Skip to content

Commit aa24290

Browse files
committed
doc(#2934): tidy and correct nvim_tree.Config.UI and nvim_tree.Config.Actions
1 parent 7634f72 commit aa24290

2 files changed

Lines changed: 220 additions & 96 deletions

File tree

doc/nvim-tree-lua.txt

Lines changed: 77 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -3525,101 +3525,110 @@ Lua module: nvim_tree *nvim-tree-module*
35253525
*nvim_tree.Config.Actions*
35263526

35273527
Fields: ~
3528-
• {use_system_clipboard}? (`boolean`) A boolean value that toggle the
3529-
use of system clipboard when copy/paste
3530-
function are invoked. When enabled, copied
3531-
text will be stored in registers '+'
3532-
(system), otherwise, it will be stored in '1'
3533-
and '"'. Default: `true`
3534-
• {change_dir}? (`nvim_tree.Config.Actions.ChangeDir`) vim
3535-
|current-directory| behaviour.
3528+
• {use_system_clipboard}? (`boolean`, default: `true`) A boolean value
3529+
that toggle the use of system clipboard when
3530+
copy/paste function are invoked. When
3531+
enabled, copied text will be stored in
3532+
registers `+` (system), otherwise, it will be
3533+
stored in `1` and `"`
3534+
• {change_dir}? (`nvim_tree.Config.Actions.ChangeDir`)
3535+
|nvim_tree.Config.Actions.ChangeDir|
35363536
• {expand_all}? (`nvim_tree.Config.Actions.ExpandAll`)
3537-
Configuration for
3538-
|nvim-tree-api.tree.expand_all()| and
3539-
|nvim-tree-api.node.expand()|
3537+
|nvim_tree.Config.Actions.ExpandAll|
35403538
• {file_popup}? (`nvim_tree.Config.Actions.FilePopup`)
3541-
Configuration for file_popup behaviour.
3539+
|nvim_tree.Config.Actions.FilePopup|
35423540
• {open_file}? (`nvim_tree.Config.Actions.OpenFile`)
3543-
Configuration options for opening a file from
3544-
nvim-tree.
3541+
|nvim_tree.Config.Actions.OpenFile|
35453542
• {remove_file}? (`nvim_tree.Config.Actions.RemoveFile`)
3546-
Configuration options for removing a file
3547-
from nvim-tree.
3543+
|nvim_tree.Config.Actions.RemoveFile|
35483544

35493545
*nvim_tree.Config.Actions.ChangeDir*
3546+
vim |current-directory| behaviour
35503547

35513548
Fields: ~
3552-
{enable}? (`boolean`) Change the working directory when
3553-
changing directories in the tree. Default:
3554-
`true`
3555-
{global}? (`boolean`) Use `:cd` instead of `:lcd` when
3556-
changing directories. Default: `false`
3557-
• {restrict_above_cwd}? (`boolean`) Restrict changing to a directory
3558-
above the global cwd. Default: `false`
3549+
{enable}? (`boolean`, default: `true`) Change the working
3550+
directory when changing directories in the tree
3551+
{global}? (`boolean`, default: `false`) Use `:cd` instead
3552+
of `:lcd` when changing directories.
3553+
• {restrict_above_cwd}? (`boolean`, default: `false`) Restrict changing
3554+
to a directory above the global cwd.
35593555

35603556
*nvim_tree.Config.Actions.ExpandAll*
3557+
Configuration for |nvim-tree-api.tree.expand_all()| and
3558+
|nvim-tree-api.node.expand()|
35613559

35623560
Fields: ~
3563-
• {max_folder_discovery}? (`integer`) Limit the number of folders being
3564-
explored when expanding every folders. Avoids
3565-
hanging neovim when running this action on
3566-
very large folders. Default: `300`
3567-
{exclude}? (`string[]`) A list of directories that
3568-
should not be expanded automatically. E.g
3569-
`{ ".git", "target", "build" }` etc. Default:
3570-
`{}`
3561+
• {max_folder_discovery}? (`integer`, default: `300`) Limit the number
3562+
of folders being explored when expanding
3563+
every folders. Avoids hanging neovim when
3564+
running this action on very large folders.
3565+
{exclude}? (`string[]`, default: `{}`) A list of
3566+
directories that should not be expanded
3567+
automatically e.g
3568+
`{ ".git", "target", "build" }`
35713569

35723570
*nvim_tree.Config.Actions.FilePopup*
3571+
Configuration for file_popup behaviour.
35733572

35743573
Fields: ~
3575-
• {open_win_config}? (`table`) Floating window config for file_popup.
3576-
See |nvim_open_win| for more details. You
3577-
shouldn't define `"width"` and `"height"` values
3578-
here. They will be overridden to fit the
3579-
file_popup content. Default:
3580-
`{ col = 1, row = 1, relative = "cursor", border = "shadow", style = "minimal", }`
3574+
• {open_win_config}? (`vim.api.keyset.win_config`, default: `{ col = 1, row = 1, relative = "cursor", border = "shadow", style = "minimal", }`)
3575+
Floating window config for file_popup. See
3576+
|nvim_open_win| and |vim.api.keyset.win_config|
3577+
for more details. You shouldn't define `width` and
3578+
`height` values here. They will be overridden to
3579+
fit the file_popup content.
35813580

35823581
*nvim_tree.Config.Actions.OpenFile*
3582+
Configuration options for opening a file from nvim-tree.
35833583

35843584
Fields: ~
3585-
• {quit_on_open}? (`boolean`) Closes the explorer when opening a file.
3586-
Default: `false`
3587-
{eject}? (`boolean`) Prevent a new file opened from within
3588-
nvim-tree replacing the current nvim-tree window.
3589-
Default: `true`
3590-
• {resize_window}? (`boolean`) Resizes the tree when opening a file.
3591-
Default: `true`
3585+
• {quit_on_open}? (`boolean`, default: `false`) Closes the explorer
3586+
when opening a file
3587+
{eject}? (`boolean`, default: `true`) Prevent new opened file
3588+
from opening in the same window as the tree.
3589+
• {resize_window}? (`boolean`, default: `true`) Resizes the tree when
3590+
opening a file
35923591
• {window_picker}? (`nvim_tree.Config.Actions.OpenFile.WindowPicker`)
3593-
Window picker configuration.
3592+
|nvim_tree.Config.Actions.OpenFile.WindowPicker|
35943593

35953594
*nvim_tree.Config.Actions.OpenFile.WindowPicker*
3595+
Window picker configuration.
35963596

35973597
Fields: ~
3598-
{enable}? (`boolean`) Enable the window picker. If this feature is
3599-
not enabled, files will open in the current window.
3600-
Default: `true`
3601-
{picker}? (`string|fun(): integer`) Change the way in which to pick
3602-
a window. Default: `"default"`
3603-
{chars}? (`string`) A string of chars used for window picker
3604-
labels. Default: `"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"`
3598+
{enable}? (`boolean`, default: `true`) Enable the feature. If the
3599+
feature is not enabled, files will open in window from
3600+
which you last opened the tree, obeying
3601+
|nvim-tree.actions.open_file.window_picker.exclude|
3602+
{picker}? (`string|fun(): integer`, default: `"default"`) Change the
3603+
default window picker: a string `"default"` or a function.
3604+
The function should return the window id that will open
3605+
the node, or `nil` if an invalid window is picked or user
3606+
cancelled the action. The picker may create a new window.
3607+
{chars}? (`string`, default:
3608+
`"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"`) A string of
3609+
chars used as identifiers by the window picker.
36053610
{exclude}? (`nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude`)
3606-
Floating window config for window selector.
3611+
|nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude|
36073612

36083613
*nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude*
3614+
Tables of buffer option names mapped to a list of option values. Windows
3615+
containing matching buffers will not be:
3616+
• available when using a window picker
3617+
• selected when not using a window picker
36093618

36103619
Fields: ~
3611-
{filetype}? (`string[]`) A list of filetypes to exclude from window
3612-
picker. Default:
3613-
`{ "notify", "lazy", "qf", "diff", "fugitive", "fugitiveblame", }`
3614-
{buftype}? (`string[]`) A list of buftypes to exclude from window
3615-
picker. Default: `{ "nofile", "terminal", "help", }`
3620+
{filetype}? (`string[]`) (default:
3621+
`{ "notify", "lazy", "qf", "diff", "fugitive", "fugitiveblame", }`)
3622+
{buftype}? (`string[]`) (default:
3623+
`{ "nofile", "terminal", "help", }`)
36163624

36173625
*nvim_tree.Config.Actions.RemoveFile*
3626+
Configuration options for removing a file from nvim-tree.
36183627

36193628
Fields: ~
3620-
• {close_window}? (`boolean`) Close any window that displays a file
3621-
when removing that file from the tree. Default:
3622-
`true`
3629+
• {close_window}? (`boolean`, default: `true`) Close any window that
3630+
displays a file when removing that file from the
3631+
tree.
36233632

36243633
*nvim_tree.Config.Diagnostics*
36253634

@@ -4153,15 +4162,17 @@ Lua module: nvim_tree *nvim-tree-module*
41534162
*nvim_tree.Config.UI*
41544163

41554164
Fields: ~
4156-
{confirm}? (`nvim_tree.Config.UI.Confirm`) Confirmation prompts.
4165+
{confirm}? (`nvim_tree.Config.UI.Confirm`)
4166+
|nvim_tree.Config.UI.Confirm|
41574167

41584168
*nvim_tree.Config.UI.Confirm*
4169+
Confirmation prompts.
41594170

41604171
Fields: ~
4161-
{remove}? (`boolean`) Prompt before removing. Default: `true`
4162-
{trash}? (`boolean`) Prompt before trashing. Default: `true`
4163-
• {default_yes}? (`boolean`) If `true` the prompt will be `\"Y/n\"`,
4164-
otherwise `\"y/N\"`. Default: `false`
4172+
{remove}? (`boolean`, default: `true`) Prompt before removing.
4173+
{trash}? (`boolean`, default: `true`) Prompt before trashing.
4174+
• {default_yes}? (`boolean`, default: `false`) If `true` the prompt
4175+
will be `Y/n`, otherwise `y/N`
41654176

41664177
*nvim_tree.Config.UpdateFocusedFile*
41674178

lua/nvim-tree/_meta/config.lua

Lines changed: 143 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -326,55 +326,168 @@ error("Cannot require a meta file")
326326
--
327327

328328
---@class nvim_tree.Config.UI
329-
---@field confirm? nvim_tree.Config.UI.Confirm Confirmation prompts.
329+
---
330+
---|nvim_tree.Config.UI.Confirm|
331+
---@field confirm? nvim_tree.Config.UI.Confirm
330332

333+
--
334+
-- UI.Confirm
335+
--
336+
337+
---Confirmation prompts.
331338
---@class nvim_tree.Config.UI.Confirm
332-
---@field remove? boolean Prompt before removing. Default: `true`
333-
---@field trash? boolean Prompt before trashing. Default: `true`
334-
---@field default_yes? boolean If `true` the prompt will be `\"Y/n\"`, otherwise `\"y/N\"`. Default: `false`
339+
---
340+
---Prompt before removing.
341+
---(default: `true`)
342+
---@field remove? boolean
343+
---
344+
---Prompt before trashing.
345+
---(default: `true`)
346+
---@field trash? boolean
347+
---
348+
---If `true` the prompt will be `Y/n`, otherwise `y/N`
349+
---(default: `false`)
350+
---@field default_yes? boolean
335351

336352
--
337353
-- Actions
338354
--
339355

340356
---@class nvim_tree.Config.Actions
341-
---@field use_system_clipboard? boolean A boolean value that toggle the use of system clipboard when copy/paste function are invoked. When enabled, copied text will be stored in registers '+' (system), otherwise, it will be stored in '1' and '"'. Default: `true`
342-
---@field change_dir? nvim_tree.Config.Actions.ChangeDir vim |current-directory| behaviour.
343-
---@field expand_all? nvim_tree.Config.Actions.ExpandAll Configuration for |nvim-tree-api.tree.expand_all()| and |nvim-tree-api.node.expand()|
344-
---@field file_popup? nvim_tree.Config.Actions.FilePopup Configuration for file_popup behaviour.
345-
---@field open_file? nvim_tree.Config.Actions.OpenFile Configuration options for opening a file from nvim-tree.
346-
---@field remove_file? nvim_tree.Config.Actions.RemoveFile Configuration options for removing a file from nvim-tree.
347-
357+
---
358+
---A boolean value that toggle the use of system clipboard when copy/paste function are invoked. When enabled, copied text will be stored in registers `+` (system), otherwise, it will be stored in `1` and `"`
359+
---(default: `true`)
360+
---@field use_system_clipboard? boolean
361+
---
362+
---|nvim_tree.Config.Actions.ChangeDir|
363+
---@field change_dir? nvim_tree.Config.Actions.ChangeDir
364+
---
365+
---|nvim_tree.Config.Actions.ExpandAll|
366+
---@field expand_all? nvim_tree.Config.Actions.ExpandAll
367+
---
368+
---|nvim_tree.Config.Actions.FilePopup|
369+
---@field file_popup? nvim_tree.Config.Actions.FilePopup
370+
---
371+
---|nvim_tree.Config.Actions.OpenFile|
372+
---@field open_file? nvim_tree.Config.Actions.OpenFile
373+
---
374+
---|nvim_tree.Config.Actions.RemoveFile|
375+
---@field remove_file? nvim_tree.Config.Actions.RemoveFile
376+
377+
--
378+
-- Actions.ChangeDir
379+
--
380+
381+
--- vim |current-directory| behaviour
348382
---@class nvim_tree.Config.Actions.ChangeDir
349-
---@field enable? boolean Change the working directory when changing directories in the tree. Default: `true`
350-
---@field global? boolean Use `:cd` instead of `:lcd` when changing directories. Default: `false`
351-
---@field restrict_above_cwd? boolean Restrict changing to a directory above the global cwd. Default: `false`
383+
---
384+
---Change the working directory when changing directories in the tree
385+
---(default: `true`)
386+
---@field enable? boolean
387+
---
388+
---Use `:cd` instead of `:lcd` when changing directories.
389+
---(default: `false`)
390+
---@field global? boolean
391+
---
392+
--- Restrict changing to a directory above the global cwd.
393+
---(default: `false`)
394+
---@field restrict_above_cwd? boolean
352395

396+
--
397+
-- Actions.ExpandAll
398+
--
399+
400+
---Configuration for |nvim-tree-api.tree.expand_all()| and |nvim-tree-api.node.expand()|
353401
---@class nvim_tree.Config.Actions.ExpandAll
354-
---@field max_folder_discovery? integer Limit the number of folders being explored when expanding every folders. Avoids hanging neovim when running this action on very large folders. Default: `300`
355-
---@field exclude? string[] A list of directories that should not be expanded automatically. E.g `{ ".git", "target", "build" }` etc. Default: `{}`
402+
---
403+
---Limit the number of folders being explored when expanding every folders. Avoids hanging neovim when running this action on very large folders.
404+
---(default: `300`)
405+
---@field max_folder_discovery? integer
406+
---
407+
---A list of directories that should not be expanded automatically e.g `{ ".git", "target", "build" }`
408+
---(default: `{}`)
409+
---@field exclude? string[]
410+
411+
--
412+
-- Actions.FilePopup
413+
--
356414

415+
---Configuration for file_popup behaviour.
357416
---@class nvim_tree.Config.Actions.FilePopup
358-
---@field open_win_config? table Floating window config for file_popup. See |nvim_open_win| for more details. You shouldn't define `"width"` and `"height"` values here. They will be overridden to fit the file_popup content. Default: `{ col = 1, row = 1, relative = "cursor", border = "shadow", style = "minimal", }`
417+
---
418+
---Floating window config for file_popup. See |nvim_open_win| and |vim.api.keyset.win_config| for more details. You shouldn't define `width` and `height` values here. They will be overridden to fit the file_popup content.
419+
---(default: `{ col = 1, row = 1, relative = "cursor", border = "shadow", style = "minimal", }`)
420+
---@field open_win_config? vim.api.keyset.win_config
359421

360-
---@class nvim_tree.Config.Actions.OpenFile
361-
---@field quit_on_open? boolean Closes the explorer when opening a file. Default: `false`
362-
---@field eject? boolean Prevent a new file opened from within nvim-tree replacing the current nvim-tree window. Default: `true`
363-
---@field resize_window? boolean Resizes the tree when opening a file. Default: `true`
364-
---@field window_picker? nvim_tree.Config.Actions.OpenFile.WindowPicker Window picker configuration.
422+
--
423+
-- Actions.OpenFile
424+
--
365425

426+
---Configuration options for opening a file from nvim-tree.
427+
---@class nvim_tree.Config.Actions.OpenFile
428+
---
429+
---Closes the explorer when opening a file
430+
---(default: `false`)
431+
---@field quit_on_open? boolean
432+
---
433+
---Prevent new opened file from opening in the same window as the tree.
434+
---(default: `true`)
435+
---@field eject? boolean
436+
---
437+
---Resizes the tree when opening a file
438+
---(default: `true`)
439+
---@field resize_window? boolean
440+
---
441+
---|nvim_tree.Config.Actions.OpenFile.WindowPicker|
442+
---@field window_picker? nvim_tree.Config.Actions.OpenFile.WindowPicker
443+
444+
--
445+
-- Actions.OpenFile.WindowPicker
446+
--
447+
448+
---Window picker configuration.
366449
---@class nvim_tree.Config.Actions.OpenFile.WindowPicker
367-
---@field enable? boolean Enable the window picker. If this feature is not enabled, files will open in the current window. Default: `true`
368-
---@field picker? string|fun(): integer Change the way in which to pick a window. Default: `"default"`
369-
---@field chars? string A string of chars used for window picker labels. Default: `"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"`
370-
---@field exclude? nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude Floating window config for window selector.
371-
450+
---
451+
---Enable the feature. If the feature is not enabled, files will open in window from which you last opened the tree, obeying |nvim-tree.actions.open_file.window_picker.exclude|
452+
---(default: `true`)
453+
---@field enable? boolean
454+
---
455+
---Change the default window picker: a string `"default"` or a function. The function should return the window id that will open the node, or `nil` if an invalid window is picked or user cancelled the action. The picker may create a new window.
456+
---(default: `"default"`)
457+
---@field picker? string|fun(): integer
458+
---
459+
---A string of chars used as identifiers by the window picker.
460+
---(default: `"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"`)
461+
---@field chars? string
462+
---
463+
---|nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude|
464+
---@field exclude? nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude
465+
466+
--
467+
-- Actions.OpenFile.WindowPicker.Exclude
468+
--
469+
470+
---Tables of buffer option names mapped to a list of option values. Windows containing matching buffers will not be:
471+
--- - available when using a window picker
472+
--- - selected when not using a window picker
372473
---@class nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude
373-
---@field filetype? string[] A list of filetypes to exclude from window picker. Default: `{ "notify", "lazy", "qf", "diff", "fugitive", "fugitiveblame", }`
374-
---@field buftype? string[] A list of buftypes to exclude from window picker. Default: `{ "nofile", "terminal", "help", }`
474+
---
475+
---(default: `{ "notify", "lazy", "qf", "diff", "fugitive", "fugitiveblame", }`)
476+
---@field filetype? string[]
477+
---
478+
---(default: `{ "nofile", "terminal", "help", }`)
479+
---@field buftype? string[]
480+
481+
--
482+
-- Actions.RemoveFile
483+
--
375484

485+
---Configuration options for removing a file from nvim-tree.
376486
---@class nvim_tree.Config.Actions.RemoveFile
377-
---@field close_window? boolean Close any window that displays a file when removing that file from the tree. Default: `true`
487+
---
488+
---Close any window that displays a file when removing that file from the tree.
489+
---(default: `true`)
490+
---@field close_window? boolean
378491

379492
--
380493
-- View

0 commit comments

Comments
 (0)