jarun/nnn
1
1
Fork 0
mirror of https://github.com/jarun/nnn.git synced 2024-11-22 06:35:55 +03:00
Code Issues Projects Releases Wiki Activity

Updated Home (markdown)

Mischievous Meerkat 2020-10-18 14:50:15 +05:30
parent 98ffaaa259
commit 38203cbbd4
1 changed files with 76 additions and 257 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

333
Home.md

@ -9,260 +9,79 @@ Welcome to the `nnn` Wiki! It's editable. Feel free to add to the knowledge base
Looking for a list of features or quickstart guide? Visit the [project home](https://github.com/jarun/nnn).
## Contexts
Open multiple locations with 4 contexts. The status is shown in the top left corner:
- the current context is in reverse video
- other active contexts are underlined
- rest are inactive
Cycle contexts using <kbd>Tab</kbd> or <kbd>Shift+Tab</kbd>. A new context copies the state of the previous context.
Use **context-specific colors** (see configuration `NNN_COLORS`) to identify each context easily.
#### Dual pane
<p align="center"><img src="https://i.imgur.com/MPWpmos.png" /></p>
The `nnn` way is to work with multiple contexts using <kbd>Tab</kbd> or <kbd>Shift+Tab</kbd>.
For dual pane, use a terminal multiplexer e.g., to open 2 instances in [`dvtm`](https://github.com/martanne/dvtm), run:
```sh
dvtm n n
```
You can also have an alias:
```sh
alias n2="dvtm n n"
```
or a Bash function (with <kbd>^\\</kbd> as dvtm modifier) to handle arguments:
```sh
n2 ()
{
dvtm -m '^\' "nnn -nr $@" "nnn -nr $@"
}
```
## Sessions
Sessions are a way to save and restore states of work. A session stores the settings and contexts. All the session files are located in the `${XDG_CONFIG_HOME:-$HOME/.config}/nnn/sessions` directory by the session name.
Sessions can be loaded dynamically at runtime or with a [program option](https://github.com/jarun/nnn/wiki/Usage#program-options).
**Note:** When a session is loaded dynamically, the last working session is saved automatically to a dedicated -- "last session" -- session file. The "last session" is also used in persistent session mode.
## Filters
Filters are strings (or regex patterns) to find matching entries in the current directory instantly (_search-as-you-type_). Matches are case-insensitive by default. The last filter in each context is persisted at runtime or in saved sessions.
#### Special keys at filter prompt
| Key | Function |
|:---:| --- |
| <kbd>^char</kbd> | Usual keybind functionality |
| <kbd>Esc</kbd> | Exit filter prompt but skip dir refresh |
| <kbd>Alt+Esc</kbd> | Exit filter prompt and refresh dir (same as <kbd>Esc</kbd><kbd>^L</kbd>) |
Special keys at **_empty filter prompt_**:
| Key | Function |
|:---:| --- |
| <kbd>?</kbd> | Show help and config screen |
| <kbd>/</kbd> | Toggle between string and regex |
| <kbd>:</kbd> | Toggle case-sensitivity |
| <kbd>^L</kbd> | Clear filter (_if prompt is non-empty_)<br>OR apply last filter |
Additional special keys at **_empty filter prompt_** in **_type-to-nav_** mode:
<table>
<tr><th>Listing 1</th><th>Listing 2</th></tr>
<tr><td>
| Key | Function |
|:---:| --- |
| <kbd>'</kbd> | Go to first file/match |
| <kbd>+</kbd> | Toggle auto-advance |
| <kbd>,</kbd> | Mark CWD |
| <kbd>-</kbd> | Go to last visited dir |
| <kbd>.</kbd> | Show hidden files |
| <kbd>;</kbd> | Run a plugin by its key |
</td><td>
| Key | Function |
|:---:| --- |
| <kbd>=</kbd> | Launch a GUI application |
| <kbd>></kbd> | Export file list |
| <kbd>@</kbd> | Visit start dir |
| <kbd>]</kbd> | Show command prompt |
| <kbd>`</kbd> | Visit / |
| <kbd>~</kbd> | Go HOME |
</td></tr> </table>
#### Common regex use cases
- to list all matches starting with the filter expression, start with a `^` (caret)
- type `\.mkv` to list all MKV files
- use `.*` to match any character (_sort of_ fuzzy search)
- exclude filenames having `nnn` ([with PCRE](https://github.com/jarun/nnn/wiki/Developer-guides#compile-with-pcre)): `^(?!nnn)`
#### Limitation
Use regex for case-sensitive filtering with wide chars as the function [`strcasestr`](https://manpages.ubuntu.com/manpages/bionic/en/man3/strcasestr.3.html) (used for string filters) does not work with multibyte locales ([ref1](https://www.gnu.org/software/libunistring/manual/libunistring.html#char-_002a-strings), [ref2](https://www.gnu.org/software/gnulib/manual/html_node/c_002dstrcasestr.html)).
## Type-to-nav
In this mode directories are opened in filter mode, allowing continuous navigation.
When there's a unique match and it's a directory, `nnn` auto selects the directory and enters it in this mode. Program option `-A` disables this.
To start in _type-to-nav_ mode, use the program option `-n` or press <kbd>^N</kbd>.
## Selection
`nnn` allows file selection across directories and contexts!
There are 3 groups of [keybinds](https://github.com/jarun/nnn/wiki/Usage#keyboard-mouse) to add files to selection:
1. hovered file selection toggle
- deselects if `+` is visible before the entry, else adds to selection
2. add a range of files to selection
- repeat the range key on the same entry twice to clear selection completely
3. add all files in the current directory to selection
A selection can be edited, copied, moved, removed, archived or linked. Example workflow to copy or move some files:
- add files from source dirs (you can select files from multiple dirs in `nnn`) to selection
- navigate to a target directory
- use <kbd>^P</kbd> (cp) or <kbd>^V</kbd> (mv) to copy or move the selected files
Absolute paths of the selected files are copied to `.selection` file in the config directory. The selection file is shared between multiple program instances. The most recent instance writing to the file overwrites the entries from earlier writes. If you have 2 instances of `nnn` _open_ in 2 panes of a terminal multiplexer, you can select in one pane and use the selection (e.g. to copy or move) in the other pane (if the instance doesn't have any local selection already).
`nnn` clears the selection after file removal, batch-rename and link creation with selection. However, it is retained after archive creation with selection as the user may want to delete the archived files next.
#### Editing selection
To edit the selection use the _edit selection_ key. Use this key to remove a file from selection after you navigate away from its directory or remove duplicates. Editing doesn't end the selection mode. You can add more files to the selection and edit the list again. If no file is selected in the current session, this option attempts to list the selection file.
#### File paths in selection to system clipboard
Use the program option `-x` to copy selection to the system clipboard. You must have plugins installed.
#### Grab file paths in selection manually
Many plugins use this method. The file paths are `NUL`-terminated, so additional processing is required to make them usable.
To run `ls -l` on the file paths in selection:
```sh
xargs -0 ls -l < "${XDG_CONFIG_HOME:-$HOME/.config}/nnn/.selection"
```
An special variable may be handy:
```sh
export sel=${XDG_CONFIG_HOME:-$HOME/.config}/nnn/.selection
```
so you can easily handle files together (**even at the `nnn` command prompt!**):
```sh
xargs -0 ls -l < $sel // compare 2 selected files
```
**Notes:**
1. The selection file can be directly edited to remove any entries but it's not recommended.
2. If an already selected file doesn't have the `+` symbol before it (say, on a directory refresh or after navigating away and back to the dir), the selection toggle key will add it again.
3. Window managers like i3/sway re-dimensions window and forces redraw when opening a file. So the `+` symbol disappears. To get rid of this use a CLI opener like `nuke`. For example, when opening and renaming files with `nuke`, the images are opened in the terminal in `viu` and there is no window-manager redraw involved. See issue [#464](https://github.com/jarun/nnn/issues/464).
## Find and list
There are two ways to search and list:
- feed a list of file paths as input
- search using a plugin (e.g. `finder`) and list the results
File paths must be NUL-separated ('\0'). Paths can be relative to the current directory or absolute. Invalid paths in the input are ignored. Input limit is 65,536 paths or 256 MiB of data.
To list the input stream, start `nnn` by writing to its standard input. E.g., to list files in current directory larger than 1M:
```sh
find -maxdepth 1 -size +1M -print0 | nnn
# fd -d 2 -S +1M -0 | nnn
```
or redirect a list from a file:
```sh
nnn < files.txt
```
Handy bash/zsh shell function to list files by mime-type in current directory:
```sh
# to show video files, run: list video
list ()
{
find . -maxdepth 1 | file -if- | grep "$1" | awk -F: '{printf "%s\0", $1}' | nnn
# fd -d 1 | file -if- | grep "$1" | awk -F: '{printf "%s\0", $1}' | nnn
}
```
A temporary directory will be created containing symlinks to the given paths. Any action performed on these symlinks will be performed _only_ on their targets, after which they might become invalid.
<kbd>Right</kbd> or <kbd>l</kbd> on a symlink inside the listing dir takes to the target file. Press <kbd>-</kbd> to return to the listing dir. Press <kbd>Enter</kbd> to open the symlink.
## Prompts
The prompts (except the filter prompt) support readline-like command-line shortcuts. <kbd>Enter</kbd> or <kbd>^D</kbd> at the empty prompt (except the filter prompt) exits the prompt.
Key <kbd>^L</kbd> clears and <kbd>Esc</kbd> exits all prompts.
The _run & exit_ command prompt understands environment variables (like `$PWD`). Refer to your shell's documentation (e.g. `BASH_ENV` for bash, `~/.zshenv` for zsh) to use aliases and functions. To fuzzy-select commands from your shell history at the command prompt and issue them after editing (like [fc](http://manpages.ubuntu.com/manpages/bionic/man1/fc.1posix.html)), copy the plugin `fzhist` (as `h` maybe?) in your `$PATH`.
The special variable `$nnn` denotes the hovered file name. It is accessible from the command prompt or a spawned shell.
All binary questions are confirmed by <kbd>y</kbd> or <kbd>Y</kbd>.
## Design
`nnn` (the core C utility) is, generally speaking, _feature-restricted_. It includes features which you _really_ need so it can remain light enough to finish your workflow accurately before your train of thought is lost.
`nnn` supports [plugins](https://github.com/jarun/nnn/tree/master/plugins) to extend its capabilities.
Here's a list of the design principles driving the core `nnn` program:
1. `nnn` complements X, doesn't substitute it
- Brings the best of CLI to a GUI user
- Doesn't expect the user to abandon GUI (the GUI is well-established for a reason)
- Zero-config comfort-zone for GUI users _out of the box_
2. Quick and distraction-free workflows
3. Clean and clutter-free single-window view focused on content
- Easily switch context/tabs with (Sh)TAB
4. Only directories in color, no icons
- To search/group by extension, use filter or sort by extension option
5. Support external or plugin-based previewers by writing the the hovered file path to a custom FIFO.
6. One utility instead of multiple utilities for related tasks e.g.
- file management, batch rename, disk usage analysis, launching apps etc.
7. No configuration file and few environment variables
8. Stay portable - very limited library dependencies
- support compiling out features
9. Use a standard desktop opener to handle file associations
10. Analyze disk usage within the same filesystem, do not follow symbolic links
11. Case-insensitive alphabetic content listing instead of all uppercase first
12. Directories first in all modes (even in disk usage analyzer mode)
13. No navigation restriction with relative paths (let permissions handle it)
14. Directory updates are disabled in the following modes:
- disk usage: re-scans are issued on every change in dir
- filter mode: content refresh is very disruptive in the workflow
15. Limited (4) number of contexts; for more, use another instance
- file paths copy-paste should work seamlessly between contexts and instances of `nnn`
16. Scan each directory on visit (even in disk usage analyzer mode) rather than storing all the information from the first scan. This keeps the information up to date. To compensate, use fast re-scan with highly optimized algorithms.
### Index
##### Concepts
1. [Contexts](https://github.com/jarun/nnn/wiki#contexts)
2. [Sessions](https://github.com/jarun/nnn/wiki#sessions)
3. [Filters](https://github.com/jarun/nnn/wiki#filters)
4. [Type-to-nav](https://github.com/jarun/nnn/wiki#type-to-nav)
5. [Selection](https://github.com/jarun/nnn/wiki#selection)
6. [Find and list](https://github.com/jarun/nnn/wiki#find-and-list)
7. [Prompts](https://github.com/jarun/nnn/wiki#prompts)
8. [Design](https://github.com/jarun/nnn/wiki#design)
##### Get, Set, Go!
1. [Dependencies](https://github.com/jarun/nnn/wiki/Usage#dependencies)
2. [Installation](https://github.com/jarun/nnn/wiki/Usage#installation)
3. [Configuration](https://github.com/jarun/nnn/wiki/Usage#configuration)
4. [Program options](https://github.com/jarun/nnn/wiki/Usage#program-options)
5. [Keyboard, mouse](https://github.com/jarun/nnn/wiki/Usage#keyboard-mouse)
6. [Symbols](https://github.com/jarun/nnn/wiki/Usage#symbols)
7. [File size](https://github.com/jarun/nnn/wiki/Usage#file-size)
8. [Help](https://github.com/jarun/nnn/wiki/Usage#help)
##### How to
1. [Add bookmarks](https://github.com/jarun/nnn/wiki/Basic-use-cases#add-bookmarks)
2. [Configure cd on quit](https://github.com/jarun/nnn/wiki/Basic-use-cases#configure-cd-on-quit)
3. [Hot-plugged drives](https://github.com/jarun/nnn/wiki/Basic-use-cases#hot-plugged-drives)
4. [Image, video, pdf](https://github.com/jarun/nnn/wiki/Basic-use-cases#image-video-pdf)
5. [Detached text](https://github.com/jarun/nnn/wiki/Basic-use-cases#detached-text)
6. [Run commands](https://github.com/jarun/nnn/wiki/Basic-use-cases#run-commands)
7. [Launch applications](https://github.com/jarun/nnn/wiki/Basic-use-cases#launch-applications)
8. [Open as root](https://github.com/jarun/nnn/wiki/Basic-use-cases#open-as-root)
9. [File picker](https://github.com/jarun/nnn/wiki/Basic-use-cases#file-picker)
10. [Remote mounts](https://github.com/jarun/nnn/wiki/Basic-use-cases#remote-mounts)
11. [Synced quick notes](https://github.com/jarun/nnn/wiki/Basic-use-cases#synced-quick-notes)
12. [Drag and drop](https://github.com/jarun/nnn/wiki/Basic-use-cases#drag-and-drop)
13. [Duplicate file](https://github.com/jarun/nnn/wiki/Basic-use-cases#duplicate-file)
14. [Create batch links](https://github.com/jarun/nnn/wiki/Basic-use-cases#create-batch-links)
15. [Hidden files on top](https://github.com/jarun/nnn/wiki/Basic-use-cases#hidden-files-on-top)
16. [Disable bold fonts](https://github.com/jarun/nnn/wiki/Basic-use-cases#disable-bold-fonts)
##### Advanced
1. [Live previews](https://github.com/jarun/nnn/wiki/Live-previews)
2. [File icons](https://github.com/jarun/nnn/wiki/Advanced-use-cases#file-icons)
3. [Custom keybinds](https://github.com/jarun/nnn/wiki/Advanced-use-cases#custom-keybinds)
4. [CLI-only opener](https://github.com/jarun/nnn/wiki/Advanced-use-cases#cli-only-opener)
5. [Desktop integration](https://github.com/jarun/nnn/wiki/Advanced-use-cases#desktop-integration)
6. [cp mv progress](https://github.com/jarun/nnn/wiki/Advanced-use-cases#cp-mv-progress)
7. [Control active dir](https://github.com/jarun/nnn/wiki/Advanced-use-cases#control-active-dir)
8. [Termux tips](https://github.com/jarun/nnn/wiki/Advanced-use-cases#termux-tips)
9. [Pager as opener](https://github.com/jarun/nnn/wiki/Advanced-use-cases#pager-as-opener)
10. [Working with lftp](https://github.com/jarun/nnn/wiki/Advanced-use-cases#working-with-lftp)
11. [Power toys](https://github.com/jarun/nnn/wiki/Power-toys)
##### Troubleshooting
1. [Wrong file opener](https://github.com/jarun/nnn/wiki/Troubleshooting#wrong-file-opener)
2. [Batch rename limits](https://github.com/jarun/nnn/wiki/Troubleshooting#batch-rename-limits)
3. [Tmux configuration](https://github.com/jarun/nnn/wiki/Troubleshooting#tmux-configuration)
4. [Broken control key](https://github.com/jarun/nnn/wiki/Troubleshooting#broken-control-key)
5. [Can't list within list](https://github.com/jarun/nnn/wiki/Troubleshooting#cant-list-within-list)
6. [BSD terminal issue](https://github.com/jarun/nnn/wiki/Troubleshooting#bsd-terminal-issue)
7. [Help not showing](https://github.com/jarun/nnn/wiki/Troubleshooting#help-not-showing)
8. [Amethyst WM](https://github.com/jarun/nnn/wiki/Troubleshooting#amethyst-wm)
##### Stats, info
1. [Performance](https://github.com/jarun/nnn/wiki/Performance)
2. [From noice to nnn](https://github.com/jarun/nnn/wiki/From-noice-to-nnn)
##### Developer
1. [Release checklist](https://github.com/jarun/nnn/wiki/Developer-guides#release-checklist)
2. [Verify sources](https://github.com/jarun/nnn/wiki/Developer-guides#verify-sources)
3. [make options](https://github.com/jarun/nnn/wiki/Developer-guides#make-options)
4. [Static compilation](https://github.com/jarun/nnn/wiki/Developer-guides#static-compilation)
5. [Compile for Pi](https://github.com/jarun/nnn/wiki/Developer-guides#compile-for-pi)
6. [Compile on Cygwin](https://github.com/jarun/nnn/wiki/Developer-guides#compile-on-cygwin)
7. [Cross-compile for Android](https://github.com/jarun/nnn/wiki/Developer-guides#cross-compile-for-android)
8. [Debugging nnn](https://github.com/jarun/nnn/wiki/Developer-guides#debugging-nnn)