nnn/plugins
Arun Prakash Jana 74b779abc9
Update docs
2021-09-30 03:17:02 +05:30
..
.cbcp Replace which with builtin type in plugins 2021-05-14 17:33:28 +05:30
.iconlookup Icon changes .iconlookup (#1136) 2021-08-18 23:16:29 +05:30
.nmv Update .nmv 2021-05-01 06:23:39 +05:30
.nnn-plugin-helper Chnage tabs to spaces 2021-05-15 06:57:20 +05:30
.ntfy Replace which with builtin type in plugins 2021-05-14 17:33:28 +05:30
autojump Combine assignment of $_Z_DATA, $Z_DATA or $HOME/.z 2021-09-26 23:17:51 +02:00
boom Sanitize in-plugin documentation 2021-05-15 23:02:01 +05:30
bulknew Sanitize in-plugin documentation 2021-05-15 23:02:01 +05:30
cdpath Truncate the name, add comments. 2021-03-29 21:29:03 -04:00
chksum Sanitize in-plugin documentation 2021-05-15 23:02:01 +05:30
cmusq Exit cmusq when missing 2021-05-16 23:39:10 +02:00
diffs Sanitize in-plugin documentation 2021-05-15 23:02:01 +05:30
dragdrop Sanitize in-plugin documentation 2021-05-15 23:02:01 +05:30
dups Minor edits 2021-05-16 01:49:52 +05:30
finder Fix finder typo 2021-08-16 12:47:02 +02:00
fixname plugin cleanfilename -> fixname, unmount-parent -> umounttree 2021-05-27 19:19:51 +05:30
fzcd Replace fd dependency with find (#1078) 2021-06-21 04:59:50 +05:30
fzhist fix fzhist plugin - get fish_history from the right place 2021-08-25 10:36:10 +02:00
fzopen fzopen - add option to open files in nuke 2021-07-17 21:04:53 +05:30
fzplug Wait until cmus is ready and fix fzplug preview command 2021-05-15 22:24:40 +02:00
getplugs Replace which with builtin type in plugins 2021-05-14 17:33:28 +05:30
gpgd Sanitize in-plugin documentation 2021-05-15 23:02:01 +05:30
gpge Sanitize in-plugin documentation 2021-05-15 23:02:01 +05:30
gutenread fixed wrong spelled words 2021-01-18 13:55:28 +01:00
imgresize Sanitize in-plugin documentation 2021-05-15 23:02:01 +05:30
imgur fzopen - add option to open files in nuke 2021-07-17 21:04:53 +05:30
imgview Imgview fix ucollage directory 2021-07-01 11:24:49 +02:00
ipinfo shellcheck fixes 2019-11-22 11:13:34 +05:30
kdeconnect Sanitize in-plugin documentation 2021-05-15 23:02:01 +05:30
launch Replace which with builtin type in plugins 2021-05-14 17:33:28 +05:30
mimelist shellcheck fixes 2020-11-22 20:30:52 +05:30
moclyrics Sanitize in-plugin documentation 2021-05-15 23:02:01 +05:30
mocq Rename plugin mocplay to mocq 2021-05-16 00:25:47 +05:30
mp3conv Sanitize in-plugin documentation 2021-05-15 23:02:01 +05:30
mtpmount Sanitize in-plugin documentation 2021-05-15 23:02:01 +05:30
nbak Uniform plugins 2020-05-06 10:42:50 +05:30
nmount Update documentation 2021-05-30 23:29:10 +05:30
nuke Add option to specify arguments to exec 2021-07-21 11:54:40 +05:30
oldbigfile Change requires to dependencies 2020-05-06 10:59:57 +05:30
organize Fix #917: enhance plugin framework to clear sel on request 2021-03-27 17:12:21 +05:30
pdfread shellcheck fixes 2020-11-22 20:30:52 +05:30
preview-tabbed Revert "Close previewer when opening file (#1171)" 2021-09-22 05:46:45 +05:30
preview-tui Preview without convert 2021-09-24 12:12:13 +02:00
pskill Replace which with builtin type in plugins 2021-05-14 17:33:28 +05:30
README.md Update docs 2021-09-30 03:17:02 +05:30
renamer Plugin cleanup 1 2021-06-06 10:44:10 +05:30
ringtone Change requires to dependencies 2020-05-06 10:59:57 +05:30
rsynccp Fix #917: enhance plugin framework to clear sel on request 2021-03-27 17:12:21 +05:30
splitjoin Fix #917: enhance plugin framework to clear sel on request 2021-03-27 17:12:21 +05:30
suedit Plugin suedit - preserve environment 2021-07-17 22:00:38 +05:30
togglex Fix #917: enhance plugin framework to clear sel on request 2021-03-27 17:12:21 +05:30
umounttree plugin cleanfilename -> fixname, unmount-parent -> umounttree 2021-05-27 19:19:51 +05:30
upload Sanitize in-plugin documentation 2021-05-15 23:02:01 +05:30
wallpaper fzopen - add option to open files in nuke 2021-07-17 21:04:53 +05:30
x2sel Sanitize in-plugin documentation 2021-05-15 23:02:01 +05:30
xdgdefault xdgdefault: make dmenu case-insensitive, fix style 2021-07-28 12:30:30 +06:00

nnn plugins

read ebooks with plugin gutenread (Android)

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!

List of plugins

Plugin (a-z) Description [Clears selection1] Lang Dependencies
autojump Navigate to dir/path sh jump/autojump/
zoxide/z (needs fzf)
boom Play random music from dir sh moc
bulknew Create multiple files/dirs at once bash sed, xargs, mktemp
cdpath cd to the directory from CDPATH sh fzf
chksum Create and verify checksums [✓] sh md5sum,
sha256sum
cmusq Queue/play files/dirs in cmus player [✓] sh cmus, pgrep
diffs Diff for selection (limited to 2 for directories) [✓] sh vimdiff, mktemp
dragdrop Drag/drop files from/into nnn sh dragon
dups List non-empty duplicate files in current dir bash find, md5sum,
sort uniq xargs
finder Run custom find command (stored in histfile) and list sh -
fixname Clean filename to be more shell-friendly [✓] bash sed
fzcd Fuzzy search multiple dirs (or $PWD) and visit file sh fzf, (find)
fzhist Fuzzy-select a cmd from history, edit in $EDITOR and run sh fzf, mktemp
fzopen Fuzzy find file(s) in subtree to edit/open/pick sh fzf, xdg-open/open
fzplug Fuzzy find, preview and run other plugins sh fzf
getplugs Update plugins to installed nnn version sh curl
gpg* Encrypt/decrypt files using GPG [✓] sh gpg
gutenread Browse, download, read from Project Gutenberg sh curl, unzip, w3m
epr (optional)
imgresize Batch resize images in dir to screen resolution sh imgp
imgur Upload an image to imgur (from imgur-screenshot) bash -
imgview View (thumbnail)images, set wallpaper, rename and more sh see in-file docs
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
mimelist List files by mime in subtree sh -
moclyrics Show lyrics of the track playing in moc sh ddgr, moc
mocq Queue/play selection/dir/file in moc [✓] sh moc
mp3conv Extract audio from multimedia as mp3 sh ffmpeg
mtpmount Toggle mount of MTP device (eg. Android) sh gvfs-mtp
nbak Backs up nnn config sh tar, awk, mktemp
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
preview-tabbed Preview files with Tabbed/xembed bash see in-file docs
preview-tui Preview with Tmux/kitty/QuickLook/xterm/$TERMINAL sh see in-file docs
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
rsynccp Gives copy-paste verbose progress percentage [✓] sh rsync
splitjoin Split file or join selection [✓] sh split, cat
suedit Edit file using superuser permissions sh sudoedit/sudo/doas
togglex Toggle executable mode for selection [✓] sh chmod
umounttree Unmount a remote mountpoint from within sh fusermount
upload Upload to Firefox Send or ix.io (text) or file.io (bin) sh ffsend, curl, jq, tr
wallpaper Set wallpaper or change colorscheme sh nitrogen/pywal
x2sel Copy file list from system clipboard to selection sh see in-file docs
xdgdefault Set the default app for the hovered file type sh xdg-utils, fzf/dmenu

Note:

  1. A plugin has to explicitly request nnn to clear the selection e.g. after operating on the selected files.

Table of contents

Installation

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.

Configuration

Set environment variable NNN_PLUG to assign keybinds and invoke plugins directly using the plugin shortcut (;) 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 invoked 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 pick and run an unassigned plugin, press Enter (to enter the plugin dir) at the plugin prompt.

To run a plugin at startup, use the option -P followed by the plugin key.

If the plugins list gets too long, try breaking them up into sections:

NNN_PLUG_PERSONAL='g:personal/convert2zoom;p:personal/echo'
NNN_PLUG_WORK='j:work/prettyjson;d:work/foobar'
NNN_PLUG_INLINE='e:!go run $nnn*'
NNN_PLUG_DEFAULT='1:ipinfo;p:preview-tui;o:fzz;b:nbak'
NNN_PLUG="$NNN_PLUG_PERSONAL;$NNN_PLUG_WORK;$NNN_PLUG_DEFAULT;$NNN_PLUG_INLINE"
export NNN_PLUG

Note:

  • 'g:personal/convert2zoom' will look in the personal sub-folder inside the plugin folder.
  • 'b:boom;b:bulknew will result in only the first definition of b (b:boom) being used.
  • A keybinding definition of more than 1 character will prevent nnn from starting.

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 add a - before the plugin name:

export NNN_PLUG='p:-plugin'

Running commands as plugin

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

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.

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 a GUI app as plugin

To run a GUI app as plugin, add a & after !.

export NNN_PLUG='m:-!&mousepad $nnn'

Note: $nnn must be the last argument in this case.

Page non-interactive command output

To show the output of run-and-exit commands which do not need user input, add | (pipe) after !.

export NNN_PLUG='m:-!|mediainfo $nnn;t:-!|tree -ps;l:-!|ls -lah --group-directories-first'

This option is incompatible with & (terminal output is masked for GUI programs) and ignores * (output is already paged for user).

Notes:

  1. Use single quotes for $NNN_PLUG so $nnn is not interpreted
  2. (Again) add ! before the command
  3. To disable directory refresh after running a command as plugin, prefix with -!

Some useful key-command examples

Key:Command Description
e:-!sudo -E vim $nnn* Edit file as root in vim
g:-!git diff Show git diff
h:-!hx $nnn* Open hovered file in hx hex editor
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 three arguments to the script:
    1. $1: The hovered file's name.
    2. $2: The working directory (might differ from $PWD in case of symlinked paths; non-canonical).
    3. $3: The picker mode output file (- for stdout) if nnn is executed as a file picker.
  • Sets the environment variable NNN_PIPE used to control nnn active directory.
  • Exports the special variables.

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.

Make the file executable. Drop it in the plugin directory. 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 optional - at the beginning of the stream instructs nnn to clear the selection. In cases where the data transfer to nnn has to happen while the selection file is being read (e.g. in a loop), the plugin should create a tmp copy of the selection file, inform nnn to clear the selection and then do the subsequent processing with the tmp file.

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

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

The opcode indicates the operation type.

Opcode Operation
c change directory
l list files in list mode
p picker file overwritten

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 (or in the specific plugin after sourcing .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.

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

For more details on configuration and usage of the preview plugins, visit Live Previews.

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)"
#!/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

Quick find (using fd)

#!/usr/bin/env sh

. "$(dirname "$0")"/.nnn-plugin-helper

printf "pattern: "
read -r pattern

if [ -n "$pattern" ]; then
    printf "%s" "+l" > "$NNN_PIPE"
    eval "fd -HI $pattern -0" > "$NNN_PIPE"
fi

Quick grep (using rg)

#!/usr/bin/env sh

. "$(dirname "$0")"/.nnn-plugin-helper

printf "pattern: "
read -r pattern

if [ -n "$pattern" ]; then
    printf "%s" "+l" > "$NNN_PIPE"
    eval "rg -l0 --hidden -S $pattern" > "$NNN_PIPE"
fi

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.