Skip to content

Commit

Permalink
Docs: Make README better
Browse files Browse the repository at this point in the history
  • Loading branch information
@hankertrix
hankertrix committed Jul 1, 2024
1 parent f9b31f3 commit 8174946
Showing 1 changed file with 133 additions and 31 deletions.
164 changes: 133 additions & 31 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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

Expand Down Expand Up @@ -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
Expand All @@ -96,64 +103,140 @@ 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
[manager]
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
Expand Down Expand Up @@ -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"
```

Expand All @@ -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'"
Expand All @@ -217,16 +307,28 @@ 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?

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.

0 comments on commit 8174946

Please sign in to comment.