Advanced use cases - mirrors/nnn

nnn supports multiple ways to show icons. They are turned off by default and are not provided in the default distribution to avoid shipping third party resources. Currently supported icon sets are:

Unicode Emojis
Nerdfont Icons
Icons-in-terminal

Icons can be customized in icons.h.

You will need to recompile nnn rather than use the default release. Or you can grab one of the icon-enabled static binaries auto-generated at each release. Arch Linux users can check out the AUR packages nnn-icons and nnn-nerd.

Note that your $TERM must support 256 colors for the icons to show. The 8-color option -C also disables icons.

To enable Unicode Emoji icons

Use a font and terminal that supports unicode emojies.
Clone the nnn repo
Compile nnn with make O_EMOJI=1

To enable Nerdfont icons

Download and install a patched Nerdfont (v3.0.0 or later).
Apply that font as your terminal emulator's font. This will vary from emulator to emulator, but usually involves editing a config file or changing a setting within a GUI menu system.
Clone the nnn repo
Compile nnn with make O_NERD=1

To enable icons-in-terminal icons

Install icons-in-terminal
Clone the nnn repo
Compile nnn with make O_ICONS=1

Move the newly compiled nnn to where your programs normally go

Once compiled, you'll notice an nnn executable is now in your root. Copy this file to wherever such programs are normally stored. A good way to check is to do a which nnn on where the packaged release was installed. Simply replacing that file should be enough.

Custom keybinds

The keybinds are defined in the bindings structure in nnn.h. Users can modify these to set their preferred shortcuts. After modifying, nnn needs to be compiled (instructions).

While it's easy to compile because of few library dependencies, customizing shortcuts can be tricky because of the number of features. To make the process simpler, nnn has an option to detect key collisions. After changing the keys, compile nnn and run:

nnn -K

Note:

There's one alternative keybind with the CONTROL (^) modifier for many operations. Those are for users who prefer to run nnn in the type-to-nav mode.

Colemak keybinds

To use colemak based keybinds, build nnn with O_COLEMAK=1. There are also other variant of colemak patches which are not maintained by the nnn devs:

CLI-only opener

If you have a custom opener (like nuke) that invokes only CLI utilities, you can indicate the same to nnn:

export NNN_OPENER=/absolute/path/to/nuke
# Otherwise, if nuke is in $PATH
# export NNN_OPENER=nuke
nnn -c

Desktop integration

To make nnn available in a XDG compatible desktop environment like GNOME, KDE, XFCE, etc. a nnn.desktop file is provided. To install it, run:

make install-desktop

Or copy nnn.desktop to ~/.local/share/applications/.

This will show a nnn entry in your desktop's application menu, search, in graphical applications' Open with menu, etc.

Note that when started from a display manager (GDM, ...) the desktop environment might start nnn in a terminal without calling any login shell. So if NNN_* variables are exported in e.g. .bashrc, .zshrc, .bash_profile, and not in .profile or .xprofile it might never be sourced, and thus never be available to nnn.

Keep your variable exports in `.bashrc`

If you want to keep your variable exports in .bashrc and your display manager never sources it, you can change the Exec= line in nnn.desktop like so:

Exec=bash -lc "nnn %f"

Use a wrapper script to export variables

Or you can also call nnn in a wrapper script with necessary exports, example:

#!/bin/sh

# If you use pywal, you need to restore the scheme here
# (cat ~/.cache/wal/sequences &)

export NNN_BMS="D:$HOME/Downloads;v:$HOME/Videos"
export NNN_COLORS="5236"
alias nsel="cat ${XDG_CONFIG_HOME:-$HOME/.config}/nnn/.selection | tr '\0' '\n'"

# To use a CLI opener, specify the `-c` option to `nnn`
# export NNN_OPENER="${XDG_CONFIG_HOME:-$HOME/.config}/nnn/plugins/nuke"

# Unmask ^Q (if required, see `stty -a`) to Quit nnn
stty start undef
stty stop undef

# Start nnn with your preferred options
nnn "$@"

Call it, e.g., nwrap, make it executable with chmod +x nwrap and drop it in your PATH.

Deeper GNOME integration

You can edit nnn.desktop to integrate more deeply with some GNOME features:

[Desktop Entry]
Name=NNN for gnome
GenericName=NNN
Comment=Supercute cli
Keywords=shell;prompt;command;commandline;cmd;nnn;
Exec=gnome-terminal --class "NNN" -- bash -ilc "nnn %f"
Icon=org.gnome.Terminal
Type=Application
Categories=GNOME;GTK;System;TerminalEmulator;
StartupNotify=true
X-GNOME-SingleWindow=false
OnlyShowIn=GNOME;Unity;
StartupWMClass=NNN

--class "NNN" is used to group all nnn instances together and StartupWMClass=NNN to tell launcher which windows should be associated with this icon.

Browser Integration

To use nnn as the file picker dialog for your browser follow the instructions for your browser of choice.

Chromium

Create a script kdialog in your PATH along the lines of:

#!/bin/sh
while :; do case $1 in
    --getsavefilename) file="$2" break ;;
    --version) printf ""; exit ;;
    --*) shift ;;
    *) break ;;
