refactor!: deprecate [manager] in favor of [mgr]

[sxyazi]

Yazi's design philosophy is to use the same terminology for the same things to avoid confusion.

This PR deprecates [manager] and introduces the new [mgr] as its direct replacement, ensuring consistency with the others:

• rt.mgr - user preferences API
• th.mgr - theme configuration API
• ya.emit("mgr:...") - Lua API
• ya emit mgr:... - ya subcommand
• mgr:... - cross-layer command invocation

Deprecation

# yazi.toml / keymap.toml / theme.toml / flavor.toml
- [manager]
+ [mgr]

This PR includes an automatic migration for yazi.toml, keymap.toml, and theme.toml

When Yazi starts up, it will check if the user's configuration contains [manager], if it does, backup the existing configuration and update the user's configuration with the new [mgr] to ensure a smoother transition to the new [mgr].

Note that flavor.toml will not be automatically migrated, as it's not a user-owned file. If you are using a flavor from yazi-rs/flavors, run ya pkg upgrade to update to the latest commit for support.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Pull Request Overview

This PR deprecates the [manager] table in favor of a unified [mgr] nomenclature across configuration structures and presets, and adds a runtime migration to automatically update existing user configs.

• Removed serde(rename = "manager") attributes and standardized the mgr field.
• Updated default preset TOML files to use [mgr] instead of [manager].
• Introduced a migrate function and wrapped config deserialization to auto-migrate old [manager] entries.

Reviewed Changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
yazi-config/src/yazi.rs	Removed #[serde(rename = "manager")] on pub mgr
yazi-config/src/theme/theme.rs	Removed #[serde(rename = "manager")] on pub mgr
yazi-config/src/lib.rs	Switched direct file reads to migrate(...), and added migrate fn
yazi-config/src/keymap/keymap.rs	Removed #[serde(rename = "manager")] on pub mgr
yazi-config/preset/yazi-default.toml	Renamed [manager] to [mgr]
yazi-config/preset/theme-light.toml	Renamed [manager] to [mgr]
yazi-config/preset/theme-dark.toml	Renamed [manager] to [mgr]
yazi-config/preset/keymap-default.toml	Renamed [manager] to [mgr]
yazi-config/Cargo.toml	Added toml_edit = "0.22.26" for document editing

Comments suppressed due to low confidence (2)

yazi-config/src/lib.rs:88

• [nitpick] Consider adding unit tests for migrate to cover cases such as existing [mgr], legacy [manager], parse failures, and missing files, ensuring the migration logic behaves as expected.

fn migrate(p: std::path::PathBuf) -> String {

yazi-config/src/lib.rs:92

• The type toml_edit::DocumentMut does not exist; the toml_edit crate provides toml_edit::Document for parsing and in-place editing. Update this to old.parse::<toml_edit::Document>().

let Ok(mut doc) = old.parse::<toml_edit::DocumentMut>() else {

[uncenter]

This makes the configuration file far less readable. Why are we opting for shorter, more ambiguous wording?

[sxyazi]

Shortening "manager" to "mgr" cuts down on a few keystrokes, I hope it boosts the QoL, especially since it's the term used most frequently across all layers.

Ideally, we should balance practicality (keeping it short) with correctness (using the complete word), and I've always tried to do that - naming things when designing a feature takes a lot of effort, but sometimes there's an irreconcilable conflict between the two and when it's hard to find a short, complete word, based on my past patterns, I tend to lean more towards practicality.

[uncenter]

I'd rather [yazi-file-manager-manager-configuration-section] than [mgr]. Extreme brevity should not be the goal while naming configuration options. I, and others - judging by the reactions to my previous comment - feel that the UX is actually worsened, not improved, by this change. A major and breaking change like this might serve well as an RFC to get community feedback first.

[sxyazi]

I don't plan on changing it again anytime soon, but you could raise an RFC and if we can come up with a better term than "mgr" — one that's short enough and really gets the idea across, I can consider it in the future. To be honest, raising an RFC just for a simple renaming feels a bit overkill to me, especially since Yazi is [still in beta]( https://github.com/sxyazi/yazi?tab=readme-ov-file#project-status) and its API and configuration could change at any moment. Well... if you really think it's necessary, let's see how things go.

…

On Thu, May 29, 2025 at 3:54 AM uncenter ***@***.***> wrote: *uncenter* left a comment (sxyazi/yazi#2803) <#2803 (comment)> I'd rather [yazi-file-manager-manager-configuration-section] than [mgr]. Extreme brevity should not be the goal while naming configuration options. I, and others - judging by the reactions to my previous comment - feel that the UX is actually worsened, not improved, by this change. A major and breaking change like this might serve well as an RFC to get community feedback first. — Reply to this email directly, view it on GitHub <#2803 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AEFWFIFK2Q6VTHM7HI5ZJWD3AYH7VAVCNFSM6AAAAAB6CWDQAGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDSMJXGQ2TCOBXGQ> . You are receiving this because you modified the open/close state.Message ID: ***@***.***>

[uncenter]

I'd propose moving the manager section options to the top-level of configuration (no specific section) or calling the section something like "[general]" -- though the latter is no more "optimal" in brevity than the original "[manager]" as they are both 7 character words.

[sxyazi]

moving the manager section options to the top-level of configuration (no specific section)

How should I access them with rt and th? Currently, I use rt.mgr.sort_by to access:

yazi/yazi-config/preset/yazi-default.toml

Line 7 in 5cb6e1f

sort_by = "alphabetical"

Does that mean, after this change, it becomes rt.sort_by? That sounds odd, because it would mean mixing the values from yazi.toml with others that might not even belong to yazi.toml (like rt.args, rt.term) in the same level:

yazi/yazi-plugin/src/config/runtime.rs

Lines 14 to 23 in 5cb6e1f

	impl Runtime {
	pub fn compose(lua: &Lua) -> mlua::Result<Value> {
	Composer::make(lua, 10, |lua, key| {
	match key {
	b"args" => Self::args(lua)?,
	b"term" => Self::term(lua)?,
	b"mgr" => Self::mgr(lua)?,
	b"plugin" => super::Plugin::compose(lua)?,
	b"preview" => Self::preview(lua)?,
	b"tasks" => Self::tasks(lua)?,

calling the section something like "[general]" -- though the latter is no more "optimal" in brevity than the original "[manager]" as they are both 7 character words.

No, [manager] is not for general configuration, it's the configuration for the [manager] layer, which is used to display the 3-column layout. For general configuration, I plan to introduce a new [app] in the future, and pull out some of the existing configs of [manager] into it, such as mouse_events and title_format - it already exists, just hasn't been used yet:

yazi/yazi-shared/src/layer.rs

Lines 7 to 10 in 5cb6e1f

	pub enum Layer {
	#[default]
	App,
	Mgr,

Besides, it isn't any shorter than the original [manager], which would make code like:

yazi/yazi-plugin/preset/components/rail.lua

Lines 13 to 14 in 5cb6e1f

	ui.Bar(ui.Edge.RIGHT):area(self._chunks[1]):symbol(th.mgr.border_symbol):style(th.mgr.border_style),
	ui.Bar(ui.Edge.LEFT):area(self._chunks[3]):symbol(th.mgr.border_symbol):style(th.mgr.border_style),

even longer.

[uncenter]

Besides, it isn't any shorter than the original [manager], which would make code like:

Right lol, my point is that there is no need to make that code shorter. It was fine as it was and would continue to be fine.

[sxyazi]

That would make it inconsistent with all other APIs listed in the OP, and I really want to avoid that as much as possible.

Also, using abbreviations in Yazi is a very common practice/coding style — not just a special case. A quick look at the codebase will find many such abbreviations: app, mgr, cmp, url, cha, rect, pad, pos, cx, rt, th, fs, ui, ya, ps.

As I said in #2803 (comment), when designing Yazi, I aimed to find a balance between correctness and practicality. I don't know if you are using these APIs listed in OP, but I use them A LOT.

Using mgr instead of manager not only reduces the keystrokes but also makes it easier for me to spot errors ("mgr" vs "manager", the former is recognizable to me immediately). Also, it shortens the codeline, making reviews easier - I can read less code and focus more on other more critical parts.