barrett/canola.nvim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 4

docs: centralize documentation into helpdoc (#15)

Browse source 
* 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.
This commit is contained in:
Barrett Ruth 2026-02-21 22:15:53 -05:00 • committed by GitHub
parent 1712b6feb3
commit 3b930636e3
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
10 changed files with 363 additions and 1361 deletions
Download patch file Download diff file Expand all files Collapse all files

19
.github/workflows/tests.yml vendored
View file

@ -70,24 +70,6 @@ jobs:
run: |
bash ./run_tests.sh
update_docs:
name: Update docs
runs-on: ubuntu-22.04
steps:
- uses: actions/checkout@v4
- name: Install Neovim and dependencies
run: |
bash ./.github/workflows/install_nvim.sh
- name: Update docs
run: |
python -m pip install pyparsing==3.0.9
make doc
- name: Check docs are up to date
run: |
git diff --exit-code README.md doc
release:
name: release
@ -97,7 +79,6 @@ jobs:
- stylua
- typecheck
- run_tests
- update_docs
runs-on: ubuntu-22.04
steps:
- uses: googleapis/release-please-action@v4

5
.gitignore vendored
View file

@ -6,9 +6,6 @@ luac.out
*.zip
*.tar.gz
# python bytecode
__pycache__
# Object files
*.o
*.os
@ -44,9 +41,7 @@ __pycache__
.direnv/
.testenv/
venv/
doc/tags
scripts/nvim_doc_tools
scripts/nvim-typecheck-action
scripts/benchmark.nvim
perf/tmp/

26
Makefile
View file

@ -4,19 +4,9 @@ help:
@echo 'Usage:'
@sed -n 's/^##//p' ${MAKEFILE_LIST} | column -t -s ':' | sed -e 's/^/ /'
## all: generate docs, lint, and run tests
## all: lint and run tests
.PHONY: all
all: doc lint test
venv:
python3 -m venv venv
venv/bin/pip install -r scripts/requirements.txt
## doc: generate documentation
.PHONY: doc
doc: scripts/nvim_doc_tools venv
venv/bin/python scripts/main.py generate
venv/bin/python scripts/main.py lint
all: lint test
## test: run tests
.PHONY: test
@ -25,13 +15,8 @@ test:
## lint: run linters and LuaLS typechecking
.PHONY: lint
lint: scripts/nvim-typecheck-action fastlint
lint: scripts/nvim-typecheck-action
./scripts/nvim-typecheck-action/typecheck.sh --workdir scripts/nvim-typecheck-action lua
## fastlint: run only fast linters
.PHONY: fastlint
fastlint: scripts/nvim_doc_tools venv
venv/bin/python scripts/main.py lint
luacheck lua tests --formatter plain
stylua --check lua tests
@ -51,9 +36,6 @@ benchmark: scripts/benchmark.nvim
nvim --clean -u perf/bootstrap.lua -c 'lua benchmark()'
@cat perf/tmp/benchmark.txt
scripts/nvim_doc_tools:
git clone https://github.com/stevearc/nvim_doc_tools scripts/nvim_doc_tools
scripts/nvim-typecheck-action:
git clone https://github.com/stevearc/nvim-typecheck-action scripts/nvim-typecheck-action
@ -63,4 +45,4 @@ scripts/benchmark.nvim:
## clean: reset the repository to a clean state
.PHONY: clean
clean:
rm -rf scripts/nvim_doc_tools scripts/nvim-typecheck-action venv .testenv perf/tmp profile.json
rm -rf scripts/nvim-typecheck-action venv .testenv perf/tmp profile.json

404
README.md
View file

@ -60,113 +60,13 @@ Upstream issues triaged against this fork.
</details>
<!-- TOC -->
- [Requirements](#requirements)
- [Installation](#installation)
- [Quick start](#quick-start)
- [Options](#options)
- [Adapters](#adapters)
- [Recipes](#recipes)
- [Third-party extensions](#third-party-extensions)
- [API](#api)
- [FAQ](#faq)
<!-- /TOC -->
## Requirements
- Neovim 0.8+
- Icon provider plugin (optional)
- [mini.icons](https://github.com/nvim-mini/mini.nvim/blob/main/readmes/mini-icons.md) for file and folder icons
- [nvim-web-devicons](https://github.com/nvim-tree/nvim-web-devicons) for file icons
Neovim 0.8+ and optionally [mini.icons](https://github.com/nvim-mini/mini.nvim/blob/main/readmes/mini-icons.md) or [nvim-web-devicons](https://github.com/nvim-tree/nvim-web-devicons) for file icons.
## Installation
oil.nvim supports all the usual plugin managers
<details>
<summary>lazy.nvim</summary>
```lua
{
'stevearc/oil.nvim',
---@module 'oil'
---@type oil.SetupOpts
opts = {},
-- Optional dependencies
dependencies = { { "nvim-mini/mini.icons", opts = {} } },
-- dependencies = { "nvim-tree/nvim-web-devicons" }, -- use if you prefer nvim-web-devicons
-- Lazy loading is not recommended because it is very tricky to make it work correctly in all situations.
lazy = false,
}
```
</details>
<details>
<summary>Packer</summary>
```lua
require("packer").startup(function()
use({
"stevearc/oil.nvim",
config = function()
require("oil").setup()
end,
})
end)
```
</details>
<details>
<summary>Paq</summary>
```lua
require("paq")({
{ "stevearc/oil.nvim" },
})
```
</details>
<details>
<summary>vim-plug</summary>
```vim
Plug 'stevearc/oil.nvim'
```
</details>
<details>
<summary>dein</summary>
```vim
call dein#add('stevearc/oil.nvim')
```
</details>
<details>
<summary>Pathogen</summary>
```sh
git clone --depth=1 https://github.com/stevearc/oil.nvim.git ~/.vim/bundle/
```
</details>
<details>
<summary>Neovim native package</summary>
```sh
git clone --depth=1 https://github.com/stevearc/oil.nvim.git \
"${XDG_DATA_HOME:-$HOME/.local/share}"/nvim/site/pack/oil/start/oil.nvim
```
</details>
Install with your favorite package manager or with luarocks.
## Quick start
@ -186,285 +86,9 @@ 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>`.
## Options
## Documentation
```lua
require("oil").setup({
-- Oil will take over directory buffers (e.g. `vim .` or `:e src/`)
-- Set to false if you want some other plugin (e.g. netrw) to open when you edit directories.
default_file_explorer = true,
-- Id is automatically added at the beginning, and name at the end
-- See :help oil-columns
columns = {
"icon",
-- "permissions",
-- "size",
-- "mtime",
},
-- Buffer-local options to use for oil buffers
buf_options = {
buflisted = false,
bufhidden = "hide",
},
-- Window-local options to use for oil buffers
win_options = {
wrap = false,
signcolumn = "no",
cursorcolumn = false,
foldcolumn = "0",
spell = false,
list = false,
conceallevel = 3,
concealcursor = "nvic",
},
-- Send deleted files to the trash instead of permanently deleting them (:help oil-trash)
delete_to_trash = false,
-- Skip the confirmation popup for simple operations (:help oil.skip_confirm_for_simple_edits)
skip_confirm_for_simple_edits = false,
-- Selecting a new/moved/renamed file or directory will prompt you to save changes first
-- (:help prompt_save_on_select_new_entry)
prompt_save_on_select_new_entry = true,
-- Oil will automatically delete hidden buffers after this delay
-- You can set the delay to false to disable cleanup entirely
-- Note that the cleanup process only starts when none of the oil buffers are currently displayed
cleanup_delay_ms = 2000,
lsp_file_methods = {
-- Enable or disable LSP file operations
enabled = true,
-- Time to wait for LSP file operations to complete before skipping
timeout_ms = 1000,
-- Set to true to autosave buffers that are updated with LSP willRenameFiles
-- Set to "unmodified" to only save unmodified buffers
autosave_changes = false,
},
-- Constrain the cursor to the editable parts of the oil buffer
-- Set to `false` to disable, or "name" to keep it on the file names
constrain_cursor = "editable",
-- Set to true to watch the filesystem for changes and reload oil
watch_for_changes = false,
-- Keymaps in oil buffer. Can be any value that `vim.keymap.set` accepts OR a table of keymap
-- options with a `callback` (e.g. { callback = function() ... end, desc = "", mode = "n" })
-- Additionally, if it is a string that matches "actions.<name>",
-- it will use the mapping at require("oil.actions").<name>
-- Set to `false` to remove a keymap
-- See :help oil-actions for a list of all available actions
keymaps = {
["g?"] = { "actions.show_help", mode = "n" },
["<CR>"] = "actions.select",
["<C-s>"] = { "actions.select", opts = { vertical = true } },
["<C-h>"] = { "actions.select", opts = { horizontal = true } },
["<C-t>"] = { "actions.select", opts = { tab = true } },
["<C-p>"] = "actions.preview",
["<C-c>"] = { "actions.close", mode = "n" },
["<C-l>"] = "actions.refresh",
["-"] = { "actions.parent", mode = "n" },
["_"] = { "actions.open_cwd", mode = "n" },
["`"] = { "actions.cd", mode = "n" },
["g~"] = { "actions.cd", opts = { scope = "tab" }, mode = "n" },
["gs"] = { "actions.change_sort", mode = "n" },
["gx"] = "actions.open_external",
["g."] = { "actions.toggle_hidden", mode = "n" },
["g\\"] = { "actions.toggle_trash", mode = "n" },
},
-- Set to false to disable all of the above keymaps
use_default_keymaps = true,
view_options = {
-- Show files and directories that start with "."
show_hidden = false,
-- This function defines what is considered a "hidden" file
is_hidden_file = function(name, bufnr)
local m = name:match("^%.")
return m ~= nil
end,
-- This function defines what will never be shown, even when `show_hidden` is set
is_always_hidden = function(name, bufnr)
return false
end,
-- Sort file names with numbers in a more intuitive order for humans.
-- Can be "fast", true, or false. "fast" will turn it off for large directories.
natural_order = "fast",
-- Sort file and directory names case insensitive
case_insensitive = false,
sort = {
-- sort order can be "asc" or "desc"
-- see :help oil-columns to see which columns are sortable
{ "type", "asc" },
{ "name", "asc" },
},
-- Customize the highlight group for the file name
highlight_filename = function(entry, is_hidden, is_link_target, is_link_orphan)
return nil
end,
},
new_file_mode = 420,
new_dir_mode = 493,
-- Extra arguments to pass to SCP when moving/copying files over SSH
extra_scp_args = {},
-- Extra arguments to pass to aws s3 when creating/deleting/moving/copying files using aws s3
extra_s3_args = {},
-- EXPERIMENTAL support for performing file operations with git
git = {
-- Return true to automatically git add/mv/rm files
add = function(path)
return false
end,
mv = function(src_path, dest_path)
return false
end,
rm = function(path)
return false
end,
},
-- Configuration for the floating window in oil.open_float
float = {
-- Padding around the floating window
padding = 2,
-- max_width and max_height can be integers or a float between 0 and 1 (e.g. 0.4 for 40%)
max_width = 0,
max_height = 0,
border = nil,
win_options = {
winblend = 0,
},
-- optionally override the oil buffers window title with custom function: fun(winid: integer): string
get_win_title = nil,
-- preview_split: Split direction: "auto", "left", "right", "above", "below".
preview_split = "auto",
-- This is the config that will be passed to nvim_open_win.
-- Change values here to customize the layout
override = function(conf)
return conf
end,
},
-- Configuration for the file preview window
preview_win = {
-- Whether the preview window is automatically updated when the cursor is moved
update_on_cursor_moved = true,
-- How to open the preview window "load"|"scratch"|"fast_scratch"
preview_method = "fast_scratch",
-- A function that returns true to disable preview on a file e.g. to avoid lag
disable_preview = function(filename)
return false
end,
-- Window-local options to use for preview window buffers
win_options = {},
},
-- Configuration for the floating action confirmation window
confirmation = {
-- Width dimensions can be integers or a float between 0 and 1 (e.g. 0.4 for 40%)
-- min_width and max_width can be a single value or a list of mixed integer/float types.
-- max_width = {100, 0.8} means "the lesser of 100 columns or 80% of total"
max_width = 0.9,
-- min_width = {40, 0.4} means "the greater of 40 columns or 40% of total"
min_width = { 40, 0.4 },
-- optionally define an integer/float for the exact width of the preview window
width = nil,
-- Height dimensions can be integers or a float between 0 and 1 (e.g. 0.4 for 40%)
-- min_height and max_height can be a single value or a list of mixed integer/float types.
-- max_height = {80, 0.9} means "the lesser of 80 columns or 90% of total"
max_height = 0.9,
-- min_height = {5, 0.1} means "the greater of 5 columns or 10% of total"
min_height = { 5, 0.1 },
-- optionally define an integer/float for the exact height of the preview window
height = nil,
border = nil,
win_options = {
winblend = 0,
},
},
-- Configuration for the floating progress window
progress = {
max_width = 0.9,
min_width = { 40, 0.4 },
width = nil,
max_height = { 10, 0.9 },
min_height = { 5, 0.1 },
height = nil,
border = nil,
minimized_border = "none",
win_options = {
winblend = 0,
},
},
-- Configuration for the floating SSH window
ssh = {
border = nil,
},
-- Configuration for the floating keymaps help window
keymaps_help = {
border = nil,
},
})
```
## Adapters
Oil does all of its filesystem interaction through an _adapter_ abstraction. In practice, this means that oil can be used to view and modify files in more places than just the local filesystem, so long as the destination has an adapter implementation.
Note that file operations work _across adapters_. This means that you can use oil to copy files to/from a remote server using the ssh adapter just as easily as you can copy files from one directory to another on your local machine.
### SSH
This adapter allows you to browse files over ssh, much like netrw. To use it, simply open a buffer using the following name template:
```
nvim oil-ssh://[username@]hostname[:port]/[path]
```
This may look familiar. In fact, this is the same url format that netrw uses.
Note that at the moment the ssh adapter does not support Windows machines, and it requires the server to have a `/bin/sh` binary as well as standard unix commands (`ls`, `rm`, `mv`, `mkdir`, `chmod`, `cp`, `touch`, `ln`, `echo`).
### S3
This adapter allows you to browse files stored in aws s3. To use it, make sure `aws` is setup correctly and then simply open a buffer using the following name template:
```
nvim oil-s3://[bucket]/[path]
```
Note that older versions of Neovim don't support numbers in the url, so for Neovim 0.11 and older the url starts with `oil-sss`.
## Recipes
- [Toggle file detail view](doc/recipes.md#toggle-file-detail-view)
- [Show CWD in the winbar](doc/recipes.md#show-cwd-in-the-winbar)
- [Hide gitignored files and show git tracked hidden files](doc/recipes.md#hide-gitignored-files-and-show-git-tracked-hidden-files)
- [Open Telescope file finder in the current oil directory](doc/recipes.md#open-telescope-file-finder-in-the-current-oil-directory)
- [Add custom column for file extension](doc/recipes.md#add-custom-column-for-file-extension)
- [Disable dimming of hidden files](doc/recipes.md#disable-dimming-of-hidden-files)
## Third-party extensions
These are plugins maintained by other authors that extend the functionality of oil.nvim.
- [oil-git-status.nvim](https://github.com/refractalize/oil-git-status.nvim) - Shows git status of files in statuscolumn
- [oil-git.nvim (benomahony)](https://github.com/benomahony/oil-git.nvim) - Shows git status of files with colour and symbols
- [oil-git.nvim (malewicz1337)](https://github.com/malewicz1337/oil-git.nvim) - Async fork with directory highlighting and debounced updates
- [oil-lsp-diagnostics.nvim](https://github.com/JezerM/oil-lsp-diagnostics.nvim) - Shows LSP diagnostics indicator as virtual text
## API
<!-- API -->
- [get_entry_on_line(bufnr, lnum)](doc/api.md#get_entry_on_linebufnr-lnum)
- [get_cursor_entry()](doc/api.md#get_cursor_entry)
- [discard_all_changes()](doc/api.md#discard_all_changes)
- [set_columns(cols)](doc/api.md#set_columnscols)
- [set_sort(sort)](doc/api.md#set_sortsort)
- [set_is_hidden_file(is_hidden_file)](doc/api.md#set_is_hidden_fileis_hidden_file)
- [toggle_hidden()](doc/api.md#toggle_hidden)
- [get_current_dir(bufnr)](doc/api.md#get_current_dirbufnr)
- [open_float(dir, opts, cb)](doc/api.md#open_floatdir-opts-cb)
- [toggle_float(dir, opts, cb)](doc/api.md#toggle_floatdir-opts-cb)
- [open(dir, opts, cb)](doc/api.md#opendir-opts-cb)
- [close(opts)](doc/api.md#closeopts)
- [open_preview(opts, callback)](doc/api.md#open_previewopts-callback)
- [select(opts, callback)](doc/api.md#selectopts-callback)
- [save(opts, cb)](doc/api.md#saveopts-cb)
- [setup(opts)](doc/api.md#setupopts)
<!-- /API -->
See `:help oil` for configuration, API reference, recipes, and more.
## FAQ
@ -487,24 +111,16 @@ Plus, I think it's pretty slick ;)
If you don't need those features specifically, check out the alternatives listed below
**Q: Why write another plugin yourself instead of adding functionality to one that already exists**?
**A:** Because I am a _maniac control freak_.
**Q: Can oil display files as a tree view**?
**A:** No. A tree view would require a completely different methodology, necessitating a complete rewrite. I don't use tree views, so I will leave this as a plugin for someone else to write.
**A:** No. A tree view would require a completely different methodology, necessitating a complete rewrite.
**Q: What are some alternatives?**
**A:**
- [mini.files](https://github.com/nvim-mini/mini.nvim/blob/main/readmes/mini-files.md): A newer plugin that also supports cross-directory filesystem-as-buffer edits. It utilizes a unique column view.
- [vim-vinegar](https://github.com/tpope/vim-vinegar): The granddaddy. This made me fall in love with single-directory file browsing. I stopped using it when I encountered netrw bugs and performance issues.
- [defx.nvim](https://github.com/Shougo/defx.nvim): What I switched to after vim-vinegar. Much more flexible and performant, but requires python and the API is a little hard to work with.
- [dirbuf.nvim](https://github.com/elihunter173/dirbuf.nvim): The first plugin I encountered that let you edit the filesystem like a buffer. Never used it because it [can't do cross-directory edits](https://github.com/elihunter173/dirbuf.nvim/issues/7).
- [lir.nvim](https://github.com/tamago324/lir.nvim): What I used prior to writing this plugin. Similar to vim-vinegar, but with better Neovim integration (floating windows, lua API).
- [vim-dirvish](https://github.com/justinmk/vim-dirvish): Never personally used, but well-established, stable, simple directory browser.
- [vidir](https://github.com/trapd00r/vidir): Never personally used, but might be the first plugin to come up with the idea of editing a directory like a buffer.
There's also file trees like [neo-tree](https://github.com/nvim-neo-tree/neo-tree.nvim) and [nvim-tree](https://github.com/nvim-tree/nvim-tree.lua), but they're really a different category entirely.
- [mini.files](https://github.com/nvim-mini/mini.nvim/blob/main/readmes/mini-files.md): Also supports cross-directory filesystem-as-buffer edits with a column view.
- [vim-vinegar](https://github.com/tpope/vim-vinegar): The granddaddy of single-directory file browsing.
- [dirbuf.nvim](https://github.com/elihunter173/dirbuf.nvim): Edit filesystem like a buffer, but no cross-directory edits.
- [lir.nvim](https://github.com/tamago324/lir.nvim): Similar to vim-vinegar with better Neovim integration.
- [vim-dirvish](https://github.com/justinmk/vim-dirvish): Stable, simple directory browser.

205
doc/api.md
View file

@ -1,205 +0,0 @@
# API
<!-- TOC -->
- [get_entry_on_line(bufnr, lnum)](#get_entry_on_linebufnr-lnum)
- [get_cursor_entry()](#get_cursor_entry)
- [discard_all_changes()](#discard_all_changes)
- [set_columns(cols)](#set_columnscols)
- [set_sort(sort)](#set_sortsort)
- [set_is_hidden_file(is_hidden_file)](#set_is_hidden_fileis_hidden_file)
- [toggle_hidden()](#toggle_hidden)
- [get_current_dir(bufnr)](#get_current_dirbufnr)
- [open_float(dir, opts, cb)](#open_floatdir-opts-cb)
- [toggle_float(dir, opts, cb)](#toggle_floatdir-opts-cb)
- [open(dir, opts, cb)](#opendir-opts-cb)
- [close(opts)](#closeopts)
- [open_preview(opts, callback)](#open_previewopts-callback)
- [select(opts, callback)](#selectopts-callback)
- [save(opts, cb)](#saveopts-cb)
- [setup(opts)](#setupopts)
<!-- /TOC -->
<!-- API -->
## get_entry_on_line(bufnr, lnum)
`get_entry_on_line(bufnr, lnum): nil|oil.Entry` \
Get the entry on a specific line (1-indexed)
| Param | Type | Desc |
| ----- | --------- | ---- |
| bufnr | `integer` | |
| lnum | `integer` | |
## get_cursor_entry()
`get_cursor_entry(): nil|oil.Entry` \
Get the entry currently under the cursor
## discard_all_changes()
`discard_all_changes()` \
Discard all changes made to oil buffers
## set_columns(cols)
`set_columns(cols)` \
Change the display columns for oil
| Param | Type | Desc |
| ----- | ------------------ | ---- |
| cols | `oil.ColumnSpec[]` | |
## set_sort(sort)
`set_sort(sort)` \
Change the sort order for oil
| Param | Type | Desc |
| ----- | ---------------- | ------------------------------------------------------------------------------------- |
| sort | `oil.SortSpec[]` | List of columns plus direction. See :help oil-columns to see which ones are sortable. |
**Examples:**
```lua
require("oil").set_sort({ { "type", "asc" }, { "size", "desc" } })
```
## set_is_hidden_file(is_hidden_file)
`set_is_hidden_file(is_hidden_file)` \
Change how oil determines if the file is hidden
| Param | Type | Desc |
| -------------- | ------------------------------------------------------------------ | -------------------------------------------- |
| is_hidden_file | `fun(filename: string, bufnr: integer, entry: oil.Entry): boolean` | Return true if the file/dir should be hidden |
## toggle_hidden()
`toggle_hidden()` \
Toggle hidden files and directories
## get_current_dir(bufnr)
`get_current_dir(bufnr): nil|string` \
Get the current directory
| Param | Type | Desc |
| ----- | -------------- | ---- |
| bufnr | `nil\|integer` | |
## open_float(dir, opts, cb)
`open_float(dir, opts, cb)` \
Open oil browser in a floating window
| Param | Type | Desc |
| ------------ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| dir | `nil\|string` | When nil, open the parent of the current buffer, or the cwd if current buffer is not a file |
| opts | `nil\|oil.OpenOpts` | |
| >preview | `nil\|oil.OpenPreviewOpts` | When present, open the preview window after opening oil |
| >>vertical | `nil\|boolean` | Open the buffer in a vertical split |
| >>horizontal | `nil\|boolean` | Open the buffer in a horizontal split |
| >>split | `nil\|"aboveleft"\|"belowright"\|"topleft"\|"botright"` | Split modifier |
| cb | `nil\|fun()` | Called after the oil buffer is ready |
## toggle_float(dir, opts, cb)
`toggle_float(dir, opts, cb)` \
Open oil browser in a floating window, or close it if open
| Param | Type | Desc |
| ------------ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| dir | `nil\|string` | When nil, open the parent of the current buffer, or the cwd if current buffer is not a file |
| opts | `nil\|oil.OpenOpts` | |
| >preview | `nil\|oil.OpenPreviewOpts` | When present, open the preview window after opening oil |
| >>vertical | `nil\|boolean` | Open the buffer in a vertical split |
| >>horizontal | `nil\|boolean` | Open the buffer in a horizontal split |
| >>split | `nil\|"aboveleft"\|"belowright"\|"topleft"\|"botright"` | Split modifier |
| cb | `nil\|fun()` | Called after the oil buffer is ready |
## open(dir, opts, cb)
`open(dir, opts, cb)` \
Open oil browser for a directory
| Param | Type | Desc |
| ------------ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| dir | `nil\|string` | When nil, open the parent of the current buffer, or the cwd if current buffer is not a file |
| opts | `nil\|oil.OpenOpts` | |
| >preview | `nil\|oil.OpenPreviewOpts` | When present, open the preview window after opening oil |
| >>vertical | `nil\|boolean` | Open the buffer in a vertical split |
| >>horizontal | `nil\|boolean` | Open the buffer in a horizontal split |
| >>split | `nil\|"aboveleft"\|"belowright"\|"topleft"\|"botright"` | Split modifier |
| cb | `nil\|fun()` | Called after the oil buffer is ready |
## close(opts)
`close(opts)` \
Restore the buffer that was present when oil was opened
| Param | Type | Desc |
| ----------------- | -------------------- | --------------------------------------------------- |
| opts | `nil\|oil.CloseOpts` | |
| >exit_if_last_buf | `nil\|boolean` | Exit vim if this oil buffer is the last open buffer |
## open_preview(opts, callback)
`open_preview(opts, callback)` \
Preview the entry under the cursor in a split
| Param | Type | Desc |
| ----------- | ------------------------------------------------------- | ---------------------------------------------- |
| opts | `nil\|oil.OpenPreviewOpts` | |
| >vertical | `nil\|boolean` | Open the buffer in a vertical split |
| >horizontal | `nil\|boolean` | Open the buffer in a horizontal split |
| >split | `nil\|"aboveleft"\|"belowright"\|"topleft"\|"botright"` | Split modifier |
| callback | `nil\|fun(err: nil\|string)` | Called once the preview window has been opened |
## select(opts, callback)
`select(opts, callback)` \
Select the entry under the cursor
| Param | Type | Desc |
| ----------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| opts | `nil\|oil.SelectOpts` | |
| >vertical | `nil\|boolean` | Open the buffer in a vertical split |
| >horizontal | `nil\|boolean` | Open the buffer in a horizontal split |
| >split | `nil\|"aboveleft"\|"belowright"\|"topleft"\|"botright"` | Split modifier |
| >tab | `nil\|boolean` | Open the buffer in a new tab |
| >close | `nil\|boolean` | Close the original oil buffer once selection is made |
| >handle_buffer_callback | `nil\|fun(buf_id: integer)` | If defined, all other buffer related options here would be ignored. This callback allows you to take over the process of opening the buffer yourself. |
| callback | `nil\|fun(err: nil\|string)` | Called once all entries have been opened |
## save(opts, cb)
`save(opts, cb)` \
Save all changes
| Param | Type | Desc |
| -------- | ---------------------------- | ------------------------------------------------------------------------------------------- |
| opts | `nil\|table` | |
| >confirm | `nil\|boolean` | Show confirmation when true, never when false, respect skip_confirm_for_simple_edits if nil |
| cb | `nil\|fun(err: nil\|string)` | Called when mutations complete. |
**Note:**
<pre>
If you provide your own callback function, there will be no notification for errors.
</pre>
## setup(opts)
`setup(opts)` \
Initialize oil
| Param | Type | Desc |
| ----- | -------------------- | ---- |
| opts | `oil.setupOpts\|nil` | |
<!-- /API -->

356
doc/oil.txt
View file

@ -3,13 +3,47 @@
--------------------------------------------------------------------------------
CONTENTS *oil-contents*
1. Config |oil-config|
2. Options |oil-options|
3. Api |oil-api|
4. Columns |oil-columns|
5. Actions |oil-actions|
6. Highlights |oil-highlights|
7. Trash |oil-trash|
1. Introduction |oil-introduction|
2. Requirements |oil-requirements|
3. Config |oil-config|
4. Options |oil-options|
5. Api |oil-api|
6. Columns |oil-columns|
7. Actions |oil-actions|
8. Highlights |oil-highlights|
9. Adapters |oil-adapters|
10. Recipes |oil-recipes|
11. Events |oil-events|
12. Trash |oil-trash|
--------------------------------------------------------------------------------
INTRODUCTION *oil-introduction*
oil.nvim is a file explorer for Neovim in the style of vim-vinegar. It lets
you edit your filesystem like a normal buffer: create files and directories by
typing new lines, delete them by removing lines, rename or move them by
changing the text. When you save the buffer, oil diffs it against the original
listing and performs the corresponding filesystem operations.
Open a directory with `nvim .`, `:edit <path>`, or `:Oil <path>`. Use `<CR>`
to open a file or descend into a directory, and `-` to go up. Treat the
listing like any other buffer — edit freely, then `:w` to apply changes.
To open oil in a floating window, use `:Oil --float <path>`.
To mimic vim-vinegar's parent-directory keymap: >lua
vim.keymap.set("n", "-", "<CMD>Oil<CR>", { desc = "Open parent directory" })
<
File operations work across adapters. You can copy files between your local
machine and a remote server over SSH, or between local directories and S3
buckets, using the same buffer-editing workflow.
--------------------------------------------------------------------------------
REQUIREMENTS *oil-requirements*
- Neovim 0.8+
- (optional) mini.icons or nvim-web-devicons for file icons
--------------------------------------------------------------------------------
CONFIG *oil-config*
@ -766,6 +800,314 @@ OilTrash *hl-OilTras
OilTrashSourcePath *hl-OilTrashSourcePath*
Virtual text that shows the original path of file in the trash
--------------------------------------------------------------------------------
ADAPTERS *oil-adapters*
Oil performs all filesystem interaction through an adapter abstraction. This
means oil can view and modify files in places beyond the local filesystem, as
long as the destination has an adapter implementation. File operations work
across adapters — you can copy files between local and remote with the same
buffer-editing workflow.
SSH *oil-adapter-ssh*
Browse files over SSH, much like netrw. Open a buffer with: >
nvim oil-ssh://[username@]hostname[:port]/[path]
<
This is the same URL format that netrw uses.
The SSH adapter does not support Windows machines, and it requires the
server to have `/bin/sh` as well as standard unix commands (`ls`, `rm`,
`mv`, `mkdir`, `chmod`, `cp`, `touch`, `ln`, `echo`).
S3 *oil-adapter-s3*
Browse files stored in AWS S3. Make sure `aws` is configured correctly,
then open a buffer with: >
nvim oil-s3://[bucket]/[path]
<
Older versions of Neovim (0.11 and earlier) don't support numbers in the
URL scheme, so use `oil-sss` instead of `oil-s3`.
Trash *oil-adapter-trash*
See |oil-trash| for details on the built-in trash adapter.
--------------------------------------------------------------------------------
RECIPES *oil-recipes*
Toggle file detail view ~
*oil-recipe-toggle-detail-view*
>lua
local detail = false
require("oil").setup({
keymaps = {
["gd"] = {
desc = "Toggle file detail view",
callback = function()
detail = not detail
if detail then
require("oil").set_columns({ "icon", "permissions", "size", "mtime" })
else
require("oil").set_columns({ "icon" })
end
end,
},
},
})
<
Show CWD in the winbar ~
*oil-recipe-cwd-winbar*
>lua
function _G.get_oil_winbar()
local bufnr = vim.api.nvim_win_get_buf(vim.g.statusline_winid)
local dir = require("oil").get_current_dir(bufnr)
if dir then
return vim.fn.fnamemodify(dir, ":~")
else
return vim.api.nvim_buf_get_name(0)
end
end
require("oil").setup({
win_options = {
winbar = "%!v:lua.get_oil_winbar()",
},
})
<
Hide gitignored files and show git tracked hidden files ~
*oil-recipe-git-is-hidden*
>lua
local function parse_output(proc)
local result = proc:wait()
local ret = {}
if result.code == 0 then
for line in vim.gsplit(result.stdout, "\n", { plain = true, trimempty = true }) do
line = line:gsub("/$", "")
ret[line] = true
end
end
return ret
end
local function new_git_status()
return setmetatable({}, {
__index = function(self, key)
local ignore_proc = vim.system(
{ "git", "ls-files", "--ignored", "--exclude-standard", "--others", "--directory" },
{
cwd = key,
text = true,
}
)
local tracked_proc = vim.system({ "git", "ls-tree", "HEAD", "--name-only" }, {
cwd = key,
text = true,
})
local ret = {
ignored = parse_output(ignore_proc),
tracked = parse_output(tracked_proc),
}
rawset(self, key, ret)
return ret
end,
})
end
local git_status = new_git_status()
local refresh = require("oil.actions").refresh
local orig_refresh = refresh.callback
refresh.callback = function(...)
git_status = new_git_status()
orig_refresh(...)
end
require("oil").setup({
view_options = {
is_hidden_file = function(name, bufnr)
local dir = require("oil").get_current_dir(bufnr)
local is_dotfile = vim.startswith(name, ".") and name ~= ".."
if not dir then
return is_dotfile
end
if is_dotfile then
return not git_status[dir].tracked[name]
else
return git_status[dir].ignored[name]
end
end,
},
})
<
Open Telescope file finder in the current oil directory ~
*oil-recipe-telescope*
When using `get_current_dir()` in a keymap that also opens another plugin's UI
(like Telescope), capture the directory in a local variable before the call
that changes the buffer context.
>lua
require("oil").setup({
keymaps = {
["<leader>ff"] = {
desc = "Find files in the current directory",
callback = function()
local dir = require("oil").get_current_dir()
if not dir then
vim.notify("Could not get oil directory", vim.log.levels.WARN)
return
end
require("telescope.builtin").find_files({ cwd = dir })
end,
},
["<leader>fg"] = {
desc = "Live grep in the current directory",
callback = function()
local dir = require("oil").get_current_dir()
if not dir then
vim.notify("Could not get oil directory", vim.log.levels.WARN)
return
end
require("telescope.builtin").live_grep({ cwd = dir })
end,
},
},
})
<
If you need the directory after an operation that might change the current
buffer, pass the buffer number explicitly: >lua
local bufnr = vim.api.nvim_get_current_buf()
-- ... some operation that changes the current buffer ...
local dir = require("oil").get_current_dir(bufnr)
<
Add custom column for file extension ~
*oil-recipe-extension-column*
>lua
local oil_cfg = require "oil.config"
local oil_constant = require "oil.constants"
local oil_column = require "oil.columns"
local FIELD_TYPE = oil_constant.FIELD_TYPE
local FIELD_NAME = oil_constant.FIELD_NAME
local function adjust_number(int)
return string.format("%03d%s", #int, int)
end
local function format(output)
return vim.fn.fnamemodify(output, ":e")
end
oil_column.register("extension", {
render = function(entry, _)
local field_type = entry[FIELD_TYPE]
local name = entry[FIELD_NAME]
if field_type == "file" then
if name then
local extension = format(name)
if not extension:match "%s" then
return extension
end
end
end
end,
parse = function(line, _)
return line:match "^(%S+)%s+(.*)$"
end,
create_sort_value_factory = function(num_entries)
if
oil_cfg.view_options.natural_order == false
or (oil_cfg.view_options.natural_order == "fast" and num_entries > 5000)
then
return function(entry)
return format(entry[FIELD_NAME]:lower())
end
else
local memo = {}
return function(entry)
if memo[entry] == nil and entry[FIELD_TYPE] == "file" then
local name = entry[FIELD_NAME]:gsub("0*(%d+)", adjust_number)
memo[entry] = format(name:lower())
end
return memo[entry]
end
end
end,
})
require("oil").setup({
columns = {
"size",
"extension",
"icon",
},
view_options = {
sort = {
{ "type", "asc" },
{ "extension", "asc" },
{ "name", "asc" },
},
},
})
<
Disable dimming of hidden files ~
*oil-recipe-no-hidden-dimming*
By default, hidden files (toggled with `g.`) are dimmed via the `OilHidden`
highlight group, which links to `Comment`. To make hidden files look identical
to their visible counterparts, relink each hidden group to its non-hidden
variant after calling `setup()`:
>lua
for _, hl in ipairs(require("oil")._get_highlights()) do
local base = hl.name:match("^(Oil.+)Hidden$")
if base then
vim.api.nvim_set_hl(0, hl.name, { link = base })
end
end
<
--------------------------------------------------------------------------------
EVENTS *oil-events*
Oil emits the following |User| autocmd events. Listen for them with
|nvim_create_autocmd|: >lua
vim.api.nvim_create_autocmd("User", {
pattern = "OilEnter",
callback = function(args)
vim.print("Entered oil buffer: " .. args.data.buf)
end,
})
<
OilEnter *OilEnter*
Fired once per oil buffer, after the initial directory listing has been
rendered and the buffer is ready. The `args.data.buf` field contains the
buffer number. Use this event for one-time buffer setup such as setting
keymaps or window options.
OilReadPost *OilReadPost*
Fired after every successful buffer render, including the initial render
and all subsequent re-renders (e.g. after directory changes, refreshes, or
mutations). The `args.data.buf` field contains the buffer number. Use this
event for logic that must run each time the directory listing updates.
OilMutationComplete *OilMutationComplete*
Fired after all pending mutations (create, delete, rename, move, copy)
have been executed and the affected buffers have been re-rendered. No
additional data fields. Use this event for post-mutation side effects such
as refreshing external status indicators.
--------------------------------------------------------------------------------
TRASH *oil-trash*

262
doc/recipes.md
View file

@ -1,262 +0,0 @@
# Recipes
Have a cool recipe to share? Open a pull request and add it to this doc!
<!-- TOC -->
- [Toggle file detail view](#toggle-file-detail-view)
- [Show CWD in the winbar](#show-cwd-in-the-winbar)
- [Hide gitignored files and show git tracked hidden files](#hide-gitignored-files-and-show-git-tracked-hidden-files)
- [Open Telescope file finder in the current oil directory](#open-telescope-file-finder-in-the-current-oil-directory)
- [Add custom column for file extension](#add-custom-column-for-file-extension)
- [Disable dimming of hidden files](#disable-dimming-of-hidden-files)
<!-- /TOC -->
## Toggle file detail view
```lua
local detail = false
require("oil").setup({
keymaps = {
["gd"] = {
desc = "Toggle file detail view",
callback = function()
detail = not detail
if detail then
require("oil").set_columns({ "icon", "permissions", "size", "mtime" })
else
require("oil").set_columns({ "icon" })
end
end,
},
},
})
```
## Show CWD in the winbar
```lua
-- Declare a global function to retrieve the current directory
function _G.get_oil_winbar()
local bufnr = vim.api.nvim_win_get_buf(vim.g.statusline_winid)
local dir = require("oil").get_current_dir(bufnr)
if dir then
return vim.fn.fnamemodify(dir, ":~")
else
-- If there is no current directory (e.g. over ssh), just show the buffer name
return vim.api.nvim_buf_get_name(0)
end
end
require("oil").setup({
win_options = {
winbar = "%!v:lua.get_oil_winbar()",
},
})
```
## Hide gitignored files and show git tracked hidden files
```lua
-- helper function to parse output
local function parse_output(proc)
local result = proc:wait()
local ret = {}
if result.code == 0 then
for line in vim.gsplit(result.stdout, "\n", { plain = true, trimempty = true }) do
-- Remove trailing slash
line = line:gsub("/$", "")
ret[line] = true
end
end
return ret
end
-- build git status cache
local function new_git_status()
return setmetatable({}, {
__index = function(self, key)
local ignore_proc = vim.system(
{ "git", "ls-files", "--ignored", "--exclude-standard", "--others", "--directory" },
{
cwd = key,
text = true,
}
)
local tracked_proc = vim.system({ "git", "ls-tree", "HEAD", "--name-only" }, {
cwd = key,
text = true,
})
local ret = {
ignored = parse_output(ignore_proc),
tracked = parse_output(tracked_proc),
}
rawset(self, key, ret)
return ret
end,
})
end
local git_status = new_git_status()
-- Clear git status cache on refresh
local refresh = require("oil.actions").refresh
local orig_refresh = refresh.callback
refresh.callback = function(...)
git_status = new_git_status()
orig_refresh(...)
end
require("oil").setup({
view_options = {
is_hidden_file = function(name, bufnr)
local dir = require("oil").get_current_dir(bufnr)
local is_dotfile = vim.startswith(name, ".") and name ~= ".."
-- if no local directory (e.g. for ssh connections), just hide dotfiles
if not dir then
return is_dotfile
end
-- dotfiles are considered hidden unless tracked
if is_dotfile then
return not git_status[dir].tracked[name]
else
-- Check if file is gitignored
return git_status[dir].ignored[name]
end
end,
},
})
```
## Open Telescope file finder in the current oil directory
When using `get_current_dir()` in a keymap that also opens another plugin's UI (like Telescope), always capture the directory in a local variable **before** the call that changes the buffer context. Passing `get_current_dir()` directly as an argument works because Lua evaluates arguments before calling the function, but any subsequent calls will see the new buffer.
```lua
require("oil").setup({
keymaps = {
["<leader>ff"] = {
desc = "Find files in the current directory",
callback = function()
local dir = require("oil").get_current_dir()
if not dir then
vim.notify("Could not get oil directory", vim.log.levels.WARN)
return
end
require("telescope.builtin").find_files({ cwd = dir })
end,
},
["<leader>fg"] = {
desc = "Live grep in the current directory",
callback = function()
local dir = require("oil").get_current_dir()
if not dir then
vim.notify("Could not get oil directory", vim.log.levels.WARN)
return
end
require("telescope.builtin").live_grep({ cwd = dir })
end,
},
},
})
```
If you need the directory after an operation that might change the current buffer, pass the buffer number explicitly:
```lua
local bufnr = vim.api.nvim_get_current_buf()
-- ... some operation that changes the current buffer ...
local dir = require("oil").get_current_dir(bufnr)
```
## Add custom column for file extension
```lua
local oil_cfg = require "oil.config"
local oil_constant = require "oil.constants"
local oil_column = require "oil.columns"
local FIELD_TYPE = oil_constant.FIELD_TYPE
local FIELD_NAME = oil_constant.FIELD_NAME
local function adjust_number(int)
return string.format("%03d%s", #int, int)
end
local function format(output)
return vim.fn.fnamemodify(output, ":e")
end
oil_column.register("extension", {
render = function(entry, _)
local field_type = entry[FIELD_TYPE]
local name = entry[FIELD_NAME]
if field_type == "file" then
if name then
local extension = format(name)
if not extension:match "%s" then
return extension
end
end
end
end,
parse = function(line, _)
return line:match "^(%S+)%s+(.*)$"
end,
create_sort_value_factory = function(num_entries)
if
oil_cfg.view_options.natural_order == false
or (oil_cfg.view_options.natural_order == "fast" and num_entries > 5000)
then
return function(entry)
return format(entry[FIELD_NAME]:lower())
end
else
local memo = {}
return function(entry)
if memo[entry] == nil and entry[FIELD_TYPE] == "file" then
local name = entry[FIELD_NAME]:gsub("0*(%d+)", adjust_number)
memo[entry] = format(name:lower())
end
return memo[entry]
end
end
end,
})
require("oil").setup({
columns = {
"size",
"extension",
"icon",
},
view_options = {
sort = {
{ "type", "asc" },
{ "extension", "asc" },
{ "name", "asc" },
},
},
})
```
## Disable dimming of hidden files
By default, hidden files (toggled with `g.`) are dimmed via the `OilHidden` highlight group, which links to `Comment`. Every typed hidden group (`OilDirHidden`, `OilFileHidden`, etc.) links to `OilHidden`, so all hidden entries resolve to the same dim color regardless of their type.
To make hidden files look identical to their visible counterparts, relink each hidden group to its non-hidden variant after calling `setup()`:
```lua
for _, hl in ipairs(require("oil")._get_highlights()) do
local base = hl.name:match("^(Oil.+)Hidden$")
if base then
vim.api.nvim_set_hl(0, hl.name, { link = base })
end
end
```

412
scripts/generate.py
View file

@ -1,412 +0,0 @@
import os
import os.path
import re
from dataclasses import dataclass, field
from typing import Any, Dict, List
from nvim_doc_tools import (
LuaParam,
LuaTypes,
Vimdoc,
VimdocSection,
generate_md_toc,
indent,
leftright,
parse_directory,
read_nvim_json,
read_section,
render_md_api2,
render_vimdoc_api2,
replace_section,
wrap,
)
from nvim_doc_tools.vimdoc import format_vimdoc_params
HERE = os.path.dirname(__file__)
ROOT = os.path.abspath(os.path.join(HERE, os.path.pardir))
README = os.path.join(ROOT, "README.md")
DOC = os.path.join(ROOT, "doc")
VIMDOC = os.path.join(DOC, "oil.txt")
def add_md_link_path(path: str, lines: List[str]) -> List[str]:
ret = []
for line in lines:
ret.append(re.sub(r"(\(#)", "(" + path + "#", line))
return ret
def update_md_api():
api_doc = os.path.join(DOC, "api.md")
types = parse_directory(os.path.join(ROOT, "lua"))
funcs = types.files["oil/init.lua"].functions
lines = ["\n"] + render_md_api2(funcs, types, 2) + ["\n"]
replace_section(
api_doc,
r"^<!-- API -->$",
r"^<!-- /API -->$",
lines,
)
toc = ["\n"] + generate_md_toc(api_doc, max_level=1) + ["\n"]
replace_section(
api_doc,
r"^<!-- TOC -->$",
r"^<!-- /TOC -->$",
toc,
)
toc = add_md_link_path("doc/api.md", toc)
replace_section(
README,
r"^<!-- API -->$",
r"^<!-- /API -->$",
toc,
)
def update_readme():
def get_toc(filename: str) -> List[str]:
subtoc = generate_md_toc(os.path.join(DOC, filename))
return add_md_link_path("doc/" + filename, subtoc)
recipes_toc = get_toc("recipes.md")
replace_section(
README,
r"^## Recipes$",
r"^#",
["\n"] + recipes_toc + ["\n"],
)
def update_md_toc(filename: str, max_level: int = 99):
toc = ["\n"] + generate_md_toc(filename, max_level) + ["\n"]
replace_section(
filename,
r"^<!-- TOC -->$",
r"^<!-- /TOC -->$",
toc,
)
def update_config_options():
config_file = os.path.join(ROOT, "lua", "oil", "config.lua")
opt_lines = ['\n```lua\nrequire("oil").setup({\n']
opt_lines.extend(read_section(config_file, r"^\s*local default_config =", r"^}$"))
replace_section(
README,
r"^## Options$",
r"^}\)$",
opt_lines,
)
@dataclass
class ColumnDef:
name: str
adapters: str
editable: bool
sortable: bool
summary: str
params: List["LuaParam"] = field(default_factory=list)
UNIVERSAL = [
LuaParam(
"highlight",
"string|fun(value: string): string",
"Highlight group, or function that returns a highlight group",
),
LuaParam(
"align",
'"left"|"center"|"right"',
"Text alignment within the column",
)
]
TIME = [
LuaParam("format", "string", "Format string (see :help strftime)"),
]
COL_DEFS = [
ColumnDef(
"type",
"*",
False,
True,
"The type of the entry (file, directory, link, etc)",
UNIVERSAL
+ [LuaParam("icons", "table<string, string>", "Mapping of entry type to icon")],
),
ColumnDef(
"icon",
"*",
False,
False,
"An icon for the entry's type (requires nvim-web-devicons)",
UNIVERSAL
+ [
LuaParam(
"default_file",
"string",
"Fallback icon for files when nvim-web-devicons returns nil",
),
LuaParam("directory", "string", "Icon for directories"),
LuaParam(
"add_padding",
"boolean",
"Set to false to remove the extra whitespace after the icon",
),
LuaParam(
"use_slow_filetype_detection",
"boolean",
"Set to true to detect filetypes by reading the first lines of each file (e.g. shebangs).",
),
],
),
ColumnDef("size", "files, ssh, s3", False, True, "The size of the file", UNIVERSAL + []),
ColumnDef(
"permissions",
"files, ssh",
True,
False,
"Access permissions of the file",
UNIVERSAL + [],
),
ColumnDef(
"ctime", "files", False, True, "Change timestamp of the file", UNIVERSAL + TIME + []
),
ColumnDef(
"mtime", "files", False, True, "Last modified time of the file", UNIVERSAL + TIME + []
),
ColumnDef(
"atime", "files", False, True, "Last access time of the file", UNIVERSAL + TIME + []
),
ColumnDef(
"birthtime",
"files, s3",
False,
True,
"The time the file was created",
UNIVERSAL + TIME + [],
),
]
def get_options_vimdoc() -> "VimdocSection":
section = VimdocSection("config", "oil-config")
config_file = os.path.join(ROOT, "lua", "oil", "config.lua")
opt_lines = read_section(config_file, r"^local default_config =", r"^}$")
lines = ["\n", ">lua\n", ' require("oil").setup({\n']
lines.extend(indent(opt_lines, 4))
lines.extend([" })\n", "<\n"])
section.body = lines
return section
def get_options_detail_vimdoc() -> "VimdocSection":
section = VimdocSection("options", "oil-options")
section.body.append(
"""
skip_confirm_for_simple_edits *oil.skip_confirm_for_simple_edits*
type: `boolean` default: `false`
Before performing filesystem operations, Oil displays a confirmation popup to ensure
that all operations are intentional. When this option is `true`, the popup will be
skipped if the operations:
* contain no deletes
* contain no cross-adapter moves or copies (e.g. from local to ssh)
* contain at most one copy or move
* contain at most five creates
prompt_save_on_select_new_entry *oil.prompt_save_on_select_new_entry*
type: `boolean` default: `true`
There are two cases where this option is relevant:
1. You copy a file to a new location, then you select it and make edits before
saving.
2. You copy a directory to a new location, then you enter the directory and make
changes before saving.
In case 1, when you edit the file you are actually editing the original file because
oil has not yet moved/copied it to its new location. This means that the original
file will, perhaps unexpectedly, also be changed by any edits you make.
Case 2 is similar; when you edit the directory you are again actually editing the
original location of the directory. If you add new files, those files will be
created in both the original location and the copied directory.
When this option is `true`, Oil will prompt you to save before entering a file or
directory that is pending within oil, but does not exist on disk.
"""
)
return section
def get_highlights_vimdoc() -> "VimdocSection":
section = VimdocSection("Highlights", "oil-highlights", ["\n"])
highlights = read_nvim_json('require("oil")._get_highlights()')
for hl in highlights:
name = hl["name"]
desc = hl.get("desc")
if desc is None:
continue
section.body.append(leftright(name, f"*hl-{name}*"))
section.body.extend(wrap(desc, 4))
section.body.append("\n")
return section
def load_params(params: Dict[str, Any]) -> List[LuaParam]:
ret = []
for name, data in sorted(params.items()):
ret.append(LuaParam(name, data["type"], data["desc"]))
return ret
def get_actions_vimdoc() -> "VimdocSection":
section = VimdocSection("Actions", "oil-actions", ["\n"])
section.body.append(
"""The `keymaps` option in `oil.setup` allow you to create mappings using all the same parameters as |vim.keymap.set|.
>lua
keymaps = {
-- Mappings can be a string
["~"] = "<cmd>edit $HOME<CR>",
-- Mappings can be a function
["gd"] = function()
require("oil").set_columns({ "icon", "permissions", "size", "mtime" })
end,
-- You can pass additional opts to vim.keymap.set by using
-- a table with the mapping as the first element.
["<leader>ff"] = {
function()
require("telescope.builtin").find_files({
cwd = require("oil").get_current_dir()
})
end,
mode = "n",
nowait = true,
desc = "Find files in the current directory"
},
-- Mappings that are a string starting with "actions." will be
-- one of the built-in actions, documented below.
["`"] = "actions.tcd",
-- Some actions have parameters. These are passed in via the `opts` key.
["<leader>:"] = {
"actions.open_cmdline",
opts = {
shorten_path = true,
modify = ":h",
},
desc = "Open the command line with the current directory as an argument",
},
}
"""
)
section.body.append("\n")
section.body.extend(
wrap(
"""Below are the actions that can be used in the `keymaps` section of config options. You can refer to them as strings (e.g. "actions.<action_name>") or you can use the functions directly with `require("oil.actions").action_name.callback()`"""
)
)
section.body.append("\n")
actions = read_nvim_json('require("oil.actions")._get_actions()')
actions.sort(key=lambda a: a["name"])
for action in actions:
if action.get("deprecated"):
continue
name = action["name"]
desc = action["desc"]
section.body.append(leftright(name, f"*actions.{name}*"))
section.body.extend(wrap(desc, 4))
params = action.get("parameters")
if params:
section.body.append("\n")
section.body.append(" Parameters:\n")
section.body.extend(
format_vimdoc_params(load_params(params), LuaTypes(), 6)
)
section.body.append("\n")
return section
def get_columns_vimdoc() -> "VimdocSection":
section = VimdocSection("Columns", "oil-columns", ["\n"])
section.body.extend(
wrap(
'Columns can be specified as a string to use default arguments (e.g. `"icon"`), or as a table to pass parameters (e.g. `{"size", highlight = "Special"}`)'
)
)
section.body.append("\n")
for col in COL_DEFS:
section.body.append(leftright(col.name, f"*column-{col.name}*"))
section.body.extend(wrap(f"Adapters: {col.adapters}", 4))
if col.sortable:
section.body.extend(
wrap(f"Sortable: this column can be used in view_props.sort", 4)
)
if col.editable:
section.body.extend(wrap(f"Editable: this column is read/write", 4))
section.body.extend(wrap(col.summary, 4))
section.body.append("\n")
section.body.append(" Parameters:\n")
section.body.extend(format_vimdoc_params(col.params, LuaTypes(), 6))
section.body.append("\n")
return section
def get_trash_vimdoc() -> "VimdocSection":
section = VimdocSection("Trash", "oil-trash", [])
section.body.append(
"""
Oil has built-in support for using the system trash. When
`delete_to_trash = true`, any deleted files will be sent to the trash instead
of being permanently deleted. You can browse the trash for a directory using
the `toggle_trash` action (bound to `g\\` by default). You can view all files
in the trash with `:Oil --trash /`.
To restore files, simply move them from the trash to the desired destination,
the same as any other file operation. If you delete files from the trash they
will be permanently deleted (purged).
Linux:
Oil supports the FreeDesktop trash specification.
https://specifications.freedesktop.org/trash/1.0/
All features should work.
Mac:
Oil has limited support for MacOS due to the proprietary nature of the
implementation. The trash bin can only be viewed as a single dir
(instead of being able to see files that were trashed from a directory).
Windows:
Oil supports the Windows Recycle Bin. All features should work.
"""
)
return section
def generate_vimdoc():
doc = Vimdoc("oil.txt", "oil")
types = parse_directory(os.path.join(ROOT, "lua"))
funcs = types.files["oil/init.lua"].functions
doc.sections.extend(
[
get_options_vimdoc(),
get_options_detail_vimdoc(),
VimdocSection("API", "oil-api", render_vimdoc_api2("oil", funcs, types)),
get_columns_vimdoc(),
get_actions_vimdoc(),
get_highlights_vimdoc(),
get_trash_vimdoc(),
]
)
with open(VIMDOC, "w", encoding="utf-8") as ofile:
ofile.writelines(doc.render())
def main() -> None:
"""Update the README"""
update_config_options()
update_md_api()
update_md_toc(README, max_level=1)
update_md_toc(os.path.join(DOC, "recipes.md"))
update_readme()
generate_vimdoc()

31
scripts/main.py
View file

@ -1,31 +0,0 @@
#!/usr/bin/env python
import argparse
import os
import sys
HERE = os.path.dirname(__file__)
ROOT = os.path.abspath(os.path.join(HERE, os.path.pardir))
DOC = os.path.join(ROOT, "doc")
def main() -> None:
"""Generate docs"""
sys.path.append(HERE)
parser = argparse.ArgumentParser(description=main.__doc__)
parser.add_argument("command", choices=["generate", "lint"])
args = parser.parse_args()
if args.command == "generate":
import generate
generate.main()
elif args.command == "lint":
from nvim_doc_tools import lint_md_links
files = [os.path.join(ROOT, "README.md")] + [
os.path.join(DOC, file) for file in os.listdir(DOC) if file.endswith(".md")
]
lint_md_links.main(ROOT, files)
if __name__ == "__main__":
main()

4
scripts/requirements.txt
View file

@ -1,4 +0,0 @@
pyparsing==3.0.9
black
isort
mypy