Upgrade Guide
When you upgrade xplr, you might see an error like this
Incompatible script version in: /home/sayanarijit/.config/xplr/init.lua. The script version is: 0.9.0, the required version is: 0.10.1. Visit https://github.com/sayanarijit/xplr/wiki/Upgrade-Guide
All you need to do is follow the instructions starting from your config version, all the way to the required version.
Expand for more information
With every update, we either implement a major
breaking change (e.g.
deprecating or replacing messages), or a minor
feature addition (e.g. adding
new messages) or patch
, fixes, and optimization (e.g. performance
optimization).
Knowing that we use the {major}.{minor}.{patch}
versioning format,
- Major version mismatch are generally incompatible. xplr will fail with error.
- Minor version upgrades (not downgrades) and patch fixes are backwards compatible. You might get notified by log a message which you can disable by updating the version in your config file.
- However, if the config file has a higher value for the minor version than the app, then also xplr will fail with error, suggesting you to visit this page. Though in that case, you will be downgrading your config file based on your app version.
e.g.
1.0.0
->1.0.x
: Bug fix (fully compatible).1.0.0
->1.x.x
: Only backwards compatible. You can't generally use for e.g.app-1.0.0
withconfig-1.1.0
. But vice versa is fine.1.0.0
->x.x.x
: Not compatible at all.
Note that until we're v1
, we'll be using the {minor}
version number as
{major}
, and the {patch}
fix number as {minor}
to determine
compatibility.
Instructions
v0.16.4 -> v0.17.0
- Deprecated
app.directory_buffer
,app.history
, andapp.last_modes
in the custom dynamic layout renderer context. As of now, there's no way to access these fields in dynamic layouts. Whileapp.history
andapp.last_modes
can be re-added upon request (with justification),app.directory_buffer
has been deprecated for good. However, there's no change in theCallLua*
context. - Set
xplr.config.general.help_hide_remaps
totrue
to hide the remaps in help menu. None
will be serialized tonil
in Lua.LuaEval
can now return a function that will be called with the Lua Context argument. Refer to theFull List of Messages
doc for example.
v0.15.2 -> v0.16.4
- Deprecated
config.general.cursor
. The default terminal cursor will be used for the time being. - Opening xplr inside a symlink will not resolve the path.
- You can now replace most boilerplate configuration handling keys to send
BufferInputFromKey
,RemoveInputBufferLastCharacter
,RemoveInputBufferLastWord
,SetInputBuffer = ""
etc. messages with a singleUpdateInputBufferFromKey
message. - You can now pass multiple paths as command-line arguments or via stdin to
select paths, e.g.
xplr -- $PWD /path/to/select/1 /path/to/select/2
. - Pass
--force-focus
to focus on the first path even if it's a directory, e.g.xplr . --force-focus
. - Use new messages
LuaEval
andLuaEvalSilently
to run Lua code without needing to define a function. However, theapp
context won't be available. - You can now use new key handlers in the config:
- on_alphanumeric
- on_character
- on_navigation
- on_function
Like this project so far? Please consider contributing.
v0.14.7 -> v0.15.2
- Deprecated
config
field fromCallLua
argument. Use the globally availablexplr.config
instead. xplr.config.general.disable_recover_mode
has been deprecated. Usexplr.config.general.enable_recover_mode
instead.- Use
xplr.config.general.focus_selection_ui
to highlight selected files under focus differently than files under focus that are not selected. - Use
PopModeKeepingInputBuffer
, and SwitchMode alternatives to switching to different modes without resetting the input buffer. - Use the new
CustomContent
layout option to render custom content. - Use the new
layout
field in a mode to define custom layout for a specific mode. - Library users please refer to the latest API docs and examples.
v0.13.7 -> v0.14.7
- macOS users need to place their config file (
init.lua
) in$HOME/.config/xplr/
or/etc/xplr/
. - Library users please refer to the latest API docs.
- Check out the new messages:
{Start|Stop|Toggle}Fifo
. These enable support for FIFO based file previews. - You can disable the recover mode using
config.general.disable_recover_mode = true
. - Try running
xplr --help
. Yes, CLI has been implemented. - Since version
v0.14.3
,StartFifo
andToggleFifo
will write to the FIFO path when called. So, there's no need to pipe the focus path explicitely. - Since version
v0.14.3
, general configxplr.config.start_fifo
is available which can be set to a file path to start a fifo when xplr starts. - Since version
v0.14.4
,$XPLR_SESSION_PATH
can be used to dump session related data. - Since version
v0.14.6
, the-C
or--extra-config
CLI argument is available.
v0.12.1 -> v0.13.7
- Lua functions called using
CallLua
andCallLuaSilently
messages will receiveCallLuaArg
object as the function argument (instead of theApp
object). - Each
node_types
config will inherit defaults from matching less specifignode_types
config and overwrite them. - Since version
v0.13.2
, you don't need to use/sendRefresh
anymore. It will be auto-handled by xplr.
v0.11.1 -> v0.12.1
xplr.config.node_types.mime_essence
has split into type and subtype. Hence, instead ofxplr.config.node_types.mime_essence["text/plain"] = ..
usexplr.config.node_types.mime_essence["text"] = { plain = .. }
.- You can also define
xplr.config.node_types.mime_essence["text"]["*"]
that will match all text types (text/*
).
v0.10.2 -> v0.11.1
remaps:
has been removed to avoid confusion. Use lua assignments instead. For e.g.xplr.config.modes.builtin.default.key_bindings.on_key["v"] = xplr.config.modes.builtin.default.key_bindings.on_key.space
v0.9.1 -> v0.10.2
config.yml
has been fully replaced withinit.lua
. If you have a lot of customization in yourconfig.yml
, xplr-yml2lua can help you with migrating it toinit.lua
.Handlebars
templates has been replaced with Lua functions. You can either remove the customizations or overwrite the functions accordingly.- Added new messages
CallLua
andCallLuaSilently
to call lua functions. The app state will be passed as input to the functions, and the returned messages will be handled by xplr.CallLua
andCallLuaSilently
are more flexible (and probably faster) alternatives toCall
,CallSilently
,BashExec
andBashExecSilently
. e.g.
v0.9.0 -> v0.9.1
- You can now set
remaps: {key: null}
to un-map a key. gx
will open the item under focus.- New key map
:sx
will open the selected items.
v0.8.0 -> v0.9.0
Your previous config should mostly work fine. However, in case you are using SwitchMode
heavily in your custom config, follow along.
- Introduced new message
PopMode
. You might want to use this message instead ofSwitchMode*
when returning back to the previous mode. - After using (the group of)
PopMode
andSwitchMode*
messages, you are now required toRefresh
manually to avoid the UI lag. - Pressing any invalid key will now lead you to the
recover
mode and will protect you from typing further invalid keys. Pressesc
to escape therecover
mode. - Introduced new message
LogWarning
, similar to otherLog*
messages. - Creating files and directories has been optimized for batch creation.
v0.7.2 -> v0.8.0
If you have made changes to the config file,
- Replace message
Explore
withExplorePwd
orExplorePwdAsync
or probablyExploreParentsAsync
. - Pipe
$XPLR_PIPE_FOCUS_OUT
has been removed. Use$XPLR_FOCUS_PATH
env var instead. - You might want to review your path escaping logics. For e.g. use
echo FocusPath: "'"$PWD"'" >> $PIPE
instead ofecho "FocusPath: $PWD" >> $PIPE
.
v0.7.0 -> v0.7.2
- Just update the
version
in your config file. - For version >=
v0.7.1
, you might want to free up or remap thetab
key insearch
mode to enable easy selection during search.
v0.6.0 -> v0.7.0
If you haven't made any changes in the config file, you should be fine just updating the version number. Else,
- You can make the
Table: ...
,InputAndLogs: ...
layout values null and define the common properties in thegeneral.panel_ui
instead.
v0.5.13 -> v0.6.0
If you haven't made any changes in the config file, you should be fine just updating the version number. Else,
- Rename
add_modifier: {bits: 1}
toadd_modifiers: [Bold]
,sub_modifier: {bits: 1}
tosub_modifiers: [Bold]
and so on. - Rename
percentage: 10
toPercentage: 10
,ratio: 1
toRatio: 1
and so on. - You might want to free up or remap the
ctrl-w
key binding indefault
mode to enable layout switching.
Optionally, checkout this new theme to learn more about what's new.
v0.5.0 -> v0.5.13
- Just update the
version
in your config file. - For versions >=
v0.5.8
, you can set$OPENER
env var to declare a global GUI file opener (to open files using keysgx
). - You might also want to update other mappings to handle files with names starting with
-
(hiphen). For example, instead ofrm ${filename}
userm -- ${filename}
. Same goes forcp
,mv
,cat
,touch
etc. - For version >=
v0.5.13
, you might want to use the more specificSwitchModeBuiltin
andSwitchModeCustom
messages instead of the generalSwitchMode
message.
v0.4.3 -> v0.5.0
If you haven't have any changes in the config file, you should be fine just updating the version number.
Else do the following
- Replace
{RelativePathIs, case_sensitive: true}
withRelativePathIs
. - Replace
{RelativePathIs, case_sensitive: false}
withIRelativePathIs
. - Do the same with other filters you are using.
- You might want to update your
backspace
handling to use theRemoveInputBufferLastCharacter
message. - You might want to free-up
f
,s
,ctrl-r
andctrl-u
key bindings in the default mode, or remap them. - You might want to use the new UI variables.
- Update your config version to
v0.5.0
.
v0.4.2 -> v0.4.3
If you have customized general.table.row.cols
, you might want to update it to use the new variables with better symlink support.
v0.4.1 -> v0.4.2
In case you have mapped the keys q
, ctrl-i
and ctrl-o
, you may want to revisit the default mode key bindings and remap accordingly to use the new functionalities.
v0.3.13 -> v0.4.1
A lot has changed (apologies). But I promise from now on, upgrading will be much less painful (thanks to @maximbaz's valuable inputs and code reviews).
So, to start with the upgrade, let's remove everything from your config file except the version
field and your custom modifications. If version
is the only thing remaining, update it to v0.4.1
and you are done.
Else, do the following
- Rename
general.focused_ui
togeneral.focus_ui
(see here). - Rename
filetypes
tonode_types
. (see here) - Rename
custom
field tometa
. (see here) - Move
icon
tometa.icon
. (see here) - Rename
normal_ui
todefault_ui
. (see here) - Split
modes
intomodes.builtin
andmodes.custom
(see here). Migrate your custom modes tomodes.custom
. And copy only the changes in the in-built modes inmodes.builtin
. - Finally, update the
version
tov0.4.1
.
v0.3.8 -> v0.3.13
Your current config should work fine. However, you might want to replace some Call
and BashExec
messages with CallSilently
and BashExecSilently
to remove the flickering of the screen.
If you haven't made any changes to the configuration, you can delete and regenerate it.
Else, do the following
- Check the new default config by temporarily removing your current config (with backup) and dumping the new config.
- Search for
Call
andBashExec
in the new config. - Compare and probably replace the associated actions in your current config
v0.3.0 -> v0.3.8
Your current config should work fine. However, you might want to replace some ResetNodeFilters
messages with RemoveNodeFilter
and RemoveNodeFilterFromInput
to get a better search and filter experience.
If you haven't made any changes to the configuration, you can delete and regenerate it.
Else, do the following
- Check the new default config by temporarily removing your current config (with backup) and dumping the new config.
- Search for
RemoveNodeFilterFromInput
in the new config. - Compare and probably replace the associated actions in your current config.
v0.2.14 -> v0.3.0
If you haven't made any changes to the configuration, you can delete and regenerate it.
Else do the following:
$XPLR_APP_YAML
has been removed. You can useDebug
to export the app state.$XPLR_RESULT
has been ported to file$XPLR_PIPE_RESULT_OUT
. Usecat
instead ofecho
,<
instead of<<<
etc.$XPLR_GLOBAL_HELP_MENU
has been ported to file$XPLR_PIPE_GLOBAL_HELP_MENU_OUT
. Usecat
instead ofecho
,<
instead of<<<
etc.$XPLR_DIRECTORY_NODES
has been ported to file$XPLR_PIPE_DIRECTORY_NODES_OUT
. Usecat
instead ofecho
,<
instead of<<<
etc.$XPLR_LOGS
has been ported to file$XPLR_PIPE_LOGS_OUT
. Usecat
instead ofecho
,<
instead of<<<
etc.$XPLR_PIPE_RESULT
has been ported to file$XPLR_PIPE_RESULT_OUT
. Usecat
instead ofecho
,<
instead of<<<
etc.- Finally, update the
version
in your config file.