Filesystem API

Filesystem operations in Yazi plugins

The fs namespace provides filesystem operations that work with both local and remote (VFS) files.

File Access

fs.access()

Create a file access builder for opening files with specific permissions.

return · Access

Access builder object

local access = fs.access()
  :read(true)
  :write(true)
  
local fd, err = access:open(url)
if fd then
  -- Use file descriptor
  ya.drop(fd)
end

Access Methods

• :append(bool) - Open for appending
• :create(bool) - Create file if it doesn’t exist
• :create_new(bool) - Create new file, fail if exists
• :read(bool) - Open for reading
• :write(bool) - Open for writing
• :truncate(bool) - Truncate file on open
• :open(url) - Open the file and return file descriptor

File Operations

fs.copy(from, to)

Copy a file from one location to another.

from · Url · required

Source file URL

to · Url · required

Destination file URL

return · number|nil, Error

Number of bytes copied, or (nil, error)

local len, err = fs.copy(src_url, dest_url)
if not len then
  ya.err("Copy failed: " .. tostring(err))
end

fs.rename(from, to)

Rename/move a file or directory.

from · Url · required

Source URL

to · Url · required

Destination URL

return · bool, Error|nil

Success boolean, or (false, error)

local ok, err = fs.rename(old_url, new_url)
if not ok then
  ya.err("Rename failed: " .. tostring(err))
end

fs.write(url, data)

Write data to a file.

url · Url · required

File URL

data · string · required

Data to write

return · bool, Error|nil

Success boolean, or (false, error)

local ok, err = fs.write(url, "Hello, World!")

Directory Operations

fs.create(type, url)

Create a directory.

type · string · required

Either "dir" or "dir_all" (creates parent directories)

url · Url · required

Directory URL

return · bool, Error|nil

Success boolean, or (false, error)

-- Create single directory
local ok, err = fs.create("dir", url)

-- Create with parents
local ok, err = fs.create("dir_all", url)

fs.remove(type, url)

Remove a file or directory.

type · string · required

One of: "file", "dir", "dir_all" (recursive), "dir_clean" (only if empty)

url · Url · required

File/directory URL

return · bool, Error|nil

Success boolean, or (false, error)

-- Remove file
fs.remove("file", file_url)

-- Remove directory recursively
fs.remove("dir_all", dir_url)

-- Remove only if empty
fs.remove("dir_clean", dir_url)

fs.read_dir(dir, options)

Read directory contents.

dir · Url · required

Directory URL

options · table

Read options

options.glob · string

Glob pattern to filter files

options.limit · number

Maximum number of files to read (default: unlimited)

options.resolve · bool

Resolve symlinks and get full metadata (default: false)

return · File[]|nil, Error

List of files, or (nil, error)

local files, err = fs.read_dir(url, {
  glob = "*.lua",
  limit = 100,
  resolve = true
})

if files then
  for _, file in ipairs(files) do
    ya.dbg(file.url)
  end
end

File Metadata

fs.cha(url, follow?)

Get file characteristics (metadata).

url · Url · required

File URL

follow · bool

Follow symlinks (default: false)

return · Cha|nil, Error

File characteristics, or (nil, error)

local cha, err = fs.cha(url, true)
if cha then
  ya.dbg("Size: " .. cha.len)
  ya.dbg("Is dir: " .. tostring(cha.is_dir))
end

Cha Fields

• len (number) - File size in bytes
• is_dir (bool) - Is directory
• is_hidden (bool) - Is hidden file
• is_link (bool) - Is symbolic link
• is_orphan (bool) - Is orphan symlink
• is_block (bool) - Is block device
• is_char (bool) - Is character device
• is_fifo (bool) - Is FIFO
• is_sock (bool) - Is socket
• is_exec (bool) - Is executable
• is_sticky (bool) - Has sticky bit
• modified (number) - Last modified time (timestamp)
• accessed (number) - Last accessed time (timestamp)
• created (number) - Created time (timestamp)
• permissions (string) - Unix permissions string (e.g., “rwxr-xr-x”)

fs.calc_size(url)

Calculate total size of a directory (async iterator).

url · Url · required

Directory URL

return · SizeCalculator|nil, Error

Size calculator iterator, or (nil, error)

local calc, err = fs.calc_size(url)
if calc then
  repeat
    local progress = calc:next()
    if progress then
      ya.dbg("Size: " .. progress.size)
    end
  until not progress
end

Utilities

fs.unique(type, url)

Create a unique file or directory name (handles naming conflicts).

type · string · required

Either "file" or "dir"

url · Url · required

Desired URL (may be modified to be unique)

return · Url|nil, Error

Unique URL, or (nil, error)

local unique_url, err = fs.unique("file", url)
-- If /path/file.txt exists, may return /path/file (1).txt

This replaces the deprecated fs.unique_name() to fix TOCTOU race conditions. See #3677.

fs.cwd()

Get the current working directory.

return · Url|nil, Error

Current directory URL, or (nil, error)

local cwd, err = fs.cwd()

fs.expand_url(value)

Expand ~ and environment variables in a URL/path string.

value · string|Url · required

URL string or Url object

return · Url

Expanded URL

local url = fs.expand_url("~/documents")
-- Url("/home/user/documents")

fs.partitions()

Get list of mounted partitions.

return · table[]

List of partition info tables

local parts = fs.partitions()
for _, p in ipairs(parts) do
  ya.dbg(string.format("%s -> %s (%s)", p.src, p.dist, p.fstype))
end

Each partition table contains:

• src (string) - Device path
• dist (string) - Mount point
• label (string) - Volume label
• fstype (string) - Filesystem type
• external (bool) - Is external drive
• removable (bool) - Is removable media

File Operations Helper

fs.op(name, options)

Low-level file operation helper (internal use).

name · string · required

Operation name: "part", "done", "size"

options · table · required

Operation-specific options

This is used internally by Yazi for progress tracking of file operations.