* 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

* doc: minor phrasing "improvements"

* fix(doc): restore Q/A format in FAQ and close lua block

2026-02-21 23:10:59 -05:00

8.7 KiB

Raw Permalink Blame History

oil.nvim

A vim-vinegar like file explorer that lets you edit your filesystem like a normal Neovim buffer.

https://user-images.githubusercontent.com/506791/209727111-6b4a11f4-634a-4efa-9461-80e9717cea94.mp4

This is a maintained fork of stevearc/oil.nvim with cherry-picked upstream PRs and original bug fixes that haven't landed upstream yet.

Changes from upstream

PRs

Upstream PRs cherry-picked or adapted into this fork.

PR	Description	Commit
#495	Cancel visual/operator-pending mode on close instead of closing buffer	`16f3d7b`
#537	Configurable file and directory creation permissions (`new_file_mode`, `new_dir_mode`)	`c6b4a7a`
#578	Recipe to disable hidden file dimming by relinking `Oil*Hidden` groups	`38db6cf`
#618	Opt-in filetype detection for icons via `use_slow_filetype_detection`	`ded1725`
#644	Pass full entry to `is_hidden_file` and `is_always_hidden` callbacks	`4ab4765`
#645	Add `close_float` action (close only floating oil windows)	`f6bcdda`
#690	Add `OilFileIcon` highlight group as fallback for unrecognized icons	`ce64ae1`
#697	Recipe for custom file extension column with sorting	`dcb3a08`
#698	Executable file highlighting (`OilExecutable`, `OilExecutableHidden`)	`41556ec`, `85ed9b8`
#717	Add malewicz1337/oil-git.nvim to third-party extensions	`582d9fc`
#720	Gate `BufAdd` autocmd behind `default_file_explorer` check	`2228f80`
#722	Fix dead freedesktop trash specification URL	`b92ecb0`
#723	Emit `OilReadPost` user event after every buffer render	`29239d5`
#725	Normalize keymap keys before config merge (`<c-t>` = `<C-t>`)	`723145c`
#727	Clarify `get_current_dir` nil return and add Telescope recipe	`eed6697`

Issues

Upstream issues triaged against this fork.

Issue	Status	Resolution
#446	resolved	Executable highlighting — implemented by PR #698
#483	not actionable	Spell downloads depend on netrw — fixed in neovim (neovim#34940)
#492	not actionable	Question — j/k remapping, answered in comments
#533	not actionable	`constrain_cursor` — needs repro from reporter
#587	not actionable	Alt+h keymap — user config issue
#623	not actionable	bufferline.nvim interaction — cross-plugin issue
#624	not actionable	Mutation-in-progress race — no reliable repro
#632	fixed	Preview + move = copy — `fe16993`
#642	fixed	W10 warning under `nvim -R` — `ca834cf`
#664	not actionable	Extra buffer on session reload — no repro
#670	fixed	Multi-directory cmdline — `70861e5`
#673	fixed	Symlink newlines crash — `9110a1a`
#679	resolved	Executable file sign — implemented by PR #698
#692	resolved	Keymap normalization — fixed by PR #725
#710	fixed	buftype empty on BufEnter — `01b860e`
#714	not actionable	Support question — already answered
#719	not actionable	Neovim crash on node_modules delete — libuv/neovim bug
#726	not actionable	Meta discussion/roadmap

Requirements

Neovim 0.8+ and optionally mini.icons or nvim-web-devicons for file icons.

Installation

Install with your favorite package manager or with luarocks:

luarocks install oil.nvim

Documentation

:help oil.nvim

FAQ

Q: How do I migrate from stevearc/oil.nvim to barrettruth/oil.nvim?

Replace your setup() call with a vim.g.oil assignment. For example, with lazy.nvim:

-- before
{
  'stevearc/oil.nvim',
  config = function(_, opts)
    require('oil').setup(opts)
  end,
  opts = {
    ...
  }
}

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

Q: Why "oil"?

A: From the vim-vinegar README, a quote by Drew Neil:

Split windows and the project drawer go together like oil and vinegar

Vinegar was taken. Let's be oil. Plus, I think it's pretty slick ;)

Q: Why would I want to use oil vs any other plugin?

You like to use a netrw-like view to browse directories (as opposed to a file tree)
AND you want to be able to edit your filesystem like a buffer
AND you want to perform cross-directory actions. AFAIK there is no other plugin that does this. (update: mini.files also offers this functionality)

If you don't need those features specifically, check out the alternatives listed below

Q: Can oil display files as a tree view?

A: No. A tree view would require a completely different methodology, necessitating a complete rewrite.

Q: What are some alternatives?

the original: the lesser-maintained but official oil.nvim
mini.files: Also supports cross-directory filesystem-as-buffer edits with a column view.
vim-vinegar: The granddaddy of single-directory file browsing.
dirbuf.nvim: Edit filesystem like a buffer, but no cross-directory edits.
lir.nvim: Similar to vim-vinegar with better Neovim integration.
vim-dirvish: Stable, simple directory browser.

8.7 KiB Raw Permalink Blame History