Problem: upstream issue #637 (inconsistent symlink resolution) is
unresolved in our tracker.
Solution: mark as not actionable. Reporter confirmed the issue does
not reproduce on stable neovim (v0.11.2), only on nightly.
Problem: upstream issue #636 (Telescope picker opens file in wrong
split) is unresolved in our tracker.
Solution: mark as not actionable. Cannot reproduce with default
Telescope configuration — file correctly opens in the active canola
split. Likely user-specific Telescope config or window picker plugin.
Problem: at the filesystem root (`/`), `actions.parent` triggers a
full `vim.cmd.edit()` and async re-render cycle even though the parent
of `/` is `/`.
Solution: in `canola.open()`, return early when `parent_url` equals
the current buffer name.
Closes#108.
* fix(select): redraw screen after buffer switch
Problem: `select` opens files inside a `vim.schedule_wrap` callback
from `normalize_url`. Scheduled `FileType` autocmds (e.g. treesitter
parsing) queue onto the same batch, blocking the screen update. The
oil buffer stays visible until the heavy work finishes.
Solution: call `vim.cmd.redraw()` after the buffer switch to flush
the screen before any queued scheduled callbacks run. Matches the
behavior of plain `:e`.
* docs(upstream): mark #699 fixed (#106)
docs(upstream): mark #609 not actionable (#105)
Problem: upstream issue #609 (cursor not placed on file when jumped
via Snacks.nvim picker) is confirmed Windows-only by multiple
reporters. stevearc cannot reproduce on Linux.
Solution: mark as not actionable in the upstream tracker.
Problem: `constrain_cursor` only fired on `CursorMoved` and
`ModeChanged`, so arrow key navigation in insert mode could move
the cursor into the concealed ID prefix area.
Solution: add `CursorMovedI` to the autocmd event list. The
`constrain_cursor()` function is already mode-agnostic.
Problem: issues were split across four separate sections by status,
requiring moves between sections on every status change.
Solution: merge all issues into one `## Issues` table sorted by number
with an inline status column. Update digest script heading and row
format to match.
Problem: the upstream tracker had duplicate entries across tables,
fragile commit hash references, a 108-row flat table mixing all
statuses, and inconsistent formatting.
Solution: merge PR tables into one, split issues by status (fixed,
resolved, open, not actionable), drop all commit hashes in favor of
stable PR numbers, and eliminate duplication so each entry appears
exactly once.
* feat: add `toggle()` API for regular windows
Problem: `toggle_float()` and `toggle_split()` exist but there is no
`toggle()` for regular windows, forcing users to write their own
filetype-checking wrapper.
Solution: add `M.toggle()` that delegates to `close()` or `open()`
based on whether the current buffer is a canola buffer. Includes
vimdoc entry.
* docs(upstream): mark #621 fixed
* fix(columns): hide misleading directory sizes in size column
Problem: the size column shows the filesystem inode size (typically
4096 = 4.1k) for directories, which is misleading — users expect no
size for directories.
Solution: add an early return for directory entries in the size render
function of the files, SSH, and S3 adapters.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs(upstream): mark #486 fixed
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* feat(preview): add `max_file_size` config to skip large file previews
Problem: previewing large files (e.g. 500 MB logs, binaries) loads them
into a buffer and can freeze or OOM Neovim. `disable_preview` only
receives the filename, so users cannot gate on file size.
Solution: add `preview_win.max_file_size` (number, MB, default 10). In
`open_preview`, check `entry.meta.stat.size` and fall back to
`vim.uv.fs_stat` when the cached stat is absent. If the file exceeds
the limit and a preview window is already open, render "File too large
to preview" in it; if not, emit a WARN notify and return early. The
cursor-moved auto-update path only fires when a window already exists,
so no flag threading is needed to distinguish explicit from implicit.
Based on: stevearc/oil.nvim#213
* feat(view): add `show_hidden_when_empty` for hidden-only directories
Problem: with `show_hidden = false`, a directory containing only
dotfiles renders as just `..`, giving no indication that entries exist.
Solution: add `view_options.show_hidden_when_empty` (boolean, default
false). After the main filter loop in `render_buffer`, if the option is
set and `#line_table <= 1`, iterate `entry_list` again and render any
entry not matched by `is_always_hidden`, using `is_hidden = true` so
they render with the dimmed hidden style.
Based on: stevearc/oil.nvim#473
* docs(upstream): fix formatting
* docs(upstream): update #213 and #473 with PR and commit links
Problem: users who want hands-off behaviour had no way to skip the
`prompt_save_on_select_new_entry` confirmation dialog — enabling the
prompt meant always being asked, with no silent auto-save path.
Solution: add `auto_save_on_select_new_entry` (default `false`) which,
when true, calls `M.save()` and proceeds immediately instead of showing
the confirm dialog. Includes type annotations, vimdoc, and upstream
tracker update for stevearc/oil.nvim#393.
* docs(upstream): triage batch — #739 cherry-pick, 10 issue updates
* feat: add `open_split` and `toggle_split` API
Problem: canola had no way to open a browser in a normal split window;
only floating windows were supported via `open_float`/`toggle_float`.
`M.close` also crashed with E444 when called from the last window.
Solution: port stevearc/oil.nvim#728 — add `open_split(dir, opts, cb)`
and `toggle_split(dir, opts, cb)` mirroring the float API. Use
`is_canola_win`/`canola_original_win` window vars (not the upstream
`is_oil_win` names). Wrap `nvim_win_close` in `pcall` with `enew()`
fallback to handle the last-window E444 case.
Based on: stevearc/oil.nvim#728
* docs: add vimdoc for `open_split`/`toggle_split` and macOS trash recipe
Cherry-picked from: stevearc/oil.nvim#739
* docs(upstream): fix prettier formatting
* fix: show float title when border is nil
Problem: the float title was only shown via the native `nvim_win_set_config`
path, which requires a border to render. The guard `config.float.border ~=
'none'` did not account for `nil`, which is the default — so users with no
explicit `border` config never saw the path title in the floating window.
Solution: require both `~= nil` and `~= 'none'` before using the native
title. In all other cases (border nil, 'none', or nvim < 0.9), fall back to
`util.add_title_to_win`, which renders a child floating window for the title.
Based on: stevearc/oil.nvim#683
* refactor: drop nvim-0.9 version checks in float title logic
feat: add \`skip_confirm_for_delete\` option
Problem: there was no way to suppress the confirmation popup when the
only pending operations are deletes. \`skip_confirm_for_simple_edits\`
explicitly excludes deletes, so users who delete frequently had no opt-out.
Solution: add \`skip_confirm_for_delete = false\` config option. When true,
\`confirmation.show()\` skips the popup if every pending action is a delete.
Based on: stevearc/oil.nvim#392
Problem: when `prompt_save_on_select_new_entry` is enabled and the user
presses Escape on the "Save changes?" confirm dialog, `vim.fn.confirm`
returns 0, but the select continued as if the user had chosen "No".
Solution: add an explicit `choice == 0` branch that returns immediately,
aborting the select without saving or opening any files.
* feat: emit \`CanolaFileCreated\` autocmd on file creation
Problem: no way to hook into individual file creation to populate
initial contents, without a plugin-specific config callback.
Solution: fire \`User CanolaFileCreated\` with \`data.path\` after each
successful \`fs.touch\` in the files adapter. Users listen with
\`nvim_create_autocmd\` and write to the path however they like.
* build: gitignore `doc/upstream.html`
* docs(upstream): mark #721 fixed, triage #735
* docs(upstream): simplify #735 note
* docs(upstream): triage PRs #721 and #735
* docs(upstream): fix#721 status to deferred
* docs(upstream): remove status key legend
* docs(upstream): s/addressing/fixing in #721 note
Problem: When files are deleted via canola, any open Neovim buffers
for those files remain alive, polluting the jumplist with stale
entries.
Solution: Add an opt-in `cleanup_buffers_on_delete` config option
(default `false`). When enabled, `finish()` in `mutator/init.lua`
iterates completed delete actions and wipes matching buffers via
`nvim_buf_delete` before `CanolaActionsPost` fires. Only local
filesystem deletes are handled (guarded by the `files` adapter
check).
* fix: restore `buflisted` on jumplist buffer re-entry
Problem: Neovim's jumplist machinery re-enters canola buffers via an
internal `:edit`-equivalent path, which unconditionally sets
`buflisted = true`. The existing workaround in `open()` and
`open_float()` only covers canola-initiated navigation, leaving
`<C-o>` and `<C-i>` unhandled.
Solution: Apply the same `buf_options.buflisted` guard in the
`BufEnter` autocmd, directly after `set_win_options()`. This fires
on every buffer entry — including all jumplist paths — and mirrors
the pattern already used at the two `:edit` callsites.
* docs: mark upstream #302 as fixed in tracker
Problem: the codebase still used the upstream \`oil\` naming everywhere —
URL schemes, the \`:Oil\` command, highlight groups, user events, module
paths, filetypes, buffer/window variables, LuaCATS type annotations,
vimdoc help tags, syntax groups, and internal identifiers.
Solution: mechanical rename of every reference. URL schemes now use
\`canola://\` (plus \`canola-ssh://\`, \`canola-s3://\`, \`canola-sss://\`,
\`canola-trash://\`, \`canola-test://\`). The \`:Canola\` command replaces
\`:Oil\`. All highlight groups, user events, augroups, namespaces,
filetypes, require paths, type annotations, help tags, and identifiers
follow suit. The \`upstream\` remote to \`stevearc/oil.nvim\` has been
removed and the \`vim.g.oil\` deprecation shim dropped.
Problem: the full upstream PR and issue triage was removed from the
README during the repository modernization, leaving no user-facing
record of what the fork addresses.
Solution: restore the triage tables in a dedicated doc/upstream.md and
link to it from the top of the README. Keeps the README clean while
giving the full picture a permanent home.
* feat: support vim.g.oil declarative configuration
Problem: oil.nvim requires an imperative require("oil").setup(opts)
call to initialize. The Neovim ecosystem is moving toward vim.g.plugin
as a declarative config source that works without explicit setup calls.
Solution: fall back to vim.g.oil in config.setup() when no opts are
passed, and add plugin/oil.lua to auto-initialize when vim.g.oil is
set. Explicit setup(opts) calls still take precedence. Update docs
and add tests for the new resolution order.
Closes: barrettruth/oil.nvim#1
* build: remove release-please pipeline
Problem: the release-please action creates automated releases that
are not needed for this fork's workflow.
Solution: remove the release job from tests.yml and the
release-please branch exclusion from the review request workflow.
* fix(doc): improve readme phrasing
* doc: minor phrasing "improvements"
* ci: add luarocks release on tag push
Problem: there is no automated way to publish oil.nvim to luarocks
when a new version is tagged.
Solution: add a luarocks workflow that triggers on v* tag pushes,
runs the test suite via workflow_call, then publishes via
luarocks-tag-release. Add workflow_call trigger to tests.yml so it
can be reused.
* docs: centralize documentation into helpdoc
Problem: documentation was spread across four files (README.md,
doc/oil.txt, doc/api.md, doc/recipes.md) with duplication and gaps.
User events were undocumented, and adapter docs only lived in the
README.
Solution: expand doc/oil.txt with five new sections (introduction,
requirements, adapters, recipes, events) from existing content. Trim
README to a landing page pointing to :help oil. Delete doc/api.md
and doc/recipes.md since their content now lives in the helpdoc.
Closes: barrettruth/oil.nvim#6
* build: remove docgen pipeline
Problem: the Python docgen pipeline (scripts/generate.py,
scripts/main.py, nvim_doc_tools) was designed for upstream's doc
layout and is incompatible with the centralized helpdoc structure.
It overwrites doc/oil.txt entirely and expects sections in README.md
that no longer exist.
Solution: delete the pipeline scripts (generate.py, main.py,
requirements.txt), remove the update_docs CI job, and clean up the
Makefile and .gitignore references. Linting and typechecking remain
unchanged.
Problem: the docgen workflow pushed directly to main, which is blocked
by repository rulesets. No token-based push from GitHub Actions can
bypass ruleset rules on personal repos.
Solution: replace the push step with a git diff --exit-code check that
fails if generated docs are out of date. Docs must now be committed by
the developer via make doc. Also regenerates docs to reflect batch 4
changes (close_float, OilFileIcon, OilExecutableHidden, recipe link).
Problem: hidden files are dimmed via OilHidden -> Comment, and there is
no clean way to make them look identical to visible entries. Clearing
OilHidden alone causes all hidden types to lose their type-specific
coloring.
Solution: add a recipe that iterates _get_highlights() and relinks
each Oil*Hidden group to its non-hidden base. The Lua pattern
"^(Oil.+)Hidden$" naturally skips OilHidden itself and automatically
covers any future entry types.
Resolves: stevearc/oil.nvim#578
Problem: files were always created with mode 0644 and directories
with 0755, hardcoded in fs.touch and uv.fs_mkdir. Users who need
different defaults (e.g. 0600 for security) had no config option.
Solution: add new_file_mode (default 420 = 0644) and new_dir_mode
(default 493 = 0755) config options, passed through to fs.touch and
uv.fs_mkdir in the files and mac trash adapters. The fs.touch
signature accepts an optional mode parameter with backwards
compatibility (detects function argument to support old callers).
Local cache directories (SSH, S3) continue using standard system
permissions rather than the user-configured mode.
Based on: stevearc/oil.nvim#537
Problem: files without standard extensions (e.g. scripts with
shebangs, Makefile, Dockerfile) got incorrect or default icons since
icon providers match by filename or extension only.
Solution: add use_slow_filetype_detection option to the icon column
config. When enabled, reads the first 16 lines of each file and
passes them to vim.filetype.match for content-based detection. The
detected filetype is forwarded to mini.icons or nvim-web-devicons as
a trailing parameter, preserving backwards compatibility with
existing icon provider implementations.
Based on: stevearc/oil.nvim#618
Problem: executable files were visually indistinguishable from regular
files in oil buffers.
Solution: add OilExecutable highlight group (linked to DiagnosticOk)
that detects executables via Unix permission bits (S_IXUSR|S_IXGRP|
S_IXOTH) and Windows executable extensions (.exe, .bat, .cmd, .com,
.ps1). Applied to both regular files and symlink targets.
Based on: stevearc/oil.nvim#698Closesstevearc/oil.nvim#679
Problem: third-party plugins like oil-git-status.nvim had no way to
know when an oil buffer was re-rendered after a filesystem change,
causing their decorations to be cleared with no signal to refresh.
Solution: emit a User OilReadPost autocmd after every successful
render_buffer_async call. Also document all oil user events
(OilEnter, OilReadPost, OilMutationComplete) in oil.txt since none
were previously documented.
Cherry-picked from: stevearc/oil.nvim#723
Problem: there was no example showing how to register and sort by a
custom column.
Solution: add a recipe demonstrating an "extension" column with
natural-order sorting.
Cherry-picked from: stevearc/oil.nvim#697
