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

Cherry-picked PRs

Upstream PRs cherry-picked or adapted into this fork.

PR	Description	Commit
#495	Cancel visual/operator-pending mode on close	16f3d7b
#537	Configurable file/directory creation permissions	c6b4a7a
#618	Opt-in filetype detection for icons	ded1725
#644	Pass entry to is_hidden_file/is_always_hidden	4ab4765
#697	Recipe for file extension column	dcb3a08
#698	Executable file highlighting	41556ec, 85ed9b8
#717	Add oil-git.nvim to extensions	582d9fc
#720	Gate BufAdd autocmd behind config check	2228f80
#722	Fix freedesktop trash URL	b92ecb0
#723	Emit OilReadPost event after render	29239d5
#725	Normalize keymap keys before config merge	723145c
#727	Clarify get_current_dir nil + Telescope recipe	eed6697

Open upstream PRs

Open PRs on upstream not yet incorporated into this fork.

PR	Description	Status
#488	Parent directory in a split	not actionable — empty PR, 0 changes
#493	UNC paths on Windows	not actionable — superseded by #686
#591	release-please changelog	not applicable — fork uses different release process
#667	Virtual text columns + headers	deferred — WIP, conflicting
#686	Windows path conversion fix	not actionable — Windows-only
#708	Move file into new dir by renaming	deferred — needs rewrite for multi-level dirs, tests
#721	create_hook to populate file contents	open
#728	open_split for opening oil in a split	tracked — barrettruth/oil.nvim#2

Issues

All open upstream issues, triaged against this fork.

Status key: fixed = original fix in fork, resolved = addressed by cherry-picked PR, not actionable = can't/won't fix, tracking = known/not yet addressed, open = not yet triaged.

Issue	Status	Notes
#85	open	Git status column (P2)
#95	open	Undo after renaming files (P1)
#117	open	Move file into new dir via slash in name (P1, related to #708)
#156	open	Paste path of files into oil buffer (P2)
#200	open	Highlights not working when opening a file (P2)
#207	open	Suppress "no longer available" message (P1)
#210	open	FTP support (P2)
#213	open	Disable preview for large files (P1)
#226	open	K8s/Docker adapter (P2)
#232	open	Cannot close last window (P2)
#254	open	Buffer modified highlight group (P2)
#263	open	Diff mode (P2)
#276	open	Archives manipulation (P2)
#280	open	vim-projectionist support (P2)
#288	open	Oil failing to load (P2)
#289	open	Show absolute path toggle (P2)
#294	open	Can't handle emojis in filenames (P2)
#298	open	Open float on neovim directory startup (P2)
#302	open	C-o parent nav makes buffer buflisted (P0)
#303	open	Preview in float window mode (P2)
#325	open	oil-ssh error from command line (P0)
#330	open	File opens in floating modal
#332	open	Buffer not fixed to floating window (P2)
#335	open	Disable editing outside root dir
#349	open	Parent directory as column/vsplit (P2)
#351	open	Paste deleted file from register
#359	open	Parse error on filenames differing by space (P1)
#360	open	Pick window to open file into
#362	open	"Could not find oil adapter for scheme" error
#363	open	prompt_save_on_select_new_entry uses wrong prompt
#371	open	Constrain cursor in insert mode
#373	open	Dir from quickfix with bqf/trouble broken (P1)
#375	open	Highlights for file types and permissions (P2)
#380	open	Show file in oil when editing hidden file
#382	open	Relative path in window title (P2)
#392	open	Option to skip delete prompt
#393	open	Auto-save new buffer on entry
#396	open	Customize preview content (P2)
#399	open	Open file without closing Oil (P1)
#404	not actionable	Restricted UNC paths — Windows-only (P2)
#416	open	Cannot remap key to open split
#431	open	More SSH adapter documentation
#435	open	Error previewing with semantic tokens LSP
#436	open	Owner and group columns (P2)
#444	open	Opening behaviour customization
#446	resolved	Executable highlighting — PR #698
#449	open	Renaming TypeScript files stopped working
#450	open	Highlight opened file in directory listing
#457	open	Custom column API
#466	open	Select into window on right
#473	open	Show all hidden files if dir only has hidden
#479	open	Harpoon integration recipe
#483	not actionable	Spell downloads depend on netrw — fixed in neovim#34940
#486	open	All directory sizes show 4.1k
#492	not actionable	j/k remapping question — answered in comments
#507	open	lacasitos.nvim conflict (P1)
#521	open	oil-ssh connection issues
#525	open	SSH adapter documentation (P2)
#531	not actionable	Windows — incomplete drive letters (P1)
#533	not actionable	constrain_cursor — needs repro
#570	open	Improve c0/d0 for renaming
#571	open	Callback before highlight_filename (P2)
#578	resolved	Hidden file dimming recipe — 38db6cf
#587	not actionable	Alt+h keymap — user config issue
#599	open	user:group display and manipulation (P2)
#607	open	Per-host SCP args (P2)
#609	open	Cursor placement via Snacks picker
#612	open	Delete buffers on file delete (P2)
#615	open	Cursor at name column on o/O (P2)
#617	open	Filetype by actual filetype (P2)
#621	open	Toggle function for regular windows (P2)
#623	not actionable	bufferline.nvim interaction — cross-plugin
#624	not actionable	Mutation race — no reliable repro
#625	not actionable	E19 mark invalid line — intractable without neovim API changes
#632	fixed	Preview + move = copy — PR #12 (fe16993)
#636	open	Telescope picker opens in active buffer
#637	open	Inconsistent symlink resolution
#641	open	Flicker on actions.parent
#642	fixed	W10 warning under nvim -R — ca834cf
#645	resolved	close_float action — f6bcdda
#646	open	get_current_dir nil on SSH
#650	open	Emit LSP workspace.fileOperations events
#655	open	File statistics as virtual text
#659	open	Mark and diff files in buffer
#664	not actionable	Session reload extra buffer — no repro
#665	open	Hot load preview fast-scratch buffers
#668	open	Custom yes/no confirmation
#670	fixed	Multi-directory cmdline — PR #11 (70861e5)
#671	open	Yanking between nvim instances
#673	fixed	Symlink newlines crash — 9110a1a
#675	open	Move file into folder by renaming (related to #708)
#676	not actionable	Windows — path conversion
#678	tracking	buftype='acwrite' causes mksession to skip oil windows
#679	resolved	Executable file sign — PR #698
#682	open	get_current_dir() nil in non-telescope context
#683	open	Path not shown in floating mode
#684	open	User and group columns
#685	open	Plain directory paths in buffer names
#690	resolved	OilFileIcon highlight group — ce64ae1
#692	resolved	Keymap normalization — PR #725
#699	open	select blocks UI with slow FileType autocmd
#707	open	Move file/dir into new dir by renaming (related to #708)
#710	fixed	buftype empty on BufEnter — PR #10 (01b860e)
#714	not actionable	Support question — answered
#719	not actionable	Neovim crash on node_modules — 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.