oil.txt

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

--------------------------------------------------------------------------------
OPTIONS                                                              *oil-options*

>
    require("oil").setup({
      -- 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 = "n",
      },
      -- Oil will take over directory buffers (e.g. `vim .` or `:e src/`
      default_file_explorer = true,
      -- Restore window options to previous values when leaving an oil buffer
      restore_win_options = true,
      -- Skip the confirmation popup for simple operations
      skip_confirm_for_simple_edits = false,
      -- Deleted files will be removed with the trash_command (below).
      delete_to_trash = false,
      -- Change this to customize the command used when deleting to trash
      trash_command = "trash-put",
      -- Selecting a new/moved/renamed file or directory will prompt you to save changes first
      prompt_save_on_select_new_entry = true,
      -- 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 = "", nowait = true })
      -- 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",
        ["g."] = "actions.toggle_hidden",
      },
      -- 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,
      },
      -- 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 = 10,
        },
        -- 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_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: *
    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

size                                                                 *column-size*
    Adapters: files, ssh
    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
    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
    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
    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
    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.

cd                                                                    *actions.cd*
    :cd to the current oil directory

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

--------------------------------------------------------------------------------
HIGHLIGHTS                                                        *oil-highlights*

OilDir                                                                 *hl-OilDir*
    Directories in an oil buffer

OilSocket                                                           *hl-OilSocket*
    Socket files in an oil buffer

OilLink                                                               *hl-OilLink*
    Soft links in an oil buffer

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

================================================================================
vim:tw=80:ts=2:ft=help:norl:syntax=help: