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

2026-02-21 15:56:33 -05:00

8.7 KiB

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

Quick start

Add the following to your init.lua

require("oil").setup()

Then open a directory with nvim .. Use <CR> to open a file/directory, and - to go up a directory. Otherwise, just treat it like a normal buffer and make changes as you like. Remember to :w when you're done to actually perform the actions.

If you want to mimic the vim-vinegar method of navigating to the parent directory of a file, add this keymap:

vim.keymap.set("n", "-", "<CMD>Oil<CR>", { desc = "Open parent directory" })

You can open a directory with :edit <path> or :Oil <path>. To open oil in a floating window, do :Oil --float <path>.

Documentation

See :help oil for configuration, API reference, recipes, and more.

FAQ

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?

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 Blame History