Skip to main content
Search lets a VFS answer grep and rg from its service’s search instead of reading every file. Mirage still checks every line itself, so the output is the same as reading every file. Built-in VFSs lists which VFSs support it.

VFS and Search Integration

A VFS overrides the methods its service can answer. A method that returns None (TypeScript: null) cannot answer, and Mirage reads the files instead. TypeScript names methods and arguments in camelCase (files_containing is filesContaining). The examples extend NotesVFS from Adding a New VFS, mounted at /notes.

files_containing

Which files under a folder may contain a text. Commands: grep -r and rg on a folder, with any other flags. grep -v, grep -f FILE, and rg with --passthru, --files-without-match, --json, --stats, -z, -L, --pre or -E read every file without asking.
PathSpec
required
The folder the command searches, on this mount. Return only files inside it.
str
required
The text to look for, always plain text, never a regular expression. A command that looks for several texts calls once per text. One with no plain text of 3 or more characters does not call, and every file is read.
bool
required
Whether text must match as a whole word.
bool
required
Whether case is ignored.rg -i on a text with a k, an s or an accented letter calls once per spelling instead, each with False.
Examples:
list[PathSpec] | None
With this example, grep -rn mirage /notes reads only the pages that contain mirage. mounted_path turns a name below the mount into a path.

lines_containing

Which lines of one file may contain a text. Commands: grep and rg on one file. -v and -f FILE read the file without asking.
PathSpec
required
The file the command searches, on this mount.
str
required
The text to look for, always plain text, as in files_containing.
bool
required
Whether case is ignored.
Examples:
bytes | None
With this example, grep mirage /notes/todo.txt and grep -c mirage /notes/todo.txt read nothing. grep -n mirage /notes/todo.txt reads the page, since it holds a match.

before_full_walk

Whether a command may copy, compare, change or remove every file under a folder. Commands: tar -c, zip -r, cp -r, rm -r, chmod -R, chown -R, chgrp -R, gzip -r, diff -r and mv to another mount, before they touch anything. Past the command’s walk_limit, Mirage refuses without asking.
PathSpec
required
The folder the command will copy, change or remove in full, on this mount.
int | None
default:"None"
How many files are inside path, or None when Mirage could not count them. TypeScript passes it as the second argument.
Examples:
None
With this example, diff -r /notes /backup on a folder of 150 pages prints diff: more than 100 pages; narrow the path and exits 1.

walk_limit

walk_limit caps how many files one grep -r or rg searches under a folder (TypeScript: walkLimit). A search counts each file it searches, whether it reads the file or lines_containing answers it. A file files_containing rules out costs nothing. When files_containing returns None, the search goes through every file until it reaches the limit, then stops. A listing such as find also stops at the limit, and a copy such as cp -r of a folder over it is refused before it copies anything.

Set it

Set it per command in command_limits, on the workspace, a mount or a profile. Here grep on /data reads at most 100 files per folder, and every other command 2000:
A VFS sets its own default with a walk_limit class attribute; see Give a VFS its own default.
str
required
Which commands the entry limits.
int
default:"1000"
How many files a search may search, or entries a listing may list, under a folder. A search counts each file it reads or lines_containing answers, and a listing counts folders too. The default is 5000 on GitHub, and 10000 on disk, RAM, OPFS and SQL.

At the limit

  • A command that stops prints <command>: <folder>: stopped after <N> files (walk_limit); narrow the path. One that does not run prints more than <N> files and leaves that folder untouched. rm -r takes its folders in order, so an earlier one may already be removed.
  • Codex’s fs/walk (exec-server) stops the same way and returns truncated: true.

Example: Let a Slack mount read 5000 files

grep -rw refund /slack/channels/ then asks Slack’s search which days mention refund and reads only those. grep -r refund /slack/channels/, which Slack cannot narrow, reads the first 5000 days and stops there.

Example: Give a VFS its own default

A VFS can set the limit its mounts use when no command_limits entry sets one. This VFS reads at most 500 files per folder:
grep -r mirage /notes on 600 pages that files_containing cannot narrow then prints the matches in the first 500 pages, and: