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

> Use recursive cloud listings to browse directories with fewer requests.

Mirage connects recursive listings and batch APIs to `find`, `du`, `ls -R`
and `tree`. Your backend can list a whole folder tree together, saving a
separate request for every directory.

## Example: browse an object store

With an S3 bucket mounted at `/data/`:

```bash theme={null}
find /data/knowledge/ -type f
du /data/knowledge/
```

Mirage lists the keys under the object prefix, then uses their paths and
metadata to find files or total their sizes. Large listings may take several
API pages.

## Connect your own backend

Override `read_tree(path)` in Python or `readTree(path)` in TypeScript.
Return a mapping of relative paths, such as `guides/start.md`, to their
`FileStat` metadata. Include the full tree below the requested directory,
with the same metadata a normal listing would show.

| Method | Commands using your method | Uses normal listings instead |
| - | - | - |
| `read_tree` | `find`, `du`, `ls -R`, `tree` | A depth limit (`find -maxdepth`, `tree -L`), or plain `ls` for one directory. |
| `read_tree` | `grep -r`, `grep -R`, `grep -d recurse`, `rg` | `rg --max-depth` limits the levels to visit. |
| `read_tree` | `cp -r` | The backend cannot return a complete source tree. |

Return `None` in Python or `null` in TypeScript when a complete tree is
unavailable, and Mirage lists directories individually. Commands with depth
limits, such as `find -maxdepth 1`, also list only the levels they need.

Mirage applies options such as `find -name`, `find -type` and `ls -lR` to
the returned metadata. For search, `read_tree` discovers files and
[`files_containing`](/home/integration/search) selects which ones to read.


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