esac done

file="${file##/*/}"

st -c picker sh -c "nnn -J -p - '$file' | awk '{ print system(\"[ -d '\''\"\$0\"'\'' ]\") ? \$0 : \$0\"/$file\" }' > /proc/$$/fd/1"

This example sets the class for st to picker and nnn uses a named session picker. This allows you to for example have the picker window float by default in your window manager and nnn remembers where your previous "Save as..." target was. The -J option makes sure that the saved session saves the cursor position on the selected file/directory. Replace with your preferred terminal and nnn options if applicable.

Then create a browser wrapper that launches your browser with XDG_CURRENT_DESKTOP=KDE:

#!/bin/sh
XDG_CURRENT_DESKTOP=KDE <browser binary> "$@"

This will cause chromium to look for kdialog to open files, make sure the kdialog script comes in your PATH before the kdialog package binary if you have this installed.

Chromium will now open nnn in picker mode for "Save as/Upload file" operations, allowing you to:

Select a directory(Space) and quit(q) to save the file with its given name in the target directory.
Create a new file(n) and select it(Enter) to save the file with a different name.

To restore xdg-open functionality inside chromium, you will need a xdg-open wrapper that restores XDG_CURRENT_DESKTOP to the correct value for your environment:

#!/bin/sh
XDG_CURRENT_DESKTOP='' /usr/bin/xdg-open "$@"

Firefox

Install xdg-desktop-portal-termfilechooser and create its config file in $XDG_CONFIG_HOME/xdg-desktop-portal-termfilechooser/config:

[filechooser]
cmd=/home/<user>/.local/bin/ffnnn

Create the specified wrapper script ffnnn (name and location does not matter) in your PATH along the lines of:

#!/bin/sh
save="$3"
suggest="$4"
out="$5"
file="${suggest##/*/}"

if [ "$save" = 1 ]; then
    touch "$suggest"
fi

st -c picker sh -c "nnn -p - '$suggest' | awk '{ print system(\"[ -d '\''\"\$0\"'\'' ]\") ? \$0 : \$0\"/$file\" }' > '$out'"

if [ "$save" = 1 ]; then
    if [ ! -s "$out" ] || [ ! -s "$suggest" ]; then
        rm "$suggest" 
    fi
fi

Then make sure widget.use-xdg-desktop-portal.file-picker == 1 in about:config and firefox should use nnn as file picker dialog.

Launch `nnn` with a keyboard shortcut

On a Desktop Environment (KDE, GNOME, XFCE)

XDG application method

If your DE supports setting keybindings to applications, just install nnn.desktop, as explained above. Then set a keybind from you DE's settings.

Wrapper script method

You might want to create a wrapper script to launch nnn in a terminal, example with xfce4-terminal:

#!/bin/sh

xfce4-terminal -e "nnn \"$*\""

Name it, e.g. , nnnfm, make it executable, and drop it in your PATH.

You can now set a keybind to launch nnnfm from your DE settings.

Set as default file manager in XFCE

Now go to the preferred applications menu from Settings (or run exo-preferred-applications -c) and select nnnfm as your default file manager.

On a bare X window manager (`i3wm`, `bspwm`, `awesomewm` ...)

On the keyboard shortcuts section of your WM config file, you need to add a shortcut to launch nnn in a terminal. Here's is an example for sxhkd, you need to change xfce4-terminal to the terminal you want to use:

## File Manager
super + n
       xfce4-terminal -e "nwrap $*"

cp mv progress

This section is Linux-specific. BSD and macOS users can press ^T to check the progress.

advcpmv is used to show cp and mv progress on Linux.

To enable the feature, copy the avdcpmv-patched binaries in your PATH. Note that it's important to rename the binaries as cpg and mvg.

sudo cp src/cp /usr/local/bin/cpg
sudo cp src/mv /usr/local/bin/mvg

Use the program option -r to show the progress of the operations.

Control active dir

You can control nnn's active directory from a plugin. Find the instructions here.

Termux tips

General

It may be a good idea to let the default opener (xdg-open) handle non-text files. Set $VISUAL/$EDITOR to your preferred CLI editor and use the program option -e. The program option -R disables rollover at edges (useful on smaller form factors). Also see the mouse click options for simplified navigation and and usability with touch.

Enable file icons

Follow the instructions for desktop
Copy the file ~/.local/share/icons-in-terminal/icons-in-terminal.ttf to Termux environment ~/.termux/font.ttf
Run termux-reload-settings (or use the Termux:Styling app which is a GUI for that functionality)

Copy to clipboard

Install the Termux:API app from Google Play
On Android 7 you have to "protect" Termux:API by going into the settings / protected apps menu otherwise calls to the API like termux-battery-status will hang forever
Install the termux-api package
```
pkg in termux-api
```
Edit (for Termux) and save the copier script.
Make the script executable:
```
chmod +x /path/to/copier
```
export NNN_COPIER:
```
export NNN_COPIER="/path/to/copier"
```

Access internal and external storage

Official instructions.

Disclaimer: This is severe abuse of your pager, but it makes your life richer.

It would be convenient to have your pager choose how to view non-text files.

