oil.nvim — Edit Your Filesystem Like a Neovim Buffer

Introduction

oil.nvim by stevearc is a file explorer for Neovim that treats directories as editable buffers. With over 6,700 stars on GitHub, it offers a fundamentally different approach to file management: instead of a tree sidebar with custom keybindings, you manipulate your filesystem using the same text editing operations you already know.

What oil.nvim Does

When you open a directory, oil.nvim renders its contents as lines in a normal buffer. Each line represents a file or subdirectory. Rename by editing text, delete by removing lines, move by cutting and pasting into another oil buffer. On save, oil.nvim diffs the buffer against the original listing and executes the corresponding filesystem operations.

Architecture Overview

oil.nvim is written in Lua using a virtual buffer model. Each buffer maintains a mapping between displayed lines and filesystem entries. On save, it compares buffer state against its cached snapshot to determine operations (rename, delete, create, move). It uses Neovim's vim.loop (libuv) for async filesystem operations and supports adapters for different backends.

Self-Hosting & Configuration

oil.nvim runs locally with no external dependencies beyond Neovim. Configuration options in setup() include: default_file_explorer (replace netrw), columns (display icon, size, permissions, mtime), view_options.show_hidden (toggle dotfiles), float (open in floating window), keymaps (custom buffer-local mappings), and skip_confirm_for_simple_edits (skip confirmation for renames). SSH remote editing is supported via the ssh adapter.

Key Features

• Edit directory contents using standard Neovim text operations
• Batch rename, move, copy, and delete files in a single save
• Preview files without leaving the oil buffer
• Floating window mode for quick file operations
• Configurable columns: icons, file size, permissions, modification time
• SSH adapter for editing remote directories
• Undo support for filesystem changes before saving

Comparison with Similar Tools

nvim-tree.lua and neo-tree.nvim use a sidebar tree with custom keybindings for each operation. oil.nvim reuses Neovim's editing model instead. dirvish.vim pioneered buffer-based directories but lacks batch operations. Compared to telescope-file-browser, oil.nvim focuses on manipulation rather than fuzzy finding.

FAQ

Will saving accidentally delete my files? oil.nvim shows a confirmation prompt listing all pending changes before executing destructive operations. You can review and cancel.

Can I undo filesystem changes? Before saving, all changes are just buffer edits and fully undoable with u. After saving, the filesystem operations are final, though a trash feature can be configured.

Does it replace netrw? Yes. Setting default_file_explorer = true in setup makes oil.nvim handle all directory buffers that netrw would normally open.

Sources

• GitHub repository: https://github.com/stevearc/oil.nvim
• Neovim documentation: :help oil
• stevearc's plugins: https://github.com/stevearc