barrett/canola.nvim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 4
canola.nvim/doc/oil.txt
Steven Arcangeli 6175bd6462
feat: trash support for linux and mac (#165) 
* wip: skeleton code for trash adapter

* refactor: split trash implementation for mac and linux

* fix: ensure we create the .Trash/$uid dir

* feat: code complete linux trash implementation

* doc: write up trash features

* feat: code complete mac trash implementation

* cleanup: remove previous, terrible, undocumented trash feature

* fix: always disabled trash

* feat: show original path of trashed files

* doc: add a note about calling actions directly

* fix: bugs in trash implementation

* fix: schedule_wrap in mac trash

* doc: fix typo and line wrapping

* fix: parsing of arguments to :Oil command

* doc: small documentation tweaks

* doc: fix awkward wording in the toggle_trash action

* fix: warning on Windows when delete_to_trash = true

* feat: :Oil --trash can open specific trash directories

* fix: show all trash files in device root

* fix: trash mtime should be sortable

* fix: shorten_path handles optional trailing slash

* refactor: overhaul the UI

* fix: keep trash original path vtext from stacking

* refactor: replace disable_changes with an error filter

* fix: shorten path names in home directory relative to root

* doc: small README format changes

* cleanup: remove unnecessary preserve_undo logic

* test: add a functional test for the freedesktop trash adapter

* test: more functional tests for trash

* fix: schedule a callback to avoid main loop error

* refactor: clean up mutator logic

* doc: some comments and type annotations
2023-11-05 12:40:58 -08:00

493 lines
20 KiB
Text
Raw Blame History

*oil.txt*
*Oil* *oil* *oil.nvim*
--------------------------------------------------------------------------------
CONTENTS *oil-contents*
1. Options |oil-options|
2. Api |oil-api|
3. Columns |oil-columns|
4. Actions |oil-actions|
5. Highlights |oil-highlights|
6. Trash |oil-trash|
--------------------------------------------------------------------------------
OPTIONS *oil-options*
>lua
require("oil").setup({
-- Oil will take over directory buffers (e.g. `vim .` or `:e src/`)
-- Set to false if you still want to use netrw.
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
skip_confirm_for_simple_edits = false,
-- Selecting a new/moved/renamed file or directory will prompt you to save changes first
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,
-- 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",
["<CR>"] = "actions.select",
["<C-s>"] = "actions.select_vsplit",
["<C-h>"] = "actions.select_split",
["<C-t>"] = "actions.select_tab",
["<C-p>"] = "actions.preview",
["<C-c>"] = "actions.close",
["<C-l>"] = "actions.refresh",
["-"] = "actions.parent",
["_"] = "actions.open_cwd",
["`"] = "actions.cd",
["~"] = "actions.tcd",
["gs"] = "actions.change_sort",
["gx"] = "actions.open_external",
["g."] = "actions.toggle_hidden",
["g\\"] = "actions.toggle_trash",
},
-- 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)
return vim.startswith(name, ".")
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 = {
-- sort order can be "asc" or "desc"
-- see :help oil-columns to see which columns are sortable
{ "type", "asc" },
{ "name", "asc" },
},
},
-- Configuration for the floating window in oil.open_float
float = {
-- Padding around the floating window
padding = 2,
max_width = 0,
max_height = 0,
border = "rounded",
win_options = {
winblend = 0,
},
-- 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 actions floating preview window
preview = {
-- 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 = "rounded",
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 = "rounded",
minimized_border = "none",
win_options = {
winblend = 0,
},
},
})
<
--------------------------------------------------------------------------------
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} `string[]` []
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: nil|integer): boolean` Retu
rn true if the file/dir should be hidden
toggle_hidden() *oil.toggle_hidden*
Toggle hidden files and directories
get_current_dir(): nil|string *oil.get_current_dir*
Get the current directory
open_float({dir}) *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
toggle_float({dir}) *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
open({dir}) *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
close() *oil.close*
Restore the buffer that was present when oil was opened
select({opts}, {callback}) *oil.select*
Select the entry under the cursor
Parameters:
{opts} `nil|table`
{vertical} `boolean` Open the buffer in a vertical split
{horizontal} `boolean` Open the buffer in a horizontal split
{split} `"aboveleft"|"belowright"|"topleft"|"botright"` Split
modifier
{preview} `boolean` Open the buffer in a preview window
{tab} `boolean` Open the buffer in a new tab
{close} `boolean` Close the original oil buffer once selection is
made
{callback} `nil|fun(err: nil|string)` Called once all entries have been
opened
save({opts}) *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
setup({opts}) *oil.setup*
Initialize oil
Parameters:
{opts} `nil|table`
--------------------------------------------------------------------------------
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
{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
{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
size *column-size*
Adapters: files, ssh
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
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
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
{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
{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
{format} `string` Format string (see :help strftime)
birthtime *column-birthtime*
Adapters: files
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
{format} `string` Format string (see :help strftime)
--------------------------------------------------------------------------------
ACTIONS *oil-actions*
These are actions that can be used in the `keymaps` section of config options.
You can also call them directly with
`require("oil.actions").action_name.callback()`
cd *actions.cd*
:cd to the current oil directory
change_sort *actions.change_sort*
Change the sort order
close *actions.close*
Close oil and restore original buffer
copy_entry_path *actions.copy_entry_path*
Yank the filepath of the entry under the cursor to a register
open_cmdline *actions.open_cmdline*
Open vim cmdline with current entry as an argument
open_cmdline_dir *actions.open_cmdline_dir*
Open vim cmdline with current directory as an argument
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
preview *actions.preview*
Open the entry under the cursor in a preview window, or close the preview
window if already open
preview_scroll_down *actions.preview_scroll_down*
Scroll down in the preview window
preview_scroll_up *actions.preview_scroll_up*
Scroll up in the preview window
refresh *actions.refresh*
Refresh current directory list
select *actions.select*
Open the entry under the cursor
select_split *actions.select_split*
Open the entry under the cursor in a horizontal split
select_tab *actions.select_tab*
Open the entry under the cursor in a new tab
select_vsplit *actions.select_vsplit*
Open the entry under the cursor in a vertical split
show_help *actions.show_help*
Show default keymaps
tcd *actions.tcd*
:tcd to the current oil directory
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
--------------------------------------------------------------------------------
HIGHLIGHTS *oil-highlights*
OilDir *hl-OilDir*
Directory names in an oil buffer
OilDirIcon *hl-OilDirIcon*
Icon for directories
OilSocket *hl-OilSocket*
Socket files in an oil buffer
OilLink *hl-OilLink*
Soft links in an oil buffer
OilLinkTarget *hl-OilLinkTarget*
The target of a soft link
OilFile *hl-OilFile*
Normal files in an oil buffer
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
--------------------------------------------------------------------------------
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 delete them from the trash and put them in 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-spec/trashspec-1.0.html
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 does not yet support the Windows trash. PRs are welcome!
================================================================================
vim:tw=80:ts=2:ft=help:norl:syntax=help:
Reference in a new issue View git blame Copy permalink