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.
• :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. Oil ex commands (:oilopen, :oilparent, etc.) are always registered — invoking them outside an Oil buffer shows a notice instead of an error.

Keybinding	Ex command	Description
<CR>	:oilopen	Open file under cursor / navigate into directory
<C-t>	:oilopentab	Open file under cursor in new tab
<C-s>	:oilopensv	Open file under cursor in vertical split
<C-h>	:oilopensh	Open file under cursor in horizontal split
-	:oilparent	Navigate to parent directory
~	:oilroot	Navigate to vault root
q	:oilclose	Close oil buffer
<C-c>	:oilclose	Close oil buffer
<C-l>	:oilrefresh	Refresh directory listing
g.	:oiltogglehidden	Toggle hidden files (dotfiles)
gs	:oilcyclesort	Cycle sort order (name → modified time → size)
y.	:oilyankpath	Yank vault-relative file path to clipboard
gf	:oilreveal	Reveal file under cursor in Obsidian file explorer
gx	:oilopenexternal	Open file under cursor in default system app
g?	:oilhelp	Show keybinding help modal
<C-p>	:oilpreview	Toggle preview split (shows file under cursor, auto-updates on cursor move)
dd		Stage file deletion (commit with :w)
o		Stage file creation — type filename, commit with :w
cw		Stage file rename — edit filename, commit with :w
:w		Commit all staged changes (create/rename/delete)
:Oil		Open oil explorer (no arg: current dir, .//: vault root, path: specific dir)

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. Nested paths like newfolder/notes.md create both the directory and the file in one step.
• 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.

Navigation

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

Oil ex commands are always registered, even outside an Oil buffer. If you invoke an Oil ex command from a regular editor, it shows a notice: Oil: :<command> only works inside an Oil buffer. Use :Oil to open the file explorer.

Ex command	Short	Default key	Description
:oilopen	:oilo	<CR>	Open file / enter directory
:oilopentab	:oilopent	<C-t>	Open file in new tab
:oilopensv	:oilopensv	<C-s>	Open file in vertical split
:oilopensh	:oilopensh	<C-h>	Open file in horizontal split
:oilparent	:oilp	-	Navigate to parent directory
:oilroot	:oilro	~	Navigate to vault root
:oilrefresh	:oilref	<C-l>	Refresh directory listing
:oilclose	:oilcl	q, <C-c>	Close oil buffer
:oiltogglehidden	:oilt	g.	Toggle hidden files
:oilcyclesort	:oilcy	gs	Cycle sort order
:oilyankpath	:oily	y.	Yank path to register/clipboard
:oilreveal	:oilrev	gf	Reveal in Obsidian file explorer
:oilopenexternal	:oilopene	gx	Open in default app
:oilhelp	:oilh	g?	Show keybinding help modal
:oilpreview	:oilpre	<C-p>	Toggle preview split

Remap via Lua (recommended)

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()      -- yank path to unnamed register and 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.

Behavior

Mode restoration

When you close Oil (via q, :q, :wq, or vim.ob.oil.close()), the editor reopens your previous file in the same mode you were in when you opened Oil — source mode, live preview, or reading mode.

Obsidian hotkey handling

Oil’s Ctrl-key keybindings (<C-t>, <C-s>, <C-h>, <C-l>, <C-c>) are registered on the editor’s Obsidian Scope, which fires before Obsidian’s default hotkeys. This means <C-t> correctly opens in a new tab instead of triggering Obsidian’s “New tab” hotkey, <C-s> opens a vertical split instead of saving, and <C-h> opens a horizontal split instead of opening search & replace. No manual hotkey unbinding is required for Oil keybindings to work.

Neovim RPC backend

Oil’s embedded editor remains owned by the bundled Vim engine while the Neovim RPC backend is connected. RPC key delegation attaches only to Markdown editors; when Oil is active, no RPC keydown listener is attached and fork interception is disabled. Oil mappings therefore execute once in the embedded editor and never modify Neovim’s mirrored Markdown buffer.

Focus on tab switch

If you switch away from the Oil tab and then switch back (via gT, gt, or clicking the tab), the Oil editor automatically regains focus. You can start typing vim commands immediately without needing to click.

Focus after commit

When committing changes with :w, the Oil editor retains focus after the operation completes — whether the commit succeeds, the confirmation dialog is cancelled, or the dialog is dismissed with Esc. You can continue editing or navigating immediately without needing to re-focus the editor.

Opening from non-editor contexts

Oil works correctly when opened from any context — including empty panes, settings, graph view, or the command palette with no file open. The plugin automatically primes the workspace leaf with editor infrastructure before creating the Oil view, ensuring vim keybindings, conceal decorations, and which-key all function as expected.

Preview

Press <C-p> to open a preview split alongside the Oil buffer. The preview shows a read-only rendering of the file under the cursor and auto-updates as you move through the directory listing. Press <C-p> again to close the preview. The preview also closes automatically when you close Oil.

Visual mode multi-select

Select multiple entries with V (visual line mode) and press <CR> to open all selected files. The first file replaces the Oil view in the current leaf, and additional files open in new tabs. Folders in the selection are skipped (use <CR> on a single folder entry to navigate into it).

Hidden toggle guard

The g. toggle (:oiltogglehidden) is blocked when the Oil buffer has unsaved changes. A notice is shown instead of toggling. Save your changes with :w first, then toggle hidden files. This prevents accidental data loss from re-rendering the buffer while edits are pending.

Hidden files (dotfiles)

When Show hidden files is enabled in Settings → Vim Motions → File explorer, Oil shows dotfiles and hidden folders (.gitignore, .git/, etc.) that Obsidian normally hides. These are discovered via the Obsidian adapter API, which accesses the filesystem directly.

View-only limitation

Hidden files appear in the listing and can be opened, but renaming, deleting, or moving them via Oil buffer editing may fail because Obsidian’s Vault API does not index dotfiles. Full CRUD operations on hidden files are not yet supported.

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 and previous file’s editor mode) 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.