barrettruth/canola.nvim

Watch

vim.g.canola config system #16

New issue

Closed

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

barrettruth commented

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

Owner

Original issue: barrettruth/canola.nvim#82
Original author: barrettruth
Original date: 2026-03-07T03:34:26Z

Overview

vim.g.canola is the canonical configuration mechanism for canola v1.1. It replaces require('canola').setup({}) entirely — there is no setup() call at all, and no compat shim. Configuration lives in vim.g.canola, which Neovim evaluates before any plugin loads, making lazy-loading and session restore work without any extra configuration from the user.

plugin/canola.lua is the entry point. It reads vim.g.canola at Neovim startup and calls the internal initializer. Users never call require('canola') for configuration — only for setter API functions (see below).

Serializable config fields

All of the following accept the same types they did under setup(). Strings, numbers, booleans, and tables of those are fully serializable and belong directly in vim.g.canola.

Top-level options

default_file_explorer (boolean, default true) — take over directory buffers
default_to_float (boolean, default false) — always open in a floating window
columns (list of column specs, default {"icon"}) — see :help canola-columns
buf_options (table) — buffer-local options; default sets buflisted=false, bufhidden="hide"
win_options (table) — window-local options; default sets wrap=false, signcolumn="no", cursorcolumn=false, foldcolumn="0", spell=false, list=false, conceallevel=3, concealcursor="nvic"
delete_to_trash (boolean, default false) — send deleted files to the trash
cleanup_buffers_on_delete (boolean, default false) — wipe open buffers for deleted files
skip_confirm_for_simple_edits (boolean, default false) — skip confirmation for simple ops
skip_confirm_for_delete (boolean, default false) — skip confirmation when all actions are deletes
prompt_save_on_select_new_entry (boolean, default true) — prompt before navigating away with unsaved changes
auto_save_on_select_new_entry (boolean, default false) — auto-save instead of prompting
cleanup_delay_ms (integer, default 2000) — ms before hidden oil buffers are wiped; false disables
constrain_cursor ("editable", "name", or false, default "editable") — cursor confinement
watch_for_changes (boolean, default false) — reload oil when the filesystem changes
use_default_keymaps (boolean, default true) — whether the built-in keymaps are registered
new_file_mode (integer, default 420 = 0644) — permission mode for created files
new_dir_mode (integer, default 493 = 0755) — permission mode for created directories
extra_scp_args (list of strings) — extra args passed to SCP
extra_s3_args (list of strings) — extra args passed to aws s3
extra_curl_args (list of strings) — extra args passed to curl for FTP
ssh_hosts (table, keyed by hostname) — per-host extra_scp_args override
s3_buckets (table, keyed by bucket name) — per-bucket extra_s3_args override
ftp_hosts (table, keyed by hostname) — per-host extra_curl_args override

lsp_file_methods

enabled (boolean, default true)
timeout_ms (integer, default 1000)
autosave_changes (boolean or "unmodified", default false)

view_options

show_hidden (boolean, default false)
show_hidden_when_empty (boolean, default false)
natural_order (boolean or "fast", default "fast")
case_insensitive (boolean, default false)
sort (list of {column, "asc"|"desc"} pairs)

keymaps

Each entry is a string key mapped to either a string action name ("actions.select") or a table {action, mode = "n", opts = {...}}. Callbacks are not permitted in vim.g — see Setter API below for keymap callbacks.

float

padding (integer, default 2)
max_width (integer or float 0–1, default 0)
max_height (integer or float 0–1, default 0)
border (string or list)
win_options (table)
preview_split ("auto", "left", "right", "above", "below", default "auto")

preview_win

update_on_cursor_moved (boolean, default true)
preview_method ("load", "scratch", or "fast_scratch", default "fast_scratch")
max_file_size (number in MB, default 10)
win_options (table)

confirmation

max_width, min_width, width, max_height, min_height, height, border, win_options

progress

max_width, min_width, width, max_height, min_height, height, border, minimized_border, win_options

ssh

border

keymaps_help

