Skip to content

Commit

Permalink
docs: Yazi 0.4 changes
Browse files Browse the repository at this point in the history
  • Loading branch information
@sxyazi
sxyazi committed Dec 9, 2024
1 parent 9495114 commit 38d481a
Show file tree
Hide file tree
Showing 9 changed files with 78 additions and 96 deletions.
2 changes: 1 addition & 1 deletion cspell.json
View file
Original file line number Diff line number Diff line change
@@ -1 +1 @@
{"version":"0.2","language":"en","words":["linemode","Hyprland","ueberzug","yazi","sxyazi","Discardable","Sixel","downscaling","downscales","keymap","unyank","preloaders","precache","Konsole","Mintty","Ghostty","Zellij","scrolloff","unsub","subshell","translit","rustup","hardlink","Chafa"],"flagWords":[]}
{"version":"0.2","words":["linemode","Hyprland","ueberzug","yazi","sxyazi","Discardable","Sixel","downscaling","downscales","keymap","unyank","preloaders","precache","Konsole","Mintty","Ghostty","Zellij","scrolloff","unsub","subshell","translit","rustup","hardlink","Chafa","btime"],"flagWords":[],"language":"en"}
57 changes: 15 additions & 42 deletions docs/configuration/keymap.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ You can change Yazi's keybindings in your `keymap.toml` file, which consists of

