### Get user-provided nvim-tree configuration

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/doc/nvim-tree-lua.txt

Returns a reference to the configuration object passed to `nvim_tree_setup`. Returns `nil` if no configuration was provided during setup.

```lua
api.config.user()
```

--------------------------------

### Re-run nvim-tree Setup

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Development

Execute the setup function for nvim-tree.lua. This can be run multiple times.

```lua
:lua _G.setup()
```

--------------------------------

### Setup nvim-tree.lua with Defaults

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/README.md

Basic setup for nvim-tree.lua using default configurations. Ensure netrw is disabled and 24-bit color is enabled if desired.

```lua
  -- disable netrw at the very start of your init.lua
  vim.g.loaded_netrw = 1
  vim.g.loaded_netrwPlugin = 1

  -- optionally enable 24-bit colour
  vim.opt.termguicolors = true

  -- empty setup using defaults
  require("nvim-tree").setup()
```

--------------------------------

### Install nvim-tree with lazy.nvim

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Installation

Configure lazy.nvim to manage nvim-tree.lua, including its version, dependencies, and setup function.

```lua
return {
  "nvim-tree/nvim-tree.lua",
  version = "*",
  lazy = false,
  dependencies = {
    "nvim-tree/nvim-web-devicons",
  },
  config = function()
    require("nvim-tree").setup {}
  end,
}

```

--------------------------------

### Install and Run LSP Checks

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/CONTRIBUTING.md

Installs the lua-language-server and then runs checks. This is useful if the LSP is not available or the --check flag is not functioning.

```sh
mkdir luals
curl -L "https://github.com/LuaLS/lua-language-server/releases/download/3.15.0/lua-language-server-3.15.0-linux-x64.tar.gz" | tar zx --directory luals

PATH="luals/bin:${PATH}" make check
```

--------------------------------

### Setup Configuration

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/doc/nvim-tree-lua.txt

Demonstrates how to set up the nvim-tree plugin with default or custom configurations in your init.lua file.

```APIDOC
## Setup

### Description

Sets up the nvim-tree plugin. You can provide a configuration table to customize its behavior.

### Usage

```lua
require("nvim-tree").setup(config)
```

### Parameters

- `config` (table, optional): A table containing configuration options for nvim-tree. If not provided, default settings are used.

### Example with Defaults

```lua
require("nvim-tree").setup()
```

### Example with Custom Configuration

```lua
--@type nvim_tree.config
local config = {
  sort = {
    sorter = "case_sensitive",
  },
  view = {
    width = 30,
  },
  renderer = {
    group_empty = true,
  },
  filters = {
    dotfiles = true,
  },
}
require("nvim-tree").setup(config)
```
```

--------------------------------

### Native Neovim LSP Configuration for Lua

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Development

Configure and start the Lua Language Server directly using Neovim's API without relying on nvim-lspconfig. This setup uses an autocmd to trigger on Lua filetypes.

```lua
vim.api.nvim_create_autocmd("FileType", {
  pattern = "lua",
  callback = function()
    vim.lsp.start {
      name = "my-luals",
      cmd = { "lua-language-server" },
      root_dir = vim.fs.root(0, '.luarc.json'),
    }
  end,
})
```

--------------------------------

### Install nvim-tree with vim.pack

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Installation

Use vim.pack to add nvim-tree.lua and its optional dependency nvim-web-devicons.

```lua
vim.pack.add({
  { src = 'https://github.com/nvim-tree/nvim-web-devicons' }, -- optional
  { src = 'https://github.com/nvim-tree/nvim-tree.lua' },
})

```

--------------------------------

### Setup nvim-tree.lua with Custom Configuration

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/README.md

Configure nvim-tree.lua with custom settings for sorting, view width, empty group rendering, and dotfile filtering. This setup requires a Lua configuration table.

```lua
  -- OR setup with a config

  --@type nvim_tree.config
  local config = {
    sort = {
      sorter = "case_sensitive",
    },
    view = {
      width = 30,
    },
    renderer = {
      group_empty = true,
    },
    filters = {
      dotfiles = true,
    },
  }
  require("nvim-tree").setup(config)
```

--------------------------------

### Nvim-Tree Setup with on_attach Callback

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Archived

This Lua snippet shows how to integrate the `on_attach` function into the nvim-tree setup. The `on_attach` function is crucial for defining key mappings that are executed when the nvim-tree buffer is attached.

```lua
require("nvim-tree").setup({
  on_attach = on_attach,
})

```

--------------------------------

### Setup Lua Language Server with lspconfig

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Development

Configure the Lua Language Server using the nvim-lspconfig plugin. Ensure client capabilities are made.

```lua
local lspconfig = require("lspconfig")

lspconfig.lua_ls.setup({
  capabilities = vim.lsp.protocol.make_client_capabilities(),
})
```

--------------------------------

### Define custom on_attach function for nvim-tree mappings

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/doc/nvim-tree-lua.txt

Sets up custom key mappings for the nvim-tree buffer using the `on_attach` function in the setup configuration. This example shows how to add, remove, and override default mappings.

