Live previews

Live previews

A live preview is a window that shows information about whatever file or directory nnn has highlighted. As the cursor moves, the live preview window will automatically update.

There are two ways to enable live previews in nnn:

1. using a previewer plugin,
2. using a custom wrapper/previewer script.

Both ways use the NNN_FIFO feature to get updated on cursor move.

Previewer plugins

Setting up NNN_FIFO

Previewer plugins use NNN_FIFO. There are 2 ways to export it:

1. Globally export a FIFO path in, e.g., .profile:

   export NNN_FIFO=/tmp/nnn.fifo

   This mechanism is suitable if you are using a single instance of nnn.

2. For multiple instances of nnn, use a different FIFO path for every instance, e.g. with an alias:

   alias nnn='NNN_FIFO="$(mktemp -u)" nnn'

   nnn will create the per-instance FIFO files.

Using the plugin

Follow instructions nnn plugins' README page on how to install and use plugins.

There are currently 3 previewer plugins for nnn, using various technology to display the preview window:

• preview-kitty: the preview window is a kitty pane (needs kitty's allow_remote_control option turned on), and files are previewed using text tools (exa or ls, bat or cat, mediainfo or file, kitty's icat).
• preview-tabbed: the preview window is a tabbed X window, files are viewed using Xembed capable programs (mpv for audio/video, sxiv for images, zathura for PDF, xterm/urxvt/st + nuke plugin text preview for other files)
• preview-tui: the preview window is either a tmux pane or a new terminal window, and files are previewed using simple text tools (tree, head, file). This is the most barebone, dependecy free preview plugin, and probably the one you want to start from if you want to make your own.

Custom script configuration example

There are two aspects to creating a live preview:

1. A preview command
2. A setup command

Preview command example

#!/usr/bin/env sh
# #############################################################################
# File: preview_cmd.sh
# Description: Minimal example to preview files and directories
#              No external dependencies
#              Can be easily extended
#              Automatically exits when the NNN_FIFO closes
#              Prints a `tree` if directory or `head` if it's a file
#
# Shell: POSIX compliant
# Author: Todd Yamakawa
#
# ToDo:
#   1. Add support for more types of files
#         e.g. binary files, we shouldn't try to `head` those
# #############################################################################

# Check FIFO
NNN_FIFO=${NNN_FIFO:-$1}
if [ ! -r "$NNN_FIFO" ]; then
    echo "Unable to open \$NNN_FIFO='$NNN_FIFO'" | less
    exit 2
fi

# Read selection from $NNN_FIFO
while read -r selection; do
    clear
    lines=$(($(tput lines)-1))
    cols=$(tput cols)

    # Print directory tree
    if [ -d "$selection" ]; then
        cd "$selection" || continue
        tree | head -n $lines | cut -c 1-"$cols"
        continue
    fi

    # Print file head
    if [ -f "$selection" ]; then
        head -n $lines "$selection" | cut -c 1-"$cols"
        continue
    fi

    # Something went wrong
    echo "Unknown type: '$selection'"
done < "$NNN_FIFO"

Setup command example

To create your own setup command, you need the following steps:

1. Create a NNN_FIFO
2. Run your preview command in the background
3. Run nnn
4. Delete your NNN_FIFO

Here is am example bash/zsh function. To use this example, you will need to set the preview command. For the preview window:

• It uses tmux split if you're currently running in a tmux environment
  • tmux 3.0 is required for setting environment variables in a new pane
• Otherwise it uses an xterm window

nnn-preview ()
{
    # Block nesting of nnn in subshells
    if [ -n "$NNNLVL" ] && [ "${NNNLVL:-0}" -ge 1 ]; then
        echo "nnn is already running"
        return
    fi

    # The default behaviour is to cd on quit (nnn checks if NNN_TMPFILE is set)
    # To cd on quit only on ^G, remove the "export" as in:
    #     NNN_TMPFILE="${XDG_CONFIG_HOME:-$HOME/.config}/nnn/.lastd"
    # NOTE: NNN_TMPFILE is fixed, should not be modified
    export NNN_TMPFILE="${XDG_CONFIG_HOME:-$HOME/.config}/nnn/.lastd"

    # This will create a fifo where all nnn selections will be written to
    NNN_FIFO="$(mktemp --suffix=-nnn -u)"
    export NNN_FIFO
    (umask 077; mkfifo "$NNN_FIFO")

    # Preview command
    preview_cmd="/path/to/preview_cmd.sh"

    # Use `tmux` split as preview
    if [ -e "${TMUX%%,*}" ]; then
        tmux split-window -e "NNN_FIFO=$NNN_FIFO" -dh "$preview_cmd"

    # Use `xterm` as a preview window
    elif (which xterm &> /dev/null); then
        xterm -e "$preview_cmd" &

    # Unable to find a program to use as a preview window
    else
        echo "unable to open preview, please install tmux or xterm"
    fi

    nnn "$@"

    rm -f "$NNN_FIFO"
}