mirror of https://github.com/jarun/nnn.git
530 lines
16 KiB
Groff
530 lines
16 KiB
Groff
.Dd Aug 18, 2020
|
|
.Dt NNN 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm nnn
|
|
.Nd the missing terminal file manager for X
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Ar -a
|
|
.Op Ar -A
|
|
.Op Ar -b key
|
|
.Op Ar -c
|
|
.Op Ar -C
|
|
.Op Ar -d
|
|
.Op Ar -e
|
|
.Op Ar -E
|
|
.Op Ar -f
|
|
.Op Ar -F
|
|
.Op Ar -g
|
|
.Op Ar -H
|
|
.Op Ar -K
|
|
.Op Ar -l
|
|
.Op Ar -n
|
|
.Op Ar -p file
|
|
.Op Ar -P key
|
|
.Op Ar -Q
|
|
.Op Ar -r
|
|
.Op Ar -R
|
|
.Op Ar -s name
|
|
.Op Ar -S
|
|
.Op Ar -t secs
|
|
.Op Ar -T key
|
|
.Op Ar -u
|
|
.Op Ar -V
|
|
.Op Ar -w
|
|
.Op Ar -x
|
|
.Op Ar -h
|
|
.Op Ar PATH
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
(Nnn's Not Noice) is a performance-optimized, feature-packed fork of
|
|
noice (http://git.2f30.org/noice/) with seamless desktop
|
|
integration, simplified navigation, \fItype-to-nav\fR mode with
|
|
auto select, disk usage analyzer mode, bookmarks, contexts, application
|
|
launcher, familiar navigation shortcuts, subshell spawning and much
|
|
more.It remains a simple and efficient file manager that stays out of your way.
|
|
.Pp
|
|
.Nm
|
|
opens the current working directory by default if
|
|
.Ar PATH
|
|
is not specified.
|
|
.Sh KEYBINDS
|
|
.Pp
|
|
Press \fB?\fR in
|
|
.Nm
|
|
to see the list of keybinds.
|
|
.Sh OPTIONS
|
|
.Pp
|
|
.Nm
|
|
supports the following options:
|
|
.Pp
|
|
.Fl a
|
|
auto-setup temporary NNN_FIFO (described in ENVIRONMENT section)
|
|
.Pp
|
|
.Fl A
|
|
disable directory auto-select in type-to-nav mode
|
|
.Pp
|
|
.Fl "b key"
|
|
specify bookmark key to open
|
|
.Pp
|
|
.Fl c
|
|
indicates that the opener is a cli-only opener (overrides -e)
|
|
.Pp
|
|
.Fl C
|
|
earlier colorscheme - color directories by context, disable file colors
|
|
.Pp
|
|
.Fl d
|
|
detail mode
|
|
.Pp
|
|
.Fl e
|
|
open text files in $VISUAL (else $EDITOR, fallback vi) [preferably CLI]
|
|
.Pp
|
|
.Fl E
|
|
use $EDITOR for internal undetached edits
|
|
.Pp
|
|
.Fl f
|
|
use readline history file
|
|
.Pp
|
|
.Fl F
|
|
show fortune in help and settings screen
|
|
.Pp
|
|
.Fl g
|
|
use regex filters instead of substring match
|
|
.Pp
|
|
.Fl H
|
|
show hidden files
|
|
.Pp
|
|
.Fl K
|
|
test for keybind collision
|
|
.Pp
|
|
.Fl "l val"
|
|
number of lines to move per mouse wheel scroll
|
|
.Pp
|
|
.Fl n
|
|
start in type-to-nav mode
|
|
.Pp
|
|
.Fl o
|
|
open files only on Enter key
|
|
.Pp
|
|
.Fl "p file"
|
|
copy (or \fIpick\fR) selection to file, or stdout if file='-'
|
|
.Pp
|
|
.Fl "P key"
|
|
specify plugin key to run
|
|
.Pp
|
|
.Fl Q
|
|
disable confirmation on quit with multiple contexts active
|
|
.Pp
|
|
.Fl r
|
|
show cp, mv progress
|
|
(Linux-only, needs advcpmv; '^T' shows the progress on BSD/macOS)
|
|
.Pp
|
|
.Fl R
|
|
disable rollover at edges
|
|
.Pp
|
|
.Fl "s name"
|
|
load a session by name
|
|
.Pp
|
|
.Fl S
|
|
persistent session
|
|
.Pp
|
|
.Fl "t secs"
|
|
idle timeout in seconds to lock terminal
|
|
.Pp
|
|
.Fl "T key"
|
|
sort order
|
|
keys: 'a'u / 'd'u / 'e'xtension / 'r'everse / 's'ize / 't'ime / 'v'ersion
|
|
.Pp
|
|
.Fl u
|
|
use selection if available, don't prompt to choose between selection and hovered entry
|
|
.Pp
|
|
.Fl V
|
|
show version and exit
|
|
.Pp
|
|
.Fl w
|
|
place hardware cursor on hovered entry
|
|
.Pp
|
|
.Fl x
|
|
show notis on selection cp, mv, rm completion
|
|
copy path to system clipboard on select
|
|
.Pp
|
|
.Fl h
|
|
show program help and exit
|
|
.Sh CONFIGURATION
|
|
There is no configuration file. Associated files are at
|
|
.Pp
|
|
\fB${XDG_CONFIG_HOME:-$HOME/.config}/nnn/\fR
|
|
.Pp
|
|
Configuration is done using a few optional (set if you need) environment
|
|
variables. See ENVIRONMENT section.
|
|
.Pp
|
|
.Nm
|
|
uses \fIxdg-open\fR (on Linux), \fIopen(1)\fR (on macOS), \fIcygstart\fR on
|
|
(Cygwin) and \fIopen\fR on (Haiku) as the desktop opener. It's also possible
|
|
to specify a custom opener. See ENVIRONMENT section.
|
|
.Sh CONTEXTS
|
|
Open multiple locations with 4 contexts. The status is shown in the top left
|
|
corner:
|
|
.Pp
|
|
- the current context is in reverse video
|
|
.br
|
|
- other active contexts are underlined
|
|
.br
|
|
- rest are inactive
|
|
.Pp
|
|
A new context copies the state of the previous context. Each context can have
|
|
its own color. See ENVIRONMENT section.
|
|
.Sh SESSIONS
|
|
Sessions are a way to save and restore states of work. A session stores the
|
|
settings and contexts.
|
|
.Pp
|
|
Sessions can be loaded dynamically at runtime or with a program option.
|
|
.Pp
|
|
When a session is loaded dynamically, the last working session is saved
|
|
automatically to a dedicated -- "last session" -- session file. The "last
|
|
session" is also used in persistent session mode.
|
|
.Pp
|
|
All the session files are located by session name in the directory
|
|
.Pp
|
|
\fB${XDG_CONFIG_HOME:-$HOME/.config}/nnn/sessions\fR
|
|
.Pp
|
|
"@" is the "last session" file.
|
|
.Sh FILTERS
|
|
Filters are strings (or regex patterns) to find matching entries in the current
|
|
directory instantly (\fIsearch-as-you-type\fR). Matches are case-insensitive by
|
|
default. The last filter in each context is persisted at runtime or in saved
|
|
sessions.
|
|
.Pp
|
|
Special keys at filter prompt:
|
|
.Bd -literal
|
|
-------- + ---------------------------------------
|
|
Key | Function
|
|
-------- + ---------------------------------------
|
|
^char | Usual keybind functionality
|
|
Esc | Exit filter prompt but skip dir refresh
|
|
Alt+Esc | Exit filter prompt and refresh dir
|
|
-------- + ---------------------------------------
|
|
.Ed
|
|
.Pp
|
|
Special keys at \fBempty filter prompt\fR:
|
|
.Bd -literal
|
|
------ + ---------------------------------------
|
|
Key | Function
|
|
------ + ---------------------------------------
|
|
? | Show help and config screen
|
|
/ | Toggle between string and regex
|
|
: | Toggle case-sensitivity
|
|
^L | Clear filter (\fIif prompt is non-empty\fR)
|
|
| OR apply last filter
|
|
------ + ---------------------------------------
|
|
.Ed
|
|
.Pp
|
|
Additional special keys at \fBempty filter prompt\fR
|
|
in \fBtype-to-nav\fR mode:
|
|
.Bd -literal
|
|
------ + ------------------------
|
|
Key | Function
|
|
------ + ------------------------
|
|
' | Go to first non-dir file
|
|
+ | Toggle auto-advance
|
|
, | Mark CWD
|
|
- | Go to last visited dir
|
|
. | Show hidden files
|
|
; | Run a plugin by its key
|
|
= | Launch a GUI application
|
|
> | Export file list
|
|
@ | Visit start dir
|
|
] | Show command prompt
|
|
` | Visit /
|
|
~ | Go HOME
|
|
------ + ------------------------
|
|
.Ed
|
|
.Pp
|
|
Common regex use cases:
|
|
.Pp
|
|
(1) To list all matches starting with the filter expression,
|
|
start the expression with a '^' (caret) symbol.
|
|
.br
|
|
(2) Type '\\.mkv' to list all MKV files.
|
|
.br
|
|
(3) Use '.*' to match any character (\fIsort of\fR fuzzy search).
|
|
.br
|
|
(4) Exclude filenames having 'nnn' (compiled with PCRE lib): '^(?!nnn)'
|
|
.Pp
|
|
In the \fItype-to-nav\fR mode directories are opened in filter
|
|
mode, allowing continuous navigation.
|
|
.br
|
|
When there's a unique match and it's a directory,
|
|
.Nm
|
|
auto selects the directory and enters it in this mode. Use the relevant
|
|
program option to disable this behaviour.
|
|
.Sh SELECTION
|
|
.Nm
|
|
allows file selection across directories and contexts!
|
|
.Pp
|
|
There are 3 groups of keybinds to add files to selection:
|
|
.Pp
|
|
(1) hovered file selection toggle
|
|
- deselects if '+' is visible before the entry, else adds to selection
|
|
.br
|
|
(2) add a range of files to selection
|
|
- repeat the range key on the same entry twice to clear selection completely
|
|
.br
|
|
(3) add all files in the current directory to selection
|
|
.Pp
|
|
A selection can be edited, copied, moved, removed, archived or linked.
|
|
.Pp
|
|
Absolute paths of the selected files are copied to \fB.selection\fR file in
|
|
the config directory. The selection file is shared between multiple program
|
|
instances. The most recent instance writing to the file overwrites the entries
|
|
from earlier writes. If you have 2 instances if
|
|
.Nm
|
|
\fIopen\fR in 2 panes of a terminal multiplexer, you can select in one pane and
|
|
use the selection (e.g. to copy or move) in the other pane (if the instance
|
|
doesn't have any local selection already).
|
|
.Pp
|
|
.Nm
|
|
clears the selection after file removal, batch-rename and link creation with
|
|
selection. However, it is retained after archive creation with selection as
|
|
the user may want to delete the archived files next.
|
|
.Pp
|
|
To edit the selection use the _edit selection_ key. Use this key to remove a
|
|
file from selection after you navigate away from its directory. Editing doesn't
|
|
end the selection mode. You can add more files to the selection and edit the
|
|
list again. If no file is selected in the current session, this option attempts
|
|
to list the selection file.
|
|
.Sh FIND AND LIST
|
|
There are two ways to search and list:
|
|
.Pp
|
|
- feed a list of file paths as input
|
|
.br
|
|
- search using a plugin (e.g. \fIfinder\fR) and list the results
|
|
.Pp
|
|
File paths must be NUL-separated ('\\0'). Paths and can be relative to the
|
|
current directory or absolute. Invalid paths in the input are ignored. Input
|
|
limit is 65,536 paths or 256 MiB of data.
|
|
.Pp
|
|
To list the input stream, start
|
|
.Nm
|
|
by writing to its standard input. E.g., to list files in current
|
|
directory larger than
|
|
1M:
|
|
.Bd -literal
|
|
find -maxdepth 1 -size +1M -print0 | nnn
|
|
.Ed
|
|
.Pp
|
|
or redirect a list from a file:
|
|
.Bd -literal
|
|
nnn < files.txt
|
|
.Ed
|
|
.Pp
|
|
Handy bash/zsh shell function to list files by mime-type in current directory:
|
|
.Bd -literal
|
|
# to show video files, run: list video
|
|
|
|
list ()
|
|
{
|
|
find . -maxdepth 1 | file -if- | grep "$1" | awk -F: '{printf "%s\0", $1}' | nnn
|
|
}
|
|
.Ed
|
|
.Pp
|
|
A temporary directory will be created containing symlinks to the given
|
|
paths. Any action performed on these symlinks will be performed only on their
|
|
targets, after which they might become invalid.
|
|
.Pp
|
|
Right arrow or 'l' on a symlink in the listing dir takes to the target file.
|
|
Press '-' to return to the listing dir. Press 'Enter' to open the symlink.
|
|
.Sh UNITS
|
|
The minimum file size unit is byte (B). The rest are K, M, G, T, P, E, Z, Y
|
|
(powers of 1024), same as the default units in \fIls\fR.
|
|
.Sh ENVIRONMENT
|
|
The SHELL, EDITOR (VISUAL, if defined) and PAGER environment variables are
|
|
used. A single combination of arguments is supported for SHELL and PAGER.
|
|
.Pp
|
|
\fBNNN_OPTS:\fR binary options to
|
|
.Nm
|
|
.Bd -literal
|
|
export NNN_OPTS="cEnrx"
|
|
.Ed
|
|
.Pp
|
|
\fBNNN_OPENER:\fR specify a custom file opener.
|
|
.Bd -literal
|
|
export NNN_OPENER=nuke
|
|
|
|
NOTE: 'nuke' is a file opener available in the plugin repository.
|
|
.Ed
|
|
.Pp
|
|
\fBNNN_BMS:\fR bookmark string as \fIkey_char:location\fR pairs
|
|
separated by \fI;\fR:
|
|
.Bd -literal
|
|
export NNN_BMS='d:~/Documents;u:/home/user/Cam Uploads;D:~/Downloads/'
|
|
.Ed
|
|
.Pp
|
|
\fBNNN_PLUG:\fR directly executable plugins as \fIkey_char:plugin\fR pairs
|
|
separated by \fI;\fR:
|
|
.Bd -literal
|
|
export NNN_PLUG='f:finder;o:fzopen;p:mocplay;d:diffs;t:nmount;v:imgview'
|
|
|
|
NOTES:
|
|
1. To run a plugin directly, press \fI;\fR followed by the key.
|
|
2. Alternatively, combine with \fIAlt\fR (i.e. \fIAlt+key\fR).
|
|
3. To skip directory refresh after running a plugin, prefix with \fB-\fR.
|
|
|
|
export NNN_PLUG='m:-mediainf'
|
|
.Ed
|
|
.Pp
|
|
To assign keys to arbitrary non-background non-shell-interpreted cli
|
|
commands and invoke like plugins, add \fI_\fR (underscore) before the
|
|
command.
|
|
.Bd -literal
|
|
export NNN_PLUG='x:_chmod +x $nnn;g:_git log;s:_smplayer $nnn'
|
|
|
|
To pick and run an unassigned plugin, press \fBEnter\fR at the plugin prompt.
|
|
To run a plugin at startup, use the option `-P` followed by the plugin key.
|
|
|
|
NOTES:
|
|
1. Use single quotes for $NNN_PLUG so $nnn is not interpreted
|
|
2. $nnn should be the last argument (IF used)
|
|
3. (Again) add \fB_\fR before the command
|
|
4. To disable directory refresh after running a \fIcommand as plugin\fR,
|
|
prefix with \fB-_\fR
|
|
5. To skip user confirmation after command execution, suffix with \fB*\fR
|
|
Note: Do not use \fB*\fR with programs those run and exit e.g. cat
|
|
|
|
export NNN_PLUG='y:-_sync*'
|
|
|
|
6. To run a \fIGUI app as plugin\fR, add a \fB|\fR after \fB_\fR
|
|
|
|
export NNN_PLUG='m:-_|mousepad $nnn'
|
|
|
|
EXAMPLES:
|
|
----------------------------------- + -------------------------------------------------
|
|
Key:Command | Description
|
|
----------------------------------- + -------------------------------------------------
|
|
g:-_git diff | Show git diff
|
|
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
|
|
----------------------------------- + -------------------------------------------------
|
|
.Ed
|
|
.Pp
|
|
\fBNNN_COLORS:\fR string of color codes for each context, e.g.:
|
|
.Bd -literal
|
|
# 8 color codes
|
|
# codes: 0-black, 1-red, 2-green, 3-yellow, 4-blue (default), 5-magenta, 6-cyan, 7-white
|
|
export NNN_COLORS='1234'
|
|
|
|
# xterm 256 color codes (in hex, 2 symbols per context)
|
|
# codes: https://upload.wikimedia.org/wikipedia/commons/1/15/Xterm_256color_chart.svg
|
|
export NNN_COLORS='#0a1b2c3d'
|
|
|
|
# both (256 followed by 8 as fallback, separated by ';')
|
|
export NNN_COLORS='#0a1b2c3d;1234'
|
|
|
|
NOTE: If only 256 colors are specified and the terminal doesn't support, default (4-blue) is used.
|
|
.Ed
|
|
.Pp
|
|
\fBNNN_FCOLORS:\fR specify file-type specific colors:
|
|
.Bd -literal
|
|
export NNN_FCOLORS='c1e2272e006033f7c6d6abc4'
|
|
|
|
Specify file-specific colors with xterm 256 color codes (2 hex symbols per color).
|
|
Order is strict, use 00 to omit/use default terminal color. Defaults:
|
|
|
|
------------------------- + --- + -------------
|
|
Order | Hex | Color
|
|
------------------------- + --- + -------------
|
|
Block device | c1 | DarkSeaGreen1
|
|
Char device | e2 | Yellow1
|
|
Directory | 27 | DeepSkyBlue1
|
|
Executable | 2e | Green1
|
|
Regular | 00 | Normal
|
|
Hard link | 60 | Plum4
|
|
Symbolic link | 33 | Cyan1
|
|
Missing OR file details | f7 | Grey62
|
|
Orphaned symbolic link | c6 | DeepPink1
|
|
FIFO | d6 | Orange1
|
|
Socket | ab | MediumOrchid1
|
|
Unknown OR 0B regular/exe | c4 | Red1
|
|
------------------------- + --- + -------------
|
|
|
|
If the terminal supports xterm 256 colors or more, file-specific colors will be rendered.
|
|
To force the earlier colorscheme (dirs follow context color) use option -C.
|
|
If xterm 256 colors aren't supported, earlier colorscheme will be used.
|
|
.Ed
|
|
.Pp
|
|
\fBNNN_ARCHIVE:\fR archive extensions to be handled silently (default: bzip2, (g)zip, tar).
|
|
.Bd -literal
|
|
export NNN_ARCHIVE="\\\\.(7z|bz2|gz|tar|tgz|zip)$"
|
|
|
|
NOTE: Non-default formats may require a third-party utility.
|
|
.Ed
|
|
.Pp
|
|
\fBNNN_SSHFS:\fR pass additional options to sshfs command:
|
|
.Bd -literal
|
|
export NNN_SSHFS='sshfs -o reconnect,idmap=user,cache_timeout=3600'
|
|
|
|
NOTE: The options must be preceded by "sshfs" and comma-separated without any space between them.
|
|
.Ed
|
|
.Pp
|
|
\fBNNN_RCLONE:\fR pass additional options to rclone command:
|
|
.Bd -literal
|
|
export NNN_RCLONE='rclone mount --read-only --no-checksum'
|
|
|
|
NOTE: The options must be preceded by "rclone" and max 5 flags are supported.
|
|
.Ed
|
|
.Pp
|
|
\fBNNN_TRASH:\fR trash (instead of \fIdelete\fR) files to desktop Trash.
|
|
.Bd -literal
|
|
export NNN_TRASH=1
|
|
.Ed
|
|
.Pp
|
|
\fBNNN_SEL:\fR absolute path to custom selection file.
|
|
.Pp
|
|
\fBNNN_FIFO:\fR path of a named pipe to write the hovered file path:
|
|
.Bd -literal
|
|
export NNN_FIFO='/tmp/nnn.fifo'
|
|
|
|
NOTES:
|
|
1. Overridden by a temporary path with -a option.
|
|
2. If the FIFO file doesn't exist it will be created,
|
|
but not removed (unless it is generated by -a option).
|
|
.Ed
|
|
.Pp
|
|
.Em https://github.com/jarun/nnn/wiki/Live-previews
|
|
.Pp
|
|
\fBNNN_LOCKER:\fR terminal locker program.
|
|
.Bd -literal
|
|
export NNN_LOCKER='bmon -p wlp1s0'
|
|
export NNN_LOCKER='cmatrix'
|
|
.Ed
|
|
.Pp
|
|
\fBNNN_MCLICK:\fR key emulated by a middle mouse click.
|
|
.Bd -literal
|
|
export NNN_MCLICK='^R'
|
|
|
|
NOTE: Only the first character is considered if not a \fICtrl+key\fR combo.
|
|
.Ed
|
|
.Pp
|
|
\fBnnn:\fR this is a special variable.
|
|
.Bd -literal
|
|
Set to the hovered file name before starting the command prompt or spawning a shell.
|
|
.Ed
|
|
.Pp
|
|
\fBNO_COLOR:\fR disable ANSI color output (overridden by \fBNNN_COLORS\fR).
|
|
.Sh KNOWN ISSUES
|
|
.Nm
|
|
may not handle keypresses correctly when used with tmux (see issue #104 for
|
|
more details). Set \fBTERM=xterm-256color\fR to address it.
|
|
.Sh AUTHORS
|
|
.An Arun Prakash Jana Aq Mt engineerarun@gmail.com ,
|
|
.An Lazaros Koromilas Aq Mt lostd@2f30.org ,
|
|
.An Dimitris Papastamos Aq Mt sin@2f30.org .
|
|
.Sh HOME
|
|
.Em https://github.com/jarun/nnn
|