@ -7,7 +7,7 @@ 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](#instructions) starting from
All you need to do is follow the [instructions][1] starting from
your config version, all the way to the required version.
- Lua functions called using [`CallLua`](https://docs.rs/xplr/latest/xplr/app/enum.ExternalMsg.html#variant.CallLua) and [`CallLuaSilently`](https://docs.rs/xplr/latest/xplr/app/enum.ExternalMsg.html#variant.CallLuaSilently) messages will receive [`CallLuaArg`](https://docs.rs/xplr/latest/xplr/app/struct.CallLuaArg.html) object as the function argument (instead of the [`App`](https://docs.rs/xplr/latest/xplr/app/struct.App.html) object).
#### [v0.12.1][6] -> [v0.13.7][2]
- Lua functions called using [`CallLua`][7] and [`CallLuaSilently`][8] messages will receive [`CallLuaArg`][9] object as the function argument (instead of the [`App`][10] 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`](https://github.com/sayanarijit/xplr/blob/85696ded7a/src/config.yml) has been fully replaced with [`init.lua`](https://github.com/sayanarijit/xplr/blob/main/src/init.lua). If you have a lot of customization in your `config.yml`, [xplr-yml2lua](https://github.com/sayanarijit/xplr-yml2lua) can help you with migrating it to `init.lua`.
- `Handlebars` templates has been replaced with [Lua functions](https://github.com/sayanarijit/xplr/blob/bfdb7736b99bc3c5ae53e7d621ba0e7ca2299b14/src/init.lua#L2005-L2064). 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.](https://github.com/sayanarijit/xplr/pull/177#issue-650643573)
- [`config.yml`][14] has been fully replaced with [`init.lua`][15]. If you have a lot of customization in your `config.yml`, [xplr-yml2lua][16] can help you with migrating it to `init.lua`.
- `Handlebars` templates has been replaced with [Lua functions][17]. 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.][18]
- 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 have customized `general.table.row.cols`, you might want to [update it](https://github.com/sayanarijit/xplr/blob/af1cda5762/src/config.yml#L46-L48) to use the new variables with better symlink support.
If you have customized `general.table.row.cols`, you might want to [update it][28] 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](https://github.com/maximbaz)'s valuable [inputs](https://github.com/sayanarijit/xplr/issues/45#issue-854447104) and [code reviews](https://github.com/sayanarijit/xplr/pull/47)).
A lot has changed (apologies). But I promise from now on, upgrading will be much less painful (thanks to [@maximbaz][31]'s valuable [inputs][32] and [code reviews][33]).
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](https://github.com/sayanarijit/xplr/blob/055c1083d6/src/config.yml#L124)).
- Rename `filetypes` to `node_types`. ([see here](https://github.com/sayanarijit/xplr/blob/055c1083d6/src/config.yml#L145))
- Rename `custom` field to `meta`. ([see here](https://github.com/sayanarijit/xplr/blob/055c1083d6/src/config.yml#L154-L155))
- Move `icon` to `meta.icon`. ([see here](https://github.com/sayanarijit/xplr/blob/055c1083d6/src/config.yml#L45))
- Rename `normal_ui` to `default_ui`. ([see here](https://github.com/sayanarijit/xplr/blob/055c1083d6/src/config.yml#L114))
- Split `modes` into `modes.builtin` and `modes.custom` ([see here](https://github.com/sayanarijit/xplr/blob/055c1083d6/src/config.yml#L180-L181)). Migrate your custom modes to `modes.custom`. And copy only the changes in the in-built modes in `modes.builtin`.
- Rename `general.focused_ui` to `general.focus_ui` ([see here][34]).
- Rename `filetypes` to `node_types`. ([see here][35])
- Rename `custom` field to `meta`. ([see here][36])
- Move `icon` to `meta.icon`. ([see here][37])
- Rename `normal_ui` to `default_ui`. ([see here][38])
- Split `modes` into `modes.builtin` and `modes.custom` ([see here][39]). Migrate your custom modes to `modes.custom`. And copy only the changes in the in-built modes in `modes.builtin`.
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.
@ -188,7 +188,7 @@ Else, do the following
- 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.
@ -200,7 +200,7 @@ Else, do the following
- Search for `RemoveNodeFilterFromInput` in the new config.
- Compare and probably replace the associated actions in your current config.