luukvbaal/nnn.nvim

github github
file-explorer
star 236
stars
alert-circle 0
open issues
users 3
subscribers
git-branch 3
forks
CREATED

2021-09-30

UPDATED

13 days ago


nnn.nvim

File manager for Neovim powered by nnn.

img

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 simliar 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:

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 overrride (-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,       -- seperate nnn instance per tab
    },
    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"
    },
    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 = "tcd",      -- or "cd" / "lcd", command to run if quitcd file is 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.

img

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:

img

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.