barrettruth/canola.nvim

Watch

Enhanced User autocmd events with rich data fields #32

New issue

Closed

opened 2026-09-21 18:54:21 +00:00 by barrettruth · 1 comment

barrettruth commented

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

Owner

Original issue: barrettruth/canola.nvim#182
Original author: barrettruth
Original date: 2026-03-18T20:30:59Z

Overview

v1.1 replaces all hook functions that were in setup() with User autocmds, and enriches the existing notification events with richer data payloads. This issue tracks the full event surface for v1.1.

Renamed existing events

The three events from oil.nvim are renamed and given richer data fields.

`CanolaEnter` (was `OilEnter`)

Fires once when an oil buffer is first loaded.

-- ev.data
{
  buf    = <bufnr>,
  url    = "oil:///home/user/projects/",
  scheme = "oil",
  dir    = "/home/user/projects/",
}

`CanolaReadPost` (was `OilReadPost`)

Fires after every successful render of an oil buffer.

-- ev.data
{
  buf         = <bufnr>,
  url         = "oil:///home/user/projects/",
  entry_count = 12,
  first       = false,
}

first is true on the initial render, false on subsequent refreshes.

`CanolaMutationComplete` (was `OilMutationComplete`)

Fires after all mutations in a save cycle have been applied.

-- ev.data
{
  actions = {
    { type = "create", url = "oil:///home/user/projects/", filename = "new.lua" },
    { type = "delete", url = "...", filename = "old.lua" },
    { type = "move",   src_url = "...", dest_url = "..." },
    { type = "copy",   src_url = "...", dest_url = "..." },
  },
}

Each entry in actions mirrors the internal action format from the mutator pipeline.

New hook events

These replace callback functions that were previously set in setup(). The pattern is uniform: ev.data carries mutable fields, and the callback signals intent by writing back into ev.data.

`CanolaGitAdd` / `CanolaGitMv` / `CanolaGitRm`

Replaces git.add, git.mv, git.rm in setup(). Set ev.data.result = true to enable the git operation; leave it false to skip.

-- CanolaGitAdd: ev.data
{ path = "/abs/path/to/file.lua", result = false }

-- CanolaGitMv: ev.data
{ src = "/abs/path/old.lua", dest = "/abs/path/new.lua", result = false }

-- CanolaGitRm: ev.data
{ path = "/abs/path/to/file.lua", result = false }

Example handler:

vim.api.nvim_create_autocmd("User", {
  pattern = { "CanolaGitAdd", "CanolaGitMv", "CanolaGitRm" },
  callback = function(ev)
    ev.data.result = true
  end,
})

`CanolaFloatConfig`

Replaces float.override in setup(). The callback receives the fully-resolved nvim_open_win config and may mutate it in place.

-- ev.data
{ conf = { relative = "editor", width = 80, height = 24, ... } }

Example — force the float to always be full-width:

vim.api.nvim_create_autocmd("User", {
  pattern = "CanolaFloatConfig",
  callback = function(ev)
    ev.data.conf.width = vim.o.columns
  end,
})

`CanolaWinTitle`

Replaces float.get_win_title in setup(). Set ev.data.title to override the window title string.

-- ev.data
{ winid = <winid>, title = "/home/user/projects/" }

Example — show only the last path component:

vim.api.nvim_create_autocmd("User", {
  pattern = "CanolaWinTitle",
  callback = function(ev)
    ev.data.title = vim.fn.fnamemodify(ev.data.title, ":t")
  end,
})

`CanolaPreviewDisable`

Replaces preview_win.disable_preview in setup(). Set ev.data.result = true to suppress the preview for the given file.

-- ev.data
{ filename = "largefile.bin", result = false }

Example — disable preview for files larger than 1 MB:

vim.api.nvim_create_autocmd("User", {
  pattern = "CanolaPreviewDisable",
  callback = function(ev)
    local stat = vim.uv.fs_stat(ev.data.filename)
    if stat and stat.size > 1024 * 1024 then
      ev.data.result = true
    end
  end,
})

Init tier refactor

To support zero-setup()-call usage (i.e. vim.g.canola set before the plugin loads, no explicit require('oil').setup()), autocmd registration is split into two tiers.

Tier 1 — `plugin/canola.lua` (always-on, fires at startup)

Registered unconditionally when the plugin file is sourced:

BufReadCmd oil://* — core buffer loading handler
BufAdd — directory hijacking (replaces netrw for local dirs)
ColorScheme — re-applies highlight groups after colorscheme changes
vim.filetype.add — registers the oil filetype

These must be up before any config is resolved because Neovim may fire BufReadCmd before the user's init.lua finishes (e.g. nvim /some/dir).

Tier 2 — registered after config is resolved

Registered once config has been merged from vim.g.canola or setup():

VimEnter — default_to_float handling (open a float when Neovim starts on a directory)
SessionLoadPost — session restore compatibility
WinNew — float geometry recalculation on window resize
BufLeave / BufEnter pairs — cursor save/restore, modifiable guards
BufNew — SCP path warning (netrw conflict)

An _initialized guard prevents double-registration if setup() is called after vim.g.canola has already triggered tier-2 init.

The practical result: users who set vim.g.canola before lazy.nvim or packpath loads canola get a fully working plugin with no setup() call required.

