Yazi Terminal File Manager

yazi-sftp is a specialized fork of russh-sftp optimized for use within the Yazi file manager. It provides an idiomatic Rust API and includes several performance and compatibility enhancements over the original library.

Key features include:

• UTF-8 Robustness: Supports file paths containing invalid UTF-8 sequences.
• Extended Metadata: Supports retrieving file nlink, username, and group information.
• Performance Optimizations:
  • Copy-on-write (CoW) for all packets to minimize memory allocations.
  • Precomputed packet lengths to avoid secondary allocations.
  • Zero-clone buffer management in AsyncRead and AsyncWrite implementations.
• Idiomatic API: Uses generic return parameters for cleaner code integration.

Yazi comes with default configuration files included in the installation. To customize behavior, you should create override files in your Yazi configuration directory. The specific files you create will override the defaults:

• General Settings: Create yazi.toml to override yazi-default.toml.
• Keybindings: Create keymap.toml to override keymap-default.toml.
• Themes: Create theme.toml to override theme-light.toml and theme-dark.toml.

Configuration Directory Paths:

• Unix-like systems: ~/.config/yazi/
• Windows: %AppData%\yazi\config\

When creating a theme.toml to override default themes, you can apply a single color scheme to both light and dark modes.

For granular control (different colors for light and dark modes), use the [flavor] section in your theme.toml to specify two different flavors, and then provide overrides within those respective flavor files.

The yazi-sftp library uses generic return parameters to provide a more idiomatic Rust experience. When sending requests via a session, you can specify the expected response type directly.

let attrs: responses::Attrs = session.send(requests::Stat::new(path)).await?

The Überzug++ driver applies scaling and offsets to image preview rectangles based on the YAZI configuration. This is used to adjust the position and size of the image overlay relative to the terminal cell grid.

Key configuration parameters used by the driver:

• YAZI.preview.ueberzug_scale: A multiplier applied to the rectangle coordinates and dimensions.
• YAZI.preview.ueberzug_offset: An (x, y, width, height) tuple used to shift and resize the preview area.

The driver calculates the final position using: new_coord = max(0, old_coord * scale + offset)

In Yazi's Lua environment, colors can be represented as Color objects. You can create or manipulate colors using several formats:

1. Strings: Pass a color name or hex string (e.g., `

The init function is used to set up the global RUNNER instance. It requires a setter function that accepts a Lua state (&mlua::Lua) and returns a mlua::Result<()>. This function also triggers the initialization of the loader module.

This is typically called during the startup sequence of the Yazi process to bridge the Rust runner logic with the Lua environment.

pub fn init(setter: fn(&mlua::Lua) -> mlua::Result<()>) {
	crate::loader::init();
	RUNNER.init(Runner { setter });
}

The shutdown() function is an asynchronous operation that shuts down the Pump component of the DDS system.

yazi_dds::shutdown().await;

Yazi provides a way to compose colors in Lua. A color object can be treated as a function (callable) that returns itself, which is useful for chaining or specific UI logic within Yazi's plugin system. When working with the Lua API, a Color can be initialized from a string or a nil value (which defaults to Reset).

-- Example of how colors are handled in Yazi Lua
local my_color = "red"
local reset_color = nil

-- Colors can be passed to UI functions expecting a Color type
-- Strings like "#ff0000" or "blue" are automatically parsed