3b930636e3
* 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.
8.7 KiB
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?
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:
- 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.