> Original issue: barrettruth/canola.nvim#182 > Original author: `barrettruth` > Original date: 2026-03-18T20:30:59Z ## Overview v1.1 replaces all hook functions that were in `setup()` with User autocmds, and enriches the existing notification events with richer data payloads. This issue tracks the full event surface for v1.1. --- ## Renamed existing events The three events from oil.nvim are renamed and given richer `data` fields. ### `CanolaEnter` (was `OilEnter`) Fires once when an oil buffer is first loaded. ```lua -- ev.data { buf = <bufnr>, url = "oil:///home/user/projects/", scheme = "oil", dir = "/home/user/projects/", } ``` ### `CanolaReadPost` (was `OilReadPost`) Fires after every successful render of an oil buffer. ```lua -- ev.data { buf = <bufnr>, url = "oil:///home/user/projects/", entry_count = 12, first = false, } ``` `first` is `true` on the initial render, `false` on subsequent refreshes. ### `CanolaMutationComplete` (was `OilMutationComplete`) Fires after all mutations in a save cycle have been applied. ```lua -- ev.data { actions = { { type = "create", url = "oil:///home/user/projects/", filename = "new.lua" }, { type = "delete", url = "...", filename = "old.lua" }, { type = "move", src_url = "...", dest_url = "..." }, { type = "copy", src_url = "...", dest_url = "..." }, }, } ``` Each entry in `actions` mirrors the internal action format from the mutator pipeline. --- ## New hook events These replace callback functions that were previously set in `setup()`. The pattern is uniform: `ev.data` carries mutable fields, and the callback signals intent by writing back into `ev.data`. ### `CanolaGitAdd` / `CanolaGitMv` / `CanolaGitRm` Replaces `git.add`, `git.mv`, `git.rm` in `setup()`. Set `ev.data.result = true` to enable the git operation; leave it `false` to skip. ```lua -- CanolaGitAdd: ev.data { path = "/abs/path/to/file.lua", result = false } -- CanolaGitMv: ev.data { src = "/abs/path/old.lua", dest = "/abs/path/new.lua", result = false } -- CanolaGitRm: ev.data { path = "/abs/path/to/file.lua", result = false } ``` Example handler: ```lua vim.api.nvim_create_autocmd("User", { pattern = { "CanolaGitAdd", "CanolaGitMv", "CanolaGitRm" }, callback = function(ev) ev.data.result = true end, }) ``` ### `CanolaFloatConfig` Replaces `float.override` in `setup()`. The callback receives the fully-resolved `nvim_open_win` config and may mutate it in place. ```lua -- ev.data { conf = { relative = "editor", width = 80, height = 24, ... } } ``` Example — force the float to always be full-width: ```lua vim.api.nvim_create_autocmd("User", { pattern = "CanolaFloatConfig", callback = function(ev) ev.data.conf.width = vim.o.columns end, }) ``` ### `CanolaWinTitle` Replaces `float.get_win_title` in `setup()`. Set `ev.data.title` to override the window title string. ```lua -- ev.data { winid = <winid>, title = "/home/user/projects/" } ``` Example — show only the last path component: ```lua vim.api.nvim_create_autocmd("User", { pattern = "CanolaWinTitle", callback = function(ev) ev.data.title = vim.fn.fnamemodify(ev.data.title, ":t") end, }) ``` ### `CanolaPreviewDisable` Replaces `preview_win.disable_preview` in `setup()`. Set `ev.data.result = true` to suppress the preview for the given file. ```lua -- ev.data { filename = "largefile.bin", result = false } ``` Example — disable preview for files larger than 1 MB: ```lua vim.api.nvim_create_autocmd("User", { pattern = "CanolaPreviewDisable", callback = function(ev) local stat = vim.uv.fs_stat(ev.data.filename) if stat and stat.size > 1024 * 1024 then ev.data.result = true end end, }) ``` --- ## Init tier refactor To support zero-`setup()`-call usage (i.e. `vim.g.canola` set before the plugin loads, no explicit `require('oil').setup()`), autocmd registration is split into two tiers. ### Tier 1 — `plugin/canola.lua` (always-on, fires at startup) Registered unconditionally when the plugin file is sourced: - `BufReadCmd oil://*` — core buffer loading handler - `BufAdd` — directory hijacking (replaces netrw for local dirs) - `ColorScheme` — re-applies highlight groups after colorscheme changes - `vim.filetype.add` — registers the `oil` filetype These must be up before any config is resolved because Neovim may fire `BufReadCmd` before the user's `init.lua` finishes (e.g. `nvim /some/dir`). ### Tier 2 — registered after config is resolved Registered once config has been merged from `vim.g.canola` or `setup()`: - `VimEnter` — `default_to_float` handling (open a float when Neovim starts on a directory) - `SessionLoadPost` — session restore compatibility - `WinNew` — float geometry recalculation on window resize - `BufLeave` / `BufEnter` pairs — cursor save/restore, modifiable guards - `BufNew` — SCP path warning (netrw conflict) An `_initialized` guard prevents double-registration if `setup()` is called after `vim.g.canola` has already triggered tier-2 init. The practical result: users who set `vim.g.canola` before `lazy.nvim` or `packpath` loads canola get a fully working plugin with no `setup()` call required.

barrettruth added this to the v1.1 milestone

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

barrettruth closed this issue

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

barrettruth commented

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

Author

Owner

Original comment: barrettruth/canola.nvim#182, comment 4101834752
Original author: barrettruth
Original date: 2026-03-21T02:08:16Z

Implemented in #228.

> Original comment: barrettruth/canola.nvim#182, comment 4101834752 > Original author: `barrettruth` > Original date: 2026-03-21T02:08:16Z Implemented in #228.