"] = "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
-
-
-
-- [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)
-
-
-
## FAQ
-**Q: Why "oil"**?
+**Q: How do I migrate from `stevearc/oil.nvim` to `barrettruth/oil.nvim`?**
+
+Replace your `setup()` call with a `vim.g.oil` assignment. For example, with
+[lazy.nvim](https://github.com/folke/lazy.nvim):
+
+```lua
+-- before
+{
+ 'stevearc/oil.nvim',
+ config = function(_, opts)
+ require('oil').setup(opts)
+ end,
+ opts = {
+ ...
+ }
+}
+
+-- after
+{
+ 'barrettruth/oil.nvim',
+ init = function()
+ vim.g.oil = {
+ columns = { "icon", "size" },
+ delete_to_trash = true,
+ }
+ end,
+}
+```
+
+**Q: Why "oil"?**
**A:** From the [vim-vinegar](https://github.com/tpope/vim-vinegar) README, a quote by Drew Neil:
@@ -431,24 +128,18 @@ 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**?
+**Q: Can oil display files as a tree view?**
-**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.
+- [the original](https://github.com/stevearc/oil.nvim): the lesser-maintained but
+ official `oil.nvim`
+- [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.
diff --git a/doc/api.md b/doc/api.md
deleted file mode 100644
index 2ae4124..0000000
--- a/doc/api.md
+++ /dev/null
@@ -1,205 +0,0 @@
-# API
-
-
-
-- [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)
-
-
-
-
-
-## 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:**
-
-If you provide your own callback function, there will be no notification for errors.
-
-
-## setup(opts)
-
-`setup(opts)` \
-Initialize oil
-
-| Param | Type | Desc |
-| ----- | -------------------- | ---- |
-| opts | `oil.setupOpts\|nil` | |
-
-
-
diff --git a/doc/oil.txt b/doc/oil.txt
index 3bed69d..431eff1 100644
--- a/doc/oil.txt
+++ b/doc/oil.txt
@@ -3,17 +3,72 @@
--------------------------------------------------------------------------------
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 `, or `:Oil `. Use ``
+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 `.
+
+To mimic vim-vinegar's parent-directory keymap: >lua
+ vim.keymap.set("n", "-", "Oil", { 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*
+Oil can be configured in two ways:
+
+1. The traditional `setup()` call: >lua
+ require("oil").setup({
+ -- your opts here
+ })
+<
+
+2. Declarative configuration via `vim.g.oil`, which does not require calling
+ `setup()`: >lua
+ vim.g.oil = {
+ -- your opts here
+ }
+<
+
+ When `vim.g.oil` is set, oil initializes automatically during plugin
+ loading. If `setup()` is called with explicit opts, those take precedence
+ over `vim.g.oil`.
+
+The full list of options with their defaults:
+
>lua
require("oil").setup({
-- Oil will take over directory buffers (e.g. `vim .` or `:e src/`)
@@ -766,6 +821,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 = {
+ ["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,
+ },
+ ["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*
diff --git a/doc/recipes.md b/doc/recipes.md
deleted file mode 100644
index 4fe8e33..0000000
--- a/doc/recipes.md
+++ /dev/null
@@ -1,262 +0,0 @@
-# Recipes
-
-Have a cool recipe to share? Open a pull request and add it to this doc!
-
-
-
-- [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)
-
-
-
-## 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 = {
- ["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,
- },
- ["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
-```
diff --git a/flake.lock b/flake.lock
new file mode 100644
index 0000000..7501bfa
--- /dev/null
+++ b/flake.lock
@@ -0,0 +1,43 @@
+{
+ "nodes": {
+ "nixpkgs": {
+ "locked": {
+ "lastModified": 1771207753,
+ "narHash": "sha256-b9uG8yN50DRQ6A7JdZBfzq718ryYrlmGgqkRm9OOwCE=",
+ "owner": "NixOS",
+ "repo": "nixpkgs",
+ "rev": "d1c15b7d5806069da59e819999d70e1cec0760bf",
+ "type": "github"
+ },
+ "original": {
+ "owner": "NixOS",
+ "ref": "nixpkgs-unstable",
+ "repo": "nixpkgs",
+ "type": "github"
+ }
+ },
+ "root": {
+ "inputs": {
+ "nixpkgs": "nixpkgs",
+ "systems": "systems"
+ }
+ },
+ "systems": {
+ "locked": {
+ "lastModified": 1681028828,
+ "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+ "owner": "nix-systems",
+ "repo": "default",
+ "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+ "type": "github"
+ },
+ "original": {
+ "owner": "nix-systems",
+ "repo": "default",
+ "type": "github"
+ }
+ }
+ },
+ "root": "root",
+ "version": 7
+}
diff --git a/flake.nix b/flake.nix
new file mode 100644
index 0000000..5670f55
--- /dev/null
+++ b/flake.nix
@@ -0,0 +1,29 @@
+{
+ description = "oil.nvim — Neovim file explorer: edit your filesystem like a buffer";
+
+ inputs = {
+ nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
+ systems.url = "github:nix-systems/default";
+ };
+
+ outputs =
+ {
+ nixpkgs,
+ systems,
+ ...
+ }:
+ let
+ forEachSystem = f: nixpkgs.lib.genAttrs (import systems) (system: f nixpkgs.legacyPackages.${system});
+ in
+ {
+ devShells = forEachSystem (pkgs: {
+ default = pkgs.mkShell {
+ packages = [
+ pkgs.prettier
+ pkgs.stylua
+ pkgs.selene
+ ];
+ };
+ });
+ };
+}
diff --git a/lua/oil/config.lua b/lua/oil/config.lua
index 5c62b7e..3734bc0 100644
--- a/lua/oil/config.lua
+++ b/lua/oil/config.lua
@@ -406,7 +406,7 @@ local M = {}
---@field border? string|string[] Window border
M.setup = function(opts)
- opts = opts or {}
+ opts = opts or vim.g.oil or {}
local new_conf = vim.tbl_deep_extend("keep", opts, default_config)
if not new_conf.use_default_keymaps then
diff --git a/lua/oil/init.lua b/lua/oil/init.lua
index db454d8..0329afd 100644
--- a/lua/oil/init.lua
+++ b/lua/oil/init.lua
@@ -602,7 +602,7 @@ M.open_preview = function(opts, callback)
-- If we called open_preview during an autocmd, then the edit command may not trigger the
-- BufReadCmd to load the buffer. So we need to do it manually.
- if util.is_oil_bufnr(filebufnr) then
+ if util.is_oil_bufnr(filebufnr) and not vim.b[filebufnr].oil_ready then
M.load_oil_buffer(filebufnr)
end
@@ -1082,6 +1082,7 @@ M.load_oil_buffer = function(bufnr)
-- (e.g. ssh) because it will set up the filetype keybinds at the *beginning* of the loading
-- process.
vim.bo[bufnr].filetype = "oil"
+ vim.bo[bufnr].buftype = "acwrite"
keymap_util.set_keymaps(config.keymaps, bufnr)
end
loading.set_loading(bufnr, true)
@@ -1446,9 +1447,10 @@ M.setup = function(opts)
end,
})
- local bufnr = vim.api.nvim_get_current_buf()
- if maybe_hijack_directory_buffer(bufnr) and vim.v.vim_did_enter == 1 then
- M.load_oil_buffer(bufnr)
+ for _, bufnr in ipairs(vim.api.nvim_list_bufs()) do
+ if maybe_hijack_directory_buffer(bufnr) and vim.v.vim_did_enter == 1 then
+ M.load_oil_buffer(bufnr)
+ end
end
end
end
diff --git a/plugin/oil.lua b/plugin/oil.lua
new file mode 100644
index 0000000..2b1c352
--- /dev/null
+++ b/plugin/oil.lua
@@ -0,0 +1,3 @@
+if vim.g.oil ~= nil then
+ require("oil").setup()
+end
diff --git a/scripts/generate.py b/scripts/generate.py
deleted file mode 100755
index eb30f85..0000000
--- a/scripts/generate.py
+++ /dev/null
@@ -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"^$",
- r"^$",
- lines,
- )
- toc = ["\n"] + generate_md_toc(api_doc, max_level=1) + ["\n"]
- replace_section(
- api_doc,
- r"^$",
- r"^$",
- toc,
- )
- toc = add_md_link_path("doc/api.md", toc)
- replace_section(
- README,
- r"^$",
- r"^$",
- 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"^$",
- r"^$",
- 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", "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
- ["~"] = "edit $HOME",
- -- 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.
- ["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.
- [":"] = {
- "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.") 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()
diff --git a/scripts/main.py b/scripts/main.py
deleted file mode 100755
index 4dffddf..0000000
--- a/scripts/main.py
+++ /dev/null
@@ -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()
diff --git a/scripts/requirements.txt b/scripts/requirements.txt
deleted file mode 100644
index 2c6271f..0000000
--- a/scripts/requirements.txt
+++ /dev/null
@@ -1,4 +0,0 @@
-pyparsing==3.0.9
-black
-isort
-mypy
diff --git a/selene.toml b/selene.toml
new file mode 100644
index 0000000..96cf5ab
--- /dev/null
+++ b/selene.toml
@@ -0,0 +1 @@
+std = 'vim'
diff --git a/tests/config_spec.lua b/tests/config_spec.lua
new file mode 100644
index 0000000..aac4eb1
--- /dev/null
+++ b/tests/config_spec.lua
@@ -0,0 +1,27 @@
+local config = require("oil.config")
+
+describe("config", function()
+ after_each(function()
+ vim.g.oil = nil
+ end)
+
+ it("falls back to vim.g.oil when setup() is called with no args", function()
+ vim.g.oil = { delete_to_trash = true, cleanup_delay_ms = 5000 }
+ config.setup()
+ assert.is_true(config.delete_to_trash)
+ assert.equals(5000, config.cleanup_delay_ms)
+ end)
+
+ it("uses defaults when neither opts nor vim.g.oil is set", function()
+ vim.g.oil = nil
+ config.setup()
+ assert.is_false(config.delete_to_trash)
+ assert.equals(2000, config.cleanup_delay_ms)
+ end)
+
+ it("prefers explicit opts over vim.g.oil", function()
+ vim.g.oil = { delete_to_trash = true }
+ config.setup({ delete_to_trash = false })
+ assert.is_false(config.delete_to_trash)
+ end)
+end)