```lua
local function my_on_attach(bufnr)
    local api = require("nvim-tree.api")

    local function opts(desc)
      return { desc = "nvim-tree: " .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true }
    end

    -- copy default mappings here from defaults in next section
    vim.keymap.set("n", "<C-]>", api.tree.change_root_to_node,          opts("CD"))
    vim.keymap.set("n", "<C-e>", api.node.open.replace_tree_buffer,     opts("Open: In Place"))
    -- OR use all default mappings
    api.map.on_attach.default(bufnr)

    -- remove a default
    vim.keymap.del("n", "<C-]>", { buffer = bufnr })

    -- override a default
    vim.keymap.set("n", "<C-e>", api.tree.reload,                       opts("Refresh"))

    -- add your mappings
    vim.keymap.set("n", "?",     api.tree.toggle_help,                  opts("Help"))
    -- 
  end

  require("nvim-tree").setup({
    ---
    on_attach = my_on_attach,
    ---
  })
```

--------------------------------

### Register VimEnter Autocmd

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Open-At-Startup

Use the `VimEnter` event to trigger nvim-tree setup after Neovim has started and other plugins are initialized. This is the recommended time to define startup behavior.

```lua
vim.api.nvim_create_autocmd({ "VimEnter" }, { callback = open_nvim_tree })
```

--------------------------------

### Customizing on_attach with Default Mappings

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/doc/nvim-tree-lua.txt

This example shows how to define a custom `on_attach` function that includes the default nvim-tree mappings and allows for further customization.

```lua
local function my_on_attach(bufnr)
  local api = require("nvim-tree.api")

  local function opts(desc)
    return { desc = "nvim-tree: " .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true }
  end

  api.map.on_attach.default(bufnr)

  -- your removals and mappings go here
end
```

--------------------------------

### Disable netrw and Setup nvim-tree

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/doc/nvim-tree-lua.txt

Disable netrw before setting up nvim-tree. This snippet shows both an empty setup using defaults and a setup with custom configuration options.

```lua
vim.g.loaded_netrw = 1
vim.g.loaded_netrwPlugin = 1

vim.opt.termguicolors = true

require("nvim-tree").setup()

-- OR setup with a config

---
--@type nvim_tree.config
local config = {
  sort = {
    sorter = "case_sensitive",
  },
  view = {
    width = 30,
  },
  renderer = {
    group_empty = true,
  },
  filters = {
    dotfiles = true,
  },
}
require("nvim-tree").setup(config)
```

--------------------------------

### Install nvim-tree with lazy.nvim

Source: https://context7.com/nvim-tree/nvim-tree.lua/llms.txt

Install nvim-tree using the lazy.nvim plugin manager. Ensure netrw is disabled before loading any plugins. This snippet includes basic configuration options for sorting, view width, empty directory collapsing, and dotfile filtering.

```lua
vim.g.loaded_netrw       = 1
vim.g.loaded_netrwPlugin = 1

vim.opt.termguicolors = true

-- lazy.nvim spec
return {
  "nvim-tree/nvim-tree.lua",
  version = "*",
  lazy = false,                        -- do NOT lazy load nvim-tree
  dependencies = {
    "nvim-tree/nvim-web-devicons",     -- optional: file icons (needs Nerd Font)
  },
  config = function()
    ---@type nvim_tree.config
    require("nvim-tree").setup({
      sort = {
        sorter = "case_sensitive",     -- "name" | "modification_time" | "extension"
      },
      view = {
        width = 30,
      },
      renderer = {
        group_empty = true,            -- collapse single-child empty directories
      },
      filters = {
        dotfiles = true,               -- hide dotfiles by default (toggle with H)
      },
    })
  end,
}
```

--------------------------------

### nvim-tree.lua: Custom Key Mappings Configuration

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/doc/nvim-tree-lua.txt

Example of how to define custom key mappings within the nvim-tree configuration using the `on_attach` callback.

```lua
local function my_on_attach(bufnr)
  local api = require "nvim-tree.api"

  local function opts(desc)
    return { desc = "nvim-tree: " .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true }
  end

  -- default mappings
  api.map.on_attach.default(bufnr)

  -- custom mappings
  vim.keymap.set("n", "<C-t>", api.tree.change_root_to_parent,        opts("Up"))
  vim.keymap.set("n", "?",     api.tree.toggle_help,                  opts("Help"))
end

-- pass to setup along with your other config
require("nvim-tree").setup({
    --- 
    on_attach = my_on_attach,
    --- 
  })
```

--------------------------------

### Feature Flags on Linux

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Development

Example output of feature flags when running on a Linux system.

```text
linux=1
mac=0
macunix=0
osx=0
osxdarwin=0
unix=1
win32=0
win64=0
wsl=0
```

--------------------------------

### Install nvim-tree with vim-plug

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Installation

Add nvim-tree.lua and its optional dependency nvim-web-devicons to your vim-plug configuration.

```vim
Plug 'nvim-tree/nvim-web-devicons' " optional
Plug 'nvim-tree/nvim-tree.lua'

```

--------------------------------

### Integrate Telescope with Nvim-Tree for File Searching

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Recipes

This snippet allows you to launch Telescope's 'find_files' or 'live_grep' actions, with the search context automatically set to the directory of the currently selected node in Nvim-Tree. It requires Telescope to be installed.

