Skip to main content
Walks lets a VFS hand over a whole folder tree in one call, instead of one listing per folder. Built-in VFSs lists which VFSs support it.

VFS and Walks Integration

A VFS overrides read_tree when its service can list a whole tree in one call. It returns None (TypeScript: null) when it cannot, and Mirage lists each folder with readdir instead. TypeScript names methods in camelCase (readTree). The example extends NotesVFS from Adding a New VFS, mounted at /notes.

read_tree

Every file and folder below one folder. Commands: find, du, ls -R, tree, grep -r and rg on a folder, and cp -r inside the mount when the VFS overrides copy. find -maxdepth N, tree -L N, rg --max-depth N and cp -r to another mount list each folder without asking, and ls without -R lists one folder. Every walk stops at its command’s walk_limit.
PathSpec
required
The folder, on this mount. For a path that is not a folder, raise what readdir raises.
int | None
default:"None"
The most entries worth returning, one more than the walk can still use, or None when nothing caps the walk. TypeScript passes it as handed.limit. readdir takes the same argument.
Examples:
dict[str, FileStat] | None
This example’s pages sit in one folder, so one readdir is the whole tree. A service with nested folders would return them all from one recursive call. With this example, find /notes, du -a /notes, ls -R /notes and tree /notes call read_tree once, and find /notes -maxdepth 1 lists the folder instead. Past limit entries, readdir returns what it holds as a DirListing with partial=True, and Mirage does not keep it as the whole folder: