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
-`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