```lua
local api = require("nvim-tree.api")
local actions = require'telescope.actions'
local action_state = require'telescope.actions.state'
local M = {}

local view_selection = function(prompt_bufnr)
  actions.select_default:replace(function()
    actions.close(prompt_bufnr)
    local selection = action_state.get_selected_entry()
    local filename = selection.filename
    if (filename == nil) then
      filename = selection[1]
    end
    api.tree.find_file(filename, { open = true, focus = true, })
    api.node.open.preview()
  end)
  return true
end

function M.launch_live_grep(opts)
  return M.launch_telescope("live_grep", opts)
end

function M.launch_find_files(opts)
  return M.launch_telescope("find_files", opts)
end

function M.launch_telescope(func_name, opts)
  local telescope_status_ok, _ = pcall(require, "telescope")
  if not telescope_status_ok then
    return
  end
  local node = api.tree.get_node_under_cursor()
  local basedir = node.type == "directory" and node.absolute_path or vim.fn.fnamemodify(node.absolute_path, ":h")
  opts = opts or {}
  opts.cwd = basedir
  opts.search_dirs = { basedir }
  opts.attach_mappings = view_selection
  return require("telescope.builtin")[func_name](opts)
end

return M
```

```lua
local treeutils = require("treeutils")

vim.keymap.set('n', '<c-f>', treeutils.launch_find_files, opts('Launch Find Files'))
vim.keymap.set('n', '<c-g>', treeutils.launch_live_grep,  opts('Launch Live Grep'))
```

--------------------------------

### Configure nvim-tree Setup Options

Source: https://context7.com/nvim-tree/nvim-tree.lua/llms.txt

Configure nvim-tree with various options to customize its behavior and appearance. This includes cursor handling, sync with current working directory, reload behavior, prompt selection, view settings, renderer options, Git integration, diagnostics display, filters, and file opening actions.

```lua
vim.g.loaded_netrw       = 1
vim.g.loaded_netrwPlugin = 1

---@type nvim_tree.config
require("nvim-tree").setup({
  hijack_cursor          = true,   -- keep cursor on first letter of filename
  sync_root_with_cwd     = true,   -- change tree root on :cd
  reload_on_bufenter     = false,
  select_prompts         = true,   -- use vim.ui.select() for confirmations (dressing.nvim friendly)

  view = {
    width = 35,
    side  = "left",                -- "left" | "right"
    float = { enable = false },
  },

  renderer = {
    root_folder_label = ":~:s?$?/..?",
    highlight_git     = "name",    -- "none" | "icon" | "name" | "all"
    icons = {
      show = { file = true, folder = true, folder_arrow = true, git = true },
    },
  },

  git = {
    enable  = true,
    timeout = 400,
  },

  diagnostics = {
    enable   = true,
    severity = { min = vim.diagnostic.severity.HINT },
  },

  filters = {
    git_ignored = false,
    dotfiles    = false,
    custom      = { ".git$" },    -- always hide .git directory
    exclude     = {},
  },

  actions = {
    open_file = {
      quit_on_open  = false,
      resize_window = true,
    },
  },
})
```

--------------------------------

### nvim-tree API: Open

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Open-At-Startup

The `open` API function is used to display the nvim-tree. This example shows its default parameters, excluding the `focus` option.

```lua
require("nvim-tree.api").tree.open({
	path = nil,
	current_window = false,
	find_file = false,
	update_root = false,
})
```

--------------------------------

### Custom Highlight Group Example in Vim

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/doc/nvim-tree-lua.txt

Example of how to manually set a highlight group for symlinks in Vim. This allows for custom styling of specific file types.

```vim
:hi NvimTreeSymlink guifg=blue gui=bold,underline
```

--------------------------------

### Register Custom Decorator in nvim-tree Setup

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Decorators

Shows how to require and register a custom decorator class within the nvim-tree setup configuration.

```lua
local MyDecorator = require("my-decorator")

require("nvim-tree").setup({
  renderer = {
    decorators = {
      "Git",
      "Open",
      "Hidden",
      "Modified",
      "Bookmark",
      "Diagnostics",
      "Copied",
      MyDecorator,
      "Cut",
    },
  },
})
```

--------------------------------

### Integrate nvim-tree with Telescope

Source: https://context7.com/nvim-tree/nvim-tree.lua/llms.txt

Launch Telescope searches scoped to the current nvim-tree directory. This requires the Telescope plugin to be installed. The `view_selection` function customizes the default Telescope action to open files within nvim-tree.

```lua
-- File: lua/treeutils.lua
local M   = {}
local api = require("nvim-tree.api")

local function view_selection(prompt_bufnr)
  local actions      = require("telescope.actions")
  local action_state = require("telescope.actions.state")
  actions.select_default:replace(function()
    actions.close(prompt_bufnr)
    local selection = action_state.get_selected_entry()
    local filename  = selection.filename or selection[1]
    api.tree.find_file(filename, { open = true, focus = true })
    api.node.open.preview()
  end)
  return true
end

function M.launch_telescope(func_name, opts)
  if not pcall(require, "telescope") then return end
  local node    = api.tree.get_node_under_cursor()
  local basedir = node.type == "directory" and node.absolute_path
                  or vim.fn.fnamemodify(node.absolute_path, ":h")
  opts               = opts or {}
  opts.cwd           = basedir
  opts.search_dirs   = { basedir }
  opts.attach_mappings = view_selection
  require("telescope.builtin")[func_name](opts)
end

M.launch_find_files = function(o) return M.launch_telescope("find_files", o) end
M.launch_live_grep  = function(o) return M.launch_telescope("live_grep",  o) end

return M

-- In on_attach:
local treeutils = require("treeutils")
vim.keymap.set("n", "<C-f>", treeutils.launch_find_files, opts("Find Files"))
vim.keymap.set("n", "<C-g>", treeutils.launch_live_grep,  opts("Live Grep"))
```

