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.

Instructions

v0.18.0 -> v0.19.0

• BREAKING: The builtin modes cannot be accessed using space separated names anymore. Use underscore separated mode names. For e.g. SwitchModeBuiltin: create file becomes SwitchModeBuiltin: create_file and so on. Kindly go through your config, find and update them, or copy from the latest init.lua.
• Now you can use xplr.config.general.global_key_bindings to define a set of key bindings that are available by default in every mode. e.g. esc and ctrl-c, and remove boilerplate code from your config.
• You can use the new builtin mode go_to_path which can be used for typing or pasting paths to enter into or to focus on. Type g p to enter this mode.
• Now you can use basic tab completion in the go_to_path, create_file, create_directory, rename and duplicate_as modes.
• Use the builtin function xplr.fn.builtin.try_complete_path to add easy tab completion support into your own configuration.
• Now you can open OSC 7 compatible terminals into the xplr's current working directory by spawning new terminal sessions via the terminal supported key bindings.
• Use NO_COLOR environment variable to disable OSC 7 compliance along with colors.
• If you have fully copied the default init.lua locally, you might want to go through the latest improvements in init.lua. Specifically the search, filter and sort modes. Also, search for SetInputPrompt and the tab key bindings.

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

v0.17.6 -> v0.18.0

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

v0.16.4 -> v0.17.6

• Deprecated app.directory_buffer, app.history, and app.last_modes in the custom dynamic layout renderer context. As of now, there's no way to access these fields in dynamic layouts. While app.history and app.last_modes can be re-added upon request (with justification), app.directory_buffer has been deprecated for good. However, there's no change in the CallLua* context.
• Set xplr.config.general.hide_remaps_in_help_menu to true to hide the remaps in help menu.
• None will be serialized to nil in Lua.
• LuaEval can now return a function that will be called with the Lua Context argument. Refer to the Full List of Messages doc for example.
• From version v0.17.1, set xplr.config.general.disable_debug_error_mode to true to disable switching to the "debug error" mode when startup errors occur.
• From version v0.17.2, you can use CLI argument --print-pwd-as-result for cd on quit, and key binding ctrl-d to duplicate a path in the same directory with a different name.
• Since version v0.17.3, you can use border_type, border_style to customize borders, and enforce_bounded_index_navigation to customize up/down navigation behavior when focus is on the top or bottom node.

v0.15.2 -> v0.16.4

• Deprecated config.general.cursor. The default terminal cursor will be used for the time being.
• Opening xplr inside a symlink will not resolve the path.
• You can now replace most boilerplate configuration handling keys to send BufferInputFromKey, RemoveInputBufferLastCharacter, RemoveInputBufferLastWord, SetInputBuffer = "" etc. messages with a single UpdateInputBufferFromKey message.
• You can now pass multiple paths as command-line arguments or via stdin to select paths, e.g. xplr -- $PWD /path/to/select/1 /path/to/select/2.
• Pass --force-focus to focus on the first path even if it's a directory, e.g. xplr . --force-focus.
• Use new messages LuaEval and LuaEvalSilently to run Lua code without needing to define a function. However, the app context won't be available.
• You can now use new key handlers in the config:
  • on_alphanumeric
  • on_character
  • on_navigation
  • on_function

v0.14.7 -> v0.15.2

• Deprecated config field from CallLua argument. Use the globally available xplr.config instead.
• xplr.config.general.disable_recover_mode has been deprecated. Use xplr.config.general.enable_recover_mode instead.
• Use xplr.config.general.focus_selection_ui to highlight selected files under focus differently than files under focus that are not selected.
• Use PopModeKeepingInputBuffer, and SwitchMode alternatives to switching to different modes without resetting the input buffer.
• Use the new CustomContent layout option to render custom content.
• Use the new layout field in a mode to define custom layout for a specific mode.
• Library users please refer to the latest API docs and examples.

v0.13.7 -> v0.14.7

