DOCSEARCHbyAlgolia
Submit Docs

Yazi Documentation

website·Indexed 29 days ago

https://yazi-rs.github.io/

Documentation for Yazi, a terminal file manager. Includes guides on installation, configuration via yazi.toml and keymap.toml, theme customization, and extending functionality through Lua plugins. Covers version 26.9.1 and nightly builds, detailing features like image previews, VFS, and the ya utility module.

Tokens
64.4K
Snippets
370
Records
554
Agent score
73%

What's inside Yazi

  1. Overview of Yazi Data Distribution Service (DDS)

    The Data Distribution Service (DDS) allows communication and state synchronization between multiple Yazi instances and provides state persistence. It uses a client-server architecture without requiring a separate server process and integrates with a Lua-based publish-subscribe model.

    Key concepts:

    • Local: The current Yazi process instance.
    • Remote: Any Yazi instance other than the current one.
    • Static Message: Messages with a kind starting with @ are stored persistently and restored when a new instance starts. To remove a persistent message, send nil to that kind.

  2. Overview of Yazi Data Distribution Service (DDS)

    The Data Distribution Service (DDS) allows communication and state synchronization between multiple Yazi instances and provides state persistence. It uses a client-server architecture (without requiring a separate server process) and a publish-subscribe model.

    Key concepts:

    • Local: The current Yazi process instance.
    • Remote: Any Yazi instance other than the current one.
    • Static Messages: Messages with a kind starting with @ are persistently stored and restored when a new instance starts. To remove a persisted message, send nil to that kind.

  3. Understand Yazi's architectural layers

    Yazi uses a layered architectural design where each layer has specific responsibilities. Understanding these layers is essential for navigating the application's logic and configuring key bindings or plugins:

    • app: The top-level application layer. It handles system-level interactions like mouse/key events, system signals, and interface redrawing.
    • mgr: The main manager UI where primary user actions (browsing, selecting, opening, editing files) occur.
    • tasks: The task manager that handles asynchronous shell processes, plugins, preloading, and file operations (copy, move, delete).
    • spot: The file information spotter that displays metadata (e.g., image dimensions, video duration) based on user configuration.
    • pick: The picker component used to select file-opening methods.
    • input: The input component for receiving plain text or password entries.
    • confirm: The confirmation component for prompts like deleting or overwriting files.
    • cmp: The auto-completion component for file names and paths.
    • help: The help menu that displays available key bindings and descriptions for different layers.

  4. Use Drag and Drop in Yazi

    Yazi provides built-in Drag and Drop (DnD) support, allowing users to drag files from Yazi to other applications or drop files from other applications into Yazi. This functionality requires a terminal that supports the Drag and Drop protocol. Currently supported or planned terminals include:

    • kitty (v0.47.1 or newer): Supported
    • iTerm2 (3.7.0 beta10 or newer): Landed on master
    • Ghostty: Accepted for support

  5. Inspect URL specifications using the Spec type

    The Spec type (accessed via url.spec) provides metadata about the URL's protocol and nature:

    • kind: The URL kind (string).
    • scheme: The URL scheme (string).
    • domain: The domain of the URL (string).
    • is_regular: Boolean indicating if it represents a regular file.
    • is_search: Boolean indicating if the URL is a search result.

  6. Understand Yazi's asynchronous architecture and task management

    Yazi implements full asynchronous support to maximize resource utilization. All I/O operations are asynchronous, and CPU-intensive tasks are distributed across multiple threads. The system includes a task scheduler that manages internal task priority assignment, allows for task cancellation, and provides real-time progress updates.

  7. Access folder and file state in the current context

    The tab::Folder and fs::File types provide detailed information about the directory being viewed and the files within it, including cursor position, hover state, and file metadata.
    -- Folder properties
local cwd = folder.cwd           -- Url
local cursor_pos = folder.cursor -- integer
local all_files = folder.files   -- fs::Files
local hovered_file = folder.hovered -- fs::File? (nil if none)

-- File properties (fs::File)
local is_hovered = file.is_hovered
local size = file.size()         -- integer? (bytes)
local mime_type = file.mime()    -- string?
local relative_prefix = file.prefix() -- string? (relative to CWD)
local file_icon = file.icon()    -- Icon?
local file_style = file.style()  -- Style?
local is_yanked = file.is_yanked()

  8. Understand Yazi's architectural layers

    Yazi uses a layered architectural design where each layer has specific responsibilities. This structure governs how the application handles user input, file management, and UI components:

    • app: The top-level application layer. It mediates between the user and the system (e.g., handling mouse/key events, system signals, and interface redrawing).
    • mgr: The main manager UI where primary user actions occur (browsing, selecting, opening, and editing files).
    • tasks: The task manager for asynchronous operations, including shell processes, plugins, preloading, and file operations (copy, move, delete).
    • spot: The file information spotter, which displays metadata based on file type (e.g., image dimensions, video duration, directory size).
    • pick: The picker component for choosing file-opening methods.
    • input: The input component for receiving plain text or password entries.
    • confirm: The confirmation component for prompts like deleting or overwriting files.
    • cmp: The auto-completion component for file names and paths.
    • help: The help menu displaying available key bindings and descriptions for different layers.

  9. Understand Yazi's asynchronous architecture

    Yazi is designed as an entirely asynchronous program using the Tokio runtime. It handles all time-consuming I/O and CPU tasks as non-blocking, event-driven async tasks. Key application-layer optimizations include chunked loading for large directories (e.g., 100,000+ files) and background pre-loading of directory file lists to improve responsiveness compared to traditional CLI tools.

  10. Access folder and cursor state via tab::Folder

    The tab::Folder object provides detailed state about the folder currently being viewed in a tab, including the current working directory (CWD), cursor position, and the list of files.
    local folder = cx.active.folder
local cwd = folder.cwd           -- Url type
local cursor_pos = folder.cursor -- integer
local all_files = folder.files    -- fs::Files
local hovered_file = folder.hovered -- fs::File or nil

  11. Yazi Async Architecture and Runtime

    Yazi is designed as an entirely asynchronous program to handle I/O and CPU-intensive tasks in a non-blocking, event-driven manner. It uses the Tokio runtime to implement application-layer optimizations such as chunked loading for large directories (e.g., 100,000 files) and background pre-loading of directory file lists.

  12. Yazi Core Feature Overview

    Yazi is a terminal file manager that includes the following key capabilities:

    • Scrollable Preview: Preview various file types and scroll through the content during preview.
    • Visual Mode & Bulk Rename: Select multiple files using a visual mode to perform bulk renaming operations.
    • Vim-like Interface: Uses Vim-like input for filename editing and a selection component for choosing how to open files.
    • Navigation & Integration: Supports multi-tab workflows and integrates with fzf and zoxide for rapid directory jumping.
    • Task Management: Supports multi-selection for copy/cut operations, managed by a task system that provides real-time progress reports and the ability to cancel tasks.
    • Incremental Find: Real-time incremental file searching that displays the current position and total match count.
    • Advanced Search: Integrates with fd for name-based searching and rg (ripgrep) for content-based searching, allowing arbitrary operations on the resulting file lists.