> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search

> Answer grep and rg from a service's own search.

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](https://docs.mirage.strukto.ai/home/integration/overview.md#search) 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](https://docs.mirage.strukto.ai/home/setup/vfs/new.md#write-one), 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.

**path** `PathSpec` *required*

The folder the command searches, on this mount. Return only files inside it.

**text** `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.

**whole\_word** `bool` *required*

Whether `text` must match as a whole word.

| Value | Commands | Return |
| - | - | - |
| `True` | `grep -rw`, `grep -rx`, `rg -w`, `rg -x` with a plain word | The files that contain `text` as a word. A service that only searches whole words, such as Google Drive, answers only here. |
| `False` | Every other search | The files that contain `text` anywhere, also inside a longer word, or `None` if the service cannot. |

**ignore\_case** `bool` *required*

Whether case is ignored.

| Value | Commands | Return |
| - | - | - |
| `True` | `grep -ri`, `rg -i`, `rg -S` with a lowercase pattern | The files that contain `text` in any case, or `None` if the service matches case exactly. |
| `False` | A search without `-i` | The files that contain `text` as written. A service that ignores case anyway can return its results, since extra files are fine. |

`rg -i` on a text with a `k`, an `s` or an accented letter calls once per spelling instead, each with `False`.

**Examples:**

| Command | `path` | `text` | `whole_word` | `ignore_case` |
| - | - | - | - | - |
| `grep -r invoice /notes` | `/notes` | `invoice` | `False` | `False` |
| `grep -rw invoice /notes` | `/notes` | `invoice` | `True` | `False` |
| `grep -ri invoice /notes` | `/notes` | `invoice` | `False` | `True` |
| `grep -r 'invoice.*2026' /notes` | `/notes` | `invoice` | `False` | `False` |
| `grep -r -e invoice -e receipt /notes` | `/notes` | `invoice`, then `receipt` in a second call | `False` | `False` |

**returns** `list[PathSpec] | None`

| Return | What happens |
| - | - |
| A list of files | Only these files are read. Extra files are fine, since Mirage checks every line. A file left out is a missed match. |
| `[]` | No file under `path` holds the text. Nothing is read, and `grep` prints nothing. |
| `None` | The service cannot answer. Every file under `path` is read. |

> [tab] Python
>
> ```python theme={null}
> from mirage import PathSpec
> from mirage.utils.key_prefix import mounted_path
>
> from notes import NotesVFS
>
>
> class SearchableNotesVFS(NotesVFS):
>     async def files_containing(
>         self, path: PathSpec, text: str, *, whole_word: bool, ignore_case: bool
>     ) -> list[PathSpec] | None:
>         if ignore_case:
>             return None
>         return [
>             mounted_path(path, "/" + name)
>             for name, page in self.pages.items()
>             if text in page
>         ]
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import type { PathSpec } from '@struktoai/mirage-node'
> import { mountedPath } from '@struktoai/mirage-core/utils/key_prefix'
> import { NotesVFS } from './notes.ts'
>
> export class SearchableNotesVFS extends NotesVFS {
>   override async filesContaining(
>     path: PathSpec,
>     text: string,
>     opts: { wholeWord: boolean; ignoreCase: boolean },
>   ): Promise<PathSpec[] | null> {
>     if (opts.ignoreCase) return null
>     return Object.entries(this.pages)
>       .filter(([, page]) => page.includes(text))
>       .map(([name]) => mountedPath(path, `/${name}`))
>   }
> }
> ```

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.

**path** `PathSpec` *required*

The file the command searches, on this mount.

**text** `str` *required*

The text to look for, always plain text, as in [`files_containing`](#files_containing).

**ignore\_case** `bool` *required*

Whether case is ignored.

| Value | Commands | Return |
| - | - | - |
| `True` | `grep -i`, `rg -i`, `rg -S` with a lowercase pattern | The lines that contain `text` in any case, or `None` if the service matches case exactly. |
| `False` | A search without `-i` | The lines that contain `text` as written. |

**Examples:**

| Command | `path` | `text` | `ignore_case` |
| - | - | - | - |
| `grep invoice /notes/todo.txt` | `/notes/todo.txt` | `invoice` | `False` |
| `grep -i invoice /notes/todo.txt` | `/notes/todo.txt` | `invoice` | `True` |

**returns** `bytes | None`

| Return | What happens |
| - | - |
| The lines, in file order, as bytes or a stream of byte chunks | Mirage matches only these lines. Plain `grep`, and `-c`, `-l`, `-q`, `-o`, `-m N`, `-w`, `-x`, `-F` or `grep -L`, never read the file. `-n`, `-b`, `-A`, `-B`, `-C`, several patterns, `grep -z`, `rg --column`, `rg --vimgrep` or `rg -U` read it only when these lines hold a match. |
| `b""` | No line matches. Nothing is read. |
| `None` | The file is read. Return `None` for a file that may hold a NUL byte. |

> [tab] Python
>
> ```python theme={null}
> import io
>
> from mirage import PathSpec
>
> from notes import NotesVFS
>
>
> class LineSearchNotesVFS(NotesVFS):
>     async def lines_containing(
>         self, path: PathSpec, text: str, *, ignore_case: bool
>     ) -> bytes | None:
>         page = self.page(path)
>         if ignore_case or "\0" in page:
>             return None
>         lines = io.StringIO(page, newline="\n").readlines()
>         return "".join(line for line in lines if text in line).encode()
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import type { PathSpec } from '@struktoai/mirage-node'
> import { NotesVFS } from './notes.ts'
>
> export class LineSearchNotesVFS extends NotesVFS {
>   override async linesContaining(
>     path: PathSpec,
>     text: string,
>     opts: { ignoreCase: boolean },
>   ): Promise<Uint8Array | null> {
>     const page = this.page(path)
>     if (opts.ignoreCase || page.includes('\0')) return null
>     const lines = page.split(/(?<=\n)/).filter((line) => line.includes(text))
>     return new TextEncoder().encode(lines.join(''))
>   }
> }
> ```

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`](#walk_limit), Mirage refuses
without asking.

**path** `PathSpec` *required*

The folder the command will copy, change or remove in full, on this mount.

**files** `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:**

| Command | `path` | `files` |
| - | - | - |
| `rm -r /notes/old`, with 2 files inside | `/notes/old` | `2` |

**returns** `None`

| Return | What happens |
| - | - |
| Nothing | The command runs. |
| Raise `ValueError` (TypeScript: throw) | The command does not run. It prints `<command>: <message>` and exits 1. |

> [tab] Python
>
> ```python theme={null}
> from mirage import PathSpec
>
> from notes import NotesVFS
>
>
> class GuardedNotesVFS(NotesVFS):
>     async def before_full_walk(self, path: PathSpec, *, files: int | None = None) -> None:
>         if files is not None and files > 100:
>             raise ValueError("more than 100 pages; narrow the path")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import type { PathSpec } from '@struktoai/mirage-node'
> import { NotesVFS } from './notes.ts'
>
> export class GuardedNotesVFS extends NotesVFS {
>   override async beforeFullWalk(_path: PathSpec, files: number | null): Promise<void> {
>     if (files !== null && files > 100) throw new Error('more than 100 pages; narrow the path')
>   }
> }
> ```

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`](#lines_containing) answers it. A file
[`files_containing`](#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:

> [tab] Python
>
> ```python theme={null}
> from mirage import Limit, MountMode, Workspace
> from mirage.vfs.ram import RAMVFS
>
> ws = Workspace(
>     {"/data": (RAMVFS(), MountMode.WRITE, {"grep": Limit(walk_limit=100)})},
>     mode=MountMode.WRITE,
>     command_limits={"@all": Limit(walk_limit=2000)},
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Limit, MountMode, RAMVFS, Workspace } from '@struktoai/mirage-node'
>
> const ws = new Workspace(
>   { '/data': [new RAMVFS(), MountMode.WRITE, { grep: new Limit({ walkLimit: 100 }) }] },
>   { mode: MountMode.WRITE, commandLimits: { '@all': new Limit({ walkLimit: 2000 }) } },
> )
> ```

> [tab] YAML
>
> ```yaml theme={null}
> command_limits:
>   "@all": {walk_limit: 2000}
> mounts:
>   /data:
>     vfs: ram
>     mode: write
>     command_limits:
>       grep: {walk_limit: 100}
> ```

A VFS sets its own default with a `walk_limit` class attribute; see
[Give a VFS its own default](#example-give-a-vfs-its-own-default).

**key** `str` *required*

Which commands the entry limits.

| Key | Limits |
| - | - |
| `"@all"` | Every command |
| A command name, such as `grep` or `find` | That command only, with any flags. `grep` also covers `git grep`. |
| A name with flags, such as `"grep -r"` | Nothing, since a key has no flags |

**walk\_limit** `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.

| Value | What happens |
| - | - |
| `-1` | No limit. On `"@all"`, a service search that can miss a match is also turned off, so every file is read. |
| `0` | Nothing under a folder is read or listed. |
| A number, such as `100` | Searches stop after that many files, and listings after that many entries. Globs, copies and removals over that many files do not run. |

### At the limit

| Kind | Commands | At the limit |
| - | - | - |
| Searches | `grep -r`, `rg`, `git grep` | Stop, keep what they printed, and exit 2 (`git grep`: 128). |
| Listings | `find`, `ls -R`, `du`, `tree`, `getfattr -R` | Stop, keep what they printed, and exit 1 (`tree`: 2). |
| Globs | Any glob, such as `cat *.log` | Do not run, and exit 126. |
| Copies and removals | `tar -c`, `zip -r`, `cp -r`, `rm -r`, `chmod -R`, `chown -R`, `chgrp -R`, `diff -r`, `gzip -r`, `mv` to another mount | Do not run, and exit 1. |
| Git work tree | `git status`, `git add`, `git commit -a`, `git diff`, `git checkout`, `git reset`, `git rm` | Do not run, and exit 128. |

* 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](https://docs.mirage.strukto.ai/home/agents/codex.md#exec-server-forward))
  stops the same way and returns `truncated: true`.

### Example: Let a Slack mount read 5000 files

> [tab] Python
>
> ```python theme={null}
> import os
>
> from mirage import Limit, MountMode, Workspace
> from mirage.vfs.slack import SlackConfig, SlackVFS
>
> slack = SlackVFS(
>     config=SlackConfig(
>         token=os.environ["SLACK_BOT_TOKEN"],
>         search_token=os.environ["SLACK_USER_TOKEN"],
>     )
> )
> ws = Workspace(
>     {"/slack": (slack, MountMode.READ, {"@all": Limit(walk_limit=5000)})},
>     mode=MountMode.READ,
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Limit, MountMode, SlackVFS, Workspace } from '@struktoai/mirage-node'
>
> const slack = new SlackVFS({
>   token: process.env.SLACK_BOT_TOKEN!,
>   searchToken: process.env.SLACK_USER_TOKEN,
> })
> const ws = new Workspace(
>   { '/slack': [slack, MountMode.READ, { '@all': new Limit({ walkLimit: 5000 }) }] },
>   { mode: MountMode.READ },
> )
> ```

> [tab] YAML
>
> ```yaml theme={null}
> mounts:
>   /slack:
>     vfs: slack
>     mode: read
>     config:
>       token: ${SLACK_BOT_TOKEN}
>       search_token: ${SLACK_USER_TOKEN}
>     command_limits:
>       "@all":
>         walk_limit: 5000
> ```

`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:

> [tab] Python
>
> ```python theme={null}
> class SearchableNotesVFS(NotesVFS):
>     walk_limit = 500
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> export class SearchableNotesVFS extends NotesVFS {
>   override walkLimit = 500
> }
> ```

`grep -r mirage /notes` on 600 pages that `files_containing` cannot narrow
then prints the matches in the first 500 pages, and:

```text theme={null}
grep: /notes: stopped after 500 files (walk_limit); narrow the path
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.