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 modal system based on message passing to control xplr session using:
Easy, typesafe message passing with -m MSG or -M MSG subcommands.
Readline-like input buffer with customizable behavior 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.
Virtual root with --vroot and :v key bindings.
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).

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

(same for Manjaro Linux)

Official Community Repo

sudo pacman -S xplr

AUR

Git version:

paru -S xplr-git

Alpine Linux

Edge Testing Repo

# Add the following line in /etc/apk/repositories:
# https://dl-cdn.alpinelinux.org/alpine/edge/testing

apk add xplr bash less

Void Linux

void-templates by shubham

Gentoo

Overlay GURU

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

cd /usr/ports/misc/xplr
make install clean

NetBSD

pkgsrc

pkgin install xplr

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 --version | awk '{print $2}')"

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.try_complete_path

Tries to auto complete the path in the input buffer

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.

Hooks

This section of the configuration cannot be overwritten by another config file or plugin, since this is an optional lua return statement specific to each config file. It can be used to define things that should be explicit for reasons like performance concerns, such as hooks.

Plugins should expose the hooks, and require users to subscribe to them explicitly.

Example:

return {
  -- Add messages to send when the xplr loads.
  -- This is similar to the `--on-load` command-line option.
  --
  -- Type: list of [Message](https://xplr.dev/en/message#message)s
  on_load = {
    { LogSuccess = "Configuration successfully loaded!" },
    { CallLuaSilently = "custom.some_plugin_with_hooks.on_load" },
  },

  -- Add messages to send when the directory changes.
  --
  -- Type: list of [Message](https://xplr.dev/en/message#message)s
  on_directory_change = {
    { LogSuccess = "Changed directory" },
    { CallLuaSilently = "custom.some_plugin_with_hooks.on_directory_change" },
  },

  -- Add messages to send when the focus changes.
  --
  -- Type: list of [Message](https://xplr.dev/en/message#message)s
  on_focus_change = {
    { LogSuccess = "Changed focus" },
    { CallLuaSilently = "custom.some_plugin_with_hooks.on_focus_change" },
  }
}

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:

key: Sorter
value:
- format: nullable string
- style: Style

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:

key: Filter
value:
- format: nullable string
- style: Style

xplr.config.general.sort_and_filter_ui.search_identifier

The identifiers used to denote applied search input.

Type: { format = nullable string, style = Style }

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

xplr.config.general.global_key_bindings

Use it to define a set of key bindings that are available by default in every mode. They can be overwritten.

Type: Key Bindings

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. You can set as many metadata as you want.

Type: nullable string

Example:

xplr.config.node_types.directory.meta.foo = "foo"
xplr.config.node_types.directory.meta.bar = "bar"

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. You can set as many metadata as you want.

Type: nullable string

Example:

xplr.config.node_types.file.meta.foo = "foo"
xplr.config.node_types.file.meta.bar = "bar"

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. You can set as many metadata as you want.

Type: nullable string

Example:

xplr.config.node_types.symlink.meta.foo = "foo"
xplr.config.node_types.symlink.meta.bar = "bar"

xplr.config.node_types.mime_essence

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

demo

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.go_to_path

The builtin go to path 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.builtin.vroot

The builtin vroot 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

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.

Try debug key bindings to understand how key bindings actually work.

Key Bindings

Key bindings contains the following information:

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
                "$XPLR" -m 'ChangeDirectory: %q' "$PTH"
              else
                "$XPLR" -m 'FocusPath: %q' "$PTH"
              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, $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-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
page-down		scroll down
page-up		scroll up
q		quit
r		rename
s		sort
space	v	toggle selection
{		scroll up half
}		scroll down half
~		go home
[0-9]		input

filter

key	remaps	action
R		relative path does not match regex
backspace		remove last filter
ctrl-r		reset filters
ctrl-u		clear filters
r		relative path does match regex

vroot

key	remaps	action
.		vroot $PWD
/		vroot /
~		vroot $HOME
v		toggle vroot
ctrl-r		reset vroot
ctrl-u		unset vroot

create_file

key	remaps	action
enter		submit
tab		try complete

selection_ops

key	remaps	action
c		copy here
m		move here
u		clear selection

create

key	remaps	action
d		create directory
f		create file

quit

key	remaps	action
enter		just quit
f		quit printing focus
p		quit printing pwd
r		quit printing result
s		quit printing selection

switch_layout

key	remaps	action
1		default
2		no help menu
3		no selection panel
4		no help or selection

delete

key	remaps	action
D		force delete
d		delete

relative_path_does_not_match_regex

key	remaps	action
enter		submit

number

key	remaps	action
down	j	to down
enter		to index
k	up	to up
[0-9]		input

relative_path_does_match_regex

key	remaps	action
enter		submit

create_directory

key	remaps	action
enter		submit
tab		try complete

duplicate_as

key	remaps	action
enter		submit
tab		try complete

rename

key	remaps	action
enter		submit
tab		try complete

go_to_path

key	remaps	action
enter		submit
tab		try complete

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-r		reset sorters
ctrl-u		clear sorters
e		by canonical extension
enter		submit
l		by last modified
m		by canonical mime essence
n		by node type
r		by relative path
s		by size

search

key	remaps	action
ctrl-n	down	down
ctrl-p	up	up
enter		submit
esc		cancel
left		back
right		enter
tab		toggle selection

debug_error

key	remaps	action
enter		open logs in editor
q		quit

action

key	remaps	action
!		shell
c		create
e		open in editor
l		logs
m		toggle mouse
q		quit options
s		selection operations
v		vroot
[0-9]		go to index

recover

key	remaps	action

go_to

key	remaps	action
f		follow symlink
g		top
i		initial $PWD
p		path
x		open in gui

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.

-- The global key bindings inherited by all the modes.
xplr.config.general.global_key_bindings = {
  on_key = {
    esc = {
      help = "escape",
      messages = {
        { LogInfo = "global on_key(esc) called" },
        "PopMode",
      },
    },
    ["ctrl-c"] = {
      help = "terminate",
      messages = {
        "Terminate",
      },
    },
  },
}

-- Press `#` to enter the `debug key bindings` mode.
xplr.config.modes.builtin.default.key_bindings.on_key["#"] = {
  help = "test",
  messages = {
    "PopMode",
    { SwitchModeCustom = "debug_key_bindings" },
  },
}

-- The `debug key bindings` mode.
xplr.config.modes.custom.debug_key_bindings = {
  name = "debug key bindings",
  key_bindings = {
    on_key = {
      ["1"] = {
        messages = {
          { LogInfo = "on_key(1) called" },
        },
      },
      a = {
        messages = {
          { LogInfo = "on_key(a) called" },
        },
      },
      ["`"] = {
        messages = {
          { LogInfo = "on_key(`) called" },
        },
      },
      tab = {
        messages = {
          { LogInfo = "on_key(tab) called" },
        },
      },
      f1 = {
        messages = {
          { LogInfo = "on_key(f1) 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
style

Also See:

xplr.config.node_types

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:

title
body

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 }

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:

xplr.config.layouts

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.

prompt

Type: nullable string

If set, this prompt will be displayed in the input buffer when in this mode.

Also See:

xplr.config.modes

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

Full List of Messages

xplr messages categorized based on their purpose.

Also See:

Message

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"
"DeleteTillEnd"

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"

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
input

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"

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.

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.

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

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.

uid

Type: integer

User ID of the file owner.

gid

Type: integer

Group ID of the file owner.

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.

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.

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.

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.

Visit the xplr.util API docs for some useful utility / helper functions that you can use in your Lua function calls.

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

Type: string

xplr version. Can be used to test compatibility.

pwd

Type: string

The present working directory.

initial_pwd

Type: string

The initial working directory when xplr started.

vroot

Type: nullable string

The current virtual root.

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

Type: Explorer Config

The configuration for exploring paths.

history

Type: History

last_modes

Type: list of Mode

Last modes, not popped yet.

Node

A node contains the following fields:

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.

uid

Type: integer

User ID of the file owner.

gid

Type: integer

Group ID of the file owner.

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.

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
paths

loc

Type: int

Location of the current path in history.

paths

Type: list of string

Visited paths.

Explorer Config

Explorer config contains the following fields:

filters

List of filters to apply.

Type: list of Node Filter Applicable

sorters

Add list or sorters to the pipeline.

Type: list of Node Sorter Applicable

searcher

Type: nullable Node Searcher

Node Searcher

Node Searcher contains the following fields:

pattern

The patters used to search.

Type: string

recoverable_focus

Where to focus when search is cancelled.

Type: nullable string

Also Ssee:

xplr.util

xplr.util.version

Get the xplr version details.

Type: function() -> { major: number, minor: number, patch: number }

Example:

xplr.util.version()
-- { major = 0, minor = 0, patch = 0 }

xplr.util.dirname

Get the directory name of a given path.

Type: function( path:string ) -> path:string|nil

Example:

xplr.util.dirname("/foo/bar")
-- "/foo"

xplr.util.basename

Get the base name of a given path.

Type: function( path:string ) -> path:string|nil

Example:

xplr.util.basename("/foo/bar")
-- "bar"

xplr.util.absolute

Get the absolute path of the given path by prepending $PWD. It doesn't check if the path exists.

Type: function( path:string ) -> path:string

Example:

xplr.util.absolute("foo/bar")
-- "/tmp/foo/bar"

xplr.util.explore

Explore directories with the given explorer config.

Type: function( path:string, config:Explorer Config|nil ) -> { node:Node... }

Example:


xplr.util.explore("/tmp")
xplr.util.explore("/tmp", app.explorer_config)
-- { { absolute_path = "/tmp/a", ... }, ... }

xplr.util.shell_execute

Execute shell commands safely.

Type: function( program:string, args:{ arg:string... }|nil ) -> { stdout = string, stderr = string, returncode = number|nil }

Example:

xplr.util.shell_execute("pwd")
xplr.util.shell_execute("bash", {"-c", "xplr --help"})
-- { stdout = "xplr...", stderr = "", returncode = 0 }

xplr.util.shell_quote

Quote commands and paths safely.

Type: function( string ) -> string

Example:

xplr.util.shell_quote("a'b\"c")
-- 'a'"'"'b"c'

xplr.util.from_json

Load JSON string into Lua value.

Type: function( string ) -> value

Example:

xplr.util.from_json([[{"foo": "bar"}]])
-- { foo = "bar" }

xplr.util.to_json

Dump Lua value into JSON (i.e. also YAML) string.

Type: function( value ) -> string

Example:

xplr.util.to_json({ foo = "bar" })
-- [[{ "foos": "bar" }]]

xplr.util.to_json({ foo = "bar" }, { pretty = true })
-- [[{
--   "foos": "bar"
-- }]]

xplr.util.from_yaml

Load YAML (i.e. also JSON) string into Lua value.

Type: function( string ) -> value

Example:

xplr.util.from_yaml([[{foo: bar}]])
-- { foo = "bar" }

xplr.util.to_yaml

Dump Lua value into YAML string.

Type: function( value ) -> string

Example:

xplr.util.to_yaml({ foo = "bar" })
-- "foo: bar"

Environment Variables and Pipes

Alternative to CallLua, CallLuaSilently messages that call Lua functions, there are Call0, CallSilently0, BashExec0, BashExecSilently0 messages that call shell commands.

Example: Simple file opener using xdg-open and $XPLR_FOCUS_PATH

xplr.config.modes.builtin.default.key_bindings.on_key["X"] = {
  help = "open",
  messages = {
    {
      BashExecSilently0 = [===[
        xdg-open "${XPLR_FOCUS_PATH:?}"
      ]===],
    },
  },
}

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.

Example: Using Environment Variables and Pipes

xplr.config.modes.builtin.default.key_bindings.on_key["space"] = {
  help = "ask name and greet",
  messages = {
    {
      BashExec0 = [===[
        echo "What's your name?"

        read name
        greeting="Hello $name!"
        message="$greeting You are inside $PWD"

        "$XPLR" -m 'LogSuccess: %q' "$message"
      ]===]
    }
  }
}

-- 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.

Visit the fzf integration tutorial for another 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=xplr
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:

Environment variables

XPLR

The binary path of xplr command.

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_INITIAL_PWD

The $PWD then xplr started.

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.

XPLR_VROOT

Contains the path of current virtual root, is set.

Pipes

Input pipe

Currently there is only one input pipe.

XPLR_PIPE_MSG_IN

Output pipes

XPLR_PIPE_*_OUT are the output pipes that contain data which cannot be exposed directly via environment variables, like multi-line strings. These pipes can be accessed as plain text files located in $XPLR_SESSION_PATH.

Depending on the message (e.g. Call or Call0), each line will be separated by newline or null character (\n or \0).

XPLR_PIPE_MSG_IN

Append new messages to this pipe in YAML (or JSON) syntax. These messages will be read and handled by xplr after the command execution.

Depending on the message (e.g. Call or Call0) you need to separate each message using newline or null character (\n or \0).

NOTE: Since version v0.20.0, it's recommended to avoid writing directly to this file, as safely escaping YAML strings is a lot of work. Use xplr -m / xplr --pipe-msg-in to pass messages to xplr in a safer way.

Example: "$XPLR" -m 'ChangeDirectory: %q' "${HOME:?}"

XPLR_PIPE_SELECTION_OUT

List of selected paths.

XPLR_PIPE_GLOBAL_HELP_MENU_OUT

The full help menu.

XPLR_PIPE_LOGS_OUT

List of logs.

XPLR_PIPE_RESULT_OUT

Result (selected paths if any, else the focused path)

XPLR_PIPE_HISTORY_OUT

List of last visited paths (similar to jump list in vim).

XPLR_PIPE_DIRECTORY_NODES_OUT

List of paths, filtered and sorted as displayed in the files table.

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.

You can try these hacks by writing them to a file, say hack.lua and passsing it to xplr with --extra-config or -C.

xplr -C hack.lua

cd on quit

Change directory using xplr.

Expand for details

Author: @sayanarijit
Tested on: Linux

NOTE: This is a shell hack, rather than Lua config hack. Add this in .bashrc or .profile file in your home directory.

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 = {
    {
      BashExecSilently0 = [===[
        PTH="${XPLR_FOCUS_PATH:?}"
        PTH_ESC=$(printf %q "$PTH")
        if echo "${PTH:?}" >> "${XPLR_SESSION_PATH:?}/bookmarks"; then
          "$XPLR" -m 'LogSuccess: %q' "$PTH_ESC added to bookmarks"
        else
          "$XPLR" -m 'LogError: %q' "Failed to bookmark $PTH_ESC"
        fi
      ]===],
    },
  },
}

xplr.config.modes.builtin.default.key_bindings.on_key["`"] = {
  help = "go to bookmark",
  messages = {
    {
      BashExec0 = [===[
        PTH=$(cat "${XPLR_SESSION_PATH:?}/bookmarks" | fzf --no-sort)
        PTH_ESC=$(printf %q "$PTH")
        if [ "$PTH" ]; then
          "$XPLR" -m 'FocusPath: %q' "$PTH"
        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 = {
          { BashExecSilently0 = [[
              PTH="${XPLR_FOCUS_PATH:?}"
              if [ -d "${PTH}" ]; then
                PTH="${PTH}"
              elif [ -f "${PTH}" ]; then
                PTH="$(dirname "${PTH}")"
              fi
              PTH_ESC=$(printf %q "$PTH")
              if echo "${PTH:?}" >> "${XPLR_BOOKMARK_FILE:?}"; then
                "$XPLR" -m 'LogSuccess: %q' "$PTH_ESC added to bookmarks"
              else
                "$XPLR" -m 'LogError: %q' "Failed to bookmark $PTH_ESC"
              fi
            ]]
          },
        },
      },
      g = {
        help = "go to bookmark",
        messages = {
          {
            BashExec0 = [===[
              PTH=$(cat "${XPLR_BOOKMARK_FILE:?}" | fzf --no-sort)
              if [ "$PTH" ]; then
                "$XPLR" -m 'FocusPath: %q' "$PTH"
              fi
            ]===]
          },
        },
      },
      d = {
        help = "delete bookmark",
        messages = {
          { BashExec0 = [[
              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",
    { BashExec0 = [===[
        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
          "$XPLR" -m 'ChangeDirectory: %q' "$PTH"
        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",
    {
      BashExec0 = [===[
        PTH=$(cat "${XPLR_PIPE_HISTORY_OUT:?}" | sort -z -u | fzf --read0)
        if [ "$PTH" ]; then
          "$XPLR" -m 'ChangeDirectory: %q' "$PTH"
        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
         "$XPLR" -m ExplorePwdAsync
       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 = {
    {
      BashExec0 = [===[
        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, FreeBSD 13.1-RELEASE

xplr.config.modes.builtin.default.key_bindings.on_key.P = {
  help = "preview",
  messages = {
    {
      BashExecSilently0 = [===[
        FIFO_PATH="/tmp/xplr.fifo"

        if [ -e "$FIFO_PATH" ]; then
          "$XPLR" -m StopFifo
          rm -f -- "$FIFO_PATH"
        else
          mkfifo "$FIFO_PATH"
          "$HOME/.local/bin/imv-open.sh" "$FIFO_PATH" "$XPLR_FOCUS_PATH" &
          "$XPLR" -m 'StartFifo: %q' "$FIFO_PATH"
        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"

Text preview pane

Preview text files in a native xplr pane (should be fast enough).

Expand for details

Author: @sayanarijit
Requires: none
Tested on: Linux, FreeBSD 13.1-RELEASE

local function stat(node)
  return node.mime_essence
end

local function read(path, height)
  local p = io.open(path)

  if p == nil then
    return nil
  end

  local i = 0
  local res = ""
  for line in p:lines() do
    if line:match("[^ -~\n\t]") then
      p:close()
      return
    end

    res = res .. line .. "\n"
    if i == height then
      break
    end
    i = i + 1
  end
  p:close()

  return res
end


xplr.config.layouts.builtin.default = {
  Horizontal = {
    config = {
      constraints = {
        { Percentage = 60 },
        { Percentage = 40 },
      },
    },
    splits = {
      "Table",
      {
        CustomContent = {
          title = "preview",
          body = { DynamicParagraph = { render = "custom.preview_pane.render" } },
        },
      },
    },
  },
}

xplr.fn.custom.preview_pane = {}
xplr.fn.custom.preview_pane.render = function(ctx)
  local n = ctx.app.focused_node

  if n and n.canonical then
    n = n.canonical
  end

  if n then
    if n.is_file then
      return read(n.absolute_path, ctx.layout_size.height)
    else
      return stat(n)
    end
  else
    return ""
  end
end

Navigate using the tere file explorer (defaults to type-to-nav system).

Expand for details

Author: @sayanarijit
Requires: tere
Tested on: Linux

xplr.config.modes.builtin.default.key_bindings.on_key.T = {
  help = "tere nav",
  messages = {
    { BashExec0 = [[xplr -m 'ChangeDirectory: %q' "$(tere)"]] },
  },
}

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:

.
├── 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.

Best practices

Try not to execute a lot of commands at startup, it may make xplr slow to start.
When executing commands, prefer Call0 over Call, BashExec0 over BashExec and so on. File names may contain newline characters (e.g. foo$'\n'bar).
File names may also contain quotes. Avoid writing directly to $XPLR_PIPE_MSG_IN. Use xplr -m / xplr --pipe-msg-in instead.
Check for empty variables using the syntax ${FOO:?} or use a default value ${FOO:-defaultvalue}.

Examples

Visit Awesome Plugins for xplr plugin examples.

Also See

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/offline-docs.xplr Fetch the appropriate version of xplr docs and browse offline.
sayanarijit/regex-search.xplr Bring back the regex based seach in xplr.
sayanarijit/registers.xplr Use multiple registers to store the selected paths.
sayanarijit/tri-pane.xplr xplr plugin that implements ranger-like three pane layout.
sayanarijit/type-to-nav.xplr Inspired by nnn's type-to-nav mode for xplr, with some tweaks.
igorepst/term.xplr Terminal integration for xplr
sayanarijit/wl-clipboard.xplr Copy and paste with system clipboard using wl-clipboard
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.
Junker/nuke.xplr Open files in apps by file type or mime
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/scp.xplr Integrate xplr with scp.
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.
dtomvan/extra-icons.xplr Adds more icons to icons.xplr, compatible with zentable.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

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.vim Pick files in Vim using xplr.

Github

gh-xplr Explore GitHub repos using xplr via GitHub CLI.

Shell

powerlevel10k Powerlevel10k prompt for xplr shell.

Security Tools

gpg-tui Import GPG certificates using xplr.

Also See:

Alternatives

These are the alternative TUI/CLI file managers/explorers you might want to check out (in no particular order).

add more

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: Patch (fully compatible).
1.0.0 -> 1.x.x: Only backwards compatible. You can't generally use for e.g. app-1.0.0 with config-1.1.0. But vice versa is fine.
1.0.0 -> x.x.x: Not compatible at all.

Note that until we're v1, we'll be using the {minor} version number as {major}, and the {patch} number as {minor} to determine compatibility.

Instructions

v0.19.4 -> v0.20.1

BREAKING: xplr shell (:!) will default to null (\0) delimited pipes, as opposed to newline (\n) delimited ones (i.e. will use Call0 instead of Call).
Use new messages for safer file path handling (\0 delimited):
- Call0
- CallSilently0
- BashExec0
- BashExecSilently0
Use new sub-commands for safer message passing:
- -m FORMAT [ARGUMENT]... / --pipe-msg-in FORMAT [ARGUMENT]...
- -M FORMAT [ARGUMENT]... / --print-msg-in FORMAT [ARGUMENT]... Where FORMAT is a YAML string that may contain %s, %q and %% placeholders and ARGUMENT is the value per placeholder. See init.lua.
Following hooks can be defined in the config files using an optional return { on_* = { list, of, messages }, ... } statement at the end.
- on_load
- on_focus_change
- on_directory_change
Use --vroot to isolate navigation of an xplr session inside a specific directory. Interaction still requires passing full path, and shell, lua functions etc still can access paths outside vroot.
Use the following messages to switch vroot at runtime, or the use key bindings available in the new builtin mode "vroot" (mapped to : v).
- SetVroot
- UnsetVroot
- ToggleVroot
- ResetVroot
Use $XPLR_INITIAL_PWD and Lua equivalent to implement workspace like features without using virtual root. Use keys gi to go to the initial working directory from anywhere.
Use the convenient xplr.util utility functions in your Lua function calls. See xplr.util API docs.

v0.18.0 -> v0.19.4

BREAKING: The builtin modes cannot be accessed using space separated names anymore. Use underscore separated mode names. For e.g. SwitchModeBuiltin: create file becomes SwitchModeBuiltin: create_file and so on. Kindly go through your config, find and update them, or copy from the latest init.lua.
Now you can use xplr.config.general.global_key_bindings to define a set of key bindings that are available by default in every mode. e.g. esc and ctrl-c, and remove boilerplate code from your config.
You can use the new builtin mode go_to_path which can be used for typing or pasting paths to enter into or to focus on. Type g p to enter this mode.
Now you can use basic tab completion in the go_to_path, create_file, create_directory, rename and duplicate_as modes.
Use the builtin function xplr.fn.builtin.try_complete_path to add easy tab completion support into your own configuration.
Now you can open OSC 7 compatible terminals into the xplr's current working directory by spawning new terminal sessions via the terminal supported key bindings.
Use NO_COLOR environment variable to disable OSC 7 compliance along with colors.
If you have fully copied the default init.lua locally, you might want to go through the latest improvements in init.lua. Specifically the search, filter and sort modes. Also, search for SetInputPrompt and the tab key bindings.
Since version 0.19.1, you can access uid and gid of the file owner in the Lua API.
The input buffer will support more readline-like keys. Also, added "DeleteTillEnd" as another cursor based "InputOperation" option.
Fixed applying regex based filters via the CLI and $XPLR_PIPE_MSG_IN pipe.
You can use the prompt field to define input prompt for each mode, instead of using the SetInputPrompt message.
Since version v0.19.4, the native search will default to skim-v2 based fuzzy matching. esc while in search mode will recover the initial focus. People who prefer the regex based search, can use the regex-search.xplr plugin. The following messages will be available for search based operations:
- SearchFuzzy
- SearchFuzzyFromInput
- AcceptSearch
- CancelSearch
Since version v0.19.4, quick scrolling operations are supported using the following messages and keys:
- ScrollUp -------- page-up
- ScrollDown ------ page-down
- ScrollUpHalf ---- {
- ScrollDownHalf -- }

_{Like this project so far? Please consider contributing.}

v0.17.6 -> v0.18.0

Key binding f r and f R will now filter using regex.
Key binding f backspace will now remove the last filter.
Search mode now defaults to regex search.
Node metadata in the Lua API will contain two new fields:
- created
- last_modified
The last column in the files table now displays the last modification time.
You can now use --read0, --write0 and -0/--null to read and/or print null character delimited paths.
You can now the following regex filters:
- RelativePathDoesMatchRegex
- RelativePathDoesNotMatchRegex
- IRelativePathDoesMatchRegex
- IRelativePathDoesNotMatchRegex
- AbsolutePathDoesMatchRegex
- AbsolutePathDoesNotMatchRegex
- IAbsolutePathDoesMatchRegex
- IAbsolutePathDoesNotMatchRegex
You can use a new SetInputPrompt to set the input prompt dynamically.
You can now use the following timestamp based sorters:
- "ByCreated"
- "ByLastModified"
- "ByCanonicalCreated"
- "ByCanonicalLastModified"
- "BySymlinkCreated"
- "BySymlinkLastModified"

v0.16.4 -> v0.17.6

Deprecated app.directory_buffer, app.history, and app.last_modes in the custom dynamic layout renderer context. As of now, there's no way to access these fields in dynamic layouts. While app.history and app.last_modes can be re-added upon request (with justification), app.directory_buffer has been deprecated for good. However, there's no change in the CallLua* context.
Set xplr.config.general.hide_remaps_in_help_menu to true to hide the remaps in help menu.
None will be serialized to nil in Lua.
LuaEval can now return a function that will be called with the Lua Context argument. Refer to the Full List of Messages doc for example.
From version v0.17.1, set xplr.config.general.disable_debug_error_mode to true 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 binding ctrl-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, and enforce_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 single UpdateInputBufferFromKey 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 and LuaEvalSilently to run Lua code without needing to define a function. However, the app 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 from CallLua argument. Use the globally available xplr.config instead.
xplr.config.general.disable_recover_mode has been deprecated. Use xplr.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 and ToggleFifo 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 config xplr.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 and CallLuaSilently messages will receive CallLuaArg object as the function argument (instead of the App object).
Each node_types config will inherit defaults from matching less specifig node_types config and overwrite them.
Since version v0.13.2, you don't need to use/send Refresh anymore. It will be auto-handled by xplr.

v0.11.1 -> v0.12.1

xplr.config.node_types.mime_essence has split into type and subtype. Hence, instead of xplr.config.node_types.mime_essence["text/plain"] = .. use xplr.config.node_types.mime_essence["text"] = { plain = .. }.
You can also define xplr.config.node_types.mime_essence["text"]["*"] that will match all text types (text/*).

v0.10.2 -> 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 with init.lua. If you have a lot of customization in your config.yml, xplr-yml2lua can help you with migrating it to init.lua.
Handlebars templates has been replaced with Lua functions. You can either remove the customizations or overwrite the functions accordingly.
Added new messages CallLua and CallLuaSilently to call lua functions. The app state will be passed as input to the functions, and the returned messages will be handled by xplr. CallLua and CallLuaSilently are more flexible (and probably faster) alternatives to Call, CallSilently, BashExec and BashExecSilently. e.g.

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 of SwitchMode* when returning back to the previous mode.
After using (the group of) PopMode and SwitchMode* messages, you are now required to Refresh manually to avoid the UI lag.
Pressing any invalid key will now lead you to the recover mode and will protect you from typing further invalid keys. Press esc to escape the recover mode.
Introduced new message LogWarning, similar to other Log* messages.
Creating files and directories has been optimized for batch creation.

v0.7.2 -> v0.8.0

If you have made changes to the config file,

Replace message Explore with ExplorePwd or ExplorePwdAsync or probably ExploreParentsAsync.
Pipe $XPLR_PIPE_FOCUS_OUT has been removed. Use $XPLR_FOCUS_PATH env var instead.
You might want to review your path escaping logics. For e.g. use echo FocusPath: "'"$PWD"'" >> $PIPE instead of echo "FocusPath: $PWD" >> $PIPE.

v0.7.0 -> v0.7.2

Just update the version in your config file.
For version >= v0.7.1, you might want to free up or remap the tab key in search mode to enable easy selection during search.

v0.6.0 -> v0.7.0

If you haven't made any changes in the config file, you should be fine just updating the version number. Else,

You can make the Table: ..., InputAndLogs: ... layout values null and define the common properties in the general.panel_ui instead.

v0.5.13 -> v0.6.0

If you haven't made any changes in the config file, you should be fine just updating the version number. Else,

Rename add_modifier: {bits: 1} to add_modifiers: [Bold], sub_modifier: {bits: 1} to sub_modifiers: [Bold] and so on.
Rename percentage: 10 to Percentage: 10, ratio: 1 to Ratio: 1 and so on.
You might want to free up or remap the ctrl-w key binding in default mode to enable layout switching.

Optionally, checkout this new theme to learn more about what's new.

v0.5.0 -> v0.5.13

Just update the version in your config file.
For versions >= v0.5.8, you can set $OPENER env var to declare a global GUI file opener (to open files using keys gx).
You might also want to update other mappings to handle files with names starting with - (hiphen). For example, instead of rm ${filename} use rm -- ${filename}. Same goes for cp, mv, cat, touch etc.
For version >= v0.5.13, you might want to use the more specific SwitchModeBuiltin and SwitchModeCustom messages instead of the general SwitchMode message.

v0.4.3 -> v0.5.0

If you haven't have any changes in the config file, you should be fine just updating the version number.

Else do the following

Replace {RelativePathIs, case_sensitive: true} with RelativePathIs.
Replace {RelativePathIs, case_sensitive: false} with IRelativePathIs.
Do the same with other filters you are using.
You might want to update your backspace handling to use the RemoveInputBufferLastCharacter message.
You might want to free-up f, s, ctrl-r and ctrl-u key bindings in the default mode, or remap them.
You might want to use the new UI variables.
Update your config version to v0.5.0.

v0.4.2 -> 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 to general.focus_ui (see here).
Rename filetypes to node_types. (see here)
Rename custom field to meta. (see here)
Move icon to meta.icon. (see here)
Rename normal_ui to default_ui. (see here)
Split modes into modes.builtin and modes.custom (see here). Migrate your custom modes to modes.custom. And copy only the changes in the in-built modes in modes.builtin.
Finally, update the version to v0.4.1.

v0.3.8 -> v0.3.13

Your current config should work fine. However, you might want to replace some Call and BashExec messages with CallSilently and BashExecSilently to remove the flickering of the screen.

If you haven't made any changes to the configuration, you can delete and regenerate it.

Else, do the following

Check the new default config by temporarily removing your current config (with backup) and dumping the new config.
Search for Call and BashExec in the new config.
Compare and probably replace the associated actions in your current config

v0.3.0 -> 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 use Debug to export the app state.
$XPLR_RESULT has been ported to file $XPLR_PIPE_RESULT_OUT. Use cat instead of echo, < instead of <<< etc.
$XPLR_GLOBAL_HELP_MENU has been ported to file $XPLR_PIPE_GLOBAL_HELP_MENU_OUT. Use cat instead of echo, < instead of <<< etc.
$XPLR_DIRECTORY_NODES has been ported to file $XPLR_PIPE_DIRECTORY_NODES_OUT. Use cat instead of echo, < instead of <<< etc.
$XPLR_LOGS has been ported to file $XPLR_PIPE_LOGS_OUT. Use cat instead of echo, < instead of <<< etc.
$XPLR_PIPE_RESULT has been ported to file $XPLR_PIPE_RESULT_OUT. Use cat instead of echo, < instead of <<< etc.
Finally, update the version in your config file.

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 or sponsoring me via any of the following ways.

For further queries or concern related to xplr, just ask us.

xplr book