New "Open At Startup" Mechanisms

[alex-courtis]

open_on_setup.* have been deprecated in favour of self serve mechanisms: Open At Startup. Please start a Discussion if you have an questions or concerns.

The existing startup mechanisms such an open_on_setup are problematic, with recent changes resulting in many regressions #1668.

The options are nonatomic and difficult (sometimes impossible) to configure for each use case.

There are often race conditions around startup and events with vim itself and other plugins.

A new mechanisms to specify startup behaviour with more granularity is under way.

The existing mechanism will be retained if an original configuration options such as open_on_setup is specified, however the user will be notified of the new mechanism on startup and pointed to a wiki page to explain migration to the new.

Update 20230109: the new mechanism will be a set of recipes for the user to control behaviour programatically, along with the events to allow this.

Update 20230129: existing configuration will be deprecated in favour of a self serve mechanism: Open At Startup

[alex-courtis]

Draft:

on_start = {
    open = {
      always = false,
      directory = true,
      unnamed = false,
      empty = false,
      file = true,
      ignore_filetype = {
        "gitcommit"
      },
    },
    focus_tree = {
      always = true,
      unnamed = false,
      empty = false,
      file = false,
    },
  }

unnamed is a buffer with empty bufname().

empty is a buffer with a name but filereadable(bufname()) == 0. Needs a better name.

The new configuration could go in an alternate nvim-tree.on_enter to be used if the user has specified on_start.

[alex-courtis]

LunarVim must be notified prior to release so that they may refactor ignore_ft: https://github.com/LunarVim/LunarVim/blob/36c8bdee9ff59a0a63c1edfc445b5eb2886cf246/lua/lvim/core/nvimtree.lua#L9

[alex-courtis]

Allow on_start to be nil for no action on startup.

Users may take their own startup actions on Event.Ready

[alex-courtis]

There are some difficulties here:

1. There are many options however they may still not satisfy all users
2. The issue of timing still remains: nvim-tree setup time is too early and VimEnter time still may be too early depending on other plugins / automation
3. netrw is still an issue

A pragmatic solution may be to remove this functionality and provide startup recipes. The user can control their own startup order and deal with netrw. We successfully removed the close-on-quit functionality as it was equally problematic.

I am beginning to see why NerdTree never provided this functionality, only recipes.

Your wisdom would be gratefully appreciated @gegoune

Some recipes that users can mix and match:

vim.api.nvim_create_autocmd({ "VimEnter" }, { group = group, callback = M.startup })

-- open_on_setup unnamed
function M.startup0(data)

  -- ordinary buffers with no name only
  if vim.bo[data.buf].buftype == "" and data.file == "" then
    api.tree.open()
  end
end

-- open_on_setup_file, ignore_ft_on_setup
function M.startup1(data)

  -- only files
  if vim.fn.filereadable(data.file) ~= 1 then
    return
  end

  -- do nothing for git commit messages
  if vim.bo[data.buf].ft == "gitcommit" then
    return
  end

  -- open the tree
  api.tree.open()
end

-- open_on_setup_file, focus buffer
function M.startup2(data)

  -- window of the startup buffer
  local winid = vim.fn.bufwinid(data.buf)

  -- open the tree
  api.tree.open()

  -- restore focus
  vim.api.nvim_set_current_win(winid)
end

-- open_on_setup (directory) hijack disabled
function M.startup3(data)

  -- only open for directories
  if vim.fn.isdirectory(data.file) == 0 then
    return
  end

  -- window of the startup buffer
  local winid = vim.fn.bufwinid(data.buf)

  -- open the tree
  api.tree.open()

  -- restore focus
  vim.api.nvim_set_current_win(winid)

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

[gegoune]

I am in favour of removal given enough API is provided for users to implement their own automation. I am bit biased though - never had that option enabled.

[alex-courtis]

The only interesting bits remaining are:

• Startup with an existing session: we will need to open the tree in the previous window proper session restoration #1742
• Hijack directory may be directly applied at startup
• Hijack netrw, as some people still use it

[alex-courtis]

#1918 would be useful, allowing the user to replace the startup buffer.

[harmtemolder]

@alex-courtis Thanks for pointing me from #176

This is the use case I was hoping to solve with the old ignore_ft_on_setup:

When I open a file through sudoedit it copies the file to /var/tmp and opens that copy instead. I like having the tree open on any other file from any other directory, to provide me with context. But I'd like to prevent it from opening with files within /var/tmp. Is that something that would be possible with this new startup mechanism?

[alex-courtis]

When I open a file through sudoedit it copies the file to /var/tmp and opens that copy instead. I like having the tree open on any other file from any other directory, to provide me with context. But I'd like to prevent it from opening with files within /var/tmp. Is that something that would be possible with this new startup mechanism?

Unfortunately nothing is complete and documented yet. It's time to pull the trigger on this and make it official via wiki / help.

You could do something like the above VimEnter examples:

function M.startup1(data)

  -- only files
  if vim.fn.filereadable(data.file) ~= 1 then
    return
  end

  -- do nothing for undesirable file paths
  if data.file starts with /var/tmp then
    return
  end

  -- OR do nothing for undesirable directories
  if vim.fn.getcwd() == "/var/tmp" then
    return
 end

  -- open the tree
  api.tree.open()
end

[alex-courtis]

More preparation: #1946

[alex-courtis]

Wiki: Open At Startup

Deprecation PR: #1951

[danielmirzad]

Can we somehow disable the
[NvimTree] "open_on_setup behaviour has been deprecated, please see https://github.com/nvim-tree/nvim-tree.lua/wiki/Open-At-Startup" Press ENTER or type command to continue
Message?

[gegoune]

Please have a look at https://github.com/nvim-tree/nvim-tree.lua/pull/2122/files and remove those options from your configuration.