nnn.1

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