README

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

Notes:

1. A plugin has to explicitly request nnn to clear the selection e.g. after operating on the selected files.
2. Files starting with a dot in the plugins directory are internal files and should not be used as plugins.

Table of contents

• Installation
• Configuration
  • Skip directory refresh after running a plugin
• Running commands as plugin
  • Skip user confirmation after command execution
  • Run a GUI app as plugin
  • Page non-interactive command output
  • Some useful key-command examples
• Access level of plugins
• Create your own plugins
  • Send data to nnn
  • Get notified on file hover
• 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 (<kbd>;</kbd>) 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 <kbd>;f</kbd>, fzopen can be run with <kbd>;o</kbd> and so on... The key vs. plugin pairs are shown in the help and config screen.

Alternatively, combine with <kbd>Alt</kbd> (i.e. <kbd>Alt+key</kbd>).

To pick and run an unassigned plugin, press <kbd>Enter</kbd> (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 ! before the command.

export NNN_PLUG='x:!chmod +x "$nnn";g:!git log;s:!smplayer "$nnn"'

Now <kbd>;x</kbd> can be used to make a file executable, <kbd>;g</kbd> can be used to the git log of a git project directory, <kbd>;s</kbd> 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 <kbd>;s</kbd> and <kbd>;n</kbd>.

Note: Do not use * with programs that 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"'

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. Place $nnn (or exported variables) in double quotes ("$nnn")
2. Use single quotes for $NNN_PLUG so "$nnn" is not interpreted
3. (Again) add ! before the command
4. To disable directory refresh after running a command as plugin, prefix with -!

Non-interactive command output in a floating window [>]

To show the output of run-and-exit commands in a floating window, add > (right arrow) 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 rendered in a floating window). Option - is ignored with this option. The directory is always refreshed.

Some useful key-command examples

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.
• Sets the environment variable NNN_INCLUDE_HIDDEN to 1 if hidden files are active, 0 otherwise.
• Sets the environment variable NNN_PREFER_SELECTION to 1 if user prefers to use selection (see nnn's -u flag), 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.

The opcode indicates the operation type.

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

Change directory

NNN_PLUG='c:!read -p "full path: " -r to && [ -n "$to" ] && printf "0c%s" "${to}" > "$NNN_PIPE"*'

Contributing plugins

1. Add informative sections like Description, Notes, Dependencies, Shell, Author etc. in the plugin.
2. Add an entry in the table above. Note that the list is alphabetically ordered by plugin name.
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.