--------------------------------

### Feature Flags on macOS

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Development

Example output of feature flags when running on a macOS system.

```text
linux=0
mac=1
macunix=1
osx=1
osxdarwin=1
unix=1
win32=0
win64=0
wsl=0
```

--------------------------------

### Extend nvim-tree Class

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/doc/nvim-tree-lua.txt

Demonstrates how to create new classes by extending existing ones, starting from the base `Class`. Ensure to use `---@class` for type annotations.

```lua
local Class = require("nvim-tree.classic")

--@class (exact) Fruit: nvim_tree.Class
--@field ...
local Fruit = Class:extend()

--@class (exact) Apple: Fruit
--@field ...
local Apple = Fruit:extend()
```

--------------------------------

### nvim-tree API: Toggle

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Open-At-Startup

The `toggle` API function can be used to open, close, or focus the nvim-tree. This example shows its default parameters for startup.

```lua
require("nvim-tree.api").tree.toggle({
	path = nil,
	current_window = false,
	find_file = false,
	update_root = false,
	focus = true,
})
```

--------------------------------

### Feature Flags on WSL

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Development

Example output of feature flags when running on Windows Subsystem for Linux (WSL).

```text
linux=1
mac=0
macunix=0
osx=0
osxdarwin=0
unix=1
win32=0
win64=0
wsl=1
```

--------------------------------

### OS-Specific System Open Configuration

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Tips

Conditionally set the system_open command based on the operating system. This example configures the 'open -R' command for MacOS and defaults to nil for other OS.

```lua
  -- identify OS and set OS-specific cmd with args
  vim.fn.has("mac") == 1
  and {
    cmd = "open",
    args = { "-R" },
  }
  or nil,
```

--------------------------------

### Backwards Compatibility Shim Example

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/CONTRIBUTING.md

Provides a shim for neovim API calls to ensure compatibility with older versions. This is used when a new API is introduced but needs to be available in older versions.

```lua
if vim.fn.has("nvim-0.11") == 1 and vim.hl and vim.hl.range then
  vim.hl.range(0, ns_id, details.hl_group, { 0, col }, { 0, details.end_col, }, {})
else
  vim.api.nvim_buf_add_highlight(0, ns_id, details.hl_group, 0, col, details.end_col) ---@diagnostic disable-line: deprecated
end
```

--------------------------------

### Custom Key Mappings for nvim-tree.lua

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/README.md

Define custom key mappings for nvim-tree.lua within the `on_attach` function. This example includes mappings for changing the root directory and toggling help, along with default mappings.

```lua
  local function my_on_attach(bufnr)
    local api = require "nvim-tree.api"

    local function opts(desc)
      return { desc = "nvim-tree: " .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true }
    end

    -- default mappings
    api.map.on_attach.default(bufnr)

    -- custom mappings
    vim.keymap.set("n", "<C-t>", api.tree.change_root_to_parent,        opts("Up"))
    vim.keymap.set("n", "?",     api.tree.toggle_help,                  opts("Help"))
  end

  -- pass to setup along with your other config
  require("nvim-tree").setup({
    ---
    on_attach = my_on_attach,
    ---
  })
```

--------------------------------

### Focus Already-Opened File on Enter in Nvim-Tree

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Recipes

Configure the `on_attach` callback to set a keymap for opening nodes. This example sets the Enter key to use `api.node.open.tab_drop` to focus already opened files.

```lua
require("nvim-tree").setup({
    on_attach = function(bufnr)
        local function opts(desc)
            return { desc = 'nvim-tree: ' .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true }
        end
        local ok, api = pcall(require, "nvim-tree.api")
        assert(ok, "api module is not found")
        vim.keymap.set("n", "<CR>", api.node.open.tab_drop, opts("Tab drop"))
    end
})
```

--------------------------------

### Configure nvim-tree on Attach for Multi-File Operations

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Recipes

Implement multi-file operations like copy, cut, trash, and remove by defining custom functions within the `on_attach` callback. This setup requires the `nvim-tree.api` and uses `vim.ui.input` for confirmations.

