xplr version 0.20.0 was released last week. If you haven't already, go ahead and install the latest version. This post will try to break down the changelog in the release in an easy-to-digest manner, looking through the perspective of different user groups.

For Regular Users (who don't yet have a custom init.lua)

Virtual root

This is probably one of the most unique features yet seen in a file explorer. What this does is simply lets you treat any directory as the root, restricting your navigation options limited inside that directory and its subdirectories, by passing the "--vroot /any/directory" command-line argument, or by toggling the vroot mode by typing ":vv". This new feature may not sound very useful at first, but imagine a scenario where you want to restrict your navigation options inside a project workspace, or a mount point, or a temporarily created directory. If you are not convinced of its usefulness yet, just wait for the upcoming set of interesting tools and plugins utilizing this feature (see gh-xplr). If you see the word "vroot" appear on the screen, you'll know you're using this feature.

go to the initial directory

No matter where you are, you can always return to where you started, by typing "g" and then "i". This lets you work in a project or any workspace where you always need to return to the "root" directory. By spawning xplr in the root directory of your project, your project root will be only two keys away. This is not like the "virtual root" explained above, since it doesn't restrict your navigation options. But sometimes, the use case may overlap, and you may have to decide whether to rely on this or the virtual root feature.

Newline safe

xplr can now handle file paths with newline characters (or basically any weird character) in them. Before this release, newline characters were a pain to deal with. However, if you are using plugins, you might need to wait while they update for this release to become newline safe.

For Advanced Users and Plugin Authors

For advanced users, probably the most exciting news is - "xplr has been fully documented". While there is still a lot to improve, the current xplr documentation should be able to provide all the references you might need to use xplr as an advanced user. Other interesting highlights are -

Type-safe message passing

If you have been using echo SomeMessage: "Some Argument" >> "$XPLR_PIPE_MSG_IN" to pass messages from the xplr shell, chances are, it will probably fail, or behave unexpectedly when handling file paths with newline characters or quotes in them. Safely escaping the paths, and then including it in an YAML string could be difficult and error-prone. That's why, this release introduces a new argument -m / --pipe-msg-in, using which, you can safely create and pass messages without having to worry about escaping. To pass a message safely, you simply execute the following command:

"$XPLR" -m "SomeMessage: %q" "Some Argument"

Where "$XPLR" points to the actual path of the currently running xplr binary (i.e. you can replace it with "xplr"), and "%q" is a placeholder for the argument ("Some Argument" in this case) to be safely escaped and quoted. You can use another placeholder "%s" to skip quoting the argument, for passing values like number or boolean. To write a single "%", you need to escape it with "%", i.e. write "%%". If the result string is not a valid message, it will try to give you a helpful error message, and then fail with some non-zero return code. Else, it will pass this message directly to $XPLR_PIPE_MSG_IN, leaving the stdout empty and returning zero. However, if you run this outside of xplr shell, you can see the JSON encoded message. This will help you debug message passing. Sometimes you may not want to pass a message into the input pipe, even when in xplr shell. In that case, you can use -M or --print-msg-in in the same way to generate and print the message into stdout.

Hooks

Another feature aimed towards advanced users is the ability to define hooks, i.e. define what to do when certain events occur, such as on directory change, on focus change, on load etc. However, unlike the traditional way of overriding the config file, you need to define it in a return statement at the end of your config file like below -

return {
  on_directory_change = { some, messages, },
  on_focus_change = { some, messages, },
  on_load = { some, messages, },
}

This means that plugins cannot override the hooks. Plugins are supposed to expose the hooks, so that you can hook them in your init.lua yourself, being aware of what all hooks are currently in use, and debug potential performance and other issues. Currently, only these three hooks are supported, but in the future, after some cleanup of the codebase, more hooks like "before_quit", "before_directory_change", "before_focus_change" etc. might be implemented.

new messages

Beside the hooks, you also get new messages to use in your init.lua, namely - Call0, CallSilently0, BashExec0, BashExecSilently0, SetVroot, UnsetVroot, ResetVroot, and ToggleVroot. These will help you with newline safety, and implement virtual root related features.

new environment variables

You also get new environment variables in xplr shell, namely - $XPLR, $XPLR_INITIAL_PWD and $XPLR_VROOT to pass messages using -m safely, and implement workspace based features.

lua utilities api

You can use the new Lua utility functions like basename, dirname, absolute, explore, shell_execute, and shell_quote exposed via the xplr.util table to write your config more conveniently. There might be more utility functions exposed this way in the future.

For xplr Author & Maintainer

This is probably a brag, but since the last release, the author & maintainer of xplr (i.e. me) got two new financial sponsors on github, (other than one long time sponsor in opencollective), which fuelled him to write this detailed post for you. So, be grateful to them, like the author is, or of course, you can sponsor him too.

So, this was about the most interesting highlights of xplr v0.20.0 for everyone. Follow this site for more updates.