nnn/nnn.1

480 lines
14 KiB
Groff
Raw Normal View History

2020-07-14 00:14:41 +00:00
.Dd Jul 14, 2020
.Dt NNN 1
2014-10-22 11:52:45 +00:00
.Os
.Sh NAME
.Nm nnn
2018-08-06 23:22:39 +00:00
.Nd the missing terminal file manager for X
2014-10-22 11:52:45 +00:00
.Sh SYNOPSIS
2017-06-04 17:45:08 +00:00
.Nm
.Op Ar -a
.Op Ar -A
.Op Ar -b key
2019-10-02 22:16:35 +00:00
.Op Ar -c
.Op Ar -C
.Op Ar -d
.Op Ar -e
2019-11-24 13:53:09 +00:00
.Op Ar -E
.Op Ar -f
2020-03-30 03:39:11 +00:00
.Op Ar -F
2019-12-14 08:36:00 +00:00
.Op Ar -g
.Op Ar -H
2019-10-11 15:56:03 +00:00
.Op Ar -K
.Op Ar -l
2019-07-14 17:30:14 +00:00
.Op Ar -n
2018-11-23 17:11:47 +00:00
.Op Ar -p file
2020-05-29 23:47:06 +00:00
.Op Ar -P key
2019-12-14 17:58:13 +00:00
.Op Ar -Q
.Op Ar -r
2019-12-01 17:30:06 +00:00
.Op Ar -R
.Op Ar -s name
2017-04-14 18:44:25 +00:00
.Op Ar -S
.Op Ar -t secs
2020-03-17 21:05:05 +00:00
.Op Ar -T key
.Op Ar -u
.Op Ar -V
.Op Ar -x
2017-04-14 18:44:25 +00:00
.Op Ar -h
.Op Ar PATH
2014-10-22 11:52:45 +00:00
.Sh DESCRIPTION
.Nm
2020-01-15 05:39:51 +00:00
(Nnn's Not Noice) is a performance-optimized, feature-packed fork of
2020-02-03 03:16:14 +00:00
noice (http://git.2f30.org/noice/) with seamless desktop
2020-04-12 13:31:02 +00:00
integration, simplified navigation, \fItype-to-nav\fR mode with
2020-02-03 03:16:14 +00:00
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.
2014-10-22 11:52:45 +00:00
.Pp
.Nm
2017-12-24 13:16:56 +00:00
opens the current working directory by default if
2017-04-14 18:44:25 +00:00
.Ar PATH
2017-03-31 02:52:51 +00:00
is not specified.
2018-11-11 10:52:58 +00:00
.Sh KEYBINDS
.Pp
Press \fB?\fR in
.Nm
to see the list of keybinds.
2018-11-11 10:52:58 +00:00
.Sh OPTIONS
.Pp
2017-04-01 05:18:18 +00:00
.Nm
2017-04-13 13:43:33 +00:00
supports the following options:
2017-04-01 05:18:18 +00:00
.Pp
.Fl a
auto-setup temporary NNN_FIFO (described in ENVIRONMENT section)
.Pp
.Fl A
2020-04-12 13:31:02 +00:00
disable directory auto-select in type-to-nav mode
.Pp
.Fl "b key"
specify bookmark key to open
.Pp
.Fl c
2020-04-13 21:32:53 +00:00
indicates that the opener is a cli-only opener (overrides -e)
.Pp
.Fl C
place hardware cursor on hovered entry
.Pp
.Fl d
detail mode
.Pp
.Fl e
open text files in $VISUAL (else $EDITOR, fallback vi) [preferably CLI]
.Pp
2019-11-24 13:53:09 +00:00
.Fl E
use $EDITOR for internal undetached edits
.Pp
.Fl f
use readline history file
.Pp
2020-03-30 03:39:11 +00:00
.Fl F
show fortune in help and settings screen
.Pp
2019-12-14 08:36:00 +00:00
.Fl g
use regex filters instead of substring match
.Pp
.Fl H
show hidden files
.Pp
2019-10-11 15:56:03 +00:00
.Fl K
test for keybind collision
.Pp
.Fl "l val"
number of lines to move per mouse wheel scroll
.Pp
2019-07-14 17:30:14 +00:00
.Fl n
2020-04-12 13:31:02 +00:00
start in type-to-nav mode
2019-07-14 17:30:14 +00:00
.Pp
.Fl o
open files only on Enter key
.Pp
2018-11-23 17:11:47 +00:00
.Fl "p file"
copy (or \fIpick\fR) selection to file, or stdout if file='-'
.Pp
2020-05-29 23:47:06 +00:00
.Fl "P key"
specify plugin key to run
.Pp
2019-12-14 17:58:13 +00:00
.Fl Q
2020-01-15 05:39:51 +00:00
disable confirmation on quit with multiple contexts active
2019-12-14 17:58:13 +00:00
.Pp
.Fl r
2020-01-15 05:39:51 +00:00
show cp, mv progress
(Linux-only, needs advcpmv; '^T' shows the progress on BSD/macOS)
.Pp
2019-12-01 17:30:06 +00:00
.Fl R
disable rollover at edges
.Pp
.Fl "s name"
load a session by name
.Pp
.Fl S
2020-04-17 23:24:07 +00:00
persistent session
2017-04-13 13:43:33 +00:00
.Pp
.Fl "t secs"
idle timeout in seconds to lock terminal
.Pp
2020-03-17 21:05:05 +00:00
.Fl "T key"
sort order
keys: 'a'u / 'd'u / 'e'xtension / 'r'everse / 's'ize / 't'ime / 'v'ersion
.Pp
.Fl u
2020-06-16 13:39:09 +00:00
use selection if available, don't prompt to choose between selection and hovered entry
.Pp
.Fl V
2019-12-28 05:45:38 +00:00
show version and exit
.Pp
.Fl x
2020-01-15 05:39:51 +00:00
show notis on selection cp, mv, rm completion
copy path to system clipboard on select
.Pp
2017-04-14 18:44:25 +00:00
.Fl h
show program help and exit
2014-10-22 11:52:45 +00:00
.Sh CONFIGURATION
2020-01-15 05:39:51 +00:00
There is no configuration file. Associated files are at
.Pp
\fB${XDG_CONFIG_HOME:-$HOME/.config}/nnn/\fR
.Pp
2020-01-15 05:39:51 +00:00
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.
2018-11-08 12:59:38 +00:00
.Sh CONTEXTS
2020-06-11 05:41:35 +00:00
Open multiple locations with 4 contexts. The status is shown in the top left
corner:
2018-11-08 12:59:38 +00:00
.Pp
2019-08-21 02:13:15 +00:00
- the current context is in reverse video
2018-11-08 12:59:38 +00:00
.br
2019-03-23 14:14:07 +00:00
- other active contexts are underlined
2018-11-08 12:59:38 +00:00
.br
2019-03-23 14:14:07 +00:00
- rest are inactive
2018-11-08 12:59:38 +00:00
.Pp
2020-04-09 04:18:04 +00:00
A new context copies the state of the previous context. Each context can have
its own color. See ENVIRONMENT section.
.Sh SESSIONS
2020-01-15 05:39:51 +00:00
Sessions are a way to save and restore states of work. A session stores the
settings and contexts.
.Pp
2020-06-11 05:41:35 +00:00
Sessions can be loaded dynamically at runtime or with a program option.
.Pp
2020-01-15 05:39:51 +00:00
When a session is loaded dynamically, the last working session is saved
2020-04-17 23:24:07 +00:00
automatically to a dedicated -- "last session" -- session file. The "last
session" is also used in persistent session mode.
2020-01-15 05:39:51 +00:00
.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.
2014-10-22 11:52:45 +00:00
.Sh FILTERS
2020-04-09 04:18:04 +00:00
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.
2020-01-11 05:53:57 +00:00
.Pp
2020-02-27 14:21:04 +00:00
Special keys at filter prompt:
.Bd -literal
2020-07-12 18:50:12 +00:00
-------- + ---------------------------------------
Key | Function
-------- + ---------------------------------------
^char | Usual keybind functionality
Esc | Exit filter prompt but skip dir refresh
Alt+Esc | Exit filter prompt and refresh dir
-------- + ---------------------------------------
2020-02-27 14:21:04 +00:00
.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
2020-04-12 13:31:02 +00:00
in \fBtype-to-nav\fR mode:
2020-02-27 14:21:04 +00:00
.Bd -literal
------ + ------------------------
Key | Function
------ + ------------------------
' | Go to first non-dir file
2020-04-12 13:31:02 +00:00
+ | Toggle auto-advance
2020-07-07 02:27:43 +00:00
, | Mark CWD
2020-02-27 14:21:04 +00:00
- | Go to last visited dir
. | Show hidden files
; | Run a plugin by its key
= | Launch a GUI application
2020-03-20 18:16:58 +00:00
> | Export file list
2020-02-27 14:21:04 +00:00
@ | Visit start dir
] | Show command prompt
` | Visit /
~ | Go HOME
------ + ------------------------
.Ed
2020-01-12 08:35:33 +00:00
.Pp
2019-12-14 08:36:00 +00:00
Common regex use cases:
.Pp
2020-01-15 05:39:51 +00:00
(1) To list all matches starting with the filter expression,
start the expression with a '^' (caret) symbol.
.br
2019-12-10 12:55:00 +00:00
(2) Type '\\.mkv' to list all MKV files.
2018-05-01 04:39:10 +00:00
.br
(3) Use '.*' to match any character (\fIsort of\fR fuzzy search).
2020-03-20 19:25:46 +00:00
.br
(4) Exclude filenames having 'nnn' (compiled with PCRE lib): '^(?!nnn)'
.Pp
2020-04-12 13:31:02 +00:00
In the \fItype-to-nav\fR mode directories are opened in filter
2020-04-09 04:18:04 +00:00
mode, allowing continuous navigation.
.br
2019-09-28 15:08:41 +00:00
When there's a unique match and it's a directory,
.Nm
2020-01-15 05:39:51 +00:00
auto selects the directory and enters it in this mode. Use the relevant
program option to disable this behaviour.
2019-04-21 18:37:48 +00:00
.Sh SELECTION
2020-02-03 03:16:14 +00:00
.Nm
allows file selection across directories and contexts!
.Pp
2019-12-13 18:47:16 +00:00
There are 3 groups of keybinds to add files to selection:
.Pp
2020-04-09 04:18:04 +00:00
(1) hovered file selection toggle
- deselects if '+' is visible before the entry, else adds to selection
.br
2020-04-09 04:18:04 +00:00
(2) add a range of files to selection
- repeat the range key on the same entry twice to clear selection completely
2019-10-06 14:22:30 +00:00
.br
(3) add all files in the current directory to selection
2019-09-29 17:29:27 +00:00
.Pp
A selection can be edited, copied, moved, removed, archived or linked.
2019-11-29 15:28:12 +00:00
.Pp
2020-01-15 05:39:51 +00:00
Absolute paths of the selected files are copied to \fB.selection\fR file in
2020-04-10 13:02:28 +00:00
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).
2020-01-15 05:39:51 +00:00
.Pp
.Nm
2020-06-16 13:39:09 +00:00
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
2020-01-15 05:39:51 +00:00
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.
2020-06-09 05:14:09 +00:00
.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
2020-02-03 03:16:14 +00:00
.Pp
2020-06-09 05:14:09 +00:00
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
2020-06-11 05:41:35 +00:00
limit is 65,536 paths or 256 MiB of data.
2020-02-03 03:16:14 +00:00
.Pp
2020-06-09 05:14:09 +00:00
To list the input stream, start
2020-02-03 03:16:14 +00:00
.Nm
2020-06-09 05:14:09 +00:00
by writing to its standard input. E.g., to list files in current
2020-04-09 04:18:04 +00:00
directory larger than
2020-02-03 03:16:14 +00:00
1M:
.Bd -literal
find -maxdepth 1 -size +1M -print0 | nnn
.Ed
.Pp
2020-04-09 04:18:04 +00:00
or redirect a list from a file:
2020-02-03 03:16:14 +00:00
.Bd -literal
nnn < files.txt
.Ed
.Pp
2020-04-10 12:30:52 +00:00
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
2020-02-03 03:16:14 +00:00
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.
2020-01-15 05:39:51 +00:00
.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.
2015-11-26 15:03:26 +00:00
.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.
2016-08-21 08:28:53 +00:00
.Pp
2020-03-15 15:25:14 +00:00
\fBNNN_OPTS:\fR binary options to
.Nm
.Bd -literal
export NNN_OPTS="cEnrx"
.Ed
.Pp
2019-12-29 17:51:18 +00:00
\fBNNN_OPENER:\fR specify a custom file opener.
.Bd -literal
export NNN_OPENER=nuke
2020-03-15 15:25:14 +00:00
NOTE: 'nuke' is a file opener available in the plugin repository.
2019-12-29 17:51:18 +00:00
.Ed
.Pp
2020-01-15 05:39:51 +00:00
\fBNNN_BMS:\fR bookmark string as \fIkey_char:location\fR pairs
2020-02-28 13:50:42 +00:00
separated by \fI;\fR:
2017-06-11 04:15:50 +00:00
.Bd -literal
2018-11-11 21:34:17 +00:00
export NNN_BMS='d:~/Documents;u:/home/user/Cam Uploads;D:~/Downloads/'
.Ed
.Pp
2020-05-05 17:39:24 +00:00
\fBNNN_PLUG:\fR directly executable plugins as \fIkey_char:plugin\fR pairs
2020-02-28 13:50:42 +00:00
separated by \fI;\fR:
.Bd -literal
2020-05-04 14:47:40 +00:00
export NNN_PLUG='f:finder;o:fzopen;p:mocplay;d:diffs;t:nmount;v:imgview'
2019-12-29 17:51:18 +00:00
NOTES:
2020-05-13 07:25:46 +00:00
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.
2019-12-29 17:51:18 +00:00
2020-05-04 14:47:40 +00:00
export NNN_PLUG='m:-mediainf'
2017-06-11 04:15:50 +00:00
.Ed
.Pp
2019-11-20 21:08:34 +00:00
To assign keys to arbitrary non-background non-shell-interpreted cli
2020-01-15 05:39:51 +00:00
commands and invoke like plugins, add \fI_\fR (underscore) before the
command.
.Bd -literal
2020-05-04 14:47:40 +00:00
export NNN_PLUG='x:_chmod +x $nnn;g:_git log;s:_smplayer $nnn'
NOTES:
2019-11-23 20:43:27 +00:00
1. Use single quotes for $NNN_PLUG so $nnn is not interpreted
2020-01-15 05:39:51 +00:00
2. $nnn should be the last argument (IF used)
2019-12-29 17:51:18 +00:00
3. (Again) add \fB_\fR before the command
2020-01-15 05:39:51 +00:00
4. To disable directory refresh after running a \fIcommand as plugin\fR,
prefix with \fB-_\fR
2019-12-29 17:51:18 +00:00
5. To skip user confirmation after command execution, suffix with \fB*\fR
2020-05-14 18:43:55 +00:00
Note: Do not use \fB*\fR with programs those run and exit e.g. cat
2019-12-29 17:51:18 +00:00
export NNN_PLUG='y:-_sync*'
2020-01-30 18:08:36 +00:00
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
----------------------------------- + -------------------------------------------------
2020-03-30 20:29:30 +00:00
g:-_git diff | Show git diff
2020-05-04 14:47:40 +00:00
k:-_fuser -kiv $nnn* | Interactively kill process(es) using hovered file
2020-03-30 20:29:30 +00:00
l:-_git log | Show git log
n:-_vi /home/user/Dropbox/dir/note* | Take quick notes in a synced file/dir of notes
2020-01-15 04:12:23 +00:00
p:-_less -iR $nnn* | Page through hovered file in less
2020-01-30 18:08:36 +00:00
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
2017-06-11 04:15:50 +00:00
.Pp
2020-01-18 15:31:27 +00:00
\fBNNN_COLORS:\fR string of color codes for each context, e.g.:
2018-12-03 16:14:33 +00:00
.Bd -literal
2020-01-18 15:31:27 +00:00
export NNN_COLORS='1234'
2018-12-03 16:14:33 +00:00
codes: 0-black, 1-red, 2-green, 3-yellow, 4-blue (default), 5-magenta, 6-cyan, 7-white
.Ed
.Pp
2020-03-15 15:25:14 +00:00
\fBNNN_ARCHIVE:\fR archive types 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
2020-01-18 15:31:27 +00:00
\fBNNN_SSHFS:\fR pass additional options to sshfs command:
2019-06-24 16:15:02 +00:00
.Bd -literal
2020-01-18 15:31:27 +00:00
export NNN_SSHFS='sshfs -o reconnect,idmap=user,cache_timeout=3600'
2019-06-24 16:15:02 +00:00
2020-03-15 15:25:14 +00:00
NOTE: The options must be preceded by "sshfs" and comma-separated without any space between them.
2019-06-24 16:15:02 +00:00
.Ed
.Pp
2020-01-18 15:31:27 +00:00
\fBNNN_RCLONE:\fR pass additional options to rclone command:
2019-11-24 15:52:44 +00:00
.Bd -literal
2020-01-18 15:31:27 +00:00
export NNN_RCLONE='rclone mount --read-only --no-checksum'
2019-11-24 15:52:44 +00:00
2020-03-15 15:25:14 +00:00
NOTE: The options must be preceded by "rclone" and max 5 flags are supported.
2019-11-24 15:52:44 +00:00
.Ed
.Pp
2019-03-09 03:13:56 +00:00
\fBNNN_TRASH:\fR trash (instead of \fIdelete\fR) files to desktop Trash.
2019-03-02 11:23:16 +00:00
.Bd -literal
export NNN_TRASH=1
.Ed
2019-10-06 14:22:30 +00:00
.Pp
2020-05-04 04:20:31 +00:00
\fBNNN_SEL:\fR absolute path to custom selection file.
.Pp
2020-05-05 20:15:04 +00:00
\fBNNN_FIFO:\fR path of a named pipe to write the hovered file path:
2020-05-04 04:20:31 +00:00
.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).
2020-05-04 04:20:31 +00:00
.Ed
.Pp
2020-04-15 18:59:45 +00:00
\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
2020-01-15 05:39:51 +00:00
\fBnnn:\fR this is a special variable set to the hovered entry before executing
a command from the command prompt or spawning a shell.
.Pp
\fBNO_COLOR:\fR disable ANSI color output (overridden by \fBNNN_COLORS\fR).
2014-10-22 13:59:15 +00:00
.Sh KNOWN ISSUES
2019-09-28 15:08:41 +00:00
.Nm
2020-01-15 05:39:51 +00:00
may not handle keypresses correctly when used with tmux (see issue #104 for
more details). Set \fBTERM=xterm-256color\fR to address it.
2014-10-22 11:52:45 +00:00
.Sh AUTHORS
2019-09-28 15:08:41 +00:00
.An Arun Prakash Jana Aq Mt engineerarun@gmail.com ,
.An Lazaros Koromilas Aq Mt lostd@2f30.org ,
2019-09-28 15:08:41 +00:00
.An Dimitris Papastamos Aq Mt sin@2f30.org .
2017-03-31 02:52:51 +00:00
.Sh HOME
2017-04-01 05:18:18 +00:00
.Em https://github.com/jarun/nnn