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