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?

A:

• 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?

A:

• 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.