Migrating to Yazi v0.3.0

[sxyazi]

TOC

• Migrating to Yazi v0.3.0 - here
• Packaging
• Lua API breaking changes in Yazi v0.3

Eliminated the exec property

Since Yazi v0.2.4, exec has been deprecated and replaced with a new run property and some compatibility code has been written to ensure users can transition smoothly.

In Yazi v0.3, these compatibility codes will be removed, meaning exec will be completely eliminated.

Please replace all instances of exec = ... with run = ... in your yazi.toml, keymap.toml, and theme.toml files if any, for example:

# keymap.toml
- { on = [ "k" ], exec = "arrow -1", desc = "Move cursor up" }
+ { on = [ "k" ], run = "arrow -1", desc = "Move cursor up" }

Eliminated the jump command

In Yazi v0.2.5, the jump command has been deprecated, and zoxide and fzf have been re-implemented as built-in plugins to enhance their functionality and provide better flexibility (See #865 for details).

In Yazi v0.3, the compatibility code of jump command will be deleted. Please replace them in your keymap.toml if any:

# keymap.toml
- { on = [ "z" ], run = "jump zoxide" },
+ { on = [ "z" ], run = "plugin zoxide" },

# keymap.toml
- { on = [ "Z" ], run = "jump fzf" },
+ { on = [ "Z" ], run = "plugin fzf" },

Removed the mime plugin from preloaders

Yazi v0.3 introduced a fetcher to simplify preloader design, and reclassified the mime plugin as part of the fetcher.

If you copied the entire preloaders before, please remove it from the list:

# yazi.toml
[plugin]
preloaders = [
-  { name = "*", cond = "!mime", run = "mime", prio = "high" }

Changed the behavior of the sort command's --reverse and --dir-first options

If you use a custom configuration and have overridden the , key series, please update them to the latest (See the sort docs for details):

yazi/yazi-config/preset/keymap.toml

Lines 109 to 120 in 46cd42f

	{ on = [ ",", "m" ], run = "sort modified --reverse=no", desc = "Sort by modified time" },
	{ on = [ ",", "M" ], run = "sort modified --reverse", desc = "Sort by modified time (reverse)" },
	{ on = [ ",", "c" ], run = "sort created --reverse=no", desc = "Sort by created time" },
	{ on = [ ",", "C" ], run = "sort created --reverse", desc = "Sort by created time (reverse)" },
	{ on = [ ",", "e" ], run = "sort extension --reverse=no", desc = "Sort by extension" },
	{ on = [ ",", "E" ], run = "sort extension --reverse", desc = "Sort by extension (reverse)" },
	{ on = [ ",", "a" ], run = "sort alphabetical --reverse=no", desc = "Sort alphabetically" },
	{ on = [ ",", "A" ], run = "sort alphabetical --reverse", desc = "Sort alphabetically (reverse)" },
	{ on = [ ",", "n" ], run = "sort natural --reverse=no", desc = "Sort naturally" },
	{ on = [ ",", "N" ], run = "sort natural --reverse", desc = "Sort naturally (reverse)" },
	{ on = [ ",", "s" ], run = "sort size --reverse=no", desc = "Sort by size" },
	{ on = [ ",", "S" ], run = "sort size --reverse", desc = "Sort by size (reverse)" },

The reason for this change

Before Yazi v0.3, the sort command was stateless. It didn’t consider the current sorting state of the directory. For example, if the directory was in reverse order, using sort new-ordering would lose that setting, and you’d have to use sort new-ordering --reverse to keep it.

If the directory had both --reverse and --dir-first enabled, you’d have to use sort new-ordering --reverse --dir-first, which was cumbersome. Yazi v0.3 introduced the sort --translit option, exacerbating this issue.

Therefore, in Yazi v0.3, the behavior was changed: the new sort command respects the previous directory sorting state. If --reverse isn’t passed, it won’t change the state, and --reverse/--dir-first now also supports --reverse=no to explicitly cancel it.

Used Ctrl-c instead of Ctrl-q as the universal close key for all components

Ctrl-c is more in line with conventions, and it's closer to Ctrl, which makes it more convenient to press. See #763 (comment) and #779 (comment) for more details.

This is a change in user behavior, so it's listed as a breaking change here. For users who copy the entire keymap.toml configuration file or use a custom key, they will not be affected.

Used K and J for the seek command

seek -5 has been changed from <A-k> to K, and seek 5 has been changed from <A-j> to J.

This is because scrolling the preview pane is a common operation, but some terminals do not support Alt key combinations or have them disabled by default. On macOS, there's no Alt key, only Option, and some terminals require additional settings to map Option to Alt (like the macos_option_as_alt option in kitty).

arrow -5 and arrow 5 have been also removed, they were previously bound to K and J and initially added to satisfy my own navigation needs before the relative-motions.yazi plugin existed. Since then, I've realized that using a fixed movement of 5 lines is quite subjective and many users don't use it at all.

Used <S-Enter> instead of <C-Enter> as the alternative key for interactive open

Previously, <C-Enter> was used as an alternative key for interactive open, in Yazi v0.3, changing it to <S-Enter> aligns with the behavior of o/O - o for direct file opening, O (Shift-o) for interactive file opening.

This change makes the behavior more intuitive and reduces additional cognitive burden. This is a change in user behavior, so it's listed as a breaking change here.

Redesigned icons

See #1086 for details.

Renamed the shell wrapper to yy, in favor of the new Ya CLI

This is a change in user behavior, so it's listed as a breaking change here. See #914 for details.

For users who do not need the new CLI program, they will not be affected since shell function takes precedence over binary programs.

[sxyazi]

Lua API breaking changes in Yazi v0.3

success and code are now properties instead of methods of Status

local status = Command("ls"):spawn():wait()
- ya.err("success:", status:success(), "code:", status:code())
+ ya.err("success:", status.success, "code:", status.code)

Renamed is_block_device, is_char_device, and is_socket of Cha

• is_block_device => is_block
• is_char_device => is_char
• is_socket => is_sock

Removed fs.cha_follow() in favor of fs.cha()

- local cha = fs.cha_follow(url)
+ local cha = fs.cha(url, true)

The names of builtin plugins are now reserved

Yazi comes with some builtin plugins. Before v0.3, it always checked the user's plugin directory for plugins with the same name first, and if found, it would prioritize using those.

In v0.3, this check will no longer be performed, and the builtin plugins will always be used. This effectively avoids any I/O operations to improve performance since most users always use these builtin plugins.

It also reduces the possibility of troubles - if a user has a plugin with the same name but different functionality, it will prevent the builtin plugin from working as expected.

Redesigned the UI rendering API

See #1257 for details.

[sxyazi]

Packaging

Changed required dependency:

• Ya - Yazi's CLI tool that enables cross-instance communication (used in yazi.nvim), and calls the builtin plugins (for example archive extraction). It should be included during packaging (cargo build --release already built it by default).

Changed optional dependencies:

• ImageMagick - Yazi 0.3 now supports previewing fonts, SVGs, HEIC, and JPEG XL files, ImageMagick can be installed as needed to enable that.

• 7zip - It replaces unar (removed from Yazi 0.3's dependency list), for more efficient archive previewing, see perf!: reimplement and significantly speed up archive previewing #1220

• chafa - Yazi 0.3 switched its ASCII art backend from Überzug++ to chafa, because Überzug++ had some issues in practice, see feat: Chafa integration #1066

[xtexChooser]

Yazi v0.3.0 added a new default-on build feature that controls whether Lua should be vendored. For distributions using patches to let Yazi use not-vendored Lua, now the patch can be replaced with --no-default-features

[saumyajyoti]

Packaging

Changed required dependency:

• Ya - Yazi's CLI tool that enables cross-instance communication (used in yazi.nvim), and calls the builtin plugins (for example archive extraction). It should be included during packaging (cargo build --release already built it by default).

Changed optional dependencies:

• ImageMagick - Yazi 0.3 now supports previewing fonts, SVGs, HEIC, and JPEG XL files, ImageMagick can be installed as needed to enable that.
• 7zip - It replaces unar (removed from Yazi 0.3's dependency list), for more efficient archive previewing, see perf!: reimplement and significantly speed up archive previewing #1220
• chafa - Yazi 0.3 switched its ASCII art backend from Überzug++ to chafa, because Überzug++ had some issues in practice, see feat: Chafa integration #1066

Hi @sxyazi
I don't see any difference in font preview with image magick installed in Yazi Windows. for different font files. All ttf files look same in preview.

[github-actions]

I'm going to lock this issue because it has been closed for 30 days. ⏳
This helps our maintainers find and focus on the active issues. If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.