```lua
{
		ui = {
			confirm = {
				remove = true,
				trash = false,
			},
		},
		on_attach = function(bufnr)
			local api = require("nvim-tree.api")
			local opts = function(desc)
				return { desc = "nvim-tree: " .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true }
			end

			-- mark operation
			local mark_move_j = function()
				api.marks.toggle()
				vim.cmd("norm j")
			end
			local mark_move_k = function()
				api.marks.toggle()
				vim.cmd("norm k")
			end

			-- marked files operation
			local mark_trash = function()
				local marks = api.marks.list()
				if #marks == 0 then
					table.insert(marks, api.tree.get_node_under_cursor())
				end
				vim.ui.input({ prompt = string.format("Trash %s files? [y/n] ", #marks) }, function(input)
					if input == "y" then
						for _, node in ipairs(marks) do
								api.fs.trash(node)
						end
						api.marks.clear()
						api.tree.reload()
					end
				end)
			end
			local mark_remove = function()
				local marks = api.marks.list()
				if #marks == 0 then
					table.insert(marks, api.tree.get_node_under_cursor())
				end
				vim.ui.input({ prompt = string.format("Remove/Delete %s files? [y/n] ", #marks) }, function(input)
					if input == "y" then
						for _, node in ipairs(marks) do
								api.fs.remove(node)
						end
						api.marks.clear()
						api.tree.reload()
					end
				end)
			end

			local mark_copy = function()
				local marks = api.marks.list()
				if #marks == 0 then
					table.insert(marks, api.tree.get_node_under_cursor())
				end
				for _, node in pairs(marks) do
					api.fs.copy.node(node)
				end
				api.marks.clear()
				api.tree.reload()
			end
			local mark_cut = function()
				local marks = api.marks.list()
				if #marks == 0 then
					table.insert(marks, api.tree.get_node_under_cursor())
				end
				for _, node in pairs(marks) do
					api.fs.cut(node)
				end
				api.marks.clear()
				api.tree.reload()
			end

			vim.keymap.set("n", "p", api.fs.paste, opts("Paste"))
			vim.keymap.set("n", "J", mark_move_j, opts("Toggle Bookmark Down"))
			vim.keymap.set("n", "K", mark_move_k, opts("Toggle Bookmark Up"))

			vim.keymap.set("n", "dd", mark_cut, opts("Cut File(s)"))
			vim.keymap.set("n", "df", mark_trash, opts("Trash File(s)"))
			vim.keymap.set("n", "dF", mark_remove, opts("Remove File(s)"))
			vim.keymap.set("n", "yy", mark_copy, opts("Copy File(s)"))

			vim.keymap.set("n", "mv", api.marks.bulk.move, opts("Move Bookmarked"))

		end


}

```

--------------------------------

### nvim_tree.setup

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/doc/nvim-tree-lua.txt

Initialises or reconfigures nvim-tree with the provided configuration.

```APIDOC
## nvim_tree.setup

### Description
Initialises nvim-tree. This function should be called once to set up the plugin. It can be called again to reapply configuration changes.

### Method Signature
```lua
require("nvim-tree").setup({
  hijack_cursor = true,
})
```

### Parameters
* `config` (table, optional) - A table containing configuration options for nvim-tree. If omitted, default configurations are used. Example options include `hijack_cursor`.
```

--------------------------------

### Link Highlight Group to NONE in Lua

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/doc/nvim-tree-lua.txt

Example of how to link a nvim-tree highlight group to 'NONE' after setup in Lua to override the default link and effectively disable the highlight.

```lua
:hi! link NvimTreeExecFile NONE
```

--------------------------------

### Link Highlight Group to Normal in Vim

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/doc/nvim-tree-lua.txt

Example of how to link a nvim-tree highlight group to the 'Normal' group before setup to prevent its usage. This is useful for disabling specific highlights.

```vim
:hi NvimTreeExecFile Normal
```

--------------------------------

### Run Neovim with Minimal Configuration

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Development

Launch Neovim using the minimal configuration file to isolate nvim-tree development.

```sh
nvim -nu /tmp/nvt-min.lua
```

--------------------------------

### Migrate and Set Custom Keymaps for nvim-tree

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Archived

Shows how to migrate and set custom keymaps for nvim-tree, including actions like expanding all, showing help, changing the root directory, and printing the node path. Requires 'your code goes here' for custom action callbacks.

```lua
vim.keymap.set('n', 'A', api.tree.expand_all, opts('Expand All'))
vim.keymap.set('n', '?', api.tree.toggle_help, opts('Help'))
vim.keymap.set('n', 'C', api.tree.change_root_to_node, opts('CD'))
vim.keymap.set('n', 'P', function() 
    local node = api.tree.get_node_under_cursor() 
    print(node.absolute_path)
  end, opts('Print Node Path'))

vim.keymap.set('n', 'Z', api.node.run.system, opts('Run System'))
```

--------------------------------

### Initialize nvim-tree with configuration

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/doc/nvim-tree-lua.txt

Initializes nvim-tree with a given configuration. This function can be called once to set up the plugin or again to apply configuration changes.

```lua
require("nvim-tree").setup({
    hijack_cursor = true,
  })
```

--------------------------------

### nvim_tree.api.config.user()

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/doc/nvim-tree-lua.txt

Returns a reference to the configuration passed to |nvim-tree-setup|.

```APIDOC
## nvim_tree.api.config.user()

### Description
Reference to config passed to |nvim-tree-setup|

### Method
APICALL

### Endpoint
nvim_tree.api.config.user()

### Response
#### Success Response (200)
- **nvim_tree.config?** (nvim_tree.config?) - nil when no config passed to setup
```

--------------------------------

### nvim_tree.api.node.run.cmd

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/doc/nvim-tree-lua.txt

Enters the command line with the full path of the node.

```APIDOC
## nvim_tree.api.node.run.cmd

### Description
Enter |cmdline| with the full path of the node and the cursor at the start of the line.

### Parameters
#### Path Parameters
- **node** (nvim_tree.api.Node?) - Required - The directory or file node.
```

--------------------------------

### Conventional Commits Example

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/CONTRIBUTING.md

Example of a Conventional Commits subject line for a pull request, including a type, scope, and issue reference. This format is validated by CI.

```text
fix(#2395): marks.bulk.move defaults to directory at cursor
```

