nnn.1

   1 .Dd Jul 14, 2020
   2 .Dt NNN 1
   3 .Os
   4 .Sh NAME
   5 .Nm nnn
   6 .Nd the missing terminal file manager for X
   7 .Sh SYNOPSIS
   8 .Nm
   9 .Op Ar -a
  10 .Op Ar -A
  11 .Op Ar -b key
  12 .Op Ar -c
  13 .Op Ar -C
  14 .Op Ar -d
  15 .Op Ar -e
  16 .Op Ar -E
  17 .Op Ar -f
  18 .Op Ar -F
  19 .Op Ar -g
  20 .Op Ar -H
  21 .Op Ar -K
  22 .Op Ar -l
  23 .Op Ar -n
  24 .Op Ar -p file
  25 .Op Ar -P key
  26 .Op Ar -Q
  27 .Op Ar -r
  28 .Op Ar -R
  29 .Op Ar -s name
  30 .Op Ar -S
  31 .Op Ar -t secs
  32 .Op Ar -T key
  33 .Op Ar -u
  34 .Op Ar -V
  35 .Op Ar -x
  36 .Op Ar -h
  37 .Op Ar PATH
  38 .Sh DESCRIPTION
  39 .Nm
  40 (Nnn's Not Noice) is a performance-optimized, feature-packed fork of
  41 noice (http://git.2f30.org/noice/) with seamless desktop
  42 integration, simplified navigation, \fItype-to-nav\fR mode with
  43 auto select, disk usage analyzer mode, bookmarks, contexts, application
  44 launcher, familiar navigation shortcuts, subshell spawning and much
  45 more.It remains a simple and efficient file manager that stays out of your way.
  46 .Pp
  47 .Nm
  48 opens the current working directory by default if
  49 .Ar PATH
  50 is not specified.
  51 .Sh KEYBINDS
  52 .Pp
  53 Press \fB?\fR in
  54 .Nm
  55 to see the list of keybinds.
  56 .Sh OPTIONS
  57 .Pp
  58 .Nm
  59 supports the following options:
  60 .Pp
  61 .Fl a
  62         auto-setup temporary NNN_FIFO (described in ENVIRONMENT section)
  63 .Pp
  64 .Fl A
  65         disable directory auto-select in type-to-nav mode
  66 .Pp
  67 .Fl "b key"
  68         specify bookmark key to open
  69 .Pp
  70 .Fl c
  71         indicates that the opener is a cli-only opener (overrides -e)
  72 .Pp
  73 .Fl C
  74         place hardware cursor on hovered entry
  75 .Pp
  76 .Fl d
  77         detail mode
  78 .Pp
  79 .Fl e
  80         open text files in $VISUAL (else $EDITOR, fallback vi) [preferably CLI]
  81 .Pp
  82 .Fl E
  83         use $EDITOR for internal undetached edits
  84 .Pp
  85 .Fl f
  86         use readline history file
  87 .Pp
  88 .Fl F
  89         show fortune in help and settings screen
  90 .Pp
  91 .Fl g
  92         use regex filters instead of substring match
  93 .Pp
  94 .Fl H
  95         show hidden files
  96 .Pp
  97 .Fl K
  98         test for keybind collision
  99 .Pp
 100 .Fl "l val"
 101         number of lines to move per mouse wheel scroll
 102 .Pp
 103 .Fl n
 104         start in type-to-nav mode
 105 .Pp
 106 .Fl o
 107         open files only on Enter key
 108 .Pp
 109 .Fl "p file"
 110         copy (or \fIpick\fR) selection to file, or stdout if file='-'
 111 .Pp
 112 .Fl "P key"
 113         specify plugin key to run
 114 .Pp
 115 .Fl Q
 116         disable confirmation on quit with multiple contexts active
 117 .Pp
 118 .Fl r
 119         show cp, mv progress
 120         (Linux-only, needs advcpmv; '^T' shows the progress on BSD/macOS)
 121 .Pp
 122 .Fl R
 123         disable rollover at edges
 124 .Pp
 125 .Fl "s name"
 126         load a session by name
 127 .Pp
 128 .Fl S
 129         persistent session
 130 .Pp
 131 .Fl "t secs"
 132         idle timeout in seconds to lock terminal
 133 .Pp
 134 .Fl "T key"
 135         sort order
 136         keys: 'a'u / 'd'u / 'e'xtension / 'r'everse / 's'ize / 't'ime / 'v'ersion
 137 .Pp
 138 .Fl u
 139         use selection if available, don't prompt to choose between selection and hovered entry
 140 .Pp
 141 .Fl V
 142         show version and exit
 143 .Pp
 144 .Fl x
 145         show notis on selection cp, mv, rm completion
 146         copy path to system clipboard on select
 147 .Pp
 148 .Fl h
 149         show program help and exit
 150 .Sh CONFIGURATION
 151 There is no configuration file. Associated files are at
 152 .Pp
 153 \fB${XDG_CONFIG_HOME:-$HOME/.config}/nnn/\fR
 154 .Pp
 155 Configuration is done using a few optional (set if you need) environment
 156 variables. See ENVIRONMENT section.
 157 .Pp
 158 .Nm
 159 uses \fIxdg-open\fR (on Linux), \fIopen(1)\fR (on macOS), \fIcygstart\fR on
 160 (Cygwin) and \fIopen\fR on (Haiku) as the desktop opener. It's also possible
 161 to specify a custom opener. See ENVIRONMENT section.
 162 .Sh CONTEXTS
 163 Open multiple locations with 4 contexts. The status is shown in the top left
 164 corner:
 165 .Pp
 166 - the current context is in reverse video
 167 .br
 168 - other active contexts are underlined
 169 .br
 170 - rest are inactive
 171 .Pp
 172 A new context copies the state of the previous context. Each context can have
 173 its own color. See ENVIRONMENT section.
 174 .Sh SESSIONS
 175 Sessions are a way to save and restore states of work. A session stores the
 176 settings and contexts.
 177 .Pp
 178 Sessions can be loaded dynamically at runtime or with a program option.
 179 .Pp
 180 When a session is loaded dynamically, the last working session is saved
 181 automatically to a dedicated -- "last session" -- session file. The "last
 182 session" is also used in persistent session mode.
 183 .Pp
 184 All the session files are located by session name in the directory
 185 .Pp
 186 \fB${XDG_CONFIG_HOME:-$HOME/.config}/nnn/sessions\fR
 187 .Pp
 188 "@" is the "last session" file.
 189 .Sh FILTERS
 190 Filters are strings (or regex patterns) to find matching entries in the current
 191 directory instantly (\fIsearch-as-you-type\fR). Matches are case-insensitive by
 192 default. The last filter in each context is persisted at runtime or in saved
 193 sessions.
 194 .Pp
 195 Special keys at filter prompt:
 196 .Bd -literal
 197 -------- + ---------------------------------------
 198   Key    |                Function
 199 -------- + ---------------------------------------
 200  ^char   | Usual keybind functionality
 201  Esc     | Exit filter prompt but skip dir refresh
 202  Alt+Esc | Exit filter prompt and refresh dir
 203 -------- + ---------------------------------------
 204 .Ed
 205 .Pp
 206 Special keys at \fBempty filter prompt\fR:
 207 .Bd -literal
 208 ------ + ---------------------------------------
 209   Key  |                Function
 210 ------ + ---------------------------------------
 211    ?   | Show help and config screen
 212    /   | Toggle between string and regex
 213    :   | Toggle case-sensitivity
 214   ^L   | Clear filter (\fIif prompt is non-empty\fR)
 215        | OR apply last filter
 216 ------ + ---------------------------------------
 217 .Ed
 218 .Pp
 219 Additional special keys at \fBempty filter prompt\fR
 220 in \fBtype-to-nav\fR mode:
 221 .Bd -literal
 222 ------ + ------------------------
 223   Key  |         Function
 224 ------ + ------------------------
 225    '   | Go to first non-dir file
 226    +   | Toggle auto-advance
 227    ,   | Mark CWD
 228    -   | Go to last visited dir
 229    .   | Show hidden files
 230    ;   | Run a plugin by its key
 231    =   | Launch a GUI application
 232    >   | Export file list
 233    @   | Visit start dir
 234    ]   | Show command prompt
 235    `   | Visit /
 236    ~   | Go HOME
 237 ------ + ------------------------
 238 .Ed
 239 .Pp
 240 Common regex use cases:
 241 .Pp
 242 (1) To list all matches starting with the filter expression,
 243     start the expression with a '^' (caret) symbol.
 244 .br
 245 (2) Type '\\.mkv' to list all MKV files.
 246 .br
 247 (3) Use '.*' to match any character (\fIsort of\fR fuzzy search).
 248 .br
 249 (4) Exclude filenames having 'nnn' (compiled with PCRE lib): '^(?!nnn)'
 250 .Pp
 251 In the \fItype-to-nav\fR mode directories are opened in filter
 252 mode, allowing continuous navigation.
 253 .br
 254 When there's a unique match and it's a directory,
 255 .Nm
 256 auto selects the directory and enters it in this mode. Use the relevant
 257 program option to disable this behaviour.
 258 .Sh SELECTION
 259 .Nm
 260 allows file selection across directories and contexts!
 261 .Pp
 262 There are 3 groups of keybinds to add files to selection:
 263 .Pp
 264 (1) hovered file selection toggle
 265     - deselects if '+' is visible before the entry, else adds to selection
 266 .br
 267 (2) add a range of files to selection
 268     - repeat the range key on the same entry twice to clear selection completely
 269 .br
 270 (3) add all files in the current directory to selection
 271 .Pp
 272 A selection can be edited, copied, moved, removed, archived or linked.
 273 .Pp
 274 Absolute paths of the selected files are copied to \fB.selection\fR file in
 275 the config directory. The selection file is shared between multiple program
 276 instances. The most recent instance writing to the file overwrites the entries
 277 from earlier writes. If you have 2 instances if
 278 .Nm
 279 \fIopen\fR in 2 panes of a terminal multiplexer, you can select in one pane and
 280 use the selection (e.g. to copy or move) in the other pane (if the instance
 281 doesn't have any local selection already).
 282 .Pp
 283 .Nm
 284 clears the selection after file removal, batch-rename and link creation with
 285 selection. However, it is retained after archive creation with selection as
 286 the user may want to delete the archived files next.
 287 .Pp
 288 To edit the selection use the _edit selection_ key. Use this key to remove a
 289 file from selection after you navigate away from its directory. Editing doesn't
 290 end the selection mode. You can add more files to the selection and edit the
 291 list again. If no file is selected in the current session, this option attempts
 292 to list the selection file.
 293 .Sh FIND AND LIST
 294 There are two ways to search and list:
 295 .Pp
 296 - feed a list of file paths as input
 297 .br
 298 - search using a plugin (e.g. \fIfinder\fR) and list the results
 299 .Pp
 300 File paths must be NUL-separated ('\\0'). Paths and can be relative to the
 301 current directory or absolute. Invalid paths in the input are ignored. Input
 302 limit is 65,536 paths or 256 MiB of data.
 303 .Pp
 304 To list the input stream, start
 305 .Nm
 306 by writing to its standard input. E.g., to list files in current
 307 directory larger than
 308 1M:
 309 .Bd -literal
 310     find -maxdepth 1 -size +1M -print0 | nnn
 311 .Ed
 312 .Pp
 313 or redirect a list from a file:
 314 .Bd -literal
 315     nnn < files.txt
 316 .Ed
 317 .Pp
 318 Handy bash/zsh shell function to list files by mime-type in current directory:
 319 .Bd -literal
 320     # to show video files, run: list video
 321
 322     list ()
 323     {
 324         find . -maxdepth 1 | file -if- | grep "$1" | awk -F: '{printf "%s\0", $1}' | nnn
 325     }
 326 .Ed
 327 .Pp
 328 A temporary directory will be created containing symlinks to the given
 329 paths. Any action performed on these symlinks will be performed only on their
 330 targets, after which they might become invalid.
 331 .Pp
 332 Right arrow or 'l' on a symlink in the listing dir takes to the target file.
 333 Press '-' to return to the listing dir. Press 'Enter' to open the symlink.
 334 .Sh UNITS
 335 The minimum file size unit is byte (B). The rest are K, M, G, T, P, E, Z, Y
 336 (powers of 1024), same as the default units in \fIls\fR.
 337 .Sh ENVIRONMENT
 338 The SHELL, EDITOR (VISUAL, if defined) and PAGER environment variables are
 339 used. A single combination of arguments is supported for SHELL and PAGER.
 340 .Pp
 341 \fBNNN_OPTS:\fR binary options to
 342 .Nm
 343 .Bd -literal
 344     export NNN_OPTS="cEnrx"
 345 .Ed
 346 .Pp
 347 \fBNNN_OPENER:\fR specify a custom file opener.
 348 .Bd -literal
 349     export NNN_OPENER=nuke
 350
 351     NOTE: 'nuke' is a file opener available in the plugin repository.
 352 .Ed
 353 .Pp
 354 \fBNNN_BMS:\fR bookmark string as \fIkey_char:location\fR pairs
 355 separated by \fI;\fR:
 356 .Bd -literal
 357     export NNN_BMS='d:~/Documents;u:/home/user/Cam Uploads;D:~/Downloads/'
 358 .Ed
 359 .Pp
 360 \fBNNN_PLUG:\fR directly executable plugins as \fIkey_char:plugin\fR pairs
 361 separated by \fI;\fR:
 362 .Bd -literal
 363     export NNN_PLUG='f:finder;o:fzopen;p:mocplay;d:diffs;t:nmount;v:imgview'
 364
 365     NOTES:
 366     1. To run a plugin directly, press \fI;\fR followed by the key.
 367     2. Alternatively, combine with \fIAlt\fR (i.e. \fIAlt+key\fR).
 368     3. To skip directory refresh after running a plugin, prefix with \fB-\fR.
 369
 370     export NNN_PLUG='m:-mediainf'
 371 .Ed
 372 .Pp
 373     To assign keys to arbitrary non-background non-shell-interpreted cli
 374     commands and invoke like plugins, add \fI_\fR (underscore) before the
 375     command.
 376 .Bd -literal
 377     export NNN_PLUG='x:_chmod +x $nnn;g:_git log;s:_smplayer $nnn'
 378
 379     NOTES:
 380     1. Use single quotes for $NNN_PLUG so $nnn is not interpreted
 381     2. $nnn should be the last argument (IF used)
 382     3. (Again) add \fB_\fR before the command
 383     4. To disable directory refresh after running a \fIcommand as plugin\fR,
 384        prefix with \fB-_\fR
 385     5. To skip user confirmation after command execution, suffix with \fB*\fR
 386        Note: Do not use \fB*\fR with programs those run and exit e.g. cat
 387
 388     export NNN_PLUG='y:-_sync*'
 389
 390     6. To run a \fIGUI app as plugin\fR, add a \fB|\fR after \fB_\fR
 391
 392     export NNN_PLUG='m:-_|mousepad $nnn'
 393
 394     EXAMPLES:
 395     ----------------------------------- + -------------------------------------------------
 396                 Key:Command             |                   Description
 397     ----------------------------------- + -------------------------------------------------
 398     g:-_git diff                        | Show git diff
 399     k:-_fuser -kiv $nnn*                | Interactively kill process(es) using hovered file
 400     l:-_git log                         | Show git log
 401     n:-_vi /home/user/Dropbox/dir/note* | Take quick notes in a synced file/dir of notes
 402     p:-_less -iR $nnn*                  | Page through hovered file in less
 403     s:-_|smplayer -minigui $nnn         | Play hovered media file, even unfinished download
 404     x:_chmod +x $nnn                    | Make the hovered file executable
 405     y:-_sync*                           | Flush cached writes
 406     ----------------------------------- + -------------------------------------------------
 407 .Ed
 408 .Pp
 409 \fBNNN_COLORS:\fR string of color codes for each context, e.g.:
 410 .Bd -literal
 411     export NNN_COLORS='1234'
 412
 413     codes: 0-black, 1-red, 2-green, 3-yellow, 4-blue (default), 5-magenta, 6-cyan, 7-white
 414 .Ed
 415 .Pp
 416 \fBNNN_ARCHIVE:\fR archive types to be handled silently (default: bzip2, (g)zip, tar).
 417 .Bd -literal
 418     export NNN_ARCHIVE="\\\\.(7z|bz2|gz|tar|tgz|zip)$"
 419
 420     NOTE: Non-default formats may require a third-party utility.
 421 .Ed
 422 .Pp
 423 \fBNNN_SSHFS:\fR pass additional options to sshfs command:
 424 .Bd -literal
 425     export NNN_SSHFS='sshfs -o reconnect,idmap=user,cache_timeout=3600'
 426
 427     NOTE: The options must be preceded by "sshfs" and comma-separated without any space between them.
 428 .Ed
 429 .Pp
 430 \fBNNN_RCLONE:\fR pass additional options to rclone command:
 431 .Bd -literal
 432     export NNN_RCLONE='rclone mount --read-only --no-checksum'
 433
 434     NOTE: The options must be preceded by "rclone" and max 5 flags are supported.
 435 .Ed
 436 .Pp
 437 \fBNNN_TRASH:\fR trash (instead of \fIdelete\fR) files to desktop Trash.
 438 .Bd -literal
 439     export NNN_TRASH=1
 440 .Ed
 441 .Pp
 442 \fBNNN_SEL:\fR absolute path to custom selection file.
 443 .Pp
 444 \fBNNN_FIFO:\fR path of a named pipe to write the hovered file path:
 445 .Bd -literal
 446     export NNN_FIFO='/tmp/nnn.fifo'
 447
 448     NOTES:
 449     1. Overridden by a temporary path with -a option.
 450     2. If the FIFO file doesn't exist it will be created, but not removed (unless it is generated by -a option).
 451 .Ed
 452 .Pp
 453 \fBNNN_LOCKER:\fR terminal locker program.
 454 .Bd -literal
 455     export NNN_LOCKER='bmon -p wlp1s0'
 456     export NNN_LOCKER='cmatrix'
 457 .Ed
 458 .Pp
 459 \fBNNN_MCLICK:\fR key emulated by a middle mouse click.
 460 .Bd -literal
 461     export NNN_MCLICK='^R'
 462
 463     NOTE: Only the first character is considered if not a \fICtrl+key\fR combo.
 464 .Ed
 465 .Pp
 466 \fBnnn:\fR this is a special variable set to the hovered entry before executing
 467 a command from the command prompt or spawning a shell.
 468 .Pp
 469 \fBNO_COLOR:\fR disable ANSI color output (overridden by \fBNNN_COLORS\fR).
 470 .Sh KNOWN ISSUES
 471 .Nm
 472 may not handle keypresses correctly when used with tmux (see issue #104 for
 473 more details). Set \fBTERM=xterm-256color\fR to address it.
 474 .Sh AUTHORS
 475 .An Arun Prakash Jana Aq Mt engineerarun@gmail.com ,
 476 .An Lazaros Koromilas Aq Mt lostd@2f30.org ,
 477 .An Dimitris Papastamos Aq Mt sin@2f30.org .
 478 .Sh HOME
 479 .Em https://github.com/jarun/nnn