From 5e20eea349acc10c8455a5ca2c36fbbf5393f54c Mon Sep 17 00:00:00 2001 From: Arijit Basu Date: Sat, 5 Feb 2022 12:51:31 +0530 Subject: [PATCH] Update docs --- README.md | 23 +- docs/en/src/SUMMARY.md | 2 + docs/en/src/awesome-hacks.md | 321 ++++++++++++++++++++++++++++ docs/en/src/awesome-integrations.md | 21 +- docs/en/src/awesome-plugins.md | 19 +- docs/en/src/introduction.md | 125 +++++------ 6 files changed, 416 insertions(+), 95 deletions(-) create mode 100644 docs/en/src/awesome-hacks.md diff --git a/README.md b/README.md index 8fab5a4..6f389af 100644 --- a/README.md +++ b/README.md @@ -31,24 +31,26 @@ A hackable, minimal, fast TUI file explorer

- [Install] + [Install] [Documentation] + [Hacks] [Plugins] + [Integrations] [Community]

-`xplr` is a terminal UI based file explorer that aims to increase our terminal +xplr is a terminal UI based file explorer that aims to increase our terminal productivity by being a flexible, interactive orchestrator for the ever growing awesome command-line utilities that work with the file-system. -To achieve its goal, `xplr` strives to be a fast, minimal and more importantly, +To achieve its goal, xplr strives to be a fast, minimal and more importantly, hackable file explorer. -`xplr` is not meant to be a replacement for the standard shell commands or the -GUI file managers. Rather, it aims to integrate them all and expose an -intuitive, scriptable, keyboard controlled, real-time visual interface, also -being an ideal candidate for further integration, enabling us to achieve insane -terminal productivity. +xplr is not meant to be a replacement for the standard shell commands or the +GUI file managers. Rather, it aims to [integrate them all][14] and expose an +intuitive, scriptable, [keyboard controlled][2], +[real-time visual interface][1], also being an ideal candidate for [further +integration][15], enabling you to achieve insane terminal productivity. ## Introductions & Reviews @@ -61,3 +63,8 @@ terminal productivity. ## Backers + +[1]: https://xplr.dev/en/layouts +[2]: https://xplr.dev/en/configure-key-bindings +[14]: https://xplr.dev/en/awesome-plugins#integration +[15]: https://xplr.dev/en/awesome-integrations diff --git a/docs/en/src/SUMMARY.md b/docs/en/src/SUMMARY.md index 7683f62..183efaa 100644 --- a/docs/en/src/SUMMARY.md +++ b/docs/en/src/SUMMARY.md @@ -4,6 +4,7 @@ - [Quickstart][2] - [Install][3] - [Post Install][4] +- [Awesome Hacks][30] - [Configuration][5] - [Key Bindings][27] - [Configure Key Bindings][28] @@ -59,3 +60,4 @@ [27]: key-bindings.md [28]: configure-key-bindings.md [29]: debug-key-bindings.md +[30]: awesome-hacks.md diff --git a/docs/en/src/awesome-hacks.md b/docs/en/src/awesome-hacks.md new file mode 100644 index 0000000..e70f6a7 --- /dev/null +++ b/docs/en/src/awesome-hacks.md @@ -0,0 +1,321 @@ +# Awesome Hacks + +Here's a list of cool xplr hacks, i.e. snippets of code that you can just copy +and paste into your [configuration file][1], that are too small or niche for a +full fledge [plugins][2]. + +Do you have something cool to share? + +[Edit this file][3] or [share them here][4] or [let us know][5]. + +### Spawn multiple sessions in different tabs (iTerm2) + +Creating a new session that starts with iTerm2. + +
+Expand for details + +- Author: [@lmburns][9] +- Requires: iTerm2 +- Tested on: MacOS + +```lua +xplr.config.modes.builtin.default.key_bindings.on_key["ctrl-n"] = { + help = "new session", + messages = { + { BashExecSilently = [[ + osascript < + +### Bookmark + +Bookmark files using `m` and fuzzy search bookmarks using backtick. + +
+Expand for details + +[![xplr-bookmark.gif][7]][6] + +- Author: [@sayanarijit][8] +- Requires: fzf +- Tested on: Linux + +```lua +xplr.config.modes.builtin.default.key_bindings.on_key.m = { + help = "bookmark", + messages = { + { + BashExecSilently = [===[ + PTH="${XPLR_FOCUS_PATH:?}" + if echo "${PTH:?}" >> "${XPLR_SESSION_PATH:?}/bookmarks"; then + echo "LogSuccess: ${PTH:?} added to bookmarks" >> "${XPLR_PIPE_MSG_IN:?}" + else + echo "LogError: Failed to bookmark ${PTH:?}" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===], + }, + }, +} + +xplr.config.modes.builtin.default.key_bindings.on_key["`"] = { + help = "go to bookmark", + messages = { + { + BashExec = [===[ + PTH=$(cat "${XPLR_SESSION_PATH:?}/bookmarks" | fzf --no-sort) + if [ "$PTH" ]; then + echo FocusPath: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===], + }, + }, +} +``` + +
+ +### Persistent, multi-session bookmark + +A bookmark mode that allows for a bookmark file to be used throughout multiples +sessions. It is set to the environment variable `$XPLR_BOOKMARK_FILE`. A +bookmark can be added, deleted, or jumped to. + +
+Expand for details + +- Author: [@lmburns][9] +- Requires: fzf, sd +- Tested on: MacOS + +```lua +-- Bookmark: mode binding +xplr.config.modes.custom.bookmark = { + name = "bookmark", + key_bindings = { + on_key = { + m = { + help = "bookmark dir", + messages = { + { BashExecSilently = [[ + PTH="${XPLR_FOCUS_PATH:?}" + if [ -d "${PTH}" ]; then + PTH="${PTH}" + elif [ -f "${PTH}" ]; then + PTH="$(dirname "${PTH}")" + fi + if echo "${PTH:?}" >> "${XPLR_BOOKMARK_FILE:?}"; then + echo "LogSuccess: ${PTH:?} added to bookmarks" >> "${XPLR_PIPE_MSG_IN:?}" + else + echo "LogError: Failed to bookmark ${PTH:?}" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]] + }, + }, + }, + g = { + help = "go to bookmark", + messages = { + { + BashExec = [===[ + PTH=$(cat "${XPLR_BOOKMARK_FILE:?}" | fzf --no-sort) + if [ "$PTH" ]; then + echo FocusPath: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===] + }, + }, + }, + d = { + help = "delete bookmark", + messages = { + { BashExec = [[ + PTH=$(cat "${XPLR_BOOKMARK_FILE:?}" | fzf --no-sort) + sd "$PTH\n" "" "${XPLR_BOOKMARK_FILE:?}" + ]] + }, + }, + }, + esc = { + help = "cancel", + messages = { + "PopMode", + }, + }, + }, + }, +} +``` + +
+ +### Another bookmark manager type thing, taken from [wfxr's zsh plugin][13]. + +Another bookmark manager type thing, taken from [wfxr's zsh plugin][13] which has colored output with fzf. + +
+Expand for details + +- Author: [@lmburns][9] +- Requires: fzf, exa +- Tested on: MacOS + +```lua +xplr.config.modes.builtin.go_to.key_bindings.on_key.b = { + help = "bookmark jump", + messages = { + "PopMode", + { BashExec = [===[ + field='\(\S\+\s*\)' + esc=$(printf '\033') + N="${esc}[0m" + R="${esc}[31m" + G="${esc}[32m" + Y="${esc}[33m" + B="${esc}[34m" + pattern="s#^${field}${field}${field}${field}#$Y\1$R\2$N\3$B\4$N#" + PTH=$(sed 's#: # -> #' "$PATHMARKS_FILE"| nl| column -t \ + | gsed "${pattern}" \ + | fzf --ansi \ + --height '40%' \ + --preview="echo {}|sed 's#.*-> ##'| xargs exa --color=always" \ + --preview-window="right:50%" \ + | sed 's#.*-> ##') + if [ "$PTH" ]; then + echo ChangeDirectory: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===] + }, + } +} +``` + +
+ +### Fuzzy search history + +Fuzzy search the last visited directories. + +
+Expand for details + +- Author: [@sayanarijit][8] +- Requires: fzf +- Tested on: Linux + +```lua +xplr.config.modes.builtin.go_to.key_bindings.on_key.h = { + help = "history", + messages = { + "PopMode", + { + BashExec = [===[ + PTH=$(cat "${XPLR_PIPE_HISTORY_OUT:?}" | sort -u | fzf --no-sort) + if [ "$PTH" ]; then + echo ChangeDirectory: "'"${PTH:?}"'" >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===], + }, + }, +} +``` + +
+ +### Batch rename + +Batch rename the selected or visible files and directories in $PWD. + +
+Expand for details + +[![xplr-rename.gif][11]][10] + +- Author: [@sayanarijit][8] +- Requires: [pipe-rename][12] +- Tested on: Linux + +```lua +xplr.config.modes.builtin.default.key_bindings.on_key.R = { + help = "batch rename", + messages = { + { + BashExec = [===[ + SELECTION=$(cat "${XPLR_PIPE_SELECTION_OUT:?}") + NODES=${SELECTION:-$(cat "${XPLR_PIPE_DIRECTORY_NODES_OUT:?}")} + if [ "$NODES" ]; then + echo -e "$NODES" | renamer + echo ExplorePwdAsync >> "${XPLR_PIPE_MSG_IN:?}" + fi + ]===], + }, + }, +} +``` + +
+ +### Serve $PWD + +Serve $PWD using a static web server via LAN. + +
+Expand for details + +- Author: [@sayanarijit][8] +- Requires: [sfz][14], fzf +- Tested on: Linux + +```lua +xplr.config.modes.builtin.default.key_bindings.on_key.S = { + help = "serve $PWD", + messages = { + { + BashExec = [===[ + IP=$(ip addr | grep -w inet | cut -d/ -f1 | grep -Eo '[0-9]{1,3}\.[0-9]{ 1,3}\.[0-9]{1,3}\.[0-9]{1,3}' | fzf --prompt 'Select IP > ') + echo "IP: ${IP:?}" + read -p "Port (default 5000): " PORT + echo + sfz --all --cors --no-ignore --bind ${IP:?} --port ${PORT:-5000} . & + sleep 1 && read -p '[press enter to exit]' + kill -9 %1 + ]===], + }, + }, +} +``` + +
+ +## Also See: + +- [Awesome Plugins][15] +- [Awesome Integrations][16] + +[1]: configuration.md +[2]: plugin.md +[3]: https://github.com/sayanarijit/xplr/edit/main/docs/en/src/awesome-hacks.md +[4]: https://github.com/sayanarijit/xplr/discussions/categories/show-and-tell +[5]: community.md +[6]: https://gifyu.com/image/rGSR +[7]: https://s4.gifyu.com/images/xplr-bookmark.gif +[8]: https://github.com/sayanarijit +[9]: https://github.com/lmburns +[10]: https://gifyu.com/image/rGbo +[11]: https://s4.gifyu.com/images/xplr-rename.gif +[12]: https://github.com/marcusbuffett/pipe-rename +[13]: https://github.com/wfxr/formarks +[14]: https://github.com/weihanglo/sfz +[15]: awesome-plugins.md +[16]: awesome-integrations.md diff --git a/docs/en/src/awesome-integrations.md b/docs/en/src/awesome-integrations.md index fa4cc87..3bb707d 100644 --- a/docs/en/src/awesome-integrations.md +++ b/docs/en/src/awesome-integrations.md @@ -5,27 +5,26 @@ Here's a list of awesome xplr integrations that you might want to check out. If none of the following integrations work for you, you can create your own and [let us know][1]. -## Categories - -- [Editor][2] -- [Shell][3] -- [Security Tools][4] - -## Editor +### Editor +- [**fm-nvim**][10] Neovim plugin that lets you use your favorite terminal file managers from within Neovim. - [**vim-floaterm**][6] xplr integrated in vim-floaterm (Neo)vim plugin. - [**xplr.nvim**][9] Opens xplr inside nvim, and hosts a msgpack client inside xplr. - [**xplr.vim**][5] Pick files in Vim using xplr. -- [**fm-nvim**][10] Neovim plugin that lets you use your favorite terminal file managers from within Neovim. -## Shell +### Shell - [**powerlevel10k**][7] Powerlevel10k prompt for xplr shell. -## Security Tools +### Security Tools - [**gpg-tui**][8] Import GPG certificates using xplr. +## Also See: + +- [Awesome Hacks][11] +- [Awesome Plugins][12] + [1]: https://github.com/sayanarijit/xplr/discussions/categories/show-and-tell [2]: #editor [3]: #shell @@ -36,3 +35,5 @@ If none of the following integrations work for you, you can create your own and [8]: https://github.com/orhun/gpg-tui#importreceive [9]: https://github.com/fhill2/xplr.nvim [10]: https://github.com/is0n/fm-nvim +[11]: awesome-hacks.md +[12]: awesome-plugins.md diff --git a/docs/en/src/awesome-plugins.md b/docs/en/src/awesome-plugins.md index 4c68082..3c7acaa 100644 --- a/docs/en/src/awesome-plugins.md +++ b/docs/en/src/awesome-plugins.md @@ -4,13 +4,7 @@ Here's a list of awesome xplr plugins that you might want to check out. If none of the following plugins work for you, it's very easy to [write your own][1]. -## Categories - -- [Extension][32] -- [Integration][2] -- [Theme][3] - -## Extension +### Extension - [**sayanarijit/command-mode.xplr**][37] The missing command mode for xplr. - [**igorepst/context-switch.xplr**][42] Context switch plugin for xplr. @@ -20,7 +14,7 @@ of the following plugins work for you, it's very easy to with some tweaks. - [**igorepst/term.xplr**][39] Terminal integration for xplr -## Integration +### Integration - [**sayanarijit/alacritty.xplr**][33] [Alacritty][34] integration for xplr. - [**sayanarijit/dragon.xplr**][4] Drag and drop files using [dragon][5]. @@ -42,13 +36,18 @@ of the following plugins work for you, it's very easy to - [**sayanarijit/xclip.xplr**][15] Copy and paste with system clipboard using [xclip][16]. - [**sayanarijit/zoxide.xplr**][17] Change directory using the [zoxide][18] database. -## Theme +### Theme - [**sayanarijit/material-landscape.xplr**][19] Material Landscape - [**sayanarijit/material-landscape2.xplr**][20] Material Landscape 2 - [**sayanarijit/zentable.xplr**][31] A clean, distraction free xplr table UI - [**prncss-xyz/icons.xplr**][30] An icon theme for xplr. +## Also See: + +- [Awesome Hacks][45] +- [Awesome Integrations][46] + [1]: ./writing-plugins.md [2]: #integration [3]: #theme @@ -92,3 +91,5 @@ of the following plugins work for you, it's very easy to [42]: https://github.com/igorepst/context-switch.xplr [43]: https://github.com/sayanarijit/dual-pane.xplr [44]: https://github.com/sayanarijit/find.xplr +[45]: awesome-hacks.md +[46]: awesome-integrations.md diff --git a/docs/en/src/introduction.md b/docs/en/src/introduction.md index 8b81142..10841d6 100644 --- a/docs/en/src/introduction.md +++ b/docs/en/src/introduction.md @@ -8,93 +8,66 @@ To achieve its goal, xplr strives to be a fast, minimal and more importantly, hackable file explorer. xplr is not meant to be a replacement for the standard shell commands or the -GUI file managers. Rather, it aims to integrate them all and expose an -intuitive, scriptable, keyboard controlled, real-time visual interface, also -being an ideal candidate for further integration, enabling us to achieve insane -terminal productivity. +GUI file managers. Rather, it aims to [integrate them all][14] and expose an +intuitive, scriptable, [keyboard controlled][2], +[real-time visual interface][1], also being an ideal candidate for [further +integration][15], enabling you to achieve insane terminal productivity. -## Features +## Concept ### Hackable xplr is built with configurability in mind. So it allows you to perform a vast -set of operations and make it behave just the way you want. +set of operations and make it look and behave just the way you want. A few things you can do with the xplr configuration -- [Hack the layout][1] -- [Hack the key bindings][2] -- [Extend with plugins][3] +- [Hacks][16] +- [Plugins][3] +- [Integrations][15] -## Fast +### Fast Although speed is not the primary concern, xplr is already fast enough so that you can take it out for a walk into your `node_modules` or `/nix/store` any -time you want. I currently -[measure the most commonly used operations][4] -and I have seen it improve significantly over time, and it's only the start. +time you want, and it will only get faster. Still, if you feel like it's +somehow making you slow, just report it. Most probably we're just waiting for +someone to complain. + +**Tip:** A quick and easy way to optimize the UI rendering is reducing the +number of columns in the table. -**Tip:** A quick and easy way to optimize UI rendering is reducing the number -of columns in the table. +### Minimal -**Note:** If you feel xplr is not behaving at its optimal, this is probably -because I am waiting for someone to complain. I want to avoid optimizing things -I don't need to, because optimization often requires either complexity or -feature sacrifice or both. +xplr is being referred to as a _File Explorer_, not a _File Manager_. This +is because at the core, xplr is only an explorer, and [outsources][18] the file +management operations to external commands. This helps xplr stay minimal, and +focus only on doing what it does best. -## Minimalist +So, just like speed, minimalism isn't as as aggressively pursued as +hackability. xplr simply prefers to stay minimal and looks for the opportunity +to lose some kb if it makes sense. -xplr prefers to stay minimal, both in terms of features and binary size, but -just like speed, minimalism isn't as aggressively pursued as configurability. -If adding some feature, lines of code, or a dependency allows the users to be a -little more productive or allows xplr to be a little more configurable, it will -be considered. But of-course, the `bulk vs productivity gain per user` balance -will also be considered in the decision-making. +## Features -## Other features +Some of the coolest features xplr provide beside the basic stuff: -- [Embedded LuaJIT][5] for - portability and extensibility. -- **Switchable recover mode:** Saves you from doing unwanted things when in a +- [Embedded LuaJIT][5] for portability and extensibility. +- [A simple system based on message passing][10] to control xplr session using: + - [Keyboard inputs][11] + - [Shell Commands][12] + - [Lua Functions][13] +- [Readline-like input buffer][9] with customizable behaviour to read user + inputs. +- [Switchable recover mode][7] that saves you from doing unwanted things when in a hurry. -- **Sane (vim-like) defaults:** - - Use `h`, `j`, `k`, `l` or arrow keys - for basic navigation. - - Go to top using `g` `g`, and bottom using `G`. - - Travel history using `ctrl-o` and `ctrl-i`. - - Go to home directory using `~`. - - Enter search mode with `/` or `ctrl-f`. - - Go to absolute index (e.g. `4`) using `4` `enter` or - `:` `4` `enter`. - - Go to relative index (e.g. `4` `down`) using `4` `down` or - `:` `4` `down`. - - Follow symlink using `g` `f`. - - Open in GUI using `g` `x`. - - Spawn terminal using `:` `!`. - - Toggle selection using `v` or `space`. - - Toggle select all using `V` or `ctrl-a`. - - Clear selections using `ctrl-u`. -- **Separate keys for navigation:** navigation keys are separated from the - action keys (e.g. file opening action) to avoid mistakenly performing - unwanted actions while navigating. -- **Always visible panels** to save you brain cycles: - - Selection list. - - Help menu. - - Input & logs. - - Filter and sort pipeline. -- **Batch creation:** Create multiple files and directories without repeating - keys. -- **Batch sort & filter:** Apply sorters and filters in without repeating keys. -- **Custom file properties:** Display custom file properties with custom colors - in the table using Lua functions. -- **Input buffer:** Read user input using the built-in input buffer with - customizable behavior. -- **Switchable layouts:** Switch layouts dynamically without leaving `xplr`. -- **Saved locations:** Never lose context when traveling back and forth - directories. -- **Auto refresh state:** Auto refresh app state when the `$PWD` changes. -- **Manually refresh UI** when other apps mess it up. -- **FIFO-based previews:** Easy to manage FIFO file that can be used to +- [Customizable layouts][1] with built-in panels. For e.g. + - **Selection list** to show you the selected paths in real-time. + - **Help menu** to show you the available keys bindings in each mode. + - **Input & logs** to read input and display logs. + - **Filter and sort pipeline** to show you the applied filters and sorters. +- [Custom file properties][17] with custom colors can be displayed in the table. +- [FIFO manager][19] to manage a FIFO file that can be used to [integrate with previewers][6]. - **Different quit options:** - Quit with success without any output (`q`). @@ -107,9 +80,25 @@ will also be considered in the decision-making. (`:` `q` `s`). - Quit with failure (`ctrl-c`). +**Q.** What features should be added here? [let us know][20]. + [1]: layouts.md [2]: configure-key-bindings.md [3]: awesome-plugins.md [4]: https://github.com/sayanarijit/xplr/tree/main/benches [5]: https://github.com/sayanarijit/xplr/discussions/183 [6]: https://github.com/sayanarijit/xplr/pull/229 +[7]: general-config.md#enable_recover_mode +[8]: default-key-bindings.md +[9]: https://github.com/sayanarijit/xplr/pull/397 +[10]: message.md +[11]: configure-key-bindings.md +[12]: message.md#input-pipe +[13]: message.md#lua-function-calls +[14]: awesome-plugins.md#integration +[15]: awesome-integrations.md +[16]: awesome-hacks.md +[17]: node_types.md +[18]: https://github.com/sayanarijit/xplr/blob/main/src/init.lua +[19]: message.md#startfifo +[20]: community.md