PageSourceSearch

https://xplr.dev/en/introduction

html xplr.dev collected 2026-09-25 21:30:46 UTC 21,255 bytes, 318 lines download raw bytes

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 &amp; 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.