nnn/plugins
lvgx b1027150ed
Add -a option to generate a temporary NNN_FIFO (#588)
* Add -a option to generate a temporary NNN_FIFO

* Add documentation for -a option

* plugins/README.md: promote the use of -a

This obsoletes the global FIFO unlink trick, so I remove mentions of it.
@jarun update:

Polish -a
2020-05-23 17:40:51 +05:30
..
.cbcp Change requires to dependencies 2020-05-06 10:59:57 +05:30
.nmv NNN_SEL: custom selection file 2020-04-24 18:12:18 +05:30
.nnn-plugin-helper Drop fzy support 2020-05-06 18:41:01 +05:30
.ntfy Change requires to dependencies 2020-05-06 10:59:57 +05:30
autojump Change requires to dependencies 2020-05-06 10:59:57 +05:30
bookmarks Add a bookmarks plugin that supports names (#558) 2020-05-06 17:24:21 +05:30
boom Randomize mocp 2020-04-27 08:35:43 +05:30
chksum Uniform plugins 2020-05-06 10:42:50 +05:30
diffs NNN_SEL: custom selection file 2020-04-24 18:12:18 +05:30
dragdrop Change requires to dependencies 2020-05-06 10:59:57 +05:30
dups Change requires to dependencies 2020-05-06 10:59:57 +05:30
finder Update docs 2020-05-04 20:17:40 +05:30
fzcd Drop fzy support 2020-05-06 18:41:01 +05:30
fzhist Drop fzy support 2020-05-06 18:41:01 +05:30
fzopen Drop fzy support 2020-05-06 18:41:01 +05:30
fzz Drop fzy support 2020-05-06 18:41:01 +05:30
getplugs getplugs: add "master" version support (#560) 2020-05-06 22:36:19 +05:30
gutenread Update plugins to support some env vars 2020-03-16 07:13:35 +05:30
hexview Change requires to dependencies 2020-05-06 10:59:57 +05:30
imgresize Update plugins to support some env vars 2020-03-16 07:13:35 +05:30
imgthumb Rename plugins, group related ones 2019-11-22 17:51:13 +05:30
imgur Some of the shell script fixes as per discussion (#389) 2019-11-26 18:06:31 +05:30
imgview sxiv: load dir along with file 2020-03-03 06:16:52 +05:30
ipinfo shellcheck fixes 2019-11-22 11:13:34 +05:30
kdeconnect NNN_SEL: custom selection file 2020-04-24 18:12:18 +05:30
launch Drop fzy support 2020-05-06 18:41:01 +05:30
mediainf Change requires to dependencies 2020-05-06 10:59:57 +05:30
mimelist Change requires to dependencies 2020-05-06 10:59:57 +05:30
moclyrics Change requires to dependencies 2020-05-06 10:59:57 +05:30
mocplay Uniform plugins 2020-05-06 10:42:50 +05:30
mp3conv Update mocplay to understand opener calls 2020-02-23 15:29:21 +05:30
nbak Uniform plugins 2020-05-06 10:42:50 +05:30
nmount Force undetachable edits in EDITOR 2019-11-24 01:54:06 +05:30
nuke Late handle blocked mimes 2020-05-17 00:46:49 +05:30
oldbigfile Change requires to dependencies 2020-05-06 10:59:57 +05:30
organize Plugin organize 2019-08-19 23:01:41 +05:30
pdfread Rename plugins, group related ones 2019-11-22 17:51:13 +05:30
pdfview shellcheck fixes 2019-11-22 11:13:34 +05:30
picker Uniform plugins 2020-05-06 10:42:50 +05:30
preview-kitty preview-kitty polish (async version + text render for SVGs) (#591) 2020-05-23 15:59:51 +05:30
preview-tabbed Minor doc update 2020-05-08 01:08:42 +05:30
preview-tui Change binary file detection in preview-tui/kitty (#587) 2020-05-22 08:18:00 +05:30
pskill Drop fzy support 2020-05-06 18:41:01 +05:30
README.md Add -a option to generate a temporary NNN_FIFO (#588) 2020-05-23 17:40:51 +05:30
renamer NNN_SEL: custom selection file 2020-04-24 18:12:18 +05:30
ringtone Change requires to dependencies 2020-05-06 10:59:57 +05:30
splitjoin NNN_SEL: custom selection file 2020-04-24 18:12:18 +05:30
suedit Change command order 2020-01-15 17:18:10 +05:30
treeview Plugin treeview to show tree o/p with perms and size 2019-11-16 11:22:34 +05:30
uidgid Uniform plugins 2020-05-06 10:42:50 +05:30
upgrade Uniform plugins 2020-05-06 10:42:50 +05:30
upload Change requires to dependencies 2020-05-06 10:59:57 +05:30
vidthumb Change requires to dependencies 2020-05-06 10:59:57 +05:30
wall Integrate similar plugins, diff should begin at start of file 2019-11-22 13:50:00 +05:30
x2sel Change requires to dependencies 2020-05-06 10:59:57 +05:30

nnn plugins

read ebooks with plugin gutenread (Android)

image preview with plugin imgthumb

Introduction

Plugins extend the capabilities of nnn. They are executable scripts (or binaries) nnn can communicate with and trigger. This mechanism fits perfectly with the fundamental design to keep the core file manager lean and fast, by delegating repetitive (but not necessarily file manager-specific) tasks to the plugins which can be run with custom hotkeys.

nnn is language-agnostic when it comes to plugins. You can write a plugin in any (scripting) language you are comfortable in!

Installing plugins

The following command installs or updates (after backup) all plugins:

curl -Ls https://raw.githubusercontent.com/jarun/nnn/master/plugins/getplugs | sh

Plugins are installed to ${XDG_CONFIG_HOME:-$HOME/.config}/nnn/plugins.

List of plugins

Plugin (a-z) Description Lang Dependencies
autojump Navigate to dir/path sh autojump
bookmarks Use named bookmarks managed with symlinks sh fzf
boom Play random music from dir sh moc
dups List non-empty duplicate files in current dir sh find, md5sum,
sort uniq xargs
chksum Create and verify checksums sh md5sum,
sha256sum
diffs Diff for selection (limited to 2 for directories) sh vimdiff
dragdrop Drag/drop files from/into nnn sh dragon
finder Run custom find command and list sh -
fzcd Change to the directory of a fuzzy-selected file/dir sh fzf
fzhist Fuzzy-select a cmd from history, edit in $EDITOR and run sh fzf
fzopen Fuzzy find a file in dir subtree and edit or open sh fzf, xdg-open
fzz Change to any directory in the z database with fzf sh fzf, z
getplugs Update plugins to installed nnn version sh curl
gutenread Browse, download, read from Project Gutenberg sh curl, unzip, w3m
epr (optional)
hexview View a file in hex in $PAGER sh xxd
imgresize Resize images in dir to screen resolution sh imgp
imgthumb View thumbnail of an image or dir of images sh lsix
imgur Upload an image to imgur (from imgur-screenshot) bash -
imgview Browse images, set wallpaper, copy path (config), rename sh sxiv/viu, less
ipinfo Fetch external IP address and whois information sh curl, whois
kdeconnect Send selected files to an Android device sh kdeconnect-cli
launch GUI application launcher sh fzf
mediainf Show media information sh mediainfo
mimelist List files by mime in subtree sh fd/find
moclyrics Show lyrics of the track playing in moc sh ddgr, moc
mocplay Append (and/or play) selection/dir/file in moc sh moc
mp3conv Extract audio from multimedia as mp3 sh ffmpeg
nbak Backs up nnn config sh tar, awk
nmount Toggle mount status of a device as normal user sh pmount, udisks2
nuke Sample file opener (CLI-only by default) sh see in-file docs
oldbigfile List large files by access time sh find, sort
organize Auto-organize files in directories by file type sh file
pdfread Read a PDF or text file aloud sh pdftotext, mpv,
pico2wave
pdfview View PDF file in $PAGER sh pdftotext/
mupdf-tools
picker Pick files and list one per line (to pipe) sh nnn
preview-kitty File previewer in a kitty terminal pane sh kitty, optional:
exa bat mediainfo
preview-tabbed tabbed/xembed based file previewer bash see in-file docs
preview-tui Simple TUI file previewer (needs NNN_FIFO) sh tmux (>= 3.0)/xterm/
$TERMINAL, file, tree
pskill Fuzzy list by name and kill process or zombie sh fzf, ps, sudo/doas
renamer Batch rename selection or files in dir sh qmv/vidir
ringtone Create a variable bitrate mp3 ringtone from file sh date, ffmpeg
splitjoin Split file or join selection sh split, cat
suedit Edit file using superuser permissions sh sudoedit/sudo/doas
treeview Informative tree output in $EDITOR sh tree
uidgid List user and group of all files in dir sh ls, less
upgrade Upgrade nnn manually on Debian 9 Stretch sh curl
upload Paste text to ix.io, upload binary to file.io sh curl, jq, tr
vidthumb Show video thumbnails in terminal sh ffmpegthumbnailer,
lsix
wall Set wallpaper or change colorscheme sh nitrogen/pywal
x2sel Copy \n-separated file list from system clipboard to sel sh see in-file docs

Invoking a plugin

Press the plugin shortcut (; or ^S) followed by the assigned key character. E.g., with the below config:

export NNN_PLUG='f:finder;o:fzopen;p:mocplay;d:diffs;t:nmount;v:imgview'

Plugin finder can be run with the keybind ;f, fzopen can be run with ;o and so on... The key vs. plugin pairs are shown in the help and config screen.

Alternatively, combine with Alt (i.e. Alt+key).

To select and invoke a plugin from the plugin directory, press Enter (to enter the plugin dir) after the plugin shortcut.

Skip directory refresh after running a plugin

nnn refreshes the directory after running a plugin to reflect any changes by the plugin. To disable this (say while running the mediainfo plugin on some filtered files), add a - before the plugin name:

export NNN_PLUG='m:-mediainf'

Now nnn will not refresh the directory after running the mediainfo plugin.

Running commands as plugin

To assign keys to arbitrary non-background, non-shell-interpreted cli commands and invoke like plugins, add _ (underscore) before the command.

For example:

export NNN_PLUG='x:_chmod +x $nnn;g:_git log;s:_smplayer $nnn'

Now ;x can be used to make a file executable, ;g can be used to the git log of a git project directory, ;s can be used to preview a partially downloaded media file.

Skip user confirmation after command execution

nnn waits for user confirmation (the prompt Press Enter to continue) after it executes a command as plugin (unlike plugins which can add a read to wait). To skip this, add a * after the command. For example:

export NNN_PLUG='s:_smplayer $nnn*;n:-_vim /home/vaio/Dropbox/Public/synced_note*'

Now there will be no prompt after ;s and ;n.

Note: Do not use * with programs those run and exit e.g. cat.

Run GUI app as plugin

To run a GUI app as plugin, add a | after _. For example:

export NNN_PLUG='m:-_|mousepad $nnn'

Notes:

  1. Use single quotes for $NNN_PLUG so $nnn is not interpreted
  2. $nnn should be the last argument (IF used)
  3. (Again) add _ before the command
  4. To disable directory refresh after running a command as plugin, prefix with -_

Some useful key-command examples

Key:Command Description
g:-_git diff Show git diff
k:-_fuser -kiv $nnn* Interactively kill process(es) using hovered file
l:-_git log Show git log
n:-_vi /home/user/Dropbox/dir/note* Take quick notes in a synced file/dir of notes
p:-_less -iR $nnn* Page through hovered file in less
s:-_|smplayer -minigui $nnn Play hovered media file, even unfinished download
x:_chmod +x $nnn Make the hovered file executable
y:-_sync* Flush cached writes

Access level of plugins

When nnn executes a plugin, it does the following:

  • Changes to the directory where the plugin is to be run ($PWD pointing to the active directory)
  • Passes two arguments to the script:
    1. The hovered file's name.
    2. The working directory (might differ from $PWD in case of symlinked paths; non-canonical).
  • Sets the environment variable NNN_PIPE used to control nnn active directory.

Plugins can also read the .selection file in the config directory.

Create your own plugins

Plugins can be written in any scripting language. However, POSIX-compliant shell scripts runnable in sh are preferred.

Drop the plugin in ${XDG_CONFIG_HOME:-$HOME/.config}/nnn/plugins and make it executable. Optionally add a hotkey in $NNN_PLUG for frequent usage.

Send data to nnn

nnn provides a mechanism for plugins to send data to nnn to control its active directory or invoke the list mode. The way to do so is by writing to the pipe pointed by the environment variable NNN_PIPE. The plugin should write a single string in the format <ctxcode><opcode><data> without a newline at the end. For example, 1c/etc.

The ctxcode indicates the context to change the active directory of.

Context code Meaning
1-4 context number
0 current context
+ smart context (next inactive else current)

The opcode indicates the operation type.

Opcode Operation
c change directory
l list files in list mode

For convenience, we provided a helper script named .nnn-plugin-helper and a function named nnn_cd to ease this process. nnn_cd receives the path to change to as the first argument, and the context as an optional second argument. If a context is not provided, it is asked for explicitly. To skip this and choose the current context, set the CUR_CTX variable in .nnn-plugin-helper to 1. Usage examples can be found in the Examples section below.

Get notified on file hover

If NNN_FIFO is set, nnn will open it and write every hovered files. This can be used in plugins and external scripts, e.g. to implement file previews.

The easiest way to set NNN_FIFO is to start nnn with the -a option, to automatically setup a temporary FIFO file for this nnn instance.

If a NNN_FIFO environment variable is set globally (and -a is not passed to nnn), each nnn instance will write to the same FIFO, and a process reading from the pipe will get hovered path from every instance, interleaved.

Don't forget to fork in the background to avoid blocking nnn.

Examples

There are many plugins provided by nnn which can be used as examples. Here are a few simple selected examples.

  • Show the git log of changes to the particular file along with the code for a quick and easy review.

    #!/usr/bin/env sh
    git log -p -- "$1"
    
  • Change to directory in clipboard using helper script

    #!/usr/bin/env sh
    . $(dirname $0)/.nnn-plugin-helper
    
    nnn_cd "$(xsel -ob)"
    
  • Change directory to the location of a link using helper script with specific context (current)

    #!/usr/bin/env sh
    . $(dirname $0)/.nnn-plugin-helper
    
    nnn_cd "$(dirname $(readlink -fn $1))" 0
    
  • Change to arbitrary directory without helper script

    #!/usr/bin/env sh
    printf "cd to: "
    read -r dir
    
    printf "%s" "0c$dir" > "$NNN_PIPE"
    
  • Send every hovered file to X selection

    #!/usr/bin/env sh
    if [ -z "$NNN_FIFO" ] ; then
        exit 1
    fi
    
    while read FILE ; do
        printf "%s" "$FILE" | xsel
    done < "$NNN_FIFO" &
    disown
    

Contributing plugins

  1. Add informative sections like Description, Notes, Dependencies, Shell, Author etc. in the plugin.
  2. Add an entry in the table above.
  3. Keep non-portable commands (like notify-send) commented so users from any other OS/DE aren't surprised.
  4. The plugin file should be executable.
  5. If your plugin stores data, use ${XDG_CACHE_HOME:-$HOME/.cache}/nnn. Document it in-file.