refactor: migrate from setup() to vim.g.oil configuration #1

New issue

Closed

opened 2026-09-21 18:54:07 +00:00 by barrettruth · 0 comments

barrettruth commented

2026-09-21 18:54:07 +00:00

Owner

Original issue: barrettruth/canola.nvim#1
Original author: barrettruth
Original date: 2026-02-20T21:20:19Z

Problem

oil.nvim currently uses the require("oil").setup(opts) pattern for configuration. This requires an explicit function call at startup and prevents lazy.nvim's opts table from being merged declaratively before the plugin loads. It also means config is not accessible until setup() has run, and the setup function itself has accumulated backwards-compatibility shims that make it harder to maintain.

The Neovim ecosystem is trending toward vim.g.<plugin> for static configuration (e.g., vim.g.loaded_netrw). Plugins like snacks.nvim, lazy.nvim itself, and others have adopted this pattern.

Solution

Migrate configuration to vim.g.oil:

vim.g.oil = {
  default_file_explorer = true,
  columns = { "icon" },
  keymaps = {
    ["<CR>"] = "actions.select",
    ["-"] = { "actions.parent", mode = "n" },
  },
  -- ...
}

This would:

Allow lazy.nvim users to set opts on the plugin spec and have it automatically assigned to vim.g.oil without needing a config function
Make configuration available before any oil code runs
Simplify the setup path — config.lua reads from vim.g.oil and merges with defaults, no explicit setup() call needed
Keep require("oil").setup(opts) working as a compatibility shim that writes to vim.g.oil and triggers initialization

Migration path

Phase 1: Add vim.g.oil support alongside setup(). If both are provided, setup() wins.
Phase 2: Deprecate setup() with a warning.
Phase 3: Remove setup() in a future major version.

Considerations

vim.g.oil is a plain table — no metatables, no functions. Callbacks like is_hidden_file, highlight_filename, and view_options.sort are functions in the current config. These would need to remain in setup() or use a separate require("oil").configure() for the function-valued options.
Alternatively, function-valued config could be set via require("oil").on.hidden_file = function(...) end or similar.
The keymaps table contains both string references and function values, which also can't live in vim.g.

This is a non-trivial refactor that touches config.lua, init.lua, and all documentation. It should be planned carefully to avoid breaking existing configs.

> Original issue: barrettruth/canola.nvim#1 > Original author: `barrettruth` > Original date: 2026-02-20T21:20:19Z ## Problem oil.nvim currently uses the `require("oil").setup(opts)` pattern for configuration. This requires an explicit function call at startup and prevents lazy.nvim's `opts` table from being merged declaratively before the plugin loads. It also means config is not accessible until `setup()` has run, and the setup function itself has accumulated backwards-compatibility shims that make it harder to maintain. The Neovim ecosystem is trending toward `vim.g.<plugin>` for static configuration (e.g., `vim.g.loaded_netrw`). Plugins like snacks.nvim, lazy.nvim itself, and others have adopted this pattern. ## Solution Migrate configuration to `vim.g.oil`: ```lua vim.g.oil = { default_file_explorer = true, columns = { "icon" }, keymaps = { ["<CR>"] = "actions.select", ["-"] = { "actions.parent", mode = "n" }, }, -- ... } ``` This would: 1. Allow lazy.nvim users to set `opts` on the plugin spec and have it automatically assigned to `vim.g.oil` without needing a `config` function 2. Make configuration available before any oil code runs 3. Simplify the setup path — `config.lua` reads from `vim.g.oil` and merges with defaults, no explicit `setup()` call needed 4. Keep `require("oil").setup(opts)` working as a compatibility shim that writes to `vim.g.oil` and triggers initialization ### Migration path - Phase 1: Add `vim.g.oil` support alongside `setup()`. If both are provided, `setup()` wins. - Phase 2: Deprecate `setup()` with a warning. - Phase 3: Remove `setup()` in a future major version. ### Considerations - `vim.g.oil` is a plain table — no metatables, no functions. Callbacks like `is_hidden_file`, `highlight_filename`, and `view_options.sort` are functions in the current config. These would need to remain in `setup()` or use a separate `require("oil").configure()` for the function-valued options. - Alternatively, function-valued config could be set via `require("oil").on.hidden_file = function(...) end` or similar. - The keymaps table contains both string references and function values, which also can't live in `vim.g`. This is a non-trivial refactor that touches config.lua, init.lua, and all documentation. It should be planned carefully to avoid breaking existing configs.

barrettruth closed this issue

2026-09-21 18:54:07 +00:00

barrettruth referenced this issue

2026-09-21 18:54:08 +00:00

refactor: "own" everything #5

barrettruth referenced this issue

2026-09-21 18:54:11 +00:00

vim.g.canola config system #16

barrettruth referenced this issue

2026-09-21 18:54:23 +00:00

Drop setup() entirely #39