*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}, {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} `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: