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.