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 you to achieve insane terminal productivity.
Concept
Hackable
xplr is built with configurability in mind. So it allows you to perform a vast set of operations and make it look and 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, and it will only get faster. Still, if you feel like it's
somehow making you slow, just report it. Most probably we're just waiting for
someone to complain.
Tip: A quick and easy way to optimize the UI rendering is reducing the number of columns in the table.
Minimal
xplr is being referred to as a File Explorer, not a File Manager. This is because at the core, xplr is only an explorer, and outsources the file management operations to external commands. This helps xplr stay minimal, and focus only on doing what it does best.
So, just like speed, minimalism isn't as as aggressively pursued as hackability. xplr simply prefers to stay minimal and looks for the opportunity to lose some kb if it makes sense.
Features
Some of the coolest features xplr provide beside the basic stuff:
- Embedded LuaJIT for portability and extensibility.
- A simple system based on message passing to control xplr session using:
- Readline-like input buffer with customizable behaviour to read user inputs.
- Switchable recover mode that saves you from doing unwanted things when in a hurry.
- Customizable layouts with built-in panels. For e.g.
- Selection list to show you the selected paths in real-time.
- Help menu to show you the available keys bindings in each mode.
- Input & logs to read input and display logs.
- Filter and sort pipeline to show you the applied filters and sorters.
- Custom file properties with custom colors can be displayed in the table.
- FIFO manager to manage a 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 (
Q. What features should be added here? let us know.
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 less
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
Nixpkgs
nix-env -f https://github.com/NixOS/nixpkgs/tarball/master -iA xplr
Arch Linux
Official Community Repo
sudo pacman -S xplr
AUR
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" / "linux-musl"
# 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
,
which can be placed in ~/.config/xplr/
(local to user) or /etc/xplr/
(global) depending on the use case.
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
The first one found will be loaded by xplr and the lookup will stop.
The loaded config can be further extended using the -C
or --extra-config
command-line option.
Config
The xplr configuration, exposed via xplr.config
Lua API contains the
following sections.
See:
Function
While xplr.config
defines all the static parts of the configuration,
xplr.fn
defines all the dynamic parts using functions.
See: Lua Function Calls
As always, xplr.fn.builtin
is where the built-in functions are defined
that can be overwritten.
xplr.fn.builtin.fmt_general_table_row_cols_0
Renders the first column in the table
xplr.fn.builtin.fmt_general_table_row_cols_1
Renders the second column in the table
xplr.fn.builtin.fmt_general_table_row_cols_2
Renders the third column in the table
xplr.fn.builtin.fmt_general_table_row_cols_3
Renders the fourth column in the table
xplr.fn.builtin.fmt_general_table_row_cols_4
Renders the fifth column in the table
xplr.fn.custom
This is where the custom functions can be added.
There is currently no restriction on what kind of functions can be defined
in xplr.fn.custom
.
You can also use nested tables such as
xplr.fn.custom.my_plugin.my_function
to define custom functions.
General Configuration
The general configuration properties are grouped together in
xplr.config.general
.
xplr.config.general.disable_debug_error_mode
Set it to true
if you want to ignore the startup errors. You can still see
the errors in the logs.
Type: boolean
xplr.config.general.enable_mouse
Set it to true
if you want to enable mouse scrolling.
Type: boolean
xplr.config.general.show_hidden
Set it to true
to show hidden files by default.
Type: boolean
xplr.config.general.read_only
Set it to true
to use only a subset of selected operations that forbids
executing commands or performing write operations on the file-system.
Type: boolean
xplr.config.general.enable_recover_mode
Set it to true
if you want to enable a safety feature that will save you
from yourself when you type recklessly.
Type: boolean
xplr.config.general.hide_remaps_in_help_menu
Set it to true
if you want to hide all remaps in the help menu.
Type: boolean
xplr.config.general.enforce_bounded_index_navigation
Set it to true
if you want the cursor to stay in the same position when
the focus is on the first path and you navigate to the previous path
(by pressing up
/k
), or when the focus is on the last path and you
navigate to the next path (by pressing down
/j
).
The default behavior is to rotate from the last/first path.
Type: boolean
xplr.config.general.prompt.format
This is the shape of the prompt for the input buffer.
Type: nullable string
xplr.config.general.prompt.style
This is the style of the prompt for the input buffer.
Type: Style
xplr.config.general.logs.info.format
The string to indicate an information in logs.
Type: nullable string
xplr.config.general.logs.info.style
The style for the informations logs.
Type: Style
xplr.config.general.logs.success.format
The string to indicate an success in logs.
Type: nullable string
xplr.config.general.logs.success.style
The style for the success logs.
Type: Style
xplr.config.general.logs.warning.format
The string to indicate an warnings in logs.
Type: nullable string
xplr.config.general.logs.warning.style
The style for the warnings logs.
Type: Style
xplr.config.general.logs.error.format
The string to indicate an error in logs.
Type: nullable string
xplr.config.general.logs.error.style
The style for the error logs.
Type: Style
xplr.config.general.table.header.cols
Columns to display in the table header.
Type: nullable list of tables with the following fields:
- format: nullable string
- style: Style
xplr.config.general.table.header.style
Style of the table header.
Type: Style
xplr.config.general.table.header.height
Height of the table header.
Type: nullable integer
xplr.config.general.table.row.cols
Columns to display in each row in the table.
Type: nullable list of tables with the following fields:
- format: nullable string
- style: Style
xplr.config.general.table.row.style
Default style of the table.
Type: Style
xplr.config.general.table.row.height
Height of the table rows.
Type: nullable integer
xplr.config.general.table.style
Default style of the table.
Type: Style
xplr.config.general.table.tree
Tree to display in the table.
Type: nullable list of tables with the following fields:
- format: nullable string
- style: Style
xplr.config.general.table.col_spacing
Spacing between the columns in the table.
Type: nullable integer
xplr.config.general.table.col_widths
Constraint for the column widths.
Type: nullable list of Constraint
xplr.config.general.default_ui.prefix
The content that is placed before the item name for each row by default.
Type: nullable string
xplr.config.general.default_ui.suffix
The content which is appended to each item name for each row by default.
Type: nullable string
xplr.config.general.default_ui.style
The default style of each item for each row.
Type: Style
xplr.config.general.focus_ui.prefix
The string placed before the item name for a focused row.
Type: nullable string
xplr.config.general.focus_ui.suffix
The string placed after the item name for a focused row.
Type: nullable string
xplr.config.general.focus_ui.style
Style for focused item. Type: Style
xplr.config.general.selection_ui.prefix
The string placed before the item name for a selected row.
Type: nullable string
xplr.config.general.selection_ui.suffix
The string placed after the item name for a selected row.
Type: nullable string
xplr.config.general.selection_ui.style
Style for selected rows.
Type: Style
xplr.config.general.focus_selection_ui.prefix
The string placed before item name for a selected row that gets the focus.
Type: nullable string
xplr.config.general.focus_selection_ui.suffix
The string placed after the item name for a selected row that gets the focus.
Type: nullable string
xplr.config.general.focus_selection_ui.style
Style for a selected row that gets the focus.
Type: Style
xplr.config.general.sort_and_filter_ui.separator.format
The shape of the separator for the Sort & filter panel.
Type: nullable string
xplr.config.general.sort_and_filter_ui.separator.style
The style of the separator for the Sort & filter panel.
Type: Style
xplr.config.general.sort_and_filter_ui.default_identifier.format
The content of the default identifier in Sort & filter panel.
Type: nullable string
xplr.config.general.sort_and_filter_ui.default_identifier.style
Style for the default identifier in Sort & filter panel.
Type: Style
xplr.config.general.sort_and_filter_ui.sort_direction_identifiers.forward.format
The shape of the forward direction indicator for sort identifiers in Sort & filter panel.
Type: nullable string
xplr.config.general.sort_and_filter_ui.sort_direction_identifiers.forward.style
Style of forward direction indicator in Sort & filter panel.
Type: Style
xplr.config.general.sort_and_filter_ui.sort_direction_identifiers.reverse.format
The shape of the reverse direction indicator for sort identifiers in Sort & filter panel.
Type: nullable string
xplr.config.general.sort_and_filter_ui.sort_direction_identifiers.reverse.style
Style of reverse direction indicator in Sort & filter panel.
Type: Style
xplr.config.general.sort_and_filter_ui.sorter_identifiers
The identifiers used to denote applied sorters in the Sort & filter panel.
Type: nullable mapping of the following key-value pairs:
xplr.config.general.sort_and_filter_ui.filter_identifiers
The identifiers used to denote applied filters in the Sort & filter panel.
Type: nullable mapping of the following key-value pairs:
xplr.config.general.panel_ui.default.title.format
The content for panel title by default.
Type: nullable string
xplr.config.general.panel_ui.default.title.style
The style for panel title by default.
Type: Style
xplr.config.general.panel_ui.default.style
Style of the panels by default.
Type: Style
xplr.config.general.panel_ui.default.borders
Defines where to show borders for the panels by default.
Type: nullable list of Border
xplr.config.general.panel_ui.default.border_type
Type of the borders by default.
Type: nullable Border Type
xplr.config.general.panel_ui.default.border_style
Style of the panel borders by default.
Type: Style
xplr.config.general.panel_ui.table.title.format
The content for the table panel title.
Type: nullable string
xplr.config.general.panel_ui.table.title.style
Style of the table panel title.
Type: Style
xplr.config.general.panel_ui.table.style
Style of the table panel.
Type: Style
xplr.config.general.panel_ui.table.borders
Defines where to show borders for the table panel.
Type: nullable list of Border
xplr.config.general.panel_ui.table.border_type
Type of the borders for table panel.
Type: nullable Border Type
xplr.config.general.panel_ui.table.border_style
Style of the table panel borders.
Type: Style
xplr.config.general.panel_ui.help_menu.title.format
The content for the help menu panel title.
Type: nullable string
xplr.config.general.panel_ui.help_menu.title.style
Style of the help menu panel title.
Type: Style
xplr.config.general.panel_ui.help_menu.style
Style of the help menu panel.
Type: Style
xplr.config.general.panel_ui.help_menu.borders
Defines where to show borders for the help menu panel.
Type: nullable list of Border
xplr.config.general.panel_ui.help_menu.border_type
Type of the borders for help menu panel.
Type: nullable Border Type
xplr.config.general.panel_ui.help_menu.border_style
Style of the help menu panel borders.
Type: Style
xplr.config.general.panel_ui.input_and_logs.title.format
The content for the input & logs panel title.
Type: nullable string
xplr.config.general.panel_ui.input_and_logs.title.style
Style of the input & logs panel title.
Type: Style
xplr.config.general.panel_ui.input_and_logs.borders
xplr.config.general.panel_ui.input_and_logs.style
Style of the input & logs panel.
Type: Style Defines where to show borders for the input & logs panel.
Type: nullable list of Border
xplr.config.general.panel_ui.input_and_logs.border_type
Type of the borders for input & logs panel.
Type: nullable Border Type
xplr.config.general.panel_ui.input_and_logs.border_style
Style of the input & logs panel borders.
Type: Style
xplr.config.general.panel_ui.selection.title.format
The content for the selection panel title.
Type: nullable string
xplr.config.general.panel_ui.selection.title.style
Style of the selection panel title.
Type: Style
xplr.config.general.panel_ui.selection.borders
xplr.config.general.panel_ui.selection.style
Style of the selection panel.
Type: Style Defines where to show borders for the selection panel.
Type: nullable list of Border
xplr.config.general.panel_ui.selection.border_type
Type of the borders for selection panel.
Type: nullable Border Type
xplr.config.general.panel_ui.selection.border_style
Style of the selection panel borders.
Type: Style
xplr.config.general.panel_ui.sort_and_filter.title.format
The content for the sort & filter panel title.
Type: nullable string
xplr.config.general.panel_ui.sort_and_filter.title.style
Style of the sort & filter panel title.
Type: Style
xplr.config.general.panel_ui.sort_and_filter.style
Style of the sort & filter panel.
Type: Style
xplr.config.general.panel_ui.sort_and_filter.borders
Defines where to show borders for the sort & filter panel.
Type: nullable list of Border
xplr.config.general.panel_ui.sort_and_filter.border_type
Type of the borders for sort & filter panel.
Type: nullable Border Type
xplr.config.general.panel_ui.sort_and_filter.border_style
Style of the sort & filter panel borders.
Type: Style
xplr.config.general.initial_sorting
Initial group if sorters applied to the nodes list in the table.
Type: nullable list of Node Sorter
xplr.config.general.initial_mode
The name of one of the modes to use when xplr loads.
Type: nullable string
xplr.config.general.initial_layout
The name of one of the layouts to use when xplr loads.
Type: nullable string
xplr.config.general.start_fifo
Set it to a file path to start fifo when xplr loads. Generally it is used to integrate with external tools like previewers.
Type: nullable string
Node Types
This section defines how to deal with different kinds of nodes (files, directories, symlinks etc.) based on their properties.
One node can fall into multiple categories. For example, a node can have the
extension md
, and also be a file. In that case, the properties from
the more specific category i.e. extension will be used.
This can be configured using the xplr.config.node_types
Lua API.
xplr.config.node_types.directory.style
The style for the directory nodes
Type: Style
xplr.config.node_types.directory.meta.icon
Metadata for the directory nodes
Type: nullable string
xplr.config.node_types.file.style
The style for the file nodes
Type: Style
xplr.config.node_types.file.meta.icon
Metadata for the file nodes
Type: nullable string
xplr.config.node_types.symlink.style
The style for the symlink nodes
Type: Style
xplr.config.node_types.symlink.meta.icon
Metadata for the symlink nodes
Type: nullable string
Metadata and style based on mime types.
It is possible to use the wildcard *
to match all mime sub types. It will
be overwritten by the more specific sub types that are defined.
Type: mapping of the following key-value pairs:
- key: string
- value:
- key: string
- value: Node Type
Example:
xplr.config.node_types.mime_essence = {
application = {
-- application/*
["*"] = { meta = { icon = "a" } }
-- application/pdf
pdf = { meta = { icon = "" }, style = { fg = "Blue" } },
-- application/zip
zip = { meta = { icon = ""} },
},
}
xplr.config.node_types.extension
Metadata and style based on extension.
Type: mapping of the following key-value pairs:
- key: string
- value: Node Type
Example:
xplr.config.node_types.extension.md = { meta = { icon = "" }, style = { fg = "Blue" } }
xplr.config.node_types.extension.rs = { meta = { icon = "🦀" } }
xplr.config.node_types.special
Metadata and style based on special file names.
Type: mapping of the following key-value pairs:
- key: string
- value: Node Type
Example:
xplr.config.node_types.special["Cargo.toml"] = { meta = { icon = "" } }
xplr.config.node_types.special["Downloads"] = { meta = { icon = "" }, style = { fg = "Blue" } }
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.
xplr.config.layouts.builtin
contain some built-in panels which can be
overridden, but you can't add or remove panels in it.
You can add new panels in xplr.config.layouts.custom
.
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.config.layouts.builtin.default
The default layout
Type: Layout
xplr.config.layouts.builtin.no_help
The layout without help menu
Type: Layout
xplr.config.layouts.builtin.no_selection
The layout without selection panel
Type: Layout
xplr.config.layouts.builtin.no_help_no_selection
The layout without help menu and selection panel
Type: Layout
xplr.config.layouts.custom
This is where you can define custom layouts
Type: mapping of the following key-value pairs:
- key: string
- value: Layout
Example:
xplr.config.layouts.custom.example = "Nothing" -- Show a blank screen
xplr.config.general.initial_layout = "example" -- Load the example layout
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.
xplr.config.modes.builtin
contain some built-in modes which can be
overridden, but you can't add or remove modes in it.
xplr.config.modes.builtin.default
The builtin default mode. Visit the Default Key Bindings to see what each mode does.
Type: Mode
xplr.config.modes.builtin.debug_error
The builtin debug error mode.
Type: Mode
xplr.config.modes.builtin.recover
The builtin recover mode.
Type: Mode
xplr.config.modes.builtin.selection_ops
The builtin selection ops mode.
Type: Mode
xplr.config.modes.builtin.create
The builtin create mode.
Type: Mode
xplr.config.modes.builtin.create_directory
The builtin create directory mode.
Type: Mode
xplr.config.modes.builtin.create_file
The builtin create file mode.
Type: Mode
xplr.config.modes.builtin.number
The builtin number mode.
Type: Mode
xplr.config.modes.builtin.go_to
The builtin go to mode.
Type: Mode
xplr.config.modes.builtin.rename
The builtin rename mode.
Type: Mode
xplr.config.modes.builtin.duplicate_as
The builtin duplicate as mode.
Type: Mode
xplr.config.modes.builtin.delete
The builtin delete mode.
Type: Mode
xplr.config.modes.builtin.action
The builtin action mode.
Type: Mode
xplr.config.modes.builtin.quit
The builtin quit mode.
Type: Mode
xplr.config.modes.builtin.search
The builtin search mode.
Type: Mode
xplr.config.modes.builtin.filter
The builtin filter mode.
Type: Mode
xplr.config.modes.builtin.relative_path_does_match_regex
The builtin relative_path_does_match_regex mode.
Type: Mode
xplr.config.modes.builtin.relative_path_does_not_match_regex
The builtin relative_path_does_not_match_regex mode.
Type: Mode
xplr.config.modes.builtin.sort
The builtin sort mode.
Type: Mode
xplr.config.modes.builtin.switch_layout
The builtin switch layout mode.
Type: Mode
xplr.config.modes.custom
This is where you define custom modes.
Type: mapping of the following key-value pairs:
- key: string
- value: Mode
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"
Concept
These are the concepts that make xplr probably the most hackable terminal file explorer.
- Key Bindings
- Node Type
- Layout
- Mode
- Message
- Borders
- Style
- Sorting
- Filtering
- Column Renderer
- Lua Function Calls
- Environment Variables and Pipes
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-d | duplicate as | |
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 |
debug error
key | remaps | action |
---|---|---|
ctrl-c | terminate | |
enter | open logs in editor | |
esc | escape | |
q | quit |
recover
key | remaps | action |
---|---|---|
ctrl-c | terminate | |
esc | escape |
selection ops
key | remaps | action |
---|---|---|
c | copy here | |
ctrl-c | terminate | |
esc | cancel | |
m | move here | |
x | open in gui |
create
key | remaps | action |
---|---|---|
ctrl-c | terminate | |
d | create directory | |
esc | cancel | |
f | create file |
create directory
key | remaps | action |
---|---|---|
ctrl-c | terminate | |
enter | create directory | |
esc | cancel |
create file
key | remaps | action |
---|---|---|
ctrl-c | terminate | |
enter | create file | |
esc | cancel |
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 |
rename
key | remaps | action |
---|---|---|
ctrl-c | terminate | |
enter | rename | |
esc | cancel |
duplicate as
key | remaps | action |
---|---|---|
ctrl-c | terminate | |
enter | duplicate | |
esc | cancel |
delete
key | remaps | action |
---|---|---|
D | force delete | |
ctrl-c | terminate | |
d | delete | |
esc | cancel |
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 |
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 |
filter
key | remaps | action |
---|---|---|
R | relative path does not match regex | |
backspace | remove last filter | |
ctrl-c | terminate | |
ctrl-r | reset filters | |
ctrl-u | clear filters | |
enter | esc | done |
r | relative path does match regex |
relative path does match regex
key | remaps | action |
---|---|---|
ctrl-c | terminate | |
enter | apply filter | |
esc | cancel |
relative path does not match regex
key | remaps | action |
---|---|---|
ctrl-c | terminate | |
enter | apply filter | |
esc | cancel |
sort
key | remaps | action |
---|---|---|
! | reverse sorters | |
C | by created reverse | |
E | by canonical extension reverse | |
L | by last modified 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 | |
c | by created | |
ctrl-c | terminate | |
ctrl-r | reset sorters | |
ctrl-u | clear sorters | |
e | by canonical extension | |
enter | esc | done |
l | by last modified | |
m | by canonical mime essence | |
n | by node type | |
r | by relative path | |
s | by size |
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 |
quit
key | remaps | action |
---|---|---|
ctrl-c | terminate | |
enter | just quit | |
esc | cancel | |
f | quit printing focus | |
p | quit printing pwd | |
r | quit printing result | |
s | quit printing selection |
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" },
},
},
},
}
Node Type
A node-type 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",
}
}
Also See:
Layout
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",
}
}
}
A layout can be one of the following:
Nothing
This layout contains a blank panel.
Example: "Nothing"
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.
Example: "InputAndLogs"
Selection
This layout contains the panel displaying the selected paths.
Example: "Selection"
HelpMenu
This layout contains the panel displaying the help menu for the current mode in real-time.
Example: "HelpMenu"
SortAndFilter
This layout contains the panel displaying the pipeline of sorters and filters applied of the list of paths being displayed.
Example: "SortAndFilter"
Custom Content
Custom content is a special layout to render something custom. It contains the following information:
Example: { CustomContent = { title = title, body = body }
Horizontal
This is a special layout that splits the panel into two horizontal parts.
It contains the following information:
Example: { Horizontal = { config = config, splits = splits }
Vertical
This is a special layout that splits the panel into two vertical parts.
It contains the following information:
Example: { Vertical = { config = config, splits = splits }
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.
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.
Also See:
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.
Also See:
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 command-line (currently during start-up only, using
--on-load
) - Via key bindings
- Via Lua function calls
- Via shell command using the input pipe
- Via socket (coming soon)
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"] }
Also See:
Full List of Messages
xplr messages categorized based on their purpose.
Categories
- Exploring
- Screen
- Navigation
- Reading Input
- Switching Mode
- Switching Layout
- Executing Commands
- Calling Lua Functions
- Select Operations
- Filter Operations
- Sort Operations
- Mouse Operations
- Fifo Operations
- Logging
- Debugging
- Quit Options
Exploring
ExplorePwd
Explore the present working directory and register the filtered nodes. This operation is expensive. So, try to avoid using it too often.
Example:
- Lua:
"ExplorePwd"
- YAML:
ExplorePwd
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.
Example:
- Lua:
"ExplorePwdAsync"
- YAML:
ExplorePwdAsync
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.
Example:
- Lua:
"ExploreParentsAsync"
- YAML:
ExploreParentsAsync
Screen
ClearScreen
Clear the screen.
Example:
- Lua:
"ClearScreen"
- YAML:
ClearScreen
Refresh
Refresh the screen.
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.
Example:
- Lua:
"Refresh"
- YAML:
Refresh
Navigation
FocusNext
Focus next node.
Example:
- Lua:
"FocusNext"
- YAML:
FocusNext
FocusNextByRelativeIndex
Focus on the n
th node relative to the current focus where n
is a
given value.
Type: { FocusNextByRelativeIndex = int }
Example:
- Lua:
{ FocusNextByRelativeIndex = 2 }
- YAML:
FocusNextByRelativeIndex: 2
FocusNextByRelativeIndexFromInput
Focus on the n
th node relative to the current focus where n
is read
from the input buffer.
Example:
- Lua:
"FocusNextByRelativeIndexFromInput"
- YAML:
FocusNextByRelativeIndexFromInput
FocusPrevious
Focus on the previous item.
Example:
- Lua:
"FocusPrevious"
- YAML:
FocusPrevious
FocusPreviousByRelativeIndex
Focus on the -n
th node relative to the current focus where n
is a
given value.
Type: { FocusPreviousByRelativeIndex = int }
Example:
- Lua:
{ FocusPreviousByRelativeIndex = 2 }
- YAML:
FocusPreviousByRelativeIndex: 2
FocusPreviousByRelativeIndexFromInput
Focus on the -n
th node relative to the current focus where n
is
read from the input buffer.
Example:
- Lua:
"FocusPreviousByRelativeIndexFromInput"
- YAML:
FocusPreviousByRelativeIndexFromInput
FocusFirst
Focus on the first node.
Example:
- Lua:
"FocusFirst"
- YAML:
FocusFirst
FocusLast
Focus on the last node.
Example:
- Lua:
"FocusLast"
- YAML:
FocusLast
FocusPath
Focus on the given path.
Type: { FocusPath = "string" }
Example:
- Lua:
{ FocusPath = "/path/to/file" }
- YAML:
FocusPath: /path/to/file
FocusPathFromInput
Focus on the path read from input buffer.
Example:
- Lua:
"FocusPathFromInput"
- YAML:
FocusPathFromInput
FocusByIndex
Focus on the absolute n
th node where n
is a given value.
Type: { FocusByIndex = int }
Example:
- Lua:
{ FocusByIndex = 2 }
- YAML:
FocusByIndex: 2
FocusByIndexFromInput
Focus on the absolute n
th node where n
is read from the input buffer.
Example:
- Lua:
"FocusByIndexFromInput"
- YAML:
FocusByIndexFromInput
FocusByFileName
YAML: FocusByFileName: string
Focus on the file by name from the present working directory.
Type: { FocusByFileName = "string" }
Example:
- Lua:
{ FocusByFileName = "filename.ext" }
- YAML:
FocusByFileName: filename.ext
ChangeDirectory
Change the present working directory ($PWD)
Type: { ChangeDirectory = "string" }
Example:
- Lua:
{ ChangeDirectory = "/path/to/directory" }
- YAML:
ChangeDirectory: /path/to/directory
Enter
Enter into the currently focused path if it's a directory.
Example:
- Lua:
"Enter"
- YAML:
Enter
Back
Go back to the parent directory.
Example:
- Lua:
"Back"
- YAML:
Back
LastVisitedPath
Go to the last path visited.
Example:
- Lua:
"LastVisitedPath"
- YAML:
LastVisitedPath
NextVisitedPath
Go to the next path visited.
Example:
- Lua:
"NextVisitedPath"
- YAML:
NextVisitedPath
FollowSymlink
Follow the symlink under focus to its actual location.
Example:
Lua: "FollowSymlink"
YAML: FollowSymlink
Reading Input
SetInputPrompt
Set the input prompt temporarily, until the input buffer is reset.
Type: { SetInputPrompt = string }
Example:
- Lua:
{ SetInputPrompt = "→" }
- YAML:
SetInputPrompt: →
UpdateInputBuffer
Update the input buffer using cursor based operations.
Type: { UpdateInputBuffer = Input Opertaion }
Example:
- Lua:
{ UpdateInputBuffer = "GoToPreviousWord" }
- YAML:
UpdateInputBuffer: GoToPreviousWord
UpdateInputBufferFromKey
Update the input buffer from the key read from keyboard input.
Example:
- Lua:
"UpdateInputBufferFromKey"
- YAML:
UpdateInputBufferFromKey
BufferInput
Append/buffer the given string into the input buffer.
Type: { BufferInput = "string" }
Example:
- Lua:
{ BufferInput = "foo" }
- YAML:
BufferInput: foo
BufferInputFromKey
Append/buffer the characted read from a keyboard input into the input buffer.
Example:
- Lua:
"BufferInputFromKey"
- YAML:
BufferInputFromKey
SetInputBuffer
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.
Type: { SetInputBuffer = "string" }
Example:
- Lua:
{ SetInputBuffer = "foo" }
- YAML:
SetInputBuffer: foo
RemoveInputBufferLastCharacter
Remove input buffer's last character.
Example:
- Lua:
"RemoveInputBufferLastCharacter"
- YAML:
RemoveInputBufferLastCharacter
RemoveInputBufferLastWord
Remove input buffer's last word.
Example:
- Lua:
"RemoveInputBufferLastWord"
- YAML:
RemoveInputBufferLastWord
ResetInputBuffer
Reset the input buffer back to null. It will not show in the UI.
Example:
- Lua:
"ResetInputBuffer"
- YAML:
ResetInputBuffer
Switching Mode
SwitchMode
Switch input mode.
Type : { SwitchMode = "string" }
Example:
- Lua:
{ SwitchMode = "default" }
- YAML: SwitchMode: default
NOTE: To be specific about which mode to switch to, use
SwitchModeBuiltinKeepingInputBuffer
orSwitchModeCustomKeepingInputBuffer
instead.
SwitchModeKeepingInputBuffer
Switch input mode. It keeps the input buffer.
Type: { SwitchModeKeepingInputBuffer = "string" }
Example:
- Lua:
{ SwitchModeKeepingInputBuffer = "default" }
- YAML:
SwitchModeKeepingInputBuffer: default
NOTE: To be specific about which mode to switch to, use
SwitchModeBuiltinKeepingInputBuffer
orSwitchModeCustomKeepingInputBuffer
instead.
SwitchModeBuiltin
Switch to a builtin mode. It clears the input buffer.
Type: { SwitchModeBuiltin = "string" }
Example:
- Lua:
{ SwitchModeBuiltin = "default" }
- YAML:
SwitchModeBuiltin: default
SwitchModeBuiltinKeepingInputBuffer
Switch to a builtin mode. It keeps the input buffer.
Type: { SwitchModeBuiltinKeepingInputBuffer = "string" }
Example:
- Lua:
{ SwitchModeBuiltinKeepingInputBuffer = "default" }
- YAML:
SwitchModeBuiltinKeepingInputBuffer: default
SwitchModeCustom
Switch to a custom mode. It clears the input buffer.
Type: { SwitchModeCustom = "string" }
Example:
- Lua:
{ SwitchModeCustom = "my_custom_mode" }
- YAML:
SwitchModeCustom: my_custom_mode
SwitchModeCustomKeepingInputBuffer
Switch to a custom mode. It keeps the input buffer.
Type: { SwitchModeCustomKeepingInputBuffer = "string" }
Example:
- Lua:
{ SwitchModeCustomKeepingInputBuffer = "my_custom_mode" }
- YAML:
SwitchModeCustomKeepingInputBuffer: my_custom_mode
PopMode
Pop the last mode from the history and switch to it. It clears the input buffer.
Example:
- Lua:
"PopMode"
- YAML:
PopMode
PopModeKeepingInputBuffer
Pop the last mode from the history and switch to it. It keeps the input buffer.
Example:
- Lua:
PopModeKeepingInputBuffer
- YAML:
PopModeKeepingInputBuffer
Switching Layout
SwitchLayout
Switch layout.
Type: { SwitchLayout = "string" }
Example:
- Lua:
{ SwitchLayout = "default" }
- YAML:
SwitchLayout: default
NOTE: To be specific about which layout to switch to, use
SwitchLayoutBuiltin
orSwitchLayoutCustom
instead.
SwitchLayoutBuiltin
Switch to a builtin layout.
Type: { SwitchLayoutBuiltin = "string" }
Example:
- Lua:
{ SwitchLayoutBuiltin = "default" }
- YAML:
SwitchLayoutBuiltin: default
SwitchLayoutCustom
Switch to a custom layout.
Type: { SwitchLayoutCustom = "string" }
Example:
- Lua:
{ SwitchLayoutCustom = "my_custom_layout" }
- YAML:
SwitchLayoutCustom: my_custom_layout
Executing Commands
Call
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.
Type: { Call = "string" }
Example:
- Lua:
{ Call = { command = "bash", args = { "-c", "read -p test" } } }
- YAML:
Call: { command: bash, args: ["-c", "read -p test"] }
CallSilently
Like Call
but without the flicker. The stdin, stdout
stderr will be piped to null. So it's non-interactive.
Type: { CallSilently = "string" }
Example:
- Lua:
{ CallSilently = { command = "tput", args = { "bell" } } }
- YAML:
CallSilently: { command: tput, args: ["bell"] }
BashExec
An alias to Call: {command: bash, args: ["-c", "{string}"], silent: false}
where {string}
is the given value.
Type: { BashExec = "string" }
Example:
- Lua:
{ BashExec = "read -p test" }
- YAML:
BashExec: "read -p test"
BashExecSilently
Like BashExec
but without the flicker. The stdin, stdout
stderr will be piped to null. So it's non-interactive.
Type: { BashExecSilently = "string" }
Example:
- Lua:
{ BashExecSilently = "tput bell" }
- YAML:
BashExecSilently: "tput bell"
Calling Lua Functions
CallLua
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.
Type: { CallLua = "string" }
Example:
- Lua:
{ CallLua = "custom.some_custom_funtion" }
- YAML:
CallLua: custom.some_custom_funtion
CallLuaSilently
Like CallLua
but without the flicker. The stdin, stdout
stderr will be piped to null. So it's non-interactive.
Type: { CallLuaSilently = "string" }
Example:
- Lua:
{ CallLuaSilently = "custom.some_custom_function" }
- YAML:
CallLuaSilently: custom.some_custom_function
LuaEval
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.
Type: { LuaEval = "string" }
Example:
- Lua:
{ LuaEval = [[return { { LogInfo = io.read() } }]] }
- Lua:
{ LuaEval = [[function(app) return { { LogInfo = app.pwd } } end]] }
- YAML:
LuaEval: "return { { LogInfo = io.read() } }"
- YAML:
LuaEval: "function(app) return { { LogInfo = app.pwd } } end"
LuaEvalSilently
Like LuaEval
but without the flicker. The stdin, stdout
stderr will be piped to null. So it's non-interactive.
Type: { LuaEvalSilently = "string" }
Example:
- Lua:
{ LuaEvalSilently = [[return { { LogInfo = "foo" } }]] }
- YAML:
LuaEvalSilently: "return { { LogInfo = 'foo' } }"
Select Operations
Select
Select the focused node.
Example:
- Lua:
"Select"
- YAML:
Select
SelectAll
Select all the visible nodes.
Example:
- Lua:
"SelectAll"
- YAML:
SelectAll
SelectPath
Select the given path.
Type: { SelectPath = "string" }
Example:
- Lua:
{ SelectPath = "/path/to/file" }
- YAML:
SelectPath: /path/to/file
UnSelect
Unselect the focused node.
Example:
- Lua:
"UnSelect"
- YAML:
UnSelect
UnSelectAll
Unselect all the visible nodes.
Example:
- Lua:
"UnSelectAll"
- YAML:
UnSelectAll
UnSelectPath
UnSelect the given path.
Type: { UnSelectPath = "string)" }
Example:
- Lua:
{ UnSelectPath = "/path/to/file" }
- YAML:
UnSelectPath: /path/to/file
ToggleSelection
Toggle selection on the focused node.
Example:
- Lua:
"ToggleSelection"
- YAML
ToggleSelection
ToggleSelectAll
Toggle between select all and unselect all. Example:
- Lua:
"ToggleSelectAll"
- YAML:
ToggleSelectAll
ToggleSelectionByPath
Toggle selection by file path.
Type: { ToggleSelectionByPath = "string" }
Example:
- Lua:
{ ToggleSelectionByPath = "/path/to/file" }
- YAML:
ToggleSelectionByPath: /path/to/file
ClearSelection
Clear the selection.
Example:
- Lua:
"ClearSelection"
- YAML:
ClearSelection
Filter Operations
AddNodeFilter
Add a filter to exclude nodes while exploring directories.
Type: { AddNodeFilter = { filter = Filter, input = "string" }
Example:
- Lua:
{ AddNodeFilter = { filter = "RelativePathDoesStartWith", input = "foo" } }
- YAML:
AddNodeFilter: { filter: RelativePathDoesStartWith, input: foo }
RemoveNodeFilter
Remove an existing filter.
Type: { RemoveNodeFilter = { filter = Filter, input = "string" }
Example:
- Lua:
{ RemoveNodeFilter: { filter: "RelativePathDoesStartWith", input: "foo" } }
- YAML:
RemoveNodeFilter: { filter: RelativePathDoesStartWith, input: foo }
ToggleNodeFilter
Remove a filter if it exists, else, add a it.
Type: { ToggleNodeFilter = { filter = Filter, input = "string" }
Example:
- Lua:
{ ToggleNodeFilter = { filter = "RelativePathDoesStartWith", input = "foo" } }
- YAML:
ToggleNodeFilter: { filter: RelativePathDoesStartWith, input: foo }
AddNodeFilterFromInput
Add a node filter reading the input from the buffer.
Type: { AddNodeFilterFromInput = Filter }
Example:
- Lua:
{ AddNodeFilterFromInput = "RelativePathDoesStartWith" }
- YAML:
AddNodeFilterFromInput: RelativePathDoesStartWith
RemoveNodeFilterFromInput
Remove a node filter reading the input from the buffer.
Type: { RemoveNodeFilterFromInput = Filter }
Example:
- Lua:
{ RemoveNodeFilterFromInput = "RelativePathDoesStartWith" }
- YAML:
RemoveNodeFilterFromInput: RelativePathDoesStartWith
RemoveLastNodeFilter
Remove the last node filter.
Example:
- Lua:
"RemoveLastNodeFilter"
- YAML:
RemoveLastNodeFilter
ResetNodeFilters
Reset the node filters back to the default configuration.
Example:
- Lua:
"ResetNodeFilters"
- YAML:
ResetNodeFilters
ClearNodeFilters
Clear all the node filters.
Example:
- Lua:
"ClearNodeFilters"
- YAML:
ClearNodeFilters
Sort Operations
AddNodeSorter
Add a sorter to sort nodes while exploring directories.
Type: { AddNodeSorter = { sorter = Sorter, reverse = bool } }
Example:
- Lua:
{ AddNodeSorter = { sorter = "ByRelativePath", reverse = false } }
- YAML:
AddNodeSorter: { sorter: ByRelativePath, reverse: false }
RemoveNodeSorter
Remove an existing sorter.
Type: { RemoveNodeSorter = Sorter }
Example:
- Lua:
{ RemoveNodeSorter = "ByRelativePath" }
- YAML:
RemoveNodeSorter: ByRelativePath
ReverseNodeSorter
Reverse a node sorter.
Type: { ReverseNodeSorter = Sorter }
Example:
- Lua:
{ ReverseNodeSorter = "ByRelativePath" }
- YAML:
ReverseNodeSorter: ByRelativePath
ToggleNodeSorter
Remove a sorter if it exists, else, add a it.
Type: { ToggleNodeSorter = { sorter = Sorter, reverse = bool } }
Example:
- Lua:
{ ToggleSorterSorter: { sorter = "ByRelativePath", reverse = false } }
- YAML:
ToggleSorterSorter: {sorter: ByRelativePath, reverse: false }
ReverseNodeSorters
Reverse the node sorters.
Example:
- Lua:
"ReverseNodeSorters"
- YAML:
ReverseNodeSorters
RemoveLastNodeSorter
Remove the last node sorter.
Example:
- Lua:
"RemoveLastNodeSorter"
- YAML:
RemoveLastNodeSorter
ResetNodeSorters
Reset the node sorters back to the default configuration.
Example:
- Lua:
"ResetNodeSorters"
- YAML:
ResetNodeSorters
ClearNodeSorters
Clear all the node sorters.
Example:
- Lua:
"ClearNodeSorters"
- YAML:
ClearNodeSorters
Mouse Operations
EnableMouse
Enable mouse
Example:
- Lua:
"EnableMouse"
- YAML:
EnableMouse
DisableMouse
Disable mouse
Example:
- Lua:
"DisableMouse"
- YAML:
DisableMouse
ToggleMouse
Toggle mouse
Example:
- Lua:
"ToggleMouse"
- YAML:
ToggleMouse
Fifo Operations
StartFifo
Start piping the focused path to the given fifo path
Type: { StartFifo = "string" }
Example:
- Lua:
{ StartFifo = "/tmp/xplr.fifo }
- YAML:
StartFifo: /tmp/xplr.fifo
StopFifo
Close the active fifo and stop piping.
Example:
- Lua:
"StopFifo"
- YAML:
StopFifo
ToggleFifo
Toggle betwen {Start|Stop}Fifo
Type: { ToggleFifo = "string" }
Example:
- Lua:
{ ToggleFifo = "/path/to/fifo" }
- YAML:
ToggleFifo: /path/to/fifo
Logging
LogInfo
Log information message.
Type: { LogInfo = "string" }
Example:
- Lua:
{ LogInfo = "launching satellite" }
- YAML:
LogInfo: launching satellite
LogSuccess
Log a success message.
Type: { LogSuccess = "String" }
Example:
- Lua:
{ LogSuccess = "satellite reached destination" }
- YAML:
LogSuccess: satellite reached destination
LogWarning
Log an warning message.
Type: { LogWarning = "string" }
Example:
- Lua:
{ LogWarning = "satellite is heating" }
- YAML:
LogWarning: satellite is heating
LogError
Log an error message.
Type: { LogError = "string" }
Example:
- Lua:
{ LogError = "satellite crashed" }
- YAML:
LogError: satellite crashed
Debugging
Debug
Write the application state to a file, without quitting. Also helpful for debugging.
Type: { Debug = "string" }
Example:
- Lua:
{ Debug = "/path/to/file" }
- YAML:
Debug: /path/to/file
Quit Options
Quit
Example:
- Lua:
"Quit"
- YAML:
Quit
Quit with returncode zero (success).
PrintPwdAndQuit
Print $PWD and quit.
Example:
- Lua:
"PrintPwdAndQuit"
- YAML:
PrintPwdAndQuit
PrintFocusPathAndQuit
Print the path under focus and quit. It can be empty string if there's nothing to focus.
Example:
- Lua:
"PrintFocusPathAndQuit"
- YAML:
PrintFocusPathAndQuit
PrintSelectionAndQuit
Print the selected paths and quit. It can be empty is no path is selected.
Example:
- Lua:
"PrintSelectionAndQuit"
- YAML:
PrintSelectionAndQuit
PrintResultAndQuit
Print the selected paths if it's not empty, else, print the focused node's path.
Example:
- Lua:
"PrintResultAndQuit"
- YAML:
PrintResultAndQuit
PrintAppStateAndQuit
Print the state of application in YAML format. Helpful for debugging or generating the default configuration file.
Example:
- Lua:
"PrintAppStateAndQuit"
- YAML:
PrintAppStateAndQuit
Terminate
Terminate the application with a non-zero return code.
Example:
- Lua:
"Terminate"
- YAML:
Terminate
Also See:
Input Operation
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"
Also See:
Borders
xplr allows customizing the shape and style of the borders.
Border
A border can be one of the following:
- Top
- Right
- Bottom
- Left
Border Type
A border can be one of the following:
- Plain
- Rounded
- Double
- Thick
Example
xplr.config.general.panel_ui.default.borders = { "Top", "Right", "Bottom", "Left" }
xplr.config.general.panel_ui.default.border_type = "Thick"
xplr.config.general.panel_ui.default.border_style.fg = "Black"
xplr.config.general.panel_ui.default.border_style.bg = "Gray"
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"
- "ByCreated"
- "ByLastModified"
- "ByCanonicalAbsolutePath"
- "ByICanonicalAbsolutePath"
- "ByCanonicalExtension"
- "ByCanonicalIsDir"
- "ByCanonicalIsFile"
- "ByCanonicalIsReadonly"
- "ByCanonicalMimeEssence"
- "ByCanonicalSize"
- "ByCanonicalCreated"
- "ByCanonicalLastModified"
- "BySymlinkAbsolutePath"
- "ByISymlinkAbsolutePath"
- "BySymlinkExtension"
- "BySymlinkIsDir"
- "BySymlinkIsFile"
- "BySymlinkIsReadonly"
- "BySymlinkMimeEssence"
- "BySymlinkSize"
- "BySymlinkCreated"
- "BySymlinkLastModified"
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"
- "RelativePathDoesMatchRegex"
- "RelativePathDoesNotMatchRegex"
- "IRelativePathDoesMatchRegex"
- "IRelativePathDoesNotMatchRegex"
- "AbsolutePathIs"
- "AbsolutePathIsNot"
- "IAbsolutePathIs"
- "IAbsolutePathIsNot"
- "AbsolutePathDoesStartWith"
- "AbsolutePathDoesNotStartWith"
- "IAbsolutePathDoesStartWith"
- "IAbsolutePathDoesNotStartWith"
- "AbsolutePathDoesContain"
- "AbsolutePathDoesNotContain"
- "IAbsolutePathDoesContain"
- "IAbsolutePathDoesNotContain"
- "AbsolutePathDoesEndWith"
- "AbsolutePathDoesNotEndWith"
- "IAbsolutePathDoesEndWith"
- "IAbsolutePathDoesNotEndWith"
- "AbsolutePathDoesMatchRegex"
- "AbsolutePathDoesNotMatchRegex"
- "IAbsolutePathDoesMatchRegex"
- "IAbsolutePathDoesNotMatchRegex"
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
- created
- last_modified
- 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.
created
Type: nullable integer
Creation time in nanosecond since UNIX epoch.
last_modified
Type: nullable integer
Last modification time in nanosecond since UNIX epoch.
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.
- absolute_path
- extension
- is_dir
- is_file
- is_readonly
- mime_essence
- size
- human_size
- created
- last_modified
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.
Lua Function Calls
xplr allows you 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.
created
Type: nullable integer
Creation time in nanosecond since UNIX epoch.
last_modified
Type: nullable integer
Last modification time in nanosecond since UNIX epoch.
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
- created
- last_modified
- 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.
To see the environment variables and pipes, 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.
The other variables are single-line variables containing simple information:
- XPLR_APP_VERSION
- XPLR_FOCUS_INDEX
- XPLR_FOCUS_PATH
- XPLR_INPUT_BUFFER
- XPLR_MODE
- XPLR_PID
- XPLR_SESSION_PATH
Environment variables
XPLR_APP_VERSION
Self-explanatory.
XPLR_FOCUS_INDEX
Contains the index of the currently focused item, as seen in column-renderer/index.
XPLR_FOCUS_PATH
Contains the full path of the currently focused node.
XPLR_INPUT_BUFFER
The line currently in displaying in the xplr input buffer. For e.g. the search input while searching. See Reading Input.
XPLR_MODE
Contains the mode xplr is currently in, see modes.
XPLR_PID
Contains the process ID of the current xplr process.
XPLR_SESSION_PATH
Contains the current session path, like /tmp/runtime-"$USER"/xplr/session/"$XPLR_PID"/, you can find temporary files here, such as pipes.
Pipes
Input pipe
Currently 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 strings.
These pipes can be accessed as plaintext files located in $XPLR_SESSION_PATH.
- 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.
Another example: Simple file opener using xdg-open and $XPLR_FOCUS_PATH
xplr.config.modes.builtin.default.key_bindings.on_key.X = {
help = "open",
messages = {
{
BashExec = [===[
xdg-open "${XPLR_FOCUS_PATH:?}"
]===],
},
},
}
Awesome Hacks
Here's a list of cool xplr hacks, i.e. snippets of code that you can just copy and paste into your configuration or the appropriate file, that are too small or too niche for a full fledge plugin.
Do you have something cool to share?
Edit this file or share them here or let us know.
cd on quit
Change directory using xplr.
Expand for details
- Author: @sayanarijit
- Tested on: Linux
With this alias set, you can navigate directories using xplr by entering xcd command, and when you quit by pressing enter, you will enter the directory.
You can of course, quit with plain Quit (i.e. by pressing q) to gracefully cancel "cd on quit".
alias xcd='cd "$(xplr --print-pwd-as-result)"'
Spawn multiple sessions in different tabs (iTerm2)
Creating a new session that starts with iTerm2.
Expand for details
- Author: @lmburns
- Requires: iTerm2
- Tested on: MacOS
xplr.config.modes.builtin.default.key_bindings.on_key["ctrl-n"] = {
help = "new session",
messages = {
{ BashExecSilently = [[
osascript <<EOF
tell application "iTerm2"
tell current window
create tab with default profile
tell current session to write text "xplr"
end tell
end tell
]]
},
},
}
Bookmark
Bookmark files using m
and fuzzy search bookmarks using backtick.
Expand for details
- Author: @sayanarijit
- Requires: fzf
- Tested on: Linux
xplr.config.modes.builtin.default.key_bindings.on_key.m = {
help = "bookmark",
messages = {
{
BashExecSilently = [===[
PTH="${XPLR_FOCUS_PATH:?}"
if echo "${PTH:?}" >> "${XPLR_SESSION_PATH:?}/bookmarks"; then
echo "LogSuccess: ${PTH:?} added to bookmarks" >> "${XPLR_PIPE_MSG_IN:?}"
else
echo "LogError: Failed to bookmark ${PTH:?}" >> "${XPLR_PIPE_MSG_IN:?}"
fi
]===],
},
},
}
xplr.config.modes.builtin.default.key_bindings.on_key["`"] = {
help = "go to bookmark",
messages = {
{
BashExec = [===[
PTH=$(cat "${XPLR_SESSION_PATH:?}/bookmarks" | fzf --no-sort)
if [ "$PTH" ]; then
echo FocusPath: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}"
fi
]===],
},
},
}
Persistent, multi-session bookmark
A bookmark mode that allows for a bookmark file to be used throughout multiples
sessions. It is set to the environment variable $XPLR_BOOKMARK_FILE
. A
bookmark can be added, deleted, or jumped to.
Expand for details
- Author: @lmburns
- Requires: fzf, sd
- Tested on: MacOS
-- Bookmark: mode binding
xplr.config.modes.custom.bookmark = {
name = "bookmark",
key_bindings = {
on_key = {
m = {
help = "bookmark dir",
messages = {
{ BashExecSilently = [[
PTH="${XPLR_FOCUS_PATH:?}"
if [ -d "${PTH}" ]; then
PTH="${PTH}"
elif [ -f "${PTH}" ]; then
PTH="$(dirname "${PTH}")"
fi
if echo "${PTH:?}" >> "${XPLR_BOOKMARK_FILE:?}"; then
echo "LogSuccess: ${PTH:?} added to bookmarks" >> "${XPLR_PIPE_MSG_IN:?}"
else
echo "LogError: Failed to bookmark ${PTH:?}" >> "${XPLR_PIPE_MSG_IN:?}"
fi
]]
},
},
},
g = {
help = "go to bookmark",
messages = {
{
BashExec = [===[
PTH=$(cat "${XPLR_BOOKMARK_FILE:?}" | fzf --no-sort)
if [ "$PTH" ]; then
echo FocusPath: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}"
fi
]===]
},
},
},
d = {
help = "delete bookmark",
messages = {
{ BashExec = [[
PTH=$(cat "${XPLR_BOOKMARK_FILE:?}" | fzf --no-sort)
sd "$PTH\n" "" "${XPLR_BOOKMARK_FILE:?}"
]]
},
},
},
esc = {
help = "cancel",
messages = {
"PopMode",
},
},
},
},
}
Another bookmark manager type thing, taken from wfxr's zsh plugin.
Another bookmark manager type thing, taken from wfxr's zsh plugin which has colored output with fzf.
Expand for details
- Author: @lmburns
- Requires: fzf, exa
- Tested on: MacOS
xplr.config.modes.builtin.go_to.key_bindings.on_key.b = {
help = "bookmark jump",
messages = {
"PopMode",
{ BashExec = [===[
field='\(\S\+\s*\)'
esc=$(printf '\033')
N="${esc}[0m"
R="${esc}[31m"
G="${esc}[32m"
Y="${esc}[33m"
B="${esc}[34m"
pattern="s#^${field}${field}${field}${field}#$Y\1$R\2$N\3$B\4$N#"
PTH=$(sed 's#: # -> #' "$PATHMARKS_FILE"| nl| column -t \
| gsed "${pattern}" \
| fzf --ansi \
--height '40%' \
--preview="echo {}|sed 's#.*-> ##'| xargs exa --color=always" \
--preview-window="right:50%" \
| sed 's#.*-> ##')
if [ "$PTH" ]; then
echo ChangeDirectory: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}"
fi
]===]
},
}
}
Fuzzy search history
Fuzzy search the last visited directories.
Expand for details
- Author: @sayanarijit
- Requires: fzf
- Tested on: Linux
xplr.config.modes.builtin.go_to.key_bindings.on_key.h = {
help = "history",
messages = {
"PopMode",
{
BashExec = [===[
PTH=$(cat "${XPLR_PIPE_HISTORY_OUT:?}" | sort -u | fzf --no-sort)
if [ "$PTH" ]; then
echo ChangeDirectory: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}"
fi
]===],
},
},
}
Batch rename
Batch rename the selected or visible files and directories in $PWD.
Expand for details
- Author: @sayanarijit
- Requires: pipe-rename
- Tested on: Linux
xplr.config.modes.builtin.default.key_bindings.on_key.R = {
help = "batch rename",
messages = {
{
BashExec = [===[
SELECTION=$(cat "${XPLR_PIPE_SELECTION_OUT:?}")
NODES=${SELECTION:-$(cat "${XPLR_PIPE_DIRECTORY_NODES_OUT:?}")}
if [ "$NODES" ]; then
echo -e "$NODES" | renamer
echo ExplorePwdAsync >> "${XPLR_PIPE_MSG_IN:?}"
fi
]===],
},
},
}
Serve $PWD
Serve $PWD using a static web server via LAN.
Expand for details
- Author: @sayanarijit
- Requires: sfz, fzf
- Tested on: Linux
xplr.config.modes.builtin.default.key_bindings.on_key.S = {
help = "serve $PWD",
messages = {
{
BashExec = [===[
IP=$(ip addr | grep -w inet | cut -d/ -f1 | grep -Eo '[0-9]{1,3}\.[0-9]{ 1,3}\.[0-9]{1,3}\.[0-9]{1,3}' | fzf --prompt 'Select IP > ')
echo "IP: ${IP:?}"
read -p "Port (default 5000): " PORT
echo
sfz --all --cors --no-ignore --bind ${IP:?} --port ${PORT:-5000} . &
sleep 1 && read -p '[press enter to exit]'
kill -9 %1
]===],
},
},
}
Image viewer (imv)
Preview images using imv.
Expand for details
- Author: @sayanarijit
- Requires: imv, xdotool
- Tested on: Linux
xplr.config.modes.builtin.default.key_bindings.on_key.P = {
help = "preview",
messages = {
{
BashExecSilently = [===[
FIFO_PATH="/tmp/xplr.fifo"
if [ -e "$FIFO_PATH" ]; then
echo StopFifo >> "$XPLR_PIPE_MSG_IN"
rm "$FIFO_PATH"
else
mkfifo "$FIFO_PATH"
"$HOME/.local/bin/imv-open.sh" "$FIFO_PATH" "$XPLR_FOCUS_PATH" &
echo "StartFifo: '$FIFO_PATH'" >> "$XPLR_PIPE_MSG_IN"
fi
]===],
},
},
}
$HOME/.local/bin/imv-open.sh
#!/usr/bin/env bash
FIFO_PATH="$1"
IMAGE="$2"
MAINWINDOW="$(xdotool getactivewindow)"
IMV_PID="$(pgrep imv)"
if [ ! "$IMV_PID" ]; then
imv "$IMAGE" &
IMV_PID=$!
fi
sleep 0.5
xdotool windowactivate "$MAINWINDOW"
while read -r path; do
imv-msg "$IMV_PID" close all
imv-msg "$IMV_PID" open "$path"
done < "$FIFO_PATH"
imv-msg "$IMV_PID" quit
[ -e "$FIFO_PATH" ] && rm -f "$FIFO_PATH"
Also See:
Plugin
xplr supports pluggable Lua modules that can be used to easily configure or extend xplr UI and functionalities.
Installing Plugins
One way to install plugins is to use a plugin manager like dtomvan/xpm.xplr.
But you can also install and manage plugins manually.
Install Manually
-
Add the following line in
~/.config/xplr/init.lua
local home = os.getenv("HOME") package.path = home .. "/.config/xplr/plugins/?/init.lua;" .. home .. "/.config/xplr/plugins/?.lua;" .. package.path
-
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.
Luarocks Support
Some plugins may require luarocks to work.
Setup luarocks with the following steps:
-
Install luarocks (via your package managers or follow the official guide).
-
Add
eval "$(luarocks path --lua-version 5.1)"
in your.bashrc
or.zshrc
. -
Add the following lines in
~/.config/xplr/init.lua
package.path = os.getenv("LUA_PATH") .. ";" .. package.path package.cpath = os.getenv("LUA_CPATH") .. ";" .. package.cpath
Now you can install packages using luarocks. Be sure to append
--lua-version
.
Example:
luarocks install luafilesystem --local --lua-version 5.1
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
└── init.lua
You can also use this template.
README.md
This is where you document what the plugin does, how to use it, etc.
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.
Extension
- sayanarijit/command-mode.xplr The missing command mode for xplr.
- igorepst/context-switch.xplr Context switch plugin for xplr.
- sayanarijit/dual-pane.xplr Implements support for dual-pane navigation into xplr.
- sayanarijit/map.xplr Visually inspect and interactively execute batch commands using xplr.
- sayanarijit/registers.xplr Use multiple registers to store the selected paths.
- prncss-xyz/type-to-nav.xplr Inspired by nnn's type-to-nav mode for xplr, with some tweaks.
- igorepst/term.xplr Terminal integration for xplr
- dtomvan/xpm.xplr The XPLR Plugin Manager
Integration
- sayanarijit/alacritty.xplr Alacritty integration for xplr.
- sayanarijit/dragon.xplr Drag and drop files using dragon.
- sayanarijit/dua-cli.xplr Get the disk usage using dua-cli with selection support.
- sayanarijit/fzf.xplr Fuzzy search using fzf to focus on a file or enter
- sayanarijit/find.xplr An interactive finder plugin to complement map.xplr.
- sayanarijit/nvim-ctrl.xplr Send files to running Neovim sessions using nvim-ctrl.
- dtomvan/ouch.xplr This plugin uses ouch to compress and decompress files.
- dtomvan/paste-rs.xplr Use this plugin to paste your files to paste.rs, and open/delete them later using fzf.
- sayanarijit/preview-tabbed.xplr Preview paths using suckless tabbed and nnn preview-tabbed.
- sayanarijit/qrcp.xplr Send and receive files via QR code using qrcp.
- sayanarijit/trash-cli.xplr Trash files and directories using trash-cli.
- sayanarijit/xargs.xplr Batch execute commands on the focused or selected files
using
xargs
. - sayanarijit/xclip.xplr Copy and paste with system clipboard using xclip.
- sayanarijit/zoxide.xplr Change directory using the zoxide database.
Theme
- sayanarijit/material-landscape.xplr Material Landscape
- sayanarijit/material-landscape2.xplr Material Landscape 2
- sayanarijit/zentable.xplr A clean, distraction free xplr table UI
- prncss-xyz/icons.xplr An icon theme for xplr.
Also See:
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.
Editor
- fm-nvim Neovim plugin that lets you use your favorite terminal file managers from within Neovim.
- 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.
Shell
- powerlevel10k Powerlevel10k prompt for xplr shell.
Security Tools
- gpg-tui Import GPG certificates using xplr.
Also See:
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.17.6 -> v0.18.0
- Added new command-line arguments
--read0
,--write0
and-0
/--null
to support reading and printing null character delimited file paths. - Added support for filtering with regex using the new filters:
RelativePathDoesMatchRegex
RelativePathDoesNotMatchRegex
IRelativePathDoesMatchRegex
IRelativePathDoesNotMatchRegex
AbsolutePathDoesMatchRegex
AbsolutePathDoesNotMatchRegex
IAbsolutePathDoesMatchRegex
IAbsolutePathDoesNotMatchRegex
- Key binding
f
r
andf
R
will now filter using regex. - Added key binding
f
backspace
to remove the last filter. - Search mode now defaults to regex search.
- Added a new message
SetInputPrompt
to set the input prompt dynamically. - Added new node properties (available via the Lua API):
created
last_modified
- Added support for sorting with timestamp using the new sorters:
- "ByCreated"
- "ByLastModified"
- "ByCanonicalCreated"
- "ByCanonicalLastModified"
- "BySymlinkCreated"
- "BySymlinkLastModified"
- The last column in the files table now displays the last modification time.
- Fixed a bug causing crashes when handling unicode characters in the input buffer.
- Improved docs.
Like this project so far? Please consider contributing.
v0.16.4 -> v0.17.6
- 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.hide_remaps_in_help_menu
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.- From version v0.17.1, set
xplr.config.general.disable_debug_error_mode
totrue
to disable switching to the "debug error" mode when startup errors occur. - From version v0.17.2, you can use CLI argument
--print-pwd-as-result
for cd on quit, and key bindingctrl-d
to duplicate a path in the same directory with a different name. - Since version v0.17.3, you can use
border_type
,border_style
to customize borders, andenforce_bounded_index_navigation
to customize up/down navigation behavior when focus is on the top or bottom node.
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
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.