- [\[manager\]](#manager) - File list.
- [\[tasks\]](#tasks) - Task manager.
- [\[select\]](#select) - Select component. e.g. "open with" for files.
- [\[pick\]](#pick) - Pick component. e.g. "open with" for files.
- [\[input\]](#input) - Input component. e.g. create, rename, etc.
- [\[completion\]](#completion) - Completion component. e.g. "cd" path completion.
- [\[help\]](#help) - Help menu.
Expand Down Expand Up @@ -189,32 +189,8 @@ Change the current directory to the parent of specified file, and hover on it.
| --------------- | ------------------- |
| `[path]` | The path to reveal. |

### `select` {#manager.select}

| Argument/Option | Description |
| --------------- | -------------------------------------------------------- |
| `--state=true` | Select the current file. |
| `--state=false` | Deselect the current file. |
| `--state=none` | Default, toggle the selection state of the current file. |

### `select_all` {#manager.select_all}

Select all files in the current working directory.

| Argument/Option | Description |
| --------------- | ------------------------------------------------ |
| `--state=true` | Select all files |
| `--state=false` | Deselect all files |
| `--state=none` | Default, toggle the selection state of all files |

Note that `--state=false` will deselect all files in the current working directory.

If you have selected files across directories and want to deselect all of them, use [`escape --select`](#manager.escape) instead.

### `toggle` {#manager.toggle}

**Note**: This command is introduced in the upcoming v0.4 to replace `select` and currently requires the nightly build.

Toggle the selection state of the hovered file.

| Argument/Option | Description |
Expand All @@ -225,8 +201,6 @@ Toggle the selection state of the hovered file.

### `toggle_all` {#manager.toggle_all}

**Note**: This command is introduced in the upcoming v0.4 to replace `select_all` and currently requires the nightly build.

Toggle the selection state of all files in the current working directory.

| Argument/Option | Description |
Expand Down Expand Up @@ -354,8 +328,7 @@ Run a shell command.
| `[template]` | Optional, command template to be run. |
| `--block` | Open in a blocking manner. After setting this, Yazi will hide into a secondary screen and display the program on the main screen until it exits. During this time, it can receive I/O signals, which is useful for interactive programs. |
| `--orphan` | Keep the process running even if Yazi has exited, once specified, the process will be detached from the task scheduling system. |
| `--confirm` | When the template is provided, run it directly, no input box was shown. It's mutually exclusive with `--interactive`. |
| `--interactive` | Request the user to input the command to be run interactively. It's mutually exclusive with `--confirm`. |
| `--interactive` | Request the user to input the command to be run interactively |
| `--cursor` | Set the initial position of the cursor in the interactive command input box. For example, `shell 'zip -r .zip "$0"' --cursor=7 --interactive` places the cursor before `.zip`. |

You can use the following shell variables in `[run]`:
Expand All @@ -382,7 +355,7 @@ Set the [line mode](/docs/configuration/yazi#manager.linemode).
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `none` | No line mode. |
| `size` | Display the size in bytes of the file. Note that currently directory sizes are only evaluated when [`sort_by = "size"`](/docs/configuration/yazi#manager.sort_by), and this might change in the future. |
| `ctime` | Display the creation time of the file. |
| `btime` | Display the birth time of the file. |
| `mtime` | Display the last modified time of the file. |
| `permissions` | Display the permissions of the file, only available on Unix-like systems. |
| `owner` | Display the owner of the file, only available on Unix-like systems. |
Expand Down Expand Up @@ -441,8 +414,8 @@ Move the cursor to the next or previous occurrence.

- `[by]`: Optional, if not provided, the sort method will be kept unchanged.
- `"none"`: Don't sort.
- `"modified"`: Sort by last modified time.
- `"created"`: Sort by creation time. (Due to a Rust bug, this is not available at the moment, see [sxyazi/yazi#356](https://github.com/sxyazi/yazi/issues/356) and [rust-lang/rust#108277](https://github.com/rust-lang/rust/issues/108277))
- `"mtime"`: Sort by last modified time.
- `"btime"`: Sort by birth time.
- `"extension"`: Sort by file extension.
- `"alphabetical"`: Sort alphabetically, e.g. `1.md` < `10.md` < `2.md`
- `"natural"`: Sort naturally, e.g. `1.md` < `2.md` < `10.md`
Expand Down Expand Up @@ -549,31 +522,31 @@ See [Functional plugin](/docs/plugins/overview#functional-plugin).

See [`noop` command](#manager.noop).

## [select] {#select}
## [pick] {#pick}

### `close` {#select.close}
### `close` {#pick.close}

Cancel selection.
Cancel the picker.

| Argument/Option | Description |
| --------------- | --------------------- |
| `--submit` | Submit the selection. |
| Argument/Option | Description |
| --------------- | ------------------ |
| `--submit` | Submit the picker. |

### `arrow` {#select.arrow}
### `arrow` {#pick.arrow}

| Argument/Option | Description |
| --------------- | ------------------------------------------------------------------------------------- |
| `[n]` | Move the cursor up or down `n` lines. Negative value for up, positive value for down. |

### `help` {#select.help}
### `help` {#pick.help}

Open the help menu.

### `plugin` {#select.plugin}
### `plugin` {#pick.plugin}

See [Functional plugin](/docs/plugins/overview#functional-plugin).

### `noop` {#select.noop}
### `noop` {#pick.noop}

See [`noop` command](#manager.noop).

Expand Down
23 changes: 11 additions & 12 deletions docs/configuration/theme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -117,11 +117,11 @@ Progress

Permissions

- permissions_t (Style): File type.
- permissions_r (Style): Read permission.
- permissions_w (Style): Write permission.
- permissions_x (Style): Execute permission.
- permissions_s (Style): `-` separator.
- perm_type (Style): File type.
- perm_read (Style): Read permission.
- perm_write (Style): Write permission.
- perm_exec (Style): Execute permission.
- perm_sep (Style): `-` separator.

## [select] {#select}

Expand Down Expand Up @@ -201,7 +201,7 @@ rules = [
{ mime = "audio/*", fg = "magenta" },

# Empty files
{ mime = "inode/x-empty", fg = "cyan" },
{ mime = "inode/empty", fg = "cyan" },

# Orphan symbolic links
{ name = "*", is = "orphan", fg = "red" },
Expand Down Expand Up @@ -238,11 +238,11 @@ If you want to add your own rules to this set, you can use `prepend_*` and `appe
```toml
[icon]
prepend_dirs = [
{ name = "desktop", text = "", fg_dark = "#563d7c", fg_light = "#563d7c" },
{ name = "desktop", text = "", fg = "#563d7c" },
# ...
]
append_exts = [
{ name = "mp3", text = "", fg_dark = "#00afff", fg_light = "#0075aa" },
{ name = "mp3", text = "", fg = "#00afff" },
# ...
]
# ...
Expand All @@ -253,11 +253,11 @@ If you want to completely override the default rules, you can do so with:
```toml
[icon]
dirs = [
{ name = "desktop", text = "", fg_dark = "#563d7c", fg_light = "#563d7c" },
{ name = "desktop", text = "", fg = "#563d7c" },
# ...
]
exts = [
{ name = "mp3", text = "", fg_dark = "#00afff", fg_light = "#0075aa" },
{ name = "mp3", text = "", fg = "#00afff" },
# ...
]
# ...
Expand All @@ -267,8 +267,7 @@ Each icon rule contains the following properties:

- `name` (globs, dirs, files, exts), or `if` (conds): the rule itself, which is a string
- `text`: icon text, which is a string
- `fg_dark`: icon color in dark mode, which is a [Color](/docs/configuration/theme#types.color)
- `fg_light`: icon color for light mode, which is a [Color](/docs/configuration/theme#types.color)
- `fg`: icon color, which is a [Color](/docs/configuration/theme#types.color)

Icons are matched according to the following priority:

Expand Down
10 changes: 5 additions & 5 deletions docs/configuration/yazi.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,8 @@ Set the value to `0` to hide the corresponding panel, but at least one panel mus
File sorting method.

- `"none"`: Don't sort.
- `"modified"`: Sort by last modified time.
- `"created"`: Sort by creation time.
- `"mtime"`: Sort by last modified time.
- `"btime"`: Sort by birth time.
- `"extension"`: Sort by file extension.
- `"alphabetical"`: Sort alphabetically, e.g. `1.md` < `10.md` < `2.md`
- `"natural"`: Sort naturally, e.g. `1.md` < `2.md` < `10.md`
Expand Down Expand Up @@ -68,7 +68,7 @@ Line mode: display information associated with the file on the right side of the

- `"none"`: No line mode.
- `"size"`: Display the size in bytes of the file. Note that currently directory sizes are only evaluated when [`sort_by = "size"`](/docs/configuration/yazi#manager.sort_by), and this might change in the future.
- `"ctime"`: Display the creation time of the file.
- `"btime"`: Display the birth time of the file.
- `"mtime"`: Display the last modified time of the file.
- `"permissions"`: Display the permissions of the file, only available on Unix-like systems.
- `"owner"`: Display the owner of the file, only available on Unix-like systems.
Expand All @@ -84,7 +84,7 @@ linemode = "size_and_mtime"
```lua
-- ~/.config/yazi/init.lua
function Linemode:size_and_mtime()
local time = math.floor(self._file.cha.modified or 0)
local time = math.floor(self._file.cha.mtime or 0)
if time == 0 then
time = ""
elseif os.date("%Y", time) == os.date("%Y") then
Expand All @@ -94,7 +94,7 @@ function Linemode:size_and_mtime()
end

local size = self._file:size()
return ui.Line(string.format("%s %s", size and ya.readable_size(size) or "-", time))
return string.format("%s %s", size and ya.readable_size(size) or "-", time)
end
```

Expand Down
2 changes: 1 addition & 1 deletion docs/installation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -124,7 +124,7 @@ in {
manager.prepend_keymap = [
{
on = "T";
run = "plugin --sync max-preview";
run = "plugin max-preview";
desc = "Maximize or restore the preview pane";
}
{
Expand Down
19 changes: 13 additions & 6 deletions docs/plugins/overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,23 +50,30 @@ You can bind a `plugin` command to a specific key in your `keymap.toml` with:
| Argument/Option | Description |
| --------------- | ------------------------------------------- |
| `[name]` | The name of the plugin to run. |
| `--sync` | Run the plugin in a sync context. |
| `--args=[args]` | Shell-style arguments passed to the plugin. |

For example, `plugin test --sync --args='hello world'` will run the `test` plugin with the arguments `hello` and `world` in a sync context.
For example, `plugin test --args='hello --foo --bar=baz'` will run the `test` plugin with the arguments `hello --foo --bar=baz` in a sync context.

To receive the arguments in the plugin, use `args`:
To access the arguments in the plugin, use `job.args`:

TODO: add doc about `@sync` (`--sync`)

```lua
--- @sync entry
-- ~/.config/yazi/plugins/test.yazi/init.lua
return {
entry = function(self, args)
ya.err(args[1]) -- "hello"
ya.err(args[2]) -- "world"
entry = function(self, job)
ya.err(job.args[1]) -- "hello"
ya.err(job.args.foo) -- true
ya.err(job.args.bar) -- "baz"
end,
}
```

Note that currently Yazi only supports positional arguments (`hello`) and named arguments (`--foo`, `--bar`), it does not support shorthand arguments like `-f` or `-b`.

These will be treated as positional arguments, but as Yazi adds support for shorthands in the future, their behavior will change. So please avoid using them to prevent any potential conflicts.

## Sync vs Async {#sync-vs-async}

The plugin system is designed with an async-first philosophy. Therefore, unless specifically specified, such as the `--sync` for the `plugin` command, all plugins run in an async context.
Expand Down
13 changes: 8 additions & 5 deletions docs/plugins/types.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,11 +22,14 @@ Cha means one file's characteristics with the following properties:
- `is_sock` - Whether this file is a socket
- `is_exec` - Whether this file is executable
- `is_sticky` - Whether this file has the sticky bit set
- `length` - The length of this file, returns an integer representing the size in bytes. Note that it can't reflect the size of a directory, use [`size()`](#app-data.folder-file) instead
- `created` - The created time of this file in Unix timestamp, or `nil` if it doesn't have a valid time
- `modified` - The modified time of this file in Unix timestamp, or `nil` if it doesn't have a valid time
- `accessed` - The accessed time of this file in Unix timestamp, or `nil` if it doesn't have a valid time
- `permissions` - Unix permissions of this file in string, e.g. `drwxr-xr-x`. For Windows, it's always `nil`
- `len` - The length of this file, returns an integer representing the size in bytes. Note that it can't reflect the size of a directory, use [`size()`](#app-data.folder-file) instead
- `atime` - The accessed time of this file in Unix timestamp, or `nil` if it doesn't have a valid time
- `btime` - The birth time of this file in Unix timestamp, or `nil` if it doesn't have a valid time
- `mtime` - The modified time of this file in Unix timestamp, or `nil` if it doesn't have a valid time

And methods:

- `perm()` - Unix permissions of this file in string, e.g. `drwxr-xr-x`. For Windows, it's always `nil`

And the Unix only properties:

Expand Down
4 changes: 2 additions & 2 deletions docs/quick-start.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -220,8 +220,8 @@ _Observation: <kbd>,</kbd> ⇒ <kbd>a</kbd> indicates pressing the <kbd>,</kbd>
| --------------------------- | -------------------------------- |
| <kbd>,</kbd> ⇒ <kbd>m</kbd> | Sort by modified time |
| <kbd>,</kbd> ⇒ <kbd>M</kbd> | Sort by modified time (reverse) |
| <kbd>,</kbd> ⇒ <kbd>c</kbd> | Sort by creation time |
| <kbd>,</kbd> ⇒ <kbd>C</kbd> | Sort by creation time (reverse) |
| <kbd>,</kbd> ⇒ <kbd>b</kbd> | Sort by birth time |
| <kbd>,</kbd> ⇒ <kbd>B</kbd> | Sort by birth time (reverse) |
| <kbd>,</kbd> ⇒ <kbd>e</kbd> | Sort by file extension |
| <kbd>,</kbd> ⇒ <kbd>E</kbd> | Sort by file extension (reverse) |
| <kbd>,</kbd> ⇒ <kbd>a</kbd> | Sort alphabetically |
Expand Down
Loading

0 comments on commit 38d481a

Please sign in to comment.