ya-tree.nvim

Ya-Tree is sidebar plugin with file browser, Git status, LSP Symbols, LSP Call Hierarchy and buffers panels. Additional panels can easily be created.

Features

• Git integration, including yadm, updates when working tree status changes.
• Directory watching for automatically updating the state of the files and git status panels.
• File search.
• Go to node with path completion.
• Basic file operations.
• LSP Diagnostics.
• LSP Symbols.
• LSP Call Hierarchy.
• One or two sidebars per tabpage.
• One or more panels per sidebar.
• Tabpage working directory aware.

Requirements

• neovim >= 0.8.0
• nui.nvim
• nvim-web-devicons (optional)

Installation with Packer:

use({
  "jgottzen/ya-tree.nvim",
  config = function()
    require("ya-tree").setup()
  end,
  requires = {
    "MunifTanjim/nui.nvim",
    "nvim-tree/nvim-web-devicons", -- optional, used for displaying icons
  },
})

Commands

ya-tree.nvim provides the following commands, which are enabled upon calling ya-tree.setup().

YaTreeOpen

The YaTreeOpen command accepts arguments for how the sidebar should be opened.

By default the topmost left side panel is focused when the sidebar is opened.

no-focus

Keep the current window focused. Must be the first argument.

:YaTreeOpen no-focus

{panel}

A specific panel to focus, and/or it's specific arguments.

The builtin panel types are:

• files: Regular file browser.
• git_status: Git status.
• buffers: List of currently open buffers, including terminals.
• symbols: Lsp symbols of the current buffer.
• call_hierarchy: Lsp call hierarchy.

YaTreeOpen files

files panel arugments

path

Type: key-value pair.

Which path to expand to in the files panel.

:YaTreeOpen files path=./path/to/file.rs
:YaTreeOpen files path=%
:YaTreeOpen files path=./path/to/directory

If the path is located under the current files root, the tree expands to the path, % expands to the path of the current buffer. If the path is not located in the tree the root is changed to the path.

git_status panel arugments

dir

Type: key-value pair.

Which repository to open to in the git_status panel.

:YaTreeOpen git_status dir=/path/to/repo/or/directory/in/repo

call_hierarchy panel arguments

direction

Type: key-value pair.

Values: direction=incoming or direction=outgoing.

Incoming or outgoing calls, the default is incoming.

:YaTreeopen call_hierarchy direction=outgoing

Examples:

• YaTreeOpen Open the sidebar, and focus the first panel.
• YaTreeOpen no-focus Open the sidebar, but keep the current window focused.
• YaTreeOpen files Open the sidebar and focus the files panel.
• YaTreeOpen files path=./path/to/some-where Open the sidebar and focus the files panel and expand and focus on the path ./path/to/some-where.
• YaTreeOpen files path=/path/to/other/directory Open the sidebar and focus the files panel and changes the root to the path /path/to/other/directory.
• YaTreeOpen files path=% Open the sidebar, and expand the files panel to the path of the current buffer.
• YaTreeOpen no-focus git_status Open the sidebar and the git_status panel, but keep the current window focused.
• YaTreeOpen call_hierarchy direction=outgoing Open the sidebar and the call_hierarchy panel, with outgoing calls.

The lua api is:

---@class Yat.OpenWindowArgs
---@field focus? boolean Whether to focus the sidebar.
---@field panel? Yat.Panel.Type The panel to open.
---@field panel_args? table<string, string> The panel specific arguments.

---@param opts? Yat.OpenWindowArgs
require("ya-tree").open(opts)

YaTreeClose

Closes the sidebar.

:YaTreeClose

The lua api is:

require("ya-tree").close()

YaTreeToggle

Toggles the sidebar.

:YaTreeToggle

The lua api is:

require("ya-tree").toggle()

Configuration

The ya-tree.setup() function must be run for YaTree to be properly initialized. It takes an optional table argument, which is fully annotated with EmmyLua.

In the default configuration, only the files panel is enabled, i.e. functioning as regular file-tree plugin. To enable more panels call ya-tree.setup like this:

require("ya-tree").setup({
  sidebar = {
    layout = {
      left = {
        panels = {
          { panel = "files", height = 30 },
          { panel = "symbols", height = 30 },
          { panel = "buffers", show = false },
        },
        width = 40,
      },
      right = {
        panels = {
          { panel = "git_status", show = false },
          { panel = "call_hierarchy", show = false, height = 30 },
        },
        width = 40,
      },
    },
  },
})

and it will open a sidebar on the left side with the files, symbols panels. The buffers panel can be opened with the open_buffers_panel action (b by default) and the right side with the git_status and call_hierarchy panels can be opened by using the open_git_status_panel action (<C-g> by default) or the open_call_hierarchy_panel action (gc by default).

Default Configuration

