1<!DOCTYPE HTML> 2<html lang="en" class="dark" dir="ltr"> 3 <head> 4 <!-- Book generated using mdBook --> 5 <meta charset="UTF-8"> 6 <title>Introduction - xplr book</title> 7 8 9 <!-- Custom HTML head --> 10 11 <meta name="description" content="A hackable, minimal, fast TUI file explorer"> 12 <meta name="viewport" content="width=device-width, initial-scale=1"> 13 <meta name="theme-color" content="#ffffff"> 14 15 <link rel="shortcut icon" href="favicon.png"> 16 <link rel="stylesheet" href="css/variables.css"> 17 <link rel="stylesheet" href="css/general.css"> 18 <link rel="stylesheet" href="css/chrome.css"> 19 <link rel="stylesheet" href="css/print.css" media="print"> 20 21 <!-- Fonts --> 22 <link rel="stylesheet" href="FontAwesome/css/font-awesome.css"> 23 <link rel="stylesheet" href="fonts/fonts.css"> 24 25 <!-- Highlight.js Stylesheets --> 26 <link rel="stylesheet" href="highlight.css"> 27 <link rel="stylesheet" href="tomorrow-night.css"> 28 <link rel="stylesheet" href="ayu-highlight.css"> 29 30 <!-- Custom theme stylesheets --> 31 32 33 <!-- EthicalAds --> 34
34<script async src="https://media.ethicalads.io/media/client/ethicalads.min.js"></script>
34 35 </head> 36 <body class="sidebar-visible no-js"> 37 <div id="body-container"> 38 <!-- Provide site root to javascript --> 39
39<script> 40 var path_to_root = ""; 41 var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "coal" : "dark"; 42 </script>
42 43 44 <!-- Work around some values being stored in localStorage wrapped in quotes --> 45
45<script> 46 try { 47 var theme = localStorage.getItem('mdbook-theme'); 48 var sidebar = localStorage.getItem('mdbook-sidebar'); 49 50 if (theme.startsWith('"') && theme.endsWith('"')) { 51 localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1)); 52 } 53 54 if (sidebar.startsWith('"') && sidebar.endsWith('"')) { 55 localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1)); 56 } 57 } catch (e) { } 58 </script>
58 59 60 <!-- Set the theme before any content is loaded, prevents flash --> 61
61<script> 62 var theme; 63 try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { } 64 if (theme === null || theme === undefined) { theme = default_theme; } 65 var html = document.querySelector('html'); 66 html.classList.remove('dark') 67 html.classList.add(theme); 68 var body = document.querySelector('body'); 69 body.classList.remove('no-js') 70 body.classList.add('js'); 71 </script>
71 72 73 <input type="checkbox" id="sidebar-toggle-anchor" class="hidden"> 74 75 <!-- Hide / unhide sidebar before it is displayed --> 76
76<script> 77 var body = document.querySelector('body'); 78 var sidebar = null; 79 var sidebar_toggle = document.getElementById("sidebar-toggle-anchor"); 80 if (document.body.clientWidth >= 1080) { 81 try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { } 82 sidebar = sidebar || 'visible'; 83 } else { 84 sidebar = 'hidden'; 85 } 86 sidebar_toggle.checked = sidebar === 'visible'; 87 body.classList.remove('sidebar-visible'); 88 body.classList.add("sidebar-" + sidebar); 89 </script>
89 90 91 <nav id="sidebar" class="sidebar" aria-label="Table of contents"> 92 <div class="sidebar-scrollbox"> 93 <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html" class="active"><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="sum-type.html"><strong aria-hidden="true">4.1.</strong> Sum Type</a></li><li class="chapter-item expanded "><a href="key-bindings.html"><strong aria-hidden="true">4.2.</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.2.1.</strong> Configure Key Bindings</a></li><li class="chapter-item expanded "><a href="default-key-bindings.html"><strong aria-hidden="true">4.2.2.</strong> Default Key Bindings</a></li><li class="chapter-item expanded "><a href="debug-key-bindings.html"><strong aria-hidden="true">4.2.3.</strong> Debug Key Bindings</a></li></ol></li><li class="chapter-item expanded "><a href="node-type.html"><strong aria-hidden="true">4.3.</strong> Node Type</a></li><li class="chapter-item expanded "><a href="layout.html"><strong aria-hidden="true">4.4.</strong> Layout</a></li><li class="chapter-item expanded "><a href="mode.html"><strong aria-hidden="true">4.5.</strong> Mode</a></li><li class="chapter-item expanded "><a href="message.html"><strong aria-hidden="true">4.6.</strong> Message</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="messages.html"><strong aria-hidden="true">4.6.1.</strong> Full List of Messages</a></li><li class="chapter-item expanded "><a href="input-operation.html"><strong aria-hidden="true">4.6.2.</strong> Input Operation</a></li></ol></li><li class="chapter-item expanded "><a href="borders.html"><strong aria-hidden="true">4.7.</strong> Borders</a></li><li class="chapter-item expanded "><a href="style.html"><strong aria-hidden="true">4.8.</strong> Style</a></li><li class="chapter-item expanded "><a href="searching.html"><strong aria-hidden="true">4.9.</strong> Searching</a></li><li class="chapter-item expanded "><a href="sorting.html"><strong aria-hidden="true">4.10.</strong> Sorting</a></li><li class="chapter-item expanded "><a href="filtering.html"><strong aria-hidden="true">4.11.</strong> Filtering</a></li><li class="chapter-item expanded "><a href="column-renderer.html"><strong aria-hidden="true">4.12.</strong> Column Renderer</a></li><li class="chapter-item expanded "><a href="lua-function-calls.html"><strong aria-hidden="true">4.13.</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.13.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.14.</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"><strong aria-hidden="true">9.</strong> Upgrade Guide</a></li></ol> 94 95 <!-- EthicalAds --> 96 <div 97 id="docs-sidebar-bottom" 98 class="dark flat" 99 data-ea-publisher="xplrdev" 100 data-ea-type="image" 101 ></div> 102 </div> 103 <div id="sidebar-resize-handle" class="sidebar-resize-handle"> 104 <div class="sidebar-resize-indicator"></div> 105 </div> 106 </nav> 107 108 <!-- Track and set sidebar scroll position --> 109
109<script> 110 var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox'); 111 sidebarScrollbox.addEventListener('click', function(e) { 112 if (e.target.tagName === 'A') { 113 sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop); 114 } 115 }, { passive: true }); 116 var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll'); 117 sessionStorage.removeItem('sidebar-scroll'); 118 if (sidebarScrollTop) { 119 // preserve sidebar scroll position when navigating via links within sidebar 120 sidebarScrollbox.scrollTop = sidebarScrollTop; 121 } else { 122 // scroll sidebar to current active section when navigating via "next/previous chapter" buttons 123 var activeSection = document.querySelector('#sidebar .active'); 124 if (activeSection) { 125 activeSection.scrollIntoView({ block: 'center' }); 126 } 127 } 128 </script>
128 129 130 <div id="page-wrapper" class="page-wrapper"> 131 132 <div class="page"> 133 <div id="menu-bar-hover-placeholder"></div> 134 <div id="menu-bar" class="menu-bar sticky"> 135 <div class="left-buttons"> 136 <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar"> 137 <i class="fa fa-bars"></i> 138 </label> 139 <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"> 140 <i class="fa fa-paint-brush"></i> 141 </button> 142 <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu"> 143 <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li> 144 <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li> 145 <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li> 146 <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li> 147 <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li> 148 </ul> 149 <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"> 150 <i class="fa fa-search"></i> 151 </button> 152 </div> 153 154 <h1 class="menu-title">xplr book</h1> 155 156 <div class="right-buttons"> 157 <a href="print.html" title="Print this book" aria-label="Print this book"> 158 <i id="print-button" class="fa fa-print"></i> 159 </a> 160 <a href="https://github.com/sayanarijit/xplr" title="Git repository" aria-label="Git repository"> 161 <i id="git-repository-button" class="fa fa-github"></i> 162 </a> 163 <a href="https://github.com/sayanarijit/xplr/edit/main/docs/en/src/introduction.md" title="Suggest an edit" aria-label="Suggest an edit"> 164 <i id="git-edit-button" class="fa fa-edit"></i> 165 </a> 166 167 </div> 168 </div> 169 170 <div id="search-wrapper" class="hidden"> 171 <form id="searchbar-outer" class="searchbar-outer"> 172 <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header"> 173 </form> 174 <div id="searchresults-outer" class="searchresults-outer hidden"> 175 <div id="searchresults-header" class="searchresults-header"></div> 176 <ul id="searchresults"> 177 </ul> 178 </div> 179 </div> 180 181 <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM --> 182
182<script> 183 document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible'); 184 document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible'); 185 Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) { 186 link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1); 187 }); 188 </script>
188 189 190 <div id="content" class="content"> 191 <main> 192 <h1 id="introduction"><a class="header" href="#introduction">Introduction</a></h1> 193<p>xplr is a terminal UI based file explorer that aims to increase our terminal 194productivity by being a flexible, interactive orchestrator for the ever growing 195awesome command-line utilities that work with the file-system.</p> 196<p>To achieve its goal, xplr strives to be a fast, minimal and more importantly, 197hackable file explorer.</p> 198<p>xplr is not meant to be a replacement for the standard shell commands or the 199GUI file managers. Rather, it aims to <a href="awesome-plugins.html#integration">integrate them all</a> and expose an 200intuitive, scriptable, <a href="configure-key-bindings.html">keyboard controlled</a>, 201<a href="layouts.html">real-time visual interface</a>, also being an ideal candidate for <a href="awesome-integrations.html">further 202integration</a>, enabling you to achieve insane terminal productivity.</p> 203<h2 id="concept"><a class="header" href="#concept">Concept</a></h2> 204<h3 id="hackable"><a class="header" href="#hackable">Hackable</a></h3> 205<p>xplr is built with configurability in mind. So it allows you to perform a vast 206set of operations and make it look and behave just the way you want.</p> 207<p>A few things you can do with the xplr configuration</p> 208<ul> 209<li><a href="awesome-hacks.html">Hacks</a></li> 210<li><a href="awesome-plugins.html">Plugins</a></li> 211<li><a href="awesome-integrations.html">Integrations</a></li> 212</ul> 213<h3 id="fast"><a class="header" href="#fast">Fast</a></h3> 214<p>Although speed is not the primary concern, xplr is already fast enough so that 215you can take it out for a walk into your <code>node_modules</code> or <code>/nix/store</code> any 216time you want, and it will only get faster. Still, if you feel like it's 217somehow making you slow, just report it. Most probably we're just waiting for 218someone to complain.</p> 219<p><strong>Tip:</strong> A quick and easy way to optimize the UI rendering is reducing the 220number of columns in the table.</p> 221<h3 id="minimal"><a class="header" href="#minimal">Minimal</a></h3> 222<p>xplr is being referred to as a <em>File Explorer</em>, not a <em>File Manager</em>. This 223is because at the core, xplr is only an explorer, and <a href="https://github.com/sayanarijit/xplr/blob/main/src/init.lua">outsources</a> the file 224management operations to external commands. This helps xplr stay minimal, and 225focus only on doing what it does best.</p> 226<p>So, just like speed, minimalism isn't as as aggressively pursued as 227hackability. xplr simply prefers to stay minimal and looks for the opportunity 228to lose some kb if it makes sense.</p> 229<h2 id="features"><a class="header" href="#features">Features</a></h2> 230<p>Some of the coolest features xplr provide beside the basic stuff:</p> 231<ul> 232<li><a href="https://github.com/sayanarijit/xplr/discussions/183">Embedded LuaJIT</a> for portability and extensibility.</li> 233<li><a href="messages.html">A simple modal system based on message passing</a> to control xplr session 234using: 235<ul> 236<li><a href="configure-key-bindings.html">Keyboard inputs</a></li> 237<li><a href="environment-variables-and-pipes.html">Shell Commands</a></li> 238<li><a href="lua-function-calls.html">Lua Functions</a></li> 239<li><a href="configuration.html#hooks">Hooks</a></li> 240</ul> 241</li> 242<li>Easy, typesafe message passing with <code>-m MSG</code> or <code>-M MSG</code> subcommands.</li> 243<li><a href="https://github.com/sayanarijit/xplr/pull/397">Readline-like input buffer</a> with customizable behavior to read user 244inputs.</li> 245<li><a href="modes.html#xplrconfigmodesbuiltinrecover">Switchable recover mode</a> that saves you from doing unwanted things when 246in a hurry.</li> 247<li><a href="layouts.html">Customizable layouts</a> with built-in panels. For e.g. 248<ul> 249<li><strong>Selection list</strong> to show you the selected paths in real-time.</li> 250<li><strong>Help menu</strong> to show you the available keys bindings in each mode.</li> 251<li><strong>Input & logs</strong> to read input and display logs.</li> 252<li><strong>Filter and sort pipeline</strong> to show you the applied filters and sorters.</li> 253</ul> 254</li> 255<li><a href="node_types.html">Custom file properties</a> with custom colors can be displayed in the table.</li> 256<li><a href="messages.html#startfifo">FIFO manager</a> to manage a FIFO file that can be used to 257<a href="https://github.com/sayanarijit/xplr/pull/229">integrate with previewers</a>.</li> 258<li><a href="messages.html#virtual-root">Virtual root</a> with <code>--vroot</code> and <code>:v</code> key bindings.</li> 259<li><strong>Different quit options:</strong> 260<ul> 261<li>Quit with success without any output (<code>q</code>).</li> 262<li>Quit with success and the result printed on stdout (<code>enter</code>).</li> 263<li>Quit with success and the present working directory printed on stdout 264(<code>:</code> <code>q</code> <code>p</code>).</li> 265<li>Quit with success and the path under focus printed on stdout 266(<code>:</code> <code>q</code> <code>f</code>).</li> 267<li>Quit with success and the selection printed on stdout 268(<code>:</code> <code>q</code> <code>s</code>).</li> 269<li>Quit with failure (<code>ctrl-c</code>).</li> 270</ul> 271</li> 272</ul> 273 274 </main> 275 276 <nav class="nav-wrapper" aria-label="Page navigation"> 277 <!-- Mobile navigation buttons --> 278 279 <a rel="next prefetch" href="quickstart.html" class="mobile-nav-chapter
279s next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right"> 280 <i class="fa fa-angle-right"></i> 281 </a> 282 283 <div style="clear: both"></div> 284 </nav> 285 </div> 286 </div> 287 288 <nav class="nav-wide-wrapper" aria-label="Page navigation"> 289 290 <a rel="next prefetch" href="quickstart.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right"> 291 <i class="fa fa-angle-right"></i> 292 </a> 293 </nav> 294 295 </div> 296 297 298 299 300
300<script> 301 window.playground_copyable = true; 302 </script>
302 303 304 305
305<script src="elasticlunr.min.js"></script>
305 306
306<script src="mark.min.js"></script>
306 307
307<script src="searcher.js"></script>
307 308 309
309<script src="clipboard.min.js"></script>
309 310
310<script src="highlight.js"></script>
310 311
311<script src="book.js"></script>
311 312 313 <!-- Custom JS scripts --> 314 315 316 </div> 317 <!-- Cloudflare Pages Analytics -->
vendor: 99 bytes, line 317
317<script defer src='https://static.cloudflareinsights.com/beacon.min.js' data-cf-beacon='{"token": "
3178bfbf0ee75264eee8127fff6987fdc7d
vendor: 13 bytes, line 317
317"}'></script>
317<!-- Cloudflare Pages Analytics --></body> 318</html>
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.