You could make your own customized pager handler or you could start by downloading:

$ curl -OL https://github.com/0xACE/lesspipe/raw/personal/lesspipe.sh

or git clone https://github.com/0xACE/lesspipe and then make sure you switch to the personal branch where some updates has been made.

and then have the file on some path, say:

~/git/lesspipe/lesspipe.sh

And then add:

export PAGER=less
[ -r "$HOME/git/lesspipe/lesspipe.sh" ] && export LESSOPEN="| $HOME/git/lesspipe/lesspipe.sh %s"
export LESS='-Ri '

To your ~/.bashrc or your shell rc.

This will now allow you to view files in nnn by hitting the Open in PAGER key p. This will then open your file piped through lesspipe.sh which has piped the file to other interpreters.

Note that you might want to install the following packages:

antiword - support for word file
cabextract - support for cab files
cdrkit (cdrtools) - support for iso files
fastjar - support for jar files
html2text (python-html2text, python2-html2text) - support for html files
mediainfo - support for some metadata for media files
viu - support for some image file
imagemagick - support for some image file
p7zip - support for 7za files
perl 
rpmextract - support for rpm files
unrar - support for rar files
unrtf - support for rtf file
unzip - support for zip files
source-highlight - support syntax highlighting

In the future that lesspipe.sh link might change to using atool rather than these separate archive handlers.

Working with lftp

Broadly speaking, any terminal utility can be integrated with nnn easily. For remote file transfers, lftp is the preferred tool. Let's discuss how the workflow can be simplified with nnn's capabilities and lftp combined together.

Automation using an lftp script

Use the open with key and type lftp -f to connect and transfer files to/from a remote system using a lftp script file. Note that you need to press c at the press 'c' for cli mode prompt.

Sample file:

# lftp script_file to transfer files to/from a server
# server has sshd service running and support scp

# open connection
open -u user,password -p port sftp://server_ip_address

# list files on server
ls

# create a directory
mkdir uploads

# upload some files to the directory uploads
put -O uploads file1 file2

# download some files to the current directory
pget -O downloads file3 file4

Connect to server and and copy selection manually

We will use a generic lftp setup example using lftp aliases which you can follow to connect to a SSH server and transfer your nnn selection to it.

Create an alias for this server in ~/.lftprc:

alias mob open -u username,password sftp://server_ip_address:port

Create aliases in ~/.lftprc to transfer files:

# get nnn selection and write the `put` command in a file
alias lst "!cat ${XDG_CONFIG_HOME:-$HOME/.config}/nnn/.selection | xargs -0 -I fname echo "put" \'fname\' > files.lftp"

# upload the files to the directory uploads
alias mv "source files.lftp; !rm files.lftp"

Use the command prompt key and type lftp to connect to this server.
Use the aliases to get the selection list and transfer the files. Sample operation:
```
lftp :~> mob
lftp :~> lst
lftp :~> mv
lftp :~> bye
```

More help at lftp prompt

list of supported commands:

lftp :~> ?

help on a particular command:

lftp :~> help put

File icons

To enable Unicode Emoji icons

To enable Nerdfont icons

To enable icons-in-terminal icons

Move the newly compiled nnn to where your programs normally go

Custom keybinds

Colemak keybinds

CLI-only opener

Desktop integration

Keep your variable exports in `.bashrc`

Use a wrapper script to export variables

Deeper GNOME integration

Browser Integration

Chromium

Firefox

Launch `nnn` with a keyboard shortcut

On a Desktop Environment (KDE, GNOME, XFCE)

XDG application method

Wrapper script method

Set as default file manager in XFCE

On a bare X window manager (`i3wm`, `bspwm`, `awesomewm` ...)

cp mv progress

Control active dir

Termux tips

General

Enable file icons

Copy to clipboard

Access internal and external storage

Working with lftp

Automation using an lftp script

Connect to server and and copy selection manually

More help at lftp prompt

Wiki Home

Usage

Concepts

How to

Advanced

Troubleshooting

Stats, info

Developer

File icons

To enable Unicode Emoji icons

To enable Nerdfont icons

To enable icons-in-terminal icons

Move the newly compiled nnn to where your programs normally go

Custom keybinds

Colemak keybinds

CLI-only opener

Desktop integration

Keep your variable exports in .bashrc

Use a wrapper script to export variables

Deeper GNOME integration

Browser Integration

Chromium

Firefox

Launch nnn with a keyboard shortcut

On a Desktop Environment (KDE, GNOME, XFCE)

XDG application method

Wrapper script method

Set as default file manager in XFCE

On a bare X window manager (i3wm, bspwm, awesomewm ...)

cp mv progress

Control active dir

Termux tips

General

Enable file icons

Copy to clipboard

Access internal and external storage

Pager as opener

Working with lftp

Automation using an lftp script

Connect to server and and copy selection manually

More help at lftp prompt

Wiki Home

Usage

Concepts

How to

Advanced

Troubleshooting

Stats, info

Developer

Keep your variable exports in `.bashrc`

Launch `nnn` with a keyboard shortcut

On a bare X window manager (`i3wm`, `bspwm`, `awesomewm` ...)