border

What is NOT in vim.g.canola

vim.g only holds Lua-serializable values. Functions cannot be stored there. These config fields are function-valued and use the setter API instead:

Oil option	Setter
`view_options.is_hidden_file`	`require('canola').set_is_hidden_file(fn)`
`view_options.is_always_hidden`	`require('canola').set_is_always_hidden(fn)`
`view_options.highlight_filename`	`require('canola').set_highlight_filename(fn)`
`preview_win.disable_preview`	`require('canola').set_disable_preview(fn)`

Hook functions (git.add, git.mv, git.rm, float.override, float.get_win_title) are replaced by User autocmds. The exact event names are tracked in #182.

Entry point

plugin/canola.lua runs at startup. It reads vim.g.canola, merges it with defaults, and initializes the plugin. No require() call is needed from the user's config.

lazy.nvim integration

Because plugin/canola.lua handles initialization, lazy.nvim users set config via the init key, not opts:

{
  'barrettruth/canola.nvim',
  init = function()
    vim.g.canola = {
      columns = { 'icon', 'size' },
      delete_to_trash = true,
    }
  end,
}

The opts key is for setup() — since setup() is gone, opts does nothing in canola v1.1.

#199 — Drop setup() entirely (implementation issue)
#182 — User autocmd events (hook function replacements)
#1 — original vim.g.canola tracking issue

