Open At Startup

Opening nvim-tree At Neovim Startup

It can be useful to open nvim-tree when you start neovim.

nvim-tree cannot reliably do this on setup due to race conditions at startup and the overwhelming variety of user and plugin configurations.

Behaviour at startup is also a quite personal choice, with no means to provide mechanisms to suit everyone.

Hence we now leave it to you, the power user, to configure your startup behaviour.

Open-on-startup was handled via the deprecated options: open_on_setup, open_on_setup_file, ignore_ft_on_setup and ignore_buffer_on_setup. Please remove those options from your configuration.

Please open a Discussion if you have any questions, issues or concerns.

Additional Recipes would be gratefully appreciated - please edit this page!

Recipes

The VimEnter event should be used for the startup functionality: nvim-tree setup will have been called and other plugins will have started. It's the best time for you to define the behaviour you desire.

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

The VimEnter callback will be passed a table with the following pertinent data:

buf the buffer number of the currently focused buffer

file the name of the buffer

event always VimEnter

Always Open nvim-tree

local function open_nvim_tree()

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

Open For Files And [No Name] Buffers

local function open_nvim_tree(data)

  -- buffer is a real file on the disk
  local real_file = vim.fn.filereadable(data.file) == 1

  -- buffer is a [No Name]
  local no_name = data.file == "" and vim.bo[data.buf].buftype == ""

  if not real_file and not no_name then
    return
  end

  -- open the tree, find the file but don't focus it
  require("nvim-tree.api").tree.toggle({ focus = false, find_file = true, })
end

Open For Directories And Change Neovim's Directory

Current window:

local function open_nvim_tree(data)

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

  if not directory then
    return
  end

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

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

New window:

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

Useful API

Useful API for startup. See :help nvim-tree-api for full details.

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

require("nvim-tree.api").tree.change_root("/some/path")

require("nvim-tree.api").tree.focus()

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

Useful Tests

Following are some tests that can help you make your decisions:

An actual, real file on the disk:

vim.fn.filereadable(data.file) == 1

A directory:

vim.fn.isdirectory(data.file) == 1

&buftype:

vim.bo[data.buf].buftype

&filetype:

vim.bo[data.buf].ft

A [No Name] new:

data.file == "" and vim.bo[data.buf].buftype == ""

Legacy Migration

The following legacy options, soon to be removed, defined behaviour to open nvim-tree when setup was called. Please remove these options.

*nvim-tree.open_on_setup*
Will automatically open the tree when running setup if startup buffer is
a directory, is empty or is unnamed. nvim-tree window will be focused.
  Type: `boolean`, Default: `false`

*nvim-tree.open_on_setup_file*
Will automatically open the tree when running setup if startup buffer is a file.
File window will be focused.
File will be found if update_focused_file is enabled.
  Type: `boolean`, Default: `false`

*nvim-tree.ignore_buffer_on_setup*
Will ignore the buffer, when deciding to open the tree on setup.
  Type: `boolean`, Default: `false`

*nvim-tree.ignore_ft_on_setup*
List of filetypes that will prevent `open_on_setup` to open.
You can use this option if you don't want the tree to open
in some scenarios (eg using vim startify).
  Type: {string}, Default: `{}`

Following are some recipes you can drop-in to replicate these options.

open_on_setup

local function open_nvim_tree(data)

  -- buffer is a [No Name]
  local no_name = data.file == "" and vim.bo[data.buf].buftype == ""

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

  if not no_name and not directory then
    return
  end

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

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

open_on_setup_file

local function open_nvim_tree(data)

  -- buffer is a real file on the disk
  local real_file = vim.fn.filereadable(data.file) == 1

  -- buffer is a [No Name]
  local no_name = data.file == "" and vim.bo[data.buf].buftype == ""

  -- only files please
  if not real_file and not no_name then
    return
  end

  -- open the tree but don't focus it
  require("nvim-tree.api").tree.toggle({ focus = false })
end

open_on_setup_file and ignore_ft_on_setup

local function open_nvim_tree(data)
  local IGNORED_FT = {
    "gitcommit",
  }

  -- buffer is a real file on the disk
  local real_file = vim.fn.filereadable(data.file) == 1

  -- buffer is a [No Name]
  local no_name = data.file == "" and vim.bo[data.buf].buftype == ""

  -- &ft
  local filetype = vim.bo[data.buf].ft

  -- only files please
  if not real_file and not no_name then
    return
  end

  -- skip ignored filetypes
  if vim.tbl_contains(IGNORED_FT, filetype) then
    return
  end

  -- open the tree but don't focus it
  require("nvim-tree.api").tree.toggle({ focus = false })
end

open_on_setup.* and ignore_buffer_on_setup

local function open_nvim_tree()

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