The nnn magic!
nnn unfolds on use. Some exquisite stuff you can do:
- Instantly load, sort, filter thousands of files
- Filter and type to navigate with automatic matching dir entry
- List input stream and pick entries to stdout or file as list
- Write a plugin in any language and talk to
nnn find/fd/grep/ripgrep/fzffromnnnand list innnn- Never lose context - start where you quit
- Mount any cloud storage service in a few keypresses
- Select files from anywhere (not just a single dir)
- Unlimited bookmarks, plugins, cmds with custom hotkeys
- Edit and preview markdown, man page, HTML
- Open a file and auto-advance to the next
- Filter filtered entries, export list of visible files
- Configure the middle mouse click to do anything
- Multi-location (or subtree) fuzzy search and visit a file
- Load four dirs with custom settings at once
- Notifications on
cp,mv,rmcompletion - Auto-sync selection to system clipboard
- Access selection from another instance of
nnn - Open text files detached in another pane/tab/window
- Mount and modify archives
- Create files/dirs/duplicates with parents (like
mkdir -p) - Toggle hidden with ., visit
$HOMEwith ~, last dir with - - Mark a frequently visited dir at runtime
- Sort by modification, access and inode change time
- Compile out/in features with make variables
- Watch matrix text fly or read fortune messages
- Configure in 5 minutes!
Add bookmarks
There are 2 ways (can be used together) to manage bookmarks.
Environment variable NNN_BMS
Set environment variable NNN_BMS as a string of key_char:location pairs separated by semicolons (;):
export NNN_BMS="d:$HOME/Documents;u:/home/user/Cam Uploads;D:$HOME/Downloads/"
The bookmarks are listed in the help and config screen (key ?).
The select bookmark key b lists all the bookmark keys set in NNN_BMS in the bookmarks prompt.
Symlinked bookmarks
A symlinked bookmark to the current directory can be created with the B key (or manually under ~/.config/nnn/bookmarks).
Pressing Enter at the bookmarks prompt takes to this directory. If NNN_BMS is not set, the select bookmark key directly opens it.
Press - to return to the original directory right after entering a symlinked bookmark.
Mark directory
To jump back and forth a specific directory during a session, you can mark the directory (key ,). Visit it anytime using the Bookmark key followed by ,. If a directory is marked, the Bookmark key lists , as well.
Configure cd on quit
Pick the appropriate file for your shell from misc/quitcd and add the contents to your shell's rc file. You'll need to spawn a new shell for the change to take effect. You should start nnn as n (or your preferred function name/alias).
By default, when ^G is pressed, nnn writes the last working directory to
${XDG_CONFIG_HOME:-$HOME/.config}/nnn/.lastd
To cd on quit always, export the environment variable NNN_TMPFILE set to your preferred file path.
The extra key ^G to cd on quit is to avoid writing to a file every time nnn quits and allows on-demand cd on quit.
Sync subshell $PWD
To configure nnn to cd to the $PWD of the exited bash subshell, add the following in .bashrc:
nnn_cd()
{
if ! [ -z "$NNN_PIPE" ]; then
printf "%s\0" "0c${PWD}" > "${NNN_PIPE}" !&
fi
}
trap nnn_cd EXIT
Add a plugin with the following contents:
#!/usr/bin/env bash
# Description: Start an interactive bash shell.
export nnn="$1"
bash -i
You can also use the run cmd as plugin method:
s:!bash -i*
Hot-plugged drives
Mount status external storage devices can be toggled in a REPL using the plugin nmount.
For auto-mounting external storage drives use udev rules or udisks wrappers.
Image, video, pdf
In addition to Live Previews, there is an independent plugin imgview to browse images/thumbnails of image, video or audio files in the terminal. Among other viewer utilities, it supports sxiv (opens its own window) which is particularly useful to browse images in a directory, set the wallpaper or copy image path to clipboard (instructions).
Browse, rename images
While the user can preview the hovered image in preview-tabbed and rename it, the following procedure is an alternative approach. It requires the imgview plugin (with sxiv) and dmenu (zenity can replace dmenu).
Save sxiv key-handler ~/.config/sxiv/exec/key-handler with the following content:
#!/usr/bin/env sh
# ^X-^R: prompt for new image name (needs `dmenu`) and `mv`
# ^X-^C: copy the image path to X clipboard (needs `xclip`)
# Example zenity prompt:
# name="$(zenity --entry --display=:0.0 --text "rename $file to")" 2> /dev/null
while read -r file
do
case "$1" in
"C-r")
name="$(dmenu -p "rename $file to: ")" 2> /dev/null
if [ -n "$name" ]; then
mv "$file" "$name"
fi
;;
"C-c")
printf "%s" "$file" | xclip -selection clipboard ;;
*)
printf "Sorry, I don't understand"
exit 1
;;
esac
done
Now hover on an image or directory and open it with the imgsxiv plugin. Browse images and press ^X followed by ^R to rename an image.
For file operations visit sxiv issue #228.
Read pdf as text
The plugin pdfview can convert and render PDF files as text in the terminal.
It has 2 methods to convert PDF to text. Please go through the script for the details.
Detached text
-
Set up a script (say
ewrap) to open the editor in a newtmuxsplit-pane or a newxfce4-terminaltab/window (you may want to change the terminal and the editor in the sample snippet below):#!/usr/bin/env sh if [ -n "$TMUX" ] ; then # tmux session running tmux split-window -h "vim \"$*\"" else # Remove option --tab for new window xfce4-terminal --tab -e "vim \"$*\"" fi -
Make
ewrapexecutable and drop it somewhere in your$PATH. -
Set
$VISUAL(or$EDITORif you don't have$VISUAL) toewrap:export VISUAL=ewrap -
Start
nnnwith the program option-e.
Notes:
- IMPORTANT: Use the program option
-Ewith detached text editing enabled.nnninternal operations which need to wait for the editor (like batch rename, copy/move as) wouldn't work as usual because the control returns tonnnafter the terminal emulator is spawned. To avoid this, set$VISUALas above and$EDITORto a CLI editor (likevim). The program option forces$EDITORto be used for internal operations (overriding$VISUALwhich takes precedence otherwise). - If you are already using
nukeas opener modify it to useewrapfor text files. You can also enhanceewrap(re-use code fromnuke) to handle text files by file type and use the right program (e.g. w3m for html, man for man pages). That way you don't have to change the opener. - If you are using a tiling window manager, the new terminal window with the editor would open beside your current window. In case of traditional window managers, the new window will be placed as per the window manager's placement configuration e.g. smart or centered on XFCE4.
Another options is to combine and use nnn with a multiplexer like dvtm:
Run commands
There are several ways to run commands from nnn:
- Launch a shell within the current directory. This is your regular shell.
- Use the prompt key to show the native command prompt and enter your command. The commands are invoked using the
$SHELLso you can use commands, aliases (in~/.zshenvfor zsh), environment variables, pipes, redirections. - You can also assign keys to arbitrary non-background cli commands (non-shell-interpreted) you use frequently and invoke like plugins. (instructions).
Shell depth indicator
If you use ! to spawn a shell in the current directory and your shell is bash or zsh, it could be nice to add:
[ -n "$NNNLVL" ] && PS1="N$NNNLVL $PS1"
To your shell's rc. This will have your prompt indicate that you are within a shell that will return you to nnn when you are done.
This together with cd on quit becomes a powerful combination. In addition, the quitcd scripts check $NNNLVL to guard against nesting.
Launch applications
GUI applications can be launched using a drop-down menu using plugin launch. nnn picks it up from the plugin location. If launch is not found, nnn shows a regular prompt for the application executable name.
To configure launch as an independent app launcher add a keybind to open launch in a terminal e.g.,
xfce4-terminal -e "${XDG_CONFIG_HOME:-$HOME/.config}/nnn/plugins/launch
GUI applications can also be launched from the prompt. Use & to launch in background so nnn isn't blocked.
Note:
- You can also launch an instance of your favorite terminal in the current directory (open terminal here...) this way.
Open as root
If you are a sudoer, open a new instance of nnn from the built-in prompt with sudo nnn.
You can also have a short and sweet (but powerful) alias (which also works at the nnn prompt):
alias N='sudo -E nnn -dH'
File picker
To use nnn as a file picker and redirect the output to other programs, use option -p. The option takes an output file as argument (use - to print the list to stdout).
Ways to pick files:
- to pick a single file and quit, hover on it and press Enter
- to pick selection and quit, select file(s) and press Enter or q
Notes:
- pressing Enter on a directory enters it; when trying to pick a directory, e.g. to pipe to
cd, use single file selection - to discard selection and quit, press ^G
Example picker mode use cases:
// list some files
ls -l $(nnn -p -)
-rw-rw-r-- 1 vaio vaio 14722 Jul 10 07:24 /home/vaio/GitHub/nnn/CHANGELOG
-rw-rw-r-- 1 vaio vaio 1472 Jul 7 21:49 /home/vaio/GitHub/nnn/LICENSE
-rw-rw-r-- 1 vaio vaio 1697 Jul 10 07:24 /home/vaio/GitHub/nnn/Makefile
// Attach some files and send a mail
neomutt -a $(nnn -p -) ...
// append some files to MOC playlist
mocp -a $(nnn -p -)
Remote mounts
nnn integrates with sshfs and rclone to support remote mounts. The mount points (for remotes as well as archives) are created within:
${XDG_CONFIG_HOME:-$HOME/.config}/nnn/mounts
Upon successful unmount, the mount points are removed.
The key to mount a remote folder is c (for connect).
Note: The mounts directory can be a symbolic link too. The target directory should have permissions to mount.
sshfs
Example primary setup: connect to SSH sever from desktop.
To connect to and mount remote shares using sshfs, nnn requires the ssh configuration file ~/.ssh/config to have the host entries. sshfs reads this file.
Example host entry for a Termux environment on Android device:
Host *
ServerAliveInterval 300
ServerAliveCountMax 2
Host phone
HostName 192.168.43.1
User u0_a117
Port 8022
Compression no
# Ciphers chacha20-poly1305@openssh.com
# ProxyJump jumphost
Once you try to connect using sshfs, nnn will prompt for the name of the host (phone in the example above). Type the exact name (as it appears in this file) optionally followed by the path in the remote host you want to mount.
Examples:
phone <----- Mount your remote user's $HOME folder in `phone`
phone:/tmp <----- Mount the remote `tmp` folder in `phone`
Host phone will be mounted at ${XDG_CONFIG_HOME:-$HOME/.config}/nnn/mounts/phone.
If you need to pass options to the sshfs command, you can do so:
export NNN_SSHFS='sshfs -o reconnect,idmap=user,cache_timeout=3600'
Options must be preceded by sshfs and comma-separated without any space between them.
rclone
The remote needs to be configured and authenticated beforehand (one-time activity). The name used to configure is all nnn needs to connect and mount (as well as unmount) the remote service locally.
If you need to pass options, use the dedicated environment variable for rclone:
export NNN_RCLONE='rclone mount --read-only --no-checksum'
A maximum of 5 flags can be passed.
Tip: To list all the remotes in the rclone config file: rclone listremotes
Unmount remotes
The unmount option (which also unmounts mounted archives BTW) works in 2 ways:
- hover on the mount point, press u (for unmount). This works for both remotes and archives.
- if the current entry is not a mount point,
nnnprompts for the remote host name
Notes:
nnnopens the mount point in a smart context after successful mounts.- More information on sshfs.
Synced quick notes
Open your note file OR directory (if your editor supports opening a dir like vim) in your favourite editor like a plugin (see plugin docs for more info):
export NNN_PLUG=n:-!vim /home/vaio/Dropbox/Public/Docs/Notes/note*
To keep the file synced across systems you may want to specify a file synced by a cloud storage service or stored in a network share.
Drag and drop
Use the plugin dragdrop.
Duplicate file
To duplicate the current entry:
- press ^R
- keep the name unchanged in the prompt and press Enter
- in the next prompt ("copy name"), provide the preferred name (and optionally the path to the duplicate file) for the duplicate and press Enter
Note:
- To cancel the rename or duplicate operations, press Enter in both prompts without changing the file name.
Create batch links
To create symbolic or hard links in batch:
- select the file(s) you want to link
- go to the target directory
- press n
- press
sfor symbolic link orhfor hard link - enter the link prefix (or
@for no prefix)
The reasons only prefix is allowed (and not full name):
- avoid prompting for link names one by one for a selection
- having the same prefix groups the newly created links together
Disable bold fonts
Most modern terminal emulators have the option to disable bold fonts.