> Original issue: barrettruth/canola.nvim#82 > Original author: `barrettruth` > Original date: 2026-03-07T03:34:26Z ## Overview `vim.g.canola` is the canonical configuration mechanism for canola v1.1. It replaces `require('canola').setup({})` entirely — there is no `setup()` call at all, and no compat shim. Configuration lives in `vim.g.canola`, which Neovim evaluates before any plugin loads, making lazy-loading and session restore work without any extra configuration from the user. `plugin/canola.lua` is the entry point. It reads `vim.g.canola` at Neovim startup and calls the internal initializer. Users never call `require('canola')` for configuration — only for setter API functions (see below). ## Serializable config fields All of the following accept the same types they did under `setup()`. Strings, numbers, booleans, and tables of those are fully serializable and belong directly in `vim.g.canola`. **Top-level options** - `default_file_explorer` (boolean, default `true`) — take over directory buffers - `default_to_float` (boolean, default `false`) — always open in a floating window - `columns` (list of column specs, default `{"icon"}`) — see `:help canola-columns` - `buf_options` (table) — buffer-local options; default sets `buflisted=false`, `bufhidden="hide"` - `win_options` (table) — window-local options; default sets `wrap=false`, `signcolumn="no"`, `cursorcolumn=false`, `foldcolumn="0"`, `spell=false`, `list=false`, `conceallevel=3`, `concealcursor="nvic"` - `delete_to_trash` (boolean, default `false`) — send deleted files to the trash - `cleanup_buffers_on_delete` (boolean, default `false`) — wipe open buffers for deleted files - `skip_confirm_for_simple_edits` (boolean, default `false`) — skip confirmation for simple ops - `skip_confirm_for_delete` (boolean, default `false`) — skip confirmation when all actions are deletes - `prompt_save_on_select_new_entry` (boolean, default `true`) — prompt before navigating away with unsaved changes - `auto_save_on_select_new_entry` (boolean, default `false`) — auto-save instead of prompting - `cleanup_delay_ms` (integer, default `2000`) — ms before hidden oil buffers are wiped; `false` disables - `constrain_cursor` (`"editable"`, `"name"`, or `false`, default `"editable"`) — cursor confinement - `watch_for_changes` (boolean, default `false`) — reload oil when the filesystem changes - `use_default_keymaps` (boolean, default `true`) — whether the built-in keymaps are registered - `new_file_mode` (integer, default `420` = 0644) — permission mode for created files - `new_dir_mode` (integer, default `493` = 0755) — permission mode for created directories - `extra_scp_args` (list of strings) — extra args passed to SCP - `extra_s3_args` (list of strings) — extra args passed to `aws s3` - `extra_curl_args` (list of strings) — extra args passed to `curl` for FTP - `ssh_hosts` (table, keyed by hostname) — per-host `extra_scp_args` override - `s3_buckets` (table, keyed by bucket name) — per-bucket `extra_s3_args` override - `ftp_hosts` (table, keyed by hostname) — per-host `extra_curl_args` override **`lsp_file_methods`** - `enabled` (boolean, default `true`) - `timeout_ms` (integer, default `1000`) - `autosave_changes` (boolean or `"unmodified"`, default `false`) **`view_options`** - `show_hidden` (boolean, default `false`) - `show_hidden_when_empty` (boolean, default `false`) - `natural_order` (boolean or `"fast"`, default `"fast"`) - `case_insensitive` (boolean, default `false`) - `sort` (list of `{column, "asc"|"desc"}` pairs) **`keymaps`** Each entry is a string key mapped to either a string action name (`"actions.select"`) or a table `{action, mode = "n", opts = {...}}`. Callbacks are not permitted in `vim.g` — see Setter API below for keymap callbacks. **`float`** - `padding` (integer, default `2`) - `max_width` (integer or float 0–1, default `0`) - `max_height` (integer or float 0–1, default `0`) - `border` (string or list) - `win_options` (table) - `preview_split` (`"auto"`, `"left"`, `"right"`, `"above"`, `"below"`, default `"auto"`) **`preview_win`** - `update_on_cursor_moved` (boolean, default `true`) - `preview_method` (`"load"`, `"scratch"`, or `"fast_scratch"`, default `"fast_scratch"`) - `max_file_size` (number in MB, default `10`) - `win_options` (table) **`confirmation`** - `max_width`, `min_width`, `width`, `max_height`, `min_height`, `height`, `border`, `win_options` **`progress`** - `max_width`, `min_width`, `width`, `max_height`, `min_height`, `height`, `border`, `minimized_border`, `win_options` **`ssh`** - `border` **`keymaps_help`** - `border` ## What is NOT in vim.g.canola `vim.g` only holds Lua-serializable values. Functions cannot be stored there. These config fields are function-valued and use the setter API instead: | Oil option | Setter | |---|---| | `view_options.is_hidden_file` | `require('canola').set_is_hidden_file(fn)` | | `view_options.is_always_hidden` | `require('canola').set_is_always_hidden(fn)` | | `view_options.highlight_filename` | `require('canola').set_highlight_filename(fn)` | | `preview_win.disable_preview` | `require('canola').set_disable_preview(fn)` | Hook functions (`git.add`, `git.mv`, `git.rm`, `float.override`, `float.get_win_title`) are replaced by User autocmds. The exact event names are tracked in #182. ## Entry point `plugin/canola.lua` runs at startup. It reads `vim.g.canola`, merges it with defaults, and initializes the plugin. No `require()` call is needed from the user's config. ## lazy.nvim integration Because `plugin/canola.lua` handles initialization, lazy.nvim users set config via the `init` key, not `opts`: ```lua { 'barrettruth/canola.nvim', init = function() vim.g.canola = { columns = { 'icon', 'size' }, delete_to_trash = true, } end, } ``` The `opts` key is for `setup()` — since `setup()` is gone, `opts` does nothing in canola v1.1. ## Related - #199 — Drop `setup()` entirely (implementation issue) - #182 — User autocmd events (hook function replacements) - #1 — original `vim.g.canola` tracking issue

barrettruth added this to the v1.1 milestone

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

barrettruth closed this issue

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

barrettruth commented

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

Author

Owner

Original comment: barrettruth/canola.nvim#82, comment 4076155695
Original author: barrettruth
Original date: 2026-03-17T16:08:54Z

move oil-ssh, oil-s3, oil-ftp, etc. into separate backends

> Original comment: barrettruth/canola.nvim#82, comment 4076155695 > Original author: `barrettruth` > Original date: 2026-03-17T16:08:54Z move oil-ssh, oil-s3, oil-ftp, etc. into separate backends