nnn.1

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