nnn.nvim

File manager for Neovim powered by nnn.

Install

Requires nnn to be installed, follow the instructions.

NOTE: Explorer mode requires nnn version v4.3. If your distribution doesn't provide version v4.3 from its repositories, install one of the provided static binaries, OBS packages or build from source.

Then install the plugin using your plugin manager:

Install with vim-plug:

Plug 'luukvbaal/nnn.nvim'
call plug#end()

lua << EOF
require("nnn").setup()
EOF

Install with packer:

use {
  "luukvbaal/nnn.nvim",
  config = function() require("nnn").setup() end
}

Usage

The plugin offers two possible modes of operation.

Explorer Mode

Run command :NnnExplorer to open nnn in a vertical split similar to NERDTree/nvim-tree.

In this mode, the plugin makes use of nnn's -F flag to listen for opened files. Pressing Enter on a file will open that file in a new buffer, while keeping the nnn window open.

Picker Mode

Run command :NnnPicker to open nnn in a floating window.

In this mode nnn's -p flag is used to listen for opened files on program exit. Picker mode implies only a single selection will be made before quitting nnn and thus the floating window.

Selection

In both modes it's possible to select multiple files before pressing Enter. Doing so will open the entire selection all at once, excluding the hovered file.

Bindings

Bind NnnExplorer/NnnPicker to toggle the plugin on/off in normal and terminal mode. The commands accept a path as optional argument. To always open nnn in the directory of the currently active buffer, use %:p:h as argument:

Custom Command Argument

Additionally, passing cmd=<custom command> as argument will override the configured nnn command. This allows you to for example run one-off nnn commands with different option flags. :NnnExplorer cmd=nnn\ -Pf /mnt will open explorer mode in /mnt and run the nnn plugin mapped to f. Spaces in the cmd string must be escaped.

tnoremap <C-A-n> <cmd>NnnExplorer<CR>
nnoremap <C-A-n> <cmd>NnnExplorer %:p:h<CR>
tnoremap <C-A-p> <cmd>NnnPicker<CR>
nnoremap <C-A-p> <cmd>NnnPicker<CR>

Configuration

Default options

local cfg = {
  explorer = {
    cmd = "nnn",       -- command override (-F1 flag is implied, -a flag is invalid!)
    width = 24,        -- width of the vertical split
    side = "topleft",  -- or "botright", location of the explorer window
    session = "",      -- or "global" / "local" / "shared"
    tabs = true,       -- separate nnn instance per tab
    fullscreen = true, -- whether to fullscreen explorer window when current tab is empty
  },
  picker = {
    cmd = "nnn",       -- command override (-p flag is implied)
    style = {
      width = 0.9,     -- percentage relative to terminal size when < 1, absolute otherwise
      height = 0.8,    -- ^
      xoffset = 0.5,   -- ^
      yoffset = 0.5,   -- ^
      border = "single"-- border decoration for example "rounded"(:h nvim_open_win)
    },
    session = "",      -- or "global" / "local" / "shared"
    tabs = true,       -- separate nnn instance per tab
    fullscreen = true, -- whether to fullscreen picker window when current tab is empty
  },
  auto_open = {
    setup = nil,       -- or "explorer" / "picker", auto open on setup function
    tabpage = nil,     -- or "explorer" / "picker", auto open when opening new tabpage
    empty = false,     -- only auto open on empty buffer
    ft_ignore = {      -- dont auto open for these filetypes
      "gitcommit",
    }
  },
  auto_close = false,  -- close tabpage/nvim when nnn is last window
  replace_netrw = nil, -- or "explorer" / "picker"
  mappings = {},       -- table containing mappings, see below
  windownav = {        -- window movement mappings to navigate out of nnn
    left = "<C-w>h",
    right = "<C-w>l",
    next = "<C-w>w",
    prev = "<C-w>W",
  },
  buflisted = false,   -- whether or not nnn buffers show up in the bufferlist
  quitcd = nil,        -- or "cd" / tcd" / "lcd", command to run on quitcd file if found
  offset = false,      -- whether or not to write position offset to tmpfile(for use in preview-tui)
}

Edit (part of) this table to your preferences and pass it to the setup() function i.e.:

require("nnn").setup({
  picker = {
    cmd = "tmux new-session nnn -Pp",
    style = { border = "rounded" },
    session = "shared",
  },
  replace_netrw = "picker",
  windownav = "<C-l>"
})

Mappings

It's possible to map custom lua functions to keys which are passed the selected file or active nnn selection. A set of builtin functions is provided which can be used as follows:

  local builtin = require("nnn").builtin
  mappings = {
    { "<C-t>", builtin.open_in_tab },       -- open file(s) in tab
    { "<C-s>", builtin.open_in_split },     -- open file(s) in split
    { "<C-v>", builtin.open_in_vsplit },    -- open file(s) in vertical split
    { "<C-p>", builtin.open_in_preview },   -- open file in preview split keeping nnn focused
    { "<C-y>", builtin.copy_to_clipboard }, -- copy file(s) to clipboard
    { "<C-w>", builtin.cd_to_path },        -- cd to file directory
    { "<C-e>", builtin.populate_cmdline },  -- populate cmdline (:) with file(s)
  }

To create your own function mapping follow the function signature of the builtin functions which are passed a table of file names.

Note that in both picker and explorer mode, the mapping will execute on the nnn selection if it exists.

Session

You can enable persistent sessions in nnn(-S flag) by setting picker and explorer mode session to one of ""(disabled), "global" or "local".

Alternatively you can set the session "shared" to share the same session between both explorer and picker mode (setting either one to "shared" will make the session shared).

Colors

Three highlight groups NnnNormal, NnnNormalNC and NnnBorder are available to configure the colors for the active, inactive and picker window borders respectively.

Tips and tricks

Git status

Build and install nnn with the gitstatus enable git status symbols in detail mode. Add the -G flag to your command override to also enable symbols in normal mode.

preview-tui

Setting the command override for picker mode to for example tmux new-session nnn -P<plugin-key> will open tmux inside the picker window and can be used to open preview-tui inside the floating window:

Include option offset = true in your config to write the offset of the NnnPicker window to a temporary file. This will allow preview-tui to correctly draw ueberzug image previews, accounting for said offset.