--------------------------------

### Format Root Folder Name to Uppercase (Setup Option)

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Recipes

Directly configure nvim-tree to display the root folder name in uppercase using the `root_folder_label` setup option.

```lua
root_folder_label = function(path)
  return string.upper(vim.fn.fnamemodify(path, ":t"))
end
```

--------------------------------

### nvim_tree.api.node.run.system

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/doc/nvim-tree-lua.txt

Opens a file or directory with the system's default handler.

```APIDOC
## nvim_tree.api.node.run.system

### Description
Opens with the system default handler: |vim.ui.open()|.

### Parameters
#### Path Parameters
- **node** (nvim_tree.api.Node?) - Required - The directory or file node to open.
```

--------------------------------

### Configure Nvim-Tree for Vinegar-Style File Opening

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Recipes

Replace the default open command with `api.node.open.replace_tree_buffer` for vinegar-like behavior. This snippet shows how to implement a toggle function.

```lua
local function toggle_replace()
  local api = require("nvim-tree.api")
  if api.tree.is_visible() then
    api.tree.close()
  else
    api.node.open.replace_tree_buffer()
  end
end
```

--------------------------------

### Get default nvim-tree configuration

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/doc/nvim-tree-lua.txt

Returns an immutable deep clone of the default nvim-tree configuration.

```lua
api.config.default()
```

--------------------------------

### Feature Flags on PowerShell

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Development

Example output of feature flags when running within a PowerShell environment on Windows.

```text
linux=0
mac=0
macunix=0
osx=0
osxdarwin=0
unix=0
win32=1
win64=1
wsl=0
```

--------------------------------

### Instantiate Class using __call Meta Method

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/doc/nvim-tree-lua.txt

Illustrates the conventional way to create class instances using the `__call` meta method, which invokes the class's constructor. This pattern allows for concise instantiation like `SomeClass(args)`.

```lua
--@type AppleArgs
local args = ...

local an_apple = Apple(args)
-- above will call `Apple:new(args)`
```

--------------------------------

### navigate.opened.prev

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/doc/nvim-tree-lua.txt

Navigate to the previous |bufloaded()| file.

```APIDOC
## navigate.opened.prev

### Description
Navigate to the previous |bufloaded()| file.

### Parameters
#### Path Parameters
- **node** (nvim_tree.api.Node?) - Required - directory or file
```

--------------------------------

### Get global nvim-tree configuration

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/doc/nvim-tree-lua.txt

Returns an immutable deep clone of the current global nvim-tree configuration.

```lua
api.config.global()
```

--------------------------------

### Subscribing to NodeRenamed Event

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/doc/nvim-tree-lua.txt

Example of how to subscribe to the NodeRenamed event and log the old and new names of the renamed node.

```APIDOC
## Subscribe to NodeRenamed Event

### Description
Registers a handler function to be called when a node (file or directory) is renamed within nvim-tree. The handler receives an object containing the old and new paths of the node.

### Method
`api.events.subscribe(Event.NodeRenamed, handler_function)`

### Parameters
- **Event.NodeRenamed** (nvim_tree_events_kind): The specific event to subscribe to.
- **handler_function** (function): A function that accepts one argument, `data`.

### Handler Parameters (`data`)
- **old_name** (string): Absolute path to the old node location.
- **new_name** (string): Absolute path to the new node location.

### Request Example
```lua
local api = require("nvim-tree.api")
local Event = api.events.Event

api.events.subscribe(Event.NodeRenamed, function(data)
  print("Node renamed from " .. data.old_name .. " to " ..  data.new_name)
end)
```
```

--------------------------------

### Naive Auto-Close on BufEnter

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Auto-Close

A basic implementation to quit Nvim when Nvim-Tree is the last window. This may fail in complex setups or at startup.

```lua
vim.api.nvim_create_autocmd("BufEnter", {
  nested = true,
  callback = function()
    if #vim.api.nvim_list_wins() == 1 and require("nvim-tree.utils").is_nvim_tree_buf() then
      vim.cmd "quit"
    end
  end
})

```

--------------------------------

### Reload nvim-tree API

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/doc/nvim-tree-lua.txt

Example of how to invoke the `reload` function from the `tree` module. This function is used to refresh the file tree view.

```lua
local api = require("nvim-tree.api")
api.tree.reload()
```

--------------------------------

### Implement Constructor with Super Call

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/doc/nvim-tree-lua.txt

Shows how to implement a constructor for a class, ensuring the superclass constructor is called with appropriate arguments. The `...` syntax is used to capture arguments for the super constructor.

```lua
--@protected
--@param args AppleArgs
function Apple:new(args)

  --@type FruitArgs
  local fruit_args = ...

  Apple.super.new(self, fruit_args)
  ---
```

--------------------------------

### Copy Minimal Configuration

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Development

Copy the minimal configuration file to a temporary location for clean room development.

```sh
cp .github/ISSUE_TEMPLATE/nvt-min.lua /tmp
```

--------------------------------

### navigate.opened.next

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/doc/nvim-tree-lua.txt

Navigate to the next |bufloaded()| file.

```APIDOC
## navigate.opened.next

### Description
Navigate to the next |bufloaded()| file.

### Parameters
#### Path Parameters
- **node** (nvim_tree.api.Node?) - Required - directory or file
```

--------------------------------

