From https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_24: | The return utility shall cause the shell to stop executing the current | function or dot script. If the shell is not currently executing a | function or dot script, the results are unspecified. Closes: https://github.com/jarun/nnn/issues/1572 |
||
---|---|---|
.. | ||
.cbcp | ||
.iconlookup | ||
.nmv | ||
.nnn-plugin-helper | ||
.ntfy | ||
autojump | ||
boom | ||
bulknew | ||
cdpath | ||
chksum | ||
cmusq | ||
diffs | ||
dragdrop | ||
dups | ||
finder | ||
fixname | ||
fzcd | ||
fzhist | ||
fzopen | ||
fzplug | ||
getplugs | ||
gitroot | ||
gpgd | ||
gpge | ||
gsconnect | ||
gutenread | ||
imgresize | ||
imgur | ||
imgview | ||
ipinfo | ||
kdeconnect | ||
launch | ||
mimelist | ||
moclyrics | ||
mocq | ||
mp3conv | ||
mtpmount | ||
nbak | ||
nmount | ||
nuke | ||
oldbigfile | ||
openall | ||
organize | ||
pdfread | ||
preview-tabbed | ||
preview-tui | ||
pskill | ||
README.md | ||
renamer | ||
ringtone | ||
rsynccp | ||
splitjoin | ||
suedit | ||
togglex | ||
umounttree | ||
upload | ||
wallpaper | ||
x2sel | ||
xdgdefault |
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/z.lua |
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 |
gitroot | Cd to the root of current git repo | sh | git |
gpge | Encrypt/decrypt files using GPG [✓] | sh | gpg |
gutenread | Browse, download, read from Project Gutenberg | sh | curl, unzip, w3m epr (optional) |
gsconnect | GNOME's implementation of kdeconnect [✓] | sh | gsconnect |
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 |
openall | Open selected files together or one by one [✓] | bash | - |
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 |
Notes:
- A plugin has to explicitly request
nnn
to clear the selection e.g. after operating on the selected files. - Files starting with a dot in the
plugins
directory are internal files and should not be used as plugins.
Table of contents
- Installation
- Configuration
- Running commands as plugin
- Access level of plugins
- Create your own plugins
- Examples
- Contributing plugins
Installation
The following command installs or updates (after backup) all plugins:
sh -c "$(curl -Ls https://raw.githubusercontent.com/jarun/nnn/master/plugins/getplugs)"
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:mocq;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'
$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).
$nnn
must be the last argument in this case as well.
Notes:
- Use single quotes for
$NNN_PLUG
so$nnn
is not interpreted $nnn
must be the last argument (if used) to run a GUI app as plugin or to page non-interactive command output- (Again) add
!
before the command - To disable directory refresh after running a command as plugin, prefix with
-!
Some useful key-command examples
Key:Command | Description |
---|---|
c:!convert $nnn png:- | xclip -sel clipboard -t image/png* |
Copy image to clipboard |
C:!cp -rv "$nnn" "$nnn".cp |
Create a copy of the hovered file |
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
: The hovered file's name.$2
: The working directory (might differ from$PWD
in case of symlinked paths; non-canonical).$3
: The picker mode output file (-
for stdout) ifnnn
is executed as a file picker.
- Sets the environment variable
NNN_PIPE
used to controlnnn
active directory. - Sets the environment variable
NNN_INCLUDE_HIDDEN
to1
if hidden files are active,0
otherwise. - 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.
A paged [|
] or GUI [&
] cmd run as plugin cannot clear selection.
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)"
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
Quick find
the first match in subtree and open in nuke
#!/usr/bin/env sh
NUKE="${XDG_CONFIG_HOME:-$HOME/.config}/nnn/plugins/nuke"
printf "file name: "
read -r pattern
entry=$(find . -type f -iname "$pattern" -print -quit 2>/dev/null)
if [ -n "$entry" ]; then
"$NUKE" "$entry"
fi
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
- Add informative sections like Description, Notes, Dependencies, Shell, Author etc. in the plugin.
- Add an entry in the table above. Note that the list is alphabetically ordered by plugin name.
- Keep non-portable commands (like
notify-send
) commented so users from any other OS/DE aren't surprised. - The plugin file should be executable.
- If your plugin stores data, use
${XDG_CACHE_HOME:-$HOME/.cache}/nnn
. Document it in-file.