> ## 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.

# Walks

> Answer find, du, ls -R and tree from one listing.

Walks lets a VFS hand over a whole folder tree in one call, instead of one
listing per folder. [Built-in VFSs](https://docs.mirage.strukto.ai/home/integration/overview.md#walks) 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](https://docs.mirage.strukto.ai/home/setup/vfs/new.md#write-one), 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`](https://docs.mirage.strukto.ai/home/integration/search#walk_limit).

**path** `PathSpec` *required*

The folder, on this mount. For a path that is not a folder, raise what `readdir` raises.

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

| Command | `path` | `limit` |
| - | - | - |
| `find /notes`, with a `walk_limit` of 1000 | `/notes` | `1001` |
| `find /notes`, with a `walk_limit` of `-1` | `/notes` | `None` |

**returns** `dict[str, FileStat] | None`

| Return | What happens |
| - | - |
| Every file and folder below `path`, keyed by its path below it (`guides`, `guides/start.md`), each with the `FileStat` that `stat` gives | The command walks it without listing any folder. A tree past `limit` entries is cut to fit. |
| `None` | Mirage lists each folder with `readdir`, and stops once `limit` is spent. Return `None` past `limit` entries, or for a folder too large to send in one call. |

> [tab] Python
>
> ```python theme={null}
> from mirage import FileStat, PathSpec
>
> from notes import NotesVFS
>
>
> class TreeNotesVFS(NotesVFS):
>     async def read_tree(self, path: PathSpec) -> dict[str, FileStat] | None:
>         return {entry.name: entry for entry in await self.readdir(path)}
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import type { FileStat, PathSpec } from '@struktoai/mirage-node'
> import { NotesVFS } from './notes.ts'
>
> export class TreeNotesVFS extends NotesVFS {
>   override async readTree(path: PathSpec): Promise<Map<string, FileStat> | null> {
>     return new Map((await this.readdir(path)).map((entry) => [entry.name, entry]))
>   }
> }
> ```

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:

> [tab] Python
>
> ```python theme={null}
> async def read_tree(self, path: PathSpec, limit: int | None = None) -> dict[str, FileStat] | None: ...
> async def readdir(self, path: PathSpec, limit: int | None = None) -> list[FileStat] | DirListing: ...
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> readTree(path: PathSpec, handed?: Handed): Promise<Map<string, FileStat> | null>
> readdir(path: PathSpec, handed?: Handed): Promise<readonly FileStat[] | DirListing>
> ```


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