*oil.txt*
*Oil* *oil* *oil.nvim*
--------------------------------------------------------------------------------
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|

--------------------------------------------------------------------------------
CONFIG                                                                *oil-config*

>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 = {
        -- 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",
        ["<CR>"] = "actions.select",
        ["<C-s>"] = { "actions.select", opts = { vertical = true }, desc = "Open the entry in a vertical split" },
        ["<C-h>"] = { "actions.select", opts = { horizontal = true }, desc = "Open the entry in a horizontal split" },
        ["<C-t>"] = { "actions.select", opts = { tab = true }, desc = "Open the entry in new tab" },
        ["<C-p>"] = "actions.preview",
        ["<C-c>"] = "actions.close",
        ["<C-l>"] = "actions.refresh",
        ["-"] = "actions.parent",
        ["_"] = "actions.open_cwd",
        ["`"] = "actions.cd",
        ["~"] = { "actions.cd", opts = { scope = "tab" }, desc = ":tcd to the current oil directory" },
        ["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 file names in a more intuitive order for humans. Is less performant,
        -- so you may want to set to false if you work with large directories.
        natural_order = true,
        -- 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" },
        },
      },
      -- Extra arguments to pass to SCP when moving/copying files over SSH
      extra_scp_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 = 0,
        max_height = 0,
        border = "rounded",
        win_options = {
          winblend = 0,
        },
        -- 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 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,
        },
        -- Whether the preview window is automatically updated when the cursor is moved
        update_on_cursor_moved = true,
      },
      -- 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,
        },
      },
      -- Configuration for the floating SSH window
      ssh = {
        border = "rounded",
      },
      -- Configuration for the floating keymaps help window
      keymaps_help = {
        border = "rounded",
      },
    })
<

--------------------------------------------------------------------------------
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

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.

--------------------------------------------------------------------------------
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: 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({bufnr}): nil|string                         *oil.get_current_dir*
    Get the current directory

    Parameters:
      {bufnr} `nil|integer`

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


open_preview({opts})                                            *oil.open_preview*
    Preview the entry under the cursor in a split

    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

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
      {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
      {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*

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

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

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

    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|)
      {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*

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: