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.
Features
Hackable
xplr is built with configurability in mind. So it allows you to perform a vast set of operations and make it behave just the way you want.
A few things you can do with the xplr configuration
Fast
Although speed is not the primary concern, xplr is already fast enough so that
you can take it out for a walk into your node_modules
or /nix/store
any
time you want. I currently
measure the most commonly used operations
and I have seen it improve significantly over time, and it's only the start.
Tip: A quick and easy way to optimize UI rendering is reducing the number of columns in the table.
Note: If you feel xplr is not behaving at its optimal, this is probably because I am waiting for someone to complain. I want to avoid optimizing things I don't need to, because optimization often requires either complexity or feature sacrifice or both.
Minimalist
xplr prefers to stay minimal, both in terms of features and binary size, but
just like speed, minimalism isn't as aggressively pursued as configurability.
If adding some feature, lines of code, or a dependency allows the users to be a
little more productive or allows xplr to be a little more configurable, it will
be considered. But of-course, the bulk vs productivity gain per user
balance
will also be considered in the decision-making.
Other features
- Embedded LuaJIT for portability and extensibility.
- Switchable recover mode: Saves you from doing unwanted things when in a hurry.
- Sane (vim-like) defaults:
- Use
h
,j
,k
,l
or arrow keys for basic navigation. - Go to top using
g
g
, and bottom usingG
. - Travel history using
ctrl-o
andctrl-i
. - Go to home directory using
~
. - Enter search mode with
/
orctrl-f
. - Go to absolute index (e.g.
4
) using4
enter
or:
4
enter
. - Go to relative index (e.g.
4
down
) using4
down
or:
4
down
. - Follow symlink using
g
f
. - Open in GUI using
g
x
. - Spawn terminal using
:
!
. - Toggle selection using
v
orspace
. - Toggle select all using
V
orctrl-a
. - Clear selections using
ctrl-u
.
- Use
- Separate keys for navigation: navigation keys are separated from the action keys (e.g. file opening action) to avoid mistakenly performing unwanted actions while navigating.
- Always visible panels to save you brain cycles:
- Selection list.
- Help menu.
- Input & logs.
- Filter and sort pipeline.
- Batch creation: Create multiple files and directories without repeating keys.
- Batch sort & filter: Apply sorters and filters in without repeating keys.
- Custom file properties: Display custom file properties with custom colors in the table using Lua functions.
- Input buffer: Read user input using the built-in input buffer with customizable behavior.
- Switchable layouts: Switch layouts dynamically without leaving
xplr
. - Saved locations: Never lose context when traveling back and forth directories.
- Auto refresh state: Auto refresh app state when the
$PWD
changes. - Manually refresh UI when other apps mess it up.
- FIFO-based previews: Easy to manage FIFO file that can be used to integrate with previewers.
- Different quit options:
- Quit with success without any output (
q
). - Quit with success and the result printed on stdout (
enter
). - Quit with success and the present working directory printed on stdout
(
:
q
p
). - Quit with success and the path under focus printed on stdout
(
:
q
f
). - Quit with success and the selection printed on stdout
(
:
q
s
). - Quit with failure (
ctrl-c
).
- Quit with success without any output (
Quickstart
Nice to you have here! Let's quickly start with the following steps:
Try in Docker
If you prefer to try it before installing, here's the snippet for your convenience.
docker run -w / -it --rm ubuntu sh -uec '
apt-get update -y
apt-get install -y wget tar vim
wget https://github.com/sayanarijit/xplr/releases/latest/download/xplr-linux.tar.gz
tar -xzvf xplr-linux.tar.gz
./xplr
'
Install
You can install xplr using one of the following ways. Each has their own advantages and limitations.
For example, the Direct Download, From crates.io, and 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 on the releases is to watch the repository.
Community Maintained Repositories
xplr can be installed from one of the following community maintained repositories:
Cross-platform
Snap
snap install xplr --classic
Nixpkgs
nix-env -f https://github.com/NixOS/nixpkgs/tarball/master -iA xplr
Arch Linux
Official Community Repo
sudo pacman -S xplr
AUR
Binary version:
paru -S xplr-bin
Git version:
paru -S xplr-git
Void Linux
void-templates by shubham
macOS
MacPorts
sudo port selfupdate
sudo port install xplr
Homebrew
Stable branch:
brew install xplr
HEAD branch:
brew install --head xplr
FreeBSD
ports
pkg install xplr
Or
cd /usr/ports/misc/xplr
make install clean
NetBSD
pkgsrc
pkgin install xplr
Or
cd /usr/pkgsrc/sysutils/xplr
make install
Direct Download
One can directly download the standalone binary from the releases.
Currently, the following options are available for direct download:
Command-line instructions:
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
Prerequisites:
Command-line instructions:
cargo install --locked --force xplr
Build From Source
Prerequisites:
Command-line instructions:
# Clone the repository
git clone https://github.com/sayanarijit/xplr.git
cd xplr
# Build
cargo build --locked --release --bin xplr
# Place in $PATH
sudo cp target/release/xplr /usr/local/bin/
Android
Termux
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
pkg install rustc cargo make
-
Install
xplr
cargo install --locked --force xplr
-
Setup storage
termux-setup-storage
-
Setup config and runtime dir
export XDG_CONFIG_HOME="$PWD/storage/.config" export XDG_RUNTIME_DIR="$PWD/storage/run" mkdir -p "$XDG_CONFIG_HOME" "$XDG_RUNTIME_DIR"
-
Run
~/.cargo/bin/xplr
Post Install
Once installed, use the following steps to setup and run xplr.
Create the customizable config file
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 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. Also, the default configuration is meant to be overwritten to suit your workflow.
Run
xplr
Configuration
xplr can be configured using Lua via a special file
named init.lua
(example), 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.
How Config Is Loaded
When xplr loads, it first executes the built-in init.lua to set the default values, which 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
config
The xplr configuration, exposed as xplr.config
Lua API contains the
following fields:
Key Bindings
Key bindings define how each keyboard input will be handled while in a specific mode.
See the Default key bindings for example.
To configure or work with key bindings, visit Configure Key Bindings.
In case you need help debugging key bindings or to understand the system DYI way, refer to the Debug Key Bindings guide.
Configure Key Bindings
In xplr, each keyboard input passes through a bunch of handlers (e.g. on_key
,
on_number
, default
etc.) in a given order. If any of the handlers is
configured to with an action, it will intercept the key and produce
messages for xplr to handle.
Key Bindings
Key bindings contains the following information:
- on_key
- on_alphabet
- on_number
- on_alphanumeric
- on_special_character
- on_character
- on_navigation
- on_function
- default
on_key
Type: mapping of Key to nullable Action
Defines what to do when an exact key is pressed.
on_alphabet
Type: nullable Action
An action to perform if the keyboard input is an alphabet and is not mapped via the on_key field.
on_number
Type: nullable Action
An action to perform if the keyboard input is a number and is not mapped via the on_key field.
on_alphanumeric
Type: nullable Action
An action to perform if the keyboard input is alphanumeric and is not mapped via the on_key, on_alphabet or on_number field.
on_special_character
Type: nullable Action
An action to perform if the keyboard input is a special character and is not mapped via the on_key field.
on_character
Type: nullable Action
An action to perform if the keyboard input is a character and is not mapped via the on_key, on_alphabet, on_number, on_alphanumeric or on_special_character field.
on_navigation
Type: nullable Action
An action to perform if the keyboard input is a navigation key and is not mapped via the on_key field.
on_function
Type: nullable Action
An action to perform if the keyboard input is a function key and is not mapped via the on_key field.
default
Type: nullable Action
Default action to perform in case if a keyboard input not mapped via any of the
on_*
fields mentioned above.
Key
A key can be one of the following:
- 0, 1, ... 9
- a, b, ... z
- A, B, ... Z
- f1, f2, ... f12
- backspace
- left
- right
- up
- down
- home
- end
- page-up
- page-down
- back-tab
- delete
- insert
- enter
- tab
- esc
- ctrl-a, ctrl-b, ... ctrl-z
- ctrl-backspace, ctrl-left, ... ctrl-esc
- alt-a, alt-b, ... alt-z
And finally, the special characters - including space (" "
) with their ctrl
bindings.
Action
An action contains the following information:
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 to send.
The list of messages to send when a key is pressed.
Tutorial: Adding a New Mode
Assuming xplr is installed and setup, let's add our own mode to integrate xplr with 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.
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, $XPLR_PIPE_MSG_IN
,
$XPLR_PIPE_DIRECTORY_NODES_OUT
are
environment variables exported by xplr
before executing the command. They contain the path to the
input and output 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.
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.
Visit Awesome Plugins for more integration options.
Default Key Bindings
The default key binding is inspired by vim and slightly overlaps with nnn, but it's supposed to be customized as per user requirements.
When you press ?
in default mode, you can see the complete list
of modes 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 | |
ctrl-c | terminate | |
ctrl-r | reset filters | |
ctrl-u | clear filters | |
enter | esc | done |
r | relative does contain |
number
key | remaps | action |
---|---|---|
ctrl-c | terminate | |
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 |
---|---|---|
ctrl-c | terminate | |
ctrl-n | down | down |
ctrl-p | up | up |
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 |
---|---|---|
ctrl-c | terminate | |
enter | create file | |
esc | cancel |
create directory
key | remaps | action |
---|---|---|
ctrl-c | terminate | |
enter | create directory | |
esc | cancel |
rename
key | remaps | action |
---|---|---|
ctrl-c | terminate | |
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 | |
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 |
---|---|---|
ctrl-c | terminate | |
enter | apply filter | |
esc | cancel |
relative path does not contain
key | remaps | action |
---|---|---|
ctrl-c | terminate | |
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 |
Debug Key Bindings
If you need help debugging or understanding key bindings DYI way, you can
create a test.lua
file with the following script, launch xplr with
xplr --extra-config test.lua
, press #
and play around.
xplr.config.modes.builtin.default.key_bindings.on_key["#"] = {
help = "test",
messages = {
"PopMode",
{ SwitchModeCustom = "test" },
},
}
xplr.config.modes.custom.test = {
name = "test",
key_bindings = {
on_key = {
["1"] = {
messages = {
{ LogInfo = "on_key called" },
},
},
a = {
messages = {
{ LogInfo = "on_key called" },
},
},
["`"] = {
messages = {
{ LogInfo = "on_key called" },
},
},
tab = {
messages = {
{ LogInfo = "on_key called" },
},
},
esc = {
messages = {
"PopMode",
},
},
["ctrl-c"] = {
messages = {
"Terminate",
},
},
f1 = {
messages = {
{ LogInfo = "on_key called" },
},
},
},
on_alphabet = {
messages = {
{ LogInfo = "on_alphabet called" },
},
},
on_number = {
messages = {
{ LogInfo = "on_number called" },
},
},
-- on_alphanumeric = {
-- messages = {
-- { LogInfo = "on_alphanumeric called" },
-- },
-- },
on_special_character = {
messages = {
{ LogInfo = "on_special_character called" },
},
},
-- on_character = {
-- messages = {
-- { LogInfo = "on_character called" },
-- },
-- },
on_navigation = {
messages = {
{ LogInfo = "on_navigation called" },
},
},
on_function = {
messages = {
{ LogInfo = "on_function called" },
},
},
default = {
messages = {
{ LogInfo = "default called" },
},
},
},
}
General Config
This configuration is 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.
enable_recover_mode
Type: boolean
Set it to true
if you want to enable a safety feature that will save you from
yourself when you type recklessly.
hide_remaps_in_help_menu
Type: boolean
Set it to true
if you want to hide all remaps in the help menu.
initial_layout
Type: string
The name of one of the layout to use when xplr loads.
initial_mode
Type: string
The name of one of the mode to use when xplr loads.
initial_sorting
Type: list of Node Sorter Applicable
Initial group if sorters applied to the nodes list in the table.
table.style
Type: Style
Default style of the table.
table.col_spacing
Type: nullable integer
Default spacing of the columns in the table.
table.col_widths
Type: nullable list of Constraint
Width of each column in the table.
table.header.height
Type: nullable integer
Height of the table header.
table.header.style
Type: Style
Style of table header.
table.header.cols
Type: list of column configuration
Each column config contains format
field (string) and style
field
(Style), that define the content and style of header.
table.row.height
Type: nullable integer
Height of each row in the table.
table.row.style
Type: Style
Style of table rows.
table.row.cols
Type: list of column configuration
Each column config contains format
field (string) and style
field
(Style).
However, unlike table.header.cols, the format
field here
points to a column renderer function.
table.tree
Type: list of tree configuration
It expects a list of three items. The first component of the tree, then the middle components, and finally the last component of the tree.
Each item requires the format
field which is a string, and the style
field,
which is the Style object.
Example:
xplr.config.general.table.tree = {
{ format = "├─", style = { add_modifiers = { "Bold" }, bg = nil, fg = "Blue", sub_modifiers = nil } },
{ format = "├─", style = { add_modifiers = { "Bold" }, bg = nil, fg = "Blue", sub_modifiers = nil } },
{ format = "╰─", style = { add_modifiers = { "Bold" }, bg = nil, fg = "Blue", sub_modifiers = nil } },
}
start_fifo
Type: nullable string
Start a FIFO file when xplr loads. It will track the absolute path of the file under focus.
prompt.format
Type: string
This is the shape of the prompt for the input buffer.
prompt.style
Type: Style
Style of the input prompt.
logs.error.format
Type: string
The string to indicate an error in logs.
logs.error.style
Type: Style
Style for errors shown in logs.
logs.info.format
Type: string
The string to indicate an information in logs.
logs.info.style
Type: Style
Style for infos shown in logs.
logs.success.format
Type: string
The string to indicate a successful operation in logs.
logs.success.style
Type: Style
Style for successful operations in logs.
logs.warning.format
Type: string
The string that indicates a warning in logs.
logs.warning.style
Type: Style
Style for warnings in logs.
default_ui.prefix
Type: nullable string
The content that is placed before the item name for each row.
default_ui.suffix
Type: nullable string
The content which is appended to each item name for each row.
default_ui.style
Type: Style
Style for the default user interface.
focus_ui.prefix
Type: nullable string
The string placed before the item name for a focused row.
focus_ui.suffix
Type: nullable string
The string placed after the item name for a focused row.
focus_ui.style
Type: Style
Style for focused elements.
selection_ui.prefix
Type: nullable string
The string that is placed before the item name for a selected row.
selection_ui.suffix
Type: nullable string
The string placed after the item name for a selected row.
selection_ui.style
Type: Style
Style for selected rows.
focus_selection_ui.prefix
Type: nullable string
The string placed before item name for a selected row that gets the focus.
focus_selection_ui.suffix
Type: nullable string
The string placed after the item name for a selected row that gets the focus.
focus_selection_ui.style
Type: Style
Style for a selected row that gets the focus.
sort_and_filter_ui.separator.format
Type: nullable string
The shape of the separator for the Sort & filter
panel.
sort_and_filter_ui.separator.style
Type: Style
Style for Sort & filter
panel separator.
sort_and_filter_ui.default_identifier.format
Type: nullable string
The content of the default identifier in Sort & filter
panel.
sort_and_filter_ui.default_identifier.style
Type: Style
Style for the default identifier in Sort & filter
panel.
sort_and_filter_ui.filter_identifiers
Type: Table with filter name as key
The value contains format field (string) and style field (Style), that define the content and style for the given filter.
Example:
xplr.config.general.sort_and_filter_ui.filter_identifiers.AbsolutePathDoesContain = {
format = "abs=~",
style = { add_modifiers = { "Bold" }, bg = nil, fg = nil, sub_modifiers = nil },
}
sort_and_filter_ui.sort_direction_identifiers.forward.format
Type: nullable string
The shape of the forward direction indicator for sort identifiers in
Sort & filter
panel.
sort_and_filter_ui.sort_direction_identifiers.forward.style
Type: Style
Style of forward direction indicator.
sort_and_filter_ui.sort_direction_identifiers.reverse.format
Type: nullable string
The shape of the reverse direction indicator for sort identifiers in
Sort & filter
panel.
sort_and_filter_ui.sort_direction_identifiers.reverse.style
Type: Style
Style of reverse direction indicator.
sort_and_filter_ui.sorter_identifiers
Type: Table with sorter name as key
The value contains format field (string) and style field (Style), that define the content and style for the given sorter.
Example:
sort_and_filter_ui.sorter_identifiers.ByCanonicalAbsolutePath = {
format = "[c]abs",
style = { add_modifiers = nil, bg = nil, fg = "Yellow", sub_modifiers = nil },
}
panel_ui.default.borders
Type: nullable list of strings
Defines where to show borders for the panels.
The possible values are any combination of: "Top", "Bottom", "Left" and "Right".
Example:
-- Show Left and Right borders only
xplr.config.general.panel_ui.default.borders = {
"Right",
"Left",
}
panel_ui.default.style
Type: Style
Default style for panels.
panel_ui.default.title.format
Type: nullable string
The content for panel title.
panel_ui.default.title.style
Type: Style
Style for panel title.
panel_ui.help_menu.borders
Type: nullable list of strings
Defines where to show borders for the Help
panel.
The possible values are any combination of: "Top", "Bottom", "Left" and "Right".
panel_ui.help_menu.style
Type: Style
Style for Help
panel.
panel_ui.help_menu.title.format
Type: nullable string
The content for Help
panel title.
panel_ui.help_menu.title.style
Type: Style
Style for Help
panel title.
panel_ui.input_and_logs.borders
Type: nullable list of strings
Defines where to show borders for the Input
& Logs
panel.
The possible values are any combination of: "Top", "Bottom", "Left" and "Right".
panel_ui.input_and_logs.style
Type: Style
Style for Input
& Logs
panel.
panel_ui.input_and_logs.title.format
Type: nullable string
The content for the Input
and Logs
panel title.
panel_ui.input_and_logs.title.style
Type: Style
Style for Input
& Logs
panel title.
panel_ui.selection.borders
Type: nullable list of strings
Defines where to show borders for the Selection
panel.
The possible values are any combination of: "Top", "Bottom", "Left" and "Right".
panel_ui.selection.style
Type: Style
Style for Selection
panel.
panel_ui.selection.title.format
Type: nullable string
The content for Selection
panel title.
panel_ui.selection.title.style
Type: Style
Style for Selection
panel title.
panel_ui.sort_and_filter.borders
Type: nullable list of strings
Defines where to show borders for the Sort & filter
panel.
The possible values are any combination of: "Top", "Bottom", "Left" and "Right".
panel_ui.sort_and_filter.style
Type: Style
Style for Sort & filter
panel.
panel_ui.sort_and_filter.title.format
Type: nullable string
The content for Sort & filter
panel title.
panel_ui.sort_and_filter.title.style
Type: Style
Style for Sort & filter
panel title.
Modes
xplr is a modal file explorer. That means the users switch between different modes, each containing a different set of key bindings to avoid clashes. Users can switch between these modes at run-time.
The modes can be configured using the xplr.config.modes
Lua API.
It contains the following fields:
builtin
Type: mapping of string and 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 to see what each mode does.
custom
Type: mapping of string and Mode
This is exposed by the xplr.config.modes.custom
API.
It allows the users to define custom modes.
Example:
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
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
The key bindings available in that mode.
layout
Type: nullable Layout
If specified, this layout will be used to render the UI.
Message
You can think of xplr as a server. Just like web servers listen to HTTP requests, xplr listens to messages.
You can send these messages to an xplr session in the following ways:
- Via key bindings
- Via Lua function calls
- Via shell command using the input pipe
Format
To send messages using the key bindings or Lua function calls, messages are represented in Lua syntax. For example:
- "Quit"
- { FocusPath = "/path/to/file" }
- { Call = { command = "bash", args = { "-c", "read -p test" } } }
However, to send messages using the input pipe, they need to be represented using YAML (or JSON) syntax. For example:
- Quit
- FocusPath: "/path/to/file"
- Call: { command: bash, args: ["-c", "read -p test"] }
Full List of Messages
"ExplorePwd"
YAML: ExplorePwd
Explore the present working directory and register the filtered nodes. This operation is expensive. So, try to avoid using it too often.
"ExplorePwdAsync"
YAML: ExplorePwdAsync
Explore the present working directory and register the filtered nodes asynchronously.
This operation happens asynchronously. That means, the xplr directory buffers won't be updated
immediately. Hence, it needs to be used with care and probably with special checks in place.
To explore $PWD
synchronously, use ExplorePwd
instead.
"ExploreParentsAsync"
YAML: ExploreParentsAsync
Explore the present working directory along with its parents and register the filtered nodes.
This operation happens asynchronously. That means, the xplr directory buffers won't be updated
immediately. Hence, it needs to be used with care and probably with special checks in place.
To explore just the $PWD
synchronously, use ExplorePwd
instead.
"Refresh"
YAML: Refresh
Refresh the UI.
But it will not re-explore the directory if the working directory is the same.
If there is some change in the working directory and you want to re-explore it,
use the Explore
message instead.
Also, it will not clear the screen. Use ClearScreen
for that.
"ClearScreen"
YAML: ClearScreen
Clears the screen.
"FocusNext"
YAML: FocusNext
Focus next node.
{ FocusNextByRelativeIndex = int }
YAML: FocusNextByRelativeIndex: int
Focus on the n
th node relative to the current focus where n
is a given value.
YAML Example: FocusNextByRelativeIndex: 2
Lua Example: { FocusNextByRelativeIndex = 2 }
"FocusNextByRelativeIndexFromInput"
YAML: FocusNextByRelativeIndexFromInput
Focus on the n
th node relative to the current focus where n
is read from
the input buffer.
"FocusPrevious"
YAML: FocusPrevious
Focus on the previous item.
{ FocusPreviousByRelativeIndex = int }
YAML: FocusPreviousByRelativeIndex: int
Focus on the -n
th node relative to the current focus where n
is a given value.
YAML Example: FocusPreviousByRelativeIndex: 2
Lua Example: { FocusPreviousByRelativeIndex = 2 }
"FocusPreviousByRelativeIndexFromInput"
YAML: FocusPreviousByRelativeIndexFromInput
Focus on the -n
th node relative to the current focus where n
is read from
the input buffer.
"FocusFirst"
YAML: FocusFirst
Focus on the first node.
"FocusLast"
YAML: FocusLast
Focus on the last node.
{ FocusPath = "string" }
YAML: FocusPath: string
Focus on the given path.
YAML Example: FocusPath: /path/to/file
Lua Example: { FocusPath = "/path/to/file" }
"FocusPathFromInput"
YAML: FocusPathFromInput
Focus on the path read from input buffer.
{ FocusByIndex = int }
YAML: FocusByIndex: int
Focus on the absolute n
th node where n
is a given value.
YAML Example: FocusByIndex: 2
Lua Example: { FocusByIndex = 2 }
"FocusByIndexFromInput"
YAML: FocusByIndexFromInput
Focus on the absolute n
th node where n
is read from the input buffer.
{ FocusByFileName = "string" }
YAML: FocusByFileName: string
Focus on the file by name from the present working directory.
YAML Example: FocusByFileName: filename.ext
Lua Example: { FocusByFileName = "filename.ext" }
{ ChangeDirectory = "string" }
YAML: ChangeDirectory: string
Change the present working directory ($PWD)
YAML Example: ChangeDirectory: /path/to/directory
Lua Example: { ChangeDirectory = "/path/to/directory" }
"Enter"
YAML: Enter
Enter into the currently focused path if it's a directory.
"Back"
YAML: Back
Go back to the parent directory.
"LastVisitedPath"
YAML: LastVisitedPath
Go to the last path visited.
"NextVisitedPath"
YAML: NextVisitedPath
Go to the next path visited.
"FollowSymlink"
YAML: FollowSymlink
Follow the symlink under focus to its actual location.
{ UpdateInputBuffer = Input Opertaion }
YAML: BufferInput: Input Operation
Update the input buffer using cursor based operations.
YAML Example: UpdateInputBuffer: GoToPreviousWord
Lua Example: { UpdateInputBuffer = "GoToPreviousWord" }
"UpdateInputBufferFromKey"
YAML: UpdateInputBufferFromKey
Update the input buffer from the key read from keyboard input.
{ BufferInput = "string" }
YAML: BufferInput: string
Append/buffer the given string into the input buffer.
YAML Example: BufferInput: foo
Lua Example: { BufferInput = "foo" }
"BufferInputFromKey"
YAML: BufferInputFromKey
Append/buffer the characted read from a keyboard input into the input buffer.
{ SetInputBuffer = "string" }
YAML: SetInputBuffer: string
Set/rewrite the input buffer with the given string. When the input buffer is not-null (even if empty string) it will show in the UI.
YAML Example: SetInputBuffer: foo
Lua Example: { SetInputBuffer = "foo" }
"RemoveInputBufferLastCharacter"
YAML: RemoveInputBufferLastCharacter
Remove input buffer's last character.
"RemoveInputBufferLastWord"
YAML: RemoveInputBufferLastWord
Remove input buffer's last word.
"ResetInputBuffer"
YAML: ResetInputBuffer
Reset the input buffer back to null. It will not show in the UI.
{ SwitchMode = "string" }
YAML: SwitchMode: string
Switch input mode. It clears the input buffer.
NOTE: To be specific about which mode to switch to, use
SwitchModeBuiltin
orSwitchModeCustom
instead.
YAML Example: SwitchMode: default
Lua Example: { SwitchMode = "default" }
{ SwitchModeKeepingInputBuffer = "string" }
YAML: SwitchModeKeepingInputBuffer: string
Switch input mode. It keeps the input buffer.
NOTE: To be specific about which mode to switch to, use
SwitchModeBuiltinKeepingInputBuffer
orSwitchModeCustomKeepingInputBuffer
instead.
YAML Example: SwitchModeKeepingInputBuffer: default
Lua Example: { SwitchModeKeepingInputBuffer = "default" }
{ SwitchModeBuiltin = "string" }
YAML: SwitchModeBuiltin: string
Switch to a builtin mode. It clears the input buffer.
YAML Example: SwitchModeBuiltin: default
Lua Example: { SwitchModeBuiltin = "default" }
{ SwitchModeBuiltinKeepingInputBuffer = "string" }
YAML: SwitchModeBuiltinKeepingInputBuffer: string
Switch to a builtin mode. It keeps the input buffer.
YAML Example: SwitchModeBuiltinKeepingInputBuffer: default
Lua Example: { SwitchModeBuiltinKeepingInputBuffer = "default" }
{ SwitchModeCustom = "string" }
YAML: SwitchModeCustom: string
Switch to a custom mode. It clears the input buffer.
YAML Example: SwitchModeCustom: my_custom_mode
Lua Example: { SwitchModeCustom = "my_custom_mode" }
{ SwitchModeCustomKeepingInputBuffer = "string" }
YAML: SwitchModeCustom: string
Switch to a custom mode. It keeps the input buffer.
YAML Example: SwitchModeCustomKeepingInputBuffer: my_custom_mode
Lua Example: { SwitchModeCustomKeepingInputBuffer = "my_custom_mode" }
"PopMode"
YAML: PopMode
Pop the last mode from the history and switch to it. It clears the input buffer.
PopModeKeepingInputBuffer
YAML: PopModeKeepingInputBuffer
Pop the last mode from the history and switch to it. It keeps the input buffer.
{ SwitchLayout = "string" }
YAML: SwitchLayout: string
Switch layout.
NOTE: To be specific about which layout to switch to, use
SwitchLayoutBuiltin
orSwitchLayoutCustom
instead.
YAML Example: SwitchLayout: default
Lua Example: { SwitchLayout = "default" }
{ SwitchLayoutBuiltin = "string" }
YAML: SwitchLayoutBuiltin: string
Switch to a builtin layout.
YAML Example: SwitchLayoutBuiltin: default
Lua Example: { SwitchLayoutBuiltin = "default" }
{ SwitchLayoutCustom = "string" }
YAML: SwitchLayoutCustom: string
Switch to a custom layout.
YAML Example: SwitchLayoutCustom: my_custom_layout
Lua Example: { SwitchLayoutCustom = "my_custom_layout" }
{ Call = "string" }
YAML: Call: string
Call a shell command with the given arguments.
Note that the arguments will be shell-escaped.
So to read the variables, the -c
option of the shell
can be used.
You may need to pass ExplorePwd
depening on the expectation.
YAML Example: Call: { command: bash, args: ["-c", "read -p test"] }
Lua Example: { Call = { command = "bash", args = { "-c", "read -p test" } } }
{ CallSilently = "string" }
YAML: CallSilently: string
Like Call
but without the flicker. The stdin, stdout
stderr will be piped to null. So it's non-interactive.
YAML Example: CallSilently: { command: tput, args: ["bell"] }
Lua Example: { CallSilently = { command = "tput", args = { "bell" } } }
{ BashExec = "string" }
YAML: BashExec: string
An alias to Call: {command: bash, args: ["-c", "{string}"], silent: false}
where {string}
is the given value.
YAML Example: BashExec: "read -p test"
Lua Example: { BashExec = "read -p test" }
{ BashExecSilently = "string" }
YAML: BashExecSilently(String)
Like BashExec
but without the flicker. The stdin, stdout
stderr will be piped to null. So it's non-interactive.
YAML Example: BashExecSilently: "tput bell"
Lua Example: { BashExecSilently = "tput bell" }
{ CallLua = "string" }
YAML: CallLua: string
Call a Lua function.
A Lua Context object will be passed to the function as argument. The function can optionally return a list of messages for xplr to handle after the executing the function.
YAML Example: CallLua: custom.some_custom_funtion
Lua Example: { CallLua = "custom.some_custom_funtion" }
{ CallLuaSilently = "string" }
YAML: CallLuaSilently: string
Like CallLua
but without the flicker. The stdin, stdout
stderr will be piped to null. So it's non-interactive.
YAML Example: CallLuaSilently: custom.some_custom_function
Lua Example: { CallLuaSilently = "custom.some_custom_function" }
{ LuaEval = "string" }
YAML: LuaEval: string
Execute Lua code without needing to define a function.
If the string
is a callable, xplr will try to call it with with the
Lua Context argument.
YAML Example: LuaEval: "return { { LogInfo = io.read() } }"
YAML Example: LuaEval: "function(app) return { { LogInfo = app.pwd } } end"
Lua Example: { LuaEval = [[return { { LogInfo = io.read() } }]] }
Lua Example: { LuaEval = [[function(app) return { { LogInfo = app.pwd } } end]] }
{ LuaEvalSilently = "string" }
YAML: LuaEvalSilently: string
Like LuaEval
but without the flicker. The stdin, stdout
stderr will be piped to null. So it's non-interactive.
YAML Example: LuaEvalSilently: "return { { LogInfo = 'foo' } }"
Lua Example: { LuaEvalSilently = [[return { { LogInfo = "foo" } }]] }
"Select"
YAML: Select
Select the focused node.
"SelectAll"
YAML: SelectAll
Select all the visible nodes.
{ SelectPath = "string" }
YAML: SelectPath: string
Select the given path.
YAML Example: SelectPath: /path/to/file
Lua Example: { SelectPath = "/path/to/file" }
"UnSelect"
YAML: UnSelect
Unselect the focused node.
"UnSelectAll"
YAML: UnSelectAll
Unselect all the visible nodes.
{ UnSelectPath = "string)" }
YAML: UnSelectPath: string
UnSelect the given path.
YAML Example: UnSelectPath: /path/to/file
Lua Example: { UnSelectPath = "/path/to/file" }
"ToggleSelection"
YAML: ToggleSelection
Toggle selection on the focused node.
"ToggleSelectAll"
YAML: ToggleSelectAll
Toggle between select all and unselect all.
{ ToggleSelectionByPath = "string" }
YAML: ToggleSelectionByPath: string
Toggle selection by file path.
YAML Example: ToggleSelectionByPath: /path/to/file
Lua Example: { ToggleSelectionByPath = "/path/to/file" }
"ClearSelection"
YAML: ClearSelection
Clear the selection.
{ AddNodeFilter = { filter = Filter, input = "string" }
YAML: AddNodeFilter: { filter = Filter, input = string }
Add a filter to exclude nodes while exploring directories.
YAML Example: AddNodeFilter: { filter: RelativePathDoesStartWith, input: foo }
Lua Example: { AddNodeFilter = { filter = "RelativePathDoesStartWith", input = "foo" } }
{ RemoveNodeFilter = { filter = Filter, input = "string" }
YAML: RemoveNodeFilter: { filter = Filter, input = string
Remove an existing filter.
YAML Example: RemoveNodeFilter: { filter: RelativePathDoesStartWith, input: foo }
Lua Example: { RemoveNodeFilter: { filter: "RelativePathDoesStartWith", input: "foo" } }
{ ToggleNodeFilter = { filter = Filter, input = "string" }
YAML: ToggleNodeFilter: { filter = Filter, input = string }
Remove a filter if it exists, else, add a it.
YAML Example: ToggleNodeFilter: { filter: RelativePathDoesStartWith, input: foo }
Lua Example: { ToggleNodeFilter = { filter = "RelativePathDoesStartWith", input = "foo" } }
{ AddNodeFilterFromInput = Filter }
YAML: AddNodeFilterFromInput: Filter
Add a node filter reading the input from the buffer.
YAML Example: AddNodeFilterFromInput: RelativePathDoesStartWith
Lua Example: { AddNodeFilterFromInput = "RelativePathDoesStartWith" }
{ RemoveNodeFilterFromInput = Filter }
YAML: RemoveNodeFilterFromInput: Filter
Remove a node filter reading the input from the buffer.
YAML Example: RemoveNodeFilterFromInput: RelativePathDoesStartWith
Lua Example: { RemoveNodeFilterFromInput = "RelativePathDoesStartWith" }
"RemoveLastNodeFilter"
YAML: RemoveLastNodeFilter
Remove the last node filter.
"ResetNodeFilters"
YAML: ResetNodeFilters
Reset the node filters back to the default configuration.
"ClearNodeFilters"
YAML: ClearNodeFilters
Clear all the node filters.
{ AddNodeSorter = { sorter = Sorter, reverse = bool } }
YAML: AddNodeSorter: { sorter: Sorter, reverse = bool }
Add a sorter to sort nodes while exploring directories.
YAML Example: AddNodeSorter: { sorter: ByRelativePath, reverse: false }
YAML Example: { AddNodeSorter = { sorter = "ByRelativePath", reverse = false } }
{ RemoveNodeSorter = Sorter }
YAML: RemoveNodeSorter: Sorter
Remove an existing sorter.
YAML Example: RemoveNodeSorter: ByRelativePath
Lua Example: { RemoveNodeSorter = "ByRelativePath" }
{ ReverseNodeSorter = Sorter }
YAML: ReverseNodeSorter: Sorter
Reverse a node sorter.
YAML Example: ReverseNodeSorter: ByRelativePath
Lua Example: { ReverseNodeSorter = "ByRelativePath" }
{ ToggleNodeSorter = { sorter = Sorter, reverse = bool } }
YAML: ToggleNodeSorter: { sorter: Sorter, reverse = bool }
Remove a sorter if it exists, else, add a it.
YAML Example: ToggleSorterSorter: {sorter: ByRelativePath, reverse: false }
Lua Example: { ToggleSorterSorter: { sorter = "ByRelativePath", reverse = false } }
"ReverseNodeSorters"
YAML: ReverseNodeSorters
Reverse the node sorters.
"RemoveLastNodeSorter"
YAML: RemoveLastNodeSorter
Remove the last node sorter.
"ResetNodeSorters"
YAML: ResetNodeSorters
Reset the node sorters back to the default configuration.
"ClearNodeSorters"
YAML: ClearNodeSorters
Clear all the node sorters.
"EnableMouse"
YAML: EnableMouse
Enable mouse
"DisableMouse"
YAML: DisableMouse
Disable mouse
"ToggleMouse"
YAML: ToggleMouse
Toggle mouse
{ StartFifo = "string" }
YAML: StartFifo: string
Start piping the focused path to the given fifo path
YAML Example: StartFifo: /tmp/xplr.fifo
Lua Example: { StartFifo = "/tmp/xplr.fifo }
"StopFifo"
YAML: StopFifo
Close the active fifo and stop piping.
{ ToggleFifo = "string" }
YAML: ToggleFifo: string
Toggle betwen {Start|Stop}Fifo
YAML Example: ToggleFifo: /path/to/fifo
Lua Example: { ToggleFifo = "/path/to/fifo" }
{ LogInfo = "string" }
YAML: LogInfo: string
Log information message.
YAML Example: LogInfo: launching satellite
Lua Example: { LogInfo = "launching satellite" }
{ LogSuccess = "String" }
YAML: LogSuccess: string
Log a success message.
YAML Example: LogSuccess: satellite reached destination
.
Lua Example: { LogSuccess = "satellite reached destination" }
.
{ LogWarning = "string" }
YAML: LogWarning: string
Log an warning message.
YAML Example: LogWarning: satellite is heating
Lua Example: { LogWarning = "satellite is heating" }
{ LogError = "string" }
YAML: LogError: string
Log an error message.
YAML Example: LogError: satellite crashed
Lua Example: { LogError = "satellite crashed" }
"Quit"
YAML: Quit
Quit with returncode zero (success).
"PrintPwdAndQuit"
YAML: PrintPwdAndQuit
Print $PWD and quit.
"PrintFocusPathAndQuit"
YAML: PrintFocusPathAndQuit
Print the path under focus and quit. It can be empty string if there's nothing to focus.
"PrintSelectionAndQuit"
YAML: PrintSelectionAndQuit
Print the selected paths and quit. It can be empty is no path is selected.
"PrintResultAndQuit"
YAML: PrintResultAndQuit
Print the selected paths if it's not empty, else, print the focused node's path.
"PrintAppStateAndQuit"
YAML: PrintAppStateAndQuit
Print the state of application in YAML format. Helpful for debugging or generating the default configuration file.
{ Debug = "string" }
YAML: Debug: string
Write the application state to a file, without quitting. Also helpful for debugging.
YAML Example: Debug: /path/to/file
Lua Example: { Debug = "/path/to/file" }
"Terminate"
YAML: Terminate
Terminate the application with a non-zero return code.
InputOperation
Cursor based input operation can be one of the following:
- { SetCursor = int }
- { InsertCharacter = str }
- "GoToPreviousCharacter"
- "GoToNextCharacter"
- "GoToPreviousWord"
- "GoToNextWord"
- "GoToStart"
- "GoToEnd"
- "DeletePreviousCharacter"
- "DeleteNextCharacter"
- "DeletePreviousWord"
- "DeleteNextWord"
- "DeleteLine"
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 that contains some useful information. The function can optionally return a list of messages which will be handled by xplr.
Lua Context
This is a special argument passed to the lua functions when called using the
CallLua
, CallLuaSilently
messages.
It contains the following information:
- version
- pwd
- focused_node
- directory_buffer
- selection
- mode
- layout
- input_buffer
- pid
- session_path
- explorer_config
- history
- last_modes
version
Type: string
xplr version. Can be used to test compatibility.
pwd
Type: string
The present working directory/
focused_node
Type: nullable Node
The node under focus.
directory_buffer
Type: nullable Directory Buffer
The directory buffer being rendered.
selection
Type: list of selected Nodes
The selected nodes.
mode
Type: Mode
Current mode.
layout
Type: Layout
Current layout.
input_buffer
Type: nullable string
The input buffer.
pid
Type: integer
The xplr session PID.
session_path
Type: string
The session path.
explorer_config
history
Type: History
last_modes
Type: list of Mode
Last modes, not popped yet.
parent
Type: string
The parent path of the node.
relative_path
Type: string
The path relative to the parent, i.e. the file/directory name with extension.
absolute_path
Type: string
The absolute path (without resolving symlinks) of the node.
extension
Type: string
The extension of the node.
is_symlink
Type: boolean
true
if the node is a symlink.
is_broken
Type: boolean
true
if the node is a broken symlink.
is_dir
Type: boolean
true
if the node is a directory.
is_file
Type: boolean
true
if the node is a file.
is_readonly
Type: boolean
true
if the node is real-only.
mime_essence
Type: string
The mime type of the node. For e.g. text/csv
, image/jpeg
etc.
size
Type: integer
The size of the exact node. The size of a directory won't be calculated recursively.
human_size
Type: string
Like size but in human readable format.
permissions
Type: Permission
The permissions applied to the node.
canonical
Type: nullable Resolved Node Metadata
If the node is a symlink, it will hold information about the symlink resolved node. Else, it will hold information the actual node. It the symlink is broken, it will be null.
symlink
Type: nullable Resolved Node Metadata
If the node is a symlink and is not broken, it will hold information about the symlink resolved node. However, it will never hold information about the actual node. It will instead be null.
Node
A node contains the following fields:
- parent
- relative_path
- absolute_path
- extension
- is_symlink
- is_broken
- is_dir
- is_file
- is_readonly
- mime_essence
- size
- human_size
- permissions
- canonical
- symlink
Directory Buffer
Directory buffer contains the following fields:
parent
Type: string
The parent path of the node.
nodes
Type: list of Nodes
A list of visible nodes.
total
Type: int
The count of nodes being rendered.
focus
Type: int
The index of the node under focus. It can be 0
even when there's no node to
focus on.
History
History contains the following fields:
loc
Type: int
Location of the current path in history.
paths
Type: list of string
Visited paths.
Example: Using Lua Function Calls
-- 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 = "ask name 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.
Environment Variables and Pipes
Alternative to CallLua
, CallLuaSilently
messages that call Lua functions,
there are Call
, CallSilently
, 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 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.
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_GLOBAL_HELP_MENU_OUT
- XPLR_PIPE_LOGS_OUT
- XPLR_PIPE_RESULT_OUT
- XPLR_PIPE_HISTORY_OUT
- XPLR_PIPE_DIRECTORY_NODES_OUT
XPLR_PIPE_MSG_IN
Append new-line delimited messages to this pipe in YAML (or JSON) 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.
Example: Using Environment Variables and Pipes
xplr.config.modes.builtin.default.key_bindings.on_key.space = {
help = "ask name and greet",
messages = {
{
BashExec = [===[
echo "What's your name?"
read name
greeting="Hello $name!"
message="$greeting You are inside $PWD"
echo LogSuccess: '"'$message'"' >> "${XPLR_PIPE_MSG_IN:?}"
]===]
}
}
}
-- 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.
Layouts
Example: Defining Custom Layout
xplr.config.layouts.builtin.default = {
Horizontal = {
config = {
margin = 1,
horizontal_margin = 2,
vertical_margin = 3,
constraints = {
{ Percentage = 50 },
{ Percentage = 50 },
}
},
splits = {
"Table",
"HelpMenu",
}
}
}
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:
The users can switch between these layouts at run-time.
builtin
Type: mapping of string and Layout
This is exposed by the xplr.config.layouts.builtin
API.
xplr by default provides the following builtin layouts:
default
Type: Layout
This is the default layout we see when we run xplr.
no_help
Type: Layout
This layout hides the help menu.
no_selection
Type: Layout
This layout hides the selection panel.
no_help_no_selection
Type: Layout
This layout hides both the help menu and the selection panel.
custom
Type: mapping of string and Layout
This is exposed by the xplr.config.layouts.custom
API.
It allows the users to define any custom layout.
Example:
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"
- "Table"
- "InputAndLogs"
- "Selection"
- "HelpMenu"
- "SortAndFilter"
- { CustomContent = { title, body }
- { Horizontal = { config, splits }
- { Vertical = { config, splits }
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:
Vertical
This is a special layout that splits the panel into two vertical parts.
It contains the following information:
Layout Config
A layout config contains the following information:
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 value.
vertical_Margin
Type: nullable integer
The width of the vertical margins. Overwrites the margin value.
constraints
Type: nullable list of 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 }
- { MaxLessThanLayoutWidth = int }
- { Min = int }
- { MinLessThanScreenHeight = int }
- { MinLessThanScreenWidth = int }
- { MinLessThanLayoutHeight = int }
- { MinLessThanLayoutWidth = int }
TODO: document each constraint.
splits
Type: list of Layout
The list of child layouts to fit into the parent layout.
Custom Content
Custom content is a special layout to render something custom. It contains the following information:
title
Type: nullable string
The title of the panel.
body
Type: Content Body
The body of the panel.
Content Body
Content body can be one of the following:
Static Paragraph
A paragraph to render. It contains the following fields:
- render (string): The string to render.
Example: Render a custom static paragraph
xplr.config.layouts.builtin.default = {
CustomContent = {
title = "custom title",
body = {
StaticParagraph = { render = "custom body" },
},
},
}
Dynamic Paragraph
A Lua function to render a custom paragraph. It contains the following fields:
- render (string): The lua function that returns the paragraph to render.
Example: Render a custom dynamic paragraph
xplr.config.layouts.builtin.default = {
CustomContent = {
title = "custom title",
body = { DynamicParagraph = { render = "custom.render_layout" } },
},
}
xplr.fn.custom.render_layout = function(ctx)
return ctx.app.pwd
end
Static List
A list to render. It contains the following fields:
- render (list of string): The list to render.
Example: Render a custom static list
xplr.config.layouts.builtin.default = {
CustomContent = {
title = "custom title",
body = {
StaticList = { render = { "1", "2", "3" } },
},
},
}
Dynamic List
A Lua function to render a custom list. It contains the following fields:
- render (string): The lua function that returns the list to render.
Example: Render a custom dynamic list
xplr.config.layouts.builtin.default = {
CustomContent = {
title = "custom title",
body = { DynamicList = { render = "custom.render_layout" } },
},
}
xplr.fn.custom.render_layout = function(ctx)
return {
ctx.app.pwd,
ctx.app.version,
tostring(ctx.app.pid),
}
end
Static Table
A table to render. It contains the following fields:
- widths (list of Constraint): Width of the columns.
- col_spacing (nullable int): Spacing between columns. Defaults to 1.
- render (list of list of string): The rows and columns to render.
Example: Render a custom static table
xplr.config.layouts.builtin.default = {
CustomContent = {
title = "custom title",
body = {
StaticTable = {
widths = {
{ Percentage = 50 },
{ Percentage = 50 },
},
col_spacing = 1,
render = {
{ "a", "b" },
{ "c", "d" },
},
},
},
},
}
Dynamic Table
A Lua function to render a custom table. It contains the following fields:
- widths (list of Constraint): Width of the columns.
- col_spacing (nullable int): Spacing between columns. Defaults to 1.
- render (string): The lua function that returns the table to render.
Example: Render a custom dynamic table
xplr.config.layouts.builtin.default = {
CustomContent = {
title = "custom title",
body = {
DynamicTable = {
widths = {
{ Percentage = 50 },
{ Percentage = 50 },
},
col_spacing = 1,
render = "custom.render_layout",
},
},
},
}
xplr.fn.custom.render_layout = function(ctx)
return {
{ "", "" },
{ "Layout height", tostring(ctx.layout_size.height) },
{ "Layout width", tostring(ctx.layout_size.width) },
{ "", "" },
{ "Screen height", tostring(ctx.screen_size.height) },
{ "Screen width", tostring(ctx.screen_size.width) },
}
end
Content Renderer
It is a Lua function that receives a special argument as input and returns some output that can be rendered in the UI. It is used to render content body for the custom dynamic layouts.
Content Renderer Argument
It contains the following information:
Size
It contains the following information:
- x
- y
- height
- width
Every field is of integer type.
app
This is a lightweight version of the Lua Context. In this context, the heavyweight fields like directory_buffer are omitted for performance reasons.
Hence, only the following fields are avilable.
Node Types
This configuration defines how to deal with different kinds of nodes (files, directories, symlinks etc.) in a directory.
This can be configured using the xplr.config.node_types
Lua API.
It contains the following fields:
One node can fall into multiple categories. For example, a node can have the
extension md
, and be a file
. In that case, the properties from the more
specific category i.e. extension will be used.
The priority is:
special > extension > mime_essence > symlink > file > directory
directory
Type: NodeType Config
Properties related to directories are defined here.
Contains the following fields:
Example:
xplr.config.node_types.directory.meta.icon = ""
xplr.config.node_types.directory.style.add_modifiers = { "Bold" }
file
Type: NodeType Config
Properties related to regular files are defined here.
Contains the following fields:
Example:
xplr.config.node_types.file.meta.icon = ""
xplr.config.node_types.file.style.fg = "White"
symlink
Type: NodeType Config
Properties related to symlink are defined here.
Example:
xplr.config.node_types.symlink.meta.icon = ""
xplr.config.node_types.symlink.style.add_modifiers = { "Italic" }
mime_essence
Type: mapping of mime-type and mapping of mime-subtype and NodeType Config
Properties related to files with specific mime types are defined here.
It is possible to use the wildcard *
to match all mime subtypes. It will be
overwritten by the more specific sub types that are defined.
Example:
xplr.config.node_types.mime_essence = {
application = {
-- application/*
["*"] = { meta = { icon = "a" } }
-- application/pdf
pdf = { meta = { icon = "" } },
-- application/zip
zip = { meta = { icon = ""} },
},
}
extension
Type: mapping of extension and NodeType Config
Properties related to files with specific extension are defined here.
Example:
xplr.config.node_types.extension.md = { meta = { icon = "" } }
xplr.config.node_types.extension.rs = { meta = { icon = "🦀" } }
special
Type: mapping of name and NodeType Config
Properties related to files and directories with special names are defined here.
Example:
xplr.config.node_types.special["Cargo.toml"] = { meta = { icon = "" } }
xplr.config.node_types.special["Downloads"] = { meta = { icon = "" } }
NodeType Config
A node-type config contains the following fields:
meta
Type: mapping of string and string
A meta field can contain custom metadata about a node. By default, the "icon" metadata is set for the directory, file, and symlink nodes.
Example:
xplr.config.node_types.file = {
meta = {
icon = "f",
foo = "bar",
}
}
Style
A style object contains the following information:
fg
Type: nullable Color
The foreground color.
bg
Type: nullable Color
The background color.
add_modifiers
Type: nullable list of Modifier
Modifiers to add.
sub_modifiers
Type: nullable list of 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
xplr.config.general.prompt.style.fg = "Red"
xplr.config.general.prompt.style.bg = { Rgb = { 100, 150, 200 } }
xplr.config.general.prompt.style.add_modifiers = { "Bold", "Italic" }
xplr.config.general.prompt.style.sub_modifiers = { "Hidden" }
Sorting
xplr supports sorting paths by different properties. The sorting mechanism
works like a pipeline, which in visible in the Sort & filter
panel.
Example:
size↑ › [i]rel↓ › [c]dir↑ › [c]file↑ › sym↑
This line means that the nodes visible in the table will be first sorted by it's size, then by case insensitive relative path, then by the canonical (symlink resolved) type of the node, and finally by whether or not the node is a symlink.
The arrows denote the order.
Each part of this pipeline is called Node Sorter Applicable.
Node Sorter Applicable
It contains the following information:
sorter
A sorter can be one of the following:
- "ByRelativePath"
- "ByIRelativePath"
- "ByExtension"
- "ByIsDir"
- "ByIsFile"
- "ByIsSymlink"
- "ByIsBroken"
- "ByIsReadonly"
- "ByMimeEssence"
- "BySize"
- "ByCanonicalAbsolutePath"
- "ByICanonicalAbsolutePath"
- "ByCanonicalExtension"
- "ByCanonicalIsDir"
- "ByCanonicalIsFile"
- "ByCanonicalIsReadonly"
- "ByCanonicalMimeEssence"
- "ByCanonicalSize"
- "BySymlinkAbsolutePath"
- "ByISymlinkAbsolutePath"
- "BySymlinkExtension"
- "BySymlinkIsDir"
- "BySymlinkIsFile"
- "BySymlinkIsReadonly"
- "BySymlinkMimeEssence"
- "BySymlinkSize"
TODO: document each
reverse
Type: boolean
It defined the direction of the order.
Example
xplr.config.general.initial_sorting = {
{ sorter = "ByCanonicalIsDir", reverse = true },
{ sorter = "ByIRelativePath", reverse = false },
}
This snippet defines the initial sorting logic to be applied when xplr loads.
Filtering
xplr supports filtering paths by different properties. The filtering mechanism
works like a pipeline, which in visible in the Sort & filter
panel.
Example:
rel!^. › [i]abs=~abc › [i]rel!~xyz
This line means that the nodes visible on the table will first be filtered by
the condition: relative path does not start with .
, then by the condition:
absolute path contains abc
(case insensitive), and finally by the
condition: relative path does not contain xyz
(case insensitive).
Each part of this pipeline is called Node Filter Applicable.
Node Filter Applicable
It contains the following information:
filter
A filter can be one of the following:
- "RelativePathIs"
- "RelativePathIsNot"
- "IRelativePathIs"
- "IRelativePathIsNot"
- "RelativePathDoesStartWith"
- "RelativePathDoesNotStartWith"
- "IRelativePathDoesStartWith"
- "IRelativePathDoesNotStartWith"
- "RelativePathDoesContain"
- "RelativePathDoesNotContain"
- "IRelativePathDoesContain"
- "IRelativePathDoesNotContain"
- "RelativePathDoesEndWith"
- "RelativePathDoesNotEndWith"
- "IRelativePathDoesEndWith"
- "IRelativePathDoesNotEndWith"
- "AbsolutePathIs"
- "AbsolutePathIsNot"
- "IAbsolutePathIs"
- "IAbsolutePathIsNot"
- "AbsolutePathDoesStartWith"
- "AbsolutePathDoesNotStartWith"
- "IAbsolutePathDoesStartWith"
- "IAbsolutePathDoesNotStartWith"
- "AbsolutePathDoesContain"
- "AbsolutePathDoesNotContain"
- "IAbsolutePathDoesContain"
- "IAbsolutePathDoesNotContain"
- "AbsolutePathDoesEndWith"
- "AbsolutePathDoesNotEndWith"
- "IAbsolutePathDoesEndWith"
- "IAbsolutePathDoesNotEndWith"
TODO: document each
input
Type: string
The input for the condition.
Example:
ToggleNodeFilter = {
filter = "RelativePathDoesNotStartWith",
input = "."
}
Here, ToggleNodeFilter
is a message that adds or removes
(toggles) the filter applied.
Column Renderer
A column renderer is a Lua function that receives a special argument and returns a string that will be displayed in each specific field of the files table.
xplr by default provides the following column renderers:
xplr.fn.builtin.fmt_general_table_row_cols_0
xplr.fn.builtin.fmt_general_table_row_cols_1
xplr.fn.builtin.fmt_general_table_row_cols_2
xplr.fn.builtin.fmt_general_table_row_cols_3
xplr.fn.builtin.fmt_general_table_row_cols_4
You can either overwrite these functions, or create new functions in
xplr.fn.custom
and point to them.
Terminal colors are supported.
Table Renderer Argument
The special argument contains the following fields
- parent
- relative_path
- absolute_path
- extension
- is_symlink
- is_broken
- is_dir
- is_file
- is_readonly
- mime_essence
- size
- human_size
- permissions
- canonical
- symlink
- index
- relative_index
- is_before_focus
- is_after_focus
- tree
- prefix
- suffix
- is_selected
- is_focused
- total
- meta
parent
Type: string
The parent path of the node.
relative_path
Type: string
The path relative to the parent, i.e. the file/directory name with extension.
absolute_path
Type: string
The absolute path (without resolving symlinks) of the node.
extension
Type: string
The extension of the node.
is_symlink
Type: boolean
true
if the node is a symlink.
is_broken
Type: boolean
true
if the node is a broken symlink.
is_dir
Type: boolean
true
if the node is a directory.
is_file
Type: boolean
true
if the node is a file.
is_readonly
Type: boolean
true
if the node is real-only.
mime_essence
Type: string
The mime type of the node. For e.g. text/csv
, image/jpeg
etc.
size
Type: integer
The size of the exact node. The size of a directory won't be calculated recursively.
human_size
Type: string
Like size but in human readable format.
permissions
Type: Permission
The permissions applied to the node.
canonical
Type: nullable Resolved Node Metadata
If the node is a symlink, it will hold information about the symlink resolved node. Else, it will hold information the actual node. It the symlink is broken, it will be null.
symlink
Type: nullable Resolved Node Metadata
If the node is a symlink and is not broken, it will hold information about the symlink resolved node. However, it will never hold information about the actual node. It will instead be null.
index
Type: integer
Index (starting from 0) of the node.
relative_index
Type: integer
Relative index from the focused node (i.e. 0th node).
is_before_focus
Type: boolean
true
if the node is before the focused node.
is_after_focus
Type: boolean
true
if the node is after the focused node.
tree
Type: string
The tree component based on the node's index.
prefix
Type: string
The prefix applicable for the node.
suffix
Type: string
The suffix applicable for the node.
is_selected
Type: boolean
true
if the node is selected.
is_focused
Type: boolean
true
if the node is under focus.
total
Type: integer
The total number of the nodes.
meta
Type: mapping of string and string
The applicable meta object for the node.
Permission
Permission contains the following fields:
- user_read
- user_write
- user_execute
- group_read
- group_write
- group_execute
- other_read
- other_write
- other_execute
- sticky
- setgid
- setuid
Each field holds a boolean value.
Resolved Node Metadata
It contains the following fields.
Example: Customizing Table Renderer
xplr.fn.custom.fmt_simple_column = function(m)
return m.prefix .. m.relative_path .. m.suffix
end
xplr.config.general.table.header.cols = {
{ format = " path" }
}
xplr.config.general.table.row.cols = {
{ format = "custom.fmt_simple_column" }
}
xplr.config.general.table.col_widths = {
{ Percentage = 100 }
}
-- With this config, you should only see a single column displaying the
-- relative paths.
Plugin
xplr supports pluggable Lua modules that can be used to easily configure or extend xplr UI and functionalities.
Installing Plugins
Until we get a cool plugin manager, let's install plugins manually using the following procedure:
-
Add the following line in
~/.config/xplr/init.lua
package.path = os.getenv("HOME") .. '/.config/xplr/plugins/?/src/init.lua'
-
Clone the plugin
mkdir -p ~/.config/xplr/plugins git clone https://github.com/sayanarijit/material-landscape2.xplr ~/.config/xplr/plugins/material-landscape2
-
Require the module in
~/.config/xplr/init.lua
require("material-landscape2").setup() -- The setup arguments might differ for different plugins. -- Visit the project README for setup instructions.
Writing Plugins
Anyone who can write Lua code, can write xplr plugins.
Just follow the instructions and best practices:
Naming
xplr plugins are named using hiphen (-
) separated words that may also include
integers. They will be plugged using the require()
function in Lua.
Structure
A minimal plugin should confirm to the following structure:
plugin-name
├── README.md
└── src
└── init.lua
You can also use this template.
README.md
This is where you document what the plugin does, how to use it, etc.
src/init.lua
This file is executed to load the plugin. It should expose a setup()
function, which will be used by the users to setup the plugin.
Example:
local function setup(args)
local xplr = xplr
-- do stuff with xplr
end
return { setup = setup }
Publishing
When publishing plugins on GitHub or other repositories, it's a best practice
to append .xplr
to the name to make them distinguishable. Similar to the
*.nvim
naming convention for Neovim plugins.
Finally, after publishing, don't hesitate to let us know.
Examples
Visit Awesome Plugins for xplr plugin examples.
Also See
- Tip: A list of hacks yet to make it as Lua plugins
- Tip: Some UI and themeing tips
- Tip: A list of handy utility functions
- Tip: Share tips and tricks working with Lua
- Tutorial: Adding a New Mode
- Example: Using Environment Variables and Pipes
- Example: Using Lua Function Calls
- Example: Defining Custom Layout
- Example: Customizing Table Renderer
- Example: Render a custom dynamic table
Awesome Plugins
Here's a list of awesome xplr plugins that you might want to check out. If none of the following plugins work for you, it's very easy to write your own.
Categories
Extension
- comex.xplr One xplr plugin to compress and extract them all.
- command-mode.xplr The missing command mode for xplr.
- context-switch.xplr Context switch plugin for xplr.
- map.xplr Visually inspect and interactively execute batch commands using xplr.
- type-to-nav.xplr Inspired by nnn's type-to-nav mode for xplr, with some tweaks.
- term.xplr Terminal integration for xplr
Integration
- alacritty.xplr Alacritty integration for xplr.
- dragon.xplr Drag and drop files using dragon.
- dua-cli.xplr Get the disk usage using dua-cli with selection support.
- fzf.xplr Fuzzy search using fzf to focus on a file or enter into a directory.
- nvim-ctrl.xplr Send files to running Neovim sessions using nvim-ctrl.
- ouch.xplr This plugin uses ouch to compress and decompress files.
- paste-rs.xplr Use this plugin to paste your files to paste.rs, and open/delete them later using fzf.
- preview-tabbed.xplr Preview paths using suckless tabbed and nnn preview-tabbed.
- qrcp.xplr Send and receive files via QR code using qrcp.
- trash-cli.xplr Trash files and directories using trash-cli.
- xargs.xplr Batch execute commands on the focused or selected files
using
xargs
. - xclip.xplr Copy and paste with system clipboard using xclip.
- zoxide.xplr Change directory using the zoxide database.
Theme
- material-landscape.xplr Material Landscape
- material-landscape2.xplr Material Landscape 2
- zentable.xplr A clean, distraction free xplr table UI
- icons.xplr An icon theme for xplr.
Integration
xplr is designed to integrate well with other tools and commands. It can be used as a file picker or a pluggable file manager.
Awesome Integrations
Here's a list of awesome xplr integrations that you might want to check out.
If none of the following integrations work for you, you can create your own and let us know.
Categories
Editor
- vim-floaterm xplr integrated in vim-floaterm (Neo)vim plugin.
- xplr.nvim Opens xplr inside nvim, and hosts a msgpack client inside xplr.
- xplr.vim Pick files in Vim using xplr.
- fm-nvim Neovim plugin that lets you use your favorite terminal file managers from within Neovim.
Shell
- powerlevel10k Powerlevel10k prompt for xplr shell.
Security Tools
- gpg-tui Import GPG certificates using xplr.
TODO
- Saner key bindings.
- Pipes.
- Native search & filter.
- Create, copy, move, delete files directly.
- logging support.
- Version compatibility instructions.
- Implement CLI arguments.
- ~Add support for tabs and/or panes (non native)~ hacked | discussion
- ~Implement bookmarks.~ hacked
- Add sorting support.
- Add filter support.
- File previews.
- Implement plugins support (or some way to easily share configuration).
- Bigger (and better) help menu.
- Offline docs.
- Support for background services
- ~Customize~ switch UI at run-time.
- More tests and benchmarks.
- Measure code coverage.
- Improve the vim plugin.
- Cleanup, refactor, optimize.
Like this project so far? Please consider contributing.
Alternatives
These are the alternative TUI/CLI file managers/explorers you might want to check out (in no particular order).
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 starting from your config version, all the way to the required version.
Expand for more information
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
withconfig-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.
Instructions
v0.16.4 -> v0.17.0
- Deprecated
app.directory_buffer
,app.history
, andapp.last_modes
in the custom dynamic layout renderer context. As of now, there's no way to access these fields in dynamic layouts. Whileapp.history
andapp.last_modes
can be re-added upon request (with justification),app.directory_buffer
has been deprecated for good. However, there's no change in theCallLua*
context. - Set
xplr.config.general.help_hide_remaps
totrue
to hide the remaps in help menu. None
will be serialized tonil
in Lua.LuaEval
can now return a function that will be called with the Lua Context argument. Refer to theFull List of Messages
doc for example.
v0.15.2 -> v0.16.4
- Deprecated
config.general.cursor
. The default terminal cursor will be used for the time being. - Opening xplr inside a symlink will not resolve the path.
- You can now replace most boilerplate configuration handling keys to send
BufferInputFromKey
,RemoveInputBufferLastCharacter
,RemoveInputBufferLastWord
,SetInputBuffer = ""
etc. messages with a singleUpdateInputBufferFromKey
message. - You can now pass multiple paths as command-line arguments or via stdin to
select paths, e.g.
xplr -- $PWD /path/to/select/1 /path/to/select/2
. - Pass
--force-focus
to focus on the first path even if it's a directory, e.g.xplr . --force-focus
. - Use new messages
LuaEval
andLuaEvalSilently
to run Lua code without needing to define a function. However, theapp
context won't be available. - You can now use new key handlers in the config:
- on_alphanumeric
- on_character
- on_navigation
- on_function
Like this project so far? Please consider contributing.
v0.14.7 -> v0.15.2
- Deprecated
config
field fromCallLua
argument. Use the globally availablexplr.config
instead. xplr.config.general.disable_recover_mode
has been deprecated. Usexplr.config.general.enable_recover_mode
instead.- Use
xplr.config.general.focus_selection_ui
to highlight selected files under focus differently than files under focus that are not selected. - Use
PopModeKeepingInputBuffer
, and SwitchMode alternatives to switching to different modes without resetting the input buffer. - Use the new
CustomContent
layout option to render custom content. - Use the new
layout
field in a mode to define custom layout for a specific mode. - Library users please refer to the latest API docs and examples.
v0.13.7 -> v0.14.7
- 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. - You can disable the recover mode using
config.general.disable_recover_mode = true
. - Try running
xplr --help
. Yes, CLI has been implemented. - Since version
v0.14.3
,StartFifo
andToggleFifo
will write to the FIFO path when called. So, there's no need to pipe the focus path explicitely. - Since version
v0.14.3
, general configxplr.config.start_fifo
is available which can be set to a file path to start a fifo when xplr starts. - Since version
v0.14.4
,$XPLR_SESSION_PATH
can be used to dump session related data. - Since version
v0.14.6
, the-C
or--extra-config
CLI argument is available.
v0.12.1 -> v0.13.7
- Lua functions called using
CallLua
andCallLuaSilently
messages will receiveCallLuaArg
object as the function argument (instead of theApp
object). - Each
node_types
config will inherit defaults from matching less specifignode_types
config and overwrite them. - Since version
v0.13.2
, you don't need to use/sendRefresh
anymore. It will be auto-handled by xplr.
v0.11.1 -> v0.12.1
xplr.config.node_types.mime_essence
has split into type and subtype. Hence, instead ofxplr.config.node_types.mime_essence["text/plain"] = ..
usexplr.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 -> 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 -> v0.10.2
config.yml
has been fully replaced withinit.lua
. If you have a lot of customization in yourconfig.yml
, xplr-yml2lua can help you with migrating it toinit.lua
.Handlebars
templates has been replaced with Lua functions. You can either remove the customizations or overwrite the functions accordingly.- Added new messages
CallLua
andCallLuaSilently
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
andCallLuaSilently
are more flexible (and probably faster) alternatives toCall
,CallSilently
,BashExec
andBashExecSilently
. e.g.
v0.9.0 -> 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 -> 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 ofSwitchMode*
when returning back to the previous mode. - After using (the group of)
PopMode
andSwitchMode*
messages, you are now required toRefresh
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. Pressesc
to escape therecover
mode. - Introduced new message
LogWarning
, similar to otherLog*
messages. - Creating files and directories has been optimized for batch creation.
v0.7.2 -> v0.8.0
If you have made changes to the config file,
- Replace message
Explore
withExplorePwd
orExplorePwdAsync
or probablyExploreParentsAsync
. - 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 ofecho "FocusPath: $PWD" >> $PIPE
.
v0.7.0 -> v0.7.2
- Just update the
version
in your config file. - For version >=
v0.7.1
, you might want to free up or remap thetab
key insearch
mode to enable easy selection during search.
v0.6.0 -> 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 thegeneral.panel_ui
instead.
v0.5.13 -> 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}
toadd_modifiers: [Bold]
,sub_modifier: {bits: 1}
tosub_modifiers: [Bold]
and so on. - Rename
percentage: 10
toPercentage: 10
,ratio: 1
toRatio: 1
and so on. - You might want to free up or remap the
ctrl-w
key binding indefault
mode to enable layout switching.
Optionally, checkout this new theme to learn more about what's new.
v0.5.0 -> 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 keysgx
). - You might also want to update other mappings to handle files with names starting with
-
(hiphen). For example, instead ofrm ${filename}
userm -- ${filename}
. Same goes forcp
,mv
,cat
,touch
etc. - For version >=
v0.5.13
, you might want to use the more specificSwitchModeBuiltin
andSwitchModeCustom
messages instead of the generalSwitchMode
message.
v0.4.3 -> 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}
withRelativePathIs
. - Replace
{RelativePathIs, case_sensitive: false}
withIRelativePathIs
. - Do the same with other filters you are using.
- You might want to update your
backspace
handling to use theRemoveInputBufferLastCharacter
message. - You might want to free-up
f
,s
,ctrl-r
andctrl-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 -> v0.4.3
If you have customized general.table.row.cols
, you might want to update it to use the new variables with better symlink support.
v0.4.1 -> 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 -> v0.4.1
A lot has changed (apologies). But I promise from now on, upgrading will be much less painful (thanks to @maximbaz's valuable inputs and code reviews).
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
togeneral.focus_ui
(see here). - Rename
filetypes
tonode_types
. (see here) - Rename
custom
field tometa
. (see here) - Move
icon
tometa.icon
. (see here) - Rename
normal_ui
todefault_ui
. (see here) - Split
modes
intomodes.builtin
andmodes.custom
(see here). Migrate your custom modes tomodes.custom
. And copy only the changes in the in-built modes inmodes.builtin
. - Finally, update the
version
tov0.4.1
.
v0.3.8 -> 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
andBashExec
in the new config. - Compare and probably replace the associated actions in your current config
v0.3.0 -> 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
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 useDebug
to export the app state.$XPLR_RESULT
has been ported to file$XPLR_PIPE_RESULT_OUT
. Usecat
instead ofecho
,<
instead of<<<
etc.$XPLR_GLOBAL_HELP_MENU
has been ported to file$XPLR_PIPE_GLOBAL_HELP_MENU_OUT
. Usecat
instead ofecho
,<
instead of<<<
etc.$XPLR_DIRECTORY_NODES
has been ported to file$XPLR_PIPE_DIRECTORY_NODES_OUT
. Usecat
instead ofecho
,<
instead of<<<
etc.$XPLR_LOGS
has been ported to file$XPLR_PIPE_LOGS_OUT
. Usecat
instead ofecho
,<
instead of<<<
etc.$XPLR_PIPE_RESULT
has been ported to file$XPLR_PIPE_RESULT_OUT
. Usecat
instead ofecho
,<
instead of<<<
etc.- Finally, update the
version
in your config file.
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 matrix room or discord channel.
- Forum discussion veterans can start a new GitHub discussion.
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 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 or buy me a coffee.
For further queries or concern related to xplr
, just ask us.