nnn.1

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