Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/luukvbaal/nnn.nvim
File manager for Neovim powered by nnn.
https://github.com/luukvbaal/nnn.nvim
file-manager lua neovim neovim-lua neovim-plugin nnn nvim plugin terminal
Last synced: 9 days ago
JSON representation
File manager for Neovim powered by nnn.
- Host: GitHub
- URL: https://github.com/luukvbaal/nnn.nvim
- Owner: luukvbaal
- License: bsd-3-clause
- Created: 2021-09-30T02:23:49.000Z (about 3 years ago)
- Default Branch: master
- Last Pushed: 2024-05-18T00:27:45.000Z (6 months ago)
- Last Synced: 2024-10-30T14:58:59.420Z (9 days ago)
- Topics: file-manager, lua, neovim, neovim-lua, neovim-plugin, nnn, nvim, plugin, terminal
- Language: Lua
- Homepage:
- Size: 138 KB
- Stars: 427
- Watchers: 3
- Forks: 9
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- awesome-neovim - luukvbaal/nnn.nvim - File explorer powered by [nnn](https://github.com/jarun/nnn) and Lua. (File Explorer / PHP)
README
# nnn.nvim
File manager for Neovim powered by [nnn](https://github.com/jarun/nnn).
## Install
Requires nnn to be installed, follow the [instructions](https://github.com/jarun/nnn/wiki/Usage#installation).
**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](https://github.com/jarun/nnn/releases/tag/v4.3), [OBS packages](https://software.opensuse.org//download.html?project=home%3Astig124%3Annn&package=nnn) or [build from source](https://github.com/jarun/nnn/wiki/Usage#from-source).
Then install the plugin using your plugin manager:
Install with [vim-plug](https://github.com/junegunn/vim-plug):
```vim
Plug 'luukvbaal/nnn.nvim'
call plug#end()
lua << EOF
require("nnn").setup()
EOF
```
Install with [packer](https://github.com/wbthomason/packer.nvim):
```lua
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](https://github.com/jarun/nnn/wiki/concepts#selection) 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=` 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.
```vim
tnoremap NnnExplorer
nnoremap NnnExplorer %:p:h
tnoremap NnnPicker
nnoremap NnnPicker
```
## Configuration
### Default options
```lua
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 = "h",
right = "l",
next = "w",
prev = "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.:
```lua
require("nnn").setup({
picker = {
cmd = "tmux new-session nnn -Pp",
style = { border = "rounded" },
session = "shared",
},
replace_netrw = "picker",
windownav = ""
})
```
### 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:
```lua
local builtin = require("nnn").builtin
mappings = {
{ "", builtin.open_in_tab }, -- open file(s) in tab
{ "", builtin.open_in_split }, -- open file(s) in split
{ "", builtin.open_in_vsplit }, -- open file(s) in vertical split
{ "", builtin.open_in_preview }, -- open file in preview split keeping nnn focused
{ "", builtin.copy_to_clipboard }, -- copy file(s) to clipboard
{ "", builtin.cd_to_path }, -- cd to file directory
{ "", 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](https://github.com/jarun/nnn/tree/master/patches#list-of-patches) and install nnn with the [gitstatus](https://github.com/jarun/nnn/blob/master/patches/gitstatus/mainline.diff) 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` will open `tmux` inside the picker window and can be used to open [`preview-tui`](https://github.com/jarun/nnn/blob/master/plugins/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.