Vim Motions

Oil explorer

Oil explorer (inspired by oil.nvim) provides a keyboard-first way to manage your vault’s file structure. Instead of using a sidebar or modal, Oil renders a directory’s contents as an editable Markdown buffer. You can create, rename, delete, and move files using standard Vim operators like o, cw, dd, and p, then commit all changes at once with :w.

Oil is not intended to replace the Obsidian file explorer, but rather to provide a fast, keyboard-driven alternative for bulk file operations and rapid navigation.

Opening

  • :Oil opens the directory containing the current file.
  • :Oil path/to/dir opens a specific directory.
  • :Oil . opens the vault root.

Keybindings

Oil explorer

Oil keybindings are only active when an oil buffer is focused. All keybindings are user-remappable via Lua or vimrc — see oil-explorer > Remapping keybindings for details.

KeybindingEx commandDescription
<CR>:oilopenOpen file under cursor / navigate into directory
-:oilparentNavigate to parent directory
~:oilrootNavigate to vault root
q:oilcloseClose oil buffer
<C-l>:oilrefreshRefresh directory listing
g.:oiltogglehiddenToggle hidden files (dotfiles)
gs:oilcyclesortCycle sort order (name → modified time → size)
y.:oilyankpathYank vault-relative file path to clipboard
gf:oilrevealReveal file under cursor in Obsidian file explorer
ddStage file deletion (commit with :w)
oStage file creation — type filename, commit with :w
cwStage file rename — edit filename, commit with :w
:wCommit all staged changes (create/rename/delete)
:OilOpen oil explorer for current file’s directory
Link to original

File operations

All changes in an Oil buffer are staged and only applied to the filesystem when you save the buffer with :w.

  • Create: Type a new line with the desired filename. Pressing :w creates the file. Filenames without an extension default to .md. Names ending with a / create folders.
  • Rename: Edit the filename text on an existing line. Pressing :w renames the file. Obsidian backlinks are updated automatically.
  • Delete: Delete a line using dd or any other Vim command. Pressing :w moves the file to the trash (respecting your Obsidian trash settings). A confirmation dialog is shown if the number of deleted files exceeds the configured threshold.
  • <CR> opens the file under the cursor or enters the directory.
  • - navigates to the parent directory.
  • ~ navigates to the vault root.
  • q closes the Oil buffer.

Remapping keybindings

All oil keybindings can be remapped via Lua or vimrc. Each keybinding maps to an ex command that you can target from your own bindings.

Oil ex commands

Ex commandShortDefault keyDescription
:oilopen:oilo<CR>Open file / enter directory
:oilparent:oilp-Navigate to parent directory
:oilroot:oilro~Navigate to vault root
:oilrefresh:oilref<C-l>Refresh directory listing
:oilclose:oilclqClose oil buffer
:oiltogglehidden:oiltg.Toggle hidden files
:oilcyclesort:oilcygsCycle sort order
:oilyankpath:oilyy.Yank file path to clipboard
:oilreveal:oilrevgfReveal in Obsidian file explorer
:oilhelp:oilhg?Show keybinding help modal

Use the OilEnter autocmd to set buffer-local keymaps that only apply in oil buffers:

vim.api.nvim_create_autocmd('OilEnter', {
    callback = function()
        vim.keymap.set('n', '<C-h>', function()
            vim.obsidian.oil.parent()
        end, { buffer = 0 })
        vim.keymap.set('n', 'l', function()
            vim.obsidian.oil.open_entry()
        end, { buffer = 0 })
    end
})

Remap via vimrc

nmap <C-h> :oilparent<CR>
nmap l :oilopen<CR>

Vimrc oil mappings are global

Vimrc nmap cannot scope to oil buffers only. Mappings apply everywhere. Use Lua with { buffer = 0 } for oil-only bindings.

Lua functions

All oil actions are available as Lua functions under vim.obsidian.oil:

vim.obsidian.oil.open(path)       -- open oil for a directory
vim.obsidian.oil.close()          -- close oil buffer
vim.obsidian.oil.parent()         -- navigate to parent directory
vim.obsidian.oil.root()           -- navigate to vault root
vim.obsidian.oil.refresh()        -- refresh current listing
vim.obsidian.oil.toggle_hidden()  -- toggle dotfile visibility
vim.obsidian.oil.cycle_sort()     -- cycle sort order
vim.obsidian.oil.yank_path()      -- copy path to clipboard
vim.obsidian.oil.reveal()         -- reveal in Obsidian file explorer
vim.obsidian.oil.open_entry()     -- open file/directory under cursor

Configuration

You can customize Oil explorer behavior in Settings → Vim Motions → File explorer:

  • Oil explorer: Toggle the feature on or off.
  • Show hidden files: Toggle visibility of dotfiles and hidden folders.
  • Confirm delete threshold: Set the number of files that triggers a confirmation dialog on deletion.
  • Default sort order: Choose between name, modified time, or size.

See settings > File explorer for details.

How it works

When you open Oil, the plugin creates a dedicated Oil explorer view with an embedded Markdown editor. The directory listing is rendered as editable text directly in the view — no temporary files are created in the vault.

Because Oil uses a full CodeMirror 6 editor, all existing Vim features like EasyMotion, surround, and text objects work natively within the Oil view. The view state (current directory) persists across workspace restarts.

Warning

Cross-directory moves: Moving a file from one directory to another (e.g., dd in one Oil buffer and p in another) is supported but requires both directories to be open in separate Oil buffers simultaneously. See known-limitations > Oil explorer for details.

Graph View

Backlinks