Migrating to Yazi v0.4.0

[sxyazi]

Yazi v0.4 release note: https://github.com/sxyazi/yazi/releases/tag/v0.4.0

If you encounter any issues during the upgrade, please create a discussion and upload your logs.

TOC

• Migrating to Yazi v0.4.0 - here
• Lua API breaking changes
• Packaging
• Theme system breaking changes

1. Reserve the term select for future use

See #1773 for details.

1.1 - Renamed select command to toggle

# keymap.toml
[manager]
- { on = "<Space>", run = "select --state=none" },
+ { on = "<Space>", run = "toggle" },

# keymap.toml
[manager]
- { on = "<C-r>", run = "select_all --state=none" },
+ { on = "<C-r>", run = "toggle_all" },

- { on = "<C-a>", run = "select_all --state=true" },
+ { on = "<C-a>", run = "toggle_all --state=on" },

The documentation is now available for the two new commands: toggle command and toggle_all command.

1.2 - Renamed the select component to pick component

# yazi.toml / keymap.toml / theme.toml
- [select]
+ [pick]

2. Correct the misuse of the term ctime and unify others

See #1761 for details.

2.1 - Renamed ctime to btime for the linemode command

# keymap.toml
[manager]
- { on = [ "m", "c" ], run = "linemode ctime"  }
+ { on = [ "m", "b" ], run = "linemode btime" }

2.2 - Renamed created to btime, modified to mtime for the sort_by option

# yazi.toml
[manager]
- sort_by = "created"
+ sort_by = "btime"

- sort_by = "modified"
+ sort_by = "mtime"

2.3 - Renamed created to btime, modified to mtime for the sort command

# keymap.toml
[manager]
- { on = [ ",", "c" ], run = "sort created" }
+ { on = [ ",", "b" ], run = "sort btime" },

- { on = [ ",", "m" ], run = "sort modified" }
+ { on = [ ",", "m" ], run = "sort mtime" }

3. Remove the x- prefix from mimetypes to unify behavior across different versions of file(1)

See #1927 for details.

# yazi.toml
[open]
- { mime = "application/x-{tar,bzip*,7z-compressed,xz,rar}", fg = "red" },
+ { mime = "application/{tar,bzip*,7z-compressed,xz,rar}", fg = "red" },

# theme.toml
[filetype]
- { mime = "application/x-{tar,bzip*,7z-compressed,xz,rar}", fg = "red" },
+ { mime = "application/{tar,bzip*,7z-compressed,xz,rar}", fg = "red" },

4. Deprecate the --sync option for the plugin command

See #1891 for details.

# keymap.toml
[manager]
- plugin --sync my-sync-plugin
+ plugin my-sync-plugin

5. Remove the meaningless --confirm option to simplify the shell command

See #1982 for details.

# keymap.toml
[manager]
- shell "$SHELL" --block --confirm
+ shell "$SHELL" --block

[sxyazi]

Lua API breaking changes

1. Renamed the created, modified, accessed, length, and permissions properties of the Cha

• created => btime
• modified => mtime
• accessed => atime
• length => len
• permissions => perm

Note that the old names are still available, but a deprecation warning will shown — they will be completely removed in the next major version 0.4.2. See #1761 for details.

2. Task information for peek()/seek()/preload() has been moved from self to the job parameter

Before:

function M:peek()
  ya.err("area:", self.area)
  ya.err("file:", self.file)
  ya.err("skip:", self.skip)
end

Now:

function M:peek(job)
  ya.err("area:", job.area)
  ya.err("file:", job.file)
  ya.err("skip:", job.skip)
end

These properties can still be accessed via self, but a deprecation warning will be shown. This compatibility layer will be fully removed in Yazi 0.4.2. See #1966 for details.

3. The first parameter of entry() has been replaced with the new job parameter

Before:

function M:entry(args)
  ya.err("first arg:", args[1])
end

Now:

function M:entry(job)
  ya.err("first arg:", job.args[1])
end

The new job can still be used just like the original args (like job[1] or ipairs(job)), but a deprecation warning will be shown. This compatibility layer will be fully removed in Yazi 0.4.2. See #1966 for details.

4. The first parameter of seek() has been changed from a number units to a table job

Before:

function M:seek(units)
  ya.err("units:", units)
end

Now:

function M:seek(job)
  ya.err("units:", job.units)
end

See #1966 for details.

5. Renaming ui.Paragraph to ui.Text

local area = ui.Rect { x=0, y=0, width=10, height=10 }
local lines = { ui.Line("Hello"), ui.Line("World") }

- ui.Paragraph(area, lines):align(ui.Paragraph.RIGHT)
+ ui.Text(lines):area(area):align(ui.Text.RIGHT)

- ui.Paragraph.parse("Hello world")
+ ui.Text.parse("Hello world")

The old ui.Paragraph is still available, but it will show a deprecation warning. This compatibility layer will be completely removed in version 0.4.2. See #1776 for more details.

6. Removed ui.ListItem

Now, ui.List can directly accept ui.Line objects, without needing to wrap them in ui.ListItem:

local line = ui.Line("Hello world")

- ui.List { ui.ListItem(line) }
+ ui.List { line }

See #1776 for more details.

7. Decoupling ui.List, ui.Bar, ui.Border, and ui.Gauge from coordinates

- ui.List(area, items)
+ ui.List(items):area(area)

- ui.Bar(area, ui.Bar.TOP)
+ ui.Bar(ui.Bar.TOP):area(area)

- ui.Border(area, ui.Border.ALL)
+ ui.Border(ui.Border.ALL):area(area)

- ui.Gauge(area)
+ ui.Gauge():area(area)

See #1782 for more details.

8. Replaced numeric error code with a Error type for better human-readable

See #1939 for details.

[sxyazi]

Packaging

• Yazi 0.4 uses ffmpeg and ffprobe instead of ffmpegthumbnailer as the video preview backend.

  See feat!: video spotter & using ffmpeg instead of ffmpegthumbnailer as previewer backend #1928 for details.

[sxyazi]

Theme system breaking changes

1. Use dark and light instead of use under [flavor] to support auto-switching between light and dark modes

# theme.toml
[flavor]
- use  = "dracula"
+ dark = "dracula"

See #1946 for details.

2. Unify the fg_dark and fg_light into one fg as fg_light is never used and redundant

# theme.toml
[icon]
exts = [
-  { name = "3gp", text = "🎵", fg_dark = "#fd971f", fg_light = "#fd971f" },
+  { name = "3gp", text = "🎵", fg = "#fd971f" },
}

See #1946 for details.

3. Extend the available styles for mode by separating mode from the separator styles

See #1953 for details.

[pirafrank]

The new job can still be used just like the original args (like job[1] or ipairs(job)), but a deprecation warning will be shown. This compatibility layer will be fully removed in Yazi 0.4.2. See #1966 for details.

Hi @sxyazi, this is not exactly true since job.args behaves differently for shell-style plugin options than it used to, breaking plugins (AnirudhG07/custom-shell.yazi#11 (comment))

This breaking change is not listed or clearly stated above.

edit: add mention

[sxyazi]

Hey @pirafrank

The new job can still be used just like the original args (like job[1] or ipairs(job)), but a deprecation warning will be shown. This compatibility layer will be fully removed in Yazi 0.4.2. See #1966 for details.

This refers to the new job (not job.args) can still be used in the same way as the previous args, ensuring that the old plugin code remains compatible, e.g.:

- function M:entry(args)
+ function M:entry(job)
-  print(args[1])
+  print(job[1])  -- its now a new `Job` type, but the old code still works
end

But when using job[1], a warning will be shown prompting the migration to the new job.args to ensure a smooth transition. The new job.args can be found at the linked issue or the documentation

[pirafrank]

I see, yet explicitly mentioning in the list the new way to handle the shell-script like options for plugins would have helped. It's good to reference the original issue, but that can't be the only source of truth since it tends to become messy.

Also, it would be better if web docs include the version where something has been introduced, with a link to the list of breaking changes for that version.

In this case, I guess, the whole matter comes from the following:

This compatibility layer will be fully removed in Yazi 0.4.2

One would expect patch version not to have deprecation changes or the compatibility layer removed.

A note for the future. Since yazi is gaining both a user base and a growing community of people developing plugins, I'd rather have removed that layer in 0.5.0 so that users upgrading to 0.4.2+ would not get a different experience than those upgrading to 0.4.0 or 0.4.1.

[sxyazi]

It's good to reference the original issue, but that can't be the only source of truth since it tends to become messy

In the previous 0.3 migration documentation, this was indeed the approach. However, for 0.4, I stopped doing this because 0.4 is the largest version ever, with the most breaking changes. Listing them all in a single thread would have made the thread very lengthy, so I decided to only include a brief summary in the 0.4 migration documentation and link to the corresponding PRs, where the specific reasons for the changes and alternatives are detailed.

it would be better if web docs include the version where something has been introduced

I've always wanted to introduce versioning for the documentation, so users can freely switch between v0.3 and v0.4 in the top-right, and even between subversions like v0.4.0 and v0.4.1, so they can see the differences between versions at any time. I just haven't had time to do it. If you want to explore this idea further or want to help maintain the documentation, please file an issue to let me know.

removed that layer in 0.5.0

This sounds good. The only reason for removing it in the minor version is that Yazi's major version iteration speed is too slow. It took 3 months from 0.2 to 0.3, and another 3 months from 0.3 to 0.4. This seriously affects the progress of Yazi's development. My to-do list has a lot of features I want to add, but they all require breaking changes, so I have to wait and move them to the next major version, 0.5. I think maybe I could speed up the major version iteration.

---

Note that, this issue is for the migration documentation, and I want to keep it clean. If you have any questions/ideas about specific breaking changes, documentation, or version strategies, please create a separate discussion for them, I'd be happy to discuss them there.

[spenserblack]

One would expect patch version not to have deprecation changes or the compatibility layer removed.

To be fair, while it may be surprising, I don't think it's completely unexpected for v0 to be unstable. While many people follow the the convention 0.MAJOR.MINOR+PATCH

Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

Source: semver.org

So I don't think the maintainer did anything wrong here.

---

One thing that can help with documenting breaking changes is to tag all of your PRs with the labels breaking, minor, and patch (of course, feel free to use different labels depending on what makes sense). Then you can create a .github/release.yml file to categorize PR titles based on their labels. Here's an example .github/release.yml and an example of how a release might look. It's much easier than trying to document changes manually IMO, but the trade-off is you need to make sure your PRs will generate good release notes.