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 returnsNone (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.
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.
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.- Python
- TypeScript
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.
The text to look for, always plain text, as in
files_containing.- Python
- TypeScript
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.
How many files are inside
path, or None when Mirage could not count them. TypeScript passes it as the second argument.- Python
- TypeScript
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 incommand_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:
- Python
- TypeScript
- YAML
walk_limit class attribute; see
Give a VFS its own default.
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 printsmore than <N> filesand leaves that folder untouched.rm -rtakes its folders in order, so an earlier one may already be removed. - Codex’s
fs/walk(exec-server) stops the same way and returnstruncated: true.
Example: Let a Slack mount read 5000 files
- Python
- TypeScript
- YAML
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 nocommand_limits entry sets
one. This VFS reads at most 500 files per folder:
- Python
- TypeScript
grep -r mirage /notes on 600 pages that files_containing cannot narrow
then prints the matches in the first 500 pages, and: