A sparse clone checks out only part of a repository — Perforce-style. Pass one or more path prefixes, and only files under them are downloaded and written to disk:
oak clone acme/monorepo --path services/api --path libs/shared
# or: --path services/api,libs/shared
The set of prefixes is the cone.
How it behaves#
- The directory structure still comes down. Oak's trees are content-addressed and verified on the client, so the full listing arrives; files outside the cone are listed but their content is never fetched.
- Commits carry out-of-cone files forward untouched. Narrowing a checkout never deletes what it leaves out, and
oak statusnever reports those files as missing. - Everything else is normal. Commit, push, pull, and merge work exactly as in a full clone — including
oak merge, which a mount can't do.
Change the cone#
oak sparse # show the current cone (--json for machines)
oak sparse set services/web # replace the cone and re-sync the working tree
oak sparse add docs/ # widen it
oak sparse disable # back to a full checkout
After widening, files that were never downloaded are listed; run oak pull to fetch them.
Sparse clone or mount?#
For a very large repo, a lazy mount is usually the better default: it fetches any path on demand, with no cone to manage. Reach for a sparse clone when you want a plain on-disk checkout of a subtree — for builds, for tools that dislike virtual filesystems, for merging from — without the per-machine setup a mount needs.
Sparse clones and path permissions share a mechanism: both withhold file content while keeping the tree intact. The difference is who decides — a sparse clone is a bandwidth choice you make; path permissions are access control set by the repo's admins.
Other ways to clone less#
| Flag | Effect |
|---|---|
oak clone --shallow | Only the latest commit on main, no history. |
oak clone --from ../other-checkout | Reuse content already in another local checkout of the same repo instead of downloading it again. |
oak clone --detached | Check out main's head without creating a personal branch — for read-only tooling. |
Recovery switch#
If a server is ever in a broken state and a normal clone or pull fails on a missing file, OAK_ALLOW_PARTIAL_CLONE=1 skips each missing file (and reports it) instead of failing. It's for recovery only — use --path when you want part of a repo on purpose.