nnn.1 (19287B)
1 .Dd Nov 23, 2021 2 .Dt NNN 1 3 .Os 4 .Sh NAME 5 .Nm nnn 6 .Nd The unorthodox terminal file manager. 7 .Sh SYNOPSIS 8 .Nm 9 .Op Ar -aAcCdDeEfgHJKnQrRSuUVxh 10 .Op Ar -b key 11 .Op Ar -F val 12 .Op Ar -l val 13 .Op Ar -p file 14 .Op Ar -P key 15 .Op Ar -s name 16 .Op Ar -t secs 17 .Op Ar -T key 18 .Op Ar PATH 19 .Sh DESCRIPTION 20 .Nm 21 .Pq Nnn's Not Noice 22 is a performance-optimized, feature-packed fork of noice 23 .Em http://git.2f30.org/noice/ 24 with seamless desktop integration, simplified navigation, 25 .Em type-to-nav 26 mode with dir auto-enter, disk usage analyzer mode, bookmarks, 27 contexts, application launcher, familiar navigation shortcuts, 28 subshell spawning and much more. It remains a simple and 29 efficient file manager that stays out of your way. 30 .Pp 31 .Nm 32 opens the current working directory by default if 33 .Ar PATH 34 is not specified. 35 .Sh KEYBINDS 36 .Pp 37 Press 38 .Ql \&? 39 in 40 .Nm 41 to see the list of keybinds. 42 .Sh OPTIONS 43 .Pp 44 .Nm 45 supports the following options: 46 .Pp 47 .Fl a 48 auto-setup temporary NNN_FIFO (described in ENVIRONMENT section) 49 .Pp 50 .Fl A 51 disable directory auto-enter in type-to-nav mode 52 .Pp 53 .Fl "b key" 54 specify bookmark key to open 55 .Pp 56 .Fl c 57 indicates that the opener is a cli-only opener (overrides -e) 58 .Pp 59 .Fl C 60 8-color scheme - color directories by context, disable file colors 61 .Pp 62 .Fl d 63 detail mode 64 .Pp 65 .Fl D 66 show directories in context color with \fBNNN_FCOLORS\fR set 67 .Pp 68 .Fl e 69 open text files in $VISUAL (else $EDITOR, fallback vi) [preferably CLI] 70 .Pp 71 .Fl E 72 use $EDITOR for internal undetached edits 73 .Pp 74 .Fl f 75 use readline history file 76 .Pp 77 .Fl "F val" 78 fifo notification mode 79 0: notify as previewer, 1: notify as explorer 80 .Pp 81 .Fl g 82 use regex filters instead of substring match 83 .Pp 84 .Fl H 85 show hidden files 86 .Pp 87 .Fl i 88 show current file information in info bar (may be slow) 89 .Pp 90 .Fl J 91 disable auto-proceed on selection 92 (eg. selecting an entry will no longer move cursor to the next entry) 93 .Pp 94 .Fl K 95 test for keybind collision 96 .Pp 97 .Fl "l val" 98 number of lines to move per mouse wheel scroll 99 .Pp 100 .Fl n 101 start in type-to-nav mode 102 .Pp 103 .Fl o 104 open files only on Enter key 105 .Pp 106 .Fl "p file" 107 copy (or \fIpick\fR) selection to file, or stdout if file='-' 108 .Pp 109 .Fl "P key" 110 specify plugin key to run 111 .Pp 112 .Fl Q 113 disable confirmation on quit with multiple contexts active 114 .Pp 115 .Fl r 116 show cp, mv progress 117 (Linux-only, needs \fIadvcpmv\fR; '^T' shows the progress on BSD/macOS) 118 .Pp 119 .Fl R 120 disable rollover at edges (eg. pressing \fIdown\fR while on the last 121 entry will no longer move cursor to the first entry and vice\-versa) 122 .Pp 123 .Fl "s name" 124 load a session by name 125 .Pp 126 .Fl S 127 persistent session 128 .Pp 129 .Fl "t secs" 130 idle timeout in seconds to lock terminal 131 .Pp 132 .Fl "T key" 133 sort order 134 keys: 'a'u / 'd'u / 'e'xtension / 'r'everse / 's'ize / 't'ime / 'v'ersion 135 capitalize to reverse (except 'r') 136 .Pp 137 .Fl u 138 use selection if available, don't prompt to choose between selection and hovered entry 139 .Pp 140 .Fl U 141 show user and group names in status bar 142 .Pp 143 .Fl V 144 show version and exit 145 .Pp 146 .Fl x 147 show notifications on selection cp, mv, rm completion (requires \fI.ntfy\fR plugin) 148 copy path to system clipboard on selection (requires \fI.cbcp\fR plugin) 149 show xterm title (if non-picker mode) 150 .Pp 151 .Fl h 152 show program help and exit 153 .Sh CONFIGURATION 154 There is no configuration file. Associated files are at 155 .Pp 156 .Pa ${XDG_CONFIG_HOME:-$HOME/.config}/nnn/ 157 .Pp 158 Configuration is done using a few optional (set if you need) environment 159 variables. See ENVIRONMENT section. 160 .Pp 161 .Nm 162 uses \fIxdg-open\fR (on Linux), \fIopen(1)\fR (on macOS), \fIcygstart\fR on 163 (Cygwin) and \fIopen\fR on (Haiku) as the desktop opener. It's also possible 164 to specify a custom opener. See ENVIRONMENT section. 165 .Sh CONTEXTS 166 Open multiple locations with 4 contexts. The status is shown in the top left 167 corner: 168 .Pp 169 - the current context is in reverse video 170 .br 171 - other active contexts are underlined 172 .br 173 - rest are inactive 174 .Pp 175 A new context copies the state of the previous context. Each context can have 176 its own color. See ENVIRONMENT section. 177 .Sh SESSIONS 178 Sessions are a way to save and restore states of work. A session stores the 179 settings and contexts. Sessions can be loaded at runtime or with a program 180 option. 181 .Pp 182 - When a session is loaded at runtime, the last working state is saved 183 automatically to a dedicated "auto session" session file. Session option 184 \fIrestore\fR would restore the "auto session". 185 .br 186 - The persistent session option is global. If it is used, the last active session 187 will be updated with the final state at program quit. 188 .br 189 - The "auto session" is used in persistent session mode if no session is active. 190 .br 191 - Listing input stream and opening a bookmark by key have a higher priority to 192 session options (-s/-S). 193 .Pp 194 All the session files are located by session name in the directory 195 .Pp 196 \fB${XDG_CONFIG_HOME:-$HOME/.config}/nnn/sessions\fR 197 .Pp 198 "@" is the "auto session" file. 199 .Sh FILTERS 200 Filters are strings (or regex patterns) to find matching entries in the current 201 directory instantly (\fIsearch-as-you-type\fR). Matches are case-insensitive by 202 default. The last filter in each context is persisted at runtime or in saved 203 sessions. 204 .Pp 205 Special keys at filter prompt: 206 .Bd -literal 207 -------- + --------------------------------------- 208 Key | Function 209 -------- + --------------------------------------- 210 ^char | Usual keybind functionality 211 Esc | Exit filter prompt but skip dir refresh 212 Alt+Esc | Exit filter prompt and refresh dir 213 -------- + --------------------------------------- 214 .Ed 215 .Pp 216 Special keys at \fBempty filter prompt\fR: 217 .Bd -literal 218 ------ + --------------------------------------- 219 Key | Function 220 ------ + --------------------------------------- 221 ? | Show help and config screen 222 / | Toggle between string and regex 223 : | Toggle case-sensitivity 224 ^L | Clear filter (\fIif prompt is non-empty\fR) 225 | OR apply last filter 226 Bksp | Stay at filter prompt and refresh dir 227 Del | Stay at filter prompt and refresh dir 228 ------ + --------------------------------------- 229 .Ed 230 .Pp 231 Additional special keys at \fBempty filter prompt\fR 232 in \fBtype-to-nav\fR mode: 233 .Bd -literal 234 ------ + ------------------------ 235 Key | Function 236 ------ + ------------------------ 237 ' | Go to first non-dir file 238 + | Toggle auto-proceed on open 239 , | Mark CWD 240 - | Go to last visited dir 241 . | Show hidden files 242 ; | Run a plugin by its key 243 = | Launch a GUI application 244 > | Export file list 245 @ | Visit start dir 246 ] | Show command prompt 247 ` | Visit / 248 ~ | Go HOME 249 ------ + ------------------------ 250 .Ed 251 .Pp 252 Common regex use cases: 253 .Pp 254 (1) To list all matches starting with the filter expression, 255 start the expression with a '^' (caret) symbol. 256 .br 257 (2) Type '\\.mkv' to list all MKV files. 258 .br 259 (3) Use '.*' to match any character (\fIsort of\fR fuzzy search). 260 .br 261 (4) Exclude filenames having 'nnn' (compiled with PCRE lib): '^(?!nnn)' 262 .Pp 263 In the \fItype-to-nav\fR mode directories are opened in filter 264 mode, allowing continuous navigation. 265 .br 266 When there's a unique match and it's a directory, 267 .Nm 268 auto enters it in this mode. Use the relevant program option to disable this 269 behaviour. 270 .Sh SELECTION 271 .Nm 272 allows file selection across directories and contexts! 273 .Pp 274 There are 3 groups of keybinds to add files to selection: 275 .Pp 276 (1) hovered file selection toggle 277 - deselects if '+' is visible before the entry, else adds to selection 278 .br 279 (2) add a range of files to selection 280 - repeat the range key on the same entry twice to clear selection completely 281 .br 282 (3) add all files in the current directory to selection 283 .Pp 284 A selection can be edited, copied, moved, removed, archived or linked. 285 .Pp 286 Absolute paths of the selected files are copied to \fB.selection\fR file in 287 the config directory. The selection file is shared between multiple program 288 instances. Selection from multiple instances are not merged. The last instance 289 writing to the file overwrites earlier contents. If you have 2 instances of 290 .Nm 291 \fIopen\fR in 2 panes of a terminal multiplexer, you can select in one pane and 292 use the selection in the other pane. The selection gets cleared in the 293 .Nm 294 instance where the selection was made on mv/rm (but not on cp). 295 .Pp 296 .Nm 297 clears the selection after a successful operation with the selection. Plugins 298 are allowed to define the behaviour individually. 299 .Pp 300 To edit the selection use the _edit selection_ key. Editing doesn't end the 301 selection mode. You can add more files to the selection and edit the list 302 again. If no file is selected in the current session, this option attempts 303 to list the selection file. 304 .Sh FIND AND LIST 305 There are two ways to search and list: 306 .Pp 307 - feed a list of file paths as input 308 .br 309 - search using a plugin (e.g. \fIfinder\fR) and list the results 310 .Pp 311 File paths must be NUL-separated ('\\0'). Paths and can be relative to the 312 current directory or absolute. Invalid paths in the input are ignored. Input 313 limit is 65,536 paths or 256 MiB of data. 314 .Pp 315 To list the input stream, start 316 .Nm 317 by writing to its standard input. E.g., to list files in current 318 directory larger than 319 1M: 320 .Bd -literal 321 find -maxdepth 1 -size +1M -print0 | nnn 322 .Ed 323 .Pp 324 or redirect a list from a file: 325 .Bd -literal 326 nnn < files.txt 327 .Ed 328 .Pp 329 Handy bash/zsh shell function to list files by mime-type in current directory: 330 .Bd -literal 331 # to show video files, run: list video 332 333 list () 334 { 335 find . -maxdepth 1 | file -if- | grep "$1" | awk -F: '{printf "%s\0", $1}' | nnn 336 } 337 .Ed 338 .Pp 339 A temporary directory will be created containing symlinks to the given 340 paths. Any action performed on these symlinks will be performed only on their 341 targets, after which they might become invalid. 342 .Pp 343 Right arrow or 'l' on a symlink in the listing dir takes to the target 344 file. Press '-' to return to the listing dir. Press 'Enter' to open the symlink. 345 .Pp 346 Listing input stream can be scripted. It can be extended to pick (option -p) 347 selected entries from the listed results. 348 .Sh BOOKMARKS 349 There are 2 ways (can be used together) to manage bookmarks. 350 .Pp 351 (1) Bookmark keys: See \fINNN_BMS\fR under \fIENVIORNMENT\fR section on how to 352 set bookmark keys. 353 .Pp 354 (2) Symlinked bookmarks: Symlinked bookmarks can be created at runtime 355 with the \fIB\fR key. They can also be manually created by adding symlinks 356 to bookmarked locations under the bookmarks directory in the nnn config 357 directory (~/.config/nnn/bookmarks). 358 .Pp 359 Pressing \fIb\fR will list all the bookmark keys set in NNN_BMS. Pressing 360 \fIEnter\fR at this prompt will take to the symlink bookmark directory, if 361 NNN_BMS is not set, it happens directly on bookmarks key. 362 .Sh UNITS 363 The minimum file size unit is byte (B). The rest are K, M, G, T, P, E, Z, Y 364 (powers of 1024), same as the default units in \fIls\fR. 365 .Sh ENVIRONMENT 366 The SHELL, VISUAL (else EDITOR) and PAGER environment variables are 367 used. A single combination of arguments is supported for SHELL and PAGER. 368 .Pp 369 \fBNNN_OPTS:\fR binary options to 370 .Nm 371 .Bd -literal 372 export NNN_OPTS="cEnrx" 373 .Ed 374 .Pp 375 \fBNNN_OPENER:\fR specify a custom file opener. 376 .Bd -literal 377 export NNN_OPENER=nuke 378 379 NOTE: 'nuke' is a file opener available in the plugin repository. 380 .Ed 381 .Pp 382 \fBNNN_BMS:\fR bookmark string as \fIkey_char:location\fR pairs 383 separated by \fI;\fR: 384 .Bd -literal 385 export NNN_BMS="d:$HOME/Docs;u:/home/user/Cam Uploads;D:$HOME/Downloads/" 386 .Ed 387 .Pp 388 These bookmarks are listed in the help and config screen (key ?). 389 .Pp 390 \fBNNN_PLUG:\fR directly executable plugins as \fIkey_char:plugin\fR pairs 391 separated by \fI;\fR: 392 .Bd -literal 393 export NNN_PLUG='f:finder;o:fzopen;p:mocplay;d:diffs;t:nmount;v:imgview' 394 395 NOTES: 396 1. To run a plugin directly, press \fI;\fR followed by the key. 397 2. Alternatively, combine with \fIAlt\fR (i.e. \fIAlt+key\fR). 398 3. To skip directory refresh after running a plugin, prefix with \fB-\fR. 399 400 export NNN_PLUG='p:-plugin' 401 .Ed 402 .Pp 403 To assign keys to arbitrary non-background cli commands and invoke like 404 plugins, add \fI!\fR before the command. 405 .Bd -literal 406 export NNN_PLUG='x:!chmod +x $nnn;g:!git log;s:!smplayer $nnn' 407 408 To pick and run an unassigned plugin, press \fBEnter\fR at the plugin prompt. 409 To run a plugin at startup, use the option `-P` followed by the plugin key. 410 411 NOTES: 412 1. Use single quotes for $NNN_PLUG so $nnn is not interpreted 413 2. (Again) add \fB!\fR before the command 414 3. To disable directory refresh after running a \fIcommand as plugin\fR, 415 prefix with \fB-!\fR 416 4. To skip user confirmation after command execution, suffix with \fB*\fR 417 Note: Do not use \fB*\fR with programs those run and exit e.g. cat 418 419 export NNN_PLUG='y:-!sync*' 420 421 5. To run a \fIGUI app as plugin\fR, add a \fB&\fR after \fB!\fR 422 Note: \fI$nnn\fR must be the last argument in this case. 423 424 export NNN_PLUG='m:-!&mousepad $nnn' 425 426 6. To show the output of run-and-exit commands which do not need user input, 427 add \fB|\fR (pipe) after \fB!\fR 428 Note: This option is incompatible with \fB&\fR (terminal output is masked 429 for GUI programs) and ignores \fB*\fR (output is already paged for user) 430 431 export NNN_PLUG='m:-!|mediainfo $nnn;t:-!|tree -ps;l:-!|ls -lah --group-directories-first' 432 433 EXAMPLES: 434 ------------------------------------ + ------------------------------------------------- 435 Key:Command | Description 436 ------------------------------------ + ------------------------------------------------- 437 c:!convert $nnn png:- | xclip -sel \ | Copy image to clipboard 438 clipboard -t image/png* | 439 e:-!sudo -E vim $nnn* | Edit file as root in vim 440 g:-!git diff | Show git diff 441 h:-!hx $nnn* | Open hovered file in hx hex editor 442 k:-!fuser -kiv $nnn* | Interactively kill process(es) using hovered file 443 l:-!git log | Show git log 444 n:-!vi /home/user/Dropbox/dir/note* | Take quick notes in a synced file/dir of notes 445 p:-!less -iR $nnn* | Page through hovered file in less 446 s:-!&smplayer -minigui $nnn | Play hovered media file, even unfinished download 447 x:!chmod +x $nnn | Make the hovered file executable 448 y:-!sync* | Flush cached writes 449 ------------------------------------ + ------------------------------------------------- 450 451 Online docs: https://github.com/jarun/nnn/tree/master/plugins 452 .Ed 453 .Pp 454 \fBNNN_ORDER:\fR directory-specific sort key. 455 .Bd -literal 456 export NNN_ORDER='t:/home/user/Downloads;S:/tmp' 457 458 NOTE: Sort keys can be a/d/e/r/s/t/v (see program option -T). 459 Capitalize to reverse (except 'r'). 460 Path must be absolute. 461 .Ed 462 .Pp 463 \fBNNN_COLORS:\fR string of color numbers for each context, e.g.: 464 .Bd -literal 465 # 8 color numbers: 466 # 0-black, 1-red, 2-green, 3-yellow, 4-blue (default), 5-magenta, 6-cyan, 7-white 467 export NNN_COLORS='1234' 468 469 # xterm 256 color numbers (converted to hex, 2 symbols per context): 470 # see https://user-images.githubusercontent.com/1482942/93023823-46a6ba80-f5e1-11ea-9ea3-6a3c757704f4.png 471 export NNN_COLORS='#0a1b2c3d' 472 473 # both (256 followed by 8 as fallback, separated by ';') 474 export NNN_COLORS='#0a1b2c3d;1234' 475 476 NOTE: If only 256 colors are specified and the terminal doesn't support, default is used. 477 .Ed 478 .Pp 479 \fBNNN_FCOLORS:\fR specify file-type specific colors: 480 .Bd -literal 481 export NNN_FCOLORS='c1e2272e006033f7c6d6abc4' 482 483 Specify file-specific colors in xterm 256 color hex numbers (2 symbols per color). 484 Order is strict, use 00 to omit/use default terminal color. Defaults: 485 486 ------------------------- + --- + ------------- 487 Order | Hex | Color 488 ------------------------- + --- + ------------- 489 Block device | c1 | DarkSeaGreen1 490 Char device | e2 | Yellow1 491 Directory | 27 | DeepSkyBlue1 492 Executable | 2e | Green1 493 Regular | 00 | Normal 494 Hard link | 60 | Plum4 495 Symbolic link | 33 | Cyan1 496 Missing OR file details | f7 | Grey62 497 Orphaned symbolic link | c6 | DeepPink1 498 FIFO | d6 | Orange1 499 Socket | ab | MediumOrchid1 500 Unknown OR 0B regular/exe | c4 | Red1 501 ------------------------- + --- + ------------- 502 503 If the terminal supports xterm 256 colors or more, file-specific colors will be rendered. 504 To force the 8-color scheme use option -C. 505 If xterm 256 colors aren't supported, 8-color scheme will be used. 506 .Ed 507 .Pp 508 \fBNNN_ARCHIVE:\fR archive extensions to be handled silently (default: bzip2, (g)zip, tar). 509 .Bd -literal 510 export NNN_ARCHIVE="\\\\.(7z|bz2|gz|tar|tgz|zip)$" 511 512 NOTE: Non-default formats may require a third-party utility. 513 .Ed 514 .Pp 515 \fBNNN_SSHFS:\fR specify custom sshfs command with options: 516 .Bd -literal 517 export NNN_SSHFS='sshfs -o reconnect,idmap=user,cache_timeout=3600' 518 519 NOTE: The options must be comma-separated without any space between them. 520 .Ed 521 .Pp 522 \fBNNN_RCLONE:\fR pass additional options to rclone command: 523 .Bd -literal 524 export NNN_RCLONE='rclone mount --read-only --no-checksum' 525 526 NOTE: The options must be preceded by "rclone" and max 5 flags are supported. 527 .Ed 528 .Pp 529 \fBNNN_TRASH:\fR trash (instead of \fIrm -rf\fR) files to desktop Trash. 530 .Bd -literal 531 export NNN_TRASH=n 532 # n=1: trash-cli, n=2: gio trash 533 .Ed 534 .Pp 535 \fBNNN_SEL:\fR absolute path to custom selection file. 536 .Pp 537 \fBNNN_FIFO:\fR path of a named pipe to write the hovered file path: 538 .Bd -literal 539 export NNN_FIFO='/tmp/nnn.fifo' 540 541 NOTES: 542 1. Overridden by a temporary path with -a option. 543 2. If the FIFO file doesn't exist it will be created, 544 but not removed (unless it is generated by -a option). 545 546 Online docs: https://github.com/jarun/nnn/wiki/Live-previews 547 .Ed 548 .Pp 549 \fBNNN_LOCKER:\fR terminal locker program. 550 .Bd -literal 551 export NNN_LOCKER='bmon -p wlp1s0' 552 export NNN_LOCKER='cmatrix' 553 .Ed 554 .Pp 555 \fBNNN_TMPFILE:\fR \fIalways\fR cd on quit and write the command in the file specified. 556 .Bd -literal 557 export NNN_TMPFILE='/tmp/.lastd' 558 .Ed 559 .Pp 560 \fBNNN_HELP:\fR run a program and show the output on top of the program help page. 561 .Bd -literal 562 export NNN_HELP='fortune' 563 .Ed 564 .Pp 565 \fBNNN_MCLICK:\fR key emulated by a middle mouse click. 566 .Bd -literal 567 export NNN_MCLICK='^R' 568 569 NOTE: Only the first character is considered if not a \fICtrl+key\fR combo. 570 .Ed 571 .Pp 572 \fBnnn:\fR this is a special variable. 573 .Bd -literal 574 Set to the hovered file name before starting the command prompt or spawning a shell. 575 .Ed 576 .Pp 577 \fBNO_COLOR:\fR disable ANSI color output (overridden by \fBNNN_COLORS\fR). 578 .Sh AUTHORS 579 .An Arun Prakash Jana Aq Mt engineerarun@gmail.com , 580 .An Lazaros Koromilas Aq Mt lostd@2f30.org , 581 .An Dimitris Papastamos Aq Mt sin@2f30.org . 582 .Sh HOME 583 .Em https://github.com/jarun/nnn