• macOS users need to place their config file (init.lua) in $HOME/.config/xplr/ or /etc/xplr/.
• Library users please refer to the latest API docs.
• Check out the new messages: {Start|Stop|Toggle}Fifo. These enable support for FIFO based file previews.
• You can disable the recover mode using config.general.disable_recover_mode = true.
• Try running xplr --help. Yes, CLI has been implemented.
• Since version v0.14.3, StartFifo and ToggleFifo will write to the FIFO path when called. So, there's no need to pipe the focus path explicitely.
• Since version v0.14.3, general config xplr.config.start_fifo is available which can be set to a file path to start a fifo when xplr starts.
• Since version v0.14.4, $XPLR_SESSION_PATH can be used to dump session related data.
• Since version v0.14.6, the -C or --extra-config CLI argument is available.

v0.12.1 -> v0.13.7

• Lua functions called using CallLua and CallLuaSilently messages will receive CallLuaArg object as the function argument (instead of the App object).
• Each node_types config will inherit defaults from matching less specifig node_types config and overwrite them.
• Since version v0.13.2, you don't need to use/send Refresh anymore. It will be auto-handled by xplr.

v0.11.1 -> v0.12.1

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

v0.10.2 -> v0.11.1

• remaps: has been removed to avoid confusion. Use lua assignments instead. For e.g.

  xplr.config.modes.builtin.default.key_bindings.on_key["v"] = xplr.config.modes.builtin.default.key_bindings.on_key.space
  

v0.9.1 -> v0.10.2

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

v0.9.0 -> v0.9.1

• You can now set remaps: {key: null} to un-map a key.
• gx will open the item under focus.
• New key map :sx will open the selected items.

v0.8.0 -> v0.9.0

Your previous config should mostly work fine. However, in case you are using SwitchMode heavily in your custom config, follow along.

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

v0.7.2 -> v0.8.0

If you have made changes to the config file,

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

v0.7.0 -> v0.7.2

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

v0.6.0 -> v0.7.0

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

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

v0.5.13 -> v0.6.0

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

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

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

v0.5.0 -> v0.5.13

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

v0.4.3 -> v0.5.0

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

Else do the following

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

v0.4.2 -> v0.4.3

If you have customized general.table.row.cols, you might want to update it to use the new variables with better symlink support.

v0.4.1 -> v0.4.2

In case you have mapped the keys q, ctrl-i and ctrl-o, you may want to revisit the default mode key bindings and remap accordingly to use the new functionalities.

v0.3.13 -> v0.4.1

A lot has changed (apologies). But I promise from now on, upgrading will be much less painful (thanks to @maximbaz's valuable inputs and code reviews).

So, to start with the upgrade, let's remove everything from your config file except the version field and your custom modifications. If version is the only thing remaining, update it to v0.4.1 and you are done.

Else, do the following

• Rename general.focused_ui to general.focus_ui (see here).
• Rename filetypes to node_types. (see here)
• Rename custom field to meta. (see here)
• Move icon to meta.icon. (see here)
• Rename normal_ui to default_ui. (see here)
• Split modes into modes.builtin and modes.custom (see here). Migrate your custom modes to modes.custom. And copy only the changes in the in-built modes in modes.builtin.
• Finally, update the version to v0.4.1.

v0.3.8 -> v0.3.13

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

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

Else, do the following

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

v0.3.0 -> v0.3.8

Your current config should work fine. However, you might want to replace some ResetNodeFilters messages with RemoveNodeFilter and RemoveNodeFilterFromInput to get a better search and filter experience.

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

Else, do the following

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

v0.2.14 -> v0.3.0

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

Else do the following:

• $XPLR_APP_YAML has been removed. You can use Debug to export the app state.
• $XPLR_RESULT has been ported to file $XPLR_PIPE_RESULT_OUT. Use cat instead of echo, < instead of <<< etc.
• $XPLR_GLOBAL_HELP_MENU has been ported to file $XPLR_PIPE_GLOBAL_HELP_MENU_OUT. Use cat instead of echo, < instead of <<< etc.
• $XPLR_DIRECTORY_NODES has been ported to file $XPLR_PIPE_DIRECTORY_NODES_OUT. Use cat instead of echo, < instead of <<< etc.
• $XPLR_LOGS has been ported to file $XPLR_PIPE_LOGS_OUT. Use cat instead of echo, < instead of <<< etc.
• $XPLR_PIPE_RESULT has been ported to file $XPLR_PIPE_RESULT_OUT. Use cat instead of echo, < instead of <<< etc.
• Finally, update the version in your config file.