---@class Yat.Config
---@field close_if_last_window boolean Close the sidebar when it is the last window in the tabpage, default: `false`.
---@field follow_focused_file boolean Update the focused file in the panel on `BufEnter`, default: `false`.
---@field move_cursor_to_name boolean Keep the cursor on the name in panel, default: `false`.
---@field move_buffers_from_sidebar_window boolean Move buffers from the sidebar window to the last used window, default: `true`.
---@field hijack_netrw boolean Replace the `netrw` file explorer, default: `true`.
---@field expand_all_nodes_max_depth integer The maximum depth to expand when expanding nodes, default: 5.
---@field log Yat.Config.Log Logging configuration.
---@field auto_open Yat.Config.AutoOpen Auto-open configuration.
---@field cwd Yat.Config.Cwd Current working directory configuration.
---@field dir_watcher Yat.Config.DirWatcher Directory watching configuration.
---@field search Yat.Config.Search Search configuration.
---@field filters Yat.Config.Filters Filters configuration.
---@field git Yat.Config.Git Git configuration.
---@field diagnostics Yat.Config.Diagnostics Lsp diagnostics configuration.
---@field system_open Yat.Config.SystemOpen Open file with system command configuration.
---@field trash Yat.Config.Trash `trash-cli` configuration.
---@field popups Yat.Config.Popups Popup window configuration.
---@field sidebar Yat.Config.Sidebar Sidebar configuration.
---@field actions Yat.Config.Actions User actions.
---@field panels Yat.Config.Panels Panel configurations.
---@field renderers Yat.Config.Renderers Renderer configurations.
local DEFAULT = {
  close_if_last_window = false,

  follow_focused_file = false,
  move_cursor_to_name = false,
  move_buffers_from_sidebar_window = true,

  hijack_netrw = true,

  expand_all_nodes_max_depth = 5,

  ---@alias Yat.Logger.Level "trace"|"debug"|"info"|"warn"|"error"
  ---@alias Yat.Logger.Namespace "all"|"ya-tree"|"actions"|"events"|"fs"|"lsp"|"nodes"|"panels"|"sidebar"|"ui"|"git"|"job"|string

  ---@class Yat.Config.Log
  ---@field level Yat.Logger.Level The logging level used, default: `"warn"`.
  ---@field to_console boolean Whether to log to the console, default: `false`.
  ---@field to_file boolean Whether to log to the log file, default: `false`.
  ---@field namespaces Yat.Logger.Namespace[] For which namespaces logging is enabled, default: `{ "all" }`.
  log = {
    level = "warn",
    to_console = false,
    to_file = false,
    namespaces = { "all" },
  },

  ---@class Yat.Config.AutoOpen
  ---@field on_setup boolean Automatically open the sidebar when running setup, default: `false`.
  ---@field on_new_tab boolean Automatically open the sidebar when opening a new tabpage, default: `false`.
  ---@field focus_sidebar boolean Whether to focus the sidebar when automatically opened, default: `false`.
  auto_open = {
    on_setup = false,
    on_new_tab = false,
    focus_sidebar = false,
  },

  ---@class Yat.Config.Cwd
  ---@field follow boolean Update the Files panel root directory on `DirChanged`, default: `false`.
  ---@field update_from_panel boolean Update the *tabpage* cwd when changing root directory in a panel, default: `false`.
  cwd = {
    follow = false,
    update_from_panel = false,
  },

  ---@class Yat.Config.DirWatcher
  ---@field enable boolean Whether directory watching is enabled, default: `true`.
  ---@field exclude string[] The directory names to exclude from watching, `".git"` directories are always excluded.
  dir_watcher = {
    enable = true,
    exclude = {},
  },

  ---@class Yat.Config.Search
  ---@field max_results integer Max number of search results, only `fd` supports it, setting to 0 will disable it, default: `200`.
  ---@field cmd? string Override the search command to use, default: `nil`.
  ---@field args? string[]|fun(cmd: string, term: string, path:string, config: Yat.Config):string[] Override the search command arguments to use, default: `nil`.
  search = {
    max_results = 200,
    cmd = nil,
    args = nil,
  },

  ---@class Yat.Config.Filters
  ---@field enable boolean If filters are enabled, toggleable, default: `true`.
  ---@field dotfiles boolean If dotfiles should be hidden, default: `true`.
  ---@field custom string[] Custom file/directory names to hide, default: `{}`.
  filters = {
    enable = true,
    dotfiles = true,
    custom = {},
  },

  ---@class Yat.Config.Git
  ---@field enable boolean If git should be enabled, default: `true`.
  ---@field all_untracked boolean If `git status` checks should include all untracked files: default: `false`.
  ---@field show_ignored boolean Whether to show git ignored files in panels, toggleable, default: `true`.
  ---@field watch_git_dir boolean Whether to watch the repository `.git` directory for changes, using `fs_poll`, default: `true`.
  ---@field watch_git_dir_interval integer Interval for polling, in milliseconds, default: `1000`.
  ---@field yadm Yat.Config.Git.Yadm `yadm` configuration.
  git = {
    enable = true,
    all_untracked = false,
    show_ignored = true,
    watch_git_dir = true,
    watch_git_dir_interval = 1000,

    ---@class Yat.Config.Git.Yadm
    ---@field enable boolean Whether yadm is enabled, requires git to be enabled, default: `false`.
    yadm = {
      enable = false,
    },
  },

  ---@class Yat.Config.Diagnostics
  ---@field enable boolean Show lsp diagnostics in panels, default: `true`.
  ---@field debounce_time integer Debounce time in ms, for how often `DiagnosticChanged` is processed, default: `300`.
  ---@field propagate_to_parents boolean If the diagnostic status should be propagated to parents, default: `true`.
  diagnostics = {
    enable = true,
    debounce_time = 300,
    propagate_to_parents = true,
  },

  ---@class Yat.Config.SystemOpen
  ---@field cmd? string The system open command, if unspecified the detected OS determines the default, Linux: `xdg-open`, OS X: `open`, Windows: `cmd`.
  ---@field args string[] Any arguments for the system open command, default: `{}` for Linux and OS X, `{"/c", "start"}` for Windows.
  system_open = {
    cmd = nil,
    args = {},
  },

  ---@class Yat.Config.Trash
  ---@field enable boolean Whether to enable trashing (`trash-cli must be installed`), default: `true`.
  ---@field require_confirm boolean Confirm before trashing, default: `false`.
  trash = {
    enable = true,
    require_confirm = false,
  },

  ---@class Yat.Config.Popups
  ---@field border string|string[] The border type for floating windows, default: `"rounded"`.
  popups = {
    border = "rounded",
  },

  ---@alias Yat.Panel.Type "files"|"git_status"|"symbols"|"call_hierarchy"|"buffers"|string

  ---@class Yat.Config.Sidebar
  ---@field layout Yat.Config.Sidebar.Layout The layout configuration for the sidebar.
  sidebar = {
    ---@class Yat.Config.Sidebar.PanelLayout.Panel
    ---@field panel Yat.Panel.Type The panel type.
    ---@field show? boolean Whether the panel is shown, a `nil` value is treated as `true`, default: `true`.
    ---@field height? integer|string The height of the panel, in rows or percent.

    ---@class Yat.Config.Sidebar.PanelLayout
    ---@field panels Yat.Config.Sidebar.PanelLayout.Panel[] Which panels to show on this side.
    ---@field width integer The width of the panels.

    ---@class Yat.Config.Sidebar.Layout
    ---@field left Yat.Config.Sidebar.PanelLayout The panels on the left side.
    ---@field right Yat.Config.Sidebar.PanelLayout The panels on the right side.
    layout = {
      left = {
        panels = { { panel = "files", height = 30 } },
        width = 40,
      },
      right = {
        panels = {},
        width = 40,
      },
    },
  },

  ---@alias Yat.Action.TreePanelFn async fun(panel: Yat.Panel.Tree, node: Yat.Node)

  ---@alias Yat.Actions.Mode "n"|"v"

  ---@class Yat.Config.Action
  ---@field fn Yat.Action.TreePanelFn The function implementing the action.
  ---@field desc string The description of the action.
  ---@field modes Yat.Actions.Mode[] Which modes the action is available in.
  ---@field node_independent boolean Whether the action can be called without a `Yat.Node`, e.g. the `"open_help"` action.

  ---@class Yat.Config.Actions : { [string]: Yat.Config.Action }
  actions = {},

  ---@class Yat.Config.Panels.Mappings
  ---@field disable_defaults boolean Whether to disable all default mappings, default: `false`.
  ---@field list table<string, Yat.Actions.Name|string> Map of key mappings, an empty string, `""`, disables the mapping.

  ---@class Yat.Config.Panels.TreeRenderer
  ---@field name Yat.Ui.Renderer.Name The name of the renderer.
  ---@field override Yat.Config.BaseRendererConfig The renderer specific configuration.

  ---@class Yat.Config.Panels.Panel
  ---@field title string The name of panel.
  ---@field icon string The icon for the panel.
  ---@field mappings Yat.Config.Panels.Mappings The panel specific mappings.

  ---@class Yat.Config.Panels
  ---@field files Yat.Config.Panels.Files Files panel configuration.
  ---@field symbols Yat.Config.Panels.Symbols Lsp Symbols panel configuration.
  ---@field call_hierarchy Yat.Config.Panels.CallHierarchy Call hierarchy panel configuration.
  ---@field git_status Yat.Config.Panels.GitStatus Git Status panel configuration.
  ---@field buffers Yat.Config.Panels.Buffers Buffers panel configuration.
  ---@field [Yat.Panel.Type] Yat.Config.Panels.Panel Custom panel configuration.
  panels = {
    ---@class Yat.Config.Panels.Files
    ---@field title string The name of the panel, default: `"Files"`.
    ---@field icon string The icon for the panel, default: `""`.
    ---@field completion Yat.Config.Panels.Files.Completion Completion configuration.
    ---@field sorting Yat.Config.Panels.Files.Sorting Sorting configuration.
    ---@field mappings Yat.Config.Panels.Files.Mappings Panel specific mappings.
    ---@field renderers Yat.Config.Panels.Files.Renderers Panel specific renderers.
    files = {
      title = "Files",
      icon = "",

      ---@class Yat.Config.Panels.Files.Completion
      ---@field on "root"|"node" Whether to complete on the panel root directory or the current node, ignored if `setup` is set, default: `"root"`.
      ---@field setup? fun(panel: Yat.Panel.Files, node: Yat.Node): string function for setting up completion, the returned string will be set as `completefunc`, default: `nil`.
      completion = {
        on = "root",
        setup = nil,
      },

      ---@alias Yat.Node.Filesystem.SortBy "name"|"type"|"extension"

      ---@class Yat.Config.Panels.Files.Sorting
      ---@field directories_first boolean Whether to sort directories first, default: `true`.
      ---@field case_sensitive boolean Whether to use case sensitive sort, default: `false`.
      ---@field sort_by Yat.Node.Filesystem.SortBy|fun(a: Yat.Node.Filesystem, b: Yat.Node.Filesystem):boolean What to sort by, or a user specified function, default: `"name"`.
      sorting = {
        directories_first = true,
        case_sensitive = false,
        sort_by = "name",
      },

      ---@class Yat.Config.Panels.Files.Mappings
      ---@field disable_defaults boolean Whether to disable all default mappings, default: `false`.
      ---@field list table<string, Yat.Panel.Files.SupportedActions|string> Map of key mappings, an empty string, `""`, disables the mapping.
      mappings = {
        disable_defaults = false,
        list = {
          ["q"] = "close_sidebar",
          ["?"] = "open_help",
          ["gs"] = "open_symbols_panel",
          ["<C-g>"] = "open_git_status_panel",
          ["b"] = "open_buffers_panel",
          ["gc"] = "open_call_hierarchy_panel",
          ["gx"] = "system_open",
          ["<C-i>"] = "show_node_info",
          ["<CR>"] = "open",
          ["o"] = "open",
          ["<2-LeftMouse>"] = "open",
          ["<C-v>"] = "vsplit",
          ["<C-s>"] = "split",
          ["<C-t>"] = "tabnew",
          ["<Tab>"] = "preview",
          ["<C-Tab>"] = "preview_and_focus",
          ["y"] = "copy_name_to_clipboard",
          ["Y"] = "copy_root_relative_path_to_clipboard",
          ["gy"] = "copy_absolute_path_to_clipboard",
          ["<BS>"] = "close_node",
          ["Z"] = "close_all_nodes",
          ["z"] = "close_all_child_nodes",
          ["E"] = "expand_all_nodes",
          ["e"] = "expand_all_child_nodes",
          ["R"] = "refresh_panel",
          ["P"] = "focus_parent",
          ["<"] = "focus_prev_sibling",
          [">"] = "focus_next_sibling",
          ["K"] = "focus_first_sibling",
          ["J"] = "focus_last_sibling",
          ["a"] = "add",
          ["r"] = "rename",
          ["d"] = "delete",
          ["D"] = "trash",
          ["c"] = "copy_node",
          ["x"] = "cut_node",
          ["p"] = "paste_nodes",
          ["<C-c>"] = "clear_clipboard",
          ["<2-RightMouse>"] = "cd_to",
          ["<C-]>"] = "cd_to",
          ["."] = "cd_to",
          ["-"] = "cd_up",
          ["I"] = "toggle_ignored",
          ["H"] = "toggle_filter",
          ["S"] = "search_for_node_in_panel",
          ["/"] = "search_interactively",
          ["f"] = "search_once",
          ["<C-x>"] = "close_search",
          ["gn"] = "goto_node_in_files_panel",
          ["ga"] = "git_stage",
          ["gu"] = "git_unstage",
          ["gr"] = "git_revert",
          ["<C-r>"] = "check_node_for_git",
          ["[c"] = "focus_prev_git_item",
          ["]c"] = "focus_next_git_item",
          ["[e"] = "focus_prev_diagnostic_item",
          ["]e"] = "focus_next_diagnostic_item",
        },
      },

      ---@alias Yat.Config.Panels.Files.DirectoryRendererName "indentation"|"icon"|"name"|"repository"|"symlink_target"|"git_status"|"diagnostics"|"clipboard"|string
      ---@alias Yat.Config.Panels.Files.FileRendererName "indentation"|"icon"|"name"|"symlink_target"|"modified"|"git_status"|"diagnostics"|"clipboard"|string

      ---@class Yat.Config.Panels.Files.Renderers
      ---@field directory { name : Yat.Config.Panels.Files.DirectoryRendererName, override : Yat.Config.BaseRendererConfig }[]
      ---@field file { name : Yat.Config.Panels.Files.FileRendererName, override : Yat.Config.BaseRendererConfig }[]
      renderers = {
        directory = {
          { name = "indentation" },
          { name = "icon" },
          { name = "name" },
          { name = "repository", override = { show_status = false } },
          { name = "symlink_target" },
          { name = "git_status" },
          { name = "diagnostics" },
          { name = "clipboard" },
        },
        file = {
          { name = "indentation" },
          { name = "icon" },
          { name = "name", override = { use_git_status_colors = true } },
          { name = "symlink_target" },
          { name = "modified" },
          { name = "git_status" },
          { name = "diagnostics" },
          { name = "clipboard" },
        },
      },
    },

    ---@class Yat.Config.Panels.GitStatus
    ---@field title string The name of the panel, default: `"Git"`.
    ---@field icon string The icon for the panel, default: `""`.
    ---@field completion Yat.Config.Panels.GitStatus.Completion Completion configuration.
    ---@field mappings Yat.Config.Panels.GitStatus.Mappings Panel specific mappings.
    ---@field renderers Yat.Config.Panels.GitStatus.Renderers Panel specific renderers.
    git_status = {
      title = "Git Status",
      icon = "",

      ---@class Yat.Config.Panels.GitStatus.Completion
      ---@field on "root"|"node" Whether to complete on the panel root directory or the current node, ignored if `setup` is set, default: `"root"`.
      completion = {
        on = "root",
      },

      ---@class Yat.Config.Panels.GitStatus.Mappings
      ---@field disable_defaults boolean Whether to disable all default mappings, default: `false`.
      ---@field list table<string, Yat.Panel.GitStatus.SupportedActions|string> Map of key mappings, an empty string, `""`, disables the mapping.
      mappings = {
        disable_defaults = false,
        list = {
          ["q"] = "close_sidebar",
          ["<C-x>"] = "close_panel",
          ["?"] = "open_help",
          ["gs"] = "open_symbols_panel",
          ["b"] = "open_buffers_panel",
          ["gc"] = "open_call_hierarchy_panel",
          ["gx"] = "system_open",
          ["<C-i>"] = "show_node_info",
          ["<CR>"] = "open",
          ["o"] = "open",
          ["<2-LeftMouse>"] = "open",
          ["<C-v>"] = "vsplit",
          ["<C-s>"] = "split",
          ["<C-t>"] = "tabnew",
          ["<Tab>"] = "preview",
          ["<C-Tab>"] = "preview_and_focus",
          ["y"] = "copy_name_to_clipboard",
          ["Y"] = "copy_root_relative_path_to_clipboard",
          ["gy"] = "copy_absolute_path_to_clipboard",
          ["<BS>"] = "close_node",
          ["Z"] = "close_all_nodes",
          ["z"] = "close_all_child_nodes",
          ["E"] = "expand_all_nodes",
          ["e"] = "expand_all_child_nodes",
          ["R"] = "refresh_panel",
          ["P"] = "focus_parent",
          ["<"] = "focus_prev_sibling",
          [">"] = "focus_next_sibling",
          ["K"] = "focus_first_sibling",
          ["J"] = "focus_last_sibling",
          ["<C-]>"] = "cd_to",
          ["."] = "cd_to",
          ["I"] = "toggle_ignored",
          ["H"] = "toggle_filter",
          ["S"] = "search_for_node_in_panel",
          ["gn"] = "goto_node_in_files_panel",
          ["gd"] = "open_repository",
          ["ga"] = "git_stage",
          ["gu"] = "git_unstage",
          ["gr"] = "git_revert",
          ["r"] = "rename",
          ["[c"] = "focus_prev_git_item",
          ["]c"] = "focus_next_git_item",
          ["[e"] = "focus_prev_diagnostic_item",
          ["]e"] = "focus_next_diagnostic_item",
        },
      },

      ---@alias Yat.Config.Panels.GitStatus.DirectoryRendererName "indentation"|"icon"|"name"|"repository"|"symlink_target"|"git_status"|"diagnostics"|string
      ---@alias Yat.Config.Panels.GitStatus.FileRendererName "indentation"|"icon"|"name"|"symlink_target"|"modified"|"git_status"|"diagnostics"|string

      ---@class Yat.Config.Panels.GitStatus.Renderers
      ---@field directory { name : Yat.Config.Panels.GitStatus.DirectoryRendererName, override : Yat.Config.BaseRendererConfig }[]
      ---@field file { name : Yat.Config.Panels.GitStatus.FileRendererName, override : Yat.Config.BaseRendererConfig }[]
      renderers = {
        directory = {
          { name = "indentation" },
          { name = "icon" },
          { name = "name" },
          { name = "repository" },
          { name = "symlink_target" },
          { name = "git_status" },
          { name = "diagnostics" },
        },
        file = {
          { name = "indentation" },
          { name = "icon" },
          { name = "name", override = { use_git_status_colors = true } },
          { name = "symlink_target" },
          { name = "modified" },
          { name = "git_status" },
          { name = "diagnostics" },
        },
      },
    },

    ---@class Yat.Config.Panels.Symbols
    ---@field title string The name of the panel, default: `"Lsp Symbols"`.
    ---@field icon string The icon for the panel, default" `""`.
    ---@field completion Yat.Config.Panels.Symbols.Completion Completion configuration.
    ---@field scroll_buffer_to_symbol boolean Whether to scroll the file to the current symbol, default: `true`.
    ---@field mappings Yat.Config.Panels.Symbols.Mappings Panel specific mappings.
    ---@field renderers Yat.Config.Panels.Symbols.Renderers Panel specific renderers.
    symbols = {
      title = "Lsp Symbols",
      icon = "",
      scroll_buffer_to_symbol = true,

      ---@class Yat.Config.Panels.Symbols.Completion
      ---@field on "root"|"node" Whether to complete on the panel root node or the current node, ignored if `setup` is set, default: `"root"`.
      completion = {
        on = "root",
      },

      ---@class Yat.Config.Panels.Symbols.Mappings
      ---@field disable_defaults boolean Whether to disable all default mappings, default: `false`.
      ---@field list table<string, Yat.Panel.Symbols.SupportedActions|string> Map of key mappings, an empty string, `""`, disables the mapping.
      mappings = {
        disable_defaults = false,
        list = {
          ["q"] = "close_sidebar",
          ["<C-x>"] = "close_panel",
          ["?"] = "open_help",
          ["<C-g>"] = "open_git_status_panel",
          ["b"] = "open_buffers_panel",
          ["gc"] = "open_call_hierarchy_panel",
          ["<CR>"] = "open",
          ["o"] = "open",
          ["<2-LeftMouse>"] = "open",
          ["<C-v>"] = "vsplit",
          ["<C-s>"] = "split",
          ["<C-t>"] = "tabnew",
          ["<Tab>"] = "preview",
          ["<C-Tab>"] = "preview_and_focus",
          ["y"] = "copy_name_to_clipboard",
          ["Y"] = "copy_root_relative_path_to_clipboard",
          ["gy"] = "copy_absolute_path_to_clipboard",
          ["<BS>"] = "close_node",
          ["Z"] = "close_all_nodes",
          ["z"] = "close_all_child_nodes",
          ["E"] = "expand_all_nodes",
          ["e"] = "expand_all_child_nodes",
          ["R"] = "refresh_panel",
          ["P"] = "focus_parent",
          ["<"] = "focus_prev_sibling",
          [">"] = "focus_next_sibling",
          ["K"] = "focus_first_sibling",
          ["J"] = "focus_last_sibling",
          ["S"] = "search_for_node_in_panel",
          ["[e"] = "focus_prev_diagnostic_item",
          ["]e"] = "focus_next_diagnostic_item",
        },
      },

      ---@alias Yat.Config.Panels.Symbols.ContainerRendererName "indentation"|"icon"|"name"|"modified"|"symbol_details"|"diagnostics"|string
      ---@alias Yat.Config.Panels.Symbols.LeafRendererName "indentation"|"icon"|"name"|"symbol_details"|"diagnostics"|string

      ---@class Yat.Config.Panels.Symbols.Renderers
      ---@field container { name : Yat.Config.Panels.Symbols.ContainerRendererName, override : Yat.Config.BaseRendererConfig }[]
      ---@field leaf { name : Yat.Config.Panels.Symbols.LeafRendererName, override : Yat.Config.BaseRendererConfig }[]
      renderers = {
        container = {
          { name = "indentation" },
          { name = "icon" },
          { name = "name" },
          { name = "symbol_details" },
          { name = "diagnostics" },
        },
        leaf = {
          { name = "indentation" },
          { name = "icon" },
          { name = "name" },
          { name = "symbol_details" },
          { name = "diagnostics" },
        },
      },
    },

    ---@class Yat.Config.Panels.CallHierarchy
    ---@field title string The name of the panel, default: `"Call Hierarchy"`.
    ---@field icon string The icon for the panel, default" `""`.
    ---@field completion Yat.Config.Panels.CallHierarchy.Completion Completion configuration.
    ---@field mappings Yat.Config.Panels.CallHierarchy.Mappings Panel specific mappings.
    ---@field renderers Yat.Config.Panels.CallHierarchy.Renderers Panel specific renderers.
    call_hierarchy = {
      title = "Call Hierarchy",
      icon = "",

      ---@class Yat.Config.Panels.CallHierarchy.Completion
      ---@field on "root"|"node" Whether to complete on the panel root node or the current node, ignored if `setup` is set, default: `"root"`.
      completion = {
        on = "root",
      },

      ---@class Yat.Config.Panels.CallHierarchy.Mappings
      ---@field disable_defaults boolean Whether to disable all default mappings, default: `false`.
      ---@field list table<string, Yat.Panel.CallHierarchy.SupportedActions|string> Map of key mappings, an empty string, `""`, disables the mapping.
      mappings = {
        disable_defaults = false,
        list = {
          ["q"] = "close_sidebar",
          ["<C-x>"] = "close_panel",
          ["?"] = "open_help",
          ["gs"] = "open_symbols_panel",
          ["<C-g>"] = "open_git_status_panel",
          ["b"] = "open_buffers_panel",
          ["<CR>"] = "open",
          ["o"] = "open",
          ["<2-LeftMouse>"] = "open",
          ["<C-v>"] = "vsplit",
          ["<C-s>"] = "split",
          ["<C-t>"] = "tabnew",
          ["<Tab>"] = "preview",
          ["<C-Tab>"] = "preview_and_focus",
          ["y"] = "copy_name_to_clipboard",
          ["Y"] = "copy_root_relative_path_to_clipboard",
          ["gy"] = "copy_absolute_path_to_clipboard",
          ["<BS>"] = "close_node",
          ["Z"] = "close_all_nodes",
          ["z"] = "close_all_child_nodes",
          ["E"] = "expand_all_nodes",
          ["e"] = "expand_all_child_nodes",
          ["R"] = "refresh_panel",
          ["P"] = "focus_parent",
          ["<"] = "focus_prev_sibling",
          [">"] = "focus_next_sibling",
          ["K"] = "focus_first_sibling",
          ["J"] = "focus_last_sibling",
          ["S"] = "search_for_node_in_panel",
          ["gt"] = "toggle_call_direction",
          ["gc"] = "create_call_hierarchy_from_buffer_position",
        },
      },

      ---@alias Yat.Config.Panels.CallHierarchy.ContainerRendererName "indentation"|"icon"|"name"|"symbol_details"|string
      ---@alias Yat.Config.Panels.CallHierarchy.LeafRendererName "indentation"|"icon"|"name"|"symbol_details"|string

      ---@class Yat.Config.Panels.CallHierarchy.Renderers
      ---@field container { name : Yat.Config.Panels.CallHierarchy.ContainerRendererName, override : Yat.Config.BaseRendererConfig }[]
      ---@field leaf { name : Yat.Config.Panels.CallHierarchy.LeafRendererName, override : Yat.Config.BaseRendererConfig }[]
      renderers = {
        container = {
          { name = "indentation" },
          { name = "icon" },
          { name = "name" },
          { name = "symbol_details" },
        },
        leaf = {
          { name = "indentation" },
          { name = "icon" },
          { name = "name" },
          { name = "symbol_details" },
        },
      },
    },

    ---@class Yat.Config.Panels.Buffers
    ---@field title string The name of the panel, default: `"Buffers"`.
    ---@field icon string The icon for the panel, default: `""`.
    ---@field mappings Yat.Config.Panels.Buffers.Mappings Panel specific mappings.
    ---@field renderers Yat.Config.Panels.Buffers.Renderers Panel specific renderers.
    buffers = {
      title = "Buffers",
      icon = "",

      ---@class Yat.Config.Panels.Buffers.Mappings
      ---@field disable_defaults boolean Whether to disable all default mappings, default: `false`.
      ---@field list table<string, Yat.Panel.Buffers.SupportedActions|string> Map of key mappings, an empty string, `""`, disables the mapping.
      mappings = {
        disable_defaults = false,
        list = {
          ["q"] = "close_sidebar",
          ["<C-x>"] = "close_panel",
          ["?"] = "open_help",
          ["gs"] = "open_symbols_panel",
          ["<C-g>"] = "open_git_status_panel",
          ["gc"] = "open_call_hierarchy_panel",
          ["gx"] = "system_open",
          ["<C-i>"] = "show_node_info",
          ["<CR>"] = "open",
          ["o"] = "open",
          ["<2-LeftMouse>"] = "open",
          ["<C-v>"] = "vsplit",
          ["<C-s>"] = "split",
          ["<C-t>"] = "tabnew",
          ["<Tab>"] = "preview",
          ["<C-Tab>"] = "preview_and_focus",
          ["y"] = "copy_name_to_clipboard",
          ["Y"] = "copy_root_relative_path_to_clipboard",
          ["gy"] = "copy_absolute_path_to_clipboard",
          ["<BS>"] = "close_node",
          ["Z"] = "close_all_nodes",
          ["z"] = "close_all_child_nodes",
          ["E"] = "expand_all_nodes",
          ["e"] = "expand_all_child_nodes",
          ["R"] = "refresh_panel",
          ["P"] = "focus_parent",
          ["<"] = "focus_prev_sibling",
          [">"] = "focus_next_sibling",
          ["K"] = "focus_first_sibling",
          ["J"] = "focus_last_sibling",
          ["<C-]>"] = "cd_to",
          ["."] = "cd_to",
          ["I"] = "toggle_ignored",
          ["H"] = "toggle_filter",
          ["S"] = "search_for_node_in_panel",
          ["gn"] = "goto_node_in_files_panel",
          ["ga"] = "git_stage",
          ["gu"] = "git_unstage",
          ["gr"] = "git_revert",
          ["<C-r>"] = "check_node_for_git",
          ["[c"] = "focus_prev_git_item",
          ["]c"] = "focus_next_git_item",
          ["[e"] = "focus_prev_diagnostic_item",
          ["]e"] = "focus_next_diagnostic_item",
        },
      },

      ---@alias Yat.Config.Panels.Buffers.DirectoryRendererName "indentation"|"icon"|"name"|"repository"|"symlink_target"|"git_status"|"diagnostics"|string
      ---@alias Yat.Config.Panels.Buffers.FileRendererName "indentation"|"icon"|"name"|"symlink_target"|"modified"|"git_status"|"diagnostics"|"buffer_info"|string

      ---@class Yat.Config.Panels.Buffers.Renderers
      ---@field directory { name : Yat.Config.Panels.Buffers.DirectoryRendererName, override : Yat.Config.BaseRendererConfig }[]
      ---@field file { name : Yat.Config.Panels.Buffers.FileRendererName, override : Yat.Config.BaseRendererConfig }[]
      renderers = {
        directory = {
          { name = "indentation" },
          { name = "icon" },
          { name = "name" },
          { name = "symlink_target" },
          { name = "git_status" },
          { name = "diagnostics" },
        },
        file = {
          { name = "indentation" },
          { name = "icon" },
          { name = "name", override = { use_git_status_colors = true } },
          { name = "symlink_target" },
          { name = "modified" },
          { name = "git_status" },
          { name = "diagnostics" },
          { name = "buffer_info" },
        },
      },
    },
  },

  ---@alias Yat.Ui.Renderer.Name "indentation"|"icon"|"name"|"modified"|"repository"|"symlink_target"|"git_status"|"diagnostics"|"buffer_info"|"clipboard"|"symbol_details"|string

  ---@class Yat.Config.BaseRendererConfig : { [string]: any }
  ---@field padding string The padding to use to the left of the renderer.

  ---@class Yat.Config.Renderers : { [string] : Yat.Ui.Renderer.Renderer }
  ---@field builtin Yat.Config.Renderers.Builtin Built-in renderers configuration.
  renderers = {
    ---@class Yat.Config.Renderers.Builtin
    ---@field indentation Yat.Config.Renderers.Builtin.Indentation Indentation rendering configuration.
    ---@field icon Yat.Config.Renderers.Builtin.Icon Icon rendering configuration.
    ---@field name Yat.Config.Renderers.Builtin.Name File and directory name rendering configuration.
    ---@field modified Yat.Config.Renderers.Builtin.Modified Modified file rendering configurations.
    ---@field repository Yat.Config.Renderers.Builtin.Repository Repository rendering configuration.
    ---@field symlink_target Yat.Config.Renderers.Builtin.SymlinkTarget Symbolic link rendering configuration.
    ---@field git_status Yat.Config.Renderers.Builtin.GitStatus Git status rendering configuration.
    ---@field diagnostics Yat.Config.Renderers.Builtin.Diagnostics Lsp diagnostics rendering configuration.
    ---@field buffer_info Yat.Config.Renderers.Builtin.BufferInfo Buffer info rendering configuration.
    ---@field clipboard Yat.Config.Renderers.Builtin.Clipboard Clipboard rendering configuration.
    ---@field symbol_details Yat.Config.Renderers.Builtin.SymbolDetails Symbol details rendering configuration.
    builtin = {
      ---@class Yat.Config.Renderers.Builtin.Indentation : Yat.Config.BaseRendererConfig
      ---@field padding string The padding to use to the left of the renderer, default: `""`.
      ---@field use_indent_marker boolean Whether to show indent markers, default: `false`.
      ---@field indent_marker string The icon for the indentation marker, default: `"│"`.
      ---@field last_indent_marker string The icon for the last indentation marker, default: `"└"`.
      ---@field use_expander_marker boolean Whether to show expanded and collapsed markers, default: `false`.
      ---@field expanded_marker string The icon for expanded directories, default: `""`.
      ---@field collapsed_marker string The icon for collapsed directories, default: `""`.
      indentation = {
        padding = "",
        use_indent_marker = false,
        indent_marker = "│",
        last_indent_marker = "└",
        use_expander_marker = false,
        expanded_marker = "",
        collapsed_marker = "",
      },

      ---@class Yat.Config.Renderers.Builtin.Icon : Yat.Config.BaseRendererConfig
      ---@field padding string The padding to use to the left of the renderer, default: `""`.
      ---@field default_container string The default icon for containers, default: `"󰙅"`.
      ---@field default_leaf string The default icon for leafs, default: `""`.
      ---@field directory Yat.Config.Renderers.Icon.Directory Directory icon rendering configuration.
      ---@field file Yat.Config.Renderers.Icon.File File icon rendering configuration.
      icon = {
        padding = "",
        default_container = "󰙅",
        default_leaf = "",

        ---@class Yat.Config.Renderers.Icon.Directory
        ---@field default string The icon for closed directories, default: `""`.
        ---@field expanded string The icon for opened directories, default: `""`.
        ---@field empty string The icon for closed empty directories, default: `""`.
        ---@field empty_expanded string The icon for opened empty directories, default: `""`.
        ---@field symlink string The icon for closed symbolic link directories, default: `""`.
        ---@field symlink_expanded string The icon for opened symbolic link directories, default: `""`.
        ---@field custom table<string, string> Map of directory names to custom icons, default: `{}`.
        directory = {
          default = "",
          expanded = "",
          empty = "",
          empty_expanded = "",
          symlink = "",
          symlink_expanded = "",
          custom = {},
        },

        ---@class Yat.Config.Renderers.Icon.File
        ---@field default string The default icon for files, default: `""`.
        ---@field symlink string The icon for symbolic link files, default: `""`.
        ---@field fifo string The icon for fifo files, default: `"|"`.
        ---@field socket string The icon for socket files, default: `""`.
        ---@field char string The icon for character device files, default: `""`.
        ---@field block string The icon for block device files, default: `""`.
        file = {
          default = "",
          symlink = "",
          fifo = "|",
          socket = "",
          char = "",
          block = "",
        },
      },

      ---@class Yat.Config.Renderers.Builtin.Name : Yat.Config.BaseRendererConfig
      ---@field padding string The padding to use to the left of the renderer, default: `" "`.
      ---@field root_folder_format string The root folder format as per `fnamemodify`, default: `":~"`.
      ---@field trailing_slash boolean Whether to show a trailing OS directory separator after directory names, default: `false`.
      ---@field use_git_status_colors boolean Whether to color the name with the git status color, default: `false`.
      name = {
        padding = " ",
        root_folder_format = ":~",
        trailing_slash = false,
        use_git_status_colors = false,
      },

      ---@class Yat.Config.Renderers.Builtin.Modified : Yat.Config.BaseRendererConfig
      ---@field padding string The padding to use to the left of the renderer, default: `" "`.
      ---@field icon string The icon for modified files, default: `"[+]"`.
      modified = {
        padding = " ",
        icon = "[+]",
      },

      ---@class Yat.Config.Renderers.Builtin.Repository : Yat.Config.BaseRendererConfig
      ---@field padding string The padding to use to the left of the renderer, default: `" "`.
      ---@field show_status boolean Whether to show repository status on the repository toplevel directory, default: `true`.
      ---@field icons Yat.Config.Renderers.Repository.Icons Repository icons, setting an icon to an empty string will disabled that particular status information.
      repository = {
        padding = " ",
        show_status = true,

        ---@class Yat.Config.Renderers.Repository.Icons
        ---@field behind string The icon for the behind count, default: `"⇣"`.
        ---@field ahead string The icon for the ahead count, default: `"⇡"`.
        ---@field stashed string The icon for the stashed count, default: `"*"`.
        ---@field unmerged string The icon for the unmerged count, default: `"~"`.
        ---@field staged string The icon for the staged count, default: `"+"`.
        ---@field unstaged string The icon for the unstaged count, default: `"!"`.
        ---@field untracked string The icon for the untracked count, default: `"?"`.
        ---@field remote Yat.Config.Renderers.Repository.Icons.Remote Repository remote host icons.
        icons = {
          behind = "⇣",
          ahead = "⇡",
          stashed = "*",
          unmerged = "~",
          staged = "+",
          unstaged = "!",
          untracked = "?",

          ---@class Yat.Config.Renderers.Repository.Icons.Remote : { [string]: string }
          ---@field default string The default icon for marking the git toplevel directory, default: `""`.
          remote = {
            default = "",
            ["://github.com/"] = "",
            ["://gitlab.com/"] = "",
          },
        },
      },

      ---@class Yat.Config.Renderers.Builtin.SymlinkTarget : Yat.Config.BaseRendererConfig
      ---@field padding string The padding to use to the left of the renderer, default: `" "`.
      ---@field arrow_icon string The icon to use before the symbolic link target, default: `"➛"`.
      symlink_target = {
        padding = " ",
        arrow_icon = "➛",
      },

      ---@class Yat.Config.Renderers.Builtin.GitStatus : Yat.Config.BaseRendererConfig
      ---@field padding string The padding to use to the left of the renderer, default: `" "`.
      ---@field icons Yat.Config.Renderers.GitStatus.Icons Git status icon configuration.
      git_status = {
        padding = " ",

        ---@class Yat.Config.Renderers.GitStatus.Icons
        ---@field staged string The icon for staged changes, default: `""`.
        ---@field type_changed string The icon for a type-changed file, default: `""`.
        ---@field added string The icon for an added file, default: `"✚"`.
        ---@field deleted string The icon for a deleted file, default: `"✖"`.
        ---@field renamed string The icon for a renamed file, default: `"➜"`.
        ---@field copied string The icon for a copied file, default: `""`.
        ---@field modified string The icon for modified changes, default: `""`.
        ---@field unmerged string The icon for unmerged changes, default: `""`.
        ---@field ignored string The icon for an ignored file, default: `""`.
        ---@field untracked string The icon for an untracked file, default: `, default: `""`.
        ---@field merge Yat.Config.Renderers.GitStatus.Icons.Merge Git status icons for merge information.
        icons = {
          staged = "",
          type_changed = "",
          added = "✚",
          deleted = "✖",
          renamed = "➜",
          copied = "",
          modified = "",
          unmerged = "",
          ignored = "",
          untracked = "",

          ---@class Yat.Config.Renderers.GitStatus.Icons.Merge
          ---@field us string The icon for added/deleted/modified by `us`, default: `"󱦰"`.
          ---@field them string The icon for added/deleted/modified by `them`, default: `"󱦱"`.
          ---@field both string The icon for added/deleted/modified by `both`, default: `""`.
          merge = {
            us = "󱦰",
            them = "󱦱",
            both = "",
          },
        },
      },

      ---@class Yat.Config.Renderers.Builtin.Diagnostics : Yat.Config.BaseRendererConfig
      ---@field padding string The padding to use to the left of the renderer, default: `" "`.
      ---@field directory_min_severity DiagnosticSeverity The minimum severity necessary to show for directories, see `|vim.diagnostic.severity|`, default: `vim.diagnostic.severity.ERROR`.
      ---@field file_min_severity DiagnosticSeverity The minimum severity necessary to show for files, see `|vim.diagnostic.severity|`, default: `vim.diagnostic.severity.HINT`.
      diagnostics = {
        padding = " ",
        directory_min_severity = vim.diagnostic.severity.ERROR,
        file_min_severity = vim.diagnostic.severity.HINT,
      },

      ---@class Yat.Config.Renderers.Builtin.BufferInfo : Yat.Config.BaseRendererConfig
      ---@field padding string The padding to use to the left of the renderer, default: `" "`.
      ---@field hidden_icon string The icon for hidden buffers, default: `""`.
      buffer_info = {
        padding = " ",
        hidden_icon = "",
      },

      ---@class Yat.Config.Renderers.Builtin.Clipboard : Yat.Config.BaseRendererConfig
      ---@field padding string The padding to use to the left of the renderer, default: `" "`.
      clipboard = {
        padding = " ",
      },

      ---@class Yat.Config.Renderers.Builtin.SymbolDetails : Yat.Config.BaseRendererConfig
      ---@field padding string The padding to use to the left of the renderer, default: `" "`.
      symbol_details = {
        padding = " ",
      },
    },
  },
}

Panels

The builtin panels are:

• files
• git_status
• symbols
• call_hierarchy
• buffers

Mappings & Actions

Mappings are constructed by associating the key(s) in question with an action.

? toggles the help, showing the keymap.

The actions supported by the trees are:

All builtin actions:

---@alias Yat.Actions.Name
---| "close_sidebar"
---| "system_open"
---| "open_help"
---| "show_node_info"
---| "close_panel"
---|
---| "open_git_status_panel"
---| "open_symbols_panel"
---| "open_call_hierarchy_panel"
---| "open_buffers_panel"
---|
---| "open"
---| "vsplit"
---| "split"
---| "tabnew"
---| "preview"
---| "preview_and_focus"
---|
---| "copy_name_to_clipboard"
---| "copy_root_relative_path_to_clipboard"
---| "copy_absolute_path_to_clipboard"
---| "close_node"
---| "close_all_nodes"
---| "close_all_child_nodes"
---| "expand_all_nodes"
---| "expand_all_child_nodes"
---|
---| "refresh_panel"
---|
---| "focus_parent"
---| "focus_prev_sibling"
---| "focus_next_sibling"
---| "focus_first_sibling"
---| "focus_last_sibling"
---
---| "add"
---| "rename"
---| "delete"
---| "trash"
---| "copy_node"
---| "cut_node"
---| "paste_nodes"
---| "clear_clipboard"
---| "cd_to"
---| "cd_up"
---| "toggle_filter"
---
---| "search_for_node_in_panel"
---| "search_interactively"
---| "search_once"
---| "close_search"
---
---| "goto_node_in_files_panel"
---
---| "toggle_ignored"
---| "check_node_for_git"
---| "open_repository"
---| "focus_prev_git_item"
---| "focus_next_git_item"
---| "git_stage"
---| "git_unstage"
---| "git_revert"
---
---| "focus_prev_diagnostic_item"
---| "focus_next_diagnostic_item"

Files panel actions:

---@alias Yat.Panel.Files.SupportedActions
---| "close_sidebar"
---| "system_open"
---| "open_help"
---| "show_node_info"
---
---| "open_git_status_panel"
---| "open_symbols_panel"
---| "open_call_hierarchy_panel"
---| "open_buffers_panel"
---
---| "open"
---| "vsplit"
---| "split"
---| "tabnew"
---| "preview"
---| "preview_and_focus"
---
---| "copy_name_to_clipboard"
---| "copy_root_relative_path_to_clipboard"
---| "copy_absolute_path_to_clipboard"
---
---| "close_node"
---| "close_all_nodes"
---| "close_all_child_nodes"
---| "expand_all_nodes"
---| "expand_all_child_nodes"
---
---| "refresh_panel"
---
---| "focus_parent"
---| "focus_prev_sibling"
---| "focus_next_sibling"
---| "focus_first_sibling"
---| "focus_last_sibling"
---|
---| "add"
---| "rename"
---| "delete"
---| "trash"
---
---| "copy_node"
---| "cut_node"
---| "paste_nodes"
---| "clear_clipboard"
---
---| "cd_to"
---| "cd_up"
---
---| "toggle_filter"
---
---| "search_for_node_in_panel"
---| "search_interactively"
---| "search_once"
---| "close_search"
---
---| "goto_node_in_files_panel"
---
---| "toggle_ignored"
---| "check_node_for_git"
---| "focus_prev_git_item"
---| "focus_next_git_item"
---| "git_stage"
---| "git_unstage"
---| "git_revert"
---
---| "focus_prev_diagnostic_item"
---| "focus_next_diagnostic_item"

Git Status panel actions:

---@alias Yat.Panel.GitStatus.SupportedActions
---| "close_sidebar"
---| "system_open"
---| "open_help"
---| "show_node_info"
---| "close_panel"
---
---| "open_symbols_panel"
---| "open_call_hierarchy_panel"
---| "open_buffers_panel"
---
---| "open"
---| "vsplit"
---| "split"
---| "tabnew"
---| "preview"
---| "preview_and_focus"
---
---| "copy_name_to_clipboard"
---| "copy_root_relative_path_to_clipboard"
---| "copy_absolute_path_to_clipboard"
---
---| "close_node"
---| "close_all_nodes"
---| "close_all_child_nodes"
---| "expand_all_nodes"
---| "expand_all_child_nodes"
---
---| "refresh_panel"
---
---| "focus_parent"
---| "focus_prev_sibling"
---| "focus_next_sibling"
---| "focus_first_sibling"
---| "focus_last_sibling"
---|
---| "rename"
---
---| "cd_to"
---| "toggle_filter"
---
---| "search_for_node_in_panel"
---
---| "goto_node_in_files_panel"
---
---| "toggle_ignored"
---| "open_repository"
---| "focus_prev_git_item"
---| "focus_next_git_item"
---| "git_stage"
---| "git_unstage"
---| "git_revert"
---
---| "focus_prev_diagnostic_item"
---| "focus_next_diagnostic_item"

LSP Symbols panel actions:

---@alias Yat.Panel.Symbols.SupportedActions
---| "close_sidebar"
---| "open_help"
---| "close_panel"
---
---| "open_git_status_panel"
---| "open_call_hierarchy_panel"
---| "open_buffers_panel"
---
---| "open"
---| "vsplit"
---| "split"
---| "tabnew"
---| "preview"
---| "preview_and_focus"
---
---| "copy_name_to_clipboard"
---| "copy_root_relative_path_to_clipboard"
---| "copy_absolute_path_to_clipboard"
---
---| "close_node"
---| "close_all_nodes"
---| "close_all_child_nodes"
---| "expand_all_nodes"
---| "expand_all_child_nodes"
---
---| "refresh_panel"
---
---| "focus_parent"
---| "focus_prev_sibling"
---| "focus_next_sibling"
---| "focus_first_sibling"
---| "focus_last_sibling"
---
---| "toggle_filter"
---
---| "search_for_node_in_panel"
---
---| "toggle_ignored"
---
---| "focus_prev_diagnostic_item"
---| "focus_next_diagnostic_item"

Call Hierarchy panel actions:

---@alias Yat.Panel.CallHierarchy.SupportedActions
---| "close_sidebar"
---| "open_help"
---| "close_panel"
---
---| "open_git_status_panel"
---| "open_symbols_panel"
---| "open_buffers_panel"
---
---| "open"
---| "vsplit"
---| "split"
---| "tabnew"
---| "preview"
---| "preview_and_focus"
---
---| "copy_name_to_clipboard"
---| "copy_root_relative_path_to_clipboard"
---| "copy_absolute_path_to_clipboard"
---
---| "close_node"
---| "close_all_nodes"
---| "close_all_child_nodes"
---| "expand_all_nodes"
---| "expand_all_child_nodes"
---
---| "refresh_panel"
---
---| "focus_parent"
---| "focus_prev_sibling"
---| "focus_next_sibling"
---| "focus_first_sibling"
---| "focus_last_sibling"
---
---| "toggle_filter"
---
---| "search_for_node_in_panel"
---
---| "toggle_ignored"
---
---| "toggle_call_direction"
---| "create_call_hierarchy_from_buffer_position"

Buffers panel actions:

---@alias Yat.Panel.Buffers.SupportedActions
---| "close_sidebar"
---| "system_open"
---| "open_help"
---| "show_node_info"
---| "close_panel"
---
---| "open_git_status_panel"
---| "open_symbols_panel"
---| "open_call_hierarchy_panel"
---
---| "open"
---| "vsplit"
---| "split"
---| "tabnew"
---| "preview"
---| "preview_and_focus"
---
---| "copy_name_to_clipboard"
---| "copy_root_relative_path_to_clipboard"
---| "copy_absolute_path_to_clipboard"
---
---| "close_node"
---| "close_all_nodes"
---| "close_all_child_nodes"
---| "expand_all_nodes"
---| "expand_all_child_nodes"
---
---| "refresh_panel"
---
---| "focus_parent"
---| "focus_prev_sibling"
---| "focus_next_sibling"
---| "focus_first_sibling"
---| "focus_last_sibling"
---|
---| "cd_to"
---| "toggle_filter"
---
---| "search_for_node_in_panel"
---
---| "goto_node_in_files_panel"
---
---| "toggle_ignored"
---| "check_node_for_git"
---| "focus_prev_git_item"
---| "focus_next_git_item"
---| "git_stage"
---| "git_unstage"
---| "git_revert"
---
---| "focus_prev_diagnostic_item"
---| "focus_next_diagnostic_item"

Custom actions

Custom actions can easily be created using the config helper:

---@async
---@param panel Yat.Panel.Tree
---@param node Yat.Node
local function special_action(panel, node)
  -- this is what the "git_stage" action does
  if node.repo then
    node.repo:index():add(node.path)
    -- There is no need to redraw the panel, the git watcher detect the change and
    -- updates any affected panels
  end
end

---@async
---@param panel Yat.Panel.Tree
---@param node Yat.Node
local function print_panel_and_node(panel, node)
  print(panel.TYPE)
  vim.pretty_print(node:get_debug_info())
end

local utils = require("ya-tree.config.utils")
require("ya-tree").setup({
  actions = {
    special_action = utils.create_tree_panel_action(special_action, "Add node to git", false, { "n" }),
    print = utils.create_tree_panel_action(print_panel_and_node, "Print panel and node", false, { "n" }),
  },
  panels = {
    files = {
      mappings = {
        ["A"] = "special_action",
        ["T"] = "print",
      },
    },
    git_status = {
      mappings = {
        ["t"] = "print",
      },
    },
  },
})

Async

Git and file system operations are wrapped with in coroutines, based on async.nvim and the wrap function, turning callbacks into regular return values. The consequence of this is that calling those functions must also be done in a coroutine. This bubbles up all the way, so all entry points to the plugin are called using the ya-tree.async.void function.

For actions, this conceptually translates to:

local panel = ...
local action = ...
vim.keymap.set(mode, key, function()
  local node = panel:get_current_node()
  require("ya-tree.async").void(action)(panel, node)
end, opts)

This means that all actions are running inside a coroutine and special care has to be taken to handle vim.api functions calls, since they might error when called from a vim.loop callback. The is remedied by using vim.schedule(...), or the wrapped async variant:

panel.root:refresh()
require("ya-tree.async").scheduler()
-- this can cause E5560 without the call to scheduler above
local height, width = panel:size()

The vim.ui.input and vim.ui.select functions are also wrapped to make them easier to use:

local ui = require("ya-tree.ui")
local response = ui.input({ promt = "My prompt", deault = "My value" })
local choice = ui.select({ "Yes", "No" }, { kind = "confirmation", prompt = "Choose" })

The nui.nvim Input class is extended with completion using completefunc and initialization parameters specific to ya-tree, in the ya-tree.ui.nui package. There is also a wrapped variant for when only a simple result is needed:

local ui = require("ya-tree.ui")
local reponse = ui.nui_input({ title = "My Title", completion = "file" })

Renderers

A custom renderer component can be created using the config helper:

---@class Yat.Ui.RenderContext
---@field panel_type Yat.Panel.Type
---@field config Yat.Config
---@field depth integer
---@field last_child boolean
---@field indent_markers table<integer, boolean>

---@class Yat.Ui.RenderResult
---@field padding string
---@field text string
---@field highlight string

local hl = require("ya-tree.ui.highlights")

---@param node Yat.Node
---@param context Yat.Ui.RenderContext
---@param renderer Yat.Config.BaseRendererConfig
---@return Yat.Ui.RenderResult[]|nil result
local function renderer(node, context, renderer)
  -- the renderer parameter is the merged table of the second argument to utils.create_renderer
  -- and the `override` table in the panels's renderers table
  if renderer.prop and vim.startswith(node.name, "A") then
    return {
      {
        padding = renderer.padding,
        text = "WOO",
        highlight = hl.ERROR_FILE_NAME,
      },
    }
  end
end

local utils = require("ya-tree.config.utils")
require("ya-tree").setup({
  renderers = {
    example_renderer = utils.create_tree_panel_renderer(renderer, { padding = " ", prop = false }),
  },
  panels = {
    files = {
      renderers = {
        file = {
          { name = "indentation" },
          { name = "icon" },
          { name = "name", override = { use_git_status_colors = true } },
          { name = "example_renderer", override = { prop = true } },
          { name = "symlink_target" },
          { name = "modified" },
          { name = "git_status" },
          { name = "diagnostics" },
        },
      },
    },
  },
})

Renderers should only access already availble data on the node in question, or special helper functions in the ya-tree.ui.renderers module, and not initiate any further calls, if possible.

Highlight Groups

Ya-Tree defines the following highligh groups:

Highlight Group	Default Group	Values
YaTreeError		{ fg = "#080808", bg = "#ff0000" }
YaTreeRootName		{ fg = "#ddc7a1", bold = true }
YaTreeIndentMarker		{ fg = "#5a524c" }
YaTreeIndentExpander	YaTreeDirectoryIcon
YaTreeContainerIcon	YaTreeDirectoryIcon
YaTreeDirectoryIcon	Directory
YaTreeSymbolicDirectoryIcon	YaTreeDirectoryIcon
YaTreeContainerName	YaTreeDirectoryName
YaTreeDirectoryName	Directory
YaTreeEmptyDirectoryName	YaTreeDirectoryName
YaTreeSymbolicDirectoryName	YaTreeDirectoryName
YaTreeEmptySymbolicDirectoryName	YaTreeDirectoryName
YaTreeLeafIcon	YaTreeDefaultFileIcon
YaTreeDefaultFileIcon	Normal
YaTreeSymbolicFileIcon	YaTreeDefaultFileIcon
YaTreeFifoFileIcon		{ fg = "#af0087" }
YaTreeSocketFileIcon		{ fg = "#ff005f" }
YaTreeCharDeviceFileIcon		{ fg = "#87d75f" }
YaTreeBlockDeviceFileIcon		{ fg = "#5f87d7" }
YaTreeLeafName	YaTreeFileName
YaTreeFileName	Normal
YaTreeSymbolicFileName	YaTreeFileName
YaTreeFifoFileName	YaTreeFifoFileIcon
YaTreeSocketFileName	YaTreeSocketFileIcon
YaTreeCharDeviceFileName	YaTreeCharDeviceFileIcon
YaTreeBlockDeviceFileName	YaTreeBlockDeviceFileIcon
YaTreeExecutableFileName	YaTreeFileName
YaTreeFileModified		{ fg = normal_fg, bold = true }
YaTreeSymbolicLinkTarget		{ fg = "#7daea3", italic = true }
YaTreeBufferNumber	SpecialChar
YaTreeBufferHidden	WarningMsg
YaTreeClipboardStatus	Comment
YaTreeText	Normal
YaTreeDimText	Comment
YaTreeSearchTerm	SpecialChar
YaTreeNormal	Normal
YaTreeNormalNC	NormalNC
YaTreeCursorLine	CursorLine
YaTreeWinSeparator	WinSeparator
YaTreeStatusLine	StatusLine
YaTreeStatusLineNC	StatusLineNC
YaTreeFloatNormal	NormalFloat
YaTreeGitRepoToplevel	Character	fallack: "#a9b665"
YaTreeGitUnmergedCount	GitSignsDelete, GitGutterDelete	fallack: "#ea6962"
YaTreeGitStashCount	Character	fallack: "#a9b665"
YaTreeGitAheadCount	Character	fallack: "#a9b665"
YaTreeGitBehindCount	Character	fallack: "#a9b665"
YaTreeGitStagedCount	Type	fallack: "#d8a657"
YaTreeGitUnstagedCount	Type	fallack: "#d8a657"
YaTreeGitUntrackedCount	Title	fallack: "#7daea3"
YaTreeGitStaged	Character	fallack: "#a9b665"
YaTreeGitDirty	GitSignsChange, GitGutterChange	fallack: "#cb8327"
YaTreeGitNew	GitSignsAdd, GitGutterAdd	fallack: "#6f8352"
YaTreeGitMerge	Statement	fallack: "#d3869b"
YaTreeGitRenamed	Title	fallack: "#7daea3"
YaTreeGitDeleted	GitSignsDelete, GitGutterDelete	fallack: "#ea6962"
YaTreeGitIgnored	Comment
YaTreeGitUntracked	Type	fallack: "#d8a657"
YaTreeInfoSize	TelescopePreviewSize
YaTreeInfoUser	TelescopePreviewUser
YaTreeInfoGroup	TelescopePreviewGroup
YaTreeInfoPermissionNone	TelescopePreviewHyphen
YaTreeInfoPermissionRead	TelescopePreviewRead
YaTreeInfoPermissionWrite	TelescopePreviewWrite
YaTreeInfoPermissionExecute	TelescopePreviewExecute
YaTreeInfoDate	TelescopePreviewDate
YaTreeUiCurrentTab		{ fg = "#080808", bg = "#5f87d7" }
YaTreeUiOhterTab		{ fg = "#080808", bg = "#5a524c" }
YaTreeSectionIcon	YaTreeSectionName
YaTreeSectionName		{ fg = "#5f87d7" }

Acknowledgments

• gitsigns.nvim for Git integration in Lua.
• async.nvim for async.
• nvim-tree.lua for tree plugin ideas.
• neo-tree.nvim for tree plugin ideas, and renderers.
• yanil for tree plugin ideas.
• sidebar.nvim for the sidebar idea.
• nvim-ide for panels instead of one sidebar with all trees.
• nui.nvim