### Open nvim-tree for Directories (New Window)

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Open-At-Startup

This function opens nvim-tree when the buffer is a directory. It creates a new buffer, wipes the current directory buffer, changes the directory, and then opens nvim-tree in a new window.

```lua
local function open_nvim_tree(data)

  -- buffer is a directory
  local directory = vim.fn.isdirectory(data.file) == 1

  if not directory then
    return
  end

  -- create a new, empty buffer
  vim.cmd.enew()

  -- wipe the directory buffer
  vim.cmd.bw(data.buf)

  -- change to the directory
  vim.cmd.cd(data.file)

  -- open the tree
  require("nvim-tree.api").tree.open()
end
```

--------------------------------

### Shorten Root Folder Label in Nvim-Tree

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Recipes

Shortens long file paths to a more readable format by abbreviating directory names. Configure this in nvim-tree setup.

```lua
local function label(path)
  path = path:gsub(os.getenv 'HOME', '~', 1)
  return path:gsub('([a-zA-Z])[a-z0-9]+', '%1') .. 
    (path:match '[a-zA-Z]([a-z0-9]*)$' or '')
end
local api = require 'nvim-tree.api'
local nt = require 'nvim-tree'
nt.setup { renderer = { root_folder_label = label, group_empty = label } }
```

--------------------------------

### navigate.git.prev

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/doc/nvim-tree-lua.txt

Navigate to the previous item showing git status.

```APIDOC
## navigate.git.prev

### Description
Navigate to the previous item showing git status.

### Parameters
#### Path Parameters
- **node** (nvim_tree.api.Node?) - Required - directory or file
```

--------------------------------

### Show Node Info and Run Commands

Source: https://context7.com/nvim-tree/nvim-tree.lua/llms.txt

Display a popup with file statistics for the current node or execute a shell command on the selected node. The system default application can also be used to open a node.

```lua
local api = require("nvim-tree.api")

-- Info and run
api.node.show_info_popup()            -- <C-k>  — show file stat popup
api.node.run.cmd()                    -- .       — run arbitrary shell command on node
api.node.run.system()                 -- s       — open with system default application
```

--------------------------------

### Custom Root Folder Name Formatting Function

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Recipes

Defines a custom Lua function to format the root folder name to uppercase. This function can be used with the `nvim-tree.renderer.root_folder_label` setup option.

```lua
local M = {}
local tree_api = require("nvim-tree.api")

-- *********************************************
-- * Format the root folder name to uppercase *
-- *********************************************
M.format_root_folder = function(path)
  -- Get the last component of the path (the folder name)
  local folder_name = vim.fn.fnamemodify(path, ":t") 
  
  -- Convert the folder name to uppercase and return it
  return string.upper(folder_name)
end

return M
```

--------------------------------

### Configure h, j, k, l Navigation and Editing Keymaps

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Recipes

Sets up custom key mappings for navigation and file editing using h, j, k, l keys. Includes functions for expanding/collapsing folders and opening/editing files.

```lua
-- global
vim.api.nvim_set_keymap("n", "<C-h>", ":NvimTreeToggle<cr>", {silent = true, noremap = true})

-- on_attach
vim.keymap.set("n", "l", edit_or_open,          opts("Edit Or Open"))
vim.keymap.set("n", "L", vsplit_preview,        opts("Vsplit Preview"))
vim.keymap.set("n", "h", api.tree.close,        opts("Close"))
vim.keymap.set("n", "H", api.tree.collapse_all, opts("Collapse All"))
```

```lua
local api = require("nvim-tree.api")

local function edit_or_open()
  local node = api.tree.get_node_under_cursor()

  if node.nodes ~= nil then
    -- expand or collapse folder
    api.node.open.edit()
  else
    -- open file
    api.node.open.edit()
    -- Close the tree if file was opened
    api.tree.close()
  end
end

-- open as vsplit on current node
local function vsplit_preview()
  local node = api.tree.get_node_under_cursor()

  if node.nodes ~= nil then
    -- expand or collapse folder
    api.node.open.edit()
  else
    -- open file as vsplit
    api.node.open.vertical()
  end

  -- Finally refocus on tree if it was lost
  api.tree.focus()
end
```

--------------------------------

### Update Help Documentation

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/CONTRIBUTING.md

Run this command to update configuration defaults and default mappings for nvim-tree.lua. Ensure your changes are staged or committed before running.

```sh
make help-update
```

--------------------------------

### Find Directory and Focus with Telescope

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Recipes

Integrates Telescope with nvim-tree to search for directories. Upon selection, it opens nvim-tree and focuses on the chosen directory, facilitating quick file management.

```lua
function find_directory_and_focus()
  local actions = require("telescope.actions")
  local action_state = require("telescope.actions.state")

  local function open_nvim_tree(prompt_bufnr, _)
    actions.select_default:replace(function()
      local api = require("nvim-tree.api")

      actions.close(prompt_bufnr)
      local selection = action_state.get_selected_entry()
      api.tree.open()
      api.tree.find_file(selection.cwd .. "/" .. selection.value)
    end)
    return true
  end

  require("telescope.builtin").find_files({
    find_command = { "fd", "--type", "directory", "--hidden", "--exclude", ".git/*" },
    attach_mappings = open_nvim_tree,
  })
end

vim.keymap.set("n", "fd", find_directory_and_focus)

```

--------------------------------

### navigate.sibling.prev

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/doc/nvim-tree-lua.txt

Navigate to the previous node in the current node's folder, wraps.

```APIDOC
## navigate.sibling.prev

### Description
Navigate to the previous node in the current node's folder, wraps.

### Parameters
#### Path Parameters
- **node** (nvim_tree.api.Node?) - Required - directory or file
```

--------------------------------

### Customizing Default Mappings with nvim-tree API

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Archived

Use `api.config.mappings.default_on_attach(bufnr)` to apply default mappings within a custom `on_attach` function. This example shows how to override or add specific keybindings after the defaults are applied.

```lua
local function my_on_attach(bufnr)
  local api = require('nvim-tree.api')

  local function opts(desc)
    return { desc = 'nvim-tree: ' .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true }
  end

  api.config.mappings.default_on_attach(bufnr)

  vim.keymap.set('n', 'O', '', { buffer = bufnr })
  vim.keymap.del('n', 'O', { buffer = bufnr })
  vim.keymap.set('n', '<2-RightMouse>', '', { buffer = bufnr })
  vim.keymap.del('n', '<2-RightMouse>', { buffer = bufnr })
  vim.keymap.set('n', 'D', '', { buffer = bufnr })
  vim.keymap.del('n', 'D', { buffer = bufnr })
  vim.keymap.set('n', 'E', '', { buffer = bufnr })
  vim.keymap.del('n', 'E', { buffer = bufnr })

  vim.keymap.set('n', 'A', api.tree.expand_all, opts('Expand All'))
  vim.keymap.set('n', '?', api.tree.toggle_help, opts('Help'))
  vim.keymap.set('n', 'C', api.tree.change_root_to_node, opts('CD'))
  vim.keymap.set('n', 'P', function()
    local node = api.tree.get_node_under_cursor()
    print(node.absolute_path)
  end, opts('Print Node Path'))

  vim.keymap.set('n', 'Z', api.node.run.system, opts('Run System'))
end
```

--------------------------------

### Customizing nvim-tree.lua Highlight Groups

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/README.md

Customize highlight groups for nvim-tree.lua using Vimscript commands. This example sets foreground colors and styles for various file types and links to existing highlight groups.

```vim
  vim.cmd([[
      :hi      NvimTreeExecFile    guifg=#ffa0a0
      :hi      NvimTreeSpecialFile guifg=#ff80ff gui=underline
      :hi      NvimTreeSymlink     guifg=Yellow  gui=italic
      :hi link NvimTreeImageFile   Title
  ]])
```

--------------------------------

### nvim_tree.api.marks.navigate.select()

Source: https://github.com/nvim-tree/nvim-tree.lua/blob/master/doc/nvim-tree-lua.txt

Prompts the user to select a marked node. If a folder is selected, it will be focused. If a file is selected, it will be opened.

```APIDOC
## nvim_tree.api.marks.navigate.select()

### Description
Prompts for selection of a marked node, sorted by absolute paths. A folder will be focused, a file will be opened.
```

--------------------------------

### Custom Decorator Class Implementation

Source: https://github.com/nvim-tree/nvim-tree.lua/wiki/Decorators

Defines a custom decorator class 'MyDecorator' that extends `nvim_tree.api.decorator.UserDecorator`. It sets up custom icons and highlight groups, and overrides methods to apply these customizations to nodes named 'example'.

```lua
---@class (exact) MyDecorator: nvim_tree.api.decorator.UserDecorator
---@field private my_icon1 nvim_tree.api.HighlightedString
---@field private my_icon2 nvim_tree.api.HighlightedString
---@field private my_icon_node nvim_tree.api.HighlightedString
---@field private my_highlight_group string
local MyDecorator = require("nvim-tree.api").decorator.UserDecorator:extend()

---Mandatory constructor  :new()  will be called once per tree render, with no arguments.
function MyDecorator:new()
  self.enabled            = true
  self.highlight_range    = "name"
  self.icon_placement     = "after"

  -- create your icons and highlights once, applied to every node
  self.my_icon1           = { str = "1", hl = { "DiffAdd" } }
  self.my_icon2           = { str = "2", hl = { "DiffText" } }
  self.my_icon_node       = { str = "N", hl = { "Error" } }
  self.my_highlight_group = "IncSearch"

  -- Define the icon signs only once
  -- Only needed if you are using icon_placement = "signcolumn"
  -- self:define_sign(self.my_icon1)
  -- self:define_sign(self.my_icon2)
end

---Override node icon
---@param node nvim_tree.api.Node
---@return nvim_tree.api.HighlightedString? icon_node
function MyDecorator:icon_node(node)
  if node.name == "example" then
    return self.my_icon_node
  else
    return nil
  end
end

---Return two icons for DecoratorIconPlacement "after"
---@param node nvim_tree.api.Node
---@return nvim_tree.api.HighlightedString[]? icons
function MyDecorator:icons(node)
  if node.name == "example" then
    return { self.my_icon1, self.my_icon2, }
  else
    return nil
  end
end

---Exactly one highlight group for DecoratorHighlightRange "name"
---@param node nvim_tree.api.Node
---@return string? highlight_group
function MyDecorator:highlight_group(node)
  if node.name == "example" then
    return self.my_highlight_group
  else
    return nil
  end
end

return MyDecorator
```