mirror of https://github.com/sayanarijit/xplr
Publish xplr book with intensive documentation
Closes: https://github.com/sayanarijit/xplr/issues/263pull/270/head
Arijit Basu
3 years ago
committed by
Arijit Basu
parent
b61bf9dcf2
commit
3e646b063b
@ -0,0 +1,33 @@
|
||||
name: Book
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- master
|
||||
paths:
|
||||
- 'docs/**'
|
||||
|
||||
jobs:
|
||||
deploy_en:
|
||||
name: Deploy book on gh-pages
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v2
|
||||
- name: Install mdBook
|
||||
uses: peaceiris/actions-mdbook@v1
|
||||
- name: Render book
|
||||
run: |
|
||||
mdbook build -d gh-pages docs/en
|
||||
mkdir gh-pages
|
||||
mv docs/en/gh-pages gh-pages/en
|
||||
mv docs/index.html gh-pages
|
||||
- name: Deploy
|
||||
uses: peaceiris/actions-gh-pages@v2.5.1
|
||||
with:
|
||||
emptyCommits: true
|
||||
keepFiles: false
|
||||
env:
|
||||
ACTIONS_DEPLOY_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }}
|
||||
PUBLISH_BRANCH: gh-pages
|
||||
PUBLISH_DIR: gh-pages
|
||||
@ -0,0 +1,6 @@
|
||||
[book]
|
||||
authors = ["Arijit Basu <sayanarijit@gmail.com>"]
|
||||
title = "xplr book"
|
||||
description = "A hackable, minimal, fast TUI file explorer"
|
||||
src = "src"
|
||||
language = "en"
|
||||
@ -0,0 +1,19 @@
|
||||
A hackable, minimal, fast TUI file explorer
|
||||
===========================================
|
||||
|
||||
- [Introduction](introduction.md)
|
||||
- [Quickstart](quickstart.md)
|
||||
- [Install](install.md)
|
||||
- [Post Install](post-install.md)
|
||||
- [Configuration](configuration.md)
|
||||
- [General Config](general-config.md)
|
||||
- [Modes](modes.md)
|
||||
- [Message](message.md)
|
||||
- [Layouts](layouts.md)
|
||||
- [Style](style.md)
|
||||
- [Default Key Bindings](default-key-bindings.md)
|
||||
- [TODO](todo.md)
|
||||
- [Alternatives](alternatives.md)
|
||||
- [Upgrade Guide](upgrade-guide.md)
|
||||
- [Community](community.md)
|
||||
- [Contribute](contribute.md)
|
||||
@ -0,0 +1,19 @@
|
||||
Alternatives
|
||||
============
|
||||
|
||||
These are the alternative TUI/CLI file managers/explorers you might want to check out (in no particular order).
|
||||
|
||||
- [nnn](https://github.com/jarun/nnn/)
|
||||
- [vifm](https://github.com/vifm/vifm)
|
||||
- [ranger](https://github.com/ranger/ranger)
|
||||
- [lf](https://github.com/gokcehan/lf)
|
||||
- [joshuto](https://github.com/kamiyaa/joshuto)
|
||||
- [fff](https://github.com/dylanaraps/fff)
|
||||
- [mc](https://github.com/MidnightCommander/mc)
|
||||
- [broot](https://github.com/Canop/broot)
|
||||
- [hunter](https://github.com/rabite0/hunter)
|
||||
- [noice](https://github.com/RichardHyde/noice)
|
||||
- [clifm](https://github.com/pasqu4le/clifm)
|
||||
- [clifm](https://github.com/leo-arch/clifm) (non curses)
|
||||
|
||||
[add more](community.md)
|
||||
@ -0,0 +1,11 @@
|
||||
Community
|
||||
=========
|
||||
|
||||
Building an active community of awesome people and learning stuff together is
|
||||
one of my reasons to publish this tool and maintain it. Hence, please feel free
|
||||
to reach out via your preferred way.
|
||||
|
||||
- Real-time chat lovers can [**join our discord channel**](https://discord.gg/JmasSPCcz3).
|
||||
- Forum discussion veterans can [**start a new GitHub discussion**](https://github.com/sayanarijit/xplr/discussions).
|
||||
|
||||
BTW I like Miyazaki and Shinkai works.
|
||||
@ -0,0 +1,27 @@
|
||||
Configuration
|
||||
=============
|
||||
|
||||
xplr can be configured using [Lua](https://www.lua.org/) via a special file
|
||||
named `init.lua`
|
||||
([example](https://github.com/sayanarijit/xplr/blob/main/src/init.lua)), which
|
||||
can be placed in `~/.config/xplr/` (user specific) or `/etc/xplr/` (global)
|
||||
depending on the use case.
|
||||
|
||||
When a user specific configuration is available, the global configuration file
|
||||
will be ignored.
|
||||
|
||||
However, it's also possible to place the file anywhere, with any name and use
|
||||
the command-line argument `-c` / `--config` to specify its path explicitely. In
|
||||
that case, both `~/.config/xplr/init.lua` and `/etc/xplr/init.lua` will be
|
||||
ignored.
|
||||
|
||||
|
||||
Loading Order
|
||||
-------------
|
||||
|
||||
When xplr loads, it first executes the built-in
|
||||
[init.lua](https://github.com/sayanarijit/xplr/blob/main/src/init.lua) to set
|
||||
the default values. It is then overwritten by another config file, if found
|
||||
using the following lookup order:
|
||||
|
||||
**--config /path/to/init.lua** > **~/.config/xplr/init.lua** > **/etc/xplr/init.lua**
|
||||
@ -0,0 +1,34 @@
|
||||
|
||||
|
||||
Create the customizable config file
|
||||
-----------------------------------
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.config/xplr
|
||||
|
||||
version="$(xplr | grep ^version: | cut -d' ' -f 2)"
|
||||
|
||||
# When the app loads, press `#`
|
||||
|
||||
echo version = '"'${version:?}'"' > ~/.config/xplr/init.lua
|
||||
```
|
||||
|
||||
Then
|
||||
**[copy from here](https://github.com/sayanarijit/xplr/blob/main/src/init.lua)**
|
||||
and remove / comment out what you don't want to customize.
|
||||
|
||||
> **Note:** You don't generally need to create the config file. You can use the
|
||||
> default configuration for basic operations. However, creating the config file
|
||||
> is recommended because the project is in its early stage and the defaults
|
||||
> might change. Creating the config file will save you from unexpected behavior
|
||||
> when you [upgrade](upgrade-guide.md).
|
||||
> Also, the default configuration is very minimal (just enough to get you
|
||||
> started) and you'll probably want to adjust it to suit your workflow.
|
||||
|
||||
|
||||
Run
|
||||
---
|
||||
|
||||
```
|
||||
xplr
|
||||
```
|
||||
@ -0,0 +1,19 @@
|
||||
If you like xplr, and want to contribute, that would be really awesome.
|
||||
|
||||
You can contribute to this project in the following ways
|
||||
|
||||
- Contribute your time and expertise (read [CONTRIBUTING.md](https://github.com/sayanarijit/xplr/blob/main/CONTRIBUTING.md) for instructions).
|
||||
- **Developers:** You can help me improve my code, fix things, implement features etc.
|
||||
- **Repository maintainers:** You can save the users from the pain of managing xplr in their system manually.
|
||||
- **Code Reviewers:** Teach me your ways of code.
|
||||
- **Designers:** You can make the logo even more awesome, donate stickers and blog post worthy pictures.
|
||||
- **Bloggers, YouTubers & broadcasters:** You can help spread the word.
|
||||
|
||||
|
||||
- Contribute by donating.
|
||||
- You can [fuel me with coins of encouragement](https://opencollective.com/xplr) or [buy me a coffee](https://ko-fi.com/sayanarijit).
|
||||
|
||||
For further queries or concern related to `xplr`, [just ask us](community.md).
|
||||
|
||||
### Backers
|
||||
<a href="https://opencollective.com/xplr#backer"><img src="https://opencollective.com/xplr/tiers/backer.svg?width=890" /></a>
|
||||
@ -0,0 +1,258 @@
|
||||
Default Key Bindings
|
||||
====================
|
||||
|
||||
The default key binding is inspired by [vim](https://www.vim.org/) and slightly
|
||||
overlaps with [nnn](https://github.com/jarun/nnn/), but it's supposed to be
|
||||
customized as per user requirements.
|
||||
|
||||
When you press `?` in [default mode](#default), you can see the complete list
|
||||
of [modes](modes.md) and the key mappings for each mode.
|
||||
|
||||
|
||||
### default
|
||||
|
||||
key | remaps | action
|
||||
--------------- | ------------------------- | ------
|
||||
. | | show hidden
|
||||
/ | ctrl-f | search
|
||||
: | | action
|
||||
? | | global help menu
|
||||
G | | go to bottom
|
||||
V | ctrl-a | select/unselect all
|
||||
ctrl-c | | terminate
|
||||
ctrl-i | tab | next visited path
|
||||
ctrl-o | | last visited path
|
||||
ctrl-r | | refresh screen
|
||||
ctrl-u | | clear selection
|
||||
ctrl-w | | switch layout
|
||||
d | | delete
|
||||
down | j | down
|
||||
enter | | quit with result
|
||||
f | | filter
|
||||
g | | go to
|
||||
h | left | back
|
||||
k | up | up
|
||||
l | right | enter
|
||||
q | | quit
|
||||
r | | rename
|
||||
s | | sort
|
||||
space | v | toggle selection
|
||||
~ | | go home
|
||||
[0-9] | | input
|
||||
|
||||
|
||||
### recover
|
||||
|
||||
key | remaps | action
|
||||
--------------- | ------------------------- | ------
|
||||
ctrl-c | | terminate
|
||||
esc | | escape
|
||||
|
||||
|
||||
### filter
|
||||
|
||||
key | remaps | action
|
||||
--------------- | ------------------------- | ------
|
||||
R | | relative does not contain
|
||||
backspace | | remove last filter
|
||||
ctrl-c | | terminate
|
||||
ctrl-r | | reset filters
|
||||
ctrl-u | | clear filters
|
||||
enter | esc | done
|
||||
r | | relative does contain
|
||||
|
||||
|
||||
### number
|
||||
|
||||
key | remaps | action
|
||||
--------------- | ------------------------- | ------
|
||||
backspace | | remove last character
|
||||
ctrl-c | | terminate
|
||||
ctrl-u | | remove line
|
||||
ctrl-w | | remove last word
|
||||
down | j | to down
|
||||
enter | | to index
|
||||
esc | | cancel
|
||||
k | up | to up
|
||||
[0-9] | | input
|
||||
|
||||
|
||||
### go to
|
||||
|
||||
key | remaps | action
|
||||
--------------- | ------------------------- | ------
|
||||
ctrl-c | | terminate
|
||||
esc | | cancel
|
||||
f | | follow symlink
|
||||
g | | top
|
||||
x | | open in gui
|
||||
|
||||
|
||||
### search
|
||||
|
||||
key | remaps | action
|
||||
--------------- | ------------------------- | ------
|
||||
backspace | | remove last character
|
||||
ctrl-c | | terminate
|
||||
ctrl-n | down | down
|
||||
ctrl-p | up | up
|
||||
ctrl-u | | remove line
|
||||
ctrl-w | | remove last word
|
||||
enter | esc | focus
|
||||
left | | back
|
||||
right | | enter
|
||||
tab | | toggle selection
|
||||
|
||||
|
||||
### selection ops
|
||||
|
||||
key | remaps | action
|
||||
--------------- | ------------------------- | ------
|
||||
c | | copy here
|
||||
ctrl-c | | terminate
|
||||
esc | | cancel
|
||||
m | | move here
|
||||
x | | open in gui
|
||||
|
||||
|
||||
### action to
|
||||
|
||||
key | remaps | action
|
||||
--------------- | ------------------------- | ------
|
||||
! | | shell
|
||||
c | | create
|
||||
ctrl-c | | terminate
|
||||
e | | open in editor
|
||||
esc | | cancel
|
||||
l | | logs
|
||||
m | | toggle mouse
|
||||
q | | quit options
|
||||
s | | selection operations
|
||||
[0-9] | | go to index
|
||||
|
||||
|
||||
### create
|
||||
|
||||
key | remaps | action
|
||||
--------------- | ------------------------- | ------
|
||||
ctrl-c | | terminate
|
||||
d | | create directory
|
||||
esc | | cancel
|
||||
f | | create file
|
||||
|
||||
|
||||
### create file
|
||||
|
||||
key | remaps | action
|
||||
--------------- | ------------------------- | ------
|
||||
backspace | | remove last character
|
||||
ctrl-c | | terminate
|
||||
ctrl-u | | remove line
|
||||
ctrl-w | | remove last word
|
||||
enter | | create file
|
||||
esc | | cancel
|
||||
|
||||
|
||||
### create directory
|
||||
|
||||
key | remaps | action
|
||||
--------------- | ------------------------- | ------
|
||||
backspace | | remove last character
|
||||
ctrl-c | | terminate
|
||||
ctrl-u | | remove line
|
||||
ctrl-w | | remove last word
|
||||
enter | | create directory
|
||||
esc | | cancel
|
||||
|
||||
|
||||
### rename
|
||||
|
||||
key | remaps | action
|
||||
--------------- | ------------------------- | ------
|
||||
backspace | | remove last character
|
||||
ctrl-c | | terminate
|
||||
ctrl-u | | remove line
|
||||
ctrl-w | | remove last word
|
||||
enter | | rename
|
||||
esc | | cancel
|
||||
|
||||
|
||||
### delete
|
||||
|
||||
key | remaps | action
|
||||
--------------- | ------------------------- | ------
|
||||
D | | force delete
|
||||
ctrl-c | | terminate
|
||||
d | | delete
|
||||
esc | | cancel
|
||||
|
||||
|
||||
### sort
|
||||
|
||||
key | remaps | action
|
||||
--------------- | ------------------------- | ------
|
||||
! | | reverse sorters
|
||||
E | | by canonical extension reverse
|
||||
M | | by canonical mime essence reverse
|
||||
N | | by node type reverse
|
||||
R | | by relative path reverse
|
||||
S | | by size reverse
|
||||
backspace | | remove last sorter
|
||||
ctrl-c | | terminate
|
||||
ctrl-r | | reset sorters
|
||||
ctrl-u | | clear sorters
|
||||
e | | by canonical extension
|
||||
enter | esc | done
|
||||
m | | by canonical mime essence
|
||||
n | | by node type
|
||||
r | | by relative path
|
||||
s | | by size
|
||||
|
||||
|
||||
### filter
|
||||
|
||||
key | remaps | action
|
||||
--------------- | ------------------------- | ------
|
||||
R | | relative does not contain
|
||||
backspace | | remove last filter
|
||||
ctrl-c | | terminate
|
||||
ctrl-r | | reset filters
|
||||
ctrl-u | | clear filters
|
||||
enter | esc | done
|
||||
r | | relative does contain
|
||||
|
||||
|
||||
### relative path does contain
|
||||
|
||||
key | remaps | action
|
||||
--------------- | ------------------------- | ------
|
||||
backspace | | remove last character
|
||||
ctrl-c | | terminate
|
||||
ctrl-u | | remove line
|
||||
ctrl-w | | remove last word
|
||||
enter | | apply filter
|
||||
esc | | cancel
|
||||
|
||||
|
||||
### relative path does not contain
|
||||
|
||||
key | remaps | action
|
||||
--------------- | ------------------------- | ------
|
||||
backspace | | remove last character
|
||||
ctrl-c | | terminate
|
||||
ctrl-u | | remove line
|
||||
ctrl-w | | remove last word
|
||||
enter | | apply filter
|
||||
esc | | cancel
|
||||
|
||||
|
||||
### switch layout
|
||||
|
||||
key | remaps | action
|
||||
--------------- | ------------------------- | ------
|
||||
1 | | default
|
||||
2 | | no help menu
|
||||
3 | | no selection panel
|
||||
4 | | no help or selection
|
||||
ctrl-c | | terminate
|
||||
esc | | cancel
|
||||
@ -0,0 +1,67 @@
|
||||
General Config
|
||||
==============
|
||||
|
||||
This is configuration exposed via the `xplr.config.general` API. It contains
|
||||
the following fields:
|
||||
|
||||
|
||||
enable_mouse
|
||||
------------
|
||||
|
||||
Type: boolean
|
||||
|
||||
Set it to `true` enable scrolling using mouse.
|
||||
|
||||
|
||||
show_hidden
|
||||
-----------
|
||||
|
||||
Type: boolean
|
||||
|
||||
Set it to `true` to show hidden files.
|
||||
|
||||
|
||||
read_only
|
||||
---------
|
||||
|
||||
Type: boolean
|
||||
|
||||
Set it to `true` to use only a subset of selected operations that forbids
|
||||
executing commands or performing write operations on the file-system.
|
||||
|
||||
|
||||
disable_recover_mode
|
||||
--------------------
|
||||
|
||||
Type: boolean
|
||||
|
||||
Set it to `true` when the special recover mode gets too annoying to appreciate
|
||||
the good intentions. When enabled, typing the wrong keys won't result in any
|
||||
action.
|
||||
|
||||
|
||||
cursor.format
|
||||
-------------
|
||||
|
||||
Type: nullable string
|
||||
|
||||
This is the shape of the cursor visible when the input buffer contains some string.
|
||||
|
||||
|
||||
cursor.style
|
||||
------------
|
||||
|
||||
Type: [Style](style.md)
|
||||
|
||||
Style of the cursor.
|
||||
|
||||
|
||||
initial_layout
|
||||
--------------
|
||||
|
||||
Type: string
|
||||
|
||||
The name of one of the defined [layouts](layouts.md) to use when xplr loads.
|
||||
|
||||
|
||||
TODO: Continue documentation
|
||||
@ -0,0 +1,217 @@
|
||||
Install
|
||||
=======
|
||||
|
||||
You can install xplr using one of the following ways. Each has their own
|
||||
advantages and limitations.
|
||||
|
||||
For example, the [Direct Download](#direct-download),
|
||||
[From crates.io](#from-a-hrefhttpscratesiocratesxplrcratesioa), and
|
||||
[Build From Source](#build-from-source) methods allow the users to install the
|
||||
latest possible version of xplr, but they have one common drawback - the user
|
||||
will need to keep an eye on the releases, and manually upgrade xplr when a new
|
||||
version is available.
|
||||
|
||||
One way to keep an eye of the releases is to
|
||||
[watch the repository](https://github.com/sayanarijit/xplr/watchers).
|
||||
|
||||
|
||||
Community Maintained Repositories
|
||||
---------------------------------
|
||||
|
||||
xplr can be installed from one of the following community maintained
|
||||
repositories:
|
||||
|
||||
[](https://repology.org/project/xplr/versions)
|
||||
|
||||
|
||||
### Arch Linux
|
||||
|
||||
#### [Official Community Repo](https://archlinux.org/packages/community/x86_64/xplr)
|
||||
|
||||
```
|
||||
sudo pacman -Syu xplr
|
||||
```
|
||||
|
||||
#### [AUR](https://aur.archlinux.org/packages/?O=0&SeB=n&K=xplr&outdated=&SB=n&SO=a&PP=50&do_Search=Go)
|
||||
|
||||
Binary version:
|
||||
|
||||
```
|
||||
paru -S xplr-bin
|
||||
```
|
||||
|
||||
Git version:
|
||||
|
||||
```
|
||||
paru -S xplr-git # git version
|
||||
```
|
||||
|
||||
### Void Linux
|
||||
|
||||
#### [void-templates by shubham](https://github.com/shubham-cpp/void-pkg-templates)
|
||||
|
||||
### Nix(OS)
|
||||
|
||||
#### [Nixpkgs](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/xplr)
|
||||
|
||||
```
|
||||
nix-env -f https://github.com/NixOS/nixpkgs/tarball/master -iA xplr
|
||||
```
|
||||
|
||||
### macOS
|
||||
|
||||
#### [MacPorts](https://ports.macports.org/port/xplr)
|
||||
|
||||
```
|
||||
sudo port selfupdate
|
||||
sudo port install xplr
|
||||
```
|
||||
|
||||
#### [Homebrew](https://formulae.brew.sh/formula/xplr)
|
||||
|
||||
Stable branch:
|
||||
|
||||
```
|
||||
brew install xplr
|
||||
```
|
||||
|
||||
HEAD branch:
|
||||
|
||||
```
|
||||
brew install --head xplr
|
||||
```
|
||||
|
||||
### FreeBSD
|
||||
|
||||
#### [ports](https://cgit.freebsd.org/ports/plain/misc/xplr/)
|
||||
|
||||
```
|
||||
cd /usr/ports/misc/xplr
|
||||
make install
|
||||
```
|
||||
|
||||
### NetBSD
|
||||
|
||||
#### [pkgsrc](https://pkgsrc.se/sysutils/xplr)
|
||||
|
||||
```
|
||||
pkgin install xplr
|
||||
```
|
||||
|
||||
Or build from source
|
||||
|
||||
```
|
||||
cd /usr/pkgsrc/sysutils/xplr
|
||||
make install
|
||||
```
|
||||
|
||||
|
||||
Direct Download
|
||||
---------------
|
||||
|
||||
One can directly download the standalone binary from the
|
||||
[releases](https://github.com/sayanarijit/xplr/releases).
|
||||
|
||||
Currently, the following options are available for direct download:
|
||||
|
||||
- [Linux](https://github.com/sayanarijit/xplr/releases/latest/download/xplr-linux.tar.gz)
|
||||
- [macOS](https://github.com/sayanarijit/xplr/releases/latest/download/xplr-macos.tar.gz)
|
||||
|
||||
Command-line instructions:
|
||||
|
||||
```bash
|
||||
platform="linux" # or "macos"
|
||||
|
||||
# Download
|
||||
wget https://github.com/sayanarijit/xplr/releases/latest/download/xplr-$platform.tar.gz
|
||||
|
||||
# Extract
|
||||
tar xzvf xplr-$platform.tar.gz
|
||||
|
||||
# Place in $PATH
|
||||
sudo mv xplr /usr/local/bin/
|
||||
```
|
||||
|
||||
|
||||
From [crates.io](https://crates.io/crates/xplr)
|
||||
-----------------------------------------------
|
||||
|
||||
Prerequisites:
|
||||
|
||||
- [Rust toolchain](https://www.rust-lang.org/tools/install),
|
||||
- [gcc](https://gcc.gnu.org/)
|
||||
- [make](https://www.gnu.org/software/make/)
|
||||
|
||||
Command-line instructions:
|
||||
|
||||
```bash
|
||||
cargo install --force xplr
|
||||
```
|
||||
|
||||
|
||||
Build From Source
|
||||
-----------------
|
||||
|
||||
Prerequisites:
|
||||
|
||||
- [git](https://git-scm.com/)
|
||||
- [Rust toolchain](https://www.rust-lang.org/tools/install)
|
||||
- [gcc](https://gcc.gnu.org/)
|
||||
- [make](https://www.gnu.org/software/make/)
|
||||
|
||||
Command-line instructions:
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/sayanarijit/xplr.git
|
||||
cd xplr
|
||||
|
||||
# Build
|
||||
cargo build --release --bin xplr
|
||||
|
||||
# Place in $PATH
|
||||
sudo cp target/release/xplr /usr/local/bin/
|
||||
```
|
||||
|
||||
|
||||
Android
|
||||
-------
|
||||
|
||||
### [Termux](https://termux.com/)
|
||||
|
||||
[](https://gifyu.com/image/tF2D)
|
||||
|
||||
> Please note that xplr isn't heavily tested on Termux, hence things might
|
||||
> need a little tweaking and fixing for a smooth usage experience.
|
||||
|
||||
- Install build dependencies
|
||||
|
||||
```bash
|
||||
pkg install rustc cargo make
|
||||
```
|
||||
|
||||
- Install `xplr`
|
||||
|
||||
```bash
|
||||
cargo install --force xplr
|
||||
```
|
||||
|
||||
- Setup storage
|
||||
|
||||
```bash
|
||||
termux-setup-storage
|
||||
```
|
||||
|
||||
- Setup config and runtime dir
|
||||
|
||||
```bash
|
||||
export XDG_CONFIG_HOME="$PWD/storage/.config"
|
||||
export XDG_RUNTIME_DIR="$PWD/storage/run"
|
||||
|
||||
mkdir -p "$XDG_CONFIG_HOME" "$XDG_RUNTIME_DIR"
|
||||
```
|
||||
|
||||
- Run
|
||||
```bash
|
||||
~/.cargo/bin/xplr
|
||||
```
|
||||
@ -0,0 +1,15 @@
|
||||
Introduction
|
||||
============
|
||||
|
||||
`xplr` is a terminal UI based file explorer that aims to increase our terminal
|
||||
productivity by being a flexible, interactive orchestrator for the ever growing
|
||||
awesome command-line utilities that work with the file-system.
|
||||
|
||||
To achieve its goal, `xplr` strives to be a fast, minimal and more importantly,
|
||||
hackable file explorer.
|
||||
|
||||
`xplr` is not meant to be a replacement for the standard shell commands or the
|
||||
GUI file managers. Rather, it aims to integrate them all and expose an
|
||||
intuitive, scriptable, keyboard controlled, real-time visual interface, also
|
||||
being an ideal candidate for further integration, enabling the users to achieve
|
||||
insane terminal productivity.
|
||||
@ -0,0 +1 @@
|
||||
# Key Bindings
|
||||
@ -0,0 +1,225 @@
|
||||
Layouts
|
||||
=======
|
||||
|
||||
xplr layouts define the structure of the UI, i.e. how many panel we see,
|
||||
placement and size of the panels, how they look etc.
|
||||
|
||||
This is configuration exposed via the `xplr.config.layouts` API. It contains
|
||||
the following fields:
|
||||
|
||||
- [builtin](#builtin)
|
||||
- [custom](#custom)
|
||||
|
||||
The users can switch between these layouts at run-time.
|
||||
|
||||
|
||||
builtin
|
||||
-------
|
||||
|
||||
Type: mapping of string and [Layout](#layout)
|
||||
|
||||
This is exposed by the `xplr.config.layouts.builtin` API.
|
||||
|
||||
xplr by default provides the following builtin layouts:
|
||||
|
||||
- [default](#default)
|
||||
- [no_help](#no_help)
|
||||
- [no_selection](#no_selection)
|
||||
- [no_help_no_selection](#no_help_no_selection)
|
||||
|
||||
### default
|
||||
|
||||
Type: [Layout](#layout)
|
||||
|
||||
This is the default layout we see when we run xplr.
|
||||
|
||||
### no_help
|
||||
|
||||
Type: [Layout](#layout)
|
||||
|
||||
This layout hides the help menu.
|
||||
|
||||
### no_selection
|
||||
|
||||
Type: [Layout](#layout)
|
||||
|
||||
This layout hides the selection panel.
|
||||
|
||||
### no_help_no_selection
|
||||
|
||||
Type: [Layout](#layout)
|
||||
|
||||
This layout hides both the help menu and the selection panel.
|
||||
|
||||
|
||||
custom
|
||||
------
|
||||
|
||||
Type: mapping of string and [Layout](#layout)
|
||||
|
||||
This is exposed by the `xplr.config.layouts.custom` API.
|
||||
|
||||
It allows the users to define any custom layout.
|
||||
|
||||
Example:
|
||||
|
||||
```lua
|
||||
xplr.config.layouts.custom.example = "Nothing"
|
||||
xplr.config.general.initial_layout = "example"
|
||||
|
||||
-- when you load xplr, you should see a blank screen
|
||||
```
|
||||
|
||||
Layout
|
||||
------
|
||||
|
||||
A layout can be one of the following:
|
||||
|
||||
- ["Nothing"](#nothing)
|
||||
- ["Table"](#table)
|
||||
- ["InputAndLogs"](#inputandlogs)
|
||||
- ["Selection"](#selection)
|
||||
- ["HelpMenu"](#helpmenu)
|
||||
- ["SortAndFilter"](#sortandfilter)
|
||||
- { [Horizontal](#horizontal) = { config = [Layout Config](#layout-config), splits = { [Layout](#layout), ... } }
|
||||
- { [Vertical](#vertical) = { config = [Layout Config](#layout-config), splits = { [Layout](#layout), ... } }
|
||||
|
||||
### Nothing
|
||||
|
||||
This layout contains a blank panel.
|
||||
|
||||
### Table
|
||||
|
||||
This layout contains the table displaying the files and directories in the
|
||||
current directory.
|
||||
|
||||
### InputAndLogs
|
||||
|
||||
This layout contains the panel displaying the input prompt and logs.
|
||||
|
||||
### Selection
|
||||
|
||||
This layout contains the panel displaying the selected paths.
|
||||
|
||||
### HelpMenu
|
||||
|
||||
This layout contains the panel displaying the help menu for the current mode in
|
||||
real-time.
|
||||
|
||||
### SortAndFilter
|
||||
|
||||
This layout contains the panel displaying the pipeline of sorters and filters
|
||||
applied of the list of paths being displayed.
|
||||
|
||||
### Horizontal
|
||||
|
||||
This is a special layout that splits the panel into two horizontal parts.
|
||||
|
||||
It contains the following information:
|
||||
|
||||
- [config](#layout-config)
|
||||
- [splits](#splits)
|
||||
|
||||
### Vertical
|
||||
|
||||
This is a special layout that splits the panel into two vertical parts.
|
||||
|
||||
It contains the following information:
|
||||
|
||||
- [config](#layout-config)
|
||||
- [splits](#splits)
|
||||
|
||||
|
||||
Layout Config
|
||||
-------------
|
||||
|
||||
A layout config contains the following information:
|
||||
|
||||
- [margin](#margin)
|
||||
- [horizontal_margin](#horizontal_margin)
|
||||
- [vertical_margin](#vertical_margin)
|
||||
- [constraints](#constraints)
|
||||
|
||||
### margin
|
||||
|
||||
Type: nullable integer
|
||||
|
||||
The width of the margin in all direction.
|
||||
|
||||
### horizontal_Margin
|
||||
|
||||
Type: nullable integer
|
||||
|
||||
The width of the horizontal margins. Overwrites the [margin](#margin) value.
|
||||
|
||||
### vertical_Margin
|
||||
|
||||
Type: nullable integer
|
||||
|
||||
The width of the vertical margins. Overwrites the [margin](#margin) value.
|
||||
|
||||
### constraints
|
||||
|
||||
Type: nullable list of [Constraint](#constraint)
|
||||
|
||||
The constraints applied on the layout.
|
||||
|
||||
|
||||
Constraint
|
||||
----------
|
||||
|
||||
A constraint can be one of the following:
|
||||
|
||||
- { Percentage = int }
|
||||
- { Ratio = { int, int } }
|
||||
- { Length = { int }
|
||||
- { LengthLessThanScreenHeight = int }
|
||||
- { LengthLessThanScreenWidth = int }
|
||||
- { LengthLessThanLayoutHeight = int }
|
||||
- { LengthLessThanLayoutWidth = int }
|
||||
- { Max = int }
|
||||
- { MaxLessThanScreenHeight = int }
|
||||
- { MaxLessThanScreenWidth = int }
|
||||
- { MaxLessThanLayoutHeight = int }
|
||||
- { MaxthLessThanLayoutWidth = int }
|
||||
- { Min = int }
|
||||
- { MinLessThanScreenHeight = int }
|
||||
- { MinLessThanScreenWidth = int }
|
||||
- { MinLessThanLayoutHeight = int }
|
||||
- { MinLessThanLayoutWidth = int }
|
||||
|
||||
TODO: document each constraint.
|
||||
|
||||
|
||||
splits
|
||||
------
|
||||
|
||||
Type: list of [Layout](#layout)
|
||||
|
||||
The list of child layouts to fit into the parent layout.
|
||||
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
[](https://gifyu.com/image/1X38)
|
||||
|
||||
```lua
|
||||
xplr.config.layouts.builtin.default = {
|
||||
Horizontal = {
|
||||
config = {
|
||||
margin = 1,
|
||||
horizontal_margin = 2,
|
||||
vertical_margin = 3,
|
||||
constraints = {
|
||||
{ Percentage = 50 },
|
||||
{ Percentage = 50 },
|
||||
}
|
||||
},
|
||||
splits = {
|
||||
"Table",
|
||||
"HelpMenu",
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
@ -0,0 +1,196 @@
|
||||
Message
|
||||
=======
|
||||
|
||||
You can think of xplr as a server. Just like web servers listen to HTTP
|
||||
requests, xplr listens to messages.
|
||||
|
||||
See the
|
||||
[**full list of messages**](https://docs.rs/xplr/latest/xplr/app/enum.ExternalMsg.html#variants)
|
||||
that xplr can handle.
|
||||
|
||||
You can send messages to an xplr session in the following ways:
|
||||
|
||||
- Via [key bindings](modes.md#key-bindings)
|
||||
- Via [Lua function calls](#lua-function-calls)
|
||||
- Via shell using the [input pipe](#input-pipe)
|
||||
|
||||
|
||||
Format
|
||||
------
|
||||
|
||||
To send messages using [key bindings](modes.md#key-bindings) or
|
||||
[Lua functions calls](#lua-functions-calls), these are represented in
|
||||
[Lua](https://www.lua.org/) syntax. For example:
|
||||
|
||||
- "Quit"
|
||||
- { FocusPath = "/path/to/file" }
|
||||
- { Call = { command = "bash", args = { "-c", "read -p test" } } }
|
||||
|
||||
However, to send messages using the [input pipe](#input-pipe), they need to be
|
||||
represented using
|
||||
[YAML](http://yaml.org/) (or [JSON](https://www.json.org)) syntax. For example:
|
||||
|
||||
- Foo
|
||||
- FocusPath: "/path/to/file"
|
||||
- Call: { command: bash, args: ["-c", "read -p test"] }
|
||||
|
||||
|
||||
Lua Function Calls
|
||||
------------------
|
||||
|
||||
xplr allows users to define lua functions using the `xplr.fn.custom` Lua API.
|
||||
|
||||
These functions can be called using messages like `CallLua`, `CallLuaSilently`.
|
||||
|
||||
When called the function receives a [special argument](#calllua-argument) that
|
||||
contains some useful information. The function can optionally return a list of
|
||||
messages which will be handled by xplr.
|
||||
|
||||
Example:
|
||||
|
||||
```lua
|
||||
-- Define the function
|
||||
xplr.fn.custom.ask_name_and_greet = function(app)
|
||||
print("What's your name?")
|
||||
|
||||
local name = io.read()
|
||||
local greeting = "Hello " .. name .. "!"
|
||||
local message = greeting .. " You are inside " .. app.pwd
|
||||
|
||||
return {
|
||||
{ LogSuccess = message },
|
||||
}
|
||||
end
|
||||
|
||||
-- Map the function to a key (space)
|
||||
xplr.config.modes.builtin.default.key_bindings.on_key.space = {
|
||||
help = "and & greet",
|
||||
messages = {
|
||||
{ CallLua = "custom.ask_name_and_greet" }
|
||||
}
|
||||
}
|
||||
|
||||
-- Now, when you press "space" in default mode, you will be prompted for your
|
||||
-- name. Enter your name to receive a nice greeting and to know your location.
|
||||
```
|
||||
|
||||
### CallLua Argument
|
||||
|
||||
This is a special argument passed to the lua functions when called using the
|
||||
`CallLua`, `CallLuaSilently` messages.
|
||||
|
||||
It contains the following information:
|
||||
|
||||
- version
|
||||
- config
|
||||
- pwd
|
||||
- focused_node
|
||||
- directory_buffer
|
||||
- selection
|
||||
- mode
|
||||
- layout
|
||||
- input_buffer
|
||||
- pid
|
||||
- session_path
|
||||
- explorer_config
|
||||
- history
|
||||
- last_modes
|
||||
|
||||
TODO: Document each. For now, refer to the
|
||||
[rust doc](https://docs.rs/xplr/latest/xplr/app/struct.CallLuaArg.html#fields).
|
||||
|
||||
|
||||
Environment Variables and Pipes
|
||||
-------------------------------
|
||||
|
||||
Alternative to `CallLua`, `CallLuaSilently` messages that call Lua functions,
|
||||
there are `Call`, `CallLuaSilently`, `BashExec`, `BashExecSilently` messages
|
||||
that call shell commands.
|
||||
|
||||
However, unlike the Lua functions, these shell commands have to read the useful
|
||||
information and send messages via environment variables and temporary files
|
||||
called "pipe"s. These environment variables and files are only available when
|
||||
a command is being executed.
|
||||
|
||||
Visit the [**fzf integration tutorial**](modes.html#tutorial-adding-a-new-mode)
|
||||
for example.
|
||||
|
||||
### Environment variables
|
||||
|
||||
To see the environment variables, invoke the shell by typing `:!` in default
|
||||
mode and run the following command:
|
||||
|
||||
```
|
||||
env | grep ^XPLR_
|
||||
```
|
||||
|
||||
You will see something like:
|
||||
|
||||
```
|
||||
XPLR_FOCUS_INDEX=0
|
||||
XPLR_MODE=action to
|
||||
XPLR_PIPE_SELECTION_OUT=/run/user/1000/xplr/session/122278/pipe/selection_out
|
||||
XPLR_INPUT_BUFFER=
|
||||
XPLR_PIPE_GLOBAL_HELP_MENU_OUT=/run/user/1000/xplr/session/122278/pipe/global_help_menu_out
|
||||
XPLR_PID=122278
|
||||
XPLR_PIPE_MSG_IN=/run/user/1000/xplr/session/122278/pipe/msg_in
|
||||
XPLR_PIPE_LOGS_OUT=/run/user/1000/xplr/session/122278/pipe/logs_out
|
||||
XPLR_PIPE_RESULT_OUT=/run/user/1000/xplr/session/122278/pipe/result_out
|
||||
XPLR_PIPE_HISTORY_OUT=/run/user/1000/xplr/session/122278/pipe/history_out
|
||||
XPLR_FOCUS_PATH=/home/sayanarijit/Documents/GitHub/xplr/docs/en/book
|
||||
XPLR_SESSION_PATH=/run/user/1000/xplr/session/122278
|
||||
XPLR_APP_VERSION=0.14.3
|
||||
XPLR_PIPE_DIRECTORY_NODES_OUT=/run/user/1000/xplr/session/122278/pipe/directory_nodes_out
|
||||
```
|
||||
|
||||
The environment variables starting with `XPLR_PIPE_` are the temporary files
|
||||
called "pipe"s.
|
||||
|
||||
### Input pipe
|
||||
|
||||
Current there is only one input pipe.
|
||||
|
||||
- [XPLR_PIPE_MSG_IN](#xplr_pipe_msg_in)
|
||||
|
||||
### Output pipes
|
||||
|
||||
`XPLR_PIPE_*_OUT` are the output pipes that contain data which cannot be
|
||||
exposed directly via environment variables, like multi-line string.
|
||||
|
||||
- [XPLR_PIPE_SELECTION_OUT](#xplr_pipe_selection_out)
|
||||
- [XPLR_PIPE_GLOBAL_HELP_MENU_OUT](#xplr_pipe_global_help_menu_out)
|
||||
- [XPLR_PIPE_LOGS_OUT](#xplr_pipe_logs_out)
|
||||
- [XPLR_PIPE_RESULT_OUT](#xplr_pipe_result_out)
|
||||
- [XPLR_PIPE_HISTORY_OUT](#xplr_pipe_history_out)
|
||||
- [XPLR_PIPE_DIRECTORY_NODES_OUT](#xplr_pipe_directory_nodes_out)
|
||||
|
||||
### XPLR_PIPE_MSG_IN
|
||||
|
||||
Append new-line delimited messages to this pipe in [YAML](www.yaml.org) (or
|
||||
[JSON](www.json.org)) syntax. These messages will be read and handled by xplr
|
||||
after the command execution.
|
||||
|
||||
### XPLR_PIPE_SELECTION_OUT
|
||||
|
||||
New-line delimited list of selected paths.
|
||||
|
||||
### XPLR_PIPE_GLOBAL_HELP_MENU_OUT
|
||||
|
||||
The full help menu.
|
||||
|
||||
### XPLR_PIPE_LOGS_OUT
|
||||
|
||||
New-line delimited list of logs.
|
||||
|
||||
### XPLR_PIPE_RESULT_OUT
|
||||
|
||||
New-line delimited result (selected paths if any, else the focused path)
|
||||
|
||||
### XPLR_PIPE_HISTORY_OUT
|
||||
|
||||
New-line delimited list of last visited paths (similar to jump list in vim).
|
||||
|
||||
### XPLR_PIPE_DIRECTORY_NODES_OUT
|
||||
|
||||
New-line delimited list of paths, filtered and sorted as displayed in the
|
||||
[files table](layouts.md#table).
|
||||
@ -0,0 +1,259 @@
|
||||
Modes
|
||||
=====
|
||||
|
||||
xplr is a modal application. That means the users switch between different
|
||||
modes, each containing a different set to key binding to avoid classes. The
|
||||
modes can be configured using the `xplr.config.modes` Lua API.
|
||||
|
||||
- [builtin](#builtin)
|
||||
- [custom](#custom)
|
||||
|
||||
The users can switch between these modes at run-time.
|
||||
|
||||
|
||||
builtin
|
||||
-------
|
||||
|
||||
Type: mapping of string and [Mode](#mode)
|
||||
|
||||
This is exposed by the `xplr.config.modes.builtin` API.
|
||||
|
||||
xplr by default provides the following builtin modes:
|
||||
|
||||
- default
|
||||
- recover
|
||||
- selection_ops
|
||||
- create
|
||||
- create_directory
|
||||
- create_file
|
||||
- number
|
||||
- go_to
|
||||
- rename
|
||||
- delete
|
||||
- action
|
||||
- search
|
||||
- filter
|
||||
- relative_path_does_contain
|
||||
- relative_path_does_not_contain
|
||||
- sort
|
||||
- switch_layout
|
||||
- quit
|
||||
|
||||
Visit the [Default Key Bindings](default-key-bindings.md) to see what each mode
|
||||
does.
|
||||
|
||||
|
||||
custom
|
||||
------
|
||||
|
||||
Type: mapping of string and [Mode](#mode)
|
||||
|
||||
|
||||
This is exposed by the `xplr.config.layouts.custom` API.
|
||||
|
||||
It allows the users to define any custom layout.
|
||||
|
||||
Example:
|
||||
|
||||
```lua
|
||||
xplr.config.modes.custom.example = {
|
||||
name = "example",
|
||||
key_bindings = {
|
||||
on_key = {
|
||||
enter = {
|
||||
help = "default mode",
|
||||
messages = {
|
||||
"PopMode",
|
||||
{ SwitchModeBuiltin = "default" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
xplr.config.general.initial_mode = "example"
|
||||
|
||||
-- when you load xplr, you should be in the "example" mode,
|
||||
-- pressing "enter" should take you to the "default" mode.
|
||||
```
|
||||
|
||||
|
||||
Mode
|
||||
----
|
||||
|
||||
A mode contains the following information:
|
||||
|
||||
- [name](#name)
|
||||
- [help](#help)
|
||||
- [extra_help](#extra_help)
|
||||
- [key_bindings](#key_bindings)
|
||||
|
||||
### name
|
||||
|
||||
Type: string
|
||||
|
||||
This is the name of the mode visible in the help menu.
|
||||
|
||||
### help
|
||||
|
||||
Type: nullable string
|
||||
|
||||
If specified, the help menu will display this instead of the auto generated
|
||||
mappings.
|
||||
|
||||
### extra_help
|
||||
|
||||
Type: nullable string
|
||||
|
||||
If specified, the help menu will display this along-side the auto generated
|
||||
help menu.
|
||||
|
||||
### key_bindings
|
||||
|
||||
Type: [Key Bindings](#key-bindings)
|
||||
|
||||
The key bindings available in that mode.
|
||||
|
||||
|
||||
Key Bindings
|
||||
------------
|
||||
|
||||
Key bindings define how each keyboard input will be handled in a specific mode.
|
||||
|
||||
See the [default key bindings](default-key-bindings.md) for example.
|
||||
|
||||
Key bindings contains the following information:
|
||||
|
||||
- [on_key](#on_key)
|
||||
- [on_alphabet](#on_alphabet)
|
||||
- [on_number](#on_number)
|
||||
- [on_special_character](#on_special_character)
|
||||
- [default](#default)
|
||||
|
||||
### on_key
|
||||
|
||||
Type: mapping of [Key](#key) to nullable [Action](#action)
|
||||
|
||||
Defines what to do when a specific key is pressed.
|
||||
|
||||
### on_alphabet
|
||||
|
||||
Type: nullable [Action](#action)
|
||||
|
||||
An action to perform if the keyboard input is an alphabet and is not mapped via
|
||||
the [on_key](#on_key) field.
|
||||
|
||||
### on_number
|
||||
|
||||
Type: nullable [Action](#action)
|
||||
|
||||
An action to perform if the keyboard input is a number and is not mapped via
|
||||
the [on_key](#on_key) field.
|
||||
|
||||
### on_special_character
|
||||
|
||||
Type: nullable [Action](#action)
|
||||
|
||||
An action to perform if the keyboard input is a special character and is not
|
||||
mapped via the [on_key](#on_key) field.
|
||||
|
||||
### default
|
||||
|
||||
Type: nullable [Action](#action)
|
||||
|
||||
Default action to perform in case of a keyboard input not mapped via any of the
|
||||
[on_key](#on_key), [on_alphabet](#on_alphabet), [on_number](#on_number) or
|
||||
[on_special_character](#on_special_character) field.
|
||||
|
||||
|
||||
Action
|
||||
------
|
||||
|
||||
An action contains the following information:
|
||||
|
||||
- help
|
||||
- [messages](#messages)
|
||||
|
||||
### help
|
||||
|
||||
Type: nullable string
|
||||
|
||||
Description of what it does. If unspecified, it will be excluded from the help
|
||||
menu.
|
||||
|
||||
### messages
|
||||
|
||||
Type: A list of [Message](message.md) to send.
|
||||
|
||||
The list of messages to send when a key is pressed.
|
||||
|
||||
|
||||
Tutorial: Adding a New Mode
|
||||
---------------------------
|
||||
|
||||
Assuming xplr is [installed](install.md) and [setup](post-install.md), let's
|
||||
add our own mode to integrate xplr with [fzf](https://github.com/junegunn/fzf).
|
||||
|
||||
We'll call it `fzxplr` mode.
|
||||
|
||||
First, let's add a custom mode called `fzxplr`, and map the key `F` to an
|
||||
action that will call `fzf` to search and focus on a file or enter into a
|
||||
directory.
|
||||
|
||||
```lua
|
||||
xplr.config.modes.custom.fzxplr = {
|
||||
name = "fzxplr",
|
||||
key_bindings = {
|
||||
on_key = {
|
||||
F = {
|
||||
help = "search",
|
||||
messages = {
|
||||
{
|
||||
BashExec = [===[
|
||||
PTH=$(cat "${XPLR_PIPE_DIRECTORY_NODES_OUT:?}" | awk -F/ '{print $NF}' | fzf)
|
||||
if [ -d "$PTH" ]; then
|
||||
echo ChangeDirectory: "'"${PWD:?}/${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}"
|
||||
else
|
||||
echo FocusPath: "'"${PWD:?}/${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}"
|
||||
fi
|
||||
]===]
|
||||
},
|
||||
"PopMode",
|
||||
},
|
||||
},
|
||||
},
|
||||
default = {
|
||||
messages = {
|
||||
"PopMode",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
As you can see, the key `F` in mode `fzxplr` (the name can be anything)
|
||||
executes a script in `bash`.
|
||||
|
||||
`BashExec`, `PopMode`, `SwitchModeBuiltin`, `ChangeDirectory` and `FocusPath`
|
||||
are [messages](message.md), `$XPLR_PIPE_MSG_IN`,
|
||||
`$XPLR_PIPE_DIRECTORY_NODES_OUT` are
|
||||
[environment variables](message.md#environment-variables) exported by `xplr`
|
||||
before executing the command. They contain the path to the
|
||||
[input](message.md#input-pipe) and [output](message.md#output-pipes) pipes that
|
||||
allows external tools to interact with `xplr`.
|
||||
|
||||
Now that we have our new mode ready, let's add an entry point to this mode via
|
||||
the `default` mode.
|
||||
|
||||
```lua
|
||||
xplr.config.modes.builtin.default.key_bindings.on_key["F"] = {
|
||||
help = "fzf mode",
|
||||
messages = {
|
||||
{ SwitchModeCustom = "fzxplr" },
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Now let's try out the new `xplr`-`fzf` integration.
|
||||
|
||||
[](https://gifyu.com/image/tW86)
|
||||
@ -0,0 +1,37 @@
|
||||
Post Install
|
||||
============
|
||||
|
||||
Once [installed](install.md), use the following steps to setup and run xplr.
|
||||
|
||||
Create the customizable config file
|
||||
-----------------------------------
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.config/xplr
|
||||
|
||||
version="$(xplr | grep ^version: | cut -d' ' -f 2)"
|
||||
|
||||
# When the app loads, press `#`
|
||||
|
||||
echo version = '"'${version:?}'"' > ~/.config/xplr/init.lua
|
||||
```
|
||||
|
||||
Then
|
||||
**[copy from here](https://github.com/sayanarijit/xplr/blob/main/src/init.lua)**
|
||||
and remove / comment out what you don't want to customize.
|
||||
|
||||
> **Note:** You don't generally need to create the config file. You can use the
|
||||
> default configuration for basic operations. However, creating the config file
|
||||
> is recommended because the project is in its early stage and the defaults
|
||||
> might change. Creating the config file will save you from unexpected behavior
|
||||
> when you [upgrade](upgrade-guide.md).
|
||||
> Also, the default configuration is meant to be overwritten to suit your
|
||||
> workflow.
|
||||
|
||||
|
||||
Run
|
||||
---
|
||||
|
||||
```
|
||||
xplr
|
||||
```
|
||||
@ -0,0 +1,5 @@
|
||||
Quickstart
|
||||
==========
|
||||
|
||||
In this chapter, we'll learn how to install and configure xplr on our machine
|
||||
for the first time.
|
||||
@ -0,0 +1,89 @@
|
||||
Style
|
||||
=====
|
||||
|
||||
A style object contains the following information:
|
||||
|
||||
- [fg](#fg)
|
||||
- [bg](#bg)
|
||||
- [add_modifiers](#add_modifiers)
|
||||
- [sub_modifiers](#sub_modifiers)
|
||||
|
||||
### fg
|
||||
|
||||
Type: nullable [Color](#color)
|
||||
|
||||
The foreground color.
|
||||
|
||||
|
||||
### bg
|
||||
|
||||
Type: nullable [Color](#color)
|
||||
|
||||
The background color.
|
||||
|
||||
|
||||
### add_modifiers
|
||||
|
||||
Type: nullable list of [Modifier](#modifier)
|
||||
|
||||
Modifiers to add.
|
||||
|
||||
|
||||
### sub_modifiers
|
||||
|
||||
Type: nullable list of [Modifier](#modifier)
|
||||
|
||||
Modifiers to remove.
|
||||
|
||||
|
||||
Color
|
||||
-----
|
||||
|
||||
Color can be one of the following:
|
||||
|
||||
- "Reset"
|
||||
- "Black"
|
||||
- "Red"
|
||||
- "Green"
|
||||
- "Yellow"
|
||||
- "Blue"
|
||||
- "Magenta"
|
||||
- "Cyan"
|
||||
- "Gray"
|
||||
- "DarkGray"
|
||||
- "LightRed"
|
||||
- "LightGreen"
|
||||
- "LightYellow"
|
||||
- "LightBlue"
|
||||
- "LightMagenta"
|
||||
- "LightCyan"
|
||||
- "White"
|
||||
- { Rgb = { int, int, int } }
|
||||
- { Indexed = int }
|
||||
|
||||
|
||||
Modifier
|
||||
--------
|
||||
|
||||
Modifier can be one of the following:
|
||||
|
||||
- "Bold"
|
||||
- "Dim"
|
||||
- "Italic"
|
||||
- "Underlined"
|
||||
- "SlowBlink"
|
||||
- "RapidBlink"
|
||||
- "Reversed"
|
||||
- "Hidden"
|
||||
- "CrossedOut"
|
||||
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
```lua
|
||||
xplr.config.general.cursor.style.fg = "Red"
|
||||
xplr.config.general.cursor.style.bg = { Rgb = { 100, 150, 200 } }
|
||||
xplr.config.general.cursor.style.add_modifiers = { "Bold", "Italic" }
|
||||
xplr.config.general.cursor.style.sub_modifiers = { "Hidden" }
|
||||
```
|
||||
@ -0,0 +1,28 @@
|
||||
TODO
|
||||
====
|
||||
|
||||
- [x] Saner key bindings.
|
||||
- [x] Pipes.
|
||||
- [x] Native search & filter.
|
||||
- [x] Create, copy, move, delete files directly.
|
||||
- [x] logging support.
|
||||
- [x] Version compatibility instructions.
|
||||
- [x] Implement CLI arguments.
|
||||
- ~Add support for tabs and/or panes (non native)~ [hacked](https://github.com/sayanarijit/xplr/wiki/Hacks#spawn-multiple-sessions-in-different-windows) | [discussion](https://github.com/sayanarijit/xplr/discussions/15)
|
||||
- ~Implement bookmarks.~ [hacked](https://github.com/sayanarijit/xplr/wiki/Hacks#bookmark)
|
||||
- [x] Add sorting support.
|
||||
- [x] Add filter support.
|
||||
- [x] File previews.
|
||||
- [ ] Implement plugins support (or some way to easily share configuration).
|
||||
- [x] Bigger (and better) help menu.
|
||||
- [ ] Offline docs.
|
||||
- [ ] Support for background services.
|
||||
- [x] ~Customize~ switch UI in run-time.
|
||||
- [ ] More tests and benchmarks.
|
||||
- [ ] Measure code coverage.
|
||||
- [ ] Improve the [vim plugin](https://github.com/sayanarijit/xplr.vim).
|
||||
- [ ] Cleanup, refactor, optimize.
|
||||
|
||||
[add more](https://github.com/sayanarijit/xplr/discussions/2)
|
||||
|
||||
Like this project so far? **[Please consider contributing](contribute.md).**
|
||||
@ -0,0 +1,212 @@
|
||||
Upgrade Guide
|
||||
=============
|
||||
|
||||
When you upgrade xplr, you might see an error like this
|
||||
|
||||
```
|
||||
Incompatible script version in: /home/sayanarijit/.config/xplr/init.lua. The script version is: 0.9.0, the required version is: 0.10.1. Visit https://github.com/sayanarijit/xplr/wiki/Upgrade-Guide
|
||||
```
|
||||
|
||||
All you need to do is follow the [instructions](#instructions) starting from
|
||||
your config version, all the way to the required version.
|
||||
|
||||
<details>
|
||||
<summary>Expand for more information</summary>
|
||||
|
||||
With every update, we either implement a `major` breaking change (e.g.
|
||||
deprecating or replacing messages), or a `minor` feature addition (e.g. adding
|
||||
new messages) or `patch`, fixes, and optimization (e.g. performance
|
||||
optimization).
|
||||
|
||||
Knowing that we use the `{major}.{minor}.{patch}` versioning format,
|
||||
|
||||
- Major version mismatch are generally incompatible. xplr will fail
|
||||
with error.
|
||||
- Minor version upgrades (not downgrades) and patch fixes are backwards
|
||||
compatible. You might get notified by log a message which you can disable by
|
||||
updating the version in your config file.
|
||||
- However, if the config file has a higher value for the minor version
|
||||
than the app, then also xplr will fail with error, suggesting you
|
||||
to visit this page.
|
||||
Though in that case, you will be downgrading your config file based on your
|
||||
app version.
|
||||
|
||||
e.g.
|
||||
|
||||
- `1.0.0` -> `1.0.x`: Bug fix (fully compatible).
|
||||
- `1.0.0` -> `1.x.x`: Only backwards compatible. You can't generally use for
|
||||
e.g. `app-1.0.0` with `config-1.1.0`. But vice versa is fine.
|
||||
- `1.0.0` -> `x.x.x`: Not compatible at all.
|
||||
|
||||
Note that until we're `v1`, we'll be using the `{minor}` version number as
|
||||
`{major}`, and the `{patch}` fix number as `{minor}` to determine
|
||||
compatibility.
|
||||
|
||||
</details>
|
||||
|
||||
### Instructions
|
||||
|
||||
#### [v0.13.7](https://github.com/sayanarijit/xplr/releases/tag/v0.13.7) -> [v0.14.2](https://github.com/sayanarijit/xplr/releases/tag/v0.14.2)
|
||||
|
||||
- macOS users need to place their config file (`init.lua`) in
|
||||
`$HOME/.config/xplr/` or `/etc/xplr/`.
|
||||
- Library users please refer to the latest API docs.
|
||||
- Check out the new messages: `{Start|Stop|Toggle}Fifo`. These enable support
|
||||
for [FIFO based file previews](https://github.com/sayanarijit/xplr/pull/229#issue-662426960).
|
||||
- You can disable the recover mode using `config.general.disable_recover_mode = true`.
|
||||
- Try running `xplr --help`. Yes, CLI has been implemented.
|
||||
|
||||
<sub>Like this project so far? **[Please consider contributing](contribute.md)**.</sub>
|
||||
|
||||
#### [v0.12.1](https://github.com/sayanarijit/xplr/releases/tag/v0.12.1) -> [v0.13.7](https://github.com/sayanarijit/xplr/releases/tag/v0.13.7)
|
||||
- Lua functions called using [`CallLua`](https://docs.rs/xplr/latest/xplr/app/enum.ExternalMsg.html#variant.CallLua) and [`CallLuaSilently`](https://docs.rs/xplr/latest/xplr/app/enum.ExternalMsg.html#variant.CallLuaSilently) messages will receive [`CallLuaArg`](https://docs.rs/xplr/latest/xplr/app/struct.CallLuaArg.html) object as the function argument (instead of the [`App`](https://docs.rs/xplr/latest/xplr/app/struct.App.html) object).
|
||||
- Each `node_types` config will inherit defaults from matching less specifig `node_types` config and overwrite them.
|
||||
- Since version `v0.13.2`, you don't need to use/send `Refresh` anymore. It will be auto-handled by xplr.
|
||||
|
||||
#### [v0.11.1](https://github.com/sayanarijit/xplr/releases/tag/v0.11.1) -> [v0.12.1](https://github.com/sayanarijit/xplr/releases/tag/v0.12.1)
|
||||
|
||||
- `xplr.config.node_types.mime_essence` has split into type and subtype. Hence, instead of `xplr.config.node_types.mime_essence["text/plain"] = ..` use `xplr.config.node_types.mime_essence["text"] = { plain = .. }`.
|
||||
- You can also define `xplr.config.node_types.mime_essence["text"]["*"]` that will match all text types (`text/*`).
|
||||
|
||||
#### [v0.10.2](https://github.com/sayanarijit/xplr/releases/tag/v0.10.2) -> [v0.11.1](https://github.com/sayanarijit/xplr/releases/tag/v0.11.1)
|
||||
|
||||
- `remaps:` has been removed to avoid confusion. Use lua assignments instead.
|
||||
For e.g.
|
||||
```
|
||||
xplr.config.modes.builtin.default.key_bindings.on_key["v"] = xplr.config.modes.builtin.default.key_bindings.on_key.space
|
||||
```
|
||||
|
||||
#### [v0.9.1](https://github.com/sayanarijit/xplr/releases/tag/v0.9.1) -> [v0.10.2](https://github.com/sayanarijit/xplr/releases/tag/v0.10.2)
|
||||
|
||||
- [`config.yml`](https://github.com/sayanarijit/xplr/blob/85696ded7a/src/config.yml) has been fully replaced with [`init.lua`](https://github.com/sayanarijit/xplr/blob/main/src/init.lua). If you have a lot of customization in your `config.yml`, [xplr-yml2lua](https://github.com/sayanarijit/xplr-yml2lua) can help you with migrating it to `init.lua`.
|
||||
- `Handlebars` templates has been replaced with [Lua functions](https://github.com/sayanarijit/xplr/blob/bfdb7736b99bc3c5ae53e7d621ba0e7ca2299b14/src/init.lua#L2005-L2064). You can either remove the customizations or overwrite the functions accordingly.
|
||||
- Added new messages `CallLua` and `CallLuaSilently` to call lua functions. The app state will be passed as input to the functions, and the returned messages will be handled by xplr. `CallLua` and `CallLuaSilently` are more flexible (and probably faster) alternatives to `Call`, `CallSilently`, `BashExec` and `BashExecSilently`. [e.g.](https://github.com/sayanarijit/xplr/pull/177#issue-650643573)
|
||||
|
||||
#### [v0.9.0](https://github.com/sayanarijit/xplr/releases/tag/v0.9.0) -> [v0.9.1](https://github.com/sayanarijit/xplr/releases/tag/v0.9.1)
|
||||
|
||||
- You can now set `remaps: {key: null}` to un-map a key.
|
||||
- `gx` will open the item under focus.
|
||||
- New key map `:sx` will open the selected items.
|
||||
|
||||
#### [v0.8.0](https://github.com/sayanarijit/xplr/releases/tag/v0.8.0) -> [v0.9.0](https://github.com/sayanarijit/xplr/releases/tag/v0.9.0)
|
||||
|
||||
Your previous config should mostly work fine. However, in case you are using `SwitchMode` heavily in your custom config, follow along.
|
||||
|
||||
- Introduced new message `PopMode`. You might want to use this message instead of `SwitchMode*` when returning back to the previous mode.
|
||||
- After using (the group of) `PopMode` and `SwitchMode*` messages, you are now required to `Refresh` manually to avoid the UI lag.
|
||||
- Pressing any invalid key will now lead you to the `recover` mode and will protect you from typing further invalid keys. Press `esc` to escape the `recover` mode.
|
||||
- Introduced new message `LogWarning`, similar to other `Log*` messages.
|
||||
- Creating files and directories has been optimized for batch creation.
|
||||
|
||||
#### [v0.7.2](https://github.com/sayanarijit/xplr/releases/tag/v0.7.2) -> [v0.8.0](https://github.com/sayanarijit/xplr/releases/tag/v0.8.0)
|
||||
|
||||
If you have made changes to the config file,
|
||||
|
||||
- Replace message `Explore` with `ExplorePwd` or `ExplorePwdAsync` or probably `ExploreParentsAsync`.
|
||||
- Pipe `$XPLR_PIPE_FOCUS_OUT` has been removed. Use `$XPLR_FOCUS_PATH` env var instead.
|
||||
- You might want to review your path escaping logics. For e.g. use `echo FocusPath: "'"$PWD"'" >> $PIPE` instead of `echo "FocusPath: $PWD" >> $PIPE`.
|
||||
|
||||
#### [v0.7.0](https://github.com/sayanarijit/xplr/releases/tag/v0.7.0) -> [v0.7.2](https://github.com/sayanarijit/xplr/releases/tag/v0.7.2)
|
||||
|
||||
- Just update the `version` in your config file.
|
||||
- For version >= `v0.7.1`, you might want to free up or remap the `tab` key in `search` mode to enable easy selection during search.
|
||||
|
||||
#### [v0.6.0](https://github.com/sayanarijit/xplr/releases/tag/v0.6.0) -> [v0.7.0](https://github.com/sayanarijit/xplr/releases/tag/v0.7.0)
|
||||
|
||||
If you haven't made any changes in the config file, you should be fine just updating the version number. Else,
|
||||
|
||||
- You can make the `Table: ...`, `InputAndLogs: ...` layout values null and define the common properties in the `general.panel_ui` instead.
|
||||
|
||||
#### [v0.5.13](https://github.com/sayanarijit/xplr/releases/tag/v0.5.13) -> [v0.6.0](https://github.com/sayanarijit/xplr/releases/tag/v0.6.0)
|
||||
|
||||
If you haven't made any changes in the config file, you should be fine just updating the version number. Else,
|
||||
|
||||
- Rename `add_modifier: {bits: 1}` to `add_modifiers: [Bold]`, `sub_modifier: {bits: 1}` to `sub_modifiers: [Bold]` and so on.
|
||||
- Rename `percentage: 10` to `Percentage: 10`, `ratio: 1` to `Ratio: 1` and so on.
|
||||
- You might want to free up or remap the `ctrl-w` key binding in `default` mode to enable layout switching.
|
||||
|
||||
Optionally, checkout this new theme to learn more about what's new.
|
||||
|
||||
#### [v0.5.0](https://github.com/sayanarijit/xplr/releases/tag/v0.5.0) -> [v0.5.13](https://github.com/sayanarijit/xplr/releases/tag/v0.5.13)
|
||||
|
||||
- Just update the `version` in your config file.
|
||||
- For versions >= `v0.5.8`, you can set `$OPENER` env var to declare a global GUI file opener (to open files using keys `gx`).
|
||||
- You might also want to update other mappings to handle files with names starting with `-` (hiphen). For example, instead of `rm ${filename}` use `rm -- ${filename}`. Same goes for `cp`, `mv`, `cat`, `touch` etc.
|
||||
- For version >= `v0.5.13`, you might want to use the more specific `SwitchModeBuiltin` and `SwitchModeCustom` messages instead of the general `SwitchMode` message.
|
||||
|
||||
#### [v0.4.3](https://github.com/sayanarijit/xplr/releases/tag/v0.4.3) -> [v0.5.0](https://github.com/sayanarijit/xplr/releases/tag/v0.5.0)
|
||||
|
||||
If you haven't have any changes in the config file, you should be fine just updating the version number.
|
||||
|
||||
Else do the following
|
||||
|
||||
- Replace `{RelativePathIs, case_sensitive: true}` with `RelativePathIs`.
|
||||
- Replace `{RelativePathIs, case_sensitive: false}` with `IRelativePathIs`.
|
||||
- Do the same with other filters you are using.
|
||||
- You might want to update your `backspace` handling to use the `RemoveInputBufferLastCharacter` message.
|
||||
- You might want to free-up `f`, `s`, `ctrl-r` and `ctrl-u` key bindings in the default mode, or remap them.
|
||||
- You might want to use the new UI variables.
|
||||
- Update your config version to `v0.5.0`.
|
||||
|
||||
#### [v0.4.2](https://github.com/sayanarijit/xplr/releases/tag/v0.4.2) -> [v0.4.3](https://github.com/sayanarijit/xplr/releases/tag/v0.4.3)
|
||||
|
||||
|
||||
If you have customized `general.table.row.cols`, you might want to [update it](https://github.com/sayanarijit/xplr/blob/af1cda5762/src/config.yml#L46-L48) to use the new variables with better symlink support.
|
||||
|
||||
#### [v0.4.1](https://github.com/sayanarijit/xplr/releases/tag/v0.4.1) -> [v0.4.2](https://github.com/sayanarijit/xplr/releases/tag/v0.4.2)
|
||||
|
||||
In case you have mapped the keys `q`, `ctrl-i` and `ctrl-o`, you may want to revisit the default mode key bindings and remap accordingly to use the new functionalities.
|
||||
|
||||
#### [v0.3.13](https://github.com/sayanarijit/xplr/releases/tag/v0.3.13) -> [v0.4.1](https://github.com/sayanarijit/xplr/releases/tag/v0.4.1)
|
||||
|
||||
A lot has changed (apologies). But I promise from now on, upgrading will be much less painful (thanks to [@maximbaz](https://github.com/maximbaz)'s valuable [inputs](https://github.com/sayanarijit/xplr/issues/45#issue-854447104) and [code reviews](https://github.com/sayanarijit/xplr/pull/47)).
|
||||
|
||||
So, to start with the upgrade, let's remove everything from your config file except the `version` field and your custom modifications. If `version` is the only thing remaining, update it to `v0.4.1` and you are done.
|
||||
|
||||
Else, do the following
|
||||
|
||||
- Rename `general.focused_ui` to `general.focus_ui` ([see here](https://github.com/sayanarijit/xplr/blob/055c1083d6/src/config.yml#L124)).
|
||||
- Rename `filetypes` to `node_types`. ([see here](https://github.com/sayanarijit/xplr/blob/055c1083d6/src/config.yml#L145))
|
||||
- Rename `custom` field to `meta`. ([see here](https://github.com/sayanarijit/xplr/blob/055c1083d6/src/config.yml#L154-L155))
|
||||
- Move `icon` to `meta.icon`. ([see here](https://github.com/sayanarijit/xplr/blob/055c1083d6/src/config.yml#L45))
|
||||
- Rename `normal_ui` to `default_ui`. ([see here](https://github.com/sayanarijit/xplr/blob/055c1083d6/src/config.yml#L114))
|
||||
- Split `modes` into `modes.builtin` and `modes.custom` ([see here](https://github.com/sayanarijit/xplr/blob/055c1083d6/src/config.yml#L180-L181)). Migrate your custom modes to `modes.custom`. And copy only the changes in the in-built modes in `modes.builtin`.
|
||||
- Finally, update the `version` to `v0.4.1`.
|
||||
|
||||
#### [v0.3.8](https://github.com/sayanarijit/xplr/releases/tag/v0.3.8) -> [v0.3.13](https://github.com/sayanarijit/xplr/releases/tag/v0.3.13)
|
||||
Your current config should work fine. However, you might want to replace some `Call` and `BashExec` messages with `CallSilently` and `BashExecSilently` to remove the flickering of the screen.
|
||||
|
||||
If you haven't made any changes to the configuration, you can delete and regenerate it.
|
||||
|
||||
Else, do the following
|
||||
|
||||
- Check the new default config by temporarily removing your current config (with backup) and dumping the new config.
|
||||
- Search for `Call` and `BashExec` in the new config.
|
||||
- Compare and probably replace the associated actions in your current config
|
||||
|
||||
#### [v0.3.0](https://github.com/sayanarijit/xplr/releases/tag/v0.3.0) -> [v0.3.8](https://github.com/sayanarijit/xplr/releases/tag/v0.3.8)
|
||||
|
||||
Your current config should work fine. However, you might want to replace some `ResetNodeFilters` messages with `RemoveNodeFilter` and `RemoveNodeFilterFromInput` to get a better search and filter experience.
|
||||
|
||||
If you haven't made any changes to the configuration, you can delete and regenerate it.
|
||||
|
||||
Else, do the following
|
||||
|
||||
- Check the new default config by temporarily removing your current config (with backup) and dumping the new config.
|
||||
- Search for `RemoveNodeFilterFromInput` in the new config.
|
||||
- Compare and probably replace the associated actions in your current config.
|
||||
|
||||
#### v0.2.14 -> [v0.3.0](https://github.com/sayanarijit/xplr/releases/tag/v0.3.0)
|
||||
|
||||
If you haven't made any changes to the configuration, you can delete and regenerate it.
|
||||
|
||||
Else do the following:
|
||||
- `$XPLR_APP_YAML` has been removed. You can use `Debug` to export the app state.
|
||||
- `$XPLR_RESULT` has been ported to file `$XPLR_PIPE_RESULT_OUT`. Use `cat` instead of `echo`, `<` instead of `<<<` etc.
|
||||
- `$XPLR_GLOBAL_HELP_MENU` has been ported to
|
||||
file `$XPLR_PIPE_GLOBAL_HELP_MENU_OUT`. Use `cat` instead of `echo`, `<` instead of `<<<` etc.
|
||||
- `$XPLR_DIRECTORY_NODES` has been ported to
|
||||
file `$XPLR_PIPE_DIRECTORY_NODES_OUT`. Use `cat` instead of `echo`, `<` instead of `<<<` etc.
|
||||
- `$XPLR_LOGS` has been ported to file `$XPLR_PIPE_LOGS_OUT`. Use `cat` instead of `echo`, `<` instead of `<<<` etc.
|
||||
- `$XPLR_PIPE_RESULT` has been ported to file `$XPLR_PIPE_RESULT_OUT`. Use `cat` instead of `echo`, `<` instead of `<<<` etc.
|
||||
- Finally, update the `version` in your config file.
|
||||
@ -0,0 +1,20 @@
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<title>xplr book</title>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="initial-scale=1, maximum-scale=1, user-scalable=no">
|
||||
<style>
|
||||
div {
|
||||
margin: 18pt;
|
||||
font-size: 24pt;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<h1>xplr book</h1>
|
||||
<ul>
|
||||
<li><a href="en/index.html">English</a></li>
|
||||
</ul>
|
||||
</body>
|
||||
</html>
|
||||
Loading…
Reference in New Issue