docs: runnable partial-clone worked example

[ivarvong]

Read one file from a git repo without downloading the repo — 32 lines, standalone, pure Elixir.

elixir examples/partial_clone_demo.exs

The script Mix.installs the published package (no checkout needed), clones elixir-ai-tools/just_bash under a blob:none filter — protocol v2 partial clone: refs + commits + trees cross the wire, file contents don't — reads README.md, and lets Repository.memory_report/1 account for every object fetched:

after clone   : %{blob_count: 0, tree_count: 616, cache_bytes: 363300}
read README.md:  15873 bytes — "# JustBash"
after one read: %{blob_count: 1, tree_count: 616, cache_bytes: 369585}
ls /:  21 entries — blob_count still 1

Each line is one claim:

• blob_count: 0 after clone — the filter held; nothing was shipped speculatively.
• FS.size/3 before the read returns {:error, :not_local} instead of fetching. The size probe is a gate: a caller (an agent loop, say) decides whether to pull a blob before paying for it.
• blob_count: 0 → 1 around read_path/3 — reading one file fetched exactly one blob. No readahead, no surprise pack.
• FS.ls afterwards doesn't move the count: trees are local, so navigating the repo is free after a filtered clone.

No printing framework, no control-group second clone — the 0 → 1 transition brackets the read, which is the whole proof. All state lives in the %Repository{} value the caller threads; there is no process, ETS table, or daemon behind it.

A protocol note, and a follow-up. The example uses filter: {:blob, :none} deliberately rather than lazy: true. A bare lazy clone defers everything — but its on-demand fetch is a want <sha> with no filter, and git upload-pack answers a commit want with the commit's entire reachable graph. So the first read_path on a bare-lazy repo hauls in the whole repository. The README quick-start currently pairs lazy: true with torvalds/linux, which would do exactly that on first read; the fix is either correcting that example or making lazy: true imply blob:none when the server advertises filter support. Tracked as a follow-up, decided separately from this PR.

Also here: the README links the example from its partial-clone section, and .formatter.exs now covers examples/ so the script stays format-gated in CI.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VEo6srWr3aFwhtwaXDTCZZ