a410507846
* feat(ftp): add FTP/FTPS adapter via curl Problem: canola has no way to browse or edit files on FTP servers, despite the adapter system being designed for exactly this pattern. curl speaks FTP natively, including FTPS (FTP over TLS), and requires no new dependencies. Solution: implement `lua/oil/adapters/ftp.lua` with `oil-ftp://` and `oil-ftps://` schemes. Parses Unix and IIS LIST output, supports `size`, `mtime`, and `permissions` columns, and implements the full adapter API (list, read_file, write_file, render_action, perform_action). Same-host renames use RNFR/RNTO; cross-host and local↔FTP copies use curl download/upload through a tmpfile. Adds `extra_curl_args` config option and documents the adapter in `doc/oil.txt`. Based on: stevearc/oil.nvim#210 * docs(upstream): mark #210 fixed in #167 * fix(ftp): use python3 ftplib for control-channel FTP operations Problem: DELE, RMD, MKD, and RNFR/RNTO were implemented using curl --quote, which requires a subsequent LIST or STOR to trigger the FTP connection. That data-channel operation hangs on slow or busy servers, making every mutation appear stuck. Solution: replace the curl --quote approach with a python3 ftplib one-liner for all control-channel operations. ftplib executes DELE, RMD, MKD, RNFR/RNTO, and SITE CHMOD without opening a data channel, so they complete instantly. The curl wrapper is retained for LIST, read_file, and write_file, which genuinely need a data channel. * fix(ftp): use nil entry ID so cache assigns unique IDs Problem: `M.list` returned entries as `{0, name, type, meta}`. `cache.store_entry` only assigns a fresh ID when `entry[FIELD_ID] == nil`; passing 0 caused every entry to be stored as ID 0, all overwriting each other. `get_entry_by_id(0)` then always returned the last-stored entry, breaking navigation (always opened the same file), rename (wrong entry matched), and create (wrong diff). Solution: change the placeholder from 0 to nil, matching how `cache.create_entry` itself builds entries. * fix(ftp): use ftp.rename() for RNFR/RNTO and raw Python lines in ftpcmd Problem: `ftpcmd` wrapped every command in `ftp.voidcmd()`, which expects a final 2xx response. `RNFR` returns 350 (intermediate), so `voidcmd` raised an exception before `RNTO` was ever sent, causing every rename to fail with '350 Ready for destination name'. Solution: change `ftpcmd` to accept raw Python lines instead of FTP command strings, then use `ftp.rename(src, dst)` for the rename case. `ftplib.rename` handles the 350 intermediate response correctly internally. All other callers now wrap their FTP commands in `ftp.voidcmd()` explicitly. * fix(ftp): recursively delete directory contents before RMD Problem: FTP's RMD command fails with '550 Directory not empty' if the directory has any contents. Unlike the S3 adapter which uses `aws s3 rm --recursive`, FTP has no protocol-level recursive delete. Solution: emit a Python rmtree helper inside the ftpcmd script that walks the directory via MLSD, recursively deletes children (DELE for files, rmtree for subdirs), then sends RMD on the now-empty directory. * fix(ftp): give oil-ftps:// its own adapter name to prevent scheme clobbering Problem: both oil-ftp:// and oil-ftps:// mapped to the adapter name 'ftp', so config.adapter_to_scheme['ftp'] was set to whichever scheme pairs() iterated last — non-deterministic. init.lua uses adapter_to_scheme[adapter.name] to reconstruct the parent URL, so roughly half the time it injected 'oil-ftps://' into ftp:// buffer navigation, causing the ssl-reqd error on '-' press. Solution: register oil-ftps:// under adapter name 'ftps' via a one-line shim that returns require('oil.adapters.ftp'). Now adapter_to_scheme['ftp'] = 'oil-ftp://' and adapter_to_scheme['ftps'] = 'oil-ftps://' are both stable. * fix(ftp): percent-encode path in curl FTP URLs Problem: filenames containing spaces (or other URL-unsafe characters) caused curl to fail with "Unknown error" because the raw path was concatenated directly into the FTP URL. Solution: add `url_encode_path` to encode non-safe characters (excluding `/`) before building the curl URL in `curl_ftp_url`. * fix(ftp): fix STARTTLS, error visibility, and robustness Problem: `curl_ftp_url` emitted `ftps://` (implicit TLS) for `oil-ftps://` URLs, causing listing to fail against STARTTLS servers while Python mutations worked — the two paths spoke different TLS modes. curl's `-s` flag silenced all error output, producing "Unknown error" on any curl failure. File creation used `/dev/null` (breaks on Windows, diverges from S3). The Python TLS context didn't honour `--insecure`/`-k` from `extra_curl_args`. Deleting non-empty dirs on servers without MLSD gave a cryptic `500 Unknown command`. Solution: Always emit `ftp://` in `curl_ftp_url`; TLS is enforced solely via `--ssl-reqd`, making STARTTLS consistent between curl and Python. Add `-S` to expose curl errors. Replace `/dev/null` with `curl -T -` + `stdin='null'` (matches `s3fs` pattern). Mirror `--insecure`/`-k` into the Python SSL context. Wrap `mlsd()` in try/except with a clear actionable message. Add `spec/ftp_spec.lua` with 28 unit tests covering URL parsing, list parsing, and curl URL building. Update `doc/oil.txt` to document STARTTLS and MLSD. * ci: format * fix(ftp): resolve LuaLS type warnings in `curl` wrapper and `parse_unix_list_line`
1492 lines
60 KiB
Text
1492 lines
60 KiB
Text
*oil.txt*
|
|
*Oil* *oil* *Canola* *canola*
|
|
--------------------------------------------------------------------------------
|
|
CONTENTS *oil-contents*
|
|
|
|
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*
|
|
|
|
Configure oil via `setup()`: >lua
|
|
require("oil").setup({
|
|
-- your opts here
|
|
})
|
|
<
|
|
|
|
The full list of options with their defaults:
|
|
|
|
>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,
|
|
-- When true and a directory has no visible entries, show hidden entries
|
|
-- instead of an empty listing. is_always_hidden entries are never shown.
|
|
show_hidden_when_empty = 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 = {},
|
|
-- Extra arguments to pass to curl for FTP operations
|
|
extra_curl_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,
|
|
-- Maximum file size in MB to load into the preview window. Files larger
|
|
-- than this limit will show a placeholder message instead of being loaded.
|
|
-- Set to nil to disable the limit.
|
|
max_file_size = 10,
|
|
-- 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,
|
|
},
|
|
})
|
|
<
|
|
|
|
--------------------------------------------------------------------------------
|
|
OPTIONS *oil-options*
|
|
|
|
|
|
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
|
|
|
|
skip_confirm_for_delete *oil.skip_confirm_for_delete*
|
|
type: `boolean` default: `false`
|
|
When this option is `true`, the confirmation popup will be skipped if all pending
|
|
actions are deletes.
|
|
|
|
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.
|
|
|
|
auto_save_on_select_new_entry *oil.auto_save_on_select_new_entry*
|
|
type: `boolean` default: `false`
|
|
When `prompt_save_on_select_new_entry` is true and you select a
|
|
new/moved/renamed entry, automatically save without prompting instead of
|
|
showing a confirmation dialog.
|
|
|
|
cleanup_buffers_on_delete *oil.cleanup_buffers_on_delete*
|
|
type: `boolean` default: `false`
|
|
When `true`, oil will wipe any open buffer whose path matches a file that
|
|
was successfully deleted via oil. This prevents stale buffers from
|
|
appearing in the jumplist after a deletion.
|
|
|
|
show_hidden_when_empty *oil.show_hidden_when_empty*
|
|
type: `boolean` default: `false`
|
|
When `true` and a directory contains no visible entries (because all
|
|
entries are hidden), oil will display the hidden entries anyway.
|
|
Entries matching `is_always_hidden` are never shown. Hidden entries
|
|
are still rendered with the dimmed hidden style.
|
|
|
|
preview_win.max_file_size *oil.preview_win*
|
|
type: `number` default: `10`
|
|
Maximum file size in MB to load into the preview window. Files larger
|
|
than this limit will show a placeholder message instead of being loaded.
|
|
Set to `nil` to disable the limit.
|
|
|
|
--------------------------------------------------------------------------------
|
|
API *oil-api*
|
|
|
|
get_entry_on_line({bufnr}, {lnum}): nil|oil.Entry *oil.get_entry_on_line*
|
|
Get the entry on a specific line (1-indexed)
|
|
|
|
Parameters:
|
|
{bufnr} `integer`
|
|
{lnum} `integer`
|
|
|
|
get_cursor_entry(): nil|oil.Entry *oil.get_cursor_entry*
|
|
Get the entry currently under the cursor
|
|
|
|
|
|
discard_all_changes() *oil.discard_all_changes*
|
|
Discard all changes made to oil buffers
|
|
|
|
|
|
set_columns({cols}) *oil.set_columns*
|
|
Change the display columns for oil
|
|
|
|
Parameters:
|
|
{cols} `oil.ColumnSpec[]`
|
|
|
|
set_sort({sort}) *oil.set_sort*
|
|
Change the sort order for oil
|
|
|
|
Parameters:
|
|
{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}) *oil.set_is_hidden_file*
|
|
Change how oil determines if the file is hidden
|
|
|
|
Parameters:
|
|
{is_hidden_file} `fun(filename: string, bufnr: integer, entry: oil.Entry): boolean`
|
|
Return true if the file/dir should be hidden
|
|
|
|
toggle_hidden() *oil.toggle_hidden*
|
|
Toggle hidden files and directories
|
|
|
|
|
|
get_current_dir({bufnr}): nil|string *oil.get_current_dir*
|
|
Get the current directory as a local filesystem path. Returns nil for
|
|
non-local adapters (SSH, S3, trash). See |oil.get_current_url| for an
|
|
adapter-agnostic alternative.
|
|
|
|
Parameters:
|
|
{bufnr} `nil|integer`
|
|
|
|
get_current_url({bufnr}): nil|string *oil.get_current_url*
|
|
Get the current buffer's oil URL (e.g. "oil:///path/" or
|
|
"oil-ssh://host/path/"). Works for all adapters. Returns nil if the
|
|
buffer is not an oil buffer.
|
|
|
|
Parameters:
|
|
{bufnr} `nil|integer`
|
|
|
|
open_float({dir}, {opts}, {cb}) *oil.open_float*
|
|
Open oil browser in a floating window
|
|
|
|
Parameters:
|
|
{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"` S
|
|
plit modifier
|
|
{cb} `nil|fun()` Called after the oil buffer is ready
|
|
|
|
toggle_float({dir}, {opts}, {cb}) *oil.toggle_float*
|
|
Open oil browser in a floating window, or close it if open
|
|
|
|
Parameters:
|
|
{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"` S
|
|
plit modifier
|
|
{cb} `nil|fun()` Called after the oil buffer is ready
|
|
|
|
open_split({dir}, {opts}, {cb}) *oil.open_split*
|
|
Open oil browser in a split window
|
|
|
|
Parameters:
|
|
{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.OpenSplitOpts`
|
|
{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_split({dir}, {opts}, {cb}) *oil.toggle_split*
|
|
Open oil browser in a split window, or close it if open
|
|
|
|
Parameters:
|
|
{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.OpenSplitOpts`
|
|
{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}) *oil.open*
|
|
Open oil browser for a directory
|
|
|
|
Parameters:
|
|
{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"` S
|
|
plit modifier
|
|
{cb} `nil|fun()` Called after the oil buffer is ready
|
|
|
|
close({opts}) *oil.close*
|
|
Restore the buffer that was present when oil was opened
|
|
|
|
Parameters:
|
|
{opts} `nil|oil.CloseOpts`
|
|
{exit_if_last_buf} `nil|boolean` Exit vim if this oil buffer is the
|
|
last open buffer
|
|
|
|
toggle({dir}, {opts}, {cb}) *oil.toggle*
|
|
Open oil browser for a directory, or close it if already open
|
|
|
|
Parameters:
|
|
{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"` S
|
|
plit modifier
|
|
{cb} `nil|fun()` Called after the oil buffer is ready
|
|
|
|
open_preview({opts}, {callback}) *oil.open_preview*
|
|
Preview the entry under the cursor in a split
|
|
|
|
Parameters:
|
|
{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}) *oil.select*
|
|
Select the entry under the cursor
|
|
|
|
Parameters:
|
|
{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}) *oil.save*
|
|
Save all changes
|
|
|
|
Parameters:
|
|
{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:
|
|
If you provide your own callback function, there will be no notification for errors.
|
|
|
|
setup({opts}) *oil.setup*
|
|
Initialize oil
|
|
|
|
Parameters:
|
|
{opts} `oil.setupOpts|nil`
|
|
|
|
--------------------------------------------------------------------------------
|
|
COLUMNS *oil-columns*
|
|
|
|
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"}`)
|
|
|
|
type *column-type*
|
|
Adapters: *
|
|
Sortable: this column can be used in view_props.sort
|
|
The type of the entry (file, directory, link, etc)
|
|
|
|
Parameters:
|
|
{highlight} `string|fun(value: string): string` Highlight group, or
|
|
function that returns a highlight group
|
|
{align} `"left"|"center"|"right"` Text alignment within the column
|
|
{icons} `table<string, string>` Mapping of entry type to icon
|
|
|
|
icon *column-icon*
|
|
Adapters: *
|
|
An icon for the entry's type (requires nvim-web-devicons)
|
|
|
|
Parameters:
|
|
{highlight} `string|fun(value: string): string` Highlight group, or
|
|
function that returns a highlight group
|
|
{align} `"left"|"center"|"right"` Text alignment within the column
|
|
{default_file} `string` Fallback icon for files when nvim-web-devicons
|
|
returns nil
|
|
{directory} `string` Icon for directories
|
|
{add_padding} `boolean` Set to false to remove the extra whitespace after
|
|
the icon
|
|
{use_slow_filetype_detection} `boolean` Set to true to detect filetypes by
|
|
reading the first lines of each file (e.g. shebangs).
|
|
|
|
size *column-size*
|
|
Adapters: files, ssh, s3
|
|
Sortable: this column can be used in view_props.sort
|
|
The size of the file
|
|
|
|
Parameters:
|
|
{highlight} `string|fun(value: string): string` Highlight group, or
|
|
function that returns a highlight group
|
|
{align} `"left"|"center"|"right"` Text alignment within the column
|
|
|
|
permissions *column-permissions*
|
|
Adapters: files, ssh
|
|
Editable: this column is read/write
|
|
Access permissions of the file
|
|
|
|
Parameters:
|
|
{highlight} `string|fun(value: string): string` Highlight group, or
|
|
function that returns a highlight group
|
|
{align} `"left"|"center"|"right"` Text alignment within the column
|
|
|
|
ctime *column-ctime*
|
|
Adapters: files
|
|
Sortable: this column can be used in view_props.sort
|
|
Change timestamp of the file
|
|
|
|
Parameters:
|
|
{highlight} `string|fun(value: string): string` Highlight group, or
|
|
function that returns a highlight group
|
|
{align} `"left"|"center"|"right"` Text alignment within the column
|
|
{format} `string` Format string (see :help strftime)
|
|
|
|
mtime *column-mtime*
|
|
Adapters: files
|
|
Sortable: this column can be used in view_props.sort
|
|
Last modified time of the file
|
|
|
|
Parameters:
|
|
{highlight} `string|fun(value: string): string` Highlight group, or
|
|
function that returns a highlight group
|
|
{align} `"left"|"center"|"right"` Text alignment within the column
|
|
{format} `string` Format string (see :help strftime)
|
|
|
|
atime *column-atime*
|
|
Adapters: files
|
|
Sortable: this column can be used in view_props.sort
|
|
Last access time of the file
|
|
|
|
Parameters:
|
|
{highlight} `string|fun(value: string): string` Highlight group, or
|
|
function that returns a highlight group
|
|
{align} `"left"|"center"|"right"` Text alignment within the column
|
|
{format} `string` Format string (see :help strftime)
|
|
|
|
birthtime *column-birthtime*
|
|
Adapters: files, s3
|
|
Sortable: this column can be used in view_props.sort
|
|
The time the file was created
|
|
|
|
Parameters:
|
|
{highlight} `string|fun(value: string): string` Highlight group, or
|
|
function that returns a highlight group
|
|
{align} `"left"|"center"|"right"` Text alignment within the column
|
|
{format} `string` Format string (see :help strftime)
|
|
|
|
--------------------------------------------------------------------------------
|
|
ACTIONS *oil-actions*
|
|
|
|
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",
|
|
},
|
|
}
|
|
|
|
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()`
|
|
|
|
cd *actions.cd*
|
|
:cd to the current oil directory
|
|
|
|
Parameters:
|
|
{scope} `nil|"tab"|"win"` Scope of the directory change (e.g. use |:tcd|
|
|
or |:lcd|)
|
|
{silent} `boolean` Do not show a message when changing directories
|
|
|
|
change_sort *actions.change_sort*
|
|
Change the sort order
|
|
|
|
Parameters:
|
|
{sort} `oil.SortSpec[]` List of columns plus direction (see
|
|
|oil.set_sort|) instead of interactive selection
|
|
|
|
close *actions.close*
|
|
Close oil and restore original buffer
|
|
|
|
Parameters:
|
|
{exit_if_last_buf} `boolean` Exit vim if oil is closed as the last buffer
|
|
|
|
close_float *actions.close_float*
|
|
Close oil if the window is floating, otherwise do nothing
|
|
|
|
Parameters:
|
|
{exit_if_last_buf} `boolean` Exit vim if oil is closed as the last buffer
|
|
|
|
copy_to_system_clipboard *actions.copy_to_system_clipboard*
|
|
Copy the entry under the cursor to the system clipboard
|
|
|
|
open_cmdline *actions.open_cmdline*
|
|
Open vim cmdline with current entry as an argument
|
|
|
|
Parameters:
|
|
{modify} `string` Modify the path with |fnamemodify()| using this as
|
|
the mods argument
|
|
{shorten_path} `boolean` Use relative paths when possible
|
|
|
|
open_cwd *actions.open_cwd*
|
|
Open oil in Neovim's current working directory
|
|
|
|
open_external *actions.open_external*
|
|
Open the entry under the cursor in an external program
|
|
|
|
open_terminal *actions.open_terminal*
|
|
Open a terminal in the current directory
|
|
|
|
parent *actions.parent*
|
|
Navigate to the parent path
|
|
|
|
paste_from_system_clipboard *actions.paste_from_system_clipboard*
|
|
Paste the system clipboard into the current oil directory
|
|
|
|
Parameters:
|
|
{delete_original} `boolean` Delete the original file after copying
|
|
|
|
preview *actions.preview*
|
|
Open the entry under the cursor in a preview window, or close the preview
|
|
window if already open
|
|
|
|
Parameters:
|
|
{horizontal} `boolean` Open the buffer in a horizontal split
|
|
{split} `"aboveleft"|"belowright"|"topleft"|"botright"` Split
|
|
modifier
|
|
{vertical} `boolean` Open the buffer in a vertical split
|
|
|
|
preview_scroll_down *actions.preview_scroll_down*
|
|
Scroll down in the preview window
|
|
|
|
preview_scroll_left *actions.preview_scroll_left*
|
|
Scroll left in the preview window
|
|
|
|
preview_scroll_right *actions.preview_scroll_right*
|
|
Scroll right in the preview window
|
|
|
|
preview_scroll_up *actions.preview_scroll_up*
|
|
Scroll up in the preview window
|
|
|
|
refresh *actions.refresh*
|
|
Refresh current directory list
|
|
|
|
Parameters:
|
|
{force} `boolean` When true, do not prompt user if they will be discarding
|
|
changes
|
|
|
|
select *actions.select*
|
|
Open the entry under the cursor
|
|
|
|
Parameters:
|
|
{close} `boolean` Close the original oil buffer once selection is
|
|
made
|
|
{horizontal} `boolean` Open the buffer in a horizontal split
|
|
{split} `"aboveleft"|"belowright"|"topleft"|"botright"` Split
|
|
modifier
|
|
{tab} `boolean` Open the buffer in a new tab
|
|
{vertical} `boolean` Open the buffer in a vertical split
|
|
|
|
send_to_qflist *actions.send_to_qflist*
|
|
Sends files in the current oil directory to the quickfix list, replacing the
|
|
previous entries.
|
|
|
|
Parameters:
|
|
{action} `"r"|"a"` Replace or add to current quickfix list (see
|
|
|setqflist-action|)
|
|
{only_matching_search} `boolean` Whether to only add the files that
|
|
matches the last search. This option only applies when search
|
|
highlighting is active
|
|
{target} `"qflist"|"loclist"` The target list to send files to
|
|
|
|
show_help *actions.show_help*
|
|
Show default keymaps
|
|
|
|
toggle_hidden *actions.toggle_hidden*
|
|
Toggle hidden files and directories
|
|
|
|
toggle_trash *actions.toggle_trash*
|
|
Jump to and from the trash for the current directory
|
|
|
|
yank_entry *actions.yank_entry*
|
|
Yank the filepath of the entry under the cursor to a register
|
|
|
|
Parameters:
|
|
{modify} `string` Modify the path with |fnamemodify()| using this as the
|
|
mods argument
|
|
|
|
--------------------------------------------------------------------------------
|
|
HIGHLIGHTS *oil-highlights*
|
|
|
|
OilEmpty *hl-OilEmpty*
|
|
Empty column values
|
|
|
|
OilHidden *hl-OilHidden*
|
|
Hidden entry in an oil buffer
|
|
|
|
OilDir *hl-OilDir*
|
|
Directory names in an oil buffer
|
|
|
|
OilDirHidden *hl-OilDirHidden*
|
|
Hidden directory names in an oil buffer
|
|
|
|
OilDirIcon *hl-OilDirIcon*
|
|
Icon for directories
|
|
|
|
OilFileIcon *hl-OilFileIcon*
|
|
Icon for files
|
|
|
|
OilSocket *hl-OilSocket*
|
|
Socket files in an oil buffer
|
|
|
|
OilSocketHidden *hl-OilSocketHidden*
|
|
Hidden socket files in an oil buffer
|
|
|
|
OilLink *hl-OilLink*
|
|
Soft links in an oil buffer
|
|
|
|
OilOrphanLink *hl-OilOrphanLink*
|
|
Orphaned soft links in an oil buffer
|
|
|
|
OilLinkHidden *hl-OilLinkHidden*
|
|
Hidden soft links in an oil buffer
|
|
|
|
OilOrphanLinkHidden *hl-OilOrphanLinkHidden*
|
|
Hidden orphaned soft links in an oil buffer
|
|
|
|
OilLinkTarget *hl-OilLinkTarget*
|
|
The target of a soft link
|
|
|
|
OilOrphanLinkTarget *hl-OilOrphanLinkTarget*
|
|
The target of an orphaned soft link
|
|
|
|
OilLinkTargetHidden *hl-OilLinkTargetHidden*
|
|
The target of a hidden soft link
|
|
|
|
OilOrphanLinkTargetHidden *hl-OilOrphanLinkTargetHidden*
|
|
The target of an hidden orphaned soft link
|
|
|
|
OilFile *hl-OilFile*
|
|
Normal files in an oil buffer
|
|
|
|
OilFileHidden *hl-OilFileHidden*
|
|
Hidden normal files in an oil buffer
|
|
|
|
OilExecutable *hl-OilExecutable*
|
|
Executable files in an oil buffer
|
|
|
|
OilExecutableHidden *hl-OilExecutableHidden*
|
|
Hidden executable files in an oil buffer
|
|
|
|
OilPermissionRead *hl-OilPermissionRead*
|
|
Read permission character in the permissions column
|
|
|
|
OilPermissionWrite *hl-OilPermissionWrite*
|
|
Write permission character in the permissions column
|
|
|
|
OilPermissionExec *hl-OilPermissionExec*
|
|
Execute permission character in the permissions column
|
|
|
|
OilPermissionSetuid *hl-OilPermissionSetuid*
|
|
Setuid/setgid permission character in the permissions column
|
|
|
|
OilPermissionSticky *hl-OilPermissionSticky*
|
|
Sticky bit permission character in the permissions column
|
|
|
|
OilPermissionNone *hl-OilPermissionNone*
|
|
No permission character in the permissions column
|
|
|
|
OilCreate *hl-OilCreate*
|
|
Create action in the oil preview window
|
|
|
|
OilDelete *hl-OilDelete*
|
|
Delete action in the oil preview window
|
|
|
|
OilMove *hl-OilMove*
|
|
Move action in the oil preview window
|
|
|
|
OilCopy *hl-OilCopy*
|
|
Copy action in the oil preview window
|
|
|
|
OilChange *hl-OilChange*
|
|
Change action in the oil preview window
|
|
|
|
OilRestore *hl-OilRestore*
|
|
Restore (from the trash) action in the oil preview window
|
|
|
|
OilPurge *hl-OilPurge*
|
|
Purge (Permanently delete a file from trash) action in the oil preview
|
|
window
|
|
|
|
OilTrash *hl-OilTrash*
|
|
Trash (delete a file to trash) action in the oil preview window
|
|
|
|
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`).
|
|
|
|
How it works ~
|
|
|
|
Oil opens a persistent SSH connection to the remote host and runs shell
|
|
commands over stdin/stdout. Nothing is mounted locally. Directory listings
|
|
come from `ls -la`; file reads and writes go through `scp`. One connection
|
|
is maintained per unique host/port/user combination and reused across
|
|
buffers.
|
|
|
|
If the connection takes longer than 2 seconds (e.g. waiting for a password
|
|
or host-key confirmation), oil automatically opens a floating terminal so
|
|
you can interact with the SSH prompt. Configure this window with the `ssh`
|
|
key in `float_win_config`: >lua
|
|
require("oil").setup({
|
|
float_win_config = {
|
|
ssh = { border = "rounded" },
|
|
},
|
|
})
|
|
<
|
|
Configuration ~
|
|
|
|
Pass extra flags to `scp` with `extra_scp_args`. This is useful for hosts
|
|
that require legacy SCP protocol (`-O`) or a specific cipher: >lua
|
|
require("oil").setup({
|
|
extra_scp_args = { "-O" },
|
|
})
|
|
<
|
|
The underlying `ssh` command respects `~/.ssh/config`, so per-host
|
|
settings like `IdentityFile`, `ProxyJump`, and `Port` work as expected.
|
|
|
|
Limitations ~
|
|
|
|
The SSH adapter is self-contained. It does not expose a mount point or
|
|
local filesystem path, so other plugins (Telescope, tree views, LSP)
|
|
cannot access remote files through it. For full remote development,
|
|
consider mounting the remote filesystem with `sshfs` or using
|
|
`distant.nvim`.
|
|
|
|
Files can be copied between local and SSH adapters (uses `scp`), but
|
|
cross-adapter moves are not supported — use copy + delete instead.
|
|
|
|
Troubleshooting ~
|
|
|
|
Connection hangs: Check that key-based authentication is configured in
|
|
`~/.ssh/config`. Password prompts work but require interaction through
|
|
the floating terminal.
|
|
|
|
Permission denied on `scp`: Some hosts (notably Synology NAS) expose a
|
|
different directory tree over SFTP than over SSH. Try adding `-O` to
|
|
`extra_scp_args` to force the legacy SCP protocol.
|
|
|
|
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`.
|
|
|
|
FTP *oil-adapter-ftp*
|
|
|
|
Browse files over FTP or FTPS (FTP over TLS). Open a buffer with: >
|
|
nvim oil-ftp://[username[:password]@]hostname[:port]/[path]/
|
|
nvim oil-ftps://[username[:password]@]hostname[:port]/[path]/
|
|
<
|
|
The `oil-ftps://` scheme uses explicit TLS (STARTTLS / AUTH TLS, RFC 4217).
|
|
The server must support the `AUTH TLS` command on port 21. Servers using
|
|
implicit TLS (port 990) are not supported. Use `oil-ftp://` for plain FTP.
|
|
|
|
Authentication ~
|
|
|
|
Credentials can be supplied in the URL (`user:pass@host`) or stored in
|
|
`~/.netrc` (recommended — keeps passwords out of shell history): >
|
|
machine ftp.example.com login myuser password mypass
|
|
<
|
|
How it works ~
|
|
|
|
The FTP adapter uses `curl` to perform all operations. Directory listings
|
|
come from FTP LIST output (Unix and IIS/Windows formats are both supported).
|
|
File reads download to a local tempfile; file writes upload from a tempfile.
|
|
Renames on the same server use the FTP RNFR/RNTO commands. File copies
|
|
between servers go through a local tempfile.
|
|
|
|
Limitations ~
|
|
|
|
Symbolic links cannot be created over FTP. Directory copies are not
|
|
supported (copy individual files instead). Moving or copying directories
|
|
across different FTP hosts is not supported. Deleting non-empty directories
|
|
requires MLSD support (RFC 3659); supported by vsftpd, ProFTPD, FileZilla
|
|
Server, and most servers from 2007 onwards.
|
|
|
|
Configuration ~
|
|
|
|
Pass extra flags to `curl` with `extra_curl_args`: >lua
|
|
require("oil").setup({
|
|
extra_curl_args = { "--insecure" },
|
|
})
|
|
<
|
|
The adapter supports the `size`, `mtime`, and `permissions` columns.
|
|
Permission changes use the FTP `SITE CHMOD` command; not all servers
|
|
support it.
|
|
|
|
Dependencies ~
|
|
|
|
Requires `curl` (standard on Linux and macOS).
|
|
|
|
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
|
|
<
|
|
|
|
Use FreeDesktop trash on macOS ~
|
|
*oil-recipe-macos-freedesktop-trash*
|
|
|
|
For full FreeDesktop spec compliance on macOS (list, restore operations), or
|
|
for compatibility with FreeDesktop-compliant trash programs like gtrash:
|
|
>lua
|
|
package.loaded["oil.adapters.trash.mac"] = require("oil.adapters.trash.freedesktop")
|
|
<
|
|
|
|
Flash highlight on opened file ~
|
|
*oil-recipe-highlight-opened-file*
|
|
|
|
When opening a directory from a file buffer, briefly highlight the originating
|
|
file's name in the listing. Uses |OilReadPost| to apply a timed extmark after
|
|
the buffer renders.
|
|
>lua
|
|
local ns = vim.api.nvim_create_namespace("oil_highlight_entry")
|
|
vim.api.nvim_create_autocmd("User", {
|
|
pattern = "OilReadPost",
|
|
callback = function(args)
|
|
vim.defer_fn(function()
|
|
local bufnr = args.data.buf
|
|
if not vim.api.nvim_buf_is_valid(bufnr) then
|
|
return
|
|
end
|
|
vim.api.nvim_buf_clear_namespace(bufnr, ns, 0, -1)
|
|
local entry = require("oil").get_cursor_entry()
|
|
if not entry then
|
|
return
|
|
end
|
|
local lnum = vim.api.nvim_win_get_cursor(0)[1] - 1
|
|
local line = vim.api.nvim_buf_get_lines(bufnr, lnum, lnum + 1, true)[1]
|
|
local col = line:find(entry.name, 1, true)
|
|
if col then
|
|
vim.api.nvim_buf_set_extmark(bufnr, ns, lnum, col - 1, {
|
|
end_col = col - 1 + #entry.name,
|
|
hl_group = "Visual",
|
|
})
|
|
vim.defer_fn(function()
|
|
pcall(vim.api.nvim_buf_clear_namespace, bufnr, ns, 0, -1)
|
|
end, 1500)
|
|
end
|
|
end, 50)
|
|
end,
|
|
})
|
|
<
|
|
|
|
*oil-recipe-paste-file-from-clipboard*
|
|
|
|
Copy a file into the current oil directory by pasting its absolute path from
|
|
the system clipboard. Useful on macOS where copying a file in Finder places its
|
|
path in the clipboard.
|
|
>lua
|
|
vim.keymap.set("n", "gp", function()
|
|
local oil = require("oil")
|
|
local dir = oil.get_current_dir()
|
|
if not dir then
|
|
return
|
|
end
|
|
local path = vim.fn.getreg("+"):gsub("\n$", "")
|
|
if path == "" or not vim.uv.fs_stat(path) then
|
|
vim.notify("Clipboard does not contain a valid file path", vim.log.levels.WARN)
|
|
return
|
|
end
|
|
local name = vim.fn.fnamemodify(path, ":t")
|
|
local dest = dir .. name
|
|
vim.uv.fs_copyfile(path, dest, function(err)
|
|
vim.schedule(function()
|
|
if err then
|
|
vim.notify("Copy failed: " .. err, vim.log.levels.ERROR)
|
|
else
|
|
local bufname = vim.api.nvim_buf_get_name(0)
|
|
require("oil.view").set_last_cursor(bufname, name)
|
|
require("oil.actions").refresh.callback()
|
|
end
|
|
end)
|
|
end)
|
|
end, { desc = "Paste file from clipboard path into oil directory" })
|
|
<
|
|
|
|
*oil-recipe-file-templates*
|
|
|
|
Apply initial content to newly created files using the |OilFileCreated| event.
|
|
This is the recommended alternative to relying on |BufNewFile|, which does not
|
|
fire for files created through oil (the file already exists on disk by the
|
|
time it is opened). >lua
|
|
vim.api.nvim_create_autocmd("User", {
|
|
pattern = "OilFileCreated",
|
|
callback = function(args)
|
|
local path = args.data.path
|
|
local ext = vim.fn.fnamemodify(path, ":e")
|
|
local templates = {
|
|
sh = { "#!/usr/bin/env bash", "" },
|
|
py = { "#!/usr/bin/env python3", "" },
|
|
}
|
|
if templates[ext] then
|
|
vim.fn.writefile(templates[ext], path)
|
|
end
|
|
end,
|
|
})
|
|
<
|
|
|
|
For integration with vim-projectionist or any plugin that hooks |BufNewFile|,
|
|
use |OilFileCreated| to track oil-created files, then fire |BufNewFile| the
|
|
first time each file is opened. This is more precise than checking for empty
|
|
buffers on |BufRead|: >lua
|
|
local oil_created = {}
|
|
vim.api.nvim_create_autocmd("User", {
|
|
pattern = "OilFileCreated",
|
|
callback = function(args)
|
|
oil_created[args.data.path] = true
|
|
end,
|
|
})
|
|
vim.api.nvim_create_autocmd("BufRead", {
|
|
callback = function(args)
|
|
local path = vim.api.nvim_buf_get_name(args.buf)
|
|
if oil_created[path] then
|
|
oil_created[path] = nil
|
|
vim.api.nvim_exec_autocmds("BufNewFile", { buffer = args.buf })
|
|
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.
|
|
|
|
OilFileCreated *OilFileCreated*
|
|
Fired after a new file is successfully created on the local filesystem.
|
|
The `args.data.path` field contains the absolute path of the created file.
|
|
Use this event to populate initial file contents, run formatters, or
|
|
perform any other setup on newly created files. >lua
|
|
vim.api.nvim_create_autocmd("User", {
|
|
pattern = "OilFileCreated",
|
|
callback = function(args)
|
|
local path = args.data.path
|
|
if path:match("%.sh$") then
|
|
vim.fn.writefile({ "#!/usr/bin/env bash" }, path)
|
|
end
|
|
end,
|
|
})
|
|
<
|
|
|
|
--------------------------------------------------------------------------------
|
|
TRASH *oil-trash*
|
|
|
|
|
|
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.
|
|
|
|
================================================================================
|
|
vim:tw=80:ts=2:ft=help:norl:syntax=help:
|