+
+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.
+
+
+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
+
+
+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.
+
+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.
+
+Some of the coolest features xplr provide beside the basic stuff:
+
+- Embedded LuaJIT for portability and extensibility.
+- A simple system based on message passing to control xplr session using:
+
+
+- Readline-like input buffer with customizable behaviour to read user
+inputs.
+- Switchable recover mode that saves you from doing unwanted things when in a
+hurry.
+- Customizable layouts with built-in panels. For e.g.
+
+- Selection list to show you the selected paths in real-time.
+- Help menu to show you the available keys bindings in each mode.
+- Input & logs to read input and display logs.
+- Filter and sort pipeline to show you the applied filters and sorters.
+
+
+- Custom file properties with custom colors can be displayed in the table.
+- FIFO manager to manage a FIFO file that can be used to
+integrate with previewers.
+- Different quit options:
+
+- Quit with success without any output (
q).
+- Quit with success and the result printed on stdout (
enter).
+- Quit with success and the present working directory printed on stdout
+(
: q p).
+- Quit with success and the path under focus printed on stdout
+(
: q f).
+- Quit with success and the selection printed on stdout
+(
: q s).
+- Quit with failure (
ctrl-c).
+
+
+
+Q. What features should be added here? let us know.
+
+Nice to you have here! Let's quickly start with the
+following steps:
+
+
+If you prefer to try it before installing, here's the snippet for your
+convenience.
+docker run -w / -it --rm ubuntu sh -uec '
+ apt-get update -y
+ apt-get install -y wget tar vim
+ wget https://github.com/sayanarijit/xplr/releases/latest/download/xplr-linux.tar.gz
+ tar -xzvf xplr-linux.tar.gz
+ ./xplr
+'
+
+
+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.
+
+xplr can be installed from one of the following community maintained
+repositories:
+
+
+
+nix-env -f https://github.com/NixOS/nixpkgs/tarball/master -iA xplr
+
+
+
+sudo pacman -S xplr
+
+
+Git version:
+paru -S xplr-git
+
+
+
+
+
+sudo port selfupdate
+sudo port install xplr
+
+
+Stable branch:
+brew install xplr
+
+HEAD branch:
+brew install --head xplr
+
+
+
+pkg install xplr
+
+Or
+cd /usr/ports/misc/xplr
+make install clean
+
+
+
+pkgin install xplr
+
+Or
+cd /usr/pkgsrc/sysutils/xplr
+make install
+
+
+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/
+
+
+Prerequisites:
+
+Command-line instructions:
+cargo install --locked --force xplr
+
+
+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/
+
+
+
+
+
+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
+
+
+
+
+Once installed, use the following steps to setup and run xplr.
+
+mkdir -p ~/.config/xplr
+
+version="$(xplr | grep ^version: | cut -d' ' -f 2)"
+
+# When the app loads, press `#`
+
+echo version = '"'${version:?}'"' > ~/.config/xplr/init.lua
+
+Then
+copy from here
+and remove / comment out what you don't want to customize.
+
+Note: You don't generally need to create the config file. You can use the
+default configuration for basic operations. However, creating the config file
+is recommended because the project is in its early stage and the defaults
+might change. Creating the config file will save you from unexpected behavior
+when you upgrade.
+Also, the default configuration is meant to be overwritten to suit your
+workflow.
+
+
+xplr
+
+
+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.
+
+The xplr configuration, exposed via xplr.config Lua API contains the
+following sections.
+See:
+
+
+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.
+
+Renders the first column in the table
+
+Renders the second column in the table
+
+Renders the third column in the table
+
+Renders the fourth column in the table
+
+Renders the fifth column in the table
+
+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.
+
+The general configuration properties are grouped together in
+xplr.config.general.
+
+Set it to true if you want to ignore the startup errors. You can still see
+the errors in the logs.
+Type: boolean
+
+Set it to true if you want to enable mouse scrolling.
+Type: boolean
+
+Set it to true to show hidden files by default.
+Type: boolean
+
+Set it to true to use only a subset of selected operations that forbids
+executing commands or performing write operations on the file-system.
+Type: boolean
+
+Set it to true if you want to enable a safety feature that will save you
+from yourself when you type recklessly.
+Type: boolean
+
+Set it to true if you want to hide all remaps in the help menu.
+Type: boolean
+
+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
+
+This is the shape of the prompt for the input buffer.
+Type: nullable string
+
+This is the style of the prompt for the input buffer.
+Type: Style
+
+The string to indicate an information in logs.
+Type: nullable string
+
+The style for the informations logs.
+Type: Style
+
+The string to indicate an success in logs.
+Type: nullable string
+
+The style for the success logs.
+Type: Style
+
+The string to indicate an warnings in logs.
+Type: nullable string
+
+The style for the warnings logs.
+Type: Style
+
+The string to indicate an error in logs.
+Type: nullable string
+
+The style for the error logs.
+Type: Style
+
+Columns to display in the table header.
+Type: nullable list of tables with the following fields:
+
+- format: nullable string
+- style: Style
+
+
+Style of the table header.
+Type: Style
+
+Height of the table header.
+Type: nullable integer
+
+Columns to display in each row in the table.
+Type: nullable list of tables with the following fields:
+
+- format: nullable string
+- style: Style
+
+
+Default style of the table.
+Type: Style
+
+Height of the table rows.
+Type: nullable integer
+
+Default style of the table.
+Type: Style
+
+Tree to display in the table.
+Type: nullable list of tables with the following fields:
+
+- format: nullable string
+- style: Style
+
+
+Spacing between the columns in the table.
+Type: nullable integer
+
+Constraint for the column widths.
+Type: nullable list of Constraint
+
+The content that is placed before the item name for each row by default.
+Type: nullable string
+
+The content which is appended to each item name for each row by default.
+Type: nullable string
+
+The default style of each item for each row.
+Type: Style
+
+The string placed before the item name for a focused row.
+Type: nullable string
+
+The string placed after the item name for a focused row.
+Type: nullable string
+
+Style for focused item.
+Type: Style
+
+The string placed before the item name for a selected row.
+Type: nullable string
+
+The string placed after the item name for a selected row.
+Type: nullable string
+
+Style for selected rows.
+Type: Style
+
+The string placed before item name for a selected row that gets the focus.
+Type: nullable string
+
+The string placed after the item name for a selected row that gets the focus.
+Type: nullable string
+
+Style for a selected row that gets the focus.
+Type: Style
+
+The shape of the separator for the Sort & filter panel.
+Type: nullable string
+
+The style of the separator for the Sort & filter panel.
+Type: Style
+
+The content of the default identifier in Sort & filter panel.
+Type: nullable string
+
+Style for the default identifier in Sort & filter panel.
+Type: Style
+
+The shape of the forward direction indicator for sort identifiers in Sort & filter panel.
+Type: nullable string
+
+Style of forward direction indicator in Sort & filter panel.
+Type: Style
+
+The shape of the reverse direction indicator for sort identifiers in Sort & filter panel.
+Type: nullable string
+
+Style of reverse direction indicator in Sort & filter panel.
+Type: Style
+
+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
+
+
+
+
+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
+
+
+
+
+The content for panel title by default.
+Type: nullable string
+
+The style for panel title by default.
+Type: Style
+
+Style of the panels by default.
+Type: Style
+
+Defines where to show borders for the panels by default.
+Type: nullable list of Border
+
+Type of the borders by default.
+Type: nullable Border Type
+
+Style of the panel borders by default.
+Type: Style
+
+The content for the table panel title.
+Type: nullable string
+
+Style of the table panel title.
+Type: Style
+
+Style of the table panel.
+Type: Style
+
+Defines where to show borders for the table panel.
+Type: nullable list of Border
+
+Type of the borders for table panel.
+Type: nullable Border Type
+
+Style of the table panel borders.
+Type: Style
+
+The content for the help menu panel title.
+Type: nullable string
+
+Style of the help menu panel title.
+Type: Style
+
+Style of the help menu panel.
+Type: Style
+
+Defines where to show borders for the help menu panel.
+Type: nullable list of Border
+
+Type of the borders for help menu panel.
+Type: nullable Border Type
+
+Style of the help menu panel borders.
+Type: Style
+
+The content for the input & logs panel title.
+Type: nullable string
+
+Style of the input & logs panel title.
+Type: Style
+
+
+Style of the input & logs panel.
+Type: Style
+Defines where to show borders for the input & logs panel.
+Type: nullable list of Border
+
+Type of the borders for input & logs panel.
+Type: nullable Border Type
+
+Style of the input & logs panel borders.
+Type: Style
+
+The content for the selection panel title.
+Type: nullable string
+
+Style of the selection panel title.
+Type: Style
+
+
+Style of the selection panel.
+Type: Style
+Defines where to show borders for the selection panel.
+Type: nullable list of Border
+
+Type of the borders for selection panel.
+Type: nullable Border Type
+
+Style of the selection panel borders.
+Type: Style
+
+The content for the sort & filter panel title.
+Type: nullable string
+
+Style of the sort & filter panel title.
+Type: Style
+
+Style of the sort & filter panel.
+Type: Style
+
+Defines where to show borders for the sort & filter panel.
+Type: nullable list of Border
+
+Type of the borders for sort & filter panel.
+Type: nullable Border Type
+
+Style of the sort & filter panel borders.
+Type: Style
+
+Initial group if sorters applied to the nodes list in the table.
+Type: nullable list of Node Sorter
+
+The name of one of the modes to use when xplr loads.
+Type: nullable string
+
+The name of one of the layouts to use when xplr loads.
+Type: nullable string
+
+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
+
+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.
+
+The style for the directory nodes
+Type: Style
+
+Metadata for the directory nodes
+Type: nullable string
+
+The style for the file nodes
+Type: Style
+
+Metadata for the file nodes
+Type: nullable string
+
+The style for the symlink nodes
+Type: Style
+
+Metadata for the symlink nodes
+Type: nullable string
+Metadata and style based on mime types.
+It is possible to use the wildcard * to match all mime sub types. It will
+be overwritten by the more specific sub types that are defined.
+Type: mapping of the following key-value pairs:
+
+- key: string
+- value:
+
+
+
+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 = ""} },
+ },
+}
+
+
+Metadata and style based on extension.
+Type: mapping of the following key-value pairs:
+
+Example:
+xplr.config.node_types.extension.md = { meta = { icon = "" }, style = { fg = "Blue" } }
+xplr.config.node_types.extension.rs = { meta = { icon = "🦀" } }
+
+
+Metadata and style based on special file names.
+Type: mapping of the following key-value pairs:
+
+Example:
+xplr.config.node_types.special["Cargo.toml"] = { meta = { icon = "" } }
+xplr.config.node_types.special["Downloads"] = { meta = { icon = "" }, style = { fg = "Blue" } }
+
+
+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.
+
+
+xplr.config.layouts.builtin.default = {
+ Horizontal = {
+ config = {
+ margin = 1,
+ horizontal_margin = 2,
+ vertical_margin = 3,
+ constraints = {
+ { Percentage = 50 },
+ { Percentage = 50 },
+ }
+ },
+ splits = {
+ "Table",
+ "HelpMenu",
+ }
+ }
+}
+
+
+The default layout
+Type: Layout
+
+The layout without help menu
+Type: Layout
+
+The layout without selection panel
+Type: Layout
+
+The layout without help menu and selection panel
+Type: Layout
+
+This is where you can define custom layouts
+Type: mapping of the following key-value pairs:
+
+Example:
+xplr.config.layouts.custom.example = "Nothing" -- Show a blank screen
+xplr.config.general.initial_layout = "example" -- Load the example layout
+
+
+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.
+
+The builtin default mode.
+Visit the Default Key Bindings
+to see what each mode does.
+Type: Mode
+
+The builtin debug error mode.
+Type: Mode
+
+The builtin recover mode.
+Type: Mode
+
+The builtin selection ops mode.
+Type: Mode
+
+The builtin create mode.
+Type: Mode
+
+The builtin create directory mode.
+Type: Mode
+
+The builtin create file mode.
+Type: Mode
+
+The builtin number mode.
+Type: Mode
+
+The builtin go to mode.
+Type: Mode
+
+The builtin rename mode.
+Type: Mode
+
+The builtin duplicate as mode.
+Type: Mode
+
+The builtin delete mode.
+Type: Mode
+
+The builtin action mode.
+Type: Mode
+
+The builtin quit mode.
+Type: Mode
+
+The builtin search mode.
+Type: Mode
+
+The builtin filter mode.
+Type: Mode
+
+The builtin relative_path_does_contain mode.
+Type: Mode
+
+The builtin relative_path_does_not_contain mode.
+Type: Mode
+
+The builtin sort mode.
+Type: Mode
+
+The builtin switch layout mode.
+Type: Mode
+
+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"
+
+
+These are the concepts that make xplr probably the most hackable terminal file
+explorer.
+
+
+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.
+
+In xplr, each keyboard input passes through a bunch of handlers (e.g. on_key,
+on_number, default etc.) in a given order. If any of the handlers is
+configured to with an action, it will intercept the key and produce
+messages for xplr to handle.
+
+Key bindings contains the following information:
+
+
+Type: mapping of Key to nullable Action
+Defines what to do when an exact key is pressed.
+
+Type: nullable Action
+An action to perform if the keyboard input is an alphabet and is not mapped via
+the on_key field.
+
+Type: nullable Action
+An action to perform if the keyboard input is a number and is not mapped via
+the on_key field.
+
+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.
+
+Type: nullable Action
+An action to perform if the keyboard input is a special character and is not
+mapped via the on_key field.
+
+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.
+
+Type: nullable Action
+An action to perform if the keyboard input is a navigation key and is not
+mapped via the on_key field.
+
+Type: nullable Action
+An action to perform if the keyboard input is a function key and is not mapped
+via the on_key field.
+
+Type: nullable Action
+Default action to perform in case if a keyboard input not mapped via any of the
+on_* fields mentioned above.
+
+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.
+
+An action contains the following information:
+
+
+Type: nullable string
+Description of what it does. If unspecified, it will be excluded from the help
+menu.
+
+Type: A list of Message to send.
+The list of messages to send when a key is pressed.
+
+Assuming xplr is installed and setup, let's
+add our own mode to integrate xplr with fzf.
+We'll call it fzxplr mode.
+First, let's add a custom mode called fzxplr, and map the key F to an
+action that will call fzf to search and focus on a file or enter into a
+directory.
+xplr.config.modes.custom.fzxplr = {
+ name = "fzxplr",
+ key_bindings = {
+ on_key = {
+ F = {
+ help = "search",
+ messages = {
+ {
+ BashExec = [===[
+ PTH=$(cat "${XPLR_PIPE_DIRECTORY_NODES_OUT:?}" | awk -F/ '{print $NF}' | fzf)
+ if [ -d "$PTH" ]; then
+ echo ChangeDirectory: "'"${PWD:?}/${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}"
+ else
+ echo FocusPath: "'"${PWD:?}/${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}"
+ fi
+ ]===]
+ },
+ "PopMode",
+ },
+ },
+ },
+ default = {
+ messages = {
+ "PopMode",
+ },
+ },
+ },
+}
+
+As you can see, the key F in mode fzxplr (the name can be anything)
+executes a script in bash.
+BashExec, PopMode, SwitchModeBuiltin, ChangeDirectory and FocusPath
+are messages, $XPLR_PIPE_MSG_IN,
+$XPLR_PIPE_DIRECTORY_NODES_OUT are
+environment variables exported by xplr
+before executing the command. They contain the path to the
+input and output pipes that
+allows external tools to interact with xplr.
+Now that we have our new mode ready, let's add an entry point to this mode via
+the default mode.
+xplr.config.modes.builtin.default.key_bindings.on_key["F"] = {
+ help = "fzf mode",
+ messages = {
+ { SwitchModeCustom = "fzxplr" },
+ },
+}
+
+Now let's try out the new xplr-fzf integration.
+
+
+Visit Awesome Plugins for more integration options.
+
+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.
+
+| key | remaps | action |
|---|
+| . | | show hidden |
+| / | ctrl-f | search |
+| : | | action |
+| ? | | global help menu |
+| G | | go to bottom |
+| V | ctrl-a | select/unselect all |
+| ctrl-c | | terminate |
+| ctrl-d | | duplicate as |
+| ctrl-i | tab | next visited path |
+| ctrl-o | | last visited path |
+| ctrl-r | | refresh screen |
+| ctrl-u | | clear selection |
+| ctrl-w | | switch layout |
+| d | | delete |
+| down | j | down |
+| enter | | quit with result |
+| f | | filter |
+| g | | go to |
+| h | left | back |
+| k | up | up |
+| l | right | enter |
+| q | | quit |
+| r | | rename |
+| s | | sort |
+| space | v | toggle selection |
+| ~ | | go home |
+| [0-9] | | input |
+
+
+| key | remaps | action |
|---|
+| ctrl-c | | terminate |
+| enter | | open logs in editor |
+| esc | | escape |
+| q | | quit |
+
+
+| key | remaps | action |
|---|
+| ctrl-c | | terminate |
+| esc | | escape |
+
+
+| key | remaps | action |
|---|
+| R | | relative does not contain |
+| ctrl-c | | terminate |
+| ctrl-r | | reset filters |
+| ctrl-u | | clear filters |
+| enter | esc | done |
+| r | | relative does contain |
+
+
+| key | remaps | action |
|---|
+| ctrl-c | | terminate |
+| down | j | to down |
+| enter | | to index |
+| esc | | cancel |
+| k | up | to up |
+| [0-9] | | input |
+
+
+| key | remaps | action |
|---|
+| ctrl-c | | terminate |
+| esc | | cancel |
+| f | | follow symlink |
+| g | | top |
+| x | | open in gui |
+
+
+| key | remaps | action |
|---|
+| ctrl-c | | terminate |
+| ctrl-n | down | down |
+| ctrl-p | up | up |
+| enter | esc | focus |
+| left | | back |
+| right | | enter |
+| tab | | toggle selection |
+
+
+| key | remaps | action |
|---|
+| c | | copy here |
+| ctrl-c | | terminate |
+| esc | | cancel |
+| m | | move here |
+| x | | open in gui |
+
+
+| key | remaps | action |
|---|
+| ! | | shell |
+| c | | create |
+| ctrl-c | | terminate |
+| e | | open in editor |
+| esc | | cancel |
+| l | | logs |
+| m | | toggle mouse |
+| q | | quit options |
+| s | | selection operations |
+| [0-9] | | go to index |
+
+
+| key | remaps | action |
|---|
+| ctrl-c | | terminate |
+| d | | create directory |
+| esc | | cancel |
+| f | | create file |
+
+
+| key | remaps | action |
|---|
+| ctrl-c | | terminate |
+| enter | | create file |
+| esc | | cancel |
+
+
+| key | remaps | action |
|---|
+| ctrl-c | | terminate |
+| enter | | create directory |
+| esc | | cancel |
+
+
+| key | remaps | action |
|---|
+| ctrl-c | | terminate |
+| enter | | rename |
+| esc | | cancel |
+
+
+| key | remaps | action |
|---|
+| ctrl-c | | terminate |
+| enter | | duplicate |
+| esc | | cancel |
+
+
+| key | remaps | action |
|---|
+| D | | force delete |
+| ctrl-c | | terminate |
+| d | | delete |
+| esc | | cancel |
+
+
+| key | remaps | action |
|---|
+| ! | | reverse sorters |
+| E | | by canonical extension reverse |
+| M | | by canonical mime essence reverse |
+| N | | by node type reverse |
+| R | | by relative path reverse |
+| S | | by size reverse |
+| backspace | | remove last sorter |
+| ctrl-c | | terminate |
+| ctrl-r | | reset sorters |
+| ctrl-u | | clear sorters |
+| e | | by canonical extension |
+| enter | esc | done |
+| m | | by canonical mime essence |
+| n | | by node type |
+| r | | by relative path |
+| s | | by size |
+
+
+| key | remaps | action |
|---|
+| R | | relative does not contain |
+| ctrl-c | | terminate |
+| ctrl-r | | reset filters |
+| ctrl-u | | clear filters |
+| enter | esc | done |
+| r | | relative does contain |
+
+
+| key | remaps | action |
|---|
+| ctrl-c | | terminate |
+| enter | | apply filter |
+| esc | | cancel |
+
+
+| key | remaps | action |
|---|
+| ctrl-c | | terminate |
+| enter | | apply filter |
+| esc | | cancel |
+
+
+| key | remaps | action |
|---|
+| 1 | | default |
+| 2 | | no help menu |
+| 3 | | no selection panel |
+| 4 | | no help or selection |
+| ctrl-c | | terminate |
+| esc | | cancel |
+
+
+If you need help debugging or understanding key bindings DYI way, you can
+create a test.lua file with the following script, launch xplr with
+xplr --extra-config test.lua, press # and play around.
+xplr.config.modes.builtin.default.key_bindings.on_key["#"] = {
+ help = "test",
+ messages = {
+ "PopMode",
+ { SwitchModeCustom = "test" },
+ },
+}
+
+xplr.config.modes.custom.test = {
+ name = "test",
+ key_bindings = {
+ on_key = {
+ ["1"] = {
+ messages = {
+ { LogInfo = "on_key called" },
+ },
+ },
+ a = {
+ messages = {
+ { LogInfo = "on_key called" },
+ },
+ },
+ ["`"] = {
+ messages = {
+ { LogInfo = "on_key called" },
+ },
+ },
+ tab = {
+ messages = {
+ { LogInfo = "on_key called" },
+ },
+ },
+ esc = {
+ messages = {
+ "PopMode",
+ },
+ },
+ ["ctrl-c"] = {
+ messages = {
+ "Terminate",
+ },
+ },
+ f1 = {
+ messages = {
+ { LogInfo = "on_key called" },
+ },
+ },
+ },
+ on_alphabet = {
+ messages = {
+ { LogInfo = "on_alphabet called" },
+ },
+ },
+ on_number = {
+ messages = {
+ { LogInfo = "on_number called" },
+ },
+ },
+ -- on_alphanumeric = {
+ -- messages = {
+ -- { LogInfo = "on_alphanumeric called" },
+ -- },
+ -- },
+ on_special_character = {
+ messages = {
+ { LogInfo = "on_special_character called" },
+ },
+ },
+ -- on_character = {
+ -- messages = {
+ -- { LogInfo = "on_character called" },
+ -- },
+ -- },
+ on_navigation = {
+ messages = {
+ { LogInfo = "on_navigation called" },
+ },
+ },
+ on_function = {
+ messages = {
+ { LogInfo = "on_function called" },
+ },
+ },
+ default = {
+ messages = {
+ { LogInfo = "default called" },
+ },
+ },
+ },
+}
+
+
+A node-type contains the following fields:
+
+
+Type: mapping of string and string
+A meta field can contain custom metadata about a node. By default, the "icon"
+metadata is set for the directory, file, and
+symlink nodes.
+Example:
+xplr.config.node_types.file = {
+ meta = {
+ icon = "f",
+ foo = "bar",
+ }
+}
+
+
+
+
+
+
+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:
+
+
+This layout contains a blank panel.
+
+This layout contains the table displaying the files and directories in the
+current directory.
+
+This layout contains the panel displaying the input prompt and logs.
+
+This layout contains the panel displaying the selected paths.
+
+This layout contains the panel displaying the help menu for the current mode in
+real-time.
+
+This layout contains the panel displaying the pipeline of sorters and filters
+applied of the list of paths being displayed.
+
+This is a special layout that splits the panel into two horizontal parts.
+It contains the following information:
+
+
+This is a special layout that splits the panel into two vertical parts.
+It contains the following information:
+
+
+A layout config contains the following information:
+
+
+Type: nullable integer
+The width of the margin in all direction.
+
+Type: nullable integer
+The width of the horizontal margins. Overwrites the margin value.
+
+Type: nullable integer
+The width of the vertical margins. Overwrites the margin value.
+
+Type: nullable list of Constraint
+The constraints applied on the layout.
+
+A constraint can be one of the following:
+
+- { Percentage = int }
+- { Ratio = { int, int } }
+- { Length = { int }
+- { LengthLessThanScreenHeight = int }
+- { LengthLessThanScreenWidth = int }
+- { LengthLessThanLayoutHeight = int }
+- { LengthLessThanLayoutWidth = int }
+- { Max = int }
+- { MaxLessThanScreenHeight = int }
+- { MaxLessThanScreenWidth = int }
+- { MaxLessThanLayoutHeight = int }
+- { MaxLessThanLayoutWidth = int }
+- { Min = int }
+- { MinLessThanScreenHeight = int }
+- { MinLessThanScreenWidth = int }
+- { MinLessThanLayoutHeight = int }
+- { MinLessThanLayoutWidth = int }
+
+TODO: document each constraint.
+
+Type: list of Layout
+The list of child layouts to fit into the parent layout.
+
+Custom content is a special layout to render something custom.
+It contains the following information:
+
+
+Type: nullable string
+The title of the panel.
+
+Type: Content Body
+The body of the panel.
+
+Content body can be one of the following:
+
+
+A paragraph to render. It contains the following fields:
+
+- render (string): The string to render.
+
+
+xplr.config.layouts.builtin.default = {
+ CustomContent = {
+ title = "custom title",
+ body = {
+ StaticParagraph = { render = "custom body" },
+ },
+ },
+}
+
+
+A Lua function to render a custom paragraph.
+It contains the following fields:
+
+- render (string): The lua function that returns the paragraph to
+render.
+
+
+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
+
+
+A list to render. It contains the following fields:
+
+- render (list of string): The list to render.
+
+
+xplr.config.layouts.builtin.default = {
+ CustomContent = {
+ title = "custom title",
+ body = {
+ StaticList = { render = { "1", "2", "3" } },
+ },
+ },
+}
+
+
+A Lua function to render a custom list.
+It contains the following fields:
+
+- render (string): The lua function that returns the list to render.
+
+
+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
+
+
+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.
+
+
+xplr.config.layouts.builtin.default = {
+ CustomContent = {
+ title = "custom title",
+ body = {
+ StaticTable = {
+ widths = {
+ { Percentage = 50 },
+ { Percentage = 50 },
+ },
+ col_spacing = 1,
+ render = {
+ { "a", "b" },
+ { "c", "d" },
+ },
+ },
+ },
+ },
+}
+
+
+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.
+
+
+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
+
+
+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.
+
+It contains the following information:
+
+
+It contains the following information:
+
+Every field is of integer type.
+
+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.
+
+
+
+
+A mode contains the following information:
+
+
+Type: string
+This is the name of the mode visible in the help menu.
+
+Type: nullable string
+If specified, the help menu will display this instead of the auto generated
+mappings.
+
+Type: nullable string
+If specified, the help menu will display this along-side the auto generated
+help menu.
+
+Type: Key Bindings
+The key bindings available in that mode.
+
+Type: nullable Layout
+If specified, this layout will be used to render the UI.
+
+
+
+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:
+
+
+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"] }
+
+
+
+
+xplr messages categorized based on their purpose.
+
+
+
+
+Explore the present working directory and register the filtered nodes.
+This operation is expensive. So, try to avoid using it too often.
+Example:
+
+- Lua: "ExplorePwd"
+- YAML:
ExplorePwd
+
+
+Explore the present working directory and register the filtered nodes
+asynchronously. This operation happens asynchronously. That means, the
+xplr directory buffers won't be updated immediately. Hence, it needs to
+be used with care and probably with special checks in place. To explore
+$PWD synchronously, use ExplorePwd instead.
+Example:
+
+- Lua: "ExplorePwdAsync"
+- YAML:
ExplorePwdAsync
+
+
+Explore the present working directory along with its parents and
+register the filtered nodes. This operation happens asynchronously.
+That means, the xplr directory buffers won't be updated immediately.
+Hence, it needs to be used with care and probably with special checks
+in place. To explore just the $PWD synchronously, use ExplorePwd
+instead.
+Example:
+
+- Lua: "ExploreParentsAsync"
+- YAML:
ExploreParentsAsync
+
+
+
+Clear the screen.
+Example:
+
+- Lua: "ClearScreen"
+- YAML:
ClearScreen
+
+
+Refresh the screen.
+But it will not re-explore the directory if the working directory is
+the same. If there is some change in the working directory and you want
+to re-explore it, use the Explore message instead.
+Also, it will not clear the screen. Use ClearScreen for that.
+Example:
+
+- Lua: "Refresh"
+- YAML:
Refresh
+
+
+
+Focus next node.
+Example:
+
+- Lua: "FocusNext"
+- YAML:
FocusNext
+
+
+Focus on the nth node relative to the current focus where n is a
+given value.
+Type: { FocusNextByRelativeIndex = int }
+Example:
+
+- Lua: { FocusNextByRelativeIndex = 2 }
+- YAML:
FocusNextByRelativeIndex: 2
+
+
+Focus on the nth node relative to the current focus where n is read
+from the input buffer.
+Example:
+
+- Lua: "FocusNextByRelativeIndexFromInput"
+- YAML:
FocusNextByRelativeIndexFromInput
+
+
+Focus on the previous item.
+Example:
+
+- Lua: "FocusPrevious"
+- YAML:
FocusPrevious
+
+
+Focus on the -nth node relative to the current focus where n is a
+given value.
+Type: { FocusPreviousByRelativeIndex = int }
+Example:
+
+- Lua:
{ FocusPreviousByRelativeIndex = 2 }
+- YAML:
FocusPreviousByRelativeIndex: 2
+
+
+Focus on the -nth node relative to the current focus where n is
+read from the input buffer.
+Example:
+
+- Lua: "FocusPreviousByRelativeIndexFromInput"
+- YAML:
FocusPreviousByRelativeIndexFromInput
+
+
+Focus on the first node.
+Example:
+
+- Lua: "FocusFirst"
+- YAML:
FocusFirst
+
+
+Focus on the last node.
+Example:
+
+- Lua: "FocusLast"
+- YAML:
FocusLast
+
+
+Focus on the given path.
+Type: { FocusPath = "string" }
+Example:
+
+- Lua:
{ FocusPath = "/path/to/file" }
+- YAML:
FocusPath: /path/to/file
+
+
+Focus on the path read from input buffer.
+Example:
+
+- Lua: "FocusPathFromInput"
+- YAML:
FocusPathFromInput
+
+
+Focus on the absolute nth node where n is a given value.
+Type: { FocusByIndex = int }
+Example:
+
+- Lua: { FocusByIndex = 2 }
+- YAML:
FocusByIndex: 2
+
+
+Focus on the absolute nth node where n is read from the input buffer.
+Example:
+
+- Lua: "FocusByIndexFromInput"
+- YAML:
FocusByIndexFromInput
+
+
+YAML: FocusByFileName: string
+Focus on the file by name from the present working directory.
+Type: { FocusByFileName = "string" }
+Example:
+
+- Lua: { FocusByFileName = "filename.ext" }
+- YAML:
FocusByFileName: filename.ext
+
+
+Change the present working directory ($PWD)
+Type: { ChangeDirectory = "string" }
+Example:
+
+- Lua: { ChangeDirectory = "/path/to/directory" }
+- YAML:
ChangeDirectory: /path/to/directory
+
+
+Enter into the currently focused path if it's a directory.
+Example:
+
+- Lua: "Enter"
+- YAML:
Enter
+
+
+Go back to the parent directory.
+Example:
+
+- Lua:"Back"
+- YAML:
Back
+
+
+Go to the last path visited.
+Example:
+
+- Lua: "LastVisitedPath"
+- YAML:
LastVisitedPath
+
+
+Go to the next path visited.
+Example:
+
+- Lua: "NextVisitedPath"
+- YAML:
NextVisitedPath
+
+
+Follow the symlink under focus to its actual location.
+Example:
+Lua: "FollowSymlink"
+YAML: FollowSymlink
+
+
+Update the input buffer using cursor based operations.
+Type: { UpdateInputBuffer = Input Opertaion }
+Example:
+
+- Lua: { UpdateInputBuffer = "GoToPreviousWord" }
+- YAML:
UpdateInputBuffer: GoToPreviousWord
+
+
+Update the input buffer from the key read from keyboard input.
+Example:
+
+- Lua: "UpdateInputBufferFromKey"
+- YAML:
UpdateInputBufferFromKey
+
+
+Append/buffer the given string into the input buffer.
+Type: { BufferInput = "string" }
+Example:
+
+- Lua: { BufferInput = "foo" }
+- YAML:
BufferInput: foo
+
+
+Append/buffer the characted read from a keyboard input into the
+input buffer.
+Example:
+
+- Lua: "BufferInputFromKey"
+- YAML:
BufferInputFromKey
+
+
+Set/rewrite the input buffer with the given string.
+When the input buffer is not-null (even if empty string)
+it will show in the UI.
+Type: { SetInputBuffer = "string" }
+Example:
+
+- Lua: { SetInputBuffer = "foo" }
+- YAML:
SetInputBuffer: foo
+
+
+Remove input buffer's last character.
+Example:
+
+- Lua: "RemoveInputBufferLastCharacter"
+- YAML:
RemoveInputBufferLastCharacter
+
+
+Remove input buffer's last word.
+Example:
+
+- Lua: "RemoveInputBufferLastWord"
+- YAML:
RemoveInputBufferLastWord
+
+
+Reset the input buffer back to null. It will not show in the UI.
+Example:
+
+- Lua: "ResetInputBuffer"
+- YAML:
ResetInputBuffer
+
+
+
+Switch input mode.
+Type : { SwitchMode = "string" }
+Example:
+
+- Lua: { SwitchMode = "default" }
+- YAML: SwitchMode: default
+
+
+NOTE: To be specific about which mode to switch to, use
+SwitchModeBuiltinKeepingInputBuffer or
+SwitchModeCustomKeepingInputBuffer instead.
+
+
+Switch input mode.
+It keeps the input buffer.
+Type: { SwitchModeKeepingInputBuffer = "string" }
+Example:
+
+- Lua: { SwitchModeKeepingInputBuffer = "default" }
+- YAML:
SwitchModeKeepingInputBuffer: default
+
+
+NOTE: To be specific about which mode to switch to, use
+SwitchModeBuiltinKeepingInputBuffer or
+SwitchModeCustomKeepingInputBuffer instead.
+
+
+Switch to a builtin mode.
+It clears the input buffer.
+Type: { SwitchModeBuiltin = "string" }
+Example:
+
+- Lua: { SwitchModeBuiltin = "default" }
+- YAML:
SwitchModeBuiltin: default
+
+
+Switch to a builtin mode.
+It keeps the input buffer.
+Type: { SwitchModeBuiltinKeepingInputBuffer = "string" }
+Example:
+
+- Lua: { SwitchModeBuiltinKeepingInputBuffer = "default" }
+- YAML:
SwitchModeBuiltinKeepingInputBuffer: default
+
+
+Switch to a custom mode.
+It clears the input buffer.
+Type: { SwitchModeCustom = "string" }
+Example:
+
+- Lua: { SwitchModeCustom = "my_custom_mode" }
+- YAML:
SwitchModeCustom: my_custom_mode
+
+
+Switch to a custom mode.
+It keeps the input buffer.
+Type: { SwitchModeCustomKeepingInputBuffer = "string" }
+Example:
+
+- Lua: { SwitchModeCustomKeepingInputBuffer = "my_custom_mode" }
+- YAML:
SwitchModeCustomKeepingInputBuffer: my_custom_mode
+
+
+Pop the last mode from the history and switch to it.
+It clears the input buffer.
+Example:
+
+- Lua: "PopMode"
+- YAML:
PopMode
+
+
+Pop the last mode from the history and switch to it.
+It keeps the input buffer.
+Example:
+
+- Lua: PopModeKeepingInputBuffer
+- YAML:
PopModeKeepingInputBuffer
+
+
+
+Switch layout.
+Type: { SwitchLayout = "string" }
+Example:
+
+- Lua: { SwitchLayout = "default" }
+- YAML:
SwitchLayout: default
+
+
+NOTE: To be specific about which layout to switch to, use SwitchLayoutBuiltin or
+SwitchLayoutCustom instead.
+
+
+Switch to a builtin layout.
+Type: { SwitchLayoutBuiltin = "string" }
+Example:
+
+- Lua: { SwitchLayoutBuiltin = "default" }
+- YAML:
SwitchLayoutBuiltin: default
+
+
+Switch to a custom layout.
+Type: { SwitchLayoutCustom = "string" }
+Example:
+
+- Lua: { SwitchLayoutCustom = "my_custom_layout" }
+- YAML:
SwitchLayoutCustom: my_custom_layout
+
+
+
+Call a shell command with the given arguments.
+Note that the arguments will be shell-escaped.
+So to read the variables, the -c option of the shell
+can be used.
+You may need to pass ExplorePwd depening on the expectation.
+Type: { Call = "string" }
+Example:
+
+- Lua: { Call = { command = "bash", args = { "-c", "read -p test" } } }
+- YAML:
Call: { command: bash, args: ["-c", "read -p test"] }
+
+
+Like Call but without the flicker. The stdin, stdout
+stderr will be piped to null. So it's non-interactive.
+Type: { CallSilently = "string" }
+Example:
+
+- Lua:
{ CallSilently = { command = "tput", args = { "bell" } } }
+- YAML:
CallSilently: { command: tput, args: ["bell"] }
+
+
+An alias to Call: {command: bash, args: ["-c", "{string}"], silent: false}
+where {string} is the given value.
+Type: { BashExec = "string" }
+Example:
+
+- Lua: { BashExec = "read -p test" }
+- YAML:
BashExec: "read -p test"
+
+
+Like BashExec but without the flicker. The stdin, stdout
+stderr will be piped to null. So it's non-interactive.
+Type: { BashExecSilently = "string" }
+Example:
+
+- Lua: { BashExecSilently = "tput bell" }
+- YAML:
BashExecSilently: "tput bell"
+
+
+
+Call a Lua function.
+A Lua Context
+object will be passed to the function as argument.
+The function can optionally return a list of messages for xplr to
+handle after the executing the function.
+Type: { CallLua = "string" }
+Example:
+
+- Lua: { CallLua = "custom.some_custom_funtion" }
+- YAML:
CallLua: custom.some_custom_funtion
+
+
+Like CallLua but without the flicker. The stdin, stdout
+stderr will be piped to null. So it's non-interactive.
+Type: { CallLuaSilently = "string" }
+Example:
+
+- Lua: { CallLuaSilently = "custom.some_custom_function" }
+- YAML:
CallLuaSilently: custom.some_custom_function
+
+
+Execute Lua code without needing to define a function.
+If the string is a callable, xplr will try to call it with with the
+Lua Context
+argument.
+Type: { LuaEval = "string" }
+Example:
+
+- Lua: { LuaEval = [[return { { LogInfo = io.read() } }]] }
+- Lua: { LuaEval = [[function(app) return { { LogInfo = app.pwd } } end]] }
+- YAML:
LuaEval: "return { { LogInfo = io.read() } }"
+- YAML:
LuaEval: "function(app) return { { LogInfo = app.pwd } } end"
+
+
+Like LuaEval but without the flicker. The stdin, stdout
+stderr will be piped to null. So it's non-interactive.
+Type: { LuaEvalSilently = "string" }
+Example:
+
+- Lua: { LuaEvalSilently = [[return { { LogInfo = "foo" } }]] }
+- YAML:
LuaEvalSilently: "return { { LogInfo = 'foo' } }"
+
+
+
+Select the focused node.
+Example:
+
+- Lua: "Select"
+- YAML:
Select
+
+
+Select all the visible nodes.
+Example:
+
+- Lua: "SelectAll"
+- YAML:
SelectAll
+
+
+Select the given path.
+Type: { SelectPath = "string" }
+Example:
+
+- Lua: { SelectPath = "/path/to/file" }
+- YAML:
SelectPath: /path/to/file
+
+
+Unselect the focused node.
+Example:
+
+- Lua: "UnSelect"
+- YAML:
UnSelect
+
+
+Unselect all the visible nodes.
+Example:
+
+- Lua: "UnSelectAll"
+- YAML:
UnSelectAll
+
+
+UnSelect the given path.
+Type: { UnSelectPath = "string)" }
+Example:
+
+- Lua: { UnSelectPath = "/path/to/file" }
+- YAML:
UnSelectPath: /path/to/file
+
+
+Toggle selection on the focused node.
+Example:
+
+- Lua: "ToggleSelection"
+- YAML
ToggleSelection
+
+
+Toggle between select all and unselect all.
+Example:
+
+- Lua: "ToggleSelectAll"
+- YAML:
ToggleSelectAll
+
+
+Toggle selection by file path.
+Type: { ToggleSelectionByPath = "string" }
+Example:
+
+- Lua: { ToggleSelectionByPath = "/path/to/file" }
+- YAML:
ToggleSelectionByPath: /path/to/file
+
+
+Clear the selection.
+Example:
+
+- Lua: "ClearSelection"
+- YAML:
ClearSelection
+
+
+
+Add a filter to exclude nodes
+while exploring directories.
+Type: { AddNodeFilter = { filter = Filter, input = "string" }
+Example:
+
+- Lua: { AddNodeFilter = { filter = "RelativePathDoesStartWith", input = "foo" } }
+- YAML:
AddNodeFilter: { filter: RelativePathDoesStartWith, input: foo }
+
+
+Remove an existing filter.
+Type: { RemoveNodeFilter = { filter = Filter, input = "string" }
+Example:
+
+- Lua: { RemoveNodeFilter: { filter: "RelativePathDoesStartWith", input: "foo" } }
+- YAML:
RemoveNodeFilter: { filter: RelativePathDoesStartWith, input: foo }
+
+
+Remove a filter if it exists,
+else, add a it.
+Type: { ToggleNodeFilter = { filter = Filter, input = "string" }
+Example:
+
+- Lua: { ToggleNodeFilter = { filter = "RelativePathDoesStartWith", input = "foo" } }
+- YAML:
ToggleNodeFilter: { filter: RelativePathDoesStartWith, input: foo }
+
+
+Add a node filter reading the
+input from the buffer.
+Type: { AddNodeFilterFromInput = Filter }
+Example:
+
+- Lua: { AddNodeFilterFromInput = "RelativePathDoesStartWith" }
+- YAML:
AddNodeFilterFromInput: RelativePathDoesStartWith
+
+
+Remove a node filter reading
+the input from the buffer.
+Type: { RemoveNodeFilterFromInput = Filter }
+Example:
+
+- Lua: { RemoveNodeFilterFromInput = "RelativePathDoesStartWith" }
+- YAML:
RemoveNodeFilterFromInput: RelativePathDoesStartWith
+
+
+Remove the last node filter.
+Example:
+
+- Lua: "RemoveLastNodeFilter"
+- YAML:
RemoveLastNodeFilter
+
+
+Reset the node filters back to the
+default configuration.
+Example:
+
+- Lua: "ResetNodeFilters"
+- YAML:
ResetNodeFilters
+
+
+Clear all the node filters.
+Example:
+
+- Lua: "ClearNodeFilters"
+- YAML:
ClearNodeFilters
+
+
+
+Add a sorter to sort nodes while
+exploring directories.
+Type: { AddNodeSorter = { sorter = Sorter, reverse = bool } }
+Example:
+
+- Lua: { AddNodeSorter = { sorter = "ByRelativePath", reverse = false } }
+- YAML:
AddNodeSorter: { sorter: ByRelativePath, reverse: false }
+
+
+Remove an existing sorter.
+Type: { RemoveNodeSorter = Sorter }
+Example:
+
+- Lua: { RemoveNodeSorter = "ByRelativePath" }
+- YAML:
RemoveNodeSorter: ByRelativePath
+
+
+Reverse a node sorter.
+Type: { ReverseNodeSorter = Sorter }
+Example:
+
+- Lua: { ReverseNodeSorter = "ByRelativePath" }
+- YAML:
ReverseNodeSorter: ByRelativePath
+
+
+Remove a sorter if it exists,
+else, add a it.
+Type: { ToggleNodeSorter = { sorter = Sorter, reverse = bool } }
+Example:
+
+- Lua: { ToggleSorterSorter: { sorter = "ByRelativePath", reverse = false } }
+- YAML:
ToggleSorterSorter: {sorter: ByRelativePath, reverse: false }
+
+
+Reverse the node sorters.
+Example:
+
+- Lua: "ReverseNodeSorters"
+- YAML:
ReverseNodeSorters
+
+
+Remove the last node sorter.
+Example:
+
+- Lua: "RemoveLastNodeSorter"
+- YAML:
RemoveLastNodeSorter
+
+
+Reset the node sorters back to
+the default configuration.
+Example:
+
+- Lua: "ResetNodeSorters"
+- YAML:
ResetNodeSorters
+
+
+Clear all the node sorters.
+Example:
+
+- Lua: "ClearNodeSorters"
+- YAML:
ClearNodeSorters
+
+
+
+Enable mouse
+Example:
+
+- Lua: "EnableMouse"
+- YAML:
EnableMouse
+
+
+Disable mouse
+Example:
+
+- Lua: "DisableMouse"
+- YAML:
DisableMouse
+
+
+Toggle mouse
+Example:
+
+- Lua: "ToggleMouse"
+- YAML:
ToggleMouse
+
+
+
+Start piping the focused path to the given fifo path
+Type: { StartFifo = "string" }
+Example:
+
+- Lua: { StartFifo = "/tmp/xplr.fifo }
+- YAML:
StartFifo: /tmp/xplr.fifo
+
+
+Close the active fifo and stop piping.
+Example:
+
+- Lua: "StopFifo"
+- YAML:
StopFifo
+
+
+Toggle betwen {Start|Stop}Fifo
+Type: { ToggleFifo = "string" }
+Example:
+
+- Lua: { ToggleFifo = "/path/to/fifo" }
+- YAML:
ToggleFifo: /path/to/fifo
+
+
+
+Log information message.
+Type: { LogInfo = "string" }
+Example:
+
+- Lua: { LogInfo = "launching satellite" }
+- YAML:
LogInfo: launching satellite
+
+
+Log a success message.
+Type: { LogSuccess = "String" }
+Example:
+
+- Lua: { LogSuccess = "satellite reached destination" }
+- YAML:
LogSuccess: satellite reached destination
+
+
+Log an warning message.
+Type: { LogWarning = "string" }
+Example:
+
+- Lua: { LogWarning = "satellite is heating" }
+- YAML:
LogWarning: satellite is heating
+
+
+Log an error message.
+Type: { LogError = "string" }
+Example:
+
+- Lua: { LogError = "satellite crashed" }
+- YAML:
LogError: satellite crashed
+
+
+
+Write the application state to a file, without quitting. Also helpful
+for debugging.
+Type: { Debug = "string" }
+Example:
+
+- Lua: { Debug = "/path/to/file" }
+- YAML:
Debug: /path/to/file
+
+
+
+Example:
+
+- Lua: "Quit"
+- YAML:
Quit
+
+Quit with returncode zero (success).
+
+Print $PWD and quit.
+Example:
+
+- Lua: "PrintPwdAndQuit"
+- YAML:
PrintPwdAndQuit
+
+
+Print the path under focus and quit. It can be empty string if there's
+nothing to focus.
+Example:
+
+- Lua: "PrintFocusPathAndQuit"
+- YAML:
PrintFocusPathAndQuit
+
+
+Print the selected paths and quit. It can be empty is no path is
+selected.
+Example:
+
+- Lua: "PrintSelectionAndQuit"
+- YAML:
PrintSelectionAndQuit
+
+
+Print the selected paths if it's not empty, else, print the focused
+node's path.
+Example:
+
+- Lua: "PrintResultAndQuit"
+- YAML:
PrintResultAndQuit
+
+
+Print the state of application in YAML format. Helpful for debugging or
+generating the default configuration file.
+Example:
+
+- Lua: "PrintAppStateAndQuit"
+- YAML:
PrintAppStateAndQuit
+
+
+Terminate the application with a non-zero return code.
+Example:
+
+- Lua: "Terminate"
+- YAML:
Terminate
+
+
+
+
+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"
+
+
+
+
+xplr allows customizing the shape and style of the borders.
+
+A border can be one of the following:
+
+- Top
+- Right
+- Bottom
+- Left
+
+
+A border can be one of the following:
+
+- Plain
+- Rounded
+- Double
+- Thick
+
+
+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"
+
+
+A style object contains the following information:
+
+
+Type: nullable Color
+The foreground color.
+
+Type: nullable Color
+The background color.
+
+Type: nullable list of Modifier
+Modifiers to add.
+
+Type: nullable list of Modifier
+Modifiers to remove.
+
+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 can be one of the following:
+
+- "Bold"
+- "Dim"
+- "Italic"
+- "Underlined"
+- "SlowBlink"
+- "RapidBlink"
+- "Reversed"
+- "Hidden"
+- "CrossedOut"
+
+
+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" }
+
+
+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.
+
+It contains the following information:
+
+
+A sorter can be one of the following:
+
+- "ByRelativePath"
+- "ByIRelativePath"
+- "ByExtension"
+- "ByIsDir"
+- "ByIsFile"
+- "ByIsSymlink"
+- "ByIsBroken"
+- "ByIsReadonly"
+- "ByMimeEssence"
+- "BySize"
+- "ByCanonicalAbsolutePath"
+- "ByICanonicalAbsolutePath"
+- "ByCanonicalExtension"
+- "ByCanonicalIsDir"
+- "ByCanonicalIsFile"
+- "ByCanonicalIsReadonly"
+- "ByCanonicalMimeEssence"
+- "ByCanonicalSize"
+- "BySymlinkAbsolutePath"
+- "ByISymlinkAbsolutePath"
+- "BySymlinkExtension"
+- "BySymlinkIsDir"
+- "BySymlinkIsFile"
+- "BySymlinkIsReadonly"
+- "BySymlinkMimeEssence"
+- "BySymlinkSize"
+
+TODO: document each
+
+Type: boolean
+It defined the direction of the order.
+
+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.
+
+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.
+
+It contains the following information:
+
+
+A filter can be one of the following:
+
+- "RelativePathIs"
+- "RelativePathIsNot"
+- "IRelativePathIs"
+- "IRelativePathIsNot"
+- "RelativePathDoesStartWith"
+- "RelativePathDoesNotStartWith"
+- "IRelativePathDoesStartWith"
+- "IRelativePathDoesNotStartWith"
+- "RelativePathDoesContain"
+- "RelativePathDoesNotContain"
+- "IRelativePathDoesContain"
+- "IRelativePathDoesNotContain"
+- "RelativePathDoesEndWith"
+- "RelativePathDoesNotEndWith"
+- "IRelativePathDoesEndWith"
+- "IRelativePathDoesNotEndWith"
+- "AbsolutePathIs"
+- "AbsolutePathIsNot"
+- "IAbsolutePathIs"
+- "IAbsolutePathIsNot"
+- "AbsolutePathDoesStartWith"
+- "AbsolutePathDoesNotStartWith"
+- "IAbsolutePathDoesStartWith"
+- "IAbsolutePathDoesNotStartWith"
+- "AbsolutePathDoesContain"
+- "AbsolutePathDoesNotContain"
+- "IAbsolutePathDoesContain"
+- "IAbsolutePathDoesNotContain"
+- "AbsolutePathDoesEndWith"
+- "AbsolutePathDoesNotEndWith"
+- "IAbsolutePathDoesEndWith"
+- "IAbsolutePathDoesNotEndWith"
+
+TODO: document each
+
+Type: string
+The input for the condition.
+
+ToggleNodeFilter = {
+ filter = "RelativePathDoesNotStartWith",
+ input = "."
+}
+
+Here, ToggleNodeFilter is a message that adds or removes
+(toggles) the filter applied.
+
+A column renderer is a Lua function that receives a special argument and
+returns a string that will be displayed in each specific field of the
+files table.
+xplr by default provides the following column renderers:
+
+xplr.fn.builtin.fmt_general_table_row_cols_0xplr.fn.builtin.fmt_general_table_row_cols_1xplr.fn.builtin.fmt_general_table_row_cols_2xplr.fn.builtin.fmt_general_table_row_cols_3xplr.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.
+
+The special argument contains the following fields
+
+
+Type: string
+The parent path of the node.
+
+Type: string
+The path relative to the parent, i.e. the file/directory name with extension.
+
+Type: string
+The absolute path (without resolving symlinks) of the node.
+
+Type: string
+The extension of the node.
+
+Type: boolean
+true if the node is a symlink.
+
+Type: boolean
+true if the node is a broken symlink.
+
+Type: boolean
+true if the node is a directory.
+
+Type: boolean
+true if the node is a file.
+
+Type: boolean
+true if the node is real-only.
+
+Type: string
+The mime type of the node. For e.g. text/csv, image/jpeg etc.
+
+Type: integer
+The size of the exact node. The size of a directory won't be calculated
+recursively.
+
+Type: string
+Like size but in human readable format.
+
+Type: Permission
+The permissions applied to the node.
+
+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.
+
+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.
+
+Type: integer
+Index (starting from 0) of the node.
+
+Type: integer
+Relative index from the focused node (i.e. 0th node).
+
+Type: boolean
+true if the node is before the focused node.
+
+Type: boolean
+true if the node is after the focused node.
+
+Type: string
+The tree component based on the node's index.
+
+Type: string
+The prefix applicable for the node.
+
+Type: string
+The suffix applicable for the node.
+
+Type: boolean
+true if the node is selected.
+
+Type: boolean
+true if the node is under focus.
+
+Type: integer
+The total number of the nodes.
+
+Type: mapping of string and string
+The applicable meta object for the node.
+
+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.
+
+It contains the following fields.
+
+
+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 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.
+
+This is a special argument passed to the lua functions when called using the
+CallLua, CallLuaSilently messages.
+It contains the following information:
+
+
+Type: string
+xplr version. Can be used to test compatibility.
+
+Type: string
+The present working directory/
+
+Type: nullable Node
+The node under focus.
+
+Type: nullable Directory Buffer
+The directory buffer being rendered.
+
+Type: list of selected Nodes
+The selected nodes.
+
+Type: Mode
+Current mode.
+
+Type: Layout
+Current layout.
+
+Type: nullable string
+The input buffer.
+
+Type: integer
+The xplr session PID.
+
+Type: string
+The session path.
+
+TODO
+
+Type: History
+
+Type: list of Mode
+Last modes, not popped yet.
+
+Type: string
+The parent path of the node.
+
+Type: string
+The path relative to the parent, i.e. the file/directory name with extension.
+
+Type: string
+The absolute path (without resolving symlinks) of the node.
+
+Type: string
+The extension of the node.
+
+Type: boolean
+true if the node is a symlink.
+
+Type: boolean
+true if the node is a broken symlink.
+
+Type: boolean
+true if the node is a directory.
+
+Type: boolean
+true if the node is a file.
+
+Type: boolean
+true if the node is real-only.
+
+Type: string
+The mime type of the node. For e.g. text/csv, image/jpeg etc.
+
+Type: integer
+The size of the exact node. The size of a directory won't be calculated
+recursively.
+
+Type: string
+Like size but in human readable format.
+
+Type: Permission
+The permissions applied to the node.
+
+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.
+
+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.
+
+A node contains the following fields:
+
+
+Directory buffer contains the following fields:
+
+
+Type: string
+The parent path of the node.
+
+Type: list of Nodes
+A list of visible nodes.
+
+Type: int
+The count of nodes being rendered.
+
+Type: int
+The index of the node under focus. It can be 0 even when there's no node to
+focus on.
+
+History contains the following fields:
+
+
+Type: int
+Location of the current path in history.
+
+Type: list of string
+Visited paths.
+
+-- 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.
+
+
+Alternative to CallLua, CallLuaSilently messages that call Lua functions,
+there are Call, CallSilently, BashExec, BashExecSilently messages
+that call shell commands.
+However, unlike the Lua functions, these shell commands have to read the useful
+information and send messages via environment variables and temporary files
+called "pipe"s. These environment variables and files are only available when
+a command is being executed.
+Visit the fzf integration tutorial
+for example.
+
+To see the environment variables, invoke the shell by typing :! in default
+mode and run the following command:
+env | grep ^XPLR_
+
+You will see something like:
+XPLR_FOCUS_INDEX=0
+XPLR_MODE=action to
+XPLR_PIPE_SELECTION_OUT=/run/user/1000/xplr/session/122278/pipe/selection_out
+XPLR_INPUT_BUFFER=
+XPLR_PIPE_GLOBAL_HELP_MENU_OUT=/run/user/1000/xplr/session/122278/pipe/global_help_menu_out
+XPLR_PID=122278
+XPLR_PIPE_MSG_IN=/run/user/1000/xplr/session/122278/pipe/msg_in
+XPLR_PIPE_LOGS_OUT=/run/user/1000/xplr/session/122278/pipe/logs_out
+XPLR_PIPE_RESULT_OUT=/run/user/1000/xplr/session/122278/pipe/result_out
+XPLR_PIPE_HISTORY_OUT=/run/user/1000/xplr/session/122278/pipe/history_out
+XPLR_FOCUS_PATH=/home/sayanarijit/Documents/GitHub/xplr/docs/en/book
+XPLR_SESSION_PATH=/run/user/1000/xplr/session/122278
+XPLR_APP_VERSION=0.14.3
+XPLR_PIPE_DIRECTORY_NODES_OUT=/run/user/1000/xplr/session/122278/pipe/directory_nodes_out
+
+The environment variables starting with XPLR_PIPE_ are the temporary files
+called "pipe"s.
+
+Current there is only one input pipe.
+
+
+XPLR_PIPE_*_OUT are the output pipes that contain data which cannot be
+exposed directly via environment variables, like multi-line string.
+
+
+Append new-line delimited messages to this pipe in YAML
+(or JSON) syntax. These messages will be read and
+handled by xplr after the command execution.
+
+New-line delimited list of selected paths.
+
+The full help menu.
+
+New-line delimited list of logs.
+
+New-line delimited result (selected paths if any, else the focused path)
+
+New-line delimited list of last visited paths (similar to jump list in vim).
+
+New-line delimited list of paths, filtered and sorted as displayed in the
+files table.
+
+xplr.config.modes.builtin.default.key_bindings.on_key.space = {
+ help = "ask name and greet",
+ messages = {
+ {
+ BashExec = [===[
+ echo "What's your name?"
+
+ read name
+ greeting="Hello $name!"
+ message="$greeting You are inside $PWD"
+
+ echo LogSuccess: '"'$message'"' >> "${XPLR_PIPE_MSG_IN:?}"
+ ]===]
+ }
+ }
+}
+
+-- Now, when you press "space" in default mode, you will be prompted for your
+-- name. Enter your name to receive a nice greeting and to know your location.
+
+
+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.
+
+Change directory using xplr.
+
+Expand for details
+
+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)"'
+
+
+
+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 files using m and fuzzy search bookmarks using backtick.
+
+Expand for details
+
+
+xplr.config.modes.builtin.default.key_bindings.on_key.m = {
+ help = "bookmark",
+ messages = {
+ {
+ BashExecSilently = [===[
+ PTH="${XPLR_FOCUS_PATH:?}"
+ if echo "${PTH:?}" >> "${XPLR_SESSION_PATH:?}/bookmarks"; then
+ echo "LogSuccess: ${PTH:?} added to bookmarks" >> "${XPLR_PIPE_MSG_IN:?}"
+ else
+ echo "LogError: Failed to bookmark ${PTH:?}" >> "${XPLR_PIPE_MSG_IN:?}"
+ fi
+ ]===],
+ },
+ },
+}
+
+xplr.config.modes.builtin.default.key_bindings.on_key["`"] = {
+ help = "go to bookmark",
+ messages = {
+ {
+ BashExec = [===[
+ PTH=$(cat "${XPLR_SESSION_PATH:?}/bookmarks" | fzf --no-sort)
+ if [ "$PTH" ]; then
+ echo FocusPath: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}"
+ fi
+ ]===],
+ },
+ },
+}
+
+
+
+A bookmark mode that allows for a bookmark file to be used throughout multiples
+sessions. It is set to the environment variable $XPLR_BOOKMARK_FILE. A
+bookmark can be added, deleted, or jumped to.
+
+Expand for details
+
+- Author: @lmburns
+- Requires: fzf, sd
+- Tested on: MacOS
+
+-- Bookmark: mode binding
+xplr.config.modes.custom.bookmark = {
+ name = "bookmark",
+ key_bindings = {
+ on_key = {
+ m = {
+ help = "bookmark dir",
+ messages = {
+ { BashExecSilently = [[
+ PTH="${XPLR_FOCUS_PATH:?}"
+ if [ -d "${PTH}" ]; then
+ PTH="${PTH}"
+ elif [ -f "${PTH}" ]; then
+ PTH="$(dirname "${PTH}")"
+ fi
+ if echo "${PTH:?}" >> "${XPLR_BOOKMARK_FILE:?}"; then
+ echo "LogSuccess: ${PTH:?} added to bookmarks" >> "${XPLR_PIPE_MSG_IN:?}"
+ else
+ echo "LogError: Failed to bookmark ${PTH:?}" >> "${XPLR_PIPE_MSG_IN:?}"
+ fi
+ ]]
+ },
+ },
+ },
+ g = {
+ help = "go to bookmark",
+ messages = {
+ {
+ BashExec = [===[
+ PTH=$(cat "${XPLR_BOOKMARK_FILE:?}" | fzf --no-sort)
+ if [ "$PTH" ]; then
+ echo FocusPath: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}"
+ fi
+ ]===]
+ },
+ },
+ },
+ d = {
+ help = "delete bookmark",
+ messages = {
+ { BashExec = [[
+ PTH=$(cat "${XPLR_BOOKMARK_FILE:?}" | fzf --no-sort)
+ sd "$PTH\n" "" "${XPLR_BOOKMARK_FILE:?}"
+ ]]
+ },
+ },
+ },
+ esc = {
+ help = "cancel",
+ messages = {
+ "PopMode",
+ },
+ },
+ },
+ },
+}
+
+
+
+Another bookmark manager type thing, taken from wfxr's zsh plugin which has colored output with fzf.
+
+Expand for details
+
+- Author: @lmburns
+- Requires: fzf, exa
+- Tested on: MacOS
+
+xplr.config.modes.builtin.go_to.key_bindings.on_key.b = {
+ help = "bookmark jump",
+ messages = {
+ "PopMode",
+ { BashExec = [===[
+ field='\(\S\+\s*\)'
+ esc=$(printf '\033')
+ N="${esc}[0m"
+ R="${esc}[31m"
+ G="${esc}[32m"
+ Y="${esc}[33m"
+ B="${esc}[34m"
+ pattern="s#^${field}${field}${field}${field}#$Y\1$R\2$N\3$B\4$N#"
+ PTH=$(sed 's#: # -> #' "$PATHMARKS_FILE"| nl| column -t \
+ | gsed "${pattern}" \
+ | fzf --ansi \
+ --height '40%' \
+ --preview="echo {}|sed 's#.*-> ##'| xargs exa --color=always" \
+ --preview-window="right:50%" \
+ | sed 's#.*-> ##')
+ if [ "$PTH" ]; then
+ echo ChangeDirectory: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}"
+ fi
+ ]===]
+ },
+ }
+}
+
+
+
+Fuzzy search the last visited directories.
+
+Expand for details
+
+xplr.config.modes.builtin.go_to.key_bindings.on_key.h = {
+ help = "history",
+ messages = {
+ "PopMode",
+ {
+ BashExec = [===[
+ PTH=$(cat "${XPLR_PIPE_HISTORY_OUT:?}" | sort -u | fzf --no-sort)
+ if [ "$PTH" ]; then
+ echo ChangeDirectory: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}"
+ fi
+ ]===],
+ },
+ },
+}
+
+
+
+Batch rename the selected or visible files and directories in $PWD.
+
+Expand for details
+
+
+xplr.config.modes.builtin.default.key_bindings.on_key.R = {
+ help = "batch rename",
+ messages = {
+ {
+ BashExec = [===[
+ SELECTION=$(cat "${XPLR_PIPE_SELECTION_OUT:?}")
+ NODES=${SELECTION:-$(cat "${XPLR_PIPE_DIRECTORY_NODES_OUT:?}")}
+ if [ "$NODES" ]; then
+ echo -e "$NODES" | renamer
+ echo ExplorePwdAsync >> "${XPLR_PIPE_MSG_IN:?}"
+ fi
+ ]===],
+ },
+ },
+}
+
+
+
+Serve $PWD using a static web server via LAN.
+
+Expand for details
+
+xplr.config.modes.builtin.default.key_bindings.on_key.S = {
+ help = "serve $PWD",
+ messages = {
+ {
+ BashExec = [===[
+ IP=$(ip addr | grep -w inet | cut -d/ -f1 | grep -Eo '[0-9]{1,3}\.[0-9]{ 1,3}\.[0-9]{1,3}\.[0-9]{1,3}' | fzf --prompt 'Select IP > ')
+ echo "IP: ${IP:?}"
+ read -p "Port (default 5000): " PORT
+ echo
+ sfz --all --cors --no-ignore --bind ${IP:?} --port ${PORT:-5000} . &
+ sleep 1 && read -p '[press enter to exit]'
+ kill -9 %1
+ ]===],
+ },
+ },
+}
+
+
+
+
+
+xplr supports pluggable Lua modules that can be used to easily configure or
+extend xplr UI and functionalities.
+
+
+One way to install plugins is to use a plugin manager like dtomvan/xpm.xplr.
+But you can also install and manage plugins 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.
+
+
+
+
+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
+
+
+Anyone who can write Lua code, can write xplr plugins.
+Just follow the instructions and best practices:
+
+xplr plugins are named using hiphen (-) separated words that may also include
+integers. They will be plugged using the require() function in Lua.
+
+A minimal plugin should confirm to the following structure:
+plugin-name
+├── README.md
+└── init.lua
+
+You can also use
+this template.
+
+This is where you document what the plugin does, how to use it, etc.
+
+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 }
+
+
+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.
+
+Visit Awesome Plugins for xplr plugin examples.
+
+
+
+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.
+
+
+
+
+
+
+
+
+
+xplr is designed to integrate well with other tools and commands. It can be
+used as a file picker or a pluggable file manager.
+
+
+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.
+
+
+- fm-nvim Neovim plugin that lets you use your favorite terminal file managers from within Neovim.
+- vim-floaterm xplr integrated in vim-floaterm (Neo)vim plugin.
+- xplr.nvim Opens xplr inside nvim, and hosts a msgpack client inside xplr.
+- xplr.vim Pick files in Vim using xplr.
+
+
+
+
+
+- gpg-tui Import GPG certificates using xplr.
+
+
+
+
+
+add more
+Like this project so far? Please consider contributing.
+
+These are the alternative TUI/CLI file managers/explorers you might want to check out (in no particular order).
+
+add more
+
+When you upgrade xplr, you might see an error like this
+Incompatible script version in: /home/sayanarijit/.config/xplr/init.lua. The script version is: 0.9.0, the required version is: 0.10.1. Visit https://github.com/sayanarijit/xplr/wiki/Upgrade-Guide
+
+All you need to do is follow the instructions starting from
+your config version, all the way to the required version.
+
+Expand for more information
+With every update, we either implement a major breaking change (e.g.
+deprecating or replacing messages), or a minor feature addition (e.g. adding
+new messages) or patch, fixes, and optimization (e.g. performance
+optimization).
+Knowing that we use the {major}.{minor}.{patch} versioning format,
+
+- Major version mismatch are generally incompatible. xplr will fail
+with error.
+- Minor version upgrades (not downgrades) and patch fixes are backwards
+compatible. You might get notified by log a message which you can disable by
+updating the version in your config file.
+- However, if the config file has a higher value for the minor version
+than the app, then also xplr will fail with error, suggesting you
+to visit this page.
+Though in that case, you will be downgrading your config file based on your
+app version.
+
+e.g.
+
+1.0.0 -> 1.0.x: Bug fix (fully compatible).1.0.0 -> 1.x.x: Only backwards compatible. You can't generally use for
+e.g. app-1.0.0 with config-1.1.0. But vice versa is fine.1.0.0 -> x.x.x: Not compatible at all.
+Note that until we're v1, we'll be using the {minor} version number as
+{major}, and the {patch} fix number as {minor} to determine
+compatibility.
+
+
+
+
+- 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.
+
+
+
+- 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
+
+
+
+Like this project so far? Please consider contributing.
+
+
+- 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.
+
+
+
+- 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.
+
+
+
+- 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.
+
+
+
+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/*).
+
+
+
+
+
+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.
+
+
+
+- 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.
+
+
+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.
+
+
+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.
+
+
+
+- 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.
+
+
+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.
+
+
+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.
+
+
+- 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.
+
+
+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.
+
+
+If you have customized general.table.row.cols, you might want to update it to use the new variables with better symlink support.
+
+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.
+
+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.
+
+
+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
+
+
+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.
+
+
+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.
+
+
+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.
+
+If you like xplr, and want to contribute, that would be really awesome.
+You can contribute to this project in the following ways
+
+For further queries or concern related to xplr, just ask us.
+
+
+
+