Getting Started

Fork this repo and read through CONTRIBUTING.md

If you're new to Nvim lua programming, take a look at Neovim Plugins Challenges (thanks @uanela) for some excercises to get you started on a variety of APIs, options and use cases.

Clean Room

It is strongly advised to develop in a "clean room" using the minimal configuration, so that your plugins and other customisations don't interfere with nvim-tree.

See bug report for some background on the minimal configuration.

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

Change

      "nvim-tree/nvim-tree.lua",

to your fork e.g.

      "~/src/nvim-tree.lua.myfork",

Run with

nvim -nu /tmp/nvt-min.lua

Lua Language Server

luals is strongly advised during development. It provides autocomplete, navigation etc. as well as diagnostics.

scripts/luals-check.sh is run during CI and must return no issues.

Setup

neovim/nvim-lspconfig is the "official" lsp manager.

See luals quickstart config

Minimal example:

local lspconfig = require("lspconfig")

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

See @alex-courtis language server setup:

• nvim-lspconfig

Formatting

EmmyLuaCodeStyle is the default lua-language-server formatter. It's CodeFormat utility is used for CI and CLI styling.

You can format via the standard vim.lsp.buf.format()

A convenience function and mapping:

local function format()
  -- use LSP formatting if available for this buffer
  for _, client in ipairs(vim.lsp.get_clients({ bufnr = 0 })) do
    if client.server_capabilities.documentFormattingProvider then
      vim.lsp.buf.format()
      return
    end
  end

  -- fall back to vim native
  vim.cmd([[silent! norm! gg=G``]])
end

vim.keymap.set("n", "<leader>f", format, { desc = "format" })

Completion Engine

hrsh7th/nvim-cmp provides completion and integrates with the language server via hrsh7th/cmp-nvim-lsp

Neovim 0.10+ provides snippet support, notably parameters.

See @alex-courtis language server and completion setup: <C-space> to complete, <tab> to navigate parameters:

• nvim-lspconfig and cmp-nvim-lsp
• nvim-cmp
• snippets mappings

Alternative Setup: Native neovim Configuration

neovim/nvim-lspconfig plugin not required, needs explicit setup.

Start lua-language-server via :help vim.lsp.start when a buffer's &filetype is set:

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,
})

name and root_dir identifies the instance, which will be joined on vim.lsp.start, rather than starting a new instance.

root_dir searches up the filesystem from the open buffer until nvim-tree's .luarc.json is found.

Debug Logging

Using print can be a little problematic when there are many messages.

See :help nvim-tree.log

Enable dev type:

    log = {
      enable = true,
      truncate = true,
      types = {
        all = false,
        config = false,
        copy_paste = false,
        dev = true,
        diagnostics = false,
        git = false,
        profile = false,
        watcher = false,
      },
    },

Require the logger:

local log = require "nvim-tree.log"

Add string.format style log lines e.g.:

log.line("dev", "do_copy uid %d '%s' -> '%s'", source_stats.uid, source, destination)

Watch:

tail -F ${XDG_STATE_HOME}/nvim/nvim-tree.log

Re-running setup

Setup may be run many times by the user and you are encouraged to test it.

OS Feature Flags

OS may be tested via utils.lua convenience fields.

Windows

Please ensure that windows specific fixes and features are behind the appropriate feature flag(s).

e.g.

--- path is an executable file or directory
---@param absolute_path string
---@return boolean
function M.is_executable(absolute_path)
  if M.is_windows or M.is_wsl then
    --- executable detection on windows is buggy and not performant hence it is disabled
    return false
  else
    return vim.loop.fs_access(absolute_path, "X") or false
  end

Feature Flag Enumeration

Script run by various users ~2023 10 to evaluate vim.fn.has for all known feature flags from src/nvim/eval/funcs.c

Notable:

Linux

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

WSL

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

PowerShell

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

nvim-qt also: gui_running=1

macOS

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

Cygwin

Unknown

msys2

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