nnn/plugins
Anna Arad 9afd7cf3bf Implement plugins control of nnn + plugins (#364)
* Implement plugins control of nnn + plugins

* Refactor plugins control code and fix getplugs to recognize hidden files

* Fix bug when going to dir on non-current context from plugin

* Fix some plugins to work on openbsd and freebsd

* Renamings

* Switch to -R flag in cp instead of -r; BSDs complain

* Change braces of function location

* Rewrite plugin creation in README and add new plugins to the table

* Update the fzcd script to include fzy or fzf

* Change plugin name resolve-link-dir -> lncd

* Fixing plugins README table

* Remove some cd plugins but add them as examples to plugins README
2019-10-23 15:34:12 +05:30
..
.nnn-plugin-helper Implement plugins control of nnn + plugins (#364) 2019-10-23 15:34:12 +05:30
boom Fix plugin boom, make customizable 2019-08-25 06:17:05 +05:30
checksum Fix #328 2019-08-23 21:43:32 +05:30
drag-file Check for alternative name for drag/drop exec (#354) 2019-10-13 00:48:50 +05:30
drop-file Check for alternative name for drag/drop exec (#354) 2019-10-13 00:48:50 +05:30
dups Plugin dups: find duplicate files in dir 2019-08-24 21:23:52 +05:30
fzcd Implement plugins control of nnn + plugins (#364) 2019-10-23 15:34:12 +05:30
fzy-open Suppress permission denied messages 2019-10-04 20:46:57 +05:30
getplugs Implement plugins control of nnn + plugins (#364) 2019-10-23 15:34:12 +05:30
gutenread gutenread: support epub 2019-10-13 12:06:32 +05:30
hexview Fix hex viewer 2019-07-21 13:50:46 +05:30
imgresize Plugins! 2019-04-18 20:32:53 +05:30
imgur Plugin dups: find duplicate files in dir 2019-08-24 21:23:52 +05:30
ipinfo ipinfo shows external IP address 2019-05-24 23:14:19 +05:30
kdeconnect Fix #288 2019-06-20 19:17:00 +05:30
mediainf Implement mediainfo as a plugin 2019-08-28 00:02:33 +05:30
moclyrics Update plugin docs 2019-08-15 11:11:23 +05:30
mocplay mocplay: confirm working with selection 2019-09-16 23:35:43 +05:30
ndiff ndiff: direction to get rid of vim warning 2019-08-14 01:38:30 +05:30
nmount Supprt exit on 'q' 2019-06-10 19:47:00 +05:30
notes Add plugin to take quick notes 2019-09-26 19:56:43 +05:30
nwal Plugins! 2019-04-18 20:32:53 +05:30
oldbigfile Plugin oldbigfile: find large files by access time 2019-08-30 20:01:13 +05:30
organize Plugin organize 2019-08-19 23:01:41 +05:30
pastebin Use ix.io paste service 2019-10-04 18:45:21 +05:30
pdfview Update plugins, add mutool to view PDF 2019-06-01 00:34:07 +05:30
picker Plugins! 2019-04-18 20:32:53 +05:30
pywal Plugins! 2019-04-18 20:32:53 +05:30
readit Add text2speech plugin 2019-06-23 01:43:52 +05:30
README.md Implement plugins control of nnn + plugins (#364) 2019-10-23 15:34:12 +05:30
ringtone Small ringtone plugin fixes 2019-06-27 03:38:02 +02:00
splitjoin Add an mp3 ringtone generator 2019-06-21 22:36:34 +05:30
suedit suedit plugin (#359) 2019-10-14 06:36:11 +05:30
sxiv Plugins! 2019-04-18 20:32:53 +05:30
thumb Show image thumbnails with lsix 2019-07-12 00:16:07 +05:30
transfer Plugins! 2019-04-18 20:32:53 +05:30
uidgid Group dirs on top 2019-10-03 02:24:08 +05:30
upgrade Add command to download plugins 2019-09-27 21:13:01 +05:30
vidthumb Plugin vidthumb 2019-08-15 10:06:41 +05:30
viuimg Update plugin viuimg 2019-10-01 07:35:54 +05:30

nnn plugins

image preview with plugin thumb

Plugins extend the capabilities of nnn. They are scripts 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.

The currently available plugins are listed below.

Plugin (a-z) Lang Deps Description
boom sh moc Play random music from dir
dups sh find, md5sum,
sort uniq xargs
List non-empty duplicate files in current dir
checksum sh md5sum,
sha256sum
Create and verify checksums
drag-file sh dragon Drag and drop files from nnn
drop-file sh dragon Drag and drop files into nnn
fzcd sh fzy/fzf
(optional fd)
Change to the directory of a file/directory selected by fzy/fzf
fzy-open sh fzy, xdg-open Fuzzy find a file in dir subtree and edit or xdg-open
getplugs sh curl Update plugins
gutenread sh curl, unzip, w3m
epr (optional)
Browse, download, read from Project Gutenberg
hexview sh xxd View a file in hex in $PAGER
imgresize sh imgp Resize images in dir to screen resolution
imgur bash - Upload an image to imgur (from imgur-screenshot)
ipinfo sh curl, whois Fetch external IP address and whois information
kdeconnect sh kdeconnect-cli Send selected files to an Android device
mediainf sh mediainfo Show media information
moclyrics sh ddgr, moc Show lyrics of the track playing in moc
mocplay sh moc Append (and/or play) selection/dir/file in moc
ndiff sh vimdiff Diff for selection (limited to 2 for directories)
nmount sh pmount, udisks2 Toggle mount status of a device as normal user
notes sh - Open a quick notes file/dir in $EDITOR
nwal sh nitrogen Set image as wallpaper using nitrogen
oldbigfile sh find, sort List large files by access time
organize sh file Auto-organize files in directories by file type
pastebin sh - Paste contents of a text a file ix.io
pdfview sh pdftotext/
mupdf-tools
View PDF file in $PAGER
picker sh nnn Pick files and list one per line (to pipe)
pywal sh pywal Set image as wallpaper, change terminal colorscheme
readit sh pdftotext, mpv,
pico2wave
Read a PDF or text file aloud
ringtone sh date, ffmpeg Create a variable bitrate mp3 ringtone from file
splitjoin sh split, cat Split file or join selection
suedit sh sudoedit/sudo/doas Edit file using superuser permissions
sxiv sh sxiv View images in dir, set wallpaper, copy path (config)
thumb sh lsix View thumbnail of an image or dir of images
transfer sh curl Upload file to transfer.sh
uidgid sh ls, less List user and group of all files in dir
upgrade sh curl Upgrade nnn manually on Debian 9 Stretch
vidthumb sh ffmpegthumbnailer,
lsix
Show video thumbnails in terminal
viuimg sh viu, less View an image or images in dir in $PAGER

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.

NOTE: getplugs also downloads the launcher nlaunch and tries to place it at /usr/local/bin/ using sudo. If it fails you have to place nlauch manually somewhere in your $PATH.

Executing plugins

Method 1: Directly with :key:

export NNN_PLUG='o:fzy-open;p:mocplay;d:ndiff;m:nmount;n:notes;v:viuimg;t:thumb'

With this, plugin fzy-open 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. Up to 10 plugins can have such keybinds.

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.

Create your own plugins

Plugins are a powerful yet easy way to extend the capabilities of nnn.

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

Each script has a Description section which provides more details on what the script does, if applicable.

The plugins reside in ${XDG_CONFIG_HOME:-$HOME/.config}/nnn/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)
  • 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 ndiff plugin for example).

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
    echo -n "cd to: "
    read dir
    
    echo -n "0$dir" > $NNN_PIPE
    

Contributing plugins

Please keep non-portable commands (like notify-send) commented so users from any other OS/DE aren't surprised.

The plugins should be executable. Please add an entry in the table above.