Archives/xplr
2
0
Fork 0
mirror of https://github.com/sayanarijit/xplr synced 2024-11-04 18:00:14 +00:00
Code Issues Packages Projects Releases Wiki Activity
8afb93f706
xplr/en/upgrade-guide.html
sayanarijit 8ace03cf80 deploy: 70cb745c9f
2022-10-28 21:16:44 +00:00

583 lines
46 KiB
HTML
Raw Blame History

<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js dark">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Upgrade Guide - xplr book</title>
<!-- Custom HTML head -->
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="A hackable, minimal, fast TUI file explorer">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff" />
<link rel="shortcut icon" href="favicon.png">
<link rel="stylesheet" href="css/variables.css">
<link rel="stylesheet" href="css/general.css">
<link rel="stylesheet" href="css/chrome.css">
<link rel="stylesheet" href="css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="fonts/fonts.css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<link rel="stylesheet" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- EthicalAds -->
<script async src="https://media.ethicalads.io/media/client/ethicalads.min.js"></script>
</head>
<body>
<!-- Provide site root to javascript -->
<script type="text/javascript">
var path_to_root = "";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "coal" : "dark";
</script>
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script type="text/javascript">
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script type="text/javascript">
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('no-js')
html.classList.remove('dark')
html.classList.add(theme);
html.classList.add('js');
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
<ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html"><strong aria-hidden="true">1.</strong> Introduction</a></li><li class="chapter-item expanded "><a href="quickstart.html"><strong aria-hidden="true">2.</strong> Quickstart</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="install.html"><strong aria-hidden="true">2.1.</strong> Install</a></li><li class="chapter-item expanded "><a href="post-install.html"><strong aria-hidden="true">2.2.</strong> Post Install</a></li></ol></li><li class="chapter-item expanded "><a href="configuration.html"><strong aria-hidden="true">3.</strong> Configuration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="general-config.html"><strong aria-hidden="true">3.1.</strong> General</a></li><li class="chapter-item expanded "><a href="node_types.html"><strong aria-hidden="true">3.2.</strong> Node Types</a></li><li class="chapter-item expanded "><a href="layouts.html"><strong aria-hidden="true">3.3.</strong> Layouts</a></li><li class="chapter-item expanded "><a href="modes.html"><strong aria-hidden="true">3.4.</strong> Modes</a></li></ol></li><li class="chapter-item expanded "><a href="concept.html"><strong aria-hidden="true">4.</strong> Concept</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="key-bindings.html"><strong aria-hidden="true">4.1.</strong> Key Bindings</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="configure-key-bindings.html"><strong aria-hidden="true">4.1.1.</strong> Configure Key Bindings</a></li><li class="chapter-item expanded "><a href="default-key-bindings.html"><strong aria-hidden="true">4.1.2.</strong> Default Key Bindings</a></li><li class="chapter-item expanded "><a href="debug-key-bindings.html"><strong aria-hidden="true">4.1.3.</strong> Debug Key Bindings</a></li></ol></li><li class="chapter-item expanded "><a href="node-type.html"><strong aria-hidden="true">4.2.</strong> Node Type</a></li><li class="chapter-item expanded "><a href="layout.html"><strong aria-hidden="true">4.3.</strong> Layout</a></li><li class="chapter-item expanded "><a href="mode.html"><strong aria-hidden="true">4.4.</strong> Mode</a></li><li class="chapter-item expanded "><a href="message.html"><strong aria-hidden="true">4.5.</strong> Message</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="messages.html"><strong aria-hidden="true">4.5.1.</strong> Full List of Messages</a></li><li class="chapter-item expanded "><a href="input-operation.html"><strong aria-hidden="true">4.5.2.</strong> Input Operation</a></li></ol></li><li class="chapter-item expanded "><a href="borders.html"><strong aria-hidden="true">4.6.</strong> Borders</a></li><li class="chapter-item expanded "><a href="style.html"><strong aria-hidden="true">4.7.</strong> Style</a></li><li class="chapter-item expanded "><a href="sorting.html"><strong aria-hidden="true">4.8.</strong> Sorting</a></li><li class="chapter-item expanded "><a href="filtering.html"><strong aria-hidden="true">4.9.</strong> Filtering</a></li><li class="chapter-item expanded "><a href="column-renderer.html"><strong aria-hidden="true">4.10.</strong> Column Renderer</a></li><li class="chapter-item expanded "><a href="lua-function-calls.html"><strong aria-hidden="true">4.11.</strong> Lua Function Calls</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="xplr.util.html"><strong aria-hidden="true">4.11.1.</strong> xplr.util</a></li></ol></li><li class="chapter-item expanded "><a href="environment-variables-and-pipes.html"><strong aria-hidden="true">4.12.</strong> Environment Variables and Pipes</a></li></ol></li><li class="chapter-item expanded "><a href="awesome-hacks.html"><strong aria-hidden="true">5.</strong> Awesome Hacks</a></li><li class="chapter-item expanded "><a href="plugin.html"><strong aria-hidden="true">6.</strong> Plugin</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="installing-plugins.html"><strong aria-hidden="true">6.1.</strong> Installing Plugins</a></li><li class="chapter-item expanded "><a href="writing-plugins.html"><strong aria-hidden="true">6.2.</strong> Writing Plugins</a></li><li class="chapter-item expanded "><a href="awesome-plugins.html"><strong aria-hidden="true">6.3.</strong> Awesome Plugins</a></li></ol></li><li class="chapter-item expanded "><a href="integration.html"><strong aria-hidden="true">7.</strong> Integration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="awesome-integrations.html"><strong aria-hidden="true">7.1.</strong> Awesome Integrations</a></li></ol></li><li class="chapter-item expanded "><a href="alternatives.html"><strong aria-hidden="true">8.</strong> Alternatives</a></li><li class="chapter-item expanded "><a href="upgrade-guide.html" class="active"><strong aria-hidden="true">9.</strong> Upgrade Guide</a></li><li class="chapter-item expanded "><a href="community.html"><strong aria-hidden="true">10.</strong> Community</a></li><li class="chapter-item expanded "><a href="contribute.html"><strong aria-hidden="true">11.</strong> Contribute</a></li></ol>
<!-- EthicalAds -->
<div
id="docs-sidebar-bottom"
class="dark flat"
data-ea-publisher="xplrdev"
data-ea-type="image"
></div>
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar-hover-placeholder"></div>
<div id="menu-bar" class="menu-bar sticky bordered">
<div class="left-buttons">
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</button>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">xplr book</h1>
<div class="right-buttons">
<a href="print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
<a href="https://github.com/sayanarijit/xplr" title="Git repository" aria-label="Git repository">
<i id="git-repository-button" class="fa fa-github"></i>
</a>
<a href="https://github.com/sayanarijit/xplr/edit/main/docs/en/src/upgrade-guide.md" title="Suggest an edit" aria-label="Suggest an edit">
<i id="git-edit-button" class="fa fa-edit"></i>
</a>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script type="text/javascript">
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<h1 id="upgrade-guide"><a class="header" href="#upgrade-guide">Upgrade Guide</a></h1>
<p>When you upgrade xplr, you might see an error like this</p>
<pre><code>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
</code></pre>
<p>All you need to do is follow the <a href="#instructions">instructions</a> starting from
your config version, all the way to the required version.</p>
<details>
<summary>Expand for more information</summary>
<p>With every update, we either implement a <code>major</code> breaking change (e.g.
deprecating or replacing messages), or a <code>minor</code> feature addition (e.g. adding
new messages) or <code>patch</code>, fixes, and optimization (e.g. performance
optimization).</p>
<p>Knowing that we use the <code>{major}.{minor}.{patch}</code> versioning format,</p>
<ul>
<li>Major version mismatch are generally incompatible. xplr will fail
with error.</li>
<li>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.</li>
<li>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.</li>
</ul>
<p>e.g.</p>
<ul>
<li><code>1.0.0</code> -&gt; <code>1.0.x</code>: Bug fix (fully compatible).</li>
<li><code>1.0.0</code> -&gt; <code>1.x.x</code>: Only backwards compatible. You can't generally use for
e.g. <code>app-1.0.0</code> with <code>config-1.1.0</code>. But vice versa is fine.</li>
<li><code>1.0.0</code> -&gt; <code>x.x.x</code>: Not compatible at all.</li>
</ul>
<p>Note that until we're <code>v1</code>, we'll be using the <code>{minor}</code> version number as
<code>{major}</code>, and the <code>{patch}</code> fix number as <code>{minor}</code> to determine
compatibility.</p>
</details>
<h3 id="instructions"><a class="header" href="#instructions">Instructions</a></h3>
<h4 id="v0194---v0200"><a class="header" href="#v0194---v0200"><a href="https://github.com/sayanarijit/xplr/releases/tag/v0.19.4">v0.19.4</a> -&gt; <a href="https://github.com/sayanarijit/xplr/releases/tag/v0.20.0">v0.20.0</a></a></h4>
<ul>
<li>BREAKING: xplr shell (<code>:!</code>) will default to null (<code>\0</code>) delimited pipes, as
opposed to newline (<code>\n</code>) delimited ones (i.e. will use <code>Call0</code> instead of
<code>Call</code>).</li>
<li>Use new messages for safer file path handling (<code>\0</code> delimited):
<ul>
<li>Call0</li>
<li>CallSilently0</li>
<li>BashExec0</li>
<li>BashExecSilently0</li>
</ul>
</li>
<li>Use new sub-commands for safer message passing:
<ul>
<li><code>-m FORMAT [ARGUMENT]...</code> / <code>--pipe-msg-in FORMAT [ARGUMENT]...</code></li>
<li><code>-M FORMAT [ARGUMENT]...</code> / <code>--print-msg-in FORMAT [ARGUMENT]...</code>
Where FORMAT is a YAML string that may contain <code>%s</code>, <code>%q</code> and <code>%%</code>
placeholders and ARGUMENT is the value per placeholder. See <code>init.lua</code>.</li>
</ul>
</li>
<li>Following hooks can be defined in the config files using an optional
<code>return { on_* = { list, of, messages }, ... }</code> statement at the end.
<ul>
<li>on_load</li>
<li>on_focus_change</li>
<li>on_directory_change</li>
</ul>
</li>
<li>Use <code>--vroot</code> to isolate navigation of an xplr session inside a specific
directory. Interaction still requires passing full path, and shell,
lua functions etc still can access paths outside vroot.</li>
<li>Use the following messages to switch vroot at runtime, or the use key
bindings available in the new builtin mode &quot;vroot&quot; (mapped to <code>:</code> <code>v</code>).
<ul>
<li>SetVroot</li>
<li>UnsetVroot</li>
<li>ToggleVroot</li>
<li>ResetVroot</li>
</ul>
</li>
<li>Use <code>$XPLR_INITIAL_PWD</code> and Lua equivalent to implement workspace like
features without using virtual root. Use keys <code>gi</code> to go to the initial
working directory from anywhere.</li>
<li>Use the convenient <code>xplr.util</code> utility functions in your Lua function calls.
See xplr.util API docs.</li>
</ul>
<h4 id="v0180---v0194"><a class="header" href="#v0180---v0194"><a href="https://github.com/sayanarijit/xplr/releases/tag/v0.18.0">v0.18.0</a> -&gt; <a href="https://github.com/sayanarijit/xplr/releases/tag/v0.19.4">v0.19.4</a></a></h4>
<ul>
<li>BREAKING: The builtin modes cannot be accessed using space separated names
anymore. Use underscore separated mode names. For e.g.
<code>SwitchModeBuiltin: create file</code> becomes <code>SwitchModeBuiltin: create_file</code> and
so on. Kindly go through your config, find and update them, or copy from the
latest <code>init.lua</code>.</li>
<li>Now you can use <code>xplr.config.general.global_key_bindings</code> to define a set of
key bindings that are available by default in every mode. e.g. <code>esc</code>
and <code>ctrl-c</code>, and remove boilerplate code from your config.</li>
<li>You can use the new builtin mode <code>go_to_path</code> which can be used for typing or
pasting paths to enter into or to focus on. Type <code>g</code> <code>p</code> to enter this mode.</li>
<li>Now you can use basic tab completion in the <code>go_to_path</code>, <code>create_file</code>,
<code>create_directory</code>, <code>rename</code> and <code>duplicate_as</code> modes.</li>
<li>Use the builtin function <code>xplr.fn.builtin.try_complete_path</code> to add easy tab
completion support into your own configuration.</li>
<li>Now you can open OSC 7 compatible terminals into the <code>xplr</code>'s current working
directory by spawning new terminal sessions via the terminal supported key
bindings.</li>
<li>Use <code>NO_COLOR</code> environment variable to disable OSC 7 compliance along with
colors.</li>
<li>If you have fully copied the default <code>init.lua</code> locally, you might want to
go through the latest improvements in <code>init.lua</code>. Specifically the <code>search</code>,
<code>filter</code> and <code>sort</code> modes. Also, search for <code>SetInputPrompt</code> and the <code>tab</code>
key bindings.</li>
<li>Since version 0.19.1, you can access uid and gid of the file owner in the Lua
API.</li>
<li>The input buffer will support more readline-like keys.
Also, added &quot;DeleteTillEnd&quot; as another cursor based &quot;InputOperation&quot; option.</li>
<li>Fixed applying regex based filters via the CLI and <code>$XPLR_PIPE_MSG_IN</code> pipe.</li>
<li>You can use the <code>prompt</code> field to define input prompt for each mode, instead
of using the <code>SetInputPrompt</code> message.</li>
<li>Since version v0.19.4, the native search will default to skim-v2 based fuzzy
matching. <code>esc</code> while in search mode will recover the initial focus. People
who prefer the regex based search, can use the <code>regex-search.xplr</code> plugin.
The following messages will be available for search based operations:
<ul>
<li>SearchFuzzy</li>
<li>SearchFuzzyFromInput</li>
<li>AcceptSearch</li>
<li>CancelSearch</li>
</ul>
</li>
<li>Since version v0.19.4, quick scrolling operations are supported using the
following messages and keys:
<ul>
<li>ScrollUp -------- page-up</li>
<li>ScrollDown ------ page-down</li>
<li>ScrollUpHalf ---- {</li>
<li>ScrollDownHalf -- }</li>
</ul>
</li>
</ul>
<p><sub>Like this project so far? <strong><a href="contribute.html">Please consider contributing</a></strong>.</sub></p>
<h4 id="v0176---v0180"><a class="header" href="#v0176---v0180"><a href="https://github.com/sayanarijit/xplr/releases/tag/v0.17.6">v0.17.6</a> -&gt; <a href="https://github.com/sayanarijit/xplr/releases/tag/v0.18.0">v0.18.0</a></a></h4>
<ul>
<li>Key binding <code>f</code> <code>r</code> and <code>f</code> <code>R</code> will now filter using regex.</li>
<li>Key binding <code>f</code> <code>backspace</code> will now remove the last filter.</li>
<li>Search mode now defaults to regex search.</li>
<li><code>Node</code> metadata in the Lua API will contain two new fields:
<ul>
<li><code>created</code></li>
<li><code>last_modified</code></li>
</ul>
</li>
<li>The last column in the files table now displays the last modification time.</li>
<li>You can now use <code>--read0</code>, <code>--write0</code> and <code>-0</code>/<code>--null</code> to read and/or print
null character delimited paths.</li>
<li>You can now the following regex filters:
<ul>
<li><code>RelativePathDoesMatchRegex</code></li>
<li><code>RelativePathDoesNotMatchRegex</code></li>
<li><code>IRelativePathDoesMatchRegex</code></li>
<li><code>IRelativePathDoesNotMatchRegex</code></li>
<li><code>AbsolutePathDoesMatchRegex</code></li>
<li><code>AbsolutePathDoesNotMatchRegex</code></li>
<li><code>IAbsolutePathDoesMatchRegex</code></li>
<li><code>IAbsolutePathDoesNotMatchRegex</code></li>
</ul>
</li>
<li>You can use a new <code>SetInputPrompt</code> to set the input prompt dynamically.</li>
<li>You can now use the following timestamp based sorters:
<ul>
<li>&quot;ByCreated&quot;</li>
<li>&quot;ByLastModified&quot;</li>
<li>&quot;ByCanonicalCreated&quot;</li>
<li>&quot;ByCanonicalLastModified&quot;</li>
<li>&quot;BySymlinkCreated&quot;</li>
<li>&quot;BySymlinkLastModified&quot;</li>
</ul>
</li>
</ul>
<h4 id="v0164---v0176"><a class="header" href="#v0164---v0176"><a href="https://github.com/sayanarijit/xplr/releases/tag/v0.16.4">v0.16.4</a> -&gt; <a href="https://github.com/sayanarijit/xplr/releases/tag/v0.17.6">v0.17.6</a></a></h4>
<ul>
<li>Deprecated <code>app.directory_buffer</code>, <code>app.history</code>, and <code>app.last_modes</code> in
the custom dynamic layout renderer context.
As of now, there's no way to access these fields in dynamic layouts. While
<code>app.history</code> and <code>app.last_modes</code> can be re-added upon request
(with justification), <code>app.directory_buffer</code> has been deprecated for good.
However, there's no change in the <code>CallLua*</code> context.</li>
<li>Set <code>xplr.config.general.hide_remaps_in_help_menu</code> to <code>true</code> to hide the
remaps in help menu.</li>
<li><code>None</code> will be serialized to <code>nil</code> in Lua.</li>
<li><code>LuaEval</code> can now return a function that will be called with the Lua Context
argument. Refer to the <code>Full List of Messages</code> doc for example.</li>
<li>From version v0.17.1, set <code>xplr.config.general.disable_debug_error_mode</code> to
<code>true</code> to disable switching to the &quot;debug error&quot; mode when startup errors
occur.</li>
<li>From version v0.17.2, you can use CLI argument <code>--print-pwd-as-result</code> for cd
on quit, and key binding <code>ctrl-d</code> to duplicate a path in the same directory
with a different name.</li>
<li>Since version v0.17.3, you can use <code>border_type</code>, <code>border_style</code> to customize
borders, and <code>enforce_bounded_index_navigation</code> to customize up/down
navigation behavior when focus is on the top or bottom node.</li>
</ul>
<h4 id="v0152---v0164"><a class="header" href="#v0152---v0164"><a href="https://github.com/sayanarijit/xplr/releases/tag/v0.15.2">v0.15.2</a> -&gt; <a href="https://github.com/sayanarijit/xplr/releases/tag/v0.16.4">v0.16.4</a></a></h4>
<ul>
<li>Deprecated <code>config.general.cursor</code>. The default terminal cursor will be used
for the time being.</li>
<li>Opening xplr inside a symlink will not resolve the path.</li>
<li>You can now replace most boilerplate configuration handling keys to send
<code>BufferInputFromKey</code>, <code>RemoveInputBufferLastCharacter</code>,
<code>RemoveInputBufferLastWord</code>, <code>SetInputBuffer = &quot;&quot;</code> etc. messages with a
single <code>UpdateInputBufferFromKey</code> message.</li>
<li>You can now pass multiple paths as command-line arguments or via stdin to
select paths, e.g. <code>xplr -- $PWD /path/to/select/1 /path/to/select/2</code>.</li>
<li>Pass <code>--force-focus</code> to focus on the first path even if it's a directory,
e.g. <code>xplr . --force-focus</code>.</li>
<li>Use new messages <code>LuaEval</code> and <code>LuaEvalSilently</code> to run Lua code without
needing to define a function. However, the <code>app</code> context won't be available.</li>
<li>You can now use new key handlers in the config:
<ul>
<li>on_alphanumeric</li>
<li>on_character</li>
<li>on_navigation</li>
<li>on_function</li>
</ul>
</li>
</ul>
<h4 id="v0147---v0152"><a class="header" href="#v0147---v0152"><a href="https://github.com/sayanarijit/xplr/releases/tag/v0.14.7">v0.14.7</a> -&gt; <a href="https://github.com/sayanarijit/xplr/releases/tag/v0.15.2">v0.15.2</a></a></h4>
<ul>
<li>Deprecated <code>config</code> field from <code>CallLua</code> argument. Use the globally available
<code>xplr.config</code> instead.</li>
<li><code>xplr.config.general.disable_recover_mode</code> has been deprecated. Use
<code>xplr.config.general.enable_recover_mode</code> instead.</li>
<li>Use <code>xplr.config.general.focus_selection_ui</code> to highlight selected files
under focus differently than files under focus that are not selected.</li>
<li>Use <code>PopModeKeepingInputBuffer</code>, and SwitchMode alternatives to switching to
different modes without resetting the input buffer.</li>
<li>Use the new <code>CustomContent</code> layout option to render custom content.</li>
<li>Use the new <code>layout</code> field in a mode to define custom layout for a specific
mode.</li>
<li>Library users please refer to the latest API docs and examples.</li>
</ul>
<h4 id="v0137---v0147"><a class="header" href="#v0137---v0147"><a href="https://github.com/sayanarijit/xplr/releases/tag/v0.13.7">v0.13.7</a> -&gt; <a href="https://github.com/sayanarijit/xplr/releases/tag/v0.14.7">v0.14.7</a></a></h4>
<ul>
<li>macOS users need to place their config file (<code>init.lua</code>) in
<code>$HOME/.config/xplr/</code> or <code>/etc/xplr/</code>.</li>
<li>Library users please refer to the latest API docs.</li>
<li>Check out the new messages: <code>{Start|Stop|Toggle}Fifo</code>. These enable support
for <a href="https://github.com/sayanarijit/xplr/pull/229#issue-662426960">FIFO based file previews</a>.</li>
<li>You can disable the recover mode using <code>config.general.disable_recover_mode = true</code>.</li>
<li>Try running <code>xplr --help</code>. Yes, CLI has been implemented.</li>
<li>Since version <code>v0.14.3</code>, <code>StartFifo</code> and <code>ToggleFifo</code> will write to the FIFO
path when called. So, there's no need to pipe the focus path explicitely.</li>
<li>Since version <code>v0.14.3</code>, general config <code>xplr.config.start_fifo</code> is available
which can be set to a file path to start a fifo when xplr starts.</li>
<li>Since version <code>v0.14.4</code>, <code>$XPLR_SESSION_PATH</code> can be used to dump session
related data.</li>
<li>Since version <code>v0.14.6</code>, the <code>-C</code> or <code>--extra-config</code> CLI argument is
available.</li>
</ul>
<h4 id="v0121---v0137"><a class="header" href="#v0121---v0137"><a href="https://github.com/sayanarijit/xplr/releases/tag/v0.12.1">v0.12.1</a> -&gt; <a href="https://github.com/sayanarijit/xplr/releases/tag/v0.13.7">v0.13.7</a></a></h4>
<ul>
<li>Lua functions called using <a href="https://docs.rs/xplr/latest/xplr/app/enum.ExternalMsg.html#variant.CallLua"><code>CallLua</code></a> and <a href="https://docs.rs/xplr/latest/xplr/app/enum.ExternalMsg.html#variant.CallLuaSilently"><code>CallLuaSilently</code></a> messages will receive <a href="https://docs.rs/xplr/latest/xplr/app/struct.CallLuaArg.html"><code>CallLuaArg</code></a> object as the function argument (instead of the <a href="https://docs.rs/xplr/latest/xplr/app/struct.App.html"><code>App</code></a> object).</li>
<li>Each <code>node_types</code> config will inherit defaults from matching less specifig <code>node_types</code> config and overwrite them.</li>
<li>Since version <code>v0.13.2</code>, you don't need to use/send <code>Refresh</code> anymore. It will be auto-handled by xplr.</li>
</ul>
<h4 id="v0111---v0121"><a class="header" href="#v0111---v0121"><a href="https://github.com/sayanarijit/xplr/releases/tag/v0.11.1">v0.11.1</a> -&gt; <a href="https://github.com/sayanarijit/xplr/releases/tag/v0.12.1">v0.12.1</a></a></h4>
<ul>
<li><code>xplr.config.node_types.mime_essence</code> has split into type and subtype. Hence, instead of <code>xplr.config.node_types.mime_essence[&quot;text/plain&quot;] = ..</code> use <code>xplr.config.node_types.mime_essence[&quot;text&quot;] = { plain = .. }</code>.</li>
<li>You can also define <code>xplr.config.node_types.mime_essence[&quot;text&quot;][&quot;*&quot;]</code> that will match all text types (<code>text/*</code>).</li>
</ul>
<h4 id="v0102---v0111"><a class="header" href="#v0102---v0111"><a href="https://github.com/sayanarijit/xplr/releases/tag/v0.10.2">v0.10.2</a> -&gt; <a href="https://github.com/sayanarijit/xplr/releases/tag/v0.11.1">v0.11.1</a></a></h4>
<ul>
<li><code>remaps:</code> has been removed to avoid confusion. Use lua assignments instead.
For e.g.
<pre><code>xplr.config.modes.builtin.default.key_bindings.on_key[&quot;v&quot;] = xplr.config.modes.builtin.default.key_bindings.on_key.space
</code></pre>
</li>
</ul>
<h4 id="v091---v0102"><a class="header" href="#v091---v0102"><a href="https://github.com/sayanarijit/xplr/releases/tag/v0.9.1">v0.9.1</a> -&gt; <a href="https://github.com/sayanarijit/xplr/releases/tag/v0.10.2">v0.10.2</a></a></h4>
<ul>
<li><a href="https://github.com/sayanarijit/xplr/blob/85696ded7a/src/config.yml"><code>config.yml</code></a> has been fully replaced with <a href="https://github.com/sayanarijit/xplr/blob/main/src/init.lua"><code>init.lua</code></a>. If you have a lot of customization in your <code>config.yml</code>, <a href="https://github.com/sayanarijit/xplr-yml2lua">xplr-yml2lua</a> can help you with migrating it to <code>init.lua</code>.</li>
<li><code>Handlebars</code> templates has been replaced with <a href="https://github.com/sayanarijit/xplr/blob/bfdb7736b99bc3c5ae53e7d621ba0e7ca2299b14/src/init.lua#L2005-L2064">Lua functions</a>. You can either remove the customizations or overwrite the functions accordingly.</li>
<li>Added new messages <code>CallLua</code> and <code>CallLuaSilently</code> to call lua functions. The app state will be passed as input to the functions, and the returned messages will be handled by xplr. <code>CallLua</code> and <code>CallLuaSilently</code> are more flexible (and probably faster) alternatives to <code>Call</code>, <code>CallSilently</code>, <code>BashExec</code> and <code>BashExecSilently</code>. <a href="https://github.com/sayanarijit/xplr/pull/177#issue-650643573">e.g.</a></li>
</ul>
<h4 id="v090---v091"><a class="header" href="#v090---v091"><a href="https://github.com/sayanarijit/xplr/releases/tag/v0.9.0">v0.9.0</a> -&gt; <a href="https://github.com/sayanarijit/xplr/releases/tag/v0.9.1">v0.9.1</a></a></h4>
<ul>
<li>You can now set <code>remaps: {key: null}</code> to un-map a key.</li>
<li><code>gx</code> will open the item under focus.</li>
<li>New key map <code>:sx</code> will open the selected items.</li>
</ul>
<h4 id="v080---v090"><a class="header" href="#v080---v090"><a href="https://github.com/sayanarijit/xplr/releases/tag/v0.8.0">v0.8.0</a> -&gt; <a href="https://github.com/sayanarijit/xplr/releases/tag/v0.9.0">v0.9.0</a></a></h4>
<p>Your previous config should mostly work fine. However, in case you are using <code>SwitchMode</code> heavily in your custom config, follow along.</p>
<ul>
<li>Introduced new message <code>PopMode</code>. You might want to use this message instead of <code>SwitchMode*</code> when returning back to the previous mode.</li>
<li>After using (the group of) <code>PopMode</code> and <code>SwitchMode*</code> messages, you are now required to <code>Refresh</code> manually to avoid the UI lag.</li>
<li>Pressing any invalid key will now lead you to the <code>recover</code> mode and will protect you from typing further invalid keys. Press <code>esc</code> to escape the <code>recover</code> mode.</li>
<li>Introduced new message <code>LogWarning</code>, similar to other <code>Log*</code> messages.</li>
<li>Creating files and directories has been optimized for batch creation.</li>
</ul>
<h4 id="v072---v080"><a class="header" href="#v072---v080"><a href="https://github.com/sayanarijit/xplr/releases/tag/v0.7.2">v0.7.2</a> -&gt; <a href="https://github.com/sayanarijit/xplr/releases/tag/v0.8.0">v0.8.0</a></a></h4>
<p>If you have made changes to the config file,</p>
<ul>
<li>Replace message <code>Explore</code> with <code>ExplorePwd</code> or <code>ExplorePwdAsync</code> or probably <code>ExploreParentsAsync</code>.</li>
<li>Pipe <code>$XPLR_PIPE_FOCUS_OUT</code> has been removed. Use <code>$XPLR_FOCUS_PATH</code> env var instead.</li>
<li>You might want to review your path escaping logics. For e.g. use <code>echo FocusPath: &quot;'&quot;$PWD&quot;'&quot; &gt;&gt; $PIPE</code> instead of <code>echo &quot;FocusPath: $PWD&quot; &gt;&gt; $PIPE</code>.</li>
</ul>
<h4 id="v070---v072"><a class="header" href="#v070---v072"><a href="https://github.com/sayanarijit/xplr/releases/tag/v0.7.0">v0.7.0</a> -&gt; <a href="https://github.com/sayanarijit/xplr/releases/tag/v0.7.2">v0.7.2</a></a></h4>
<ul>
<li>Just update the <code>version</code> in your config file.</li>
<li>For version &gt;= <code>v0.7.1</code>, you might want to free up or remap the <code>tab</code> key in <code>search</code> mode to enable easy selection during search.</li>
</ul>
<h4 id="v060---v070"><a class="header" href="#v060---v070"><a href="https://github.com/sayanarijit/xplr/releases/tag/v0.6.0">v0.6.0</a> -&gt; <a href="https://github.com/sayanarijit/xplr/releases/tag/v0.7.0">v0.7.0</a></a></h4>
<p>If you haven't made any changes in the config file, you should be fine just updating the version number. Else,</p>
<ul>
<li>You can make the <code>Table: ...</code>, <code>InputAndLogs: ...</code> layout values null and define the common properties in the <code>general.panel_ui</code> instead.</li>
</ul>
<h4 id="v0513---v060"><a class="header" href="#v0513---v060"><a href="https://github.com/sayanarijit/xplr/releases/tag/v0.5.13">v0.5.13</a> -&gt; <a href="https://github.com/sayanarijit/xplr/releases/tag/v0.6.0">v0.6.0</a></a></h4>
<p>If you haven't made any changes in the config file, you should be fine just updating the version number. Else,</p>
<ul>
<li>Rename <code>add_modifier: {bits: 1}</code> to <code>add_modifiers: [Bold]</code>, <code>sub_modifier: {bits: 1}</code> to <code>sub_modifiers: [Bold]</code> and so on.</li>
<li>Rename <code>percentage: 10</code> to <code>Percentage: 10</code>, <code>ratio: 1</code> to <code>Ratio: 1</code> and so on.</li>
<li>You might want to free up or remap the <code>ctrl-w</code> key binding in <code>default</code> mode to enable layout switching.</li>
</ul>
<p>Optionally, checkout this new theme to learn more about what's new.</p>
<h4 id="v050---v0513"><a class="header" href="#v050---v0513"><a href="https://github.com/sayanarijit/xplr/releases/tag/v0.5.0">v0.5.0</a> -&gt; <a href="https://github.com/sayanarijit/xplr/releases/tag/v0.5.13">v0.5.13</a></a></h4>
<ul>
<li>Just update the <code>version</code> in your config file.</li>
<li>For versions &gt;= <code>v0.5.8</code>, you can set <code>$OPENER</code> env var to declare a global GUI file opener (to open files using keys <code>gx</code>).</li>
<li>You might also want to update other mappings to handle files with names starting with <code>-</code> (hiphen). For example, instead of <code>rm ${filename}</code> use <code>rm -- ${filename}</code>. Same goes for <code>cp</code>, <code>mv</code>, <code>cat</code>, <code>touch</code> etc.</li>
<li>For version &gt;= <code>v0.5.13</code>, you might want to use the more specific <code>SwitchModeBuiltin</code> and <code>SwitchModeCustom</code> messages instead of the general <code>SwitchMode</code> message.</li>
</ul>
<h4 id="v043---v050"><a class="header" href="#v043---v050"><a href="https://github.com/sayanarijit/xplr/releases/tag/v0.4.3">v0.4.3</a> -&gt; <a href="https://github.com/sayanarijit/xplr/releases/tag/v0.5.0">v0.5.0</a></a></h4>
<p>If you haven't have any changes in the config file, you should be fine just updating the version number.</p>
<p>Else do the following</p>
<ul>
<li>Replace <code>{RelativePathIs, case_sensitive: true}</code> with <code>RelativePathIs</code>.</li>
<li>Replace <code>{RelativePathIs, case_sensitive: false}</code> with <code>IRelativePathIs</code>.</li>
<li>Do the same with other filters you are using.</li>
<li>You might want to update your <code>backspace</code> handling to use the <code>RemoveInputBufferLastCharacter</code> message.</li>
<li>You might want to free-up <code>f</code>, <code>s</code>, <code>ctrl-r</code> and <code>ctrl-u</code> key bindings in the default mode, or remap them.</li>
<li>You might want to use the new UI variables.</li>
<li>Update your config version to <code>v0.5.0</code>.</li>
</ul>
<h4 id="v042---v043"><a class="header" href="#v042---v043"><a href="https://github.com/sayanarijit/xplr/releases/tag/v0.4.2">v0.4.2</a> -&gt; <a href="https://github.com/sayanarijit/xplr/releases/tag/v0.4.3">v0.4.3</a></a></h4>
<p>If you have customized <code>general.table.row.cols</code>, you might want to <a href="https://github.com/sayanarijit/xplr/blob/af1cda5762/src/config.yml#L46-L48">update it</a> to use the new variables with better symlink support.</p>
<h4 id="v041---v042"><a class="header" href="#v041---v042"><a href="https://github.com/sayanarijit/xplr/releases/tag/v0.4.1">v0.4.1</a> -&gt; <a href="https://github.com/sayanarijit/xplr/releases/tag/v0.4.2">v0.4.2</a></a></h4>
<p>In case you have mapped the keys <code>q</code>, <code>ctrl-i</code> and <code>ctrl-o</code>, you may want to revisit the default mode key bindings and remap accordingly to use the new functionalities.</p>
<h4 id="v0313---v041"><a class="header" href="#v0313---v041"><a href="https://github.com/sayanarijit/xplr/releases/tag/v0.3.13">v0.3.13</a> -&gt; <a href="https://github.com/sayanarijit/xplr/releases/tag/v0.4.1">v0.4.1</a></a></h4>
<p>A lot has changed (apologies). But I promise from now on, upgrading will be much less painful (thanks to <a href="https://github.com/maximbaz">@maximbaz</a>'s valuable <a href="https://github.com/sayanarijit/xplr/issues/45#issue-854447104">inputs</a> and <a href="https://github.com/sayanarijit/xplr/pull/47">code reviews</a>).</p>
<p>So, to start with the upgrade, let's remove everything from your config file except the <code>version</code> field and your custom modifications. If <code>version</code> is the only thing remaining, update it to <code>v0.4.1</code> and you are done.</p>
<p>Else, do the following</p>
<ul>
<li>Rename <code>general.focused_ui</code> to <code>general.focus_ui</code> (<a href="https://github.com/sayanarijit/xplr/blob/055c1083d6/src/config.yml#L124">see here</a>).</li>
<li>Rename <code>filetypes</code> to <code>node_types</code>. (<a href="https://github.com/sayanarijit/xplr/blob/055c1083d6/src/config.yml#L145">see here</a>)</li>
<li>Rename <code>custom</code> field to <code>meta</code>. (<a href="https://github.com/sayanarijit/xplr/blob/055c1083d6/src/config.yml#L154-L155">see here</a>)</li>
<li>Move <code>icon</code> to <code>meta.icon</code>. (<a href="https://github.com/sayanarijit/xplr/blob/055c1083d6/src/config.yml#L45">see here</a>)</li>
<li>Rename <code>normal_ui</code> to <code>default_ui</code>. (<a href="https://github.com/sayanarijit/xplr/blob/055c1083d6/src/config.yml#L114">see here</a>)</li>
<li>Split <code>modes</code> into <code>modes.builtin</code> and <code>modes.custom</code> (<a href="https://github.com/sayanarijit/xplr/blob/055c1083d6/src/config.yml#L180-L181">see here</a>). Migrate your custom modes to <code>modes.custom</code>. And copy only the changes in the in-built modes in <code>modes.builtin</code>.</li>
<li>Finally, update the <code>version</code> to <code>v0.4.1</code>.</li>
</ul>
<h4 id="v038---v0313"><a class="header" href="#v038---v0313"><a href="https://github.com/sayanarijit/xplr/releases/tag/v0.3.8">v0.3.8</a> -&gt; <a href="https://github.com/sayanarijit/xplr/releases/tag/v0.3.13">v0.3.13</a></a></h4>
<p>Your current config should work fine. However, you might want to replace some <code>Call</code> and <code>BashExec</code> messages with <code>CallSilently</code> and <code>BashExecSilently</code> to remove the flickering of the screen.</p>
<p>If you haven't made any changes to the configuration, you can delete and regenerate it.</p>
<p>Else, do the following</p>
<ul>
<li>Check the new default config by temporarily removing your current config (with backup) and dumping the new config.</li>
<li>Search for <code>Call</code> and <code>BashExec</code> in the new config.</li>
<li>Compare and probably replace the associated actions in your current config</li>
</ul>
<h4 id="v030---v038"><a class="header" href="#v030---v038"><a href="https://github.com/sayanarijit/xplr/releases/tag/v0.3.0">v0.3.0</a> -&gt; <a href="https://github.com/sayanarijit/xplr/releases/tag/v0.3.8">v0.3.8</a></a></h4>
<p>Your current config should work fine. However, you might want to replace some <code>ResetNodeFilters</code> messages with <code>RemoveNodeFilter</code> and <code>RemoveNodeFilterFromInput</code> to get a better search and filter experience.</p>
<p>If you haven't made any changes to the configuration, you can delete and regenerate it.</p>
<p>Else, do the following</p>
<ul>
<li>Check the new default config by temporarily removing your current config (with backup) and dumping the new config.</li>
<li>Search for <code>RemoveNodeFilterFromInput</code> in the new config.</li>
<li>Compare and probably replace the associated actions in your current config.</li>
</ul>
<h4 id="v0214---v030"><a class="header" href="#v0214---v030">v0.2.14 -&gt; <a href="https://github.com/sayanarijit/xplr/releases/tag/v0.3.0">v0.3.0</a></a></h4>
<p>If you haven't made any changes to the configuration, you can delete and regenerate it.</p>
<p>Else do the following:</p>
<ul>
<li><code>$XPLR_APP_YAML</code> has been removed. You can use <code>Debug</code> to export the app state.</li>
<li><code>$XPLR_RESULT</code> has been ported to file <code>$XPLR_PIPE_RESULT_OUT</code>. Use <code>cat</code> instead of <code>echo</code>, <code>&lt;</code> instead of <code>&lt;&lt;&lt;</code> etc.</li>
<li><code>$XPLR_GLOBAL_HELP_MENU</code> has been ported to
file <code>$XPLR_PIPE_GLOBAL_HELP_MENU_OUT</code>. Use <code>cat</code> instead of <code>echo</code>, <code>&lt;</code> instead of <code>&lt;&lt;&lt;</code> etc.</li>
<li><code>$XPLR_DIRECTORY_NODES</code> has been ported to
file <code>$XPLR_PIPE_DIRECTORY_NODES_OUT</code>. Use <code>cat</code> instead of <code>echo</code>, <code>&lt;</code> instead of <code>&lt;&lt;&lt;</code> etc.</li>
<li><code>$XPLR_LOGS</code> has been ported to file <code>$XPLR_PIPE_LOGS_OUT</code>. Use <code>cat</code> instead of <code>echo</code>, <code>&lt;</code> instead of <code>&lt;&lt;&lt;</code> etc.</li>
<li><code>$XPLR_PIPE_RESULT</code> has been ported to file <code>$XPLR_PIPE_RESULT_OUT</code>. Use <code>cat</code> instead of <code>echo</code>, <code>&lt;</code> instead of <code>&lt;&lt;&lt;</code> etc.</li>
<li>Finally, update the <code>version</code> in your config file.</li>
</ul>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="alternatives.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="community.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a rel="prev" href="alternatives.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="community.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<script type="text/javascript">
window.playground_copyable = true;
</script>
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
<script src="book.js" type="text/javascript" charset="utf-8"></script>
<!-- Custom JS scripts -->
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink