Filesystem API

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

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

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

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.

API Reference

Filesystem API

File Access

`fs.access()`

Access Methods

File Operations

`fs.copy(from, to)`

`fs.rename(from, to)`

`fs.write(url, data)`

Directory Operations

`fs.create(type, url)`

`fs.remove(type, url)`

`fs.read_dir(dir, options)`

File Metadata

`fs.cha(url, follow?)`

Cha Fields

`fs.calc_size(url)`

Utilities

`fs.unique(type, url)`

`fs.cwd()`

`fs.expand_url(value)`

`fs.partitions()`

File Operations Helper

`fs.op(name, options)`

Build docs developers (and LLMs) love

API Reference

Documentation Index

​File Access

​fs.access()

​Access Methods

​File Operations

​fs.copy(from, to)

​fs.rename(from, to)

​fs.write(url, data)

​Directory Operations

​fs.create(type, url)

​fs.remove(type, url)

​fs.read_dir(dir, options)

​File Metadata

​fs.cha(url, follow?)

​Cha Fields

​fs.calc_size(url)

​Utilities

​fs.unique(type, url)

​fs.cwd()

​fs.expand_url(value)

​fs.partitions()

​File Operations Helper

​fs.op(name, options)

Build docs developers (and LLMs) love

File Access

`fs.access()`

Access Methods

File Operations

`fs.copy(from, to)`

`fs.rename(from, to)`

`fs.write(url, data)`

Directory Operations

`fs.create(type, url)`

`fs.remove(type, url)`

`fs.read_dir(dir, options)`

File Metadata

`fs.cha(url, follow?)`

Cha Fields

`fs.calc_size(url)`

Utilities

`fs.unique(type, url)`

`fs.cwd()`

`fs.expand_url(value)`

`fs.partitions()`

File Operations Helper

`fs.op(name, options)`