From 8174946e1e352ac22444786efcb7aadd1914b93e Mon Sep 17 00:00:00 2001 From: hankertrix <91734413+hankertrix@users.noreply.github.com> Date: Mon, 1 Jul 2024 10:26:11 +0800 Subject: [PATCH] Docs: Make README better --- README.md | 164 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 133 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 03ff21e..60cf339 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,11 @@ # augment-command.yazi -A [Yazi](https://github.com/sxyazi/yazi) plugin that enhances Yazi's default commands. This plugin is inspired by the [Yazi tips page](https://yazi-rs.github.io/docs/tips), the [bypass.yazi](https://github.com/Rolv-Apneseth/bypass.yazi) plugin and the [fast-enter.yazi](https://github.com/ourongxing/fast-enter.yazi) plugin. +A [Yazi](https://github.com/sxyazi/yazi) +plugin that enhances Yazi's default commands. +This plugin is inspired by the +[Yazi tips page](https://yazi-rs.github.io/docs/tips), +the [bypass.yazi](https://github.com/Rolv-Apneseth/bypass.yazi) plugin +and the [fast-enter.yazi](https://github.com/ourongxing/fast-enter.yazi) plugin. ## Table of Contents @@ -79,7 +84,9 @@ require("augment-command"):setup({ }) ``` -Note that you don't have to do this if you want to use the default configuration. You also can leave out configuration options that you would like to be left as default, for example: +Note that you don't have to do this if you want to use the default configuration. +You also can leave out configuration options that you would like to be left as default, +for example: ```lua -- ~/.config/yazi/init.lua @@ -96,56 +103,130 @@ require("augment-command"):setup({ ## What about the commands are augmented? -All commands that can operate on multiple files and directories, like `open`, `rename` and `remove`, as well as the new commands `editor` and `pager`, now determine an item group to operate on. By default, the command will operate on the hovered item, unless the hovered item is also selected, then it will operate on the selected items. - -- When `must_have_hovered_item` is set to `true`, having no hovered item means the plugin will cancel the operation. -- When `must_have_hovered_item` is set to `false` and there are selected items, the selected items will be operated. -- With `prompt` is set to `true`, the plugin will always prompt you to choose an item group when there are both selected items and a hovered item. +All commands that can operate on multiple files and directories, +like `open`, `rename` and `remove`, +as well as the new commands `editor` and `pager`, +now determine an item group to operate on. +By default, the command will operate on the hovered item, +unless the hovered item is also selected, +then it will operate on the selected items. + +- When `must_have_hovered_item` is set to `true`, +having no hovered item means the plugin will cancel the operation. +- When `must_have_hovered_item` is set to `false` and +there are selected items, the selected items will be operated on. +- With `prompt` is set to `true`, +the plugin will always prompt you to +choose an item group when there are +both selected items and a hovered item. ## Augmented commands ### Open (`open`) -- When `smart_enter` is set to `true`, calls the `enter` command when the hovered item is a directory. -- `--no-skip` flag, which only applies when `smart_enter` is used as it is passed to the `enter` command. -- Automatically extracts and enters archive files, with support for skipping directories with only one subdirectory in the extracted archive. This can be disabled by setting `enter_archives` to `false` in the configuration. This feature requires [unarchiver (unar)](https://theunarchiver.com/command-line) to be installed as well as the [ls](https://www.gnu.org/software/coreutils/manual/html_node/ls-invocation.html#ls-invocation) command. +- When `smart_enter` is set to `true`, +calls the `enter` command when the hovered item is a directory. +- `--no-skip` flag, which only applies +when `smart_enter` is used as it is passed to the `enter` command. +More details about this flag can be found at the documentation +for the [enter command](#enter-(enter)). +- Automatically extracts and enters archive files, +with support for skipping directories +that contain only one subdirectory in the extracted archive. +This can be disabled by setting `enter_archives` to `false` in the configuration. +This feature requires +[unarchiver (unar)](https://theunarchiver.com/command-line) +to be installed as well as the +[ls](https://www.gnu.org/software/coreutils/manual/html_node/ls-invocation.html#ls-invocation) command. ### Enter (`enter`) -- When `smart_enter` is set to `true`, calls the `open` command when the hovered item is a file. -- Automatically skips directories with only one subdirectory when entering directories. This can be turned off by setting `skip_single_subdirectory_on_enter` to `false` in the configuration. This feature requires the [ls](https://www.gnu.org/software/coreutils/manual/html_node/ls-invocation.html#ls-invocation) command. -- `--no-skip` flag. It stops the plugin from skipping directories with only one subdirectory when entering directories, even when `skip_single_subdirectory_on_enter` is set to `true`. +- When `smart_enter` is set to `true`, +calls the `open` command when the hovered item is a file. +- Automatically skips directories that +contain only one subdirectory when entering directories. +This can be turned off by setting +`skip_single_subdirectory_on_enter` to `false` in the configuration. +This feature requires the +[ls](https://www.gnu.org/software/coreutils/manual/html_node/ls-invocation.html#ls-invocation) command. +- `--no-skip` flag. It stops the plugin from skipping directories +that contain only one subdirectory when entering directories, +even when `skip_single_subdirectory_on_enter` is set to `true`. +This allows you to set a key to navigate into directories +without skipping the directories that contain only one subdirectory. ### Leave (`leave`) -- Automatically skips directories with only one subdirectory when leaving directories. This can be turned off by setting `skip_single_subdirectory_on_leave` to `false` in the configuration. This feature requires the [ls](https://www.gnu.org/software/coreutils/manual/html_node/ls-invocation.html#ls-invocation) command. -- `--no-skip` flag. It stops the plugin from skipping directories with only one subdirectory, even when `skip_single_subdirectory_on_leave` is set to `true`. +- Automatically skips directories that +contain only one subdirectory when leaving directories. +This can be turned off by +setting `skip_single_subdirectory_on_leave` to `false` +in the configuration. +This feature requires the +[ls](https://www.gnu.org/software/coreutils/manual/html_node/ls-invocation.html#ls-invocation) command. +- `--no-skip` flag. It stops the plugin +from skipping directories that contain only one subdirectory, +even when `skip_single_subdirectory_on_leave` is set to `true`. +This allows you to set a key to navigate into directories +without skipping the directories that contain only one subdirectory. ### Rename (`rename`) -- Unfortunately, to use the augmented `rename` command, you need to use the latest Git version of Yazi as [this commit](https://github.com/sxyazi/yazi/commit/9961251248c74202d8310085102d5809c279757c) adds the necessary `--hovered` flag. -- If you don't use the latest Git version of Yazi, it just behaves like the original `rename` command. +- Unfortunately, to use the augmented `rename` command, +you need to use the latest Git version of Yazi as +[this commit](https://github.com/sxyazi/yazi/commit/9961251248c74202d8310085102d5809c279757c) +adds the necessary `--hovered` flag. +- If you don't use the latest Git version of Yazi, +it just behaves like the provided `rename` command +and the prompts don't do anything. ### Remove (`remove`) -- Unfortunately, to use the augmented `remove` command, you need to use the latest Git version of Yazi as [this commit](https://github.com/sxyazi/yazi/commit/9961251248c74202d8310085102d5809c279757c) adds the necessary `--hovered` flag. -- If you don't use the latest Git version of Yazi, it just behaves like the original `remove` command. +- Unfortunately, to use the augmented `remove` command, +you need to use the latest Git version of Yazi as +[this commit](https://github.com/sxyazi/yazi/commit/9961251248c74202d8310085102d5809c279757c) +adds the necessary `--hovered` flag. +- If you don't use the latest Git version of Yazi, +it just behaves like the provided `remove` command +and the prompts don't do anything. ### Paste (`paste`) -- When `smart_paste` is set to `true`, the `paste` command will paste items into a hovered directory without entering it. If the hovered item is not a directory, the command pastes in the current directory instead. -- `--smart` flag to enable pasting in a hovered directory without entering the directory. This flag will cause the `paste` command to paste items into a hovered directory even when `smart_paste` is set to `false`. +- When `smart_paste` is set to `true`, +the `paste` command will paste items +into a hovered directory without entering it. +If the hovered item is not a directory, +the command pastes in the current directory instead. +- `--smart` flag to enable pasting in a hovered directory +without entering the directory. +This flag will cause the `paste` command to paste items +into a hovered directory even when `smart_paste` is set to `false`. +This allows you to set a key to use smart paste +instead of using smart paste for every paste command. ### Arrow (`arrow`) -- When `wraparound_file_navigation` is set to `true`, the arrow command will wrap around from the bottom to the top or from the top to the bottom when navigating. Otherwise, it'll behave like the default `arrow` command. +- When `wraparound_file_navigation` is set to `true`, +the arrow command will wrap around from the bottom to the top or +from the top to the bottom when navigating. +Otherwise, it'll behave like the default `arrow` command. ## New commands ### Parent-arrow (`parent-arrow`) -- This command behaves like the `arrow` command, but in the parent directory. It allows you to navigate the parent directory without leaving the current directory. -- When `wraparound_file_navigation` is set to `true`, this command will also wrap around from the bottom to the top or from top to the bottom when navigating in the parent directory. For this feature to work, you will need the [ls](https://www.gnu.org/software/coreutils/manual/html_node/ls-invocation.html#ls-invocation) command. You will also need to have your directories sorted first for this feature to work, i.e. in your `~/.config/yazi/yazi.toml` file: +- This command behaves like the `arrow` command, +but in the parent directory. +It allows you to navigate the parent directory +without leaving the current directory. +- When `wraparound_file_navigation` is set to `true`, +this command will also wrap around from the bottom to the top or +from top to the bottom when navigating in the parent directory. +For this feature to work, you will need the +[ls](https://www.gnu.org/software/coreutils/manual/html_node/ls-invocation.html#ls-invocation) command. +You will also need to have your directories +sorted first for this feature to work, +i.e. in your `~/.config/yazi/yazi.toml` file: ```toml # ~/.config/yazi/yazi.toml @@ -153,7 +234,9 @@ All commands that can operate on multiple files and directories, like `open`, `r sort_dir_first = true ``` -- You can also replicate this using this series of commands below, but it doesn't work as well, and doesn't support wraparound navigation: +- You can also replicate this using this series of commands below, +but it doesn't work as well, +and doesn't support wraparound navigation: ```toml # ~/.config/yazi/keymap.toml @@ -182,13 +265,15 @@ desc = "Move down in the parent directory" ## Usage -Add the commands that you would like to use to your `keymap.toml` file, located at `~/.config/yazi/keymap.toml`, in this format: +Add the commands that you would like to use to your `keymap.toml` file, +located at `~/.config/yazi/keymap.toml`, +in this format: ```toml # ~/.config/yazi/keymap.toml [[manager.prepend_keymap]] on = [ "key" ] -run = "plugin augment-command --args='command'" +run = "plugin augment-command --args='command arguments --flags --options=42'" desc = "Description" ``` @@ -202,10 +287,15 @@ run = "plugin augment-command --args='enter'" desc = "Enter a directory and skip directories with only a single subdirectory" ``` -All the default options provided by Yazi are also supported, for example: +All the default arguments, flags and options provided by Yazi are also supported, for example: ```toml # ~/.config/yazi/keymap.toml +[[manager.prepend_keymap]] +on = [ "k" ] +run = "plugin augment-command --args='arrow -1'" +desc = "Move cursor up" + [[manager.prepend_keymap]] on = [ "r" ] run = "plugin augment-command --args='rename --cursor=before_ext'" @@ -217,11 +307,22 @@ run = "plugin augment-command --args='remove --permanently'" desc = "Permanently delete the files" ``` -For the default descriptions of the commands, you can refer to [Yazi's `keymap.toml` file](https://github.com/sxyazi/yazi/blob/main/yazi-config/preset/keymap.toml). +For the default descriptions of the commands, +you can refer to +[Yazi's `keymap.toml` file](https://github.com/sxyazi/yazi/blob/main/yazi-config/preset/keymap.toml). + +Essentially, all you need to do to use this plugin +is to wrap a Yazi command in single quotes, +like `'enter'`, +then add `plugin augment-command --args` +in front of it, which results in +`plugin augment-command --args='enter'`. ### Full configuration example -For a full configuration example, you can take a look at [my `keymap.toml` file](https://github.com/hankertrix/Dotfiles/blob/master/.config/yazi/keymap.toml). +For a full configuration example, +you can take a look at +[my `keymap.toml` file](https://github.com/hankertrix/Dotfiles/blob/master/.config/yazi/keymap.toml). ## Windows support? @@ -229,4 +330,5 @@ Pull requests for Windows support are welcome! ## Licence -This plugin is licenced under the GNU GPL v3 licence. You can view the full licence in the `LICENSE.txt` file. +This plugin is licenced under the GNU GPL v3 licence. +You can view the full licence in the `LICENSE.txt` file.