nnn/plugins/README.md

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) which 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.

List of plugins

Plugin (a-z)	Description	Lang	Deps
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
exetoggle	Toggle executable status of hovered file	sh	chmod
fzcd	Change to the directory of a fuzzy-selected file/dir	sh	fzf/fzy fd/fdfind/find
fzhist	Fuzzy-select a cmd from history, edit in $EDITOR and run	sh	fzf/fzy
fzopen	Fuzzy find a file in dir subtree and edit or open	sh	fzf/fzy, xdg-open
getplugs	Update plugins	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
imgsxiv	Browse images, set wallpaper, copy path (config), rename	sh	sxiv
imgthumb	View thumbnail of an image or dir of images	sh	lsix
imgur	Upload an image to imgur (from imgur-screenshot)	bash	-
imgviu	View an image or images in dir in $PAGER	sh	viu, less
ipinfo	Fetch external IP address and whois information	sh	curl, whois
jump	Navigate to dir/path (autojump stores navigation patterns)	sh	autojump
kdeconnect	Send selected files to an Android device	sh	kdeconnect-cli
launch	GUI application launcher	sh	fzf/fzy
mediainf	Show media information	sh	mediainfo
moclyrics	Show lyrics of the track playing in moc	sh	ddgr, moc
mocplay	Append (and/or play) selection/dir/file in moc	sh	moc
nmount	Toggle mount status of a device as normal user	sh	pmount, udisks2
notes	Open a quick notes file/dir in $EDITOR	sh	-
nuke	Sample file opener (CLI-only by default)	sh	various
oldbigfile	List large files by access time	sh	find, sort
organize	Auto-organize files in directories by file type	sh	file
pastebin	Paste contents of a text a file ix.io	sh	-
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
pskill	Fuzzy list by name and kill process or zombie	sh	fzf/fzy, 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
transfer	Upload file to transfer.sh	sh	curl
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
vidthumb	Show video thumbnails in terminal	sh	ffmpegthumbnailer, lsix
wall	Set wallpaper or change colorscheme	sh	nitrogen/pywal

Installing plugins

The following command installs 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. You can run the getplugs plugin later to update the plugins. It backs up earlier plugins.

Executing plugins

Method 1: Directly with ;key or xkey:

export NNN_PLUG='o:fzopen;p:mocplay;d:diffs;m:nmount;n:notes;v:imgviu;t:imgthumb'

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

Method 2: Use the pick plugin shortcut to visit the plugin directory and execute a plugin. Repeating the same shortcut cancels the operation and puts you back in the original directory.

Skip directory refresh after running a plugin

nnn refreshes a directory after running a plugin by key (Method 1 above) to reflect any chanegs in the directory by the plugin. However, there are scenarios where this isn't desired, say while running the mediainfo plugin on some filtered files. To achive this, add a - before the plugin name, e.g.:

export NNN_PLUG='o:fzopen;m:-mediainfo;p:mocplay;

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

Running commands as plugin

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

For example:

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

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.

nnn waits for user confirmation (the prompt Press Enter to continue) when it executes a command as plugin (unline plugins which can add a read to wait). If you do not need to wait for user confirmation after the command has executed, add a * after the command. For example:

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

Now there will be no prompt after ;s.

Notes:

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

Access level of plugins

When nnn executes a plugin, it does the following:

• Change 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). Note that the second argument is not passed in case of commands starting with _.
• Sets the environment variable NNN_PIPE used to control nnn active directory.

Plugins can also access the current selections by reading the .selections file in the config directory (See the diffs plugin for example).

Create your own plugins

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

Once it's ready, drop the plugin in ${XDG_CONFIG_HOME:-$HOME/.config}/nnn/plugins and make it executable. Optionally add a custom keybind in $NNN_PLUG if you intend to use the plugin frequently.

Controlling nnn's active directory

nnn provides a mechanism for plugins to control its active directory. 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 <number><path> without a newline at the end. For example, 1/etc. The number indicates the context to change the active directory of (0 is used to indicate the current context).

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. Usage examples can be found in the Examples section below.

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 direcory 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" "0$dir" > "$NNN_PIPE"
  

Contributing plugins

Add informative sections like Description, Notes, Dependencies, Shell, Author etc. in the plugin as applicable. Add an entry in the table above. Please keep non-portable commands (like notify-send) commented so users from any other OS/DE aren't